Parameter identification

CVS0DParamID orchestrates calibration of a 0D CVS model against observation data, across the genetic-algorithm, CMA-ES, Bayesian, and sp_minimize optimisers, plus MCMC sampling.

param_id.paramID.CVS0DParamID

CVS0DParamID(
    model_path,
    model_type,
    param_id_method,
    mcmc_instead=False,
    file_name_prefix="no_name",
    params_for_id_path=None,
    param_id_obs_path=None,
    sim_time=2.0,
    pre_time=20.0,
    dt=0.01,
    solver_info=None,
    mcmc_options=None,
    optimiser_options=None,
    do_ad=False,
    DEBUG=False,
    param_id_output_dir=None,
    resources_dir=None,
    one_rank=False,
    operation_funcs_external_path=None,
    cost_funcs_external_path=None,
)

Parameter identification (calibration) for a 0D CVS model.

This is the main user-facing entry point for calibration. It wraps an inner optimisation engine (OpencorParamID, or OpencorMCMC when mcmc_instead=True) and coordinates loading observation data, selecting parameters, running the optimiser, and writing/plotting results. It is MPI-aware: rank 0 handles all file I/O and output directory creation.

Construct it either directly, or from a config dict with init_from_dict. A typical flow is::

pid = CVS0DParamID.init_from_dict(inp)
pid.set_ground_truth_data(obs_data_dict)
pid.set_params_for_id(params_for_id_dict)
pid.set_param_id_method("genetic_algorithm")
pid.run()
pid.simulate_with_best_param_vals()
pid.plot_outputs()

Parameters:

Name	Description	Default
`model_path`	Path to the generated model file (CellML/Python/CasADi).	required
`model_type`	One of `'cellml_only'`, `'python'`, `'casadi_python'`.	required
`param_id_method`	Optimiser to use, e.g. `'genetic_algorithm'`, `'CMA-ES'`, `'bayesian'`, `'sp_minimize'`.	required
`mcmc_instead`	If True, build an MCMC sampler instead of an optimiser.	`False`
`file_name_prefix`	Model name prefix; ties together the resource files and names the output case directory.	`'no_name'`
`params_for_id_path`	Optional path to a `{prefix}_params_for_id.csv`. Alternatively call `set_params_for_id`.	`None`
`param_id_obs_path`	Optional path to an `obs_data.json`. Alternatively call `set_ground_truth_data`.	`None`
`sim_time`	Logged simulation duration (s).	`2.0`
`pre_time`	Unlogged steady-state spin-up duration (s).	`20.0`
`dt`	Output sampling step (s); must be <= every dt in the obs data.	`0.01`
`solver_info`	Solver config dict (defaults to `{"solver": "CVODE_myokit"}`).	`None`
`mcmc_options`	Options dict for MCMC (used when `mcmc_instead=True`).	`None`
`optimiser_options`	Options dict for the optimiser (e.g. `cost_convergence`, `max_patience`, `num_calls_to_function`, `cost_type`). Sensible defaults are used if omitted.	`None`
`do_ad`	Enable automatic differentiation (CasADi backend).	`False`
`DEBUG`	Enable debug behaviour and the debug optimiser options.	`False`
`param_id_output_dir`	Root directory for results; defaults to `param_id_output/` in the repo.	`None`
`resources_dir`	Directory holding input resources; defaults to `resources/` in the repo.	`None`
`one_rank`	If True, skip the MPI barrier (single-rank usage).	`False`

Attributes:

Name	Type	Description
`output_dir`		Directory (under `param_id_output_dir`) where results and plots for this case are written (rank 0 only).

init_from_dict `classmethod`

init_from_dict(inp_data_dict)

Build a CVS0DParamID from a configuration dict.

Only the keys relevant to the constructor are consumed. file_prefix is accepted as an alias for file_name_prefix.

Parameters:

Name	Type	Description	Default
`inp_data_dict`		Config dict, e.g. as returned by `get_default_inp_data_dict` and then mutated in code.	required

Returns:

Name	Type	Description
`CVS0DParamID`		A configured instance (observation data and parameters
		still need to be set unless their paths were in the dict).

init_from_all_dicts `classmethod`

init_from_all_dicts(
    inp_data_dict, obs_data_dict, params_for_id_dict
)

Build a fully configured CVS0DParamID in one call.

Convenience constructor that calls init_from_dict then sets the ground-truth data and the parameters to identify.

Parameters:

Name	Description	Default
`inp_data_dict`	Configuration dict (see `init_from_dict`).	required
`obs_data_dict`	Observation data dict (see `ObsDataCreator`).	required
`params_for_id_dict`	List of parameter entries to calibrate (see `set_params_for_id`).	required

Returns:

Name	Type	Description
`CVS0DParamID`		A ready-to-run instance.

set_ground_truth_data

set_ground_truth_data(obs_data_dict)

Set the observation (ground-truth) data to calibrate against.

Parses the obs-data structure into the internal ground-truth dataframe, protocol info, observation info and prediction info.

Parameters:

Name	Type	Description	Default
`obs_data_dict`		Observation data dict, e.g. built with `ObsDataCreator` or loaded from an `obs_data.json` file.	required

set_params_for_id

set_params_for_id(params_for_id_dict)

Set which parameters to identify and their bounds.

Parameters:

Name	Type	Description	Default
`params_for_id_dict`		List of entries of the form `{vessel_name, param_name, min, max, name_for_plotting}` (the in-memory equivalent of `{prefix}_params_for_id.csv`). `vessel_name` may be a single name or a list of names to share one calibrated parameter across many vessels.	required

