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.

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.

max_pending_exceptions

Type:

int

Env var:

LEGATE_MAX_PENDING_EXCEPTIONS

Default:

64 (test-mode default: 1)

How many possibly-exception-throwing tasks to emit before blocking. Legate by default does not wait for operations to complete, but instead “runs ahead” and continues launching work, which will complete asynchronously. If an operation throws an exception, then by the time an exception is reported execution may have progressed beyond the launch of the faulting operation. If you need to check for an exception at the exact point where it might get thrown (e.g. to catch it and recover gracefully), set this to 1. Note that this will introduce more blocking in the control logic of your program, likely reducing overall utilization.

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

precise_exception_trace

Type:

bool (“0” or “1”)

Env var:

LEGATE_PRECISE_EXCEPTION_TRACE

Default:

False (test-mode default: False)

Whether to capture the stacktrace at the point when a potentially faulting operation is launched, so a more accurate error location can be reported in case an exception is thrown.

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.

max_lru_length

Type:

int

Env var:

LEGATE_MAX_LRU_LENGTH

Default:

5 (test-mode default: 1)

Once the last Store of a given shape is garbage collected, the resources associated with it are placed on an LRU queue, rather than getting freed immediately, in case the program creates a Store of the same shape in the near future. This setting controls the length of that LRU queue.

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.