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, autobin, stat_indices=None, n_init=50, n_iter=10, iter_steps=5, focus=None, 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 the parameters to optimize. The order must correspond to param_names.

• lower (ndarray) – Lower bounds for the parameters (same shape as start_params).

• upper (ndarray) – Upper bounds for the parameters (same shape as start_params).

• rhobeg (float) – Initial trust-region radius for PYBOBYQA; controls the initial step size in parameter space.

• rhoend (float) – Final (minimum) trust-region radius for PYBOBYQA; smaller values typically yield more accurate but slower optimization.

• param_names (list[str]) – Names of the parameters to optimize (order matches start_params, lower, and upper).

• methods_to_evaluate (Sequence[Callable[[...], Any]]) – Sequence of Inventory methods that compute the summary statistics to be matched (e.g. Inventory.get_CI_HS_distribution()). Each method is called with the inventory (and optional keyword arguments from autobin).

• autobin (Sequence[property | ndarray]) – For each method in methods_to_evaluate, either a property/callable of Inventory used to auto-generate histogram bins from the reference inventory (e.g. Inventory.CI_HS), or a 1D numpy.ndarray of bin edges to use directly. If None is given for a position, the corresponding method is called without extra keyword arguments.

• stat_indices (list[slice | list[int]] | None) – Optional list specifying, for each statistic, which indices (slice or list of ints) of the returned array to include in the likelihood. Use None to include all entries.

• n_init (int) – Number of simulation steps to run before collecting statistics in each objective-function evaluation.

• n_iter (int) – Number of replicate iterations (batches) used to estimate mean and standard deviation of each statistic.

• iter_steps (int) – Number of simulation steps between successive statistic evaluations within an objective-function call.

• focus (str | None) – Optional focus filter applied when computing statistics. If not None, only a subset of trees is used when evaluating the summary statistics, using the same semantics as Inventory.apply_focus() (e.g. "rep", "rec", "sap", "dead").

• reference_inventory (Inventory | None) – Optional reference inventory to use for computing the target statistics. If None, the model’s reference_inventory is used.

• maxfun (int | None) – Maximum number of objective-function evaluations allowed for PYBOBYQA. If None, the library default is used.

• verbose (bool) – If True, print intermediate diagnostics such as simulated means, standard deviations, and log-likelihood values.

• objfun_has_noise (bool) – Whether the objective function is noisy; passed through directly to pybobyqa.solve().

Returns:

The result object returned by pybobyqa.solve(), containing the optimal parameters and solver diagnostics.

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, focus=None, 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, focus=None, initial_steps=None, figsize=(24, 12))

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

ToDo: refactor

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.

• initial_steps (int | None) – Steps to be run before the plotting starts

• figsize (tuple) – 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.