physicool.optimization

A module for model calibration and optimization routines.

Module Contents

Classes

PhysiCellBlackBox	A class to run PhysiCell models through Python as a black box.
MultiLevelSweep

Functions

_create_project_command(project_name)	Creates a project command based on the current OS.
clean_outputs()	Removes the files from the output folder and creates it again (make data-cleanup).
clean_tmp_files()	Removes the temp folder if it exists.
compile_project()	Compiles the current project by calling make.
run_sweep(black_box, name, bounds, step)

Attributes

LOG_FILE

physicool.optimization.LOG_FILE = 'debug.log'

physicool.optimization._create_project_command(project_name)

Creates a project command based on the current OS.

Parameters:

project_name (str) – The base name of the PhysiCell executable file.

Returns:

The full command to be called in order to run the executable in the shell, adapted to the current OS.

Return type:

str

physicool.optimization.clean_outputs()

Removes the files from the output folder and creates it again (make data-cleanup).

Return type:

None

physicool.optimization.clean_tmp_files()

Removes the temp folder if it exists.

Return type:

None

physicool.optimization.compile_project()

Compiles the current project by calling make.

Return type:

None

class physicool.optimization.PhysiCellBlackBox

A class to run PhysiCell models through Python as a black box. Models can be run as they are, and it’s possible to run replicates.

Alternatively, users can decide to include a ParamsUpdater object to change values in the XML file before the model is run and/or a OutputProcessor to extract data from the output files and return a given user-defined metric.

Output files can be kept or discarded. If kept, they will be stored inside a new “temp” folder.

updater: Optional[physicool.updaters.ParamsUpdater]

processor: Optional[physicool.processing.OutputProcessor]

project_name: str = 'project'

project_command: str

version: str

__post_init__()

Create the right command to call the PhysiCell project based on the OS.

run(params=None, number_of_replicates=1, keep_files=True)

Runs the black box pipeline.

Parameters:

• params (Optional[Dict[str, float]]) – The new parameter values, to be updated in the XML file by the ParamsUpdater class.

• number_of_replicates (int) – The number of simulation replicates to be run.

• keep_files (bool) – If the output files should be stored in a tmp folder.

Returns:

The output metrics computed by the OutputProcessor class

Return type:

Optional[np.ndarray]

physicool.optimization.run_sweep(black_box, name, bounds, step)

Parameters:

• black_box (PhysiCellBlackBox) –

• name (str) –

• bounds (Tuple[float, float]) –

• step (float) –

Return type:

numpy.ndarray

class physicool.optimization.MultiLevelSweep

black_box: PhysiCellBlackBox

target_data: numpy.ndarray

n_levels: int

points_dir: int

percentage_dir: float

parameters: List[str]

error_estimator: physicool.processing.ErrorQuantification

plotter: physicool.plotting.SweeperPlot

results: numpy.ndarray

current_level: int

current_opt_point: Tuple[float, float]

param_bounds: List[Tuple[Union[None, float], Union[None, float]]]

__post_init__()

Sets up everything needed for the sweeper.

Return type:

None

set_param_bounds(param1_bounds=None, param2_bounds=None)

Defines the parameter bounds to be considered when creating a parameter space.

Parameters:

• param1_bounds (Optional[Tuple[Union[None, float], Union[None, float]]]) –

• param2_bounds (Optional[Tuple[Union[None, float], Union[None, float]]]) –

Return type:

None

get_parameter_range(factor, idx)

Returns the parameter values to be tested based on the current level and bounds.

Parameters:

• factor (float) –

• idx (int) –

Return type:

numpy.ndarray

get_parameter_space()

Returns the parameter values to be tested at the current level.

get_optimal_idx()

Returns the indexes for the smallest error in the current level.

Return type:

Tuple[int, int]

compute_objective(x, y)

Runs the black box for each cell of the parameter space defined by x and y. Also chooses the best optimal point found in the parameter space.

Parameters:

• x (numpy.ndarray) –

• y (numpy.ndarray) –

Return type:

None

run_level()

Run a single level of the multilevel sweep.

Return type:

None

run_sweep(initial_point)

Runs all sweep levels from an initial value and returns the best values found.

Parameters:

initial_point (Tuple[float, float]) –

Return type:

Tuple[float, float]