Skip to content

Configuration¤

NNFE uses a hierarchy of frozen dataclasses to represent the full run configuration. All classes can be constructed programmatically or loaded from YAML via the top-level NNFEConfig.from_yaml class method.

NNFEConfig¤

nnfe.nnfe_config.NNFEConfig ¤

Top-level configuration for the full NNFE solver.

Aggregates all sub-configs required to instantiate :class:~nnfe.nnfe_object.NNFE via :meth:NNFE.from_config.

Attributes:

Name Type Description
project

Filesystem and run-management settings.
plotter

Diagnostic plot settings.
sampler

Training/testing point sampler settings.
FE

Finite element problem configuration (from cardiax).
ML

Neural network and optimizer configuration.
NNFE

NNFE-specific parameter mapping configuration.
from_yaml(path: Path) -> NNFEConfig classmethod ¤

Load a complete :class:NNFEConfig from a YAML file.

The FE and ML sections may either be inlined in the main YAML or provided as paths to separate .yaml files.

Parameters:

Name Type Description Default
path Path

Path to the top-level NNFE config YAML file.

 required

Returns:

Type Description
NNFEConfig

A fully populated :class:NNFEConfig instance.

ProjectConfig¤

nnfe.nnfe_config.ProjectConfig ¤

Filesystem and run-management settings.

Attributes:

Name Type Description
name

Human-readable project name; used as a directory prefix.
parent_dir

Root directory under which the run folder is created.
save

Whether to persist model weights and configuration to disk.
print_progress

Print loss to stdout every N epochs. None disables printing.
save_progress

Save model weights every N epochs during training. None disables intermediate saves.
extra_dirs

Mapping of logical names (e.g. "model_dir", "plot_dir") to subdirectory paths relative to the run root.
trained_weights_path

Optional path to pre-trained model weights loaded at startup (before training).
name = 'Project' class-attribute ¤

str(object='') -> str str(bytes_or_buffer[, encoding[, errors]]) -> str

Create a new string object from the given object. If encoding or errors is specified, then the object must expose a data buffer that will be decoded using the given encoding and error handler. Otherwise, returns the result of object.str() (if defined) or repr(object). encoding defaults to 'utf-8'. errors defaults to 'strict'.

parent_dir = PosixPath('.') class-attribute ¤

Path subclass for non-Windows systems.

On a POSIX system, instantiating a Path should return this object.

save = True class-attribute ¤

Returns True when the argument is true, False otherwise. The builtins True and False are the only two instances of the class bool. The class bool is a subclass of the class int, and cannot be subclassed.

from_dict(params: dict) -> ProjectConfig classmethod ¤

Construct a :class:ProjectConfig from a raw config dictionary.

Parameters:

Name Type Description Default
params dict

Dict with keys name, parent_dir, save, print_progress, save_progress, and optionally extra_dirs and trained_weights_path.

 required

Returns:

Type Description
ProjectConfig

A new :class:ProjectConfig instance.

PlotterConfig¤

nnfe.nnfe_config.PlotterConfig ¤

Settings controlling which diagnostic plots are generated.

Attributes:

Name Type Description
plot_loss

Whether to plot the training loss curve.
plot_lr

Whether to plot the learning-rate schedule.
plot_sample

Whether to plot the sampling distribution (currently unused but reserved for future use).
plot_loss = True class-attribute ¤

Returns True when the argument is true, False otherwise. The builtins True and False are the only two instances of the class bool. The class bool is a subclass of the class int, and cannot be subclassed.

plot_lr = True class-attribute ¤

Returns True when the argument is true, False otherwise. The builtins True and False are the only two instances of the class bool. The class bool is a subclass of the class int, and cannot be subclassed.

plot_sample = True class-attribute ¤

Returns True when the argument is true, False otherwise. The builtins True and False are the only two instances of the class bool. The class bool is a subclass of the class int, and cannot be subclassed.

from_dict(params: dict) -> PlotterConfig classmethod ¤

Construct a :class:PlotterConfig from a raw config dictionary.

Parameters:

Name Type Description Default
params dict

Dict with keys plot_loss and plot_lr.

 required

Returns:

Type Description
PlotterConfig

A new :class:PlotterConfig instance.

SamplerConfig¤

nnfe.nnfe_config.SamplerConfig ¤

Configuration for the training and testing point samplers.

Stores what to sample (sampler type and bounds); the actual sampling is performed by :class:~nnfe.sampling.Sampler.

Attributes:

Name Type Description
training_sampler

Name of the sampler used for training points. Currently only "uniform" is supported.
training_kwargs

Keyword arguments forwarded to the training sampler (e.g. mins, maxes, samples).
testing_sampler

Name of the sampler used for test points.
testing_kwargs

Keyword arguments forwarded to the testing sampler.
testing_sampler = 'uniform' class-attribute ¤

str(object='') -> str str(bytes_or_buffer[, encoding[, errors]]) -> str

Create a new string object from the given object. If encoding or errors is specified, then the object must expose a data buffer that will be decoded using the given encoding and error handler. Otherwise, returns the result of object.str() (if defined) or repr(object). encoding defaults to 'utf-8'. errors defaults to 'strict'.

training_sampler = 'uniform' class-attribute ¤

str(object='') -> str str(bytes_or_buffer[, encoding[, errors]]) -> str

Create a new string object from the given object. If encoding or errors is specified, then the object must expose a data buffer that will be decoded using the given encoding and error handler. Otherwise, returns the result of object.str() (if defined) or repr(object). encoding defaults to 'utf-8'. errors defaults to 'strict'.

from_dict(params: dict) -> SamplerConfig classmethod ¤

Construct a :class:SamplerConfig from a raw config dictionary.

Parameters:

Name Type Description Default
params dict

