Rombus API Documentation

How to use the documentation

Documentation is available via docstrings provided with the code.

We recommend exploring the docstrings using IPython <http://ipython.scipy.org>, an advanced Python shell with TAB-completion and introspection capabilities. See below for further instructions.

The docstring examples assume that rombus has been imported as rb:

>>> import rombus as rb

Code snippets are indicated by three greater-than signs.

Use the built-in help function to view a function’s or class’s docstring:

>>> help(rb.model)

Viewing documentation using IPython

Start IPython and load Rombus (import rombus as rb), which will import rombus under the alias rb. Then, use the cpaste command to paste examples into the shell. To see which functions are available in rombus, type rb.<TAB> (where <TAB> refers to the TAB key), or use rb.model?<ENTER> (where <ENTER> refers to the ENTER key) to narrow down the list. To view the docstring for a function or class, use rb.model?<ENTER> (to view the docstring) and rb.model??<ENTER> (to view the source code).

Submodules

rombus.model 

class rombus.model.RombusModel(model: str)[source]

Bases: object

Baseclass from which all RombusModels must inherit.

coordinate: _Coordinate = <rombus.model._Coordinate object>: The domain on which this model is defined.

ordinate: _Ordinate = <rombus.model._Ordinate object>: The ordinate that this model maps its domain to.

params: Params = <rombus.params.Params object>: The parameters defined for this model

abstract compute(params: NamedTuple, domain: ndarray) → ndarray[source]

Abstract method which computes the user’s model.

This method does all the work of computing the user’s model. It takes a parameter set as a named tuple with N elements given by the names given to the N calls made to params.add() as well as the array set by coordinate.set() and returns a numpy array.

Parameters:

params (NamedTuple) – The parameters to be used when computing the model
domain (np.ndarray) – The domain on which the model is to be computed

Returns:

The user’s model, computed for the given parameter set and domain

Return type:

np.ndarray

classmethod from_file(file_in: FileOrFilename) → Self[source]

Generate a RombusModel instance from a Rombus HDF5 file.

Parameters:: file_in (hdf5.FileOrFilename) – The Rombus HDF5 file to read from.
Returns:: The generated RombusModel instance.
Return type:: Self

classmethod load(model: str | Self) → Self[source]

Ensure that a model has been imported for use by Rombus.

Parameters:: model (str | Self) – A string of format ‘sub,module.name:ClassName’ or a RombusModel instance (trivially returned in the later case).
Returns:: A RombusModel instance
Return type:: Self

write(h5file: File) → None[source]

Write a RombusModel to a Rombus HDF5 file.

Parameters:: h5file (hdf5.File) – An open HDF5 file

generate_model_set(samples: Samples) → ndarray[source]

Generate a set of models for a given set of parameter samples.

Parameters:: samples ("Samples") – A set of Samples
Returns:: An array of model results: 1 for each given sample.
Return type:: np.ndarray

parse_cli_params(args: Tuple[str, ...]) → Dict[str, Any][source]

Parse parameters given as a tuple of form ‘param0=val0’, ‘param1=val1’, … etc to a dictionary of form {‘param0’:val0, ‘param1’:val1, … }.

Generally used to parse the optional arguments recieved from Click into a format that can be converted into a Params or Numpy object

Parameters:: args (Tuple[str, ...]) – Given tuple of parameters
Returns:: Resulting dict of parameters
Return type:: Dict[str, Any]

sample(kwargs: Dict[str, Any]) → NamedTuple[source]

Create a Sample from a dictionary of the form {“param0:val0,”param1”:val1,…}

Parameters:: kwargs (Dict[str, Any]) – Dict specifying parameter values
Returns:: Named tuple specifying paramter values
Return type:: NamedTuple

timing(samples: Samples) → float[source]

Generate timing information for the original source model. Particularly useful when compared to similar timing information computed for ROMs derived from it.

Parameters:: samples ("Samples") – A set of parameters to generate timing information for. Should be the same as those used when timiing a ROM, if comparisons are to be made.
Returns:: Seconds elapsed
Return type:: float

classmethod write_project_template(project_name: str) → None[source]

Write a project model to the current working directory to start a new project from.

Two files are written to the current working direcory: a Python file and a set of samples. These can then be modified to suit the needs of the user.

Parameters:: project_name (str) – Base name to use for the project.

rombus.params 

class rombus.params.Params[source]

Bases: object

add(name: str, range_min: float, range_max: float, dtype: type = <class 'float'>) → None[source]

Add a parameter to this parameter set.

Parameters:

name (str) – Name of the parameter. This will become the reference name when accessing NamedTuple & dict versions of the parameters
range_min (float) – The minimum-allowed value for this parameter
range_max (float) – The maximum-allowed value for this parameter
dtype (type) – The datatype used to represent this parameter

set_validation(func: Callable[[NamedTuple], bool]) → None[source]

