Model catalog#

pyforestry collects many growth, yield, volume, bark, biomass, and site-index models. The pyforestry.catalog module lets you discover them without already knowing the import path or citation.

from pyforestry import catalog

catalog.find(domain="volume", species="Picea abies")  # volume models for spruce
catalog.search("brandel")                              # by id / author / title
catalog.describe("brandel_1990_volume").source         # citation
catalog.domains()                                      # ['bark', 'biomass', ...]
catalog.regions()                                      # ['norway', 'sweden']

Discovery is driven by each model’s module-level DESCRIPTOR (see pyforestry.base.contracts.FormulaModuleDescriptor and the convenience pyforestry.base.contracts.FormulaDescriptor). The full list of discoverable models is on the Model index page.

API reference#

Discover and search pyforestry’s scientific formula models.

Most formula modules publish a module-level DESCRIPTOR (see pyforestry.base.contracts.FormulaModuleDescriptor) describing the model’s identity, citation, species applicability, and units. This module aggregates those descriptors so a model can be found without already knowing its import path:

>>> from pyforestry import catalog
>>> catalog.find(domain="volume")                 # all volume models
>>> catalog.find(domain="growth", species="pinus")  # best-effort species filter
>>> catalog.search("bark")                         # by id / module / citation
>>> entry = catalog.describe("soderberg_1992_bark")
>>> entry.source.title

Discovery covers pyforestry.base as well as the regions, so region-independent models are findable too:

>>> catalog.find(region="base")                    # Näslund, García, Bitterlich, Näsberg

Discovery currently covers modules that expose a DESCRIPTOR; the set grows as more modules adopt the convention.

class pyforestry.catalog.ModelEntry(component_id: str, module: str, region: str, domain: str, source: SourceReference, species_groups: Mapping[str, frozenset[str]], units: Mapping[str, str], kernel_names: tuple[str, ...], kind: str = 'formula', composes: tuple[str, ...] = ())[source]

Bases: object

A discoverable formula model and its introspection metadata.

composes: tuple[str, ...] = ()
kind: str = 'formula'
pyforestry.catalog.describe(identifier: str) → ModelEntry[source]

Return the model matching identifier (component id or module path).

Falls back to a unique case-insensitive substring match on the component id.

Raises:

KeyError – if no model, or more than one, matches identifier.

pyforestry.catalog.discovery_errors() → dict[str, BaseException][source]

Return the modules the last discovery pass could not import.

Empty when everything imported. A non-empty result means the catalog is incomplete and says exactly which modules are missing and why – which is what “this model does not exist” used to look like.

pyforestry.catalog.domains() → list[str][source]

Return the sorted set of model domains (e.g. volume, mortality).

pyforestry.catalog.find(*, region: str | None = None, domain: str | None = None, species: str | None = None, units: str | None = None, kind: str | None = None) → list[ModelEntry][source]

Return models matching every supplied filter (case-insensitive).

Parameters:

  • region – Region name, e.g. "sweden".

  • domain – Domain name, e.g. "volume". Returns both formula kernels and composed models for that domain unless kind is also given.

  • species – Substring matched against each model’s species identifiers. Best-effort, since identifiers are stored as TreeName strings.

  • units – Substring matched against the model’s unit names or values.

  • kind – "formula" (equation kernels) or "model" (composed, runnable model adapters).

Returns:

Matching ModelEntry objects, ordered by region/domain/id.

pyforestry.catalog.list_models() → list[ModelEntry][source]

Return every discoverable model entry.

pyforestry.catalog.refresh() → None[source]

Clear the discovery cache (e.g. after importing new model modules).

pyforestry.catalog.regions() → list[str][source]

Return the sorted set of regions that publish discoverable models.

pyforestry.catalog.search(query: str) → list[ModelEntry][source]

Return models whose id, module, domain, or citation contains query.