FabNESO package

Neptune Exploratory SOftware (NESO) plugin for FabSim3.

FabNESO.neso(config: str, solver: str = 'Electrostatic2D3V', conditions_file_name: str = 'conditions.xml', mesh_file_name: str = 'mesh.xml', processes: str | int = 4, nodes: str | int = 1, cpus_per_process: str | int = 1, wall_time: str = '00:15:00', *, create_missing_parameters: bool = False, **parameter_overrides: str) → None[source]

Run a single NESO solver instance.

Parameters:

config – Directory with single run configuration information.

Keyword Arguments:

  • solver – Which NESO solver to use.

  • conditions_file_name – Name of conditions XML file in configuration directory.

  • mesh_file_name – Name of mesh XML in configuration directory.

  • processes – Number of processes to run.

  • nodes – Number of nodes to run on. Only applicable when running on a multi-node system.

  • cpus_per_process – Number of processing units to use per process. Only applicable when running on a multi-node system.

  • wall_time – Maximum time to allow job to run for. Only applicable when submitting to a job scheduler.

  • create_missing_parameters – Force parameters in parameter_overrides missing from conditions file to be added.

  • **parameter_overrides – Additional keyword arguments will be passed to FabNESO.ensemble_tools.edit_parameters to create a temporary conditions file with these parameter vaues overriden.

FabNESO.neso_grid_ensemble(config: str, solver: str = 'Electrostatic2D3V', conditions_file_name: str = 'conditions.xml', mesh_file_name: str = 'mesh.xml', processes: int = 4, nodes: int = 1, cpus_per_process: int = 1, wall_time: str = '00:15:00', **parameter_ranges: str) → None[source]

Run ensemble of NESO solver instances on a evenly spaced parameter grid.

Parameters:

config – Directory with ensemble configuration information.

Keyword Arguments:

  • solver – Which NESO solver to use.

  • conditions_file_name – Name of conditions XML file in configuration directory.

  • mesh_file_name – Name of mesh XML in configuration directory.

  • processes – Number of processes to run in each job in the ensemble.

  • nodes – Number of nodes to run each job in ensemble on. Only applicable when running on a multi-node system.

  • cpus_per_process – Number of processing units to use per process for each job in ensemble. Only applicable when running on a multi-node system.

  • wall_time – Maximum time to allow each job in ensemble to run for. Only applicable when submitting to a job scheduler.

  • **parameter_ranges – The parameter ranges to construct grid over. For each parameter name, a string of the format lower:upper:n_sample should be specified, resulting n_sample evenly spaced values over the interval [lower, upper]. The overall grid is constructed as the tensor product of the samples for each parameter.

FabNESO.neso_pce_ensemble(config: str, solver: str = 'Electrostatic2D3V', conditions_file_name: str = 'conditions.xml', mesh_file_name: str = 'mesh.xml', polynomial_order: int = 4, variant: Literal['pseudo-spectral', 'pseudo-spectral-sparse', 'point-collocation'] = 'pseudo-spectral', processes: str | int = 4, nodes: str | int = 1, cpus_per_process: str | int = 1, wall_time: str = '00:15:00', **parameter_bounds_or_overrides: str) → None[source]

Run ensemble of NESO simulations to perform a polynomial chaos expansion of outputs.

Generates a set of parameters values (and associated weights) to evaluate model at using a quadrature rule, and evaluates model outputs at each of these parameter values. The model outputs can then be approximated by an expansion in a set of orthogonal (with respect to the assumed distribution over the parameter space) polynomials, with the coefficients of the expansion estimated from the sampled model outputs. This task just computes the model outputs for the sampled parameter values, with the separate neso_pce_analysis task using the fetched model outputs from this task to estimate the coefficients and so form the polynomial expansion approximation to the model.

Parameters:

config – Directory with ensemble configuration information.

Keyword Arguments:

  • solver – Which NESO solver to use.

  • conditions_file_name – Name of conditions XML file in configuration directory.

  • mesh_file_name – Name of mesh XML in configuration directory.

  • polynomial_order – Polynomial order to use in polynomial chaos expansion.

  • variant – Polynomial chaos expansion variant to use - one of point-collocation (point-collocation method), pseudo-spectral (pseudo-spectral projection method) or pseudo-spectral-sparse (pseudo-spectral projection method with Smolyak sparse grid).

  • processes – Number of processes to run in each job in the ensemble.

  • nodes – Number of nodes to run on. Only applicable when running on a multi-node system.

  • cpus_per_process – Number of processing units to use per process. Only applicable when running on a multi-node system.

  • wall_time – Maximum time to allow job to run for. Only applicable when submitting to a job scheduler.

  • **parameter_bounds_or_overrides – Bounds of parameters to vary in polynomial chaos expansion or fixed overrides for parameters from values in conditions file in configuration directory. Each value is either a colon-separated string lower_bound:upper_bound specifying lower and upper bounds for independent uniform distributions over parameter values, or a string specifying a single int or float, in which case the corresponding parameter is considered fixed but the value given is used to override its default value in the conditions file.

FabNESO.neso_pce_analysis(config: Path | str, results_dir: Path | str, extract_outputs_script: str = 'extract_outputs.py') → None[source]

Analyse outputs from a previous polynomial chaos expansion (PCE) ensemble run.