Specify a callable which accepts a parameter set (in the form of a NamedTuple) and returns a bool indicating if the parameter set is valid.

By default, no validation is performed and all passed samples are assumed to be valid.

Parameters:: func (Callable) – Callable which will perform the validation

generate_random_sample(random_generator: Generator) → ndarray[source]

Generate a random parameter set, with values uniformly distributed between their specified min and max values.

Parameters:: random_generator (np.random._generator.Generator) – An initialised numpy random number generator
Returns:: A parameter set in numpy form
Return type:: np.ndarray

np2param(params_np: ndarray) → NamedTuple[source]

Convert a numpy version of a parameter set to a NamedTuple format.

Parameters:: params_np (np.ndarray) – Numpy version of parameter set
Returns:: NamedTuple version of parameter set
Return type:: NamedTuple

rombus.samples 

class rombus.samples.Samples(model: RombusModel, filename: str | None = None, n_random: int = 0)[source]

Bases: object

Class for managing sets of parameter samples for Rombus.

model: RombusModel: Rombus model for which the samples are computed

n_random: int: Number of random points generated for this set

n_samples: int32: Number of samples in this set.

samples: List[ndarray]: List of samples in this set.

classmethod from_file(file_in: FileOrFilename) → Self[source]

Create an instance of a Sample set from a Rombus file on disk.

Parameters:: file_in (hdf5.FileOrFilename) – Rombus file (filename or opened file) to read from
Returns:: Returns a reference to self so that method calls can be chained
Return type:: Self

extend(new_samples: List[ndarray]) → None[source]

Add additional samples to the set.

Parameters:: new_samples (List[Sample]) – A list of new samples

write(h5file: File)[source]

Save samples to an open HDF5 file.

Parameters:: h5file (hdf5.File) – An open HDF5 file

rombus.rom 

class rombus.rom.ReducedOrderModel(model: RombusModel | str, samples: Samples, reduced_basis: ReducedBasis | None = None, empirical_interpolant: EmpiricalInterpolant | None = None, basename: str | None = None, tol: float = 1e-14)[source]

Bases: object

Class for managing the creation, updating and subsequent use of a Reduced Order Model (ROM).

model: RombusModel: Model used to generate the ROM

samples: Samples fed to the greedy algorithm to generate the ROM

reduced_basis: ReducedBasis generated for the ROM

empirical_interpolant: EmpiricalInterpolant generated for the ROM

basename: Set when reading from files and provides a base name for writing plots to file, etc.

classmethod from_file(file_in: FileOrFilename) → Self[source]

Instantiate a ROM from a Rombus HDF5 file.

Parameters:: file_in (hdf5.FileOrFilename) – Rombus file (filename or opened file) to read from
Returns:: Return a reference to self so that methods can be chained.
Return type:: Self

build(do_step: str | None = None, tol: float = 1e-14) → Self[source]

(Re)build a ReducedOrderModel.

Parameters:

do_step (str|None) – Specify whether to just compute the ReducedBasis (‘RB’) or the EmpiricalInterpolant (‘EI’) or both (None)
tol (float) – Absolute error tolerance when building the reduced basis

Returns:

Returns a reference to self, so that method calls can be chained

Return type:

Self

evaluate(params: NamedTuple) → ndarray[source]

Evaluate the ROM for a given set of parameters.

Parameters:: params (NamedTuple) – The parameters to evaluate the model for
Returns:: The ROM evaluation of the model
Return type:: np.ndarray

refine(n_random: int = 100, tol: float = 1e-14, iterate: bool = True) → Self[source]

Refine the model by attempting to add new samples to it.

Parameters:

n_random (int) – Number of random samples to generate per iteration
tol (float) – The absolute tolerance to use when evaluating the errors of each sample
iterate (bool) – Flag that sets whether to iteratively refine until no new samples are added.

Returns:

Returns self so that methods can be chained

Return type:

Self

write(filename: str) → None[source]

Save the ROM to a Rombus HDF5 file.

Parameters:: filename (str) – Filename of the output file

timing(samples: Samples) → float[source]

Generate timing information for the ROM. Particularly useful when compared to similar timing information computed for the source model it is derived from.

Parameters:: samples ("Samples") – A set of parameters to generate timing information for. Should be the same as those used when timiing the source model, if comparisons are to be made.
Returns:: Seconds elapsed
Return type:: float

rombus.reduced_basis 

class rombus.reduced_basis.ReducedBasis(matrix: List[ndarray] = [], greedypoints: List[ndarray] = [], error_list: List[float] = [], matrix_shape: List[int] = [0, 0])[source]

Bases: object

Class for managing the creation of reduced basis sets.

matrix: List of matrices, storing the reduced bases

greedypoints: List of matrices, storing the selected greedy points

error_list: Errors calculated for each basis

matrix_shape: List[int]: Shape of the reduced basis matrix

classmethod from_file(file_in: FileOrFilename) → Self[source]

Instantiate a reduced basis from a Rombus file on disk.