Dict with keys training_sampler, testing_sampler, training_kwargs, and testing_kwargs.

 required

Returns:

Type Description
SamplerConfig

A new :class:SamplerConfig instance.

Raises:

Type Description
ValueError

If either sampler name is not recognised.

NNFEParamsConfig¤

nnfe.nnfe_config.NNFEParamsConfig ¤

NNFE-specific parameter configuration describing which FE quantities the network controls.

The NNFE method parameterises FE internal variables and/or Dirichlet boundary conditions with the neural network output. This config specifies which variables are parameterised and in what order they appear in the network output vector.

Attributes:

Name Type Description
natural

Nested dict mapping FE keys to the internal variables (volumetric or surface) that are controlled by the natural (Neumann-type) outputs of the network. Structure::

natural:
  internal:
    <fe_key>:
      <var_name>: ...
  surface:
    <fe_key>:
      <bc_name>:
        <var_name>: ...
essential

Nested dict for Dirichlet (essential) boundary condition outputs (currently unused in the gradient computation but reserved).
natural_order

Ordered list of variable names that maps network output indices to natural variables (used for slicing the output vector).
essential_order

Ordered list of variable names for essential (Dirichlet) outputs. An empty list disables Dirichlet training.
from_dict(params: dict) -> NNFEParamsConfig classmethod ¤

Construct an :class:NNFEParamsConfig from a raw config dictionary.

Parameters:

Name Type Description Default
params dict

Dict with keys natural_order, essential_order, and optionally natural and essential.

 required

Returns:

Type Description
NNFEParamsConfig

A new :class:NNFEParamsConfig instance.

MLConfig¤

nnfe.ml_config.MLConfig ¤

Top-level machine-learning configuration consumed by :class:~nnfe.ml.MLManager.

Attributes:

Name Type Description
networks

Ordered mapping of network names to their :class:NetworkConfig objects. When more than one network is present they are combined additively via :class:~nnfe.networks.Sum_models.
optimizer

Optimizer and learning-rate schedule configuration.
epochs

Total number of training iterations.
batch_size

Fraction of the training set to sample per step (value in (0, 1]).
rng_key

Integer seed for JAX PRNG initialisation. Defaults to 0; may also be set to a project-level key at runtime.
rng_key = 0 class-attribute ¤

int([x]) -> integer int(x, base=10) -> integer

Convert a number or string to an integer, or return 0 if no arguments are given. If x is a number, return x.int(). For floating-point numbers, this truncates towards zero.

If x is not a number or if base is given, then x must be a string, bytes, or bytearray instance representing an integer literal in the given base. The literal can be preceded by '+' or '-' and be surrounded by whitespace. The base defaults to 10. Valid bases are 0 and 2-36. Base 0 means to interpret the base from the string as an integer literal.

int('0b100', base=0) 4

from_dict(params: dict) -> MLConfig classmethod ¤

Construct an :class:MLConfig from a raw config dictionary.

Parameters:

Name Type Description Default
params dict

Dict with keys networks, optimizer, epochs, batch_size, and optionally rng_key.

 required

Returns:

Type Description
MLConfig

A new :class:MLConfig instance.
from_yaml(path) -> MLConfig classmethod ¤

Load an :class:MLConfig from a YAML file.

Parameters:

Name Type Description Default
path

Path to the YAML file.

 required

Returns:

Type Description
MLConfig

A new :class:MLConfig instance.

NetworkConfig¤

nnfe.ml_config.NetworkConfig ¤

Configuration for a single neural network.

Attributes:

Name Type Description
name

Name of the network class in :mod:nnfe.networks (e.g. "DNN", "ResNet").
kwargs

Keyword arguments forwarded to the network constructor. The special value "dofs" for out_size is resolved at runtime by :class:~nnfe.ml.MLManager to the problem's total DoF count.
load_model

Optional path to a serialised Equinox model file (.eqx). When set, weights are loaded instead of randomly initialised.
static

If True, the network's parameters are frozen during training (excluded from gradient updates).
static = False class-attribute ¤

Returns True when the argument is true, False otherwise. The builtins True and False are the only two instances of the class bool. The class bool is a subclass of the class int, and cannot be subclassed.

from_dict(params: dict) -> NetworkConfig classmethod ¤

Construct a :class:NetworkConfig from a raw config dictionary.

Parameters:

Name Type Description Default
params dict

Dict with keys name, kwargs, and optionally load_model and static.

 required

Returns:

Type Description
NetworkConfig

A new :class:NetworkConfig instance.

OptimizerConfig¤

nnfe.ml_config.OptimizerConfig ¤

Configuration for the Optax optimizer and its learning-rate schedule.

Attributes:

Name Type Description
name

Name of the Optax optimizer (e.g. "adam").
lr_scheduler

Whether to use a learning-rate schedule. When True, scheduler must be supplied.
optimizer_kwargs

Extra keyword arguments forwarded to the Optax optimizer (excluding learning_rate, which is injected from the scheduler).
scheduler

Nested dict describing a :func:optax.join_schedules setup. Expected structure::

boundaries: [<step>, ...]
schedules:
  s0:
    name: <optax schedule name>
    kwargs: {...}
  ...
lr_scheduler = True class-attribute ¤

Returns True when the argument is true, False otherwise. The builtins True and False are the only two instances of the class bool. The class bool is a subclass of the class int, and cannot be subclassed.

from_dict(params: dict) -> OptimizerConfig classmethod ¤

Construct an :class:OptimizerConfig from a raw config dictionary.

Parameters:

Name Type Description Default
params dict

Dict with keys name and optionally lr_scheduler, optimizer_kwargs, and scheduler.

 required

Returns:

Type Description
OptimizerConfig

A new :class:OptimizerConfig instance.