Uses run outputs for sampled parameter values to compute a PCE approximation to model, and uses this to compute various statistics of output and allowing construction of a surrogate model. The analysis results are saved to a pickle file pce_analysis_results.pickle in the results directory.

Parameters:

  • config – Name of configuration directory with script to use to extract relevant solver outputs from results files and output to a JSON file.

  • results_dir – Directory containing PCE ensemble outputs from a run of neso_pce task. The analysis results pickle file will be written to this directory.

Keyword Arguments:

extract_outputs_script – Name of script for extracting outputs from results files in configuration directory.

FabNESO.neso_qmc_ensemble(config: str, solver: str = 'Electrostatic2D3V', conditions_file_name: str = 'conditions.xml', mesh_file_name: str = 'mesh.xml', processes: int = 4, nodes: int = 1, cpus_per_process: int = 1, wall_time: str = '00:15:00', n_sample: int = 100, seed: int = 1234, rule: Literal['additive_recursion', 'hammersley', 'korobov', 'latin_hypercube', 'random', 'sobol'] = 'latin_hypercube', **parameter_intervals: str) → None[source]

Run ensemble of NESO solver instances on quasi-Monte Carlo parameter samples.

Parameters:

config – Directory with conditions and mesh files to create ensemble from.

Keyword Arguments:

  • solver – Which NESO solver to use.

  • conditions_file_name – Name of conditions XML file in configuration directory.

  • mesh_file_name – Name of mesh XML in configuration directory.

  • processes – Number of processes to run in each job in the ensemble.

  • nodes – Number of nodes to run each job in ensemble on. Only applicable when running on a multi-node system.

  • cpus_per_process – Number of processing units to use per process for each job in ensemble. Only applicable when running on a multi-node system.

  • wall_time – Maximum time to allow each job in ensemble to run for. Only applicable when submitting to a job scheduler.

  • n_sample – Number of quasi Monte Carlo samples in ensemble.

  • seed – Seed for pseudo-random number generator.

  • rule – String specifying sampling scheme to use.

  • **parameter_intervals – The parameter intervals over which to generate samples from. For each parameter name, a string of the format lower:upper should be specified, with the overall joint distribution on the parameter space the product of the uniform distributions on these intervals.

FabNESO.neso_vbmc(config: str, reference_field_file: str, solver: str = 'Electrostatic2D3V', conditions_file_name: str = 'conditions.xml', mesh_file_name: str = 'mesh.xml', observation_noise_std: float = 0.1, processes: int = 4, nodes: int = 1, cpus_per_process: int = 1, wall_time: str = '00:15:00', output_directory_name: str = '', **vbmc_parameters: str) → None[source]

Run variational Bayesian Monte Carlo (VBMC) to calibrate NESO solver parameters.

The VBMC algorithm (Acerbi, 2018) is an approximate Bayesian inference method for efficient parameter calibration in expensive to simulate models. Here we use the Python implementation of the algorithm in the package PyVBMC (Huggins et al., 2023).

Parameters:

  • config – Directory with ensemble configuration information.

  • reference_field_file – Name of a NumPy .txt file that holds a reference field measurement for the calibration run.

Keyword Arguments:

  • solver – Which NESO solver to use.

  • conditions_file_name – Name of conditions XML file in configuration directory.

  • mesh_file_name – Name of mesh XML in configuration directory.

  • observation_noise_std – Standard deviation of the observed noise, used for log likelihood calculation.

  • processes – Number of processes to run in each job in the ensemble.

  • nodes – Number of nodes to run on. Only applicable when running on a multi-node system.

  • cpus_per_process – Number of processing units to use per process. Only applicable when running on a multi-node system.

  • wall_time – Maximum time to allow job to run for. Only applicable when submitting to a job scheduler.

  • **vbmc_parameters – The parameters to be scanned in the VBMC instance. The value is a colon separated list: lower bound: upper bound: plausible lower bound : plausible upper bound

References

  1. Acerbi, L. (2018). Variational Bayesian Monte Carlo. Advances in Neural Information Processing Systems, 31.

  2. Huggins et al., (2023). PyVBMC: Efficient Bayesian inference in Python. Journal of Open Source Software, 8(86), 5428, https://doi.org/10.21105/joss.05428

FabNESO.neso_write_field(config: str, solver: str = 'Electrostatic2D3V', conditions_file_name: str = 'conditions.xml', mesh_file_name: str = 'mesh.xml', processes: int = 4, nodes: int = 1, cpus_per_process: int = 1, wall_time: str = '00:15:00', out_file_name: str = 'field_write_out.txt', **parameter_overrides: str) → None[source]

Run a single NESO solver instance and save the observed field to a file.

Parameters:

config – Directory with single run configuration information.

Keyword Arguments:

  • solver – Which NESO solver to use.

  • conditions_file_name – Name of conditions XML file in configuration directory.

  • mesh_file_name – Name of mesh XML in configuration directory.

  • processes – Number of processes to run.

  • nodes – Number of nodes to run on. Only applicable when running on a multi-node system.

  • cpus_per_process – Number of processing units to use per process. Only applicable when running on a multi-node system.

  • wall_time – Maximum time to allow job to run for. Only applicable when submitting to a job scheduler.

  • out_file_name – Name of the file to be created containing the measured field

  • **parameter_overrides – Additional keyword arguments will be passed to FabNESO.ensemble_tools.edit_parameters to create a temporary conditions file with these parameter vaues overriden.

Submodules