Parameters:: file_in (hdf5.FileOrFilename) – HDF5 file (filename or opend file) to read from
Returns:: Returns a reference to self so that method calls can be chained
Return type:: Self

compute(model: RombusModel | str, samples: Samples, tol: float = 1e-14) → Self[source]

Compute a reduced basis for a given model and set of parameters.

Parameters:

model (RombusModelType) – Rombus model to compute the reduced basis for
samples (Samples) – Set of parameter samples for the greedy algorithm to select from
tol (float) – The absolute tolerance in the error for the greedy algorythm to use for sample selection

Returns:

Returns a reference to self, so that method calls can be chained.

Return type:

Self

write(h5file: File) → None[source]

Save reduced basis to file.

Parameters:: h5file (hdf5.File) – Open HDF5 file to read from

rombus.ei 

class rombus.ei.EmpiricalInterpolant(B_matrix: ndarray = array(5.e-324), nodes: ndarray = array(4.64485192e-310))[source]

Bases: object

Class for managing the creation of empirical interpolants (EIs)

B_matrix: Basis matrix

nodes: Interpolant nodes

compute(reduced_basis: ReducedBasis) → Self[source]

Compute empirical interpolant for a given reduced basis

Parameters:: reduced_basis (ReducedBasis) – Reduced basis used to compute the empirical interpolant
Returns:: A reference to self, to allow for chaining of method calls
Return type:: Self

write(h5file: File) → None[source]

Write empirical interpolant to an open HDF5 file

Parameters:: h5file (hdf5.File) – Open HDF5 file

classmethod from_file(file_in: FileOrFilename) → Self[source]

Instantiate an EmpiricalInterpolant from a Rombus file.

Parameters:: file_in (hdf5.FileOrFilename) – Rombus file (filename or open file) to read from
Returns:: Returns a reference to self, so that method calls can be chained
Return type:: Self

rombus.plots 

rombus.plots.bases_errors(ROM: ReducedOrderModel) → None[source]

Generate plot of errors.

Parameters:: err_list (List[float]) – List of errors

rombus.plots.bases(ROM: ReducedOrderModel) → None[source]

Generate a plot of the Reduced Bases.

Parameters:: rb_matrix (List[np.ndarray]) – List of reduced bases

rombus.plots.compare_rom_to_true(ROM: ReducedOrderModel, model_params_in: Dict[str, Any]) → None[source]

Generate a plot comparing the ROM to the original source model for a given set of parameters.

Parameters:

ROM (ReducedOrderModel) – The Reduced Order Model to make the comparison for
model_params_in (Dict[str, Any]) – A dictionary of parameters to use as the input parameters

rombus.exceptions 

exception rombus.exceptions.RombusException(message: str)[source]

Bases: Exception

Base class for exceptions raised from Rombus

handle_exception() → None[source]

exception rombus.exceptions.EmpiricalInterpolantNotComputedError(message: str)[source]

Bases: RombusException

Raised when an EmpiricalInterpolant operation is attempted on a ROM whose EI has not yet been computed.

exception rombus.exceptions.RombusModelOrdinateError(message: str)[source]

Bases: RombusException

Raised when an error is encountered when initialising a RombusModel ordinate.

exception rombus.exceptions.RombusModelCoordinateError(message: str)[source]

Bases: RombusException

Raised when an error is encountered when initialising a RombusModel coordinate.

exception rombus.exceptions.RombusModelParamsError(message: str)[source]

Bases: RombusException

Raised when a Rombus model is instantiated with no parameters specified.

exception rombus.exceptions.RombusModelImportFromStringError(message: str)[source]

Bases: RombusException

Raised when the import of a RombusModel from a string fails.

exception rombus.exceptions.RombusModelInitError(message: str)[source]

Bases: RombusException

Raised when the instantiation of a RombusModel fails.

exception rombus.exceptions.RombusPlotError(message: str)[source]

Bases: RombusException

Raised when there is an error generating a plot.

exception rombus.exceptions.ReducedBasisInitError(message: str)[source]

Bases: RombusException

Raised when a ReducedBasis object can not be initialised.

exception rombus.exceptions.ReducedBasisNotComputedError(message: str)[source]

Bases: RombusException

Raised when an EmpiricalInterpolant operation is attempted on a ROM whose EI has not yet been computed.

exception rombus.exceptions.ReducedBasisComputeError(message: str)[source]

Bases: RombusException

Raised when a ReducedBasis object can not be computed.

exception rombus.exceptions.RombusModelLoadError(message: str)[source]

Bases: RombusException

Raised when a Rombus model fails to load.

exception rombus.exceptions.RomNotInitialised(message: str)[source]

Bases: RombusException

Raised when an uninitialised ROM is accessed.

exception rombus.exceptions.RombusHDF5Error(message: str)[source]

Bases: RombusException

Raised when an HDF5 error is raised when accessing a ROM file.