3.4 Configuration parameters

Configuration parameters affect how the package behaves. Parameters can generally be set using a dictionary-like interface in either the global configuration config or in backend-specific settings at config. To provide flexibility, the default backends (whose name is identical to the backend package, e.g. numba, jax, or torch) have a special behavior such that their configuration is linked with the global configuration. Consequently, the following commands all yield identical results:

from pde import config, get_backend

get_backend("numba").config["debug"] = True
config["backend"]["numba"]["debug"] = True
config["backend.numba.debug"] = True

In contrast, custom backends (example: get_backend("torch:cuda")) inherit the global configuration, but modifying their configuration would not influence the global configuration.

Here is a list of all global configuration options, which includes the backend-specific parameters

backend.jax.compile

Enables compilation in the `jax` backend. (Default value: True)

backend.jax.device

Determines the device that is used for the jax backend. Common options include `cpu` and `gpu`. The special value `auto` chooses `gpu` if available, otherwise `cpu`. (Default value: ‘cpu’)

backend.jax.dtype_downcasting

Determines whether dtype downcasting is used automatically. A typical example are jax devices that only support float32, so the numpy arrays using float64 need to be converted. If enabled, this happens automatically. (Default value: True)

backend.numba.debug

Determines whether numba uses the debug mode for compilation. If enabled, this emits extra information that might be useful for debugging. (Default value: False)

backend.numba.fastmath

Determines whether the fastmath flag is set during compilation. If enabled, some mathematical operations might be faster, but less precise. This flag does not affect infinity detection and NaN handling. (Default value: True)

backend.numba.multithreading

Determines whether multiple threads are used in numba-compiled code. Enabling this option accelerates a small subset of operators applied to fields defined on large grids. Possible options are ‘never’ (disable multithreading), ‘only_local’ (disable on HPC hardware), and ‘always’ (enable if number of grid points exceeds `multithreading_threshold`) (Default value: ‘only_local’)

backend.numba.multithreading_threshold

Minimal number of support points of grids before multithreading is enabled in numba compilations. Has no effect when multihreading is disabled via the `multithreading` option. (Default value: 65536)

backend.numba.use_spectral

Indicates whether a spectral implementation should be used where possible. Note that this option is only implemented for few operators. (Default value: False)

backend.torch.compile

Enables compilation in the `torch` backend. (Default value: True)

backend.torch.device

Determines the device that is used for the torch backend. Common options include `cpu`, `cuda`, and more specific choices, like `cuda:0`. The special value `auto` chooses `cuda` if available, otherwise `cpu`. (Default value: ‘cpu’)

backend.torch.dtype_downcasting

Determines whether dtype downcasting is used automatically. A typical example are torch devices that only support float32, so the numpy arrays using float64 need to be converted. If enabled, this happens automatically. (Default value: True)

boundaries.accept_lists

Indicate whether boundary conditions can be set using the deprecated legacy format, where conditions for individual axes and sides where set using lists. If disabled, only the new format using dicts is supported. (Default value: True)

default_backend

Indicate which backend is selected by default. (Default value: ‘numba’)

operators.cartesian.laplacian_2d_corner_weight

Weighting factor for the corner points of the 2d cartesian Laplacian stencil. The standard value is zero, corresponding to the traditional 5-point stencil. Alternative choices are 1/2 (Oono-Puri stencil) and 1/3 (Patra-Karttunen or Mehrstellen stencil); see https://en.wikipedia.org/wiki/Nine-point_stencil. Note that some backends might ignore this option. (Default value: 0.0)

operators.conservative_stencil

Indicates whether conservative stencils should be used for differential operators on curvilinear grids. Conservative operators ensure mass conservation at slightly slower computation speed. Note that some backends might ignore this option. (Default value: True)

operators.tensor_symmetry_check

Indicates whether tensor fields are checked for having a suitable form for evaluating differential operators in curvilinear coordinates where some axes are assumed to be symmetric. In such cases, some tensor components might need to vanish, so the result of the operator can be expressed. Note that some backends might ignore this option. (Default value: True)

Tip

To disable parallel computing via multithreading in the package, the following code could be added to the start of the script:

from pde import config
config["backend.numba.multithreading"] = "never"

# actual code using py-pde

The default value only_local already disables multithreading when the package detects it is run in an HPC environment.