API documentation

Running the optimiser

The optimiser accepts three arguments:

1. The Evaluator that determines how to evaluate the target function f(x);

2. The starting location x_0; and

3. The Solver configuration settings.

mcasopt.minimise(evaluator: Callable[[numpy.ndarray, int | None], Evaluator], x0: Sequence[int | float], config: Solver)

Find the approximate solution x that minimises f(x).

Function evaluation

The mcasopt package provides several “evaluators”, which can be used to evaluate different types of target functions:

• The FunctionEvaluator evaluates standard Python functions;

• The ExpressionEvaluator evaluated numeric Python expressions; and

• The McasEvaluator runs MCAS simulations and scores the outputs against the solution criteria.

Note

McasEvaluator requires a Runner, which defines how to run MCAS simulations. The following runners are provided by mcasopt:

• SlurmRunner, which runs MCAS simulations on Spartan via the Slurm job scheduling system;

• LocalRunner, which runs MCAS simulations on your local computer; and

• FakeMcasRunner, which runs fake MCAS simulations on the local computer by calling mcasopt.run.fake_mcas().

class mcasopt.solver.Evaluator(*args, **kwargs)

A protocol for potentially-deferred evaluation of functions.

start(job_id: str) → None

Begin evaluating the function.

result() → float | None

Return the evaluation result, or None if the evaluation has not finished.

class mcasopt.solver.FunctionEvaluator(f, x)

Immediate evaluation of Python functions.

classmethod builder(function)

Return a function that evaluates Python functions.

class mcasopt.solver.ExpressionEvaluator(f, x)

Deferred evaluation of Python expressions, using subprocesses.

classmethod builder(function)

Return a function that evaluates Python expressions.

class mcasopt.run.McasEvaluator(config, criteria, mcas_input, runner: Runner, f, x, counter)

Evaluate MCAS outputs against a set of criteria.

classmethod builder(config, runner, function)

Return a function that runs MCAS simulations using the provided runner.

classmethod run_with_slurm(config, function)

Return a function that runs MCAS simulations using Slurm.

classmethod run_locally(config, function)

Return a function that runs MCAS simulations on the local machine.

command(job_id: str)

Return a command that defines an MCAS simulation.

Parameters:

job_id – A unique identifier for this simulation.

experiment_dir()

Return the directory in which the MCAS simulation is running, if any.

mcasopt.run.fake_mcas(args=None)

Provide an entry-point for running “MCAS-like” simulations that output perturbed results. This is used to test the solver without needing to run MCAS simulations.

Running commands

class mcasopt.run.Command(args: List[str], stdin: Path | None, stdout: Path | None, cwd: Path | None)

The details required to run a command in a separate process.

• args: a list of arguments;

• stdin: optional path for reading input;

• stdout: optional path for writing output; and

• cwd: optional path to the working directory.

class mcasopt.run.Runner(*args, **kwargs)

Provide a means of running commands.

start_command(command: Command) → T

Start running a command, and return a handle that can be used to check the command’s status.

completion_status(handle: T) → int | None

Return None if the job has not completed, otherwise return its exit status; typically, zero indicates successful completion.

class mcasopt.run.SlurmRunner(config)

Schedule a Slurm job and monitor its status.

start_command(command: Command)

Submit this job.

write_script(script_file, command: Command)

Write the Slurm job script to the specified file.

write_script_to(f, command: Command)

Write the Slurm job script to the specified file object.

class mcasopt.run.LocalRunner(*args, **kwargs)

Run MCAS on the local machine.

start_command(command: Command)

Submit this job.

completion_status(popen)

Return None if the job has not completed, otherwise return its exit status; typically, zero indicates successful completion.

class mcasopt.run.FakeMcasRunner(*args, **kwargs)

Run the fake-mcas script on the local machine.

start_command(command: Command)

Start running a command, and return a handle that can be used to check the command’s status.

completion_status(popen)

Return None if the job has not completed, otherwise return its exit status; typically, zero indicates successful completion.

Configuration settings

The configuration settings Config are divided into three sections:

• The Experiment definition;

• The Solver settings; and

• The Slurm settings.