set_param_id_method

set_param_id_method(param_id_method)

Change the optimiser method.

Parameters:

Name	Type	Description	Default
`param_id_method`		e.g. `'genetic_algorithm'`, `'CMA-ES'`, `'bayesian'`, `'sp_minimize'`.	required

set_optimiser_options

set_optimiser_options(optimiser_options)

Set/update the optimiser options dict.

Parameters:

Name	Type	Description	Default
`optimiser_options`		e.g. `cost_convergence`, `max_patience`, `num_calls_to_function`, `cost_type`.	required

set_bayesian_parameters

set_bayesian_parameters(
    n_calls,
    n_initial_points,
    acq_func,
    random_state,
    acq_func_kwargs={},
)

Configure the Bayesian optimiser.

Parameters:

Name	Description	Default
`n_calls`	Total number of objective evaluations.	required
`n_initial_points`	Number of random initial points before fitting.	required
`acq_func`	Acquisition function name (e.g. `'EI'`, `'LCB'`).	required
`random_state`	Seed for reproducibility.	required
`acq_func_kwargs`	Extra keyword args for the acquisition function.	`{}`

add_user_operation_func

add_user_operation_func(func)

Register a custom feature-extraction function.

The function can then be referenced by name in a data item's operation (its operands map to the function args). Set func.series_to_constant = True for series->scalar features so that auto-plotting works.

Parameters:

Name	Type	Description	Default
`func`		The Python callable to register.	required

add_user_cost_func

add_user_cost_func(func)

Register a custom cost function (referenced via cost_type).

update_param_range

update_param_range(
    params_to_update_list_of_lists, mins, maxs
)

Update the min/max bounds of a subset of parameters after construction.

Parameters:

Name	Description	Default
`params_to_update_list_of_lists`	List of parameter-name groups to update; each must match an existing entry in the param-id info.	required
`mins`	New lower bound for each group.	required
`maxs`	New upper bound for each group.	required

remove_params_by_name

remove_params_by_name(param_names_to_remove)

Drop parameters from the identification set by name.

remove_params_by_idx

remove_params_by_idx(param_idxs_to_remove)

Drop parameters from the identification set by index.

run

run()

Run the parameter identification.

Executes the configured optimiser. Ground-truth data and parameters to identify must be set first. On rank 0 the best parameters are written to best_param_vals.npy and per-experiment full-output dumps (all_outputs_with_best_param_vals_exp_*.npz) are written under output_dir.

Raises:

Type	Description
`ValueError`	If observation data or parameters for id are not set.

run_mcmc

run_mcmc()

Run MCMC sampling (requires the instance was built with mcmc_instead=True).

simulate_with_best_param_vals

simulate_with_best_param_vals(
    reset=True, only_one_exp=-1, return_series=False
)

Simulate the model using the best-fit parameters.

Parameters:

Name	Description	Default
`reset`	Reset the simulation state before running.	`True`
`only_one_exp`	If >= 0, only simulate that experiment index; `-1` simulates all experiments.	`-1`
`return_series`	If True, also return the full time-series arrays.	`False`

Returns:

Type	Description
	If `return_series` is False, the observation dict of computed
	feature values. If True, a tuple `(obs_dicts, obs_arrays)` where
	`obs_arrays` holds the time-series for plotting.

plot_outputs

plot_outputs()

Generate and save calibration result plots (under output_dir/plots_param_id).

plot_mcmc

plot_mcmc()

Generate MCMC trace and corner plots from the saved chain (rank 0).

get_mcmc_samples

get_mcmc_samples()

Load and post-process the MCMC chain (burn-in + stuck-walker removal).

Returns:

Name	Type	Description
`tuple`		`(flat_samples, samples, num_params)`, or None if no chain
		has been written.

get_best_param_vals

get_best_param_vals()

Return the best-fit parameter vector (ndarray), or None if not yet run.

set_best_param_vals

set_best_param_vals(best_param_vals)

Manually supply the best-fit parameter vector (e.g. from a previous run).

Parameters:

Name	Type	Description	Default
`best_param_vals`		Array of parameter values, ordered as `get_param_names`.	required

get_param_names

get_param_names()

Return the list of identified parameter names (order matches the param vector).

set_param_names

set_param_names(param_names)

Override the list of parameter names.

get_param_importance

get_param_importance()

Return per-parameter importance scores (computed during sensitivity step).

get_collinearity_idx

get_collinearity_idx()

Return the collinearity index of the identified parameter set.

get_collinearity_idx_pairs

get_collinearity_idx_pairs()

Return pairwise collinearity indices for the identified parameters.

set_output_dir

set_output_dir(path)

Override the directory where results and plots are written (rank 0 only).

close_simulation

close_simulation()

Release the underlying simulation resources.

Parameter identification

param_id.paramID.CVS0DParamID

init_from_dict classmethod

init_from_all_dicts classmethod

set_ground_truth_data

set_params_for_id

set_param_id_method

set_optimiser_options

set_bayesian_parameters

add_user_operation_func

add_user_cost_func

update_param_range

remove_params_by_name

remove_params_by_idx

run

run_mcmc

simulate_with_best_param_vals

plot_outputs

plot_mcmc

get_mcmc_samples

get_best_param_vals

set_best_param_vals

get_param_names

set_param_names

get_param_importance

get_collinearity_idx

get_collinearity_idx_pairs

set_output_dir

close_simulation

init_from_dict `classmethod`

init_from_all_dicts `classmethod`