cf.configuration

cf.configuration(atol=None, rtol=None, tempdir=None, of_fraction=None, chunksize=None, collapse_parallel_mode=None, free_memory_factor=None, log_level=None, regrid_logging=None, relaxed_identities=None, bounds_combination_mode=None)

View or set any number of constants in the project-wide configuration.

The full list of global constants that can be set in any combination are:

• atol

• rtol

• tempdir

• of_fraction

• chunksize

• collapse_parallel_mode

• free_memory_factor

• log_level

• regrid_logging

• relaxed_identities

• bounds_combination_mode

These are all constants that apply throughout cf, except for in specific functions only if overridden by the corresponding keyword argument to that function.

The value of None, either taken by default or supplied as a value, will result in the constant in question not being changed from the current value. That is, it will have no effect.

Note that setting a constant using this function is equivalent to setting it by means of a specific function of the same name, e.g. via cf.atol, but in this case multiple constants can be set at once.

New in version 3.6.0.

See also

atol, rtol, tempdir, of_fraction, chunksize, collapse_parallel_mode, total_memory, free_memory_factor, fm_threshold, min_total_memory, log_level, regrid_logging, relaxed_identities, bounds_combination_mode

Parameters

atol: float or Constant, optional

The new value of absolute tolerance. The default is to not change the current value.

rtol: float or Constant, optional

The new value of relative tolerance. The default is to not change the current value.

tempdir: str or Constant, optional

The new directory for temporary files. Tilde expansion (an initial component of ~ or ~user is replaced by that user’s home directory) and environment variable expansion (substrings of the form $name or ${name} are replaced by the value of environment variable name) are applied to the new directory name.

The default is to not change the directory.

of_fraction: float or Constant, optional

The new fraction (between 0.0 and 1.0). The default is to not change the current behaviour.

chunksize: float or Constant, optional

The new chunksize in bytes. The default is to not change the current behaviour.

collapse_parallel_mode: int or Constant, optional

The new value (0, 1 or 2).

bounds_combination_mode: str or Constant, optional

Determine how to deal with cell bounds in binary operations. See cf.bounds_combination_mode for details.

free_memory_factor: float or Constant, optional

The new value of the fraction of memory kept free as a temporary workspace. The default is to not change the current behaviour.

log_level: str or int or Constant, optional

The new value of the minimal log severity level. This can be specified either as a string equal (ignoring case) to the named set of log levels or identifier 'DISABLE', or an integer code corresponding to each of these, namely:

• 'DISABLE' (0);

• 'WARNING' (1);

• 'INFO' (2);

• 'DETAIL' (3);

• 'DEBUG' (-1).

regrid_logging: bool or Constant, optional

The new value (either True to enable logging or False to disable it). The default is to not change the current behaviour.

relaxed_identities: bool or Constant, optional

The new value; if True, use “relaxed” mode when getting a construct identity. The default is to not change the current value.

Returns

Configuration

The dictionary-like object containing the names and values of the project-wide constants prior to the change, or the current names and values if no new values are specified.

Examples:

>>> cf.configuration()  # view full global configuration of constants
{'rtol': 2.220446049250313e-16,
 'atol': 2.220446049250313e-16,
 'tempdir': '/tmp',
 'of_fraction': 0.5,
 'free_memory_factor': 0.1,
 'regrid_logging': False,
 'collapse_parallel_mode': 0,
 'relaxed_identities': False,
 'log_level': 'WARNING',
 'bounds_combination_mode': 'AND',
 'chunksize': 82873466.88000001}
>>> cf.chunksize(7.5e7)  # any change to one constant...
82873466.88000001
>>> cf.configuration()['chunksize']  # ...is reflected in the configuration
75000000.0

>>> cf.configuration(
...     of_fraction=0.7, tempdir='/usr/tmp', log_level='INFO')  # set items
{'rtol': 2.220446049250313e-16,
 'atol': 2.220446049250313e-16,
 'tempdir': '/tmp',
 'of_fraction': 0.5,
 'free_memory_factor': 0.1,
 'regrid_logging': False,
 'collapse_parallel_mode': 0,
 'relaxed_identities': False,
 'log_level': 'WARNING',
 'bounds_combination_mode': 'AND',
 'chunksize': 75000000.0}
>>> cf.configuration()  # the items set have been updated accordingly
{'rtol': 2.220446049250313e-16,
 'atol': 2.220446049250313e-16,
 'tempdir': '/usr/tmp',
 'of_fraction': 0.7,
 'free_memory_factor': 0.1,
 'regrid_logging': False,
 'collapse_parallel_mode': 0,
 'relaxed_identities': False,
 'log_level': 'INFO',
 'bounds_combination_mode': 'AND',
 'chunksize': 75000000.0}

Use as a context manager:

>>> print(cf.configuration())
{'rtol': 2.220446049250313e-16,
 'atol': 2.220446049250313e-16,
 'tempdir': '/usr/tmp',
 'of_fraction': 0.7,
 'free_memory_factor': 0.1,
 'regrid_logging': False,
 'collapse_parallel_mode': 0,
 'relaxed_identities': False,
 'log_level': 'INFO',
 'bounds_combination_mode': 'AND',
 'chunksize': 75000000.0}
>>> with cf.configuration(atol=9, rtol=10):
...     print(cf.configuration())
...
{'rtol': 9.0,
 'atol': 10.0,
 'tempdir': '/usr/tmp',
 'of_fraction': 0.7,
 'free_memory_factor': 0.1,
 'regrid_logging': False,
 'collapse_parallel_mode': 0,
 'relaxed_identities': False,
 'log_level': 'INFO',
 'bounds_combination_mode': 'AND',
 'chunksize': 75000000.0}
>>> print(cf.configuration())
{'rtol': 2.220446049250313e-16,
 'atol': 2.220446049250313e-16,
 'tempdir': '/usr/tmp',
 'of_fraction': 0.7,
 'free_memory_factor': 0.1,
 'regrid_logging': False,
 'collapse_parallel_mode': 0,
 'relaxed_identities': False,
 'log_level': 'INFO',
 'bounds_combination_mode': 'AND',
 'chunksize': 75000000.0}