These settings can be loaded from an external file with load_config().

mcasopt.run.load_config(config_file) → Config

Load configuration settings from a TOML file.

class mcasopt.run.Config(experiment: Experiment, criteria: Criteria, solver: Solver, slurm: Slurm | None = None)

The configuration settings needed to run an mcasopt experiment.

Parameters:

settings – A nested dictionary of configuration settings.

Raises:

ValueError – if the settings are invalid or incomplete.

classmethod load(settings: Dict[str, Any | Mapping[str, Any]])

Load configuration settings from a dictionary.

mcas_input() → Input

Load the MCAS input for this experiment.

class mcasopt.run.Experiment(name: str, input_file: Path, mcas_path: Path, amdc_masses_path: Path, input_function: Callable[[Input, List[float]], Input], x_0: List[float], runner: str, backup_results: bool = False, cleanup: bool = False, penalty_missing: float = 1000000.0, penalty_spin: float = 1000000.0)

Configuration settings for a specific experiment.

class mcasopt.solver.Solver(cache_file: Path, method: str = 'Nelder-Mead', bounds: List[Tuple[float, float]] | None = None, epsilon: float = 1.5e-08, sleep_duration: float = 0.0, log_level: str = 'INFO')

Configuration settings for the optimisation solver.

class mcasopt.run.Slurm(shebang: str, header: Dict[str, str], modules: List[str], output_date: bool = True)

Configuration settings for Slurm jobs.

Model criteria

mcasopt.criteria.parse_criteria(criteria)

Parse model criteria and return a Criteria instance.

class mcasopt.criteria.Criteria(criteria)

ordered_criteria()

Sort the criteria from most restrictive (having a single spin and parity) to less restrictive (having multiple spins and/or parities) to least restrictive (having no spin and parity).

Model parameters

mcasopt.model.load_input(filename)

Read a model input file and return an Input instance.

Parameters:

filename – The filename of the model input file.

class mcasopt.model.Input(f)

write(f)

Write the contents of this block to a file.

Parameters:

f – The destination file (or file-like) object.

write_to(filename)

Write the contents of this block to a file.

Parameters:

filename – The destination file name.

Caching simulation results

mcasopt.cache.load_cache(filename)

Return a cache that records simulation results to disk.

Parameters:

cache_file – The file in which to record the return values. If this file exists, the cached results will be loaded from this file.

class mcasopt.cache.Cache(cache_file)

Cache return values of a function.

Parameters:

cache_file – The file in which to record the return values. If this file exists, the cached results will be loaded from this file.

Instances of this class have the following member variables:

• cache_file: the file in which to record the return values; and

• cache: a dictionary that maps locations x to return values y_and_dx.

load_from_file()

Read cached results from the cache file.

save_to_file()

Save cached results to the cache file.

contains(x)

Return whether the function has been evaluated at this location.

Parameters:

x – the location at which to evaluate the function.

query(x)

Return the cached return value at a specific location, if the function has previously been evaluated at this location. Otherwise, return None.

Parameters:

x – the location at which to evaluate the function.

insert(x, y_and_dx, save=True)

Record the value returned by the function at a new location.

Parameters:

• x – the location at which the function was evaluated.

• y_and_dx – the value returned by the function, which comprises the return value itself and the estimated gradient.

• save – whether to save the cache to disk.

best_solution_to_date()

Return a tuple that contains the smallest error so far, and a list containing the parameter values associated with that smallest error.

If no results have been cached, this will return (numpy.inf, []).

Example experiments

n+12C

mcasopt.example.save_n_plus_12C_files(out_dir=None)

Save the files needed to run the ‘n+12C’ example simulation.

Parameters:

out_dir – The directory in which to save the files (optional; the default value is the working directory).

mcasopt.example.remove_n_plus_12C_files(out_dir=None)

Remove the files needed to run the ‘n+12C’ example simulation.

Parameters:

out_dir – The directory that contains the files (optional; the default value is the working directory).

Raises:

FileNotFoundError – if any example files are missing.

mcasopt.example.n_plus_12C_files()

The files required for the ‘n+12C’ example simulation.