4. Programmatic Interface

Bfrescox is a Python package that builds an internal, barebones Frescox binary during installation. It also provides an interface for using the binary to configure and run Frescox simulations using the internal binary as well as to access results.

4.1. Infrastructure

bfrescox.test(verbosity: int = 1) → bool

Run the full set of tests in the package with results presented to caller using a simple text interface.

This is included so that users can test their actual installation directly or record test results in Jupyter notebook output for reproducibility via:

bfrescox.test()

Args:

verbosity (int): verbosity level to pass to the: unittest TestRunner

Returns:

bool: True if all tests in package passed; False, otherwise.

bfrescox.information()

All code that would like to use the Frescox executable built for this package should use this information to obtain the absolute path to the executable to avoid the situation of simply calling Frescox with no path and inadvertently using a different executable if, for example, the PATH variable is mismanaged.

Note

EXPERT USERS ONLY An empty dict indicates a hollow Bfrescox installation

Returns

dict: contains information regarding the Frescox executable: used by the package.

bfrescox.print_information()

Print information about the Frescox executable used internally by the package.

If otool is installed in macOS systems or ldd in unix-based systems, then Frescox external dependences are listed.

4.2. Simulation Configuration

class bfrescox.Configuration(filename: str | PathLike)

Class representing a Frescox input configuration.

Args:

filename (Union[str, PathLike]): Path to Frescox Fortran namelist: input file

Raises:

TypeError: If filename is not a str or Path ValueError: If filename does not exist or is not a file

classmethod from_NML(filename: str | PathLike) → Configuration

Args:

filename (Union[str, PathLike]): Path to Frescox Fortran: namelist input file

Returns:

Configuration: constructed from contents of given Frescox: Fortran namelist input file

classmethod from_template(template_path: str | PathLike, output_path: str | PathLike, parameters: dict, overwrite: bool = False) → Configuration

Read in a template nml file, replace ‘@key@’ placeholders with corresponding values from parameters, and write result to output_path. The set of possible keys in the template file must exactly match the keys in parameters, or a ValueError will be raised.

For example, if one has a Frescox template file with a line like this defining a potential: ` &POT kp=1 type=1 p1=@V@ p2=@r@ p3=@a@ p4=@W@ p5=@rw@ p6=@aw@ / &POT kp=1 type=2 p1=@Vs@ p2=@rw@ p3=@aw@ p4=@Ws@ p5=@rw@ p6=@aw@ / `

Then the parameters dict should have the keys V, r, a, W, rw, aw, Vs and Ws. Notice that rw and aw are used in multiple places in the template file. The corresponding values in parameters will be substituted into each location where the placeholder appears.

Args:

template_path (Union[str, PathLike]): Path to the template: NML file.
output_path (Union[str, PathLike]): Path to write the: modified NML file.
parameters (dict): Dictionary of parameters to replace in: the template. Keys should match placeholders in the template, corresponding values are the desired replacements in the output file.
overwrite (bool): Whether to overwrite output_path if it: already exists.

Raises:

TypeError: If template_path or output_path are not str or: PathLike
ValueError: If keys exist in the template that are not in: parameters.
ValueError: If keys exist in parameters that are not in: the template file

classmethod from_json(filename: str | PathLike) → Configuration

Args:

filename (Union[str, PathLike]): Path to Frescox Bfrescox format: JSON file

Returns:

Configurationconstructed from contents of given: w|bfrescox| format JSON file

write_to_nml(filename: str | PathLike, overwrite: bool = False) → None

Write configuration to Frescox Fortran namelist input file.

Args:

filename (Union[str, PathLike]): Path to write Frescox Fortran: namelist input file
overwrite (bool): Whether to overwrite filename if it: already exists.

Raises:

TypeError: If filename is not a str or Path RuntimeError: If filename already exists and overwrite is False

4.3. Execution & Results

Run a Frescox simulation based on the given simulation configuration object. Results are written to a file with the given output filename. The Frescox Fortran namelist configuration file generated from the configuration object for the simulation is written alongside the results file.

Args:

configuration (Configuration): Configuration object: that specifies the simulation to run.
filename (Union[str, PathLike]): Filename including path of file: to write outputs to
overwrite (dict, optional): If False, then an error is raised if: either of the simulation input or output files exist
external (bool, optional): (Bfrescox only): EXPERT USERS ONLY
cwd (Union[str, PathLike], optional): directory to run the: simulation in. If None, the current working directory is used.

Raises:

ValueError: If no valid internal or external Frescox: installation is found.

bfrescox.parse_fort16(filename: str | PathLike) → dict[str, DataFrame]

Parse a Frescox fort.16 output into a dict of DataFrames. Each ‘@sN … &’ block becomes one entry labeled channel_N, with all numeric columns and proper names (Theta, sigma, iT11, etc.).

Args:

filename (Union[str, PathLike]): Path to the Frescox fort.16: output file.

Returns:

dict[pd.DataFrame]: Dictionary with keys ‘channel_1’,: ‘channel_2’, etc., each containing a DataFrame of the corresponding data.

Raises:

TypeError: If filename is not a string or Path. ValueError: If the file does not exist.