Settings

Legate has a number of runtime settings that can be configured through environment variables.

consensus

Type:

bool (“0” or “1”)

Env var:

LEGATE_CONSENSUS

Default:

False (test-mode default: False)

Whether to perform the RegionField consensus match operation on single-node runs (for testing). This is normally only necessary on multi-node runs, where all processes must collectively agree that a RegionField has been garbage collected at the Python level before it can be reused.

This is a read-only environment variable setting used by the runtime.

limit_stdout

Type:

bool (“0” or “1”)

Env var:

LEGATE_LIMIT_STDOUT

Default:

False (test-mode default: False)

Whether to limit stdout output to only the first rank.

This is a read-only environment variable setting used by the runtime.

cycle_check

Type:

bool (“0” or “1”)

Env var:

LEGATE_CYCLE_CHECK

Default:

False

Whether to check for reference cycles involving RegionField objects on exit (developer option). When such cycles arise during execution they inhibit used RegionFields from being collected and reused for new Stores, thus increasing memory pressure. By default this check will miss any RegionField cycles that the garbage collector collected during execution. Run gc.disable() at the beginning of the program to avoid this.

future_leak_check

Type:

bool (“0” or “1”)

Env var:

LEGATE_FUTURE_LEAK_CHECK

Default:

False

Whether to check for reference cycles keeping Future/FutureMap objects alive after Legate runtime exit (developer option). Such leaks can result in Legion runtime shutdown hangs.

test

Type:

bool (“0” or “1”)

Env var:

LEGATE_TEST

Default:

False

Enable test mode. This sets alternative defaults for various other settings.

This is a read-only environment variable setting used by the runtime.

min_gpu_chunk

Type:

int

Env var:

LEGATE_MIN_GPU_CHUNK

Default:

1048576 (test-mode default: 2)

If using GPUs, any task operating on arrays smaller than this will not be parallelized across more than one GPU.

This is a read-only environment variable setting used by the runtime.

min_cpu_chunk

Type:

int

Env var:

LEGATE_MIN_CPU_CHUNK

Default:

16384 (test-mode default: 2)

If using CPUs, any task operating on arrays smaller than this will not be parallelized across more than one core.

This is a read-only environment variable setting used by the runtime.

min_omp_chunk

Type:

int

Env var:

LEGATE_MIN_OMP_CHUNK

Default:

131072 (test-mode default: 2)

If using OpenMP, any task operating on arrays smaller than this will not be parallelized across more than one OpenMP group.

This is a read-only environment variable setting used by the runtime.

window_size

Type:

int

Env var:

LEGATE_WINDOW_SIZE

Default:

1 (test-mode default: 1)

How many Legate operations to accumulate before emitting to Legion.

This is a read-only environment variable setting used by the runtime.

field_reuse_frac

Type:

int

Env var:

LEGATE_FIELD_REUSE_FRAC

Default:

256 (test-mode default: 1)

Any allocation for more than 1/frac of available memory will count as multiple allocations, for purposes of triggering a consensus match. Only relevant for multi-node runs.

This is a read-only environment variable setting used by the runtime.

field_reuse_freq

Type:

int

Env var:

LEGATE_FIELD_REUSE_FREQ

Default:

32 (test-mode default: 8)

Every how many RegionField allocations to perform a consensus match operation. Only relevant for multi-node runs, where all processes must collectively agree that a RegionField has been garbage collected at the Python level before it can be reused.

This is a read-only environment variable setting used by the runtime.

disable_mpi

Type:

bool (“0” or “1”)

Env var:

LEGATE_DISABLE_MPI

Default:

False (test-mode default: False)

Disable the MPI-based communicator (used for collective operations in certain CPU tasks). Use this to work around MPI initialization failures.

This is a read-only environment variable setting used by the runtime.

max_exception_size

Type:

int

Env var:

LEGATE_MAX_EXCEPTION_SIZE

Default:

4096 (test-mode default: 4096)

Maximum size in bytes for exceptions that can be raised by tasks.

This is a read-only environment variable setting used by the runtime.