API reference

This is the complete reference of the Python API for the parafields package.

parafields.generate_field(cells=(512, 512), extensions=(1.0, 1.0), covariance='exponential', variance=1.0, anisotropy='none', corrLength=0.05, periodic=False, autotune_embedding_factor=False, embedding_factor=2, embedding_type='classical', sigmoid_function='smoothstep', threshold=1e-14, approximate=False, fftw_transpose=None, cacheInvMatvec=True, cacheInvRootMatvec=False, cg_iterations=100, cauchy_alpha=1.0, cauchy_beta=1.0, exp_gamma=1.0, transform=None, dtype=<class 'numpy.float64'>, seed=None, partitioning=None, comm=None, rng='twister', distribution_algorithm='boxMuller')

Main entry point for generating parafields parameter fields

Parameters

  • cells (list) – The number of cells in each direction in the grid that defines the random field resolution.

  • extensions – The extent of the physical domain that the random field is defined on. This is only required if the random field is to be probed with global coordinates.

  • covariance (str or Callable) –

    The covariance structure that is used. parafields provides the following choices:

    • exponential (default choice)

    • gammaExponential (requires parameter gammaExp)

    • separableExponential

    • matern (requires parameter maternNu)

    • matern32

    • matern52

    • gaussian

    • spherical

    • cauchy

    • generalizedCauchy

    • cubic

    • dampedOscillation

    • whiteNoise

    Alternatively, you can pass a callable (e.g. a function or a class instance that defines __call__) to the covariance function. This allows you to use covariance functions defined in Python, but results in a significant performance penalty. This is currently limited to symmetric covariance functions.

  • variance (float) – The variance of the random field.

  • anisotropy (str) –

    The type of anisotropy for the field. Can be one of the following:

    • none for an isotropic field

    • axiparallel

    • geometric

  • corrLength (float) – The correlation length of the field. This can either be a scalar for an isotropic field or a list of length dimension for an anisotropic one or a row-wise dim x dim matrix for a geometric one.

  • periodic (bool) – Whether the field should be periodic. Setting periodic boundary conditions sets embedding.factor = 1, i.e. behavior can’t be controlled per boundary segment and correlation length must be small enough.

  • autotune_embedding_factor (bool) – Whether the embedding_factor should experimentally be determined. If set to True, a field with the given embedding_factor is generated. If the procedure fails it is multiplied by 2 and field generation is repeated. Once a sufficiently large embedding factor is found, the interval between the last failing and the first successful one is bisected to identify the minimum embedding factor. This costly procedure amortizes once you generate a huge amount of realizations of the field.

  • embedding_factor (int) – Relative size of extended domain (per dimension).

  • embedding_type (str) – Type of embedding. Can be one of “classical”, “merge”, “fold” or “cofold”.

  • sigmoid_function (str) – Sigmoid function for merging, resp. smooth max for folding. Can be one of “smooth” or “smoothstep”. smoothstep is better, but requires choice for recursion level.

  • threshold (float) – Threshold for considering eigenvalues as negative

  • approximate (bool) – Whether to accept approximate results or not. Simply sets negative eigenvalues to zero if they occur.

  • fftw_transpose (bool) – Whether FFTW should do transposed transforms.

  • cacheInvMatvec (bool) – Whether matvecs with inverse covariance matrix are cached

  • cacheInvRootMatvec – Whether matvecs with approximate root of inv. cov. matrix are cached

  • cg_iterations (int) – Conjugate Gradients iterations for matrix inverse multiplication

  • cauchy_alpha (float) – The Cauchy Alpha parameter for generalizedCauchy covariance

  • cauchy_beta (float) – The Cauchy Beta parameter for generalizedCauchy covariance

  • exp_gamma (float) – The gamma value for gammaExponential covariance

  • transform (str or Callable) –

    A transformation that should be applied to the raw gaussian random field after evaluation. This can either be a Python callable accepting and returning an array of values or a string to select one of these pre-defined transformations:

    • lognormal: Applies the exponential to the field, thereby producing a log-normal random field.

    • foldednormal: Applied the absolute value to the field, thereby producting folded normal fields.

    • sign: Applies the sign function to the field, thereby producing binary fields that can e.g. be used to generate random subdomains.

  • rng (str or Callable) – The random number generator to use. This can either be a string from the available selection of “twister”, “ranlux, “tausworthe” and “gfsr4”. Alternatively, it can be a callable that, when called with no arguments returns a new sample. This introduces a significant performance penalty as a C++/Python cross-language function call overhead is required for each drawn sample.

  • distribution_algorithm (str) – The algorithm used for RNG. Can be one of “boxMuller” (default), “ratioMethod” or “ziggurat”. This parameter is ignored if a custom RNG function is used.

  • dtype (np.dtype) – The floating point type to use. If the matching C++ type has not been compiled into the backend, an error is thrown.

  • seed (int) – The seed for the random number generator. This can either be an integer to reproduce a field for the given seed or None which would generate a new seed.

  • partitioning – The tuple with processors per direction. The product of all entries is expected to match the number of processors in the communicator. Alternatively, a function can be provided that accepts the number of processors and the cell sizes as arguments.

  • comm – The mpi4py communicator that should be used to distribute this random field. Defaults to MPI_COMM_WORLD. Specifying this parameter when using sequential builds for parafields results in an error.

Returns

A random field instance.

Return type

RandomField

class parafields.field.RandomField(config, transform=None, dtype=<class 'numpy.float64'>, partitioning=None, comm=None, covariance_function=None)
add_block_trend_component(mean_position=None, variance_position=None, mean_extent=None, variance_extent=None, mean_height=0.5, variance_height=0.1)

Add a block trend component to the field

add_disk_trend_component(mean_position=None, variance_position=None, mean_radius=0.05, variance_radius=0.01, mean_height=0.5, variance_height=0.1)

Add a disk trend component to the field

add_mean_trend_component(mean=1.0, variance=1.0)

Add a mean trend component to the field

add_slope_trend_component(mean=None, variance=None)

Add a slope trend component to the field

evaluate()

Evaluate the random field

Returns

A numpy array of the evaluations of the random field on the entire grid that the field is defined on.

Return type

np.ndarray

generate(seed=None, rng=None)

Regenerate the field with the given seed

Parameters

seed (int) – The seed to use. If seed is None, a new seed will be used on every call.

probe(coordinate, interpolation='none')

Evaluate the random field at a given coordinate

Parameters

  • coordinate (np.array) – Where to evaluate the field

  • interpolation (str) – A string indicating what interpolation method to use. This is currently no-op.

parafields.interactive_generate_field(comm=None, partitioning=None, dtype=<class 'numpy.float64'>)

Interactively explore field generation in a Jupyter notebook

Parameters

  • dtype (np.dtype) – The floating point type to use. If the matching C++ type has not been compiled into the backend, an error is thrown.

  • comm – The mpi4py communicator that should be used to distribute this random field. Defaults to MPI_COMM_WORLD. Specifying this parameter when using sequential builds for parafields results in an error.

  • partitioning (list) – The tuple with processors per direction. The product of all entries is expected to match the number of processors in the communicator. Alternatively, a function can be provided that accepts the number of processors and the cell sizes as arguments.