spatiocoexistence.model package

class spatiocoexistence.model.Model

Bases: object

This is the individual-based model class. This class is used to create, run, analyse and optimize models.

No-index:

Initialize the model

Parameters:

• parameters – Parameters to configure the model. Either they are supplied via a file or dictionary. Otherwise they will be set to default values.

• initial_inventory – Initial inventory data or path to file containing it.

• reference_inventory – Reference inventory to compare the simulated inventory to. For optimization and analysis purposes.

• threads – The number of CPU-threads to be used to run the model.

__init__(parameters=None, initial_inventory=None, reference_inventory=None, threads=1)

Initialize the model

Parameters:

• parameters (Path | dict[str, Any] | None) – Parameters to configure the model. Either they are supplied via a file or dictionary. Otherwise they will be set to default values.

• initial_inventory (ndarray | Path | Inventory | None) – Initial inventory data or path to file containing it.

• reference_inventory (ndarray | Path | None) – Reference inventory to compare the simulated inventory to. For optimization and analysis purposes.

• threads (int) – The number of CPU-threads to be used to run the model.

growth()

Apply growth process to the current inventory, updating dbh values in place.

Return type:

ndarray

property inventory: Inventory

Read-only access to the current inventory.

mortality()

Apply mortality process to the current inventory and return indices of dead individuals. Dead individuals are removed from the inventory.

Returns:

Array of indices that were dead (before removal).

Return type:

Inventory

optimize_parameters(start_params, lower, upper, rhobeg, rhoend, param_names, methods_to_evaluate, stat_indices=None, n_init=50, n_iter=10, iter_steps=5, reference_inventory=None, maxfun=None, verbose=False, objfun_has_noise=True)

The optimizer uses the PYBOBYQA algorithm to fit arbitrary statistics to the model parameters using the log likelihood function.

Parameters:

• start_params (ndarray) – Initial guess for parameters.

• lower (ndarray) – Lower bounds for parameters.

• upper (ndarray) – Upper bounds for parameters.

• param_names (list[str]) – Names of parameters to optimize (order matches start_params).

• methods_to_evaluate (Sequence[tuple[Callable[[...], Any], Callable[[...], Any] | property]]) – Functions to calculate the statistics that shall be matched. Each tuple: (statistic function, kwargs for function).

• stat_indices (list[slice | list[int]] | None) – For each stat_func, which indices of the values to use (default: use all).

• n_init (int) – Initial run steps.

• n_iter (int) – Number of iterations for averaging.

• iter_steps (int) – Steps per iteration.

• maxfun (int | None) – Maximum number of objective evaluations (defaults to a small value for speed).

• verbose (bool) – If True, print intermediate diagnostics.

• objfun_has_noise (bool) – Pass-through to PYBOBYQA’s objfun_has_noise.

Returns:

The result of the PYBOBYQA algorithm

Return type:

Any

property parameters: dict

Access a copy of the current model parameters (backend source of truth).

plot(reference_plot=False, threshold=50, filter=1.0, scale=7.5, figsize=(22, 10))

Plot the current state of the model.

Parameters:

• title – The title of the plot.

• reference_plot (bool) – If True, the reference inventory is plotted.

• threshold (int) – Minimum abundance of conspecifics ToDo.

• filter (float) – Filter out all trees below that size for inventory plot.

recruitment()

Apply recruitment process, add the recruits to the inventory. And return an Inventory of the new recruits.

ToDo test it.

Return type:

Inventory

run_with_plotting(n_steps=1000, plot_interval=50, threshold=50, figsize=(24, 12))

Run the simulation with plotting enabled to see the development of the forest inventory in real time.

ToDo: Extract this function to plotting.

Parameters:

• n_steps (int) – Amount of steps to be simulated.

• plot_interval (int) – The interval at which the inventories shall be plotted.

• threshold (int) – Minimum abundance of conspecifics ToDo.

• figsize – The size of the plot.

step(n_steps)

A simulation step in the model consists mainly of three different processes: mortality, recruitment and growth. One step represents 5 years in real time.

Parameters:

n_steps (int) – The amount of model steps to be simulated.

update_parameters(parameters)

Update the model parameters from a dictionary (merge with existing). Only update keys that already exist in the model parameters. :param parameters: Dictionary with the new parameter configurations.