coexist.Access

class coexist.Access(script_path: str, scheduler=LocalScheduler(python_executable=['/home/docs/checkouts/readthedocs.org/user_builds/coexist/envs/latest/bin/python']))

Bases: object

Optimise an arbitrary user-defined script’s parameters in parallel.

A minimal user script - saved in a separate file - would be:

# In file "script_filepath.py"

# ACCESS PARAMETERS START
import coexist

parameters = coexist.create_parameters(
    variables = ["fp1", "fp2"],
    minimums = [-3, -7],
    maximums = [+5, +3],
)

access_id = 0                           # Optional
# ACCESS PARAMETERS END

x = parameters.at["fp1", "value"]
y = parameters.at["fp2", "value"]

error = x ** 2 + y ** 2

This script defines two free parameters to optimise “fp1” and “fp2” with ranges [-3, +5] and [-7, +3] and saves an error value to be optimised in the variable error. To optimise it, run in another file:

# In file "access_learn.py"
import coexist

access = coexist.Access("script_filepath.py")
access.learn(num_solutions = 10, target_sigma = 0.1, random_seed = 42)

Once you run access.learn(), a folder named “access_42” is generated which stores all information about this access run, including all simulation data. You can load this data using coexist.AccessData.read even while the optimisation is still running.

In general, an ACCESS user script must define one simulation whose parameters will be optimised this way:

1. Use a variable named “parameters” to define this simulation’s free / optimisable parameters. Create it using coexist.create_parameters. An initial guess can also be set here.

2. The parameters creation should be fully self-contained between two # ACCESS PARAMETERS START and # ACCESS PARAMETERS END comments - i.e. it should not depend on code ran before the block.

3. By the end of the simulation script, define a variable named error storing a single number representing this simulation’s error value.

Notice that there is no limitation on how the error value is calculated. It can be any simulation, executed in any way - even externally; just launch a separate process from the Python script, run the simulation, extract data back into the Python script and set error to what you need optimised.

If you need to save data to disk, use file names containing the access_id variable which is set to a unique integer ID for each simulation, so that you don’t overwrite existing files when simulations are executed in parallel.

For more information on the implementation details and how parallel execution of your user script is achieved, check out the generated file “access_seed<seed>/access_script.py” after running access.learn().

Attributes:

setupcoexist.access.AccessSetup

Structure storing given ACCES configuration, containing the free parameters, number of solutions to try in parallel population, target uncertainty target, seeded random number generator rng and the seed.

pathscoexist.access.AccessPaths

Structure storing paths to the ACCES directory, saved state, simulations tried, captured outputs directory, and paths to the previous results history and history_scaled.

progresscoexist.access.AccessProgress

Structure storing ACCES optimisation run progress - epochs, history (and CMA-scaled versions of them) and latest stdout and stderr messages.

schedulercoexist.schedulers.Scheduler subclass

The scheduler used to launch each simulation in parallel.

multi_objectiveobject, optional

An object defining the method combine, combining multiple errors into a single value.

verboseint, optional

Integer denoting the level of verbosity, where 0 is quiet and 5 is maximally verbose.

__init__(script_path: str, scheduler=LocalScheduler(python_executable=['/home/docs/checkouts/readthedocs.org/user_builds/coexist/envs/latest/bin/python']))

Access class constructor.

Parameters:

script_pathstr

A path to a user-defined script that runs one simulation. It should use the free / optimisable parameters saved in a pandas.DataFrame named exactly parameters, defined between two comments # ACCESS PARAMETERS START and # ACCESS PARAMETERS END. By the end of the script, one variable named error must be defined containing the error value, a number.

schedulercoexist.schedulers.Scheduler subclass

Scheduler used to spawn function evaluations / simulations in parallel. The default LocalScheduler simply starts new Python interpreters on the local machine for executing the user’s script. See the other schedulers in coexist.schedulers for e.g. spawning jobs on a supercomputing cluster.

Methods

__init__(script_path[, scheduler])	Access class constructor.
evaluate_solutions(solutions, epoch)	Evaluate the parameter combinations given in solutions for the current epoch in parallel.
finished(es)	Check if the optimisation run is done and display the best solution found for the target sigma value.
has_historical(epoch)	Check ACCES still has historical solutions to inject.
inject_historical(es, epoch)	Inject the CMA-ES optimiser with pre-computed (historical) results.
learn([num_solutions, target_sigma, ...])	Learn the free parameters from the user script that minimise the error variable by trying num_solutions parameter combinations at a time until the overall uncertainty becomes lower than target_sigma.
print_after_eval(es, epoch, solutions, ...)	Display parameter combinations evaluated in the current epoch and the corresponding errors found.
print_before_eval(es, epoch, scaling)	Print current estimates before evaluating current epoch.
print_finished(es, scaling)	Display final message after successful convergence on optimum parameters.
print_status_eval(crashed)	Print logged stdout and stderr messages and crashed simulations after evaluating an epoch.
save_setup()	Save current ACCES run's modified script (py) and state (toml).

learn(num_solutions=8, target_sigma=0.1, random_seed=None, multi_objective=<coexist.combiners.Product object>, verbose=4)

Learn the free parameters from the user script that minimise the error variable by trying num_solutions parameter combinations at a time until the overall uncertainty becomes lower than target_sigma.

For multi_objective optimisation, use a coexist.combiner to combine multiple error values into a single one.

save_setup()

Save current ACCES run’s modified script (py) and state (toml).

has_historical(epoch)

Check ACCES still has historical solutions to inject.

inject_historical(es, epoch)

Inject the CMA-ES optimiser with pre-computed (historical) results. The solutions must have a Gaussian distribution in each problem dimension - though the standard deviation can vary for each of them. Ideally, this should only use historical values that CMA-ES asked for in a previous ACCESS run.

print_before_eval(es, epoch, scaling)

Print current estimates before evaluating current epoch.

print_status_eval(crashed)

Print logged stdout and stderr messages and crashed simulations after evaluating an epoch.

print_after_eval(es, epoch, solutions, scaling, results)

Display parameter combinations evaluated in the current epoch and the corresponding errors found.

print_finished(es, scaling)

Display final message after successful convergence on optimum parameters.

finished(es)

Check if the optimisation run is done and display the best solution found for the target sigma value.

evaluate_solutions(solutions, epoch)

Evaluate the parameter combinations given in solutions for the current epoch in parallel.