fresh_cbm

Exact libcbm stand-state cache client.

class fresh_cbm.StateCache(root: Path, manifest: dict[str, Any], index: DataFrame)[source]

Bases: object

A loaded exact stand-state table.

Parameters:

  • root (pathlib.Path) – Cache directory containing manifest.json, index.parquet, and values/.

  • manifest (dict) – Parsed manifest.

  • index (pandas.DataFrame) – State index in row order.

classmethod load(root: str | Path, *, validate: bool = True) → StateCache[source]

Load a cache directory.

Parameters:

  • root (path-like) – Cache directory.

  • validate (bool, optional) – Check the index, file set, and array shapes. Defaults to True.

Returns:

StateCache – The loaded cache.

validate() → None[source]

Check the index, file set, offsets, and array shapes.

Raises:

ValueError – When the cache is incomplete or inconsistent with its manifest.

verify_checksums(path: str | Path | None = None) → None[source]

Verify files against a SHA256SUMS manifest.

Parameters:

path (path-like or None, optional) – Checksum file. Defaults to SHA256SUMS in the cache root.

Raises:

ValueError – When a file is missing or a digest does not match.

property chain_family: ChainFamily | None

Return the declared chain family, if the manifest has one.

Returns:

ChainFamily or None – The family record, or None for a legacy manifest without one.

property accounts: tuple[str, ...]

Return the cached account names.

property years: int

Return the stored horizon length in years.

array(chain_offset: int = -1) → ndarray[source]

Return the memmapped values for one chain offset.

Parameters:

chain_offset (int, optional) – Single CC event offset; -1 is untreated.

Returns:

numpy.ndarray – The cached values with shape (states, years + 1, accounts).

lookup_state(state_id: int, chain_offset: int = -1) → ndarray[source]

Return one state’s (years + 1, accounts) array.

Parameters:

  • state_id (int) – Row in index.parquet.

  • chain_offset (int, optional) – Single CC event offset; -1 is untreated.

Returns:

numpy.ndarray – The cached accounts.

lookup(track_id: int, age: int, chain_offset: int = -1) → ndarray[source]

Return one state’s (years + 1, accounts) array.

Parameters:

  • track_id (int) – Dataset track id.

  • age (int) – Initial stand age.

  • chain_offset (int, optional) – Single CC event offset; -1 is untreated.

Returns:

numpy.ndarray – The cached accounts.

account(track_id: int, age: int, chain_offset: int, account: str) → ndarray[source]

Return one account series for a state.

Parameters:

  • track_id (int) – Dataset track id.

  • age (int) – Initial stand age.

  • chain_offset (int) – Single CC event offset; -1 is untreated.

  • account (str) – Account name.

Returns:

numpy.ndarray – The account values over all stored years.