Core API Reference

The core module implements the Ecopath mass-balance solver, Ecosim dynamic simulation, and supporting subsystems (stanzas, forcing, optimization).

Ecopath (Mass-Balance)

pypath.core.ecopath

Ecopath mass-balance model implementation.

This module contains the core Rpath class and the rpath() function that performs mass-balance calculations for food web models.

Rpath dataclass

Balanced Ecopath model.

This class represents a mass-balanced food web model created by the rpath() function.

Attributes:

Name	Type	Description
NUM_GROUPS	int	Total number of groups (living + dead + gears)
NUM_LIVING	int	Number of living groups (consumers + producers)
NUM_DEAD	int	Number of detritus groups
NUM_GEARS	int	Number of fishing fleets
Group	ndarray	Names of all groups
type	ndarray	Type codes (0=consumer, 1=producer, 2=detritus, 3=fleet)
TL	ndarray	Trophic levels
Biomass	ndarray	Biomass values (t/km²)
PB	ndarray	Production/Biomass ratios (1/year)
QB	ndarray	Consumption/Biomass ratios (1/year)
EE	ndarray	Ecotrophic efficiencies
GE	ndarray	Gross efficiencies (P/Q)
M0	ndarray	Other mortality rates (M0 = PB * (1 - EE))
BA	ndarray	Biomass accumulation rates
Unassim	ndarray	Unassimilated consumption fractions
DC	ndarray	Diet composition matrix
DetFate	ndarray	Detritus fate matrix
Landings	ndarray	Landings by group and fleet
Discards	ndarray	Discards by group and fleet
eco_name	str	Ecosystem name
eco_area	float	Ecosystem area (km²)

Source code in pypath/core/ecopath.py

@dataclass
class Rpath:
    """Balanced Ecopath model.

    This class represents a mass-balanced food web model created by the
    rpath() function.

    Attributes
    ----------
    NUM_GROUPS : int
        Total number of groups (living + dead + gears)
    NUM_LIVING : int
        Number of living groups (consumers + producers)
    NUM_DEAD : int
        Number of detritus groups
    NUM_GEARS : int
        Number of fishing fleets
    Group : np.ndarray
        Names of all groups
    type : np.ndarray
        Type codes (0=consumer, 1=producer, 2=detritus, 3=fleet)
    TL : np.ndarray
        Trophic levels
    Biomass : np.ndarray
        Biomass values (t/km²)
    PB : np.ndarray
        Production/Biomass ratios (1/year)
    QB : np.ndarray
        Consumption/Biomass ratios (1/year)
    EE : np.ndarray
        Ecotrophic efficiencies
    GE : np.ndarray
        Gross efficiencies (P/Q)
    M0 : np.ndarray
        Other mortality rates (M0 = PB * (1 - EE))
    BA : np.ndarray
        Biomass accumulation rates
    Unassim : np.ndarray
        Unassimilated consumption fractions
    DC : np.ndarray
        Diet composition matrix
    DetFate : np.ndarray
        Detritus fate matrix
    Landings : np.ndarray
        Landings by group and fleet
    Discards : np.ndarray
        Discards by group and fleet
    eco_name : str
        Ecosystem name
    eco_area : float
        Ecosystem area (km²)
    """

    NUM_GROUPS: int
    NUM_LIVING: int
    NUM_DEAD: int
    NUM_GEARS: int
    Group: np.ndarray
    type: np.ndarray
    TL: np.ndarray
    Biomass: np.ndarray
    PB: np.ndarray
    QB: np.ndarray
    EE: np.ndarray
    GE: np.ndarray
    M0: np.ndarray
    BA: np.ndarray
    Unassim: np.ndarray
    DC: np.ndarray
    DetFate: np.ndarray
    Landings: np.ndarray
    Discards: np.ndarray
    eco_name: str = ""
    eco_area: float = 1.0

    def __repr__(self) -> str:
        max_ee = np.nanmax(self.EE[: self.NUM_LIVING + self.NUM_DEAD])
        if max_ee > 1:
            status = "Unbalanced!"
            unbalanced = self.Group[np.where(self.EE > 1)[0]]
            status_detail = f"\nGroups with EE > 1: {list(unbalanced)}"
        else:
            status = "Balanced"
            status_detail = ""

        return (
            f"Rpath model: {self.eco_name}\n"
            f"Model Area: {self.eco_area}\n"
            f"     Status: {status}{status_detail}\n"
            f"     Groups: {self.NUM_GROUPS} "
            f"(living={self.NUM_LIVING}, dead={self.NUM_DEAD}, gears={self.NUM_GEARS})"
        )

    def summary(self) -> pd.DataFrame:
        """Get summary table of model results.

        Returns
        -------
        pd.DataFrame
            Summary with Group, Type, TL, Biomass, PB, QB, EE, GE, and Removals.
        """
        removals = np.nansum(self.Landings, axis=1) + np.nansum(self.Discards, axis=1)

        return pd.DataFrame(
            {
                "Group": self.Group,
                "Type": self.type,
                "TL": self.TL,
                "Biomass": self.Biomass,
                "PB": self.PB,
                "QB": self.QB,
                "EE": self.EE,
                "GE": self.GE,
                "Removals": removals,
            }
        )

summary

summary() -> pd.DataFrame

Get summary table of model results.

Returns:

Type	Description
DataFrame	Summary with Group, Type, TL, Biomass, PB, QB, EE, GE, and Removals.

Source code in pypath/core/ecopath.py

def summary(self) -> pd.DataFrame:
    """Get summary table of model results.

    Returns
    -------
    pd.DataFrame
        Summary with Group, Type, TL, Biomass, PB, QB, EE, GE, and Removals.
    """
    removals = np.nansum(self.Landings, axis=1) + np.nansum(self.Discards, axis=1)

    return pd.DataFrame(
        {
            "Group": self.Group,
            "Type": self.type,
            "TL": self.TL,
            "Biomass": self.Biomass,
            "PB": self.PB,
            "QB": self.QB,
            "EE": self.EE,
            "GE": self.GE,
            "Removals": removals,
        }
    )

rpath

rpath(rpath_params: RpathParams, eco_name: str = '', eco_area: float = 1.0, debug: bool = False) -> Union[Rpath, Tuple[Rpath, Dict[str, object]]]

Balance an Ecopath model.

Performs initial mass balance using an RpathParams object. Preserves the original group order from the input parameters.

The mass balance equation solved is:

Production = Predation Mortality + Fishing Mortality + Other Mortality + Biomass Accumulation + Net Migration

Or equivalently: B_i * PB_i * EE_i = Σ(B_j * QB_j * DC_ji) + Y_i + BA_i

Parameters:

Name	Type	Description	Default
rpath_params	RpathParams	R object containing the parameters needed to create an Rpath model.	required
eco_name	str	Name of the ecosystem (stored as attribute).	''
eco_area	float	Area of the ecosystem (stored as attribute).	1.0
debug	bool	If False (default), return only the balanced Rpath object. If True, return a tuple (rpath_obj, diagnostics) where diagnostics is a dict containing intermediate matrices (A, b_vec, x, diet_values, nodetrdiet, living_idx, no_b, no_ee).	False

Returns:

Type	Description
Rpath or tuple[Rpath, dict]	Balanced model that can be supplied to rsim_scenario(). When debug=True, returns (Rpath, diagnostics).

Raises:

Type	Description
ValueError	If the model cannot be balanced due to missing parameters.

Notes

When debug=True the function returns a tuple (rpath_obj, diagnostics) where diagnostics contains intermediate matrices useful for debugging (A, b_vec, x, diet_values, nodetrdiet, living_idx, no_b, no_ee).

Examples:

>>> params = create_rpath_params(...)
>>> # Fill in parameter values
>>> model = rpath(params, eco_name='Georges Bank')
>>> print(model)

Source code in pypath/core/ecopath.py

def rpath(
    rpath_params: RpathParams,
    eco_name: str = "",
    eco_area: float = 1.0,
    debug: bool = False,
) -> Union[Rpath, Tuple[Rpath, Dict[str, object]]]:
    """Balance an Ecopath model.

    Performs initial mass balance using an RpathParams object.
    Preserves the original group order from the input parameters.

    The mass balance equation solved is:

    Production = Predation Mortality + Fishing Mortality +
                 Other Mortality + Biomass Accumulation + Net Migration

    Or equivalently:
    B_i * PB_i * EE_i = Σ(B_j * QB_j * DC_ji) + Y_i + BA_i

    Parameters
    ----------
    rpath_params : RpathParams
        R object containing the parameters needed to create an Rpath model.
    eco_name : str, optional
        Name of the ecosystem (stored as attribute).
    eco_area : float, optional
        Area of the ecosystem (stored as attribute).
    debug : bool, optional
        If False (default), return only the balanced Rpath object.
        If True, return a tuple ``(rpath_obj, diagnostics)`` where
        *diagnostics* is a dict containing intermediate matrices
        (A, b_vec, x, diet_values, nodetrdiet, living_idx, no_b, no_ee).

    Returns
    -------
    Rpath or tuple[Rpath, dict]
        Balanced model that can be supplied to rsim_scenario().
        When *debug=True*, returns ``(Rpath, diagnostics)``.

    Raises
    ------
    ValueError
        If the model cannot be balanced due to missing parameters.

    Notes
    -----
    When ``debug=True`` the function returns a tuple
    ``(rpath_obj, diagnostics)`` where ``diagnostics`` contains
    intermediate matrices useful for debugging (A, b_vec, x,
    diet_values, nodetrdiet, living_idx, no_b, no_ee).

    Examples
    --------
    >>> params = create_rpath_params(...)
    >>> # Fill in parameter values
    >>> model = rpath(params, eco_name='Georges Bank')
    >>> print(model)
    """
    # Make a deep copy to avoid modifying original
    model_df = rpath_params.model.copy()
    diet_df = rpath_params.diet.copy()

    # Get dimensions - PRESERVE ORIGINAL ORDER
    ngroups = len(model_df)

    # Create index arrays for each group type (preserving original order)
    types_arr = model_df["Type"].values.astype(float)
    living_idx = np.where(types_arr < 2)[0]  # Indices of living groups
    dead_idx = np.where(types_arr == 2)[0]  # Indices of detritus groups
    fleet_idx = np.where(types_arr == 3)[0]  # Indices of fleet groups

    nliving = len(living_idx)
    ndead = len(dead_idx)
    ngear = len(fleet_idx)

    # Extract arrays from model DataFrame (original order)
    groups = model_df["Group"].values
    types = types_arr
    biomass = model_df["Biomass"].values.astype(float)
    pb = model_df["PB"].values.astype(float)
    qb = model_df["QB"].values.astype(float)
    ee = model_df["EE"].values.astype(float)
    prodcons = model_df["ProdCons"].values.astype(float)
    bioacc = model_df["BioAcc"].values.astype(float)
    unassim = model_df["Unassim"].values.astype(float)

    # Replace NaN with 0 for BioAcc and Unassim
    bioacc = np.where(np.isnan(bioacc), 0.0, bioacc)
    unassim = np.where(np.isnan(unassim), 0.0, unassim)

    # Get diet matrix - columns are predators (living groups only)
    living_group_names = groups[living_idx].tolist()
    diet_cols = [g for g in living_group_names if g in diet_df.columns]

    # Build diet matrix with rows matching original group order
    diet_prey_names = diet_df["Group"].tolist()
    all_group_names = groups.tolist()

    # Create mapping from diet prey names to row indices in diet_df
    prey_name_to_diet_row = {name: i for i, name in enumerate(diet_prey_names)}

    # Build diet matrix (rows = ALL groups + Import, cols = predators in living_idx order)
    # Need ngroups rows (one per group) + 1 row for Import
    n_prey = len(diet_prey_names)  # Number of rows in diet_df (includes Import)
    n_pred = len(diet_cols)
    diet_values = np.zeros(
        (ngroups + 1, n_pred)
    )  # ngroups rows for groups + 1 for Import

    # Map each group to its diet row
    for new_row_idx, group_name in enumerate(all_group_names):
        if group_name in prey_name_to_diet_row:
            old_row_idx = prey_name_to_diet_row[group_name]
            diet_values[new_row_idx, :] = diet_df.loc[
                old_row_idx, diet_cols
            ].values.astype(float)

    # Add Import row at the end if present
    if "Import" in prey_name_to_diet_row:
        import_row_idx = prey_name_to_diet_row["Import"]
        # Import goes at index ngroups (after all groups)
        if n_prey > ngroups:
            diet_values[ngroups, :] = diet_df.loc[
                import_row_idx, diet_cols
            ].values.astype(float)

    diet_values = np.nan_to_num(diet_values, nan=0.0)

    # Adjust diet for mixotrophs (Type between 0 and 1)
    for col_idx, grp_idx in enumerate(living_idx):
        if 0 < types[grp_idx] < 1:
            mix_q = 1 - types[grp_idx]
            diet_values[:, col_idx] *= mix_q

    # Extract diet for living groups only (prey rows are living groups)
    # nodetrdiet[i, j] = fraction of predator j's diet from prey i (both living)
    # Normalize predator diet columns to exclude Import fractions when present
    nodetrdiet = np.zeros((nliving, nliving))
    import_row = (
        diet_values[ngroups, :]
        if diet_values.shape[0] > ngroups
        else np.zeros(diet_values.shape[1])
    )
    # Vectorized: normalize diet by (1 - import_frac) for each predator column
    import_fracs = (
        import_row[:nliving]
        if len(import_row) >= nliving
        else np.pad(import_row, (0, nliving - len(import_row)))
    )
    denoms = np.where(1.0 - import_fracs > 0, 1.0 - import_fracs, 1.0)
    nodetrdiet = diet_values[np.ix_(living_idx, range(nliving))] / denoms[np.newaxis, :]

    # Fill in GE (P/Q), QB, or PB from other inputs
    # Compute GE = PB/QB when QB is present and non-zero, otherwise use prodcons
    ge = np.where((~np.isnan(qb)) & (qb != 0) & (~np.isnan(pb)), pb / qb, prodcons)
    # Replace NaN GE with 0 (safe default) and avoid dividing by zero below
    ge = np.nan_to_num(ge, nan=0.0)
    # Only fill QB where it's missing and we have a non-zero GE
    # Use np.divide with where to avoid divide-by-zero warnings when GE is zero
    safe_pb_over_ge = np.empty_like(pb)
    safe_pb_over_ge[:] = np.nan
    np.divide(pb, ge, out=safe_pb_over_ge, where=(ge != 0))
    qb = np.where(np.isnan(qb) & (ge != 0), safe_pb_over_ge, qb)
    # Fill PB where missing from prodcons * QB
    pb = np.where(np.isnan(pb), prodcons * qb, pb)

    # As a last resort, if both PB and QB are missing for a *living* group, set reasonable defaults
    both_missing = np.isnan(pb) & np.isnan(qb) & (types < 2)
    if np.any(both_missing):
        # Use a small default turnover/consumption rate to allow balancing for living groups
        pb = np.where(both_missing, 1.0, pb)
        qb = np.where(both_missing, 1.0, qb)

    # Remember which biomass, PB and EE values were originally missing (before filling defaults)
    original_no_b = np.isnan(biomass)
    original_pb_missing = np.isnan(model_df["PB"].values.astype(float))
    original_no_ee = np.isnan(model_df["EE"].values.astype(float))
    # Groups where B and EE are known but PB is missing → solve for PB
    original_no_pb = original_pb_missing & ~original_no_b & ~original_no_ee

    # Keep biomass as NaN for living groups when originally missing so the solver treats them
    # as unknowns and solves for biomass when EE is provided (this matches R's behavior).
    # Previously we set a default value (1.0) here which prevented solving for biomass for
    # groups with EE specified but missing biomass (e.g., Megabenthos). Do not fill here.
    # biomass = np.where(np.isnan(biomass) & (types < 2), 1.0, biomass)

    # For fleet groups (type == 3), ensure biomass/PB/QB/EE are zero to match R conventions
    fleet_mask = types == 3
    if np.any(fleet_mask):
        biomass[fleet_mask] = np.where(
            np.isnan(biomass[fleet_mask]), 0.0, biomass[fleet_mask]
        )
        pb[fleet_mask] = np.where(np.isnan(pb[fleet_mask]), 0.0, pb[fleet_mask])
        qb[fleet_mask] = np.where(np.isnan(qb[fleet_mask]), 0.0, qb[fleet_mask])
        ee[fleet_mask] = np.where(np.isnan(ee[fleet_mask]), 0.0, ee[fleet_mask])

    # Get landings and discards matrices
    det_groups = groups[dead_idx].tolist()
    fleet_groups = groups[fleet_idx].tolist()

    # Find landings columns (fleet names)
    landing_cols = fleet_groups
    discard_cols = [f"{f}.disc" for f in fleet_groups]

    landmat = np.zeros((ngroups, ngear))
    discardmat = np.zeros((ngroups, ngear))

    for g_idx, col in enumerate(landing_cols):
        if col in model_df.columns:
            landmat[:, g_idx] = model_df[col].values.astype(float)
    for g_idx, col in enumerate(discard_cols):
        if col in model_df.columns:
            discardmat[:, g_idx] = model_df[col].values.astype(float)

    landmat = np.nan_to_num(landmat, nan=0.0)
    discardmat = np.nan_to_num(discardmat, nan=0.0)

    totcatchmat = landmat + discardmat
    totcatch = np.sum(totcatchmat, axis=1)
    _landings = np.sum(landmat, axis=1)
    _discards = np.sum(discardmat, axis=1)

    # Flag missing parameters (use the ORIGINAL missing-biomass mask)
    no_b = original_no_b
    no_ee = np.isnan(ee)
    logger.debug("original_no_b: %s", original_no_b)
    logger.debug("initial no_ee: %s", no_ee)

    # Iterative solve to handle EE>1 cases by capping EE at 1 and re-solving
    # Start with masks from current state
    it_max = 5
    it = 0
    iterations = []
    while True:
        it += 1
        # Extract living group values for this iteration
        living_biomass = biomass[living_idx]
        living_qb = qb[living_idx]
        living_pb = pb[living_idx]
        living_ee = ee[living_idx]
        living_bioacc = bioacc[living_idx]
        living_catch = totcatch[living_idx]
        # Determine which variables are unknown in this iteration
        living_no_b = np.isnan(living_biomass)
        living_no_ee = np.isnan(living_ee)

        # Build unknown-biomass mask for predators whose B is being solved
        pred_unknown_mask = np.array(
            [
                original_no_b[pred_global] or np.isnan(biomass[pred_global])
                for pred_global in living_idx
            ],
            dtype=bool,
        )

        A, b_vec = _build_balance_system(
            nliving,
            living_idx,
            living_biomass,
            living_pb,
            living_ee,
            living_qb,
            living_catch,
            living_bioacc,
            nodetrdiet,
            original_no_pb,
            pred_unknown_mask,
        )

        # Validate
        if not np.all(np.isfinite(A)) or not np.all(np.isfinite(b_vec)):
            logger.debug("A finite mask: %s", np.isfinite(A))
            logger.debug("A: %s", A)
            logger.debug("b_vec finite mask: %s", np.isfinite(b_vec))
            logger.debug("b_vec: %s", b_vec)
            raise ValueError(
                "Model is missing or invalid parameters - can't be balanced. Use check_rpath_params() to diagnose."
            )

        # Solve linear system
        n = A.shape[0]
        try:
            if n <= 50:
                x = _gauss_solve(A, b_vec)
            else:
                x = np.linalg.solve(A, b_vec)
        except (ValueError, np.linalg.LinAlgError):
            logger.warning("Primary solver failed, falling back to least-squares")
            try:
                x = np.linalg.lstsq(A, b_vec, rcond=1e-6)[0]
            except (ValueError, np.linalg.LinAlgError) as e:
                raise ValueError(
                    "Unable to solve linear system during balancing"
                ) from e

        # Assign solved values back to living groups for this iteration
        for i, idx in enumerate(living_idx):
            logger.debug(
                "idx=%s iter=%s living_no_b=%s living_no_ee=%s x=%s biomass_before=%s",
                idx,
                it,
                living_no_b[i],
                living_no_ee[i],
                x[i],
                biomass[idx],
            )
            if original_no_pb[idx]:
                pb[idx] = x[i]
                logger.debug("Assigned pb[%s] = %s", idx, x[i])
                # Recalculate QB from estimated PB if QB was originally missing
                orig_qb = model_df["QB"].values.astype(float)[idx]
                if np.isnan(orig_qb) and ge[idx] > 0:
                    qb[idx] = pb[idx] / ge[idx]
                    logger.debug("Recalculated qb[%s] = %s from pb/ge", idx, qb[idx])
            elif living_no_ee[i]:
                ee[idx] = x[i]
                logger.debug("Assigned ee[%s] = %s", idx, x[i])
            if living_no_b[i]:
                biomass[idx] = x[i]
                logger.debug(
                    "Assigned biomass[%s] = %s biomass_after=%s",
                    idx,
                    x[i],
                    biomass[idx],
                )

        # Record iteration snapshot for diagnostics
        iterations.append(
            {
                "iter": it,
                "A": A.copy(),
                "b_vec": b_vec.copy(),
                "x": x.copy(),
                "ee": ee.copy(),
                "biomass": biomass.copy(),
            }
        )
        # Check for EE values > 1 for groups that were originally missing EE
        flipped = False
        # Find groups with EE > 1 eligible for flipping: those whose EE and biomass were both originally missing
        over = [
            (i, idx, ee[idx])
            for i, idx in enumerate(living_idx)
            if original_no_ee[idx]
            and original_no_b[idx]
            and not np.isnan(ee[idx])
            and ee[idx] > 1.0
        ]
        if over:
            # Flip only the largest eligible violation to avoid cascade effects
            over.sort(key=lambda t: t[2], reverse=True)
            i, idx, val = over[0]
            logger.debug(
                "ee[%s] = %s > 1.0 (largest eligible), capping to 1 and solving for biomass next iteration",
                idx,
                val,
            )
            ee[idx] = 1.0
            biomass[idx] = np.nan
            flipped = True

        # If no flips or reached iteration limit, break
        if not flipped or it >= it_max:
            break

    # After iterations, compute final A/b_vec once more for diagnostics
    living_biomass = biomass[living_idx]
    living_qb = qb[living_idx]
    living_pb = pb[living_idx]
    living_ee = ee[living_idx]
    pred_unknown_mask = np.array(
        [
            original_no_b[pred_global] or np.isnan(biomass[pred_global])
            for pred_global in living_idx
        ],
        dtype=bool,
    )
    A, b_vec = _build_balance_system(
        nliving,
        living_idx,
        living_biomass,
        living_pb,
        living_ee,
        living_qb,
        living_catch,
        living_bioacc,
        nodetrdiet,
        original_no_pb,
        pred_unknown_mask,
    )

    # Save final solve results in context for debug output
    # (x and b_vec/A are available from the last iteration)
    try:
        if n <= 50:
            x = _gauss_solve(A, b_vec)
        else:
            x = np.linalg.solve(A, b_vec)
    except (ValueError, np.linalg.LinAlgError):
        logger.warning("Final solver failed, falling back to least-squares")
        try:
            x = np.linalg.lstsq(A, b_vec, rcond=1e-6)[0]
        except (ValueError, np.linalg.LinAlgError) as e:
            raise ValueError("Unable to solve linear system during balancing") from e

    # Calculate M0 (other mortality) for living groups (detritus handled after
    # detritus PB/biomass is computed below)
    m0 = np.zeros(ngroups)
    for i, idx in enumerate(living_idx):
        ee_val = ee[idx] if np.isfinite(ee[idx]) else 1.0
        m0[idx] = pb[idx] * (1 - ee_val)

    # Flows to detritus from living groups
    # M0 can be negative if EE > 1, but loss flows should be non-negative
    qb_loss = np.where(np.isnan(qb), 0.0, qb)
    loss = np.zeros(ngroups)
    for idx in living_idx:
        # Only positive M0 contributes to detrital flow
        m0_pos = max(0.0, m0[idx])
        loss[idx] = (m0_pos * biomass[idx]) + (
            biomass[idx] * qb_loss[idx] * unassim[idx]
        )
    # Add discards from fleets
    # For each fleet, sum discards across all living groups
    for f_idx, fleet_global_idx in enumerate(fleet_idx):
        loss[fleet_global_idx] = np.sum(discardmat[living_idx, f_idx])

    # Get detritus fate matrix
    detfate = np.zeros((ngroups, ndead))
    for d_idx, det_name in enumerate(det_groups):
        if det_name in model_df.columns:
            detfate[:, d_idx] = model_df[det_name].values.astype(float)
    detfate = np.nan_to_num(detfate, nan=0.0)

    # Detrital inputs
    det_input = np.zeros(ndead)
    for d_idx, det_idx in enumerate(dead_idx):
        det_input[d_idx] = (
            model_df["DetInput"].values[det_idx]
            if "DetInput" in model_df.columns
            else 0.0
        )
    det_input = np.nan_to_num(det_input, nan=0.0)

    # Stage 1: Inputs from living + gear sources only (not other detritus)
    living_fleet_idx = np.concatenate([living_idx, fleet_idx])
    living_fleet_loss = loss[living_fleet_idx]
    living_fleet_detfate = detfate[living_fleet_idx, :]
    detinputs1 = (
        np.sum(living_fleet_loss[:, np.newaxis] * living_fleet_detfate, axis=0)
        + det_input
    )

    # Detritus consumption by living groups (vectorized)
    # diet_values rows are in original order, columns are in living_idx order
    det_diet = diet_values[dead_idx, :nliving]  # (ndead, nliving)
    bio_qb_living = np.nan_to_num(biomass[living_idx] * qb[living_idx])
    detcons = det_diet @ bio_qb_living  # (ndead,)

    # Stage 2: Route unconsumed detritus through detritus-to-detritus fate matrix
    det_unused = np.maximum(0.0, detinputs1 - detcons)
    detdetfate = detfate[dead_idx, :]  # rows for detritus groups only
    detinputs = detinputs1 + np.sum(det_unused[:, np.newaxis] * detdetfate, axis=0)

    # Detritus EE
    with np.errstate(divide="ignore", invalid="ignore"):
        det_ee = np.where(detinputs > 0, detcons / detinputs, 0.0)
    for d_idx, det_idx in enumerate(dead_idx):
        ee[det_idx] = det_ee[d_idx]

    # Set detritus biomass and PB
    default_det_pb = 0.5
    det_pb = np.zeros(ndead)
    det_b = np.zeros(ndead)
    for d_idx, det_idx in enumerate(dead_idx):
        det_pb_input = pb[det_idx]
        det_b_input = biomass[det_idx]

        # Ensure detinputs is non-negative
        det_in = max(0.0, detinputs[d_idx])

        # Treat PB as missing if original input was missing (avoid placeholder 1.0 from both_missing)
        if np.isnan(det_pb_input) or det_pb_input <= 0 or original_pb_missing[det_idx]:
            det_pb[d_idx] = default_det_pb
        else:
            det_pb[d_idx] = det_pb_input

        # If biomass was originally missing (we filled prior defaults), treat as missing
        if np.isnan(det_b_input) or det_b_input <= 0 or original_no_b[det_idx]:
            det_b[d_idx] = det_in / det_pb[d_idx] if det_pb[d_idx] > 0 else 0
        else:
            det_b[d_idx] = det_b_input

        # Recalculate PB based on actual inputs and biomass
        # PB for detritus = total inputs / biomass (turnover rate)
        if det_b[d_idx] > 0 and det_in > 0:
            det_pb[d_idx] = det_in / det_b[d_idx]
        elif det_b[d_idx] > 0:
            # No inputs calculated, use default or input PB
            det_pb[d_idx] = (
                default_det_pb if np.isnan(det_pb_input) else max(0.01, det_pb_input)
            )

        biomass[det_idx] = det_b[d_idx]
        pb[det_idx] = det_pb[d_idx]

    # Compute M0 for detritus groups now that PB and EE are finalized for detritus
    for d_idx, det_idx in enumerate(dead_idx):
        m0[det_idx] = pb[det_idx] * (1 - ee[det_idx])

    # Trophic level calculations
    # TL = 1 + sum_i(DC_ij * TL_i) for each predator j
    # Build full diet matrix for all groups (living + dead)
    n_bio = nliving + ndead
    bio_idx = np.concatenate(
        [living_idx, dead_idx]
    )  # Indices of living+dead in original order

    full_diet = np.zeros((n_bio, n_bio))

    # Fill in diet values - rows are prey (in bio_idx order), cols are predators (living only)
    full_diet[:, :nliving] = diet_values[bio_idx, :nliving]

    # Normalize to exclude import
    import_row = (
        diet_values[ngroups, :] if diet_values.shape[0] > ngroups else np.zeros(nliving)
    )
    total_diet = np.sum(full_diet[:, :nliving], axis=0)
    import_fracs = (
        import_row[:nliving] if len(import_row) >= nliving else np.zeros(nliving)
    )
    denom = 1.0 - import_fracs
    norm_mask = (total_diet > 0) & (denom > 0) & (import_fracs < 1)
    safe_denom = np.where(norm_mask, denom, 1.0)
    full_diet[:, :nliving] = np.where(
        norm_mask[np.newaxis, :],
        full_diet[:, :nliving] / safe_denom[np.newaxis, :],
        0.0,
    )

    # Set up linear system: (I - DC^T) * TL = 1
    tl_matrix = np.eye(n_bio) - full_diet.T
    b_tl = np.ones(n_bio)

    # Solve TL system robustly
    try:
        n_tl = tl_matrix.shape[0]
        if n_tl <= 50:
            tl_bio = _gauss_solve(tl_matrix, b_tl)
        else:
            tl_bio = np.linalg.solve(tl_matrix, b_tl)
    except (ValueError, np.linalg.LinAlgError):
        logger.warning("TL solve failed, falling back to least-squares")
        tl_bio = np.linalg.lstsq(tl_matrix, b_tl, rcond=1e-6)[0]

    # Map TL back to original order
    tl = np.ones(ngroups)
    for i, idx in enumerate(bio_idx):
        tl[idx] = tl_bio[i]

    # TL for fleets = weighted average of caught groups
    for g_idx, fleet_global_idx in enumerate(fleet_idx):
        geartot = np.sum(landmat[:, g_idx] + discardmat[:, g_idx])
        if geartot > 0:
            caught = (landmat[:, g_idx] + discardmat[:, g_idx]) / geartot
            tl[fleet_global_idx] = 1 + np.sum(caught * tl)

    # Prepare output arrays (in original order)
    biomass_out = biomass.copy()
    pb_out = pb.copy()
    qb_out = qb.copy()
    qb_out[np.isnan(qb_out)] = 0.0
    ee_out = ee.copy()
    ee_out[fleet_idx] = 0.0  # Fleet EE is always 0

    # Calculate GE (gross efficiency), handling zero QB values
    with np.errstate(divide="ignore", invalid="ignore"):
        ge_out = np.where(qb_out > 0, pb_out / qb_out, 0.0)
    ge_out = np.nan_to_num(ge_out, nan=0.0)

    # M0 (other mortality) for living groups, 0 for others
    m0_out = m0.copy()

    # Prepare diet matrix output (rows = groups + import, cols = living predators)
    diet_out = np.zeros((ngroups + 1, nliving))
    diet_out[:ngroups, :] = diet_values[:ngroups, :]
    if diet_values.shape[0] > ngroups:
        diet_out[ngroups, :] = diet_values[ngroups, :]  # Import row

    rpath_obj = Rpath(
        NUM_GROUPS=ngroups,
        NUM_LIVING=nliving,
        NUM_DEAD=ndead,
        NUM_GEARS=ngear,
        Group=groups.astype(str),
        type=types,
        TL=tl,
        Biomass=biomass_out,
        PB=pb_out,
        QB=qb_out,
        EE=ee_out,
        GE=ge_out,
        M0=m0_out,
        BA=bioacc,
        Unassim=unassim,
        DC=diet_out,
        DetFate=detfate,
        Landings=landmat,
        Discards=discardmat,
        eco_name=eco_name,
        eco_area=eco_area,
    )

    if debug:
        diagnostics = {
            "A": A,
            "b_vec": b_vec,
            "x": x,
            "diet_values": diet_values,
            "nodetrdiet": nodetrdiet,
            "living_idx": living_idx,
            "no_b": no_b,
            "no_ee": no_ee,
            "pb": pb,
            "qb": qb,
            "biomass_before": model_df["Biomass"].values.astype(float),
            "biomass_after": biomass.copy(),
            "detinputs": detinputs,
            "detcons": detcons,
            "det_pb": det_pb,
            "det_b": det_b,
            "iterations": iterations,
        }
        return rpath_obj, diagnostics

    return rpath_obj

Parameters

pypath.core.params

Parameter data structures for PyPath.

This module contains the RpathParams class and functions for creating, reading, writing, and validating Ecopath parameter files.

RpathStanzaParams dataclass

Parameters for multi-stanza (age-structured) groups.

Attributes:

Name	Type	Description
n_stanza_groups	int	Number of stanza group sets (e.g., juvenile + adult = 1 set)
stgroups	DataFrame	Stanza group parameters (VBGF_Ksp, VBGF_d, Wmat, etc.)
stindiv	DataFrame	Individual stanza parameters (First, Last, Z, Leading)

Source code in pypath/core/params.py

@dataclass
class RpathStanzaParams:
    """Parameters for multi-stanza (age-structured) groups.

    Attributes
    ----------
    n_stanza_groups : int
        Number of stanza group sets (e.g., juvenile + adult = 1 set)
    stgroups : pd.DataFrame
        Stanza group parameters (VBGF_Ksp, VBGF_d, Wmat, etc.)
    stindiv : pd.DataFrame
        Individual stanza parameters (First, Last, Z, Leading)
    """

    n_stanza_groups: int = 0
    stgroups: Optional[pd.DataFrame] = None
    stindiv: Optional[pd.DataFrame] = None

RpathParams dataclass

Container for Rpath model parameters.

This class holds all parameters needed to create a balanced Ecopath model.

Attributes:

Name	Type	Description
model	DataFrame	Basic parameters for each group including: - Group: Group name - Type: 0=consumer, 1=producer, 2=detritus, 3=fleet - Biomass: Biomass (t/km²) - PB: Production/Biomass ratio (1/year) - QB: Consumption/Biomass ratio (1/year) - EE: Ecotrophic efficiency - ProdCons: Production/Consumption ratio (GE) - BioAcc: Biomass accumulation rate - Unassim: Unassimilated consumption fraction - DetInput: Detrital input (for detritus groups) Plus columns for detritus fate and landings/discards by fleet.
diet	DataFrame	Diet composition matrix where rows are prey (including Import) and columns are predators. Values are fractions (0-1).
stanzas	RpathStanzaParams	Multi-stanza (age-structured) group parameters.
pedigree	DataFrame	Data quality/pedigree information for parameters.
remarks	DataFrame	Comments/remarks for parameter values. Has same structure as model with string values containing remarks for each cell.

Examples:

>>> params = create_rpath_params(
...     groups=['Phyto', 'Zoo', 'Fish', 'Detritus', 'Fleet'],
...     types=[1, 0, 0, 2, 3]
... )
>>> params.model['Biomass'] = [10.0, 5.0, 2.0, 100.0, np.nan]

Source code in pypath/core/params.py

@dataclass
class RpathParams:
    """Container for Rpath model parameters.

    This class holds all parameters needed to create a balanced Ecopath model.

    Attributes
    ----------
    model : pd.DataFrame
        Basic parameters for each group including:
        - Group: Group name
        - Type: 0=consumer, 1=producer, 2=detritus, 3=fleet
        - Biomass: Biomass (t/km²)
        - PB: Production/Biomass ratio (1/year)
        - QB: Consumption/Biomass ratio (1/year)
        - EE: Ecotrophic efficiency
        - ProdCons: Production/Consumption ratio (GE)
        - BioAcc: Biomass accumulation rate
        - Unassim: Unassimilated consumption fraction
        - DetInput: Detrital input (for detritus groups)
        Plus columns for detritus fate and landings/discards by fleet.

    diet : pd.DataFrame
        Diet composition matrix where rows are prey (including Import)
        and columns are predators. Values are fractions (0-1).

    stanzas : RpathStanzaParams
        Multi-stanza (age-structured) group parameters.

    pedigree : pd.DataFrame
        Data quality/pedigree information for parameters.

    remarks : pd.DataFrame
        Comments/remarks for parameter values. Has same structure as model
        with string values containing remarks for each cell.

    Examples
    --------
    >>> params = create_rpath_params(
    ...     groups=['Phyto', 'Zoo', 'Fish', 'Detritus', 'Fleet'],
    ...     types=[1, 0, 0, 2, 3]
    ... )
    >>> params.model['Biomass'] = [10.0, 5.0, 2.0, 100.0, np.nan]
    """

    model: pd.DataFrame
    diet: pd.DataFrame
    stanzas: RpathStanzaParams = field(default_factory=RpathStanzaParams)
    pedigree: Optional[pd.DataFrame] = None
    remarks: Optional[pd.DataFrame] = None
    ecosim: Optional[Dict[str, Any]] = None

    def __repr__(self) -> str:
        n_groups = len(self.model)
        n_living = len(self.model[self.model["Type"] <= 1])
        n_dead = len(self.model[self.model["Type"] == 2])
        n_fleet = len(self.model[self.model["Type"] == 3])
        return (
            f"RpathParams(\n"
            f"  groups={n_groups} (living={n_living}, detritus={n_dead}, fleets={n_fleet})\n"
            f"  stanzas={self.stanzas.n_stanza_groups}\n"
            f")"
        )

get_groups_by_type

get_groups_by_type(groups: List[str], types: List[int]) -> Dict[str, List[str]]

Return dict mapping type names to group lists.

Parameters:

Name	Type	Description	Default
groups	list of str	Names of all groups in the model.	required
types	list of int	Type code for each group (0=consumer, 1=producer, 2=detritus, 3=fleet).	required

Returns:

Type	Description
dict	Dictionary with keys: 'consumers', 'producers', 'detritus', 'fleets', 'living' (types 0 and 1), and 'prey' (types 0, 1, and 2).

Source code in pypath/core/params.py

def get_groups_by_type(groups: List[str], types: List[int]) -> Dict[str, List[str]]:
    """Return dict mapping type names to group lists.

    Parameters
    ----------
    groups : list of str
        Names of all groups in the model.
    types : list of int
        Type code for each group (0=consumer, 1=producer, 2=detritus, 3=fleet).

    Returns
    -------
    dict
        Dictionary with keys: 'consumers', 'producers', 'detritus', 'fleets',
        'living' (types 0 and 1), and 'prey' (types 0, 1, and 2).
    """
    groups = list(groups)
    types = list(types)
    return {
        "consumers": [g for g, t in zip(groups, types) if t == 0],
        "producers": [g for g, t in zip(groups, types) if t == 1],
        "detritus": [g for g, t in zip(groups, types) if t == 2],
        "fleets": [g for g, t in zip(groups, types) if t == 3],
        "living": [g for g, t in zip(groups, types) if t < 2],
        "prey": [g for g, t in zip(groups, types) if t < 3],
    }

create_rpath_params

create_rpath_params(groups: List[str], types: List[int], stgroups: Optional[List[str]] = None) -> RpathParams

Create a shell RpathParams object with empty parameter values.

Creates the basic structure for an Ecopath model that can be filled in with actual parameter values.

Parameters:

Name	Type	Description	Default
groups	list of str	Names of all groups in the model (living, detritus, and fleets).	required
types	list of int	Type code for each group: - 0: Consumer - 1: Primary producer (or value 0-1 for mixotrophs) - 2: Detritus - 3: Fleet/fishery	required
stgroups	list of str	Stanza group assignment for each group. Use None for non-stanza groups. Groups with the same stanza group name will be linked (e.g., juvenile/adult).	None

Returns:

Type	Description
RpathParams	Parameter object with NA values ready to be filled in.

Examples:

>>> params = create_rpath_params(
...     groups=['Phyto', 'Zoo', 'SmallFish', 'LargeFish', 'Detritus', 'Fleet'],
...     types=[1, 0, 0, 0, 2, 3],
...     stgroups=[None, None, 'Fish', 'Fish', None, None]
... )

Source code in pypath/core/params.py

def create_rpath_params(
    groups: List[str], types: List[int], stgroups: Optional[List[str]] = None
) -> RpathParams:
    """Create a shell RpathParams object with empty parameter values.

    Creates the basic structure for an Ecopath model that can be filled
    in with actual parameter values.

    Parameters
    ----------
    groups : list of str
        Names of all groups in the model (living, detritus, and fleets).
    types : list of int
        Type code for each group:
        - 0: Consumer
        - 1: Primary producer (or value 0-1 for mixotrophs)
        - 2: Detritus
        - 3: Fleet/fishery
    stgroups : list of str, optional
        Stanza group assignment for each group. Use None for non-stanza groups.
        Groups with the same stanza group name will be linked (e.g., juvenile/adult).

    Returns
    -------
    RpathParams
        Parameter object with NA values ready to be filled in.

    Examples
    --------
    >>> params = create_rpath_params(
    ...     groups=['Phyto', 'Zoo', 'SmallFish', 'LargeFish', 'Detritus', 'Fleet'],
    ...     types=[1, 0, 0, 0, 2, 3],
    ...     stgroups=[None, None, 'Fish', 'Fish', None, None]
    ... )
    """
    if len(groups) != len(types):
        raise ValueError("groups and types must have the same length")

    n_groups = len(groups)

    # Identify group types
    gbt = get_groups_by_type(groups, types)
    pred_groups = gbt["living"]  # Consumers/producers
    prey_groups = gbt["prey"]  # All except fleets
    det_groups = gbt["detritus"]
    fleet_groups = gbt["fleets"]

    # Create model DataFrame
    model_data = {
        "Group": groups,
        "Type": types,
        "Biomass": [np.nan] * n_groups,
        "PB": [np.nan] * n_groups,
        "QB": [np.nan] * n_groups,
        "EE": [np.nan] * n_groups,
        "ProdCons": [np.nan] * n_groups,
        "BioAcc": [np.nan] * n_groups,
        "Unassim": [np.nan] * n_groups,
        "DetInput": [np.nan] * n_groups,
    }

    # Add detrital fate columns
    for det in det_groups:
        model_data[det] = [np.nan] * n_groups
        # Set DetInput to 0 for detritus groups
        for i, t in enumerate(types):
            if t == 2:
                model_data["DetInput"][i] = 0.0

    # Add landing and discard columns for each fleet
    n_bio = len([t for t in types if t < 3])  # Non-fleet groups
    for fleet in fleet_groups:
        # Landings
        model_data[fleet] = [0.0] * n_bio + [np.nan] * len(fleet_groups)
        # Discards
        model_data[f"{fleet}.disc"] = [0.0] * n_bio + [np.nan] * len(fleet_groups)

    model = pd.DataFrame(model_data)

    # Create diet DataFrame
    diet_data = {"Group": prey_groups + ["Import"]}
    for pred in pred_groups:
        diet_data[pred] = [np.nan] * (len(prey_groups) + 1)
    diet = pd.DataFrame(diet_data)

    # Create stanza parameters if provided
    stanza_params = RpathStanzaParams()
    if stgroups is not None and any(s is not None for s in stgroups):
        # Get unique stanza groups
        unique_stgroups = sorted(set(s for s in stgroups if s is not None))
        n_stanza_groups = len(unique_stgroups)

        # Count stanzas per group
        nstanzas = [sum(1 for s in stgroups if s == sg) for sg in unique_stgroups]

        stgroups_df = pd.DataFrame(
            {
                "StGroupNum": range(1, n_stanza_groups + 1),
                "StanzaGroup": unique_stgroups,
                "nstanzas": nstanzas,
                "VBGF_Ksp": [np.nan] * n_stanza_groups,
                "VBGF_d": [0.66667] * n_stanza_groups,
                "Wmat": [np.nan] * n_stanza_groups,
                "BAB": [0.0] * n_stanza_groups,
                "RecPower": [1.0] * n_stanza_groups,
            }
        )

        # Individual stanza records
        stindiv_records = []
        for i, (g, t, sg) in enumerate(zip(groups, types, stgroups)):
            if sg is not None:
                st_group_num = unique_stgroups.index(sg) + 1
                stindiv_records.append(
                    {
                        "StGroupNum": st_group_num,
                        "StanzaNum": 0,  # Will be assigned later
                        "GroupNum": i + 1,
                        "Group": g,
                        "First": np.nan,
                        "Last": np.nan,
                        "Z": np.nan,
                        "Leading": np.nan,
                    }
                )

        stindiv_df = pd.DataFrame(stindiv_records)

        stanza_params = RpathStanzaParams(
            n_stanza_groups=n_stanza_groups, stgroups=stgroups_df, stindiv=stindiv_df
        )

    # Create pedigree DataFrame
    pedigree_data = {
        "Group": groups,
        "Biomass": [1.0] * n_groups,
        "PB": [1.0] * n_groups,
        "QB": [1.0] * n_groups,
        "Diet": [1.0] * n_groups,
    }
    # Add fleet pedigree columns
    for fleet in fleet_groups:
        pedigree_data[fleet] = [1.0] * n_groups
    pedigree = pd.DataFrame(pedigree_data)

    return RpathParams(model=model, diet=diet, stanzas=stanza_params, pedigree=pedigree)

read_rpath_params

read_rpath_params(model_file: Union[str, Path], diet_file: Union[str, Path], pedigree_file: Optional[Union[str, Path]] = None, stanza_group_file: Optional[Union[str, Path]] = None, stanza_file: Optional[Union[str, Path]] = None) -> RpathParams

Read Rpath parameters from CSV files.

Parameters:

Name	Type	Description	Default
model_file	str or Path	Path to CSV file with model parameters.	required
diet_file	str or Path	Path to CSV file with diet composition matrix.	required
pedigree_file	str or Path	Path to CSV file with pedigree information.	None
stanza_group_file	str or Path	Path to CSV file with stanza group parameters.	None
stanza_file	str or Path	Path to CSV file with individual stanza parameters.	None

Returns:

Type	Description
RpathParams	Parameter object populated from files.

Source code in pypath/core/params.py

def read_rpath_params(
    model_file: Union[str, Path],
    diet_file: Union[str, Path],
    pedigree_file: Optional[Union[str, Path]] = None,
    stanza_group_file: Optional[Union[str, Path]] = None,
    stanza_file: Optional[Union[str, Path]] = None,
) -> RpathParams:
    """Read Rpath parameters from CSV files.

    Parameters
    ----------
    model_file : str or Path
        Path to CSV file with model parameters.
    diet_file : str or Path
        Path to CSV file with diet composition matrix.
    pedigree_file : str or Path, optional
        Path to CSV file with pedigree information.
    stanza_group_file : str or Path, optional
        Path to CSV file with stanza group parameters.
    stanza_file : str or Path, optional
        Path to CSV file with individual stanza parameters.

    Returns
    -------
    RpathParams
        Parameter object populated from files.
    """
    model = pd.read_csv(model_file)
    diet = pd.read_csv(diet_file)

    # Read stanza files if provided
    stanza_params = RpathStanzaParams()
    if stanza_group_file is not None and stanza_file is not None:
        stgroups = pd.read_csv(stanza_group_file)
        stindiv = pd.read_csv(stanza_file)
        stanza_params = RpathStanzaParams(
            n_stanza_groups=len(stgroups), stgroups=stgroups, stindiv=stindiv
        )

    # Read pedigree if provided
    pedigree = None
    if pedigree_file is not None:
        pedigree = pd.read_csv(pedigree_file)
    else:
        # Create default pedigree
        fleet_groups = model[model["Type"] == 3]["Group"].tolist()
        pedigree_data = {
            "Group": model["Group"].tolist(),
            "Biomass": [1.0] * len(model),
            "PB": [1.0] * len(model),
            "QB": [1.0] * len(model),
            "Diet": [1.0] * len(model),
        }
        for fleet in fleet_groups:
            pedigree_data[fleet] = [1.0] * len(model)
        pedigree = pd.DataFrame(pedigree_data)

    return RpathParams(model=model, diet=diet, stanzas=stanza_params, pedigree=pedigree)

write_rpath_params

write_rpath_params(params: RpathParams, eco_name: str, path: Union[str, Path] = '') -> None

Write Rpath parameters to CSV files.

Parameters:

Name	Type	Description	Default
params	RpathParams	Parameter object to write.	required
eco_name	str	Ecosystem name used in file names.	required
path	str or Path	Directory path for output files.	''

Source code in pypath/core/params.py

def write_rpath_params(
    params: RpathParams, eco_name: str, path: Union[str, Path] = ""
) -> None:
    """Write Rpath parameters to CSV files.

    Parameters
    ----------
    params : RpathParams
        Parameter object to write.
    eco_name : str
        Ecosystem name used in file names.
    path : str or Path
        Directory path for output files.
    """
    path = Path(path)

    params.model.to_csv(path / f"{eco_name}_model.csv", index=False)
    params.diet.to_csv(path / f"{eco_name}_diet.csv", index=False)

    if params.pedigree is not None:
        params.pedigree.to_csv(path / f"{eco_name}_pedigree.csv", index=False)

    if params.stanzas.n_stanza_groups > 0:
        params.stanzas.stgroups.to_csv(
            path / f"{eco_name}_stanza_groups.csv", index=False
        )
        params.stanzas.stindiv.to_csv(path / f"{eco_name}_stanzas.csv", index=False)

check_rpath_params

check_rpath_params(params: RpathParams) -> bool

Check Rpath parameter files for consistency.

Validates that parameter files are filled out correctly and data is in the expected locations.

Parameters:

Name	Type	Description	Default
params	RpathParams	Parameter object to validate.	required

Returns:

Type	Description
bool	True if parameters are valid, False otherwise.

Raises:

Type	Description
warn	For each validation issue found.

Source code in pypath/core/params.py

def check_rpath_params(params: RpathParams) -> bool:
    """Check Rpath parameter files for consistency.

    Validates that parameter files are filled out correctly and data
    is in the expected locations.

    Parameters
    ----------
    params : RpathParams
        Parameter object to validate.

    Returns
    -------
    bool
        True if parameters are valid, False otherwise.

    Raises
    ------
    warnings.warn
        For each validation issue found.
    """
    model = params.model
    diet = params.diet

    n_warnings = 0

    # Check that all types are represented
    type_requirements = [
        (0, "consumer"),
        (1, "producer"),
        (2, "detrital group"),
        (3, "fleet"),
    ]
    for type_val, type_name in type_requirements:
        if len(model[model["Type"] == type_val]) == 0:
            warnings.warn(f"Model must contain at least 1 {type_name}")
            n_warnings += 1

    # Check that either Biomass or EE is provided for living groups
    living = model[model["Type"] < 2]
    missing_both = living[living["Biomass"].isna() & living["EE"].isna()]
    if len(missing_both) > 0:
        groups = missing_both["Group"].tolist()
        warnings.warn(f"Groups missing both Biomass and EE: {groups}")
        n_warnings += 1

    # Inform about PB estimation capability
    has_b_ee_no_pb = living[
        ~living["Biomass"].isna() & ~living["EE"].isna() & living["PB"].isna()
    ]
    if len(has_b_ee_no_pb) > 0:
        groups = has_b_ee_no_pb["Group"].tolist()
        logger.info("Groups with B+EE but missing PB (will be estimated): %s", groups)

    # Check that consumers have QB or ProdCons
    consumers = model[model["Type"] < 1]
    missing_qb = consumers[consumers["QB"].isna() & consumers["ProdCons"].isna()]
    if len(missing_qb) > 0:
        groups = missing_qb["Group"].tolist()
        warnings.warn(f"Consumers missing both QB and ProdCons: {groups}")
        n_warnings += 1

    # Check for invalid QB values (negative or sentinel -9999)
    if "QB" in consumers.columns:
        invalid_qb = consumers[
            consumers["QB"].notna()
            & ((consumers["QB"] < 0) | (consumers["QB"] == -9999))
        ]
        if len(invalid_qb) > 0:
            groups = invalid_qb["Group"].tolist()
            warnings.warn(
                f"Consumers with invalid QB values (negative or -9999): {groups}"
            )
            n_warnings += 1

    # Check diet columns sum to ~1 for consumers
    _n_living = len(model[model["Type"] <= 1])
    pred_groups = model[model["Type"] < 2]["Group"].tolist()

    for pred in pred_groups:
        if pred in diet.columns:
            col_sum = diet[pred].sum()
            pred_type = model[model["Group"] == pred]["Type"].values[0]
            expected = 1.0 - pred_type  # Producers have diet = 0
            if not np.isclose(col_sum, expected, atol=0.01) and not np.isnan(col_sum):
                warnings.warn(
                    f"Diet column '{pred}' sums to {col_sum:.3f}, expected ~{expected}"
                )
                n_warnings += 1

    # Check Import row exists
    if "Import" not in diet["Group"].values and "import" not in diet["Group"].values:
        warnings.warn("Diet matrix is missing the Import row")
        n_warnings += 1

    if n_warnings == 0:
        logger.info("Rpath parameter file is functional.")
        return True
    else:
        logger.warning(
            "Rpath parameter file needs attention! (%d warnings)", n_warnings
        )
        return False

Ecosim (Dynamic Simulation)

The Ecosim engine runs time-dynamic food web simulations using foraging arena theory. Key entry points:

• rsim_scenario() — create a scenario from a balanced Ecopath model
• rsim_run() — run the simulation with RK4 or Adams-Bashforth integration

Integration methods

Method	Description
"RK4"	4th-order Runge-Kutta. Stable, self-starting. Good for short runs.
"AB"	Adams-Bashforth 2-step (matches Rpath). Uses 1 month RK4 warmup then AB2: B_{n+1} = B_n + dt/2 * (3*f_n - f_{n-1}). Includes dynamic fast equilibrium for NoIntegrate groups and Rpath-style biomass bounds. Recommended for calibration and comparison with EwE/Rpath.

Consumption formula

The consumption kernel uses the full Rpath foraging arena functional response:

Q = QQbase * PDY * PYY^(HandleSwitch*COUPLED) *
    DD / (DD - 1 + ((1-Hself)*PYY + Hself*HandleSuite)^(HandleSwitch*COUPLED)) *
    VV / (VV - 1 + (1-Sself)*PDY + Sself*PredSuite)

Where PredSuite and HandleSuite are pooled competitor biomass sums across all predator-prey links sharing the same prey or predator.

Foraging time

Predators dynamically adjust foraging time using the Rpath formula:

Ftime_new = 0.1 + 0.9 * Ftime_old * ((1 - FtimeAdj) + FtimeAdj * QBopt / (FoodGain / B))

Capped at 2.0. Groups with FtimeAdj = 0 do not adjust foraging time.

NoIntegrate groups (fast equilibrium)

Groups flagged as NoIntegrate (typically detritus, meiobenthos, and other fast-turnover groups) use instantaneous equilibrium instead of ODE integration when running with the AB method:

biomeq = TotGain / (TotLoss / B)
B_new = 0.5 * biomeq + 0.5 * B_old

This matches Rpath's SORWT=0.5 smoothing.

pypath.core.ecosim

Ecosim dynamic simulation implementation.

This module will contain the core Ecosim simulation engine, including the derivative calculations and integration methods.

RsimParams dataclass

Dynamic simulation parameters.

Contains all parameters needed to run an Ecosim simulation, derived from a balanced Rpath model.

Attributes:

Name	Type	Description
NUM_GROUPS	int	Total number of groups
NUM_LIVING	int	Number of living groups
NUM_DEAD	int	Number of detritus groups
NUM_GEARS	int	Number of fishing fleets
NUM_BIO	int	Number of biomass groups (living + dead)
spname	list	Species/group names with "Outside" as first element
spnum	ndarray	Species numbers (0 to NUM_GROUPS)
B_BaseRef	ndarray	Reference biomass values
MzeroMort	ndarray	Other mortality rate (M0 = PB * (1-EE))
UnassimRespFrac	ndarray	Unassimilated fraction of consumption
ActiveRespFrac	ndarray	Active respiration fraction
FtimeAdj	ndarray	Foraging time adjustment rate
FtimeQBOpt	ndarray	Optimal Q/B for foraging time
PBopt	ndarray	Base production/biomass
NoIntegrate	ndarray	Fast equilibrium flag (0 = fast eq, else normal)

Predator-Prey Link Arrays

PreyFrom : np.ndarray Prey index for each link PreyTo : np.ndarray Predator index for each link QQ : np.ndarray Base consumption rate for each link DD : np.ndarray Handling time parameter VV : np.ndarray Vulnerability parameter HandleSwitch : np.ndarray Prey switching exponent PredPredWeight : np.ndarray Predator density weight PreyPreyWeight : np.ndarray Prey density weight NumPredPreyLinks : int Number of predator-prey links

Fishing Link Arrays

FishFrom : np.ndarray Fished group index FishThrough : np.ndarray Fleet index FishQ : np.ndarray Fishing rate (catch/biomass) FishTo : np.ndarray Destination (0=outside, or detritus) NumFishingLinks : int Number of fishing links

Detritus Link Arrays

DetFrac : np.ndarray Fraction flowing to detritus DetFrom : np.ndarray Source group index DetTo : np.ndarray Detritus destination index NumDetLinks : int Number of detritus links

Source code in pypath/core/ecosim.py

@dataclass
class RsimParams:
    """Dynamic simulation parameters.

    Contains all parameters needed to run an Ecosim simulation,
    derived from a balanced Rpath model.

    Attributes
    ----------
    NUM_GROUPS : int
        Total number of groups
    NUM_LIVING : int
        Number of living groups
    NUM_DEAD : int
        Number of detritus groups
    NUM_GEARS : int
        Number of fishing fleets
    NUM_BIO : int
        Number of biomass groups (living + dead)
    spname : list
        Species/group names with "Outside" as first element
    spnum : np.ndarray
        Species numbers (0 to NUM_GROUPS)
    B_BaseRef : np.ndarray
        Reference biomass values
    MzeroMort : np.ndarray
        Other mortality rate (M0 = PB * (1-EE))
    UnassimRespFrac : np.ndarray
        Unassimilated fraction of consumption
    ActiveRespFrac : np.ndarray
        Active respiration fraction
    FtimeAdj : np.ndarray
        Foraging time adjustment rate
    FtimeQBOpt : np.ndarray
        Optimal Q/B for foraging time
    PBopt : np.ndarray
        Base production/biomass
    NoIntegrate : np.ndarray
        Fast equilibrium flag (0 = fast eq, else normal)

    Predator-Prey Link Arrays
    -------------------------
    PreyFrom : np.ndarray
        Prey index for each link
    PreyTo : np.ndarray
        Predator index for each link
    QQ : np.ndarray
        Base consumption rate for each link
    DD : np.ndarray
        Handling time parameter
    VV : np.ndarray
        Vulnerability parameter
    HandleSwitch : np.ndarray
        Prey switching exponent
    PredPredWeight : np.ndarray
        Predator density weight
    PreyPreyWeight : np.ndarray
        Prey density weight
    NumPredPreyLinks : int
        Number of predator-prey links

    Fishing Link Arrays
    -------------------
    FishFrom : np.ndarray
        Fished group index
    FishThrough : np.ndarray
        Fleet index
    FishQ : np.ndarray
        Fishing rate (catch/biomass)
    FishTo : np.ndarray
        Destination (0=outside, or detritus)
    NumFishingLinks : int
        Number of fishing links

    Detritus Link Arrays
    --------------------
    DetFrac : np.ndarray
        Fraction flowing to detritus
    DetFrom : np.ndarray
        Source group index
    DetTo : np.ndarray
        Detritus destination index
    NumDetLinks : int
        Number of detritus links
    """

    NUM_GROUPS: int
    NUM_LIVING: int
    NUM_DEAD: int
    NUM_GEARS: int
    NUM_BIO: int
    spname: List[str]
    spnum: np.ndarray
    B_BaseRef: np.ndarray
    MzeroMort: np.ndarray
    UnassimRespFrac: np.ndarray
    ActiveRespFrac: np.ndarray
    FtimeAdj: np.ndarray
    FtimeQBOpt: np.ndarray
    PBopt: np.ndarray
    NoIntegrate: np.ndarray
    HandleSelf: np.ndarray
    ScrambleSelf: np.ndarray

    # Predator-prey links
    PreyFrom: np.ndarray
    PreyTo: np.ndarray
    QQ: np.ndarray
    DD: np.ndarray
    VV: np.ndarray
    HandleSwitch: np.ndarray
    PredPredWeight: np.ndarray
    PreyPreyWeight: np.ndarray
    NumPredPreyLinks: int

    # Fishing links
    FishFrom: np.ndarray
    FishThrough: np.ndarray
    FishQ: np.ndarray
    FishTo: np.ndarray
    NumFishingLinks: int

    # Detritus links
    DetFrac: np.ndarray
    DetFrom: np.ndarray
    DetTo: np.ndarray
    NumDetLinks: int

    # Group type information
    # PP_type: 0=consumer, 1=producer, 2=detritus
    PP_type: np.ndarray = None

    # Fleet group indices (0-based) for resolving gear indices from FishThrough.
    # Required when groups are in non-canonical order (e.g. detritus first).
    fleet_idx: np.ndarray = None

    # Integration parameters
    BURN_YEARS: int = -1
    COUPLED: int = 1
    RK4_STEPS: int = 4
    SENSE_LIMIT: Tuple[float, float] = (1e-4, 1e4)
    # Control whether monthly M0 algebraic adjustments are performed during the run
    MONTHLY_M0_ADJUST: bool = True

RsimState dataclass

State variables for Ecosim simulation.

Attributes:

Name	Type	Description
Biomass	ndarray	Current biomass values
N	ndarray	Numbers (for stanza groups)
Ftime	ndarray	Foraging time multiplier

Source code in pypath/core/ecosim.py

@dataclass
class RsimState:
    """State variables for Ecosim simulation.

    Attributes
    ----------
    Biomass : np.ndarray
        Current biomass values
    N : np.ndarray
        Numbers (for stanza groups)
    Ftime : np.ndarray
        Foraging time multiplier
    """

    Biomass: np.ndarray
    N: np.ndarray
    Ftime: np.ndarray
    SpawnBio: Optional[np.ndarray] = None
    StanzaPred: Optional[np.ndarray] = None
    EggsStanza: Optional[np.ndarray] = None
    NageS: Optional[np.ndarray] = None
    WageS: Optional[np.ndarray] = None
    QageS: Optional[np.ndarray] = None

RsimForcing dataclass

Forcing matrices for environmental and biological effects.

All matrices are (n_months x n_groups+1) where first column is "Outside".

Attributes:

Name	Type	Description
ForcedPrey	ndarray	Prey availability multiplier
ForcedMort	ndarray	Mortality multiplier
ForcedRecs	ndarray	Recruitment multiplier
ForcedSearch	ndarray	Search rate multiplier
ForcedActresp	ndarray	Active respiration multiplier
ForcedMigrate	ndarray	Migration rate
ForcedBio	ndarray	Forced biomass values (-1 = not forced)

Source code in pypath/core/ecosim.py

@dataclass
class RsimForcing:
    """Forcing matrices for environmental and biological effects.

    All matrices are (n_months x n_groups+1) where first column is "Outside".

    Attributes
    ----------
    ForcedPrey : np.ndarray
        Prey availability multiplier
    ForcedMort : np.ndarray
        Mortality multiplier
    ForcedRecs : np.ndarray
        Recruitment multiplier
    ForcedSearch : np.ndarray
        Search rate multiplier
    ForcedActresp : np.ndarray
        Active respiration multiplier
    ForcedMigrate : np.ndarray
        Migration rate
    ForcedBio : np.ndarray
        Forced biomass values (-1 = not forced)
    """

    ForcedPrey: np.ndarray
    ForcedMort: np.ndarray
    ForcedRecs: np.ndarray
    ForcedSearch: np.ndarray
    ForcedActresp: np.ndarray
    ForcedMigrate: np.ndarray
    ForcedBio: np.ndarray
    ForcedEffort: Optional[np.ndarray] = None

RsimFishing dataclass

Fishing forcing matrices.

Attributes:

Name	Type	Description
ForcedEffort	ndarray	Monthly effort multiplier (n_months x n_gears+1)
ForcedFRate	ndarray	Annual F rate by species (n_years x n_bio+1)
ForcedCatch	ndarray	Annual forced catch by species (n_years x n_bio+1)

Source code in pypath/core/ecosim.py

@dataclass
class RsimFishing:
    """Fishing forcing matrices.

    Attributes
    ----------
    ForcedEffort : np.ndarray
        Monthly effort multiplier (n_months x n_gears+1)
    ForcedFRate : np.ndarray
        Annual F rate by species (n_years x n_bio+1)
    ForcedCatch : np.ndarray
        Annual forced catch by species (n_years x n_bio+1)
    """

    ForcedEffort: np.ndarray
    ForcedFRate: np.ndarray
    ForcedCatch: np.ndarray

RsimScenario dataclass

Complete Ecosim simulation scenario.

Attributes:

Name	Type	Description
params	RsimParams	Dynamic simulation parameters
start_state	RsimState	Initial state variables
forcing	RsimForcing	Environmental forcing matrices
fishing	RsimFishing	Fishing forcing matrices
stanzas	dict	Multi-stanza parameters (if any)
eco_name	str	Ecosystem name
start_year	int	First year of simulation
ecospace	(EcospaceParams, optional)	Spatial ECOSPACE parameters (if None, runs non-spatial Ecosim)
environmental_drivers	(EnvironmentalDrivers, optional)	Time-varying environmental layers for habitat capacity

Source code in pypath/core/ecosim.py

@dataclass
class RsimScenario:
    """Complete Ecosim simulation scenario.

    Attributes
    ----------
    params : RsimParams
        Dynamic simulation parameters
    start_state : RsimState
        Initial state variables
    forcing : RsimForcing
        Environmental forcing matrices
    fishing : RsimFishing
        Fishing forcing matrices
    stanzas : dict
        Multi-stanza parameters (if any)
    eco_name : str
        Ecosystem name
    start_year : int
        First year of simulation
    ecospace : EcospaceParams, optional
        Spatial ECOSPACE parameters (if None, runs non-spatial Ecosim)
    environmental_drivers : EnvironmentalDrivers, optional
        Time-varying environmental layers for habitat capacity
    """

    params: RsimParams
    start_state: RsimState
    forcing: RsimForcing
    fishing: RsimFishing
    stanzas: Optional[RsimStanzas] = None
    # Optional stanza biomass time series (filled during run if stanzas present)
    stanza_biomass: Optional[np.ndarray] = None
    eco_name: str = ""
    start_year: int = 1
    ecospace: Optional["EcospaceParams"] = (
        None  # Forward reference to avoid circular import
    )
    environmental_drivers: Optional["EnvironmentalDrivers"] = None

RsimOutput dataclass

Output from Ecosim simulation run.

Attributes:

Name	Type	Description
out_Biomass	ndarray	Monthly biomass values (n_months x n_groups+1)
out_Catch	ndarray	Monthly catch values (n_months x n_groups+1)
out_Gear_Catch	ndarray	Monthly catch by gear link
annual_Biomass	ndarray	Annual biomass (n_years x n_groups+1)
annual_Catch	ndarray	Annual catch (n_years x n_groups+1)
annual_QB	ndarray	Annual Q/B values
annual_Qlink	ndarray	Annual consumption by pred-prey pair
stanza_biomass	ndarray or None	Optional monthly stanza-resolved biomass (n_months x n_groups+1)
end_state	RsimState	Final state at end of simulation
crash_year	int	Year of crash (-1 if no crash)
crashed_groups	set	Set of group indices that crashed (biomass < threshold)
pred	ndarray	Predator names for Qlink columns
prey	ndarray	Prey names for Qlink columns
start_state	RsimState	Initial state (copy)
params	dict	Summary parameters

Source code in pypath/core/ecosim.py

@dataclass
class RsimOutput:
    """Output from Ecosim simulation run.

    Attributes
    ----------
    out_Biomass : np.ndarray
        Monthly biomass values (n_months x n_groups+1)
    out_Catch : np.ndarray
        Monthly catch values (n_months x n_groups+1)
    out_Gear_Catch : np.ndarray
        Monthly catch by gear link
    annual_Biomass : np.ndarray
        Annual biomass (n_years x n_groups+1)
    annual_Catch : np.ndarray
        Annual catch (n_years x n_groups+1)
    annual_QB : np.ndarray
        Annual Q/B values
    annual_Qlink : np.ndarray
        Annual consumption by pred-prey pair
    stanza_biomass : np.ndarray or None
        Optional monthly stanza-resolved biomass (n_months x n_groups+1)
    end_state : RsimState
        Final state at end of simulation
    crash_year : int
        Year of crash (-1 if no crash)
    crashed_groups : set
        Set of group indices that crashed (biomass < threshold)
    pred : np.ndarray
        Predator names for Qlink columns
    prey : np.ndarray
        Prey names for Qlink columns
    start_state : RsimState
        Initial state (copy)
    params : dict
        Summary parameters
    """

    out_Biomass: np.ndarray
    out_Catch: np.ndarray
    out_Gear_Catch: np.ndarray
    annual_Biomass: np.ndarray
    annual_Catch: np.ndarray
    annual_QB: np.ndarray
    annual_Qlink: np.ndarray
    end_state: RsimState
    crash_year: int
    crashed_groups: set
    pred: np.ndarray
    prey: np.ndarray
    Gear_Catch_sp: np.ndarray
    Gear_Catch_gear: np.ndarray
    Gear_Catch_disp: np.ndarray
    start_state: RsimState
    params: dict
    stanza_biomass: Optional[np.ndarray] = None
    ecotracer: "EcotracerResult | None" = None
    fleet_dynamics: "FleetDynamicsResult | None" = None

rsim_params

rsim_params(rpath: Rpath, mscramble: float = 2.0, mhandle: float = 1000.0, preyswitch: float = 1.0, scrambleselfwt: float = 0.0, handleselfwt: float = 0.0, steps_yr: int = 12, steps_m: int = 1) -> RsimParams

Convert Rpath model to Ecosim simulation parameters.

Parameters:

Name	Type	Description	Default
rpath	Rpath	Balanced Ecopath model	required
mscramble	float	Base vulnerability parameter (default 2.0 = mixed response)	2.0
mhandle	float	Base handling time parameter (default 1000 = off)	1000.0
preyswitch	float	Prey switching exponent (default 1.0 = off)	1.0
scrambleselfwt	float	Predator overlap weight (0 = individual, 1 = all overlap)	0.0
handleselfwt	float	Prey overlap weight (0 = individual, 1 = all overlap)	0.0
steps_yr	int	Timesteps per year (default 12 = monthly)	12
steps_m	int	Sub-timesteps per month (default 1)	1

Returns:

Type	Description
RsimParams	Parameters object for simulation

Source code in pypath/core/ecosim.py

def rsim_params(
    rpath: Rpath,
    mscramble: float = 2.0,
    mhandle: float = 1000.0,
    preyswitch: float = 1.0,
    scrambleselfwt: float = 0.0,
    handleselfwt: float = 0.0,
    steps_yr: int = 12,
    steps_m: int = 1,
) -> RsimParams:
    """Convert Rpath model to Ecosim simulation parameters.

    Parameters
    ----------
    rpath : Rpath
        Balanced Ecopath model
    mscramble : float
        Base vulnerability parameter (default 2.0 = mixed response)
    mhandle : float
        Base handling time parameter (default 1000 = off)
    preyswitch : float
        Prey switching exponent (default 1.0 = off)
    scrambleselfwt : float
        Predator overlap weight (0 = individual, 1 = all overlap)
    handleselfwt : float
        Prey overlap weight (0 = individual, 1 = all overlap)
    steps_yr : int
        Timesteps per year (default 12 = monthly)
    steps_m : int
        Sub-timesteps per month (default 1)

    Returns
    -------
    RsimParams
        Parameters object for simulation
    """
    nliving = rpath.NUM_LIVING
    ndead = rpath.NUM_DEAD
    ngear = rpath.NUM_GEARS
    ngroups = rpath.NUM_GROUPS
    nbio = nliving + ndead

    # 0-based indices of fleet groups (needed for gear index resolution when
    # groups are in non-canonical order)
    fleet_idx_arr = np.where(rpath.type == 3)[0]

    # Species names with "Outside" prepended
    spname = ["Outside"] + list(rpath.Group)
    spnum = np.arange(ngroups + 1)

    # Reference biomass (with leading 1.0 for Outside)
    b_baseref = np.concatenate([[1.0], rpath.Biomass])

    # Other mortality M0 = PB * (1 - EE)
    mzero = np.concatenate([[0.0], rpath.PB * (1.0 - rpath.EE)])

    # Unassimilated fraction
    unassim = np.concatenate([[0.0], rpath.Unassim])

    # Build PP_type array: 0=consumer, 1=producer, 2=detritus
    # This is based on the actual group types from the Rpath model
    pp_type = np.zeros(ngroups + 1, dtype=int)
    types = np.asarray(rpath.type, dtype=int)
    pp_type[1:] = np.where(types == 0, 0, np.where(types == 1, 1, 2))

    # Active respiration = 1 - P/Q - Unassim (for consumers)
    qb = rpath.QB.copy()
    # Replace invalid QB values (-9999 or negative) with 0 for non-consumers
    qb = np.where((qb < 0) | (qb == -9999) | np.isnan(qb), 0.0, qb)

    pb = rpath.PB
    active_resp = np.zeros(ngroups + 1)
    for i in range(nliving):
        if qb[i] > 0:
            active_resp[i + 1] = max(0, 1.0 - (pb[i] / qb[i]) - rpath.Unassim[i])

    # Foraging time parameters
    ftime_adj = np.zeros(ngroups + 1)
    # For producers (type=1), use PB as the "consumption" rate
    # For consumers (type=0), use QB
    # For detritus (type=2) and fleets (type=3), use 1.0 as default
    ftime_qbopt_values = np.where(
        rpath.type == 1,
        rpath.PB,
        np.where(
            (rpath.type == 0) & (qb > 0),
            qb,
            0.0,  # Default for detritus, fleets, or invalid QB
        ),
    )
    ftime_qbopt = np.concatenate([[1.0], ftime_qbopt_values])
    pbopt = np.concatenate([[1.0], rpath.PB])

    # NoIntegrate flag: 1 indicates groups that should not be integrated (fast-turnover/equilibrium)
    # Previously this used 0/spnum which was inconsistent with downstream checks. Use 1 for NoIntegrate.
    no_integrate = np.where(mzero * b_baseref > 2 * steps_yr * steps_m, 1, 0)

    # Ensure detritus (PP_type == 2) groups are treated as algebraic (NoIntegrate)
    # Rpath commonly treats dead/detritus pools as fast equilibrium; marking them
    # NoIntegrate here makes PyPath behavior match Rpath finite-difference outputs
    try:
        det_idx = np.where(pp_type == 2)[0]
        if det_idx.size > 0:
            no_integrate[det_idx] = 1
    except Exception as e:
        warnings.warn(
            f"Failed to mark detritus groups as NoIntegrate: {e}. "
            f"Detritus dynamics may be incorrect.",
            UserWarning,
            stacklevel=2,
        )

    # Predator-prey handling parameters
    handle_self = np.full(ngroups + 1, handleselfwt)
    scramble_self = np.full(ngroups + 1, scrambleselfwt)

    # Build predator-prey links
    # Primary production links (producers eating "Outside")
    prim_to = []
    prim_from = []
    prim_q = []

    for i in range(nliving):
        if rpath.type[i] > 0 and rpath.type[i] <= 1:  # Producer or mixotroph
            prim_to.append(i + 1)  # +1 for 0-indexing offset
            prim_from.append(0)  # From Outside
            q = rpath.PB[i] * rpath.Biomass[i]
            # Adjust for mixotrophs
            if rpath.type[i] < 1:
                q = q / rpath.GE[i] * rpath.type[i] if rpath.GE[i] > 0 else q
            prim_q.append(q)

    # Predator-prey links from diet matrix
    # NOTE: Only consumers (type=0) can be predators in the diet matrix
    pred_to = []
    pred_from = []
    pred_q = []

    dc = rpath.DC[: nliving + ndead, :nliving].copy()

    # Normalize incomplete diets to sum to 1.0 (excluding import)
    # This ensures proper mass balance at equilibrium
    import_row = (
        rpath.DC[-1, :nliving] if len(rpath.DC) > nliving + ndead else np.zeros(nliving)
    )
    for pred_idx in range(nliving):
        if rpath.type[pred_idx] != 0:  # Skip non-consumers
            continue
        if qb[pred_idx] <= 0 or qb[pred_idx] == -9999 or np.isnan(qb[pred_idx]):
            continue

        # Calculate diet sum (excluding import)
        diet_sum = np.sum(dc[:, pred_idx])
        import_frac = import_row[pred_idx] if pred_idx < len(import_row) else 0
        total_diet = diet_sum + import_frac

        # Normalize if diet is incomplete (sums to less than 1.0)
        # This can happen with incomplete data or data entry errors
        if total_diet > 0 and abs(total_diet - 1.0) > 1e-6:
            # Normalize DC column to make total sum to 1.0
            scale_factor = 1.0 / total_diet
            dc[:, pred_idx] *= scale_factor
            import_row[pred_idx] *= scale_factor
    # Build valid predator mask: consumers (type==0) with valid QB
    valid_pred = (
        (rpath.type[:nliving] == 0)
        & (qb[:nliving] > 0)
        & (qb[:nliving] != -9999)
        & ~np.isnan(qb[:nliving])
    )
    # Find all nonzero DC entries using vectorized indexing (predator-major order)
    for pred_idx in np.where(valid_pred)[0]:
        prey_indices = np.where(dc[: nliving + ndead, pred_idx] > 0)[0]
        for prey_idx in prey_indices:
            q = dc[prey_idx, pred_idx] * qb[pred_idx] * rpath.Biomass[pred_idx]
            if q > 0:
                pred_from.append(prey_idx + 1)
                pred_to.append(pred_idx + 1)
                pred_q.append(q)

    # Handle import links: prey from Outside (index 0)
    import_valid = valid_pred & (import_row[:nliving] > 0)
    for pred_idx in np.where(import_valid)[0]:
        q = import_row[pred_idx] * qb[pred_idx] * rpath.Biomass[pred_idx]
        if q > 0:
            pred_from.append(0)  # From Outside
            pred_to.append(pred_idx + 1)
            pred_q.append(q)

    # Combine links
    prey_from = np.array([0] + prim_from + pred_from)
    prey_to = np.array([0] + prim_to + pred_to)
    qq = np.array([0.0] + prim_q + pred_q)

    numpredprey = len(qq) - 1

    # Vulnerability and handling parameters
    dd = np.full(len(qq), mhandle)
    vv = np.full(len(qq), mscramble)
    handle_switch = np.full(len(qq), preyswitch)
    handle_switch[0] = 0

    # Calculate predator and prey weights for scramble
    btmp = b_baseref

    # Safe division for VV calculation
    aa = np.zeros(len(qq))

    for i in range(1, len(qq)):
        prey_b = btmp[prey_from[i]]
        pred_b = btmp[prey_to[i]]
        if prey_b > 0 and pred_b > 0:
            numerator = 2.0 * qq[i] * vv[i]
            denominator = vv[i] * pred_b * prey_b - qq[i] * pred_b
            if abs(denominator) > EPSILON:
                aa[i] = numerator / denominator

    pred_pred_weight = aa * btmp[prey_to]
    prey_prey_weight = aa * btmp[prey_from]

    # Normalize weights
    pred_tot_weight = np.zeros(ngroups + 1)
    prey_tot_weight = np.zeros(ngroups + 1)

    for i in range(1, len(qq)):
        pred_tot_weight[prey_from[i]] += pred_pred_weight[i]
        prey_tot_weight[prey_to[i]] += prey_prey_weight[i]

    for i in range(1, len(qq)):
        if pred_tot_weight[prey_from[i]] > 0:
            pred_pred_weight[i] /= pred_tot_weight[prey_from[i]]
        if prey_tot_weight[prey_to[i]] > 0:
            prey_prey_weight[i] /= prey_tot_weight[prey_to[i]]

    # Build fishing links
    fish_from = [0]
    fish_through = [0]
    fish_q = [0.0]
    fish_to = [0]

    for gear_idx in range(ngear):
        # Use fleet_idx_arr to get the actual 0-based group index of this fleet,
        # rather than assuming canonical ordering (nliving + ndead + gear_idx).
        fleet_grp_0based = int(fleet_idx_arr[gear_idx])
        fleet_grp_1based = fleet_grp_0based + 1
        for grp_idx in range(ngroups):
            landing = rpath.Landings[grp_idx, gear_idx]
            if landing > 0 and b_baseref[grp_idx + 1] > 0:
                fish_from.append(grp_idx + 1)
                fish_through.append(fleet_grp_1based)
                fish_q.append(landing / b_baseref[grp_idx + 1])
                fish_to.append(0)  # Landings go Outside

            discard = rpath.Discards[grp_idx, gear_idx]
            if discard > 0 and b_baseref[grp_idx + 1] > 0:
                if ndead == 0:
                    warnings.warn(
                        f"Discard for group {rpath.Group[grp_idx]} "
                        f"({discard:.4f}) cannot be routed: no detritus "
                        f"groups in model. Discards will be lost.",
                        UserWarning,
                        stacklevel=2,
                    )
                    # Route to Outside instead of silently vanishing
                    fish_from.append(grp_idx + 1)
                    fish_through.append(fleet_grp_1based)
                    fish_q.append(discard / b_baseref[grp_idx + 1])
                    fish_to.append(0)  # Outside
                    continue
                # Discards go to detritus based on fate
                for det_idx in range(ndead):
                    det_frac = (
                        rpath.DetFate[fleet_grp_0based, det_idx]
                        if fleet_grp_0based < len(rpath.DetFate)
                        else 1.0 / ndead
                    )
                    if det_frac > 0:
                        fish_from.append(grp_idx + 1)
                        fish_through.append(fleet_grp_1based)
                        fish_q.append(discard * det_frac / b_baseref[grp_idx + 1])
                        # Use dead global indices to avoid arithmetic/indexing ambiguity
                        fish_to.append(nliving + det_idx + 1)

    fish_from = np.array(fish_from)
    fish_through = np.array(fish_through)
    fish_q = np.array(fish_q)
    fish_to = np.array(fish_to)

    # Build detritus links
    det_from = [0]
    det_to = [0]
    det_frac_list = [0.0]

    # DEBUG: print per-detritus source groups from rpath.DetFate to help trace missing links
    for det_idx in range(ndead):
        sources = [
            (i, rpath.Group[i]) for i in range(ngroups) if rpath.DetFate[i, det_idx] > 0
        ]
        # Use nliving + det_idx as the detritus global group index (no +1)
        logger.debug(
            "DetFate det_idx=%s dest_global=%s sources=%s",
            det_idx,
            nliving + det_idx,
            sources,
        )

    # FIX: Use ngroups instead of nliving+ndead to include gear rows (22-24) that contribute to detritus
    for grp_idx in range(ngroups):
        for det_idx in range(ndead):
            frac = rpath.DetFate[grp_idx, det_idx]
            if frac > 0:
                det_from.append(grp_idx + 1)
                det_to.append(nliving + det_idx + 1)
                det_frac_list.append(frac)
                # DEBUG: show each det link created
                logger.debug(
                    "DETLINK: grp_idx=%s det_idx=%s frac=%s det_to=%s",
                    grp_idx,
                    det_idx,
                    frac,
                    nliving + det_idx + 1,
                )
        # Flow to outside (1 - sum of det fate)
        det_out = 1.0 - np.sum(rpath.DetFate[grp_idx, :])
        if det_out > 0:
            det_from.append(grp_idx + 1)
            det_to.append(0)
            det_frac_list.append(det_out)

    det_from = np.array(det_from)
    det_to = np.array(det_to)
    det_frac = np.array(det_frac_list)

    # DEBUG: detect detritus columns with no DetFate sources and report mapping
    try:
        dead_idx = np.arange(nliving, nliving + ndead)
        # Sum DetFate over ALL source groups including gears
        col_sums = np.sum(rpath.DetFate[:, :], axis=0)
        zero_cols = np.where(col_sums == 0)[0]
        if len(zero_cols) > 0:
            det_names = [
                rpath.Group[int(dead_idx[zc])] for zc in zero_cols if zc < len(dead_idx)
            ]
            warnings.warn(
                f"DetFate columns with zero source fractions: "
                f"cols={zero_cols.tolist()}, detritus={det_names}. "
                f"These detritus groups receive no flow from any source.",
                UserWarning,
                stacklevel=2,
            )
        # Also report which detritus columns appear in det_to mapping
        det_to_cols = np.unique(
            (det_to[(det_to > nliving) & (det_to <= nliving + ndead)] - nliving - 1)
        )
        logger.debug("DetTo mapped detritus columns (indices): %s", det_to_cols)
        logger.debug("Unique DetTo values: %s", np.unique(det_to))
    except Exception as e:
        logger.debug("DetFate diagnostic logging failed: %s", e)

    return RsimParams(
        NUM_GROUPS=ngroups,
        NUM_LIVING=nliving,
        NUM_DEAD=ndead,
        NUM_GEARS=ngear,
        NUM_BIO=nbio,
        spname=spname,
        spnum=spnum,
        B_BaseRef=b_baseref,
        MzeroMort=mzero,
        UnassimRespFrac=unassim,
        ActiveRespFrac=active_resp,
        FtimeAdj=ftime_adj,
        FtimeQBOpt=ftime_qbopt,
        PBopt=pbopt,
        NoIntegrate=no_integrate,
        HandleSelf=handle_self,
        ScrambleSelf=scramble_self,
        PreyFrom=prey_from,
        PreyTo=prey_to,
        QQ=qq,
        DD=dd,
        VV=vv,
        HandleSwitch=handle_switch,
        PredPredWeight=pred_pred_weight,
        PreyPreyWeight=prey_prey_weight,
        NumPredPreyLinks=numpredprey,
        FishFrom=fish_from,
        FishThrough=fish_through,
        FishQ=fish_q,
        FishTo=fish_to,
        NumFishingLinks=len(fish_from) - 1,
        DetFrac=det_frac,
        DetFrom=det_from,
        DetTo=det_to,
        NumDetLinks=len(det_from) - 1,
        PP_type=pp_type,
        fleet_idx=fleet_idx_arr,
    )

rsim_state

rsim_state(params: RsimParams) -> RsimState

Create initial state vectors for simulation.

Parameters:

Name	Type	Description	Default
params	RsimParams	Simulation parameters	required

Returns:

Type	Description
RsimState	Initial state with biomass, N, and Ftime

Source code in pypath/core/ecosim.py

def rsim_state(params: RsimParams) -> RsimState:
    """Create initial state vectors for simulation.

    Parameters
    ----------
    params : RsimParams
        Simulation parameters

    Returns
    -------
    RsimState
        Initial state with biomass, N, and Ftime
    """
    return RsimState(
        Biomass=params.B_BaseRef.copy(),
        N=np.zeros(params.NUM_GROUPS + 1),
        Ftime=np.ones(params.NUM_GROUPS + 1),
    )

rsim_forcing

rsim_forcing(params: RsimParams, years: range) -> RsimForcing

Create forcing matrices with default values.

Parameters:

Name	Type	Description	Default
params	RsimParams	Simulation parameters	required
years	range	Years of simulation	required

Returns:

Type	Description
RsimForcing	Forcing matrices initialized to default values

Source code in pypath/core/ecosim.py

def rsim_forcing(params: RsimParams, years: range) -> RsimForcing:
    """Create forcing matrices with default values.

    Parameters
    ----------
    params : RsimParams
        Simulation parameters
    years : range
        Years of simulation

    Returns
    -------
    RsimForcing
        Forcing matrices initialized to default values
    """
    nyrs = len(years)
    n_months = nyrs * 12
    n_groups = params.NUM_GROUPS + 1

    # Default forcing = 1.0 (no change)
    ones = np.ones((n_months, n_groups))

    return RsimForcing(
        ForcedPrey=ones.copy(),
        ForcedMort=ones.copy(),
        ForcedRecs=ones.copy(),
        ForcedSearch=ones.copy(),
        ForcedActresp=ones.copy(),
        ForcedMigrate=np.zeros((n_months, n_groups)),
        ForcedBio=np.full((n_months, n_groups), -1.0),  # -1 = not forced
        ForcedEffort=ones.copy(),
    )

rsim_fishing

rsim_fishing(params: RsimParams, years: range) -> RsimFishing

Create fishing matrices with default values.

Parameters:

Name	Type	Description	Default
params	RsimParams	Simulation parameters	required
years	range	Years of simulation	required

Returns:

Type	Description
RsimFishing	Fishing matrices initialized to default values

Source code in pypath/core/ecosim.py

def rsim_fishing(params: RsimParams, years: range) -> RsimFishing:
    """Create fishing matrices with default values.

    Parameters
    ----------
    params : RsimParams
        Simulation parameters
    years : range
        Years of simulation

    Returns
    -------
    RsimFishing
        Fishing matrices initialized to default values
    """
    nyrs = len(years)
    n_months = nyrs * 12

    # Effort matrix (monthly, for gears)
    effort = np.ones((n_months, params.NUM_GEARS + 1))

    # F rate and Catch matrices (annual, for biomass groups)
    frate = np.zeros((nyrs, params.NUM_BIO + 1))
    catch = np.zeros((nyrs, params.NUM_BIO + 1))

    return RsimFishing(
        ForcedEffort=effort,
        ForcedFRate=frate,
        ForcedCatch=catch,
    )

rsim_scenario

rsim_scenario(rpath: Rpath, rpath_params: RpathParams, years: range = range(1, 101), vulnerability: float = 2.0, scenario_overrides: dict = None) -> RsimScenario

Create a complete Ecosim scenario.

Parameters:

Name	Type	Description	Default
rpath	Rpath	Balanced Ecopath model	required
rpath_params	RpathParams	Original model parameters	required
years	range	Years to simulate	range(1, 101)
vulnerability	float	Base vulnerability parameter (default 2.0 = mixed response) Controls predator-prey functional response: - 1.0 = donor control (top-down) - 2.0 = mixed control - Higher values = more bottom-up control	2.0
scenario_overrides	dict	EwE scenario-level parameter overrides. Keys: - 'ftime_adjust': dict mapping 0-based group index -> FtimeAdjust value - 'vv_overrides': dict mapping (prey_0based, pred_0based) -> VV value - 'forced_bio': dict mapping 0-based group index -> array of annual biomass values	None

Returns:

Type	Description
RsimScenario	Complete scenario ready for simulation

Source code in pypath/core/ecosim.py

def rsim_scenario(
    rpath: Rpath,
    rpath_params: RpathParams,
    years: range = range(1, 101),
    vulnerability: float = 2.0,
    scenario_overrides: dict = None,
) -> RsimScenario:
    """Create a complete Ecosim scenario.

    Parameters
    ----------
    rpath : Rpath
        Balanced Ecopath model
    rpath_params : RpathParams
        Original model parameters
    years : range
        Years to simulate
    vulnerability : float, optional
        Base vulnerability parameter (default 2.0 = mixed response)
        Controls predator-prey functional response:
        - 1.0 = donor control (top-down)
        - 2.0 = mixed control
        - Higher values = more bottom-up control
    scenario_overrides : dict, optional
        EwE scenario-level parameter overrides. Keys:
        - 'ftime_adjust': dict mapping 0-based group index -> FtimeAdjust value
        - 'vv_overrides': dict mapping (prey_0based, pred_0based) -> VV value
        - 'forced_bio': dict mapping 0-based group index -> array of annual biomass values

    Returns
    -------
    RsimScenario
        Complete scenario ready for simulation
    """
    if len(years) < 2:
        raise ValueError("Years must be a range of at least 2 years")

    params = rsim_params(rpath, mscramble=vulnerability)
    # Apply scenario-level overrides from EwE database
    if scenario_overrides:
        # Apply FtimeAdjust per group
        if "ftime_adjust" in scenario_overrides:
            for g, val in scenario_overrides["ftime_adjust"].items():
                ecosim_idx = g + 1  # 0-based group -> 1-based ecosim index
                if ecosim_idx < len(params.FtimeAdj):
                    params.FtimeAdj[ecosim_idx] = val

        # Apply VV overrides from forcing matrix
        if "vv_overrides" in scenario_overrides:
            vv_dict = scenario_overrides["vv_overrides"]
            for lk in range(len(params.PreyFrom)):
                prey_g = params.PreyFrom[lk] - 1  # ecosim -> 0-based
                pred_g = params.PreyTo[lk] - 1
                if (prey_g, pred_g) in vv_dict:
                    params.VV[lk] = vv_dict[(prey_g, pred_g)]

    # Preserve optional instrumentation and debug controls set on the
    # original RpathParams object by copying them onto the generated
    # rsim params object. This allows callers/tests to attach
    # 'INSTRUMENT_GROUPS' or 'instrument_callback' to the rpath_params
    # and have them available during simulation without changing
    # existing callsites.
    try:
        for _attr in (
            "INSTRUMENT_GROUPS",
            "VERBOSE_DEBUG",
            "instrument_callback",
            "spname",
            "INSTRUMENT_ASSUME_1BASED",
            "model",
        ):
            if hasattr(rpath_params, _attr):
                setattr(params, _attr, getattr(rpath_params, _attr))
    except Exception as e:
        logger.debug("attribute transfer from rpath_params failed: %s", e)

    state = rsim_state(params)
    forcing = rsim_forcing(params, years)
    fishing = rsim_fishing(params, years)

    # Stanza handling: initialize if rpath_params contains stanza definitions
    stanzas = None
    try:
        if (
            getattr(rpath_params, "stanzas", None) is not None
            and rpath_params.stanzas.n_stanza_groups > 0
        ):
            # Compute rpath stanza diagnostics (biomass/Q distribution)
            rpath_stanzas(rpath_params)
            # Initialize Rsim-compatible stanza parameters
            stanzas = rsim_stanzas(rpath_params, state, params)
    except Exception as e:
        # If stanza initialization fails, continue without stanzas but log via debug
        logger.debug("stanza initialization failed: %s", e, exc_info=True)
        stanzas = None

    return RsimScenario(
        params=params,
        start_state=state,
        forcing=forcing,
        fishing=fishing,
        stanzas=stanzas,
        eco_name=rpath.eco_name,
        start_year=years[0],
    )

rsim_run

rsim_run(scenario: RsimScenario, method: str = 'RK4', years: Optional[range] = None, *, mediation=None, ecotracer=None, fleet_dynamics=None) -> RsimOutput

Run Ecosim simulation.

Parameters:

Name	Type	Description	Default
scenario	RsimScenario	Simulation scenario	required
method	str	Integration method: 'RK4' (Runge-Kutta 4) or 'AB' (Adams-Bashforth)	'RK4'
years	range	Years to run (default: all years in scenario)	None

Returns:

Type	Description
RsimOutput	Simulation results

Source code in pypath/core/ecosim.py

def rsim_run(
    scenario: RsimScenario,
    method: str = "RK4",
    years: Optional[range] = None,
    *,
    mediation=None,
    ecotracer=None,
    fleet_dynamics=None,
) -> RsimOutput:
    """Run Ecosim simulation.

    Parameters
    ----------
    scenario : RsimScenario
        Simulation scenario
    method : str
        Integration method: 'RK4' (Runge-Kutta 4) or 'AB' (Adams-Bashforth)
    years : range, optional
        Years to run (default: all years in scenario)

    Returns
    -------
    RsimOutput
        Simulation results
    """
    from pypath.core.ecosim_deriv import integrate_ab, integrate_rk4

    params = scenario.params
    forcing = scenario.forcing
    fishing_obj = scenario.fishing
    # Build a normalized dict view of fishing to pass to derivative/integrator
    fishing_dict = _normalize_fishing_input(fishing_obj, params.NUM_GROUPS + 1)

    # Fishing link arrays (FishFrom/FishThrough/FishQ) live on params, not
    # on the fishing object.  Ensure they are present in fishing_dict so
    # deriv_vector can compute per-link fishing mortality correctly.
    if not fishing_dict.get("FishFrom", []):
        fishing_dict["FishFrom"] = getattr(params, "FishFrom", np.array([0]))
        fishing_dict["FishThrough"] = getattr(params, "FishThrough", np.array([0]))
        fishing_dict["FishQ"] = getattr(params, "FishQ", np.array([0.0]))

    # Determine years to run
    if years is None:
        n_months = forcing.ForcedBio.shape[0]
        n_years = n_months // 12
    else:
        n_years = len(years)
        n_months = n_years * 12

    n_groups = params.NUM_GROUPS + 1

    # Initialize output arrays
    out_biomass = np.zeros((n_months + 1, n_groups))
    out_catch = np.zeros((n_months + 1, n_groups))
    out_gear_catch = np.zeros((n_months + 1, params.NumFishingLinks + 1))

    # Optional stanza biomass time series
    stanza_biomass = (
        np.zeros((n_months + 1, n_groups))
        if scenario.stanzas is not None and scenario.stanzas.n_split > 0
        else None
    )

    # Initialize state
    state = scenario.start_state.Biomass.copy()
    out_biomass[0] = state

    # If stanzas present, compute initial stanza biomass snapshot
    if stanza_biomass is not None:
        for isp in range(1, scenario.stanzas.n_split + 1):
            nst = scenario.stanzas.n_stanzas[isp]
            for ist in range(1, nst + 1):
                ieco = int(scenario.stanzas.ecopath_code[isp, ist])
                first = int(scenario.stanzas.age1[isp, ist])
                last = int(scenario.stanzas.age2[isp, ist])
                # Sum biomass across ages for this stanza
                bio = np.nansum(
                    scenario.stanzas.base_nage_s[first : last + 1, isp]
                    * scenario.stanzas.base_wage_s[first : last + 1, isp]
                )
                if ieco >= 0 and ieco < n_groups:
                    stanza_biomass[0, ieco] += bio

    # Build params dict for derivative and matrix computations
    params_dict = {
        "NUM_GROUPS": params.NUM_GROUPS,
        "NUM_LIVING": params.NUM_LIVING,
        "NUM_DEAD": params.NUM_DEAD,
        "NUM_GEARS": params.NUM_GEARS,
        "PB": params.PBopt,
        "QB": params.FtimeQBOpt,
        "M0": params.MzeroMort,
        "Unassim": params.UnassimRespFrac,
        "ActiveLink": _build_active_link_matrix(params),
        "VV": _build_link_matrix(params, params.VV),
        "DD": _build_link_matrix(params, params.DD),
        "QQbase": _build_link_matrix(params, params.QQ),
        "Bbase": params.B_BaseRef,
        "PP_type": params.PP_type,
        "NoIntegrate": params.NoIntegrate,
        # Include fish discard mappings so deriv_vector sees them when params is a dict
        "FishFrom": getattr(params, "FishFrom", np.array([])),
        "FishTo": getattr(params, "FishTo", np.array([])),
        "FishQ": getattr(params, "FishQ", np.array([])),
        "fleet_idx": getattr(params, "fleet_idx", None),
    }

    # Pre-compute sparse link arrays for the consumption kernel so that
    # deriv_vector can skip inactive prey-predator pairs entirely.
    from pypath.core.link_array import ActiveLinkArray

    _links = ActiveLinkArray.from_bool_matrix(params_dict["ActiveLink"])
    params_dict["_link_prey"] = _links.prey
    params_dict["_link_pred"] = _links.pred

    # --- Suite-pooling parameters for Rpath-compatible Q formula ----------
    # HandleSelf / ScrambleSelf are per-link 1-D arrays on RsimParams;
    # convert them to 2-D matrices indexed [prey, pred] like VV / DD.
    params_dict["HandleSelf"] = (
        _build_link_matrix(params, params.HandleSelf)
        if hasattr(params, "HandleSelf")
        else None
    )
    params_dict["ScrambleSelf"] = (
        _build_link_matrix(params, params.ScrambleSelf)
        if hasattr(params, "ScrambleSelf")
        else None
    )
    params_dict["HandleSwitch"] = (
        _build_link_matrix(params, params.HandleSwitch)
        if hasattr(params, "HandleSwitch")
        else None
    )
    params_dict["COUPLED"] = 1

    # Build weight matrices (default 1.0 per active link)
    n_pp = params.NUM_GROUPS + 1
    PredPredWeight = np.zeros((n_pp, n_pp))
    PreyPreyWeight = np.zeros((n_pp, n_pp))
    if hasattr(params, "PredPredWeight") and hasattr(params, "PreyPreyWeight"):
        PredPredWeight = _build_link_matrix(params, params.PredPredWeight)
        PreyPreyWeight = _build_link_matrix(params, params.PreyPreyWeight)
    else:
        # Fallback: weight 1.0 for every active link
        for lk in range(len(params.PreyFrom)):
            prey = params.PreyFrom[lk]
            pred = params.PreyTo[lk]
            if prey < n_pp and pred < n_pp:
                PredPredWeight[prey, pred] = 1.0
                PreyPreyWeight[prey, pred] = 1.0
    params_dict["PredPredWeight"] = PredPredWeight
    params_dict["PreyPreyWeight"] = PreyPreyWeight

    if mediation is not None:
        params_dict["_mediation"] = mediation

    # Propagate IBM groups if any functional groups are IBM-managed.
    if hasattr(params, "ibm_groups"):
        params_dict["ibm_groups"] = params.ibm_groups

    # Propagate optional debugging/instrumentation control flags from the
    # RpathParams object to the params dict so deriv_vector can use them
    # when running in dict-mode. This is useful for targeted runtime
    # instrumentation without changing function signatures.
    try:
        if hasattr(params, "INSTRUMENT_GROUPS"):
            params_dict["INSTRUMENT_GROUPS"] = getattr(params, "INSTRUMENT_GROUPS")
            try:
                logger.debug(
                    "DEBUG-INSTR COPY: params.INSTRUMENT_GROUPS attr=%r type=%s",
                    getattr(params, "INSTRUMENT_GROUPS", None),
                    type(getattr(params, "INSTRUMENT_GROUPS", None)),
                )
            except Exception as e:
                logger.debug("instrumentation debug logging failed: %s", e)

        # Normalize instrument group names (strings) to 0-based indices using
        # the scenario's spname mapping so instrumentation payloads use the same
        # numeric indexing expected by unit tests.
        try:
            ig = params_dict.get("INSTRUMENT_GROUPS", None)
            spname = params_dict.get("spname", None)
            if ig is not None and spname is not None and isinstance(ig, (list, tuple)):
                normalized = []
                for g in ig:
                    if isinstance(g, str):
                        # Prefer mapping against original model 'Group' order when available
                        try:
                            model_df = getattr(params, "model", None)
                            if (
                                model_df is not None
                                and "Group" in model_df.columns
                                and g in model_df["Group"].values
                            ):
                                normalized.append(int(list(model_df["Group"]).index(g)))
                                continue
                        except Exception as e:
                            logger.debug("instrument group normalization failed: %s", e)
                        # Fallback: use spname mapping (spname includes leading 'Outside')
                        if g in spname:
                            sidx = spname.index(g)
                            if sidx > 0:  # convert to 0-based group index
                                normalized.append(sidx - 1)
                    else:
                        try:
                            normalized.append(int(g))
                        except Exception as e:
                            logger.debug("instrument group normalization failed: %s", e)
                if normalized:
                    normalized_sorted = sorted(set(normalized))
                    params_dict["INSTRUMENT_GROUPS"] = normalized_sorted
                    # Also write back normalization to the params attribute
                    try:
                        setattr(params, "INSTRUMENT_GROUPS", normalized_sorted)
                    except Exception as e:
                        logger.debug("instrument group normalization failed: %s", e)
                        try:
                            params["INSTRUMENT_GROUPS"] = normalized_sorted
                        except Exception as e:
                            logger.debug("instrument group normalization failed: %s", e)
                    try:
                        logger.debug(
                            "DEBUG-INSTR-MAP: ig_raw=%s normalized=%s model_present=%s",
                            ig,
                            normalized_sorted,
                            model_df is not None,
                        )
                    except Exception as e:
                        logger.debug("instrumentation debug logging failed: %s", e)
        except Exception as e:
            logger.debug("instrument group normalization failed: %s", e)
        if hasattr(params, "VERBOSE_DEBUG"):
            params_dict["VERBOSE_DEBUG"] = getattr(params, "VERBOSE_DEBUG")
        # Also include the species name mapping so deriv_vector can resolve
        # names (e.g., 'Seabirds') into indices for instrumentation.
        if hasattr(params, "spname"):
            params_dict["spname"] = getattr(params, "spname")
        # Also propagate the original model DataFrame when available so
        # deriv_vector can prefer the model-defined group ordering for
        # name->index mapping during instrumentation resolution.
        if hasattr(params, "model"):
            try:
                params_dict["model"] = getattr(params, "model")
            except Exception as e:
                logger.debug("model propagation to params_dict failed: %s", e)
        # Propagate an optional instrumentation callback function (callable)
        # so integration routines can report compact instrumentation data to
        # the outside world without changing function signatures.
        if hasattr(params, "MONTHLY_M0_ADJUST"):
            params_dict["MONTHLY_M0_ADJUST"] = getattr(params, "MONTHLY_M0_ADJUST")

        # callers/tests without relying on global I/O.
        if hasattr(params, "instrument_callback"):
            orig_cb = getattr(params, "instrument_callback")

            # Wrap the user-provided callback to ensure the first instrumentation
            # callback uses the caller-specified attribute-based INSTRUMENT_GROUPS
            # mapping when available. This avoids race conditions where RK4
            # warmup payloads may resolve names differently (spname vs model).
            def _wrapped_cb(payload):
                try:
                    if not getattr(_wrapped_cb, "first_called", False):
                        _wrapped_cb.first_called = True
                        attr_ig = getattr(params, "INSTRUMENT_GROUPS", None)
                        if isinstance(attr_ig, (list, tuple)) and payload.get(
                            "method"
                        ) in ("AB", "RK4"):
                            resolved = []
                            model_df = getattr(params, "model", None)
                            spname = getattr(params, "spname", None)
                            for g in attr_ig:
                                if isinstance(g, str):
                                    try:
                                        if (
                                            model_df is not None
                                            and "Group" in model_df.columns
                                            and g in model_df["Group"].values
                                        ):
                                            resolved.append(
                                                int(list(model_df["Group"]).index(g))
                                            )
                                            continue
                                    except Exception as e:
                                        logger.debug(
                                            "callback group resolution failed: %s", e
                                        )
                                    if spname is not None and g in spname:
                                        sidx = spname.index(g)
                                        if sidx > 0:
                                            resolved.append(sidx - 1)
                                else:
                                    try:
                                        resolved.append(int(g))
                                    except Exception as e:
                                        logger.debug(
                                            "callback group resolution failed: %s", e
                                        )
                            if resolved:
                                try:
                                    payload["groups"] = resolved
                                except Exception as e:
                                    logger.debug(
                                        "callback group resolution failed: %s", e
                                    )
                except Exception as e:
                    logger.debug("callback group resolution failed: %s", e)
                return orig_cb(payload)

            params_dict["instrument_callback"] = _wrapped_cb
        # Additional debug visibility for tests: print presence of callback
        try:
            logger.debug(
                "DEBUG-RUN: params hasattr instrument_callback=%s params_dict_has_cb=%s",
                hasattr(params, "instrument_callback"),
                "instrument_callback" in params_dict,
            )
            try:
                logger.debug(
                    "DEBUG-RUN: params.INSTRUMENT_GROUPS (attr)=%s params_dict['INSTRUMENT_GROUPS']=%s",
                    getattr(params, "INSTRUMENT_GROUPS", None),
                    params_dict.get("INSTRUMENT_GROUPS", None),
                )
            except Exception as e:
                logger.debug("callback group resolution failed: %s", e)
        except Exception as e:
            logger.debug("callback group resolution failed: %s", e)
    except Exception as e:
        logger.debug("callback group resolution failed: %s", e)

    # Debug: always log what's in params_dict for INSTRUMENT_GROUPS to catch
    # cases where it might be present due to other code paths or defaults.
    try:
        logger.debug(
            "DEBUG-INSTR-PARAMSDICT initial INSTRUMENT_GROUPS = %r",
            params_dict.get("INSTRUMENT_GROUPS", None),
        )
    except Exception as e:
        logger.debug("callback group resolution failed: %s", e)

    # Migration helper: accept legacy numeric 1-based INSTRUMENT_GROUPS on the
    # params object or dict. Convert to 0-based indices and emit a
    # DeprecationWarning so callers can update. This ensures integrator code
    # always sees a normalized numeric list.
    try:
        ig = params_dict.get("INSTRUMENT_GROUPS", None)
        # Explicit opt-in: only auto-convert numeric legacy 1-based groups when the
        # caller explicitly requests it via INSTRUMENT_ASSUME_1BASED.
        assume_flag = params_dict.get("INSTRUMENT_ASSUME_1BASED", False) or getattr(
            params, "INSTRUMENT_ASSUME_1BASED", False
        )
        if ig is not None:
            # check for numeric-only lists/tuples
            if isinstance(ig, (list, tuple)) and all(
                isinstance(x, (int, float, np.integer)) for x in ig
            ):
                nums = [int(x) for x in ig]
                if (
                    assume_flag
                    and nums
                    and all(1 <= v <= params.NUM_GROUPS for v in nums)
                    and min(nums) >= 1
                ):
                    import warnings as _warnings

                    _warnings.warn(
                        "Numeric INSTRUMENT_GROUPS indices are expected to be 0-based. "
                        "Detected probable 1-based indices — converting to 0-based for now. "
                        "Please update your code to use 0-based indices.",
                        DeprecationWarning,
                        stacklevel=3,
                    )
                    normalized = [v - 1 for v in nums]
                    params_dict["INSTRUMENT_GROUPS"] = normalized
                    # Also write back to params object if it has the attribute
                    try:
                        if hasattr(params, "INSTRUMENT_GROUPS"):
                            setattr(params, "INSTRUMENT_GROUPS", normalized)
                    except Exception as e:
                        logger.debug("verbose instrumentation config failed: %s", e)
                    try:
                        if params_dict.get("VERBOSE_INSTRUMENTATION"):
                            logger.debug(
                                "DEBUG-INSTR-MIGRATE: converted numeric 1-based %s -> %s",
                                nums,
                                normalized,
                            )
                    except Exception as e:
                        logger.debug("verbose instrumentation config failed: %s", e)
    except Exception as e:
        logger.debug("verbose instrumentation config failed: %s", e)

    # Provide a module-level fallback for instrumentation callback resolution.
    # Some callsites attach the callback as an attribute on the params object;
    # ensure integrator code can still find it by exporting it to the
    # ecosim_deriv module as `_last_instrument_callback`.
    try:
        import pypath.core.ecosim_deriv as _ed

        if hasattr(params, "instrument_callback"):
            _ed._last_instrument_callback = getattr(params, "instrument_callback")
            try:
                logger.debug("exported instrument_callback to ecosim_deriv")
            except Exception as e:
                logger.debug("verbose instrumentation config failed: %s", e)
            try:
                logger.debug(
                    "DEBUG-RUN: exported _last_instrument_callback=%s",
                    _ed._last_instrument_callback,
                )
            except Exception as e:
                logger.debug("verbose instrumentation config failed: %s", e)
        # Export original INSTRUMENT_GROUPS attribute (if present) so integrator
        # can consult the canonical caller-specified groups in legacy callsites
        # where the list was attached as an attribute on the params object.
        try:
            # Ensure attribute-based INSTRUMENT_GROUPS is normalized to numeric 0-based
            attr_ig = getattr(params, "INSTRUMENT_GROUPS", None)
            if isinstance(attr_ig, (list, tuple)) and attr_ig:
                # Map string names to model-based indices if available
                try:
                    model_df = getattr(params, "model", None)
                    normalized_attr = []
                    for g in attr_ig:
                        if (
                            isinstance(g, str)
                            and model_df is not None
                            and "Group" in model_df.columns
                            and g in model_df["Group"].values
                        ):
                            normalized_attr.append(
                                int(list(model_df["Group"]).index(g))
                            )
                        elif (
                            isinstance(g, str)
                            and getattr(params, "spname", None) is not None
                            and g in params.spname
                        ):
                            sidx = params.spname.index(g)
                            if sidx > 0:
                                normalized_attr.append(sidx - 1)
                        else:
                            try:
                                normalized_attr.append(int(g))
                            except Exception as e:
                                logger.debug(
                                    "verbose instrumentation config failed: %s", e
                                )
                    if normalized_attr:
                        try:
                            setattr(
                                params,
                                "INSTRUMENT_GROUPS",
                                sorted(set(normalized_attr)),
                            )
                            attr_ig = getattr(params, "INSTRUMENT_GROUPS")
                        except Exception as e:
                            logger.debug("verbose instrumentation config failed: %s", e)
                except Exception as e:
                    logger.debug("verbose instrumentation config failed: %s", e)
            _ed._last_instrument_groups = getattr(params, "INSTRUMENT_GROUPS", None)
            # Also export a module-level fallback variable so deriv_vector can
            # pick up attribute-based instrumentation when only the params
            # object had the attribute set (legacy code paths).
            try:
                globals()["_last_instrument_groups"] = _ed._last_instrument_groups
            except Exception as e:
                logger.debug("verbose instrumentation config failed: %s", e)
            if _ed._last_instrument_groups is not None:
                if params_dict.get("VERBOSE_INSTRUMENTATION"):
                    logger.debug(
                        "exported _last_instrument_groups=%s",
                        _ed._last_instrument_groups,
                    )
        except Exception as e:
            logger.debug("verbose instrumentation config failed: %s", e)
    except Exception as e:
        logger.debug("verbose instrumentation config failed: %s", e)

    # Debug: log summary of NoIntegrate array for verification
    try:
        noint = np.asarray(params_dict.get("NoIntegrate"))
        logger.debug("NoIntegrate array length=%d sample=%s", len(noint), noint[:10])
        logger.debug("NoIntegrate true count=%d", int(np.sum(noint != 0)))
    except Exception as e:
        logger.debug("verbose instrumentation config failed: %s", e)

    # Enforce exact equilibrium at initialization for tiny residual derivatives
    # This prevents tiny numerical residuals at t=0 from accumulating over long
    # simulations (observed in Seabirds tests).
    INIT_DERIV_EPS = 1e-8
    # Build forcing for month 0 (first month) similar to loop below
    forcing0 = {
        "Ftime": scenario.start_state.Ftime.copy(),
        "ForcedBio": np.where(forcing.ForcedBio[0] > 0, forcing.ForcedBio[0], 0),
        "ForcedMigrate": forcing.ForcedMigrate[0],
        "ForcedEffort": (
            fishing_obj.ForcedEffort[0]
            if 0 < len(fishing_obj.ForcedEffort)
            else np.ones(params.NUM_GEARS + 1)
        ),
    }
    # Debugging: log forcing0 summary to compare with test precomputed forcing
    try:
        logger.debug(
            "forcing0 sample ForcedEffort[:4]=%s ForcedBio[:4]=%s",
            forcing0["ForcedEffort"][:4],
            forcing0["ForcedBio"][:4],
        )
    except Exception as e:
        logger.debug("forcing0 debug logging failed: %s", e)

    try:
        # Compute initial derivative without applying NoIntegrate masking so we
        # capture the true algebraic residuals used to compute small M0 nudges.
        params_no_noint = params_dict.copy()
        params_no_noint["NoIntegrate"] = np.zeros(n_groups, dtype=int)
        # Use the actual fishing_dict (with FishFrom/FishQ from params) so
        # the init-deriv computation includes fishing mortality.  Previously
        # this used a zero-fishing dict which caused M0 to be nudged to
        # compensate for "missing" fishing, double-counting it once the fix
        # that populates fishing_dict from params was applied.
        # Threshold for considering small initial derivatives
        ADJUST_DERIV_MAX = 1e-3
        logger.debug(
            "computing init_deriv with fishing_dict FishFrom length=%d",
            len(fishing_dict.get("FishFrom", [])),
        )
        init_deriv = deriv_vector(state.copy(), params_no_noint, forcing0, fishing_dict)
        # Also compute a test-style derivative with TRACE to compare
        params_test = params_no_noint.copy()
        try:
            params_test["TRACE_DEBUG_GROUPS"] = params_no_noint.get(
                "TRACE_DEBUG_GROUPS", None
            )
            deriv_test = deriv_vector(state.copy(), params_test, forcing0, fishing_dict)
        except Exception as e:
            logger.debug("derivative comparison debug failed: %s", e)
            deriv_test = None
        init_mask = np.abs(init_deriv) < INIT_DERIV_EPS
        # Don't include the outside cell (index 0) in masking
        init_mask[0] = False
        # Debug: report summary of initial derivatives
        logger.debug(
            "init_deriv min=%.6e max=%.6e",
            float(np.nanmin(init_deriv)),
            float(np.nanmax(init_deriv)),
        )
        try:
            logger.debug("init_deriv sample[:10]=%s", init_deriv[:10])
        except Exception as e:
            logger.debug("init_deriv debug logging failed: %s", e)

        # Build a test-style params dict (like tests do) and compute its derivative
        try:
            params_test = {
                "NUM_GROUPS": params.NUM_GROUPS,
                "NUM_LIVING": params.NUM_LIVING,
                "NUM_DEAD": params.NUM_DEAD,
                "NUM_GEARS": params.NUM_GEARS,
                "PB": params.PBopt,
                "QB": params.FtimeQBOpt,
                "M0": params.MzeroMort.copy(),
                "Unassim": params.UnassimRespFrac,
                "ActiveLink": _build_active_link_matrix(params),
                "VV": _build_link_matrix(params, params.VV),
                "DD": _build_link_matrix(params, params.DD),
                "QQbase": _build_link_matrix(params, params.QQ),
                "Bbase": params.B_BaseRef,
                "PP_type": params.PP_type,
                "FishFrom": getattr(params, "FishFrom", np.array([])),
                "FishTo": getattr(params, "FishTo", np.array([])),
                "FishQ": getattr(params, "FishQ", np.array([])),
                "fleet_idx": getattr(params, "fleet_idx", None),
            }
            deriv_test = deriv_vector(state.copy(), params_test, forcing0, fishing_dict)
            diffs = np.abs(init_deriv - deriv_test)
            TH = 1e-12
            if np.any(diffs > TH):
                logger.debug(
                    "derivative mismatch between raw (NoIntegrate disabled) and test-style params; count>%s: %d",
                    TH,
                    int(np.sum(diffs > TH)),
                )
                # Show first few mismatches
                mism = np.where(diffs > TH)[0][:20]
                for idx in mism:
                    name = (
                        params.spname[idx]
                        if (hasattr(params, "spname") and idx < len(params.spname))
                        else ""
                    )
                    logger.debug(
                        "deriv diff idx=%d name=%s raw=%.6e test=%.6e diff=%.6e",
                        idx,
                        name,
                        init_deriv[idx],
                        deriv_test[idx],
                        diffs[idx],
                    )
            # Also compare key parameter arrays for quick diffs
            for key in ["M0", "PB", "QB", "Bbase", "NoIntegrate"]:
                a = params_dict.get(key)
                b = params_test.get(key)
                try:
                    aa = np.asarray(a)
                    bb = np.asarray(b)
                    if aa.shape == bb.shape:
                        md = np.nanmax(np.abs(aa - bb))
                        if md > 0:
                            logger.debug("param '%s' max abs diff = %.6e", key, md)
                    else:
                        logger.debug(
                            "param '%s' shape differs: %s vs %s",
                            key,
                            aa.shape,
                            bb.shape,
                        )
                except Exception as e:
                    logger.debug("parameter comparison failed: %s", e)
        except Exception as e:
            logger.debug("derivative comparison failed: %s", e)

    except Exception as e:
        logger.debug("init_deriv computation failed: %s", e)
        init_mask = np.zeros(n_groups, dtype=bool)

    if np.any(init_mask):
        # Informative message for debugging; this can be toggled or removed if desired
        logger.debug(
            "zeroing tiny initial derivatives for groups: %s",
            np.where(init_mask)[0].tolist(),
        )

    # Build a looser mask for small initial derivatives that we should prevent from changing
    # during the warmup period to avoid slow drift accumulation
    try:
        init_mask_loose = np.abs(init_deriv) < ADJUST_DERIV_MAX
        init_mask_loose[0] = False
        if np.any(init_mask_loose) and not np.array_equal(init_mask_loose, init_mask):
            logger.debug(
                "small initial derivatives (loose mask) groups: %s",
                np.where(init_mask_loose)[0].tolist(),
            )
    except Exception as e:
        logger.debug("loose mask computation failed: %s", e)
        init_mask_loose = np.zeros(n_groups, dtype=bool)

    # If there are tiny residuals, nudge M0 in params_dict so initial derivative is exactly zero
    # This uses a tiny adjustment only when the required change is small (avoid large parameter changes)
    # Only accept very small M0 changes at init/final check to avoid drifting from Rpath
    # (use a strict absolute threshold to prevent ~1e-3 sized nudges that affect parity)
    M0_ADJUST_THRESHOLD = (
        1e-4  # absolute threshold allowed for M0 adjustments (was 1e-3)
    )
    ADJUST_DERIV_MAX = (
        1e-3  # consider adjusting M0 for initial derivatives smaller than this (abs)
    )
    try:
        # Build immediate fishing mortality (base) to compute fish_loss
        logger.debug("entering M0 adjustment block")
        # Use the normalized fishing dict so we don't depend on dataclass vs dict
        fishing_mort = fishing_dict.get("FishingMort", np.zeros(n_groups))
        fish_from = fishing_dict.get("FishFrom", [])
        fish_q = fishing_dict.get("FishQ", np.array([0.0]))
        for i in range(1, len(fish_from)):
            grp = int(fish_from[i])
            fishing_mort[grp] += fish_q[i]

        for grp in range(1, params.NUM_GROUPS + 1):
            # Consider small initial residuals within ADJUST_DERIV_MAX
            if not (abs(init_deriv[grp]) < ADJUST_DERIV_MAX):
                continue
            B = state[grp]
            if B <= 0:
                continue
            # Use baseline QQ (QQbase) to approximate consumption and predation loss at equilibrium
            QQbase = params_dict.get("QQbase")
            # Consumption by this group (sum over prey)
            consumption = (
                float(np.nansum(QQbase[:, grp])) if QQbase is not None else 0.0
            )
            # Predation loss on this group (sum over predators)
            predation_loss = (
                float(np.nansum(QQbase[grp, :])) if QQbase is not None else 0.0
            )

            # Production (handle producers/consumers)
            PB = params_dict.get("PB")[grp]
            QB = params_dict.get("QB")[grp]
            PP_type = params_dict.get("PP_type", np.zeros(params.NUM_GROUPS + 1))
            Bbase = params_dict.get("Bbase")
            if PP_type[grp] > 0:
                # Primary producer: use density-dependent formula at baseline forcing
                if Bbase is not None and Bbase[grp] > 0:
                    rel_bio = B / Bbase[grp]
                    dd_factor = max(0.0, 2.0 - rel_bio)
                    production = PB * B * dd_factor
                else:
                    production = PB * B
            elif QB > 0:
                GE = PB / QB
                production = GE * consumption
            else:
                production = PB * B

            fish_loss = fishing_mort[grp] * B
            current_m0 = float(params_dict.get("M0")[grp])
            # Compute desired M0 using raw initial derivative computed without NoIntegrate masking
            desired_m0 = current_m0 + float(init_deriv[grp]) / B
            diff = desired_m0 - current_m0
            # Debug log the computed quantities
            logger.debug(
                "grp=%d B=%.6e consumption=%.6e production=%.6e predation_loss=%.6e fish_loss=%.6e current_m0=%.6e desired_m0=%.6e diff=%.6e",
                grp,
                B,
                consumption,
                production,
                predation_loss,
                fish_loss,
                current_m0,
                desired_m0,
                diff,
            )
            # Accept small changes only (absolute threshold)
            if np.isfinite(desired_m0) and abs(diff) <= M0_ADJUST_THRESHOLD:
                logger.debug("assigning M0 for grp=%d diff=%.6e", grp, diff)
                # Iteratively refine M0 to drive the raw (no-NoIntegrate) initial residual toward zero
                MAX_M0_ITER = 5
                TOL_INIT_DERIV_ITER = 1e-10
                try:
                    # Start from a params dict that has NoIntegrate disabled so we measure the raw algebraic residual
                    params_iter = params_no_noint.copy()
                    # Ensure M0 array is present and set initial candidate
                    params_iter["M0"] = params_dict["M0"].copy()
                    params_iter["M0"][grp] = desired_m0
                    params_dict["M0"][grp] = desired_m0
                    logger.debug(
                        "initial M0 assigned grp=%d value=%.6e",
                        grp,
                        params_dict["M0"][grp],
                    )

                    for it in range(1, MAX_M0_ITER + 1):
                        try:
                            init_deriv_iter = deriv_vector(
                                state.copy(), params_iter, forcing0, fishing_dict
                            )
                            residual = float(init_deriv_iter[grp])
                            logger.debug(
                                "M0 iter grp=%d it=%d residual=%.6e",
                                grp,
                                it,
                                residual,
                            )
                            # If residual sufficiently small, stop
                            if abs(residual) < TOL_INIT_DERIV_ITER:
                                break
                            # Compute correction step: delta_m0 = residual / B
                            step = residual / B
                            # Clamp step so we don't jump by more than allowed threshold
                            if abs(step) > M0_ADJUST_THRESHOLD:
                                step = np.sign(step) * M0_ADJUST_THRESHOLD
                            params_iter["M0"][grp] += step
                            params_dict["M0"][grp] = params_iter["M0"][grp]
                        except Exception as e:
                            logger.debug(
                                "M0 iteration failed for grp=%d it=%d: %s",
                                grp,
                                it,
                                e,
                            )
                            break
                    logger.debug(
                        "final M0 for grp=%d value=%.6e",
                        grp,
                        params_dict["M0"][grp],
                    )

                    # Final check using the params dict that will be persisted
                    try:
                        params_check = params_dict.copy()
                        init_deriv_check = deriv_vector(
                            state.copy(), params_check, forcing0, fishing_dict
                        )
                        final_residual = float(init_deriv_check[grp])
                        logger.debug(
                            "final check residual grp=%d residual=%.6e",
                            grp,
                            final_residual,
                        )
                        if (
                            B != 0
                            and np.isfinite(final_residual)
                            and abs(final_residual) > 0.0
                        ):
                            step = final_residual / B
                            if abs(step) > M0_ADJUST_THRESHOLD:
                                step = np.sign(step) * M0_ADJUST_THRESHOLD
                            params_dict["M0"][grp] += step
                            logger.debug(
                                "final adj applied grp=%d new_m0=%.6e step=%.6e",
                                grp,
                                params_dict["M0"][grp],
                                step,
                            )
                    except Exception as e:
                        logger.debug("final M0 check failed for grp=%d: %s", grp, e)
                        pass
                except Exception as e:
                    logger.debug("M0 assignment failed for grp=%d: %s", grp, e)
                    pass

            # Only persist small/safe M0 adjustments; avoid overwriting for larger computed desired_m0
            if np.isfinite(desired_m0) and abs(diff) <= M0_ADJUST_THRESHOLD:
                params_dict["M0"][grp] = desired_m0
                logger.debug(
                    "enforcing exact initial equilibrium for group %d: M0 %.6e -> %.6e (init_deriv=%.6e)",
                    grp,
                    current_m0,
                    desired_m0,
                    init_deriv[grp],
                )
            else:
                # Do not apply large adjustments; leave M0 as originally specified
                if np.isfinite(desired_m0):
                    logger.debug(
                        "skipping initial M0 assign for grp=%d (diff=%.6e > threshold)",
                        grp,
                        diff,
                    )
    except Exception as e:
        logger.debug("M0 adjustment failed: %s", e, exc_info=True)

    # Final check: compute derivative using the params dict that will be persisted
    # and make a small algebraic correction if a tiny residual remains.
    try:
        logger.debug("performing final M0 algebraic check")
        check_deriv = deriv_vector(state.copy(), params_dict, forcing0, fishing_dict)
        for grp in range(1, params.NUM_GROUPS + 1):
            if not np.isfinite(check_deriv[grp]) or state[grp] <= 0:
                continue
            # only consider small residuals within adjustment window
            if abs(check_deriv[grp]) < ADJUST_DERIV_MAX and abs(check_deriv[grp]) > 0:
                step = check_deriv[grp] / state[grp]
                if abs(step) > M0_ADJUST_THRESHOLD:
                    step = np.sign(step) * M0_ADJUST_THRESHOLD
                params_dict["M0"][grp] += step
                logger.debug(
                    "final algebraic adjust grp=%d step=%.6e new_m0=%.6e residual_after=%.6e",
                    grp,
                    step,
                    params_dict["M0"][grp],
                    check_deriv[grp],
                )
    except Exception as e:
        logger.debug("final M0 algebraic check failed: %s", e)
        pass

    # Persist any M0 adjustments back to the params dataclass so diagnostics
    # and downstream code that read scenario.params.MzeroMort see the same values
    try:
        if "M0" in params_dict:
            # params is the RsimParams object (scenario.params)
            params.MzeroMort = params_dict["M0"].copy()
            # Debug sample to confirm persistence
            try:
                logger.debug("persisted adjusted M0 sample=%s", params.MzeroMort[:6])
            except Exception as e:
                logger.debug("M0 persistence debug failed: %s", e)
    except Exception as e:
        logger.debug("M0 persistence debug failed: %s", e)

    # Build fishing dict
    fishing_dict = {
        "FishFrom": params.FishFrom,
        "FishThrough": params.FishThrough,
        "FishQ": params.FishQ,
        "FishingMort": np.zeros(n_groups),  # Base fishing mortality (no effort scaling)
    }

    # Calculate base fishing mortality (without effort scaling)
    for i in range(1, len(params.FishFrom)):
        grp = params.FishFrom[i]
        fishing_dict["FishingMort"][grp] += params.FishQ[i]

    # History for Adams-Bashforth
    derivs_history = []

    dt = 1.0 / 12.0  # Monthly timestep
    crash_year = -1
    crashed_groups = set()  # Track which groups have crashed
    crash_threshold = 1e-4  # More reasonable threshold (0.0001 vs 0.000001)

    # Initialize annual Qlink accumulator if links exist
    annual_qlink = (
        np.zeros((n_years, len(params.PreyFrom))) if len(params.PreyFrom) > 0 else None
    )

    # Pre-compute the NoIntegrate mask once (NoIntegrate never changes during sim).
    # This avoids recomputing np.asarray(...) != 0 four times per month.
    no_integrate_mask = (
        np.asarray(params_dict.get("NoIntegrate", np.zeros(n_groups))) != 0
    )

    # Ftime is dynamically adjusted when FtimeAdj > 0.
    # Initialize from start state; updated each month based on consumption.
    _ftime_current = scenario.start_state.Ftime.copy()
    _ftime_adj = params.FtimeAdj
    _ftime_qbopt = params.FtimeQBOpt
    _has_ftime_adj = np.any(_ftime_adj > 0)

    # Main simulation loop
    # Debug: log fishing link summary before starting loop
    try:
        if len(params.FishFrom) > 0:
            logger.debug(
                "starting simulation months=%s FishFrom=%s FishQ=%s FishThrough=%s ForcedEffort_sample=%s",
                n_months,
                params.FishFrom,
                params.FishQ,
                params.FishThrough,
                (
                    fishing_obj.ForcedEffort[0]
                    if len(fishing_obj.ForcedEffort) > 0
                    else None
                ),
            )
    except Exception as e:
        logger.debug("fishing link debug failed: %s", e)

    # Build gear lookup from fleet_idx once before the monthly loop,
    # for non-canonical group ordering support.
    _run_gear_lookup = {}
    if hasattr(params, "fleet_idx") and params.fleet_idx is not None:
        for _pos, _grp0 in enumerate(params.fleet_idx):
            _run_gear_lookup[int(_grp0)] = _pos + 1

    # Ecotracer initialization
    _ecotracer_conc = None
    _ecotracer_out = None
    if ecotracer is not None:
        from pypath.core.ecotracer import ecotracer_step as _ecotracer_step_fn

        n_eco_groups = params.NUM_GROUPS
        _ecotracer_conc = ecotracer.czero[:n_eco_groups].copy()
        _ecotracer_out = np.zeros((n_months + 1, n_eco_groups))
        _ecotracer_out[0] = _ecotracer_conc.copy()

    # Fleet dynamics initialization
    _fleet_capacity = None
    _fleet_out_effort = None
    _fleet_out_revenue = None
    _fleet_out_cost = None
    _fleet_out_profit = None
    _fleet_cumul_catch = None
    _original_fish_q = None
    if fleet_dynamics is not None:
        from pypath.core.fleet_dynamics import apply_quota_caps as _fleet_quota_fn
        from pypath.core.fleet_dynamics import fleet_dynamics_step as _fleet_step_fn

        _n_fd_fleets = params.NUM_GEARS
        _fleet_capacity = fishing_obj.ForcedEffort[0, 1 : _n_fd_fleets + 1].copy()
        _fleet_out_effort = np.zeros((n_months + 1, _n_fd_fleets))
        _fleet_out_revenue = np.zeros((n_months + 1, _n_fd_fleets))
        _fleet_out_cost = np.zeros((n_months + 1, _n_fd_fleets))
        _fleet_out_profit = np.zeros((n_months + 1, _n_fd_fleets))
        _fleet_out_effort[0] = _fleet_capacity.copy()
        _fleet_cumul_catch = np.zeros((_n_fd_fleets, params.NUM_GROUPS))
        _original_fish_q = params.FishQ.copy()

    for month in range(1, n_months + 1):
        # Debug: indicate loop iteration for first few months
        if month <= 6:
            logger.debug("entering month loop month=%s", month)
        t = month * dt
        year_idx = (month - 1) // 12
        month_in_year = (month - 1) % 12

        # Build forcing dict for this timestep
        # ForcedPrey: prey availability multiplier per group per month.
        # For producers this also serves as the primary production forcing.
        _forced_prey = (
            forcing.ForcedPrey[month - 1]
            if hasattr(forcing, "ForcedPrey")
            and forcing.ForcedPrey is not None
            and month - 1 < len(forcing.ForcedPrey)
            else np.ones(params.NUM_GROUPS + 1)
        )
        forcing_dict = {
            "Ftime": _ftime_current,
            "ForcedBio": np.where(
                forcing.ForcedBio[month - 1] > 0, forcing.ForcedBio[month - 1], 0
            ),
            "ForcedMigrate": forcing.ForcedMigrate[month - 1],
            "ForcedPrey": _forced_prey,
            "PP_forcing": _forced_prey,
            "ForcedEffort": (
                fishing_obj.ForcedEffort[month - 1]
                if month - 1 < len(fishing_obj.ForcedEffort)
                else np.ones(params.NUM_GEARS + 1)
            ),
        }

        # Integration step
        if method.upper() == "RK4":
            old_state = state.copy()
            state = integrate_rk4(state, params_dict, forcing_dict, fishing_dict, dt)
            # If small initial derivative mask exists, prevent first-step change for those groups
            if month == 1 and np.any(init_mask):
                state[init_mask] = old_state[init_mask]
            # Prevent groups with small initial residuals from changing during warmup
            WARMUP_MONTHS = 12
            if month <= WARMUP_MONTHS and np.any(init_mask_loose):
                state[init_mask_loose] = old_state[init_mask_loose]
        elif method.upper() == "AB":
            # Warmup: use RK4 for the first month to populate derivative history
            # before switching to Adams-Bashforth 2-step (matching Rpath)
            if month <= 1:
                # Use one RK4 step then switch to AB2
                old_state = state.copy()
                # Mark parent integration method so RK4 instrumentation reports 'AB' for warmup
                params_dict["_integration_parent_method"] = "AB"
                try:
                    state = integrate_rk4(
                        state, params_dict, forcing_dict, fishing_dict, dt
                    )
                finally:
                    # Clean up the temporary context flag
                    params_dict.pop("_integration_parent_method", None)
                if month == 1 and np.any(init_mask):
                    state[init_mask] = old_state[init_mask]
                # Prevent groups with small initial residuals from changing during warmup
                WARMUP_MONTHS = 1
                if month <= WARMUP_MONTHS and np.any(init_mask_loose):
                    state[init_mask_loose] = old_state[init_mask_loose]
                try:
                    new_deriv = deriv_vector(
                        state, params_dict, forcing_dict, fishing_dict
                    )
                    # Sanitize derivative before storing to history to avoid
                    # carrying non-finite or extreme values into Adams-Bashforth
                    new_deriv = np.nan_to_num(
                        new_deriv, nan=0.0, posinf=1e6, neginf=-1e6
                    )
                    new_deriv = np.clip(new_deriv, -1e6, 1e6)
                    # Zero derivatives for NoIntegrate groups to align with Rpath
                    if np.any(no_integrate_mask):
                        new_deriv[no_integrate_mask] = 0.0
                    derivs_history.insert(0, new_deriv)
                    if len(derivs_history) > 1:
                        derivs_history.pop()
                except Exception as e:
                    logger.debug("derivative history update failed: %s", e)
            else:
                if params_dict.get("VERBOSE_INSTRUMENTATION"):
                    logger.debug(
                        "DEBUG-INTEGRATOR: about to call integrate_ab with params_dict['INSTRUMENT_GROUPS']=%r",
                        params_dict.get("INSTRUMENT_GROUPS", None),
                    )
                state, new_deriv = integrate_ab(
                    state, derivs_history, params_dict, forcing_dict, fishing_dict, dt
                )
                # Fast equilibrium for NoIntegrate groups (matches Rpath SORWT=0.5)
                if np.any(no_integrate_mask):
                    from pypath.core.ecosim_deriv import compute_biomeq

                    QQ_ni = _compute_Q_matrix(params_dict, state, forcing_dict)
                    for i in range(1, len(state)):
                        if no_integrate_mask[i]:
                            total_gain = float(np.nansum(QQ_ni[:, i]))
                            total_loss = float(np.nansum(QQ_ni[i, :]))
                            total_loss += params_dict["M0"][i] * state[i]
                            state[i] = compute_biomeq(total_gain, total_loss, state[i])
                    new_deriv[no_integrate_mask] = 0.0
                derivs_history.insert(0, new_deriv)
                if len(derivs_history) > 1:
                    derivs_history.pop()
        else:
            # Unknown method: fallback to RK4 to be safe
            old_state = state.copy()
            state = integrate_rk4(state, params_dict, forcing_dict, fishing_dict, dt)
            if month == 1 and np.any(init_mask):
                state[init_mask] = old_state[init_mask]

        # Monthly M0 adjustment to enforce algebraic equilibrium for small residuals
        if not params_dict.get("MONTHLY_M0_ADJUST", False):
            if params_dict.get("VERBOSE_DEBUG"):
                logger.debug(
                    "skipping monthly M0 adjustment (disabled) for month=%s", month
                )
        else:
            try:
                if params_dict.get("VERBOSE_DEBUG"):
                    logger.debug(
                        "entering monthly M0 adjustment block for month=%s", month
                    )
                # Compute raw derivative with actual fishing to measure algebraic residual
                raw_init_deriv = deriv_vector(
                    state.copy(), params_dict, forcing_dict, fishing_dict
                )
                if params_dict.get("VERBOSE_DEBUG"):
                    logger.debug(
                        "computed raw_init_deriv sample %s", raw_init_deriv[:10]
                    )
                # Use the normalized fishing dict so we don't depend on dataclass vs dict
                fishing_mort = fishing_dict.get("FishingMort", np.zeros(n_groups))
                fish_from = fishing_dict.get("FishFrom", [])
                fish_q = fishing_dict.get("FishQ", np.array([0.0]))
                for i in range(1, len(fish_from)):
                    grp = int(fish_from[i])
                    fishing_mort[grp] += fish_q[i]

                for grp in range(1, params.NUM_GROUPS + 1):
                    if not (abs(raw_init_deriv[grp]) < ADJUST_DERIV_MAX):
                        continue
                    B = state[grp]
                    if B <= 0:
                        continue
                    QQbase = params_dict.get("QQbase")
                    consumption = (
                        float(np.nansum(QQbase[:, grp])) if QQbase is not None else 0.0
                    )
                    predation_loss = (
                        float(np.nansum(QQbase[grp, :])) if QQbase is not None else 0.0
                    )
                    PB = params_dict.get("PB")[grp]
                    QB = params_dict.get("QB")[grp]
                    PP_type = params_dict.get(
                        "PP_type", np.zeros(params.NUM_GROUPS + 1)
                    )
                    Bbase = params_dict.get("Bbase")
                    if PP_type[grp] > 0:
                        if Bbase is not None and Bbase[grp] > 0:
                            rel_bio = B / Bbase[grp]
                            dd_factor = max(0.0, 2.0 - rel_bio)
                            production = PB * B * dd_factor
                        else:
                            production = PB * B
                    elif QB > 0:
                        GE = PB / QB
                        production = GE * consumption
                    else:
                        production = PB * B
                    fish_loss = fishing_mort[grp] * B
                    current_m0 = float(params_dict.get("M0")[grp])
                    desired_m0 = current_m0 + float(raw_init_deriv[grp]) / B
                    diff = desired_m0 - current_m0
                    # Debug log
                    logger.debug(
                        "monthly grp=%s B=%.6e consumption=%.6e production=%.6e predation_loss=%.6e fish_loss=%.6e current_m0=%.6e desired_m0=%.6e diff=%.6e",
                        grp,
                        B,
                        consumption,
                        production,
                        predation_loss,
                        fish_loss,
                        current_m0,
                        desired_m0,
                        diff,
                    )
                    if np.isfinite(desired_m0) and abs(diff) <= M0_ADJUST_THRESHOLD:
                        # Iteratively refine monthly M0 similar to initialization
                        try:
                            params_iter = params_dict.copy()
                            params_iter["M0"] = params_dict["M0"].copy()
                            params_iter["M0"][grp] = desired_m0
                            params_dict["M0"][grp] = desired_m0
                            MAX_M0_ITER = 3
                            TOL_INIT_DERIV_ITER = 1e-10
                            for it in range(1, MAX_M0_ITER + 1):
                                try:
                                    init_deriv_iter = deriv_vector(
                                        state.copy(),
                                        params_iter,
                                        forcing_dict,
                                        fishing_dict,
                                    )
                                    residual = float(init_deriv_iter[grp])
                                    if abs(residual) < TOL_INIT_DERIV_ITER:
                                        break
                                    step = residual / B
                                    if abs(step) > M0_ADJUST_THRESHOLD:
                                        step = np.sign(step) * M0_ADJUST_THRESHOLD
                                    params_iter["M0"][grp] += step
                                    params_dict["M0"][grp] = params_iter["M0"][grp]
                                except Exception as e:
                                    logger.debug("monthly M0 iteration failed: %s", e)
                                    break
                            if params_dict.get("VERBOSE_DEBUG"):
                                logger.debug(
                                    "monthly assigned M0 grp=%s new_m0=%.6e",
                                    grp,
                                    params_dict["M0"][grp],
                                )
                        except Exception as e:
                            logger.debug("monthly M0 assignment failed: %s", e)
                            params_dict["M0"][grp] = desired_m0
                            if params_dict.get("VERBOSE_DEBUG"):
                                logger.debug(
                                    "monthly assigned M0 grp=%s new_m0=%.6e",
                                    grp,
                                    params_dict["M0"][grp],
                                )
            except Exception as e:
                logger.debug("monthly M0 adjustment failed: %s", e)

        # NoIntegrate groups: for RK4, hold at baseline (no biomeq available);
        # for AB, biomeq was already applied in the integration branch above.
        if method.upper() != "AB":
            try:
                Bbase = params_dict.get("Bbase")
                if Bbase is not None and np.any(no_integrate_mask):
                    state[no_integrate_mask] = Bbase[no_integrate_mask]
            except Exception as e:
                logger.debug("NoIntegrate application failed: %s", e)

        # Replace invalid numeric values to prevent NaN/inf runaway and
        # ensure non-negative biomass
        state = np.where(np.isfinite(state), state, EPSILON)
        state = np.maximum(state, EPSILON)

        # Update stanza groups (age structure dynamics)
        if scenario.stanzas is not None and scenario.stanzas.n_split > 0:
            # Update state in a temporary state object
            temp_state = RsimState(
                Biomass=state.copy(),
                N=np.zeros_like(state),
                Ftime=forcing_dict["Ftime"],
            )
            # Call stanza update for this month
            split_update(scenario.stanzas, temp_state, params, month)
            # Update predation rates based on new stanza structure
            split_set_pred(scenario.stanzas, temp_state, params)
            # Note: Biomass redistribution among stanza groups handled in split_update

            # Record stanza-resolved biomass for this month
            for isp in range(1, scenario.stanzas.n_split + 1):
                nst = scenario.stanzas.n_stanzas[isp]
                for ist in range(1, nst + 1):
                    ieco = int(scenario.stanzas.ecopath_code[isp, ist])
                    first = int(scenario.stanzas.age1[isp, ist])
                    last = int(scenario.stanzas.age2[isp, ist])
                    bio = np.nansum(
                        scenario.stanzas.base_nage_s[first : last + 1, isp]
                        * scenario.stanzas.base_wage_s[first : last + 1, isp]
                    )
                    if ieco >= 0 and ieco < n_groups and stanza_biomass is not None:
                        stanza_biomass[month, ieco] += bio

        # Check for crash (biomass < threshold)
        # Use more reasonable threshold to avoid false alarms from numerical noise
        if crash_year < 0:
            low_biomass_groups = np.where(
                state[1 : params.NUM_LIVING + 1] < crash_threshold
            )[0]
            if len(low_biomass_groups) > 0:
                # Record first crash year
                crash_year = year_idx + scenario.start_year
                # Track which groups crashed
                for grp_idx in low_biomass_groups:
                    crashed_groups.add(grp_idx + 1)  # +1 because we sliced from index 1

        # For non-AB methods, enforce NoIntegrate after stanza updates
        if method.upper() != "AB" and np.any(no_integrate_mask):
            Bbase = params_dict.get("Bbase")
            if Bbase is not None:
                state[no_integrate_mask] = Bbase[no_integrate_mask]

        # Store results
        out_biomass[month] = state

        # Compute consumption QQ matrix for this month to track Qlinks
        QQ_month = _compute_Q_matrix(params_dict, state, forcing_dict)
        # Ecotracer step (after biomass integration and Q computation)
        if _ecotracer_conc is not None:
            n_eco = len(_ecotracer_conc)
            eco_biomass = state[1 : n_eco + 1]
            eco_Q = QQ_month[1 : n_eco + 1, 1 : n_eco + 1]
            # detritus_fate=None for now (Phase 1 simplification)
            _ecotracer_conc = _ecotracer_step_fn(
                _ecotracer_conc,
                eco_biomass,
                eco_Q,
                ecotracer,
                dt=1.0 / 12,
                detritus_fate=None,
                n_living=params.NUM_LIVING,
            )
            _ecotracer_out[month] = _ecotracer_conc.copy()
        # Dynamic Ftime adjustment: Rpath formula (ecosim.cpp)
        # new_Ftime = 0.1 + 0.9*Ft*((1-adj) + adj*QBopt/(FoodGain/B)), cap 2.0
        if _has_ftime_adj:
            for i in range(1, params.NUM_LIVING + 1):
                if _ftime_adj[i] > 0 and state[i] > 0 and _ftime_qbopt[i] > 0:
                    food_gain = float(np.nansum(QQ_month[:, i]))
                    _ftime_current[i] = _ftime_update_rpath(
                        _ftime_current[i],
                        _ftime_adj[i],
                        _ftime_qbopt[i],
                        food_gain,
                        state[i],
                    )
        # Accumulate monthly Q (converted to monthly by dividing by 12)
        if annual_qlink is not None:
            for li in range(len(params.PreyFrom)):
                prey = params.PreyFrom[li]
                pred = params.PreyTo[li]
                if prey < QQ_month.shape[0] and pred < QQ_month.shape[1]:
                    annual_qlink[year_idx, li] += QQ_month[prey, pred] / 12.0

        # Calculate catch for this month
        for i in range(1, len(params.FishFrom)):
            grp = params.FishFrom[i]
            gear_group_idx = params.FishThrough[i]
            # Convert group-based gear index to gear array index
            gear_0based = int(gear_group_idx) - 1
            if _run_gear_lookup:
                gear_idx = _run_gear_lookup.get(gear_0based, 0)
            else:
                gear_idx = int(gear_group_idx - params.NUM_LIVING - params.NUM_DEAD)
            effort_mult = (
                forcing_dict["ForcedEffort"][gear_idx]
                if 0 < gear_idx < len(forcing_dict["ForcedEffort"])
                else 1.0
            )
            catch = params.FishQ[i] * state[grp] * effort_mult / 12.0
            # Debug log to trace catch computation for early months
            try:
                if month <= 2:
                    logger.debug(
                        "month=%s link=%s grp=%s FishQ=%.6e effort_mult=%.6e state=%.6e catch=%.6e",
                        month,
                        i,
                        grp,
                        params.FishQ[i],
                        effort_mult,
                        state[grp],
                        catch,
                    )
            except Exception as e:
                logger.debug("catch computation debug failed: %s", e)
            out_catch[month, grp] += catch
            out_gear_catch[month, i] = catch

        # Fleet dynamics step (after catch computation)
        if _fleet_capacity is not None:
            # Reset cumulative catch at year boundary (BEFORE accumulation)
            month_in_year = (month - 1) % 12
            if month_in_year == 0 and month > 1:
                _fleet_cumul_catch[:] = 0.0
                # Restore original FishQ so all links reopen for new quota year
                params.FishQ = _original_fish_q.copy()

            # Accumulate catch into cumulative tracker by fleet and group
            for i in range(1, len(params.FishFrom)):
                gear_group_idx = params.FishThrough[i]
                gear_0based = int(gear_group_idx) - 1
                if _run_gear_lookup:
                    gear_idx = _run_gear_lookup.get(gear_0based, 0)
                else:
                    gear_idx = int(gear_group_idx - params.NUM_LIVING - params.NUM_DEAD)
                fleet_0 = gear_idx - 1
                group_0 = int(params.FishFrom[i]) - 1
                if 0 <= fleet_0 < _n_fd_fleets and 0 <= group_0 < params.NUM_GROUPS:
                    _fleet_cumul_catch[fleet_0, group_0] += out_gear_catch[month, i]

            # Update capacity and effort
            _fleet_capacity, _fleet_effort = _fleet_step_fn(
                _fleet_capacity,
                out_gear_catch[month],
                _fleet_cumul_catch,
                fleet_dynamics,
                params.FishThrough,
                params.FishFrom,
                _run_gear_lookup,
                n_fleets=_n_fd_fleets,
            )

            # Write effort into ForcedEffort for next month
            if month < n_months:
                fishing_obj.ForcedEffort[month, 1 : _n_fd_fleets + 1] = _fleet_effort

            # Apply quota caps if TAC is set
            if fleet_dynamics.tac is not None:
                capped_q = _fleet_quota_fn(
                    params.FishQ,
                    _fleet_cumul_catch,
                    fleet_dynamics.tac,
                    params.FishThrough,
                    params.FishFrom,
                    _run_gear_lookup,
                )
                params.FishQ = capped_q
                fishing_dict["FishQ"] = capped_q  # propagate to derivative

            # Store results — compute revenue/cost/profit for output
            _revenue = np.zeros(_n_fd_fleets)
            for i in range(1, len(params.FishThrough)):
                gear_group_idx = params.FishThrough[i]
                gear_0based = int(gear_group_idx) - 1
                if _run_gear_lookup:
                    gear_idx = _run_gear_lookup.get(gear_0based, 0)
                else:
                    gear_idx = int(gear_group_idx - params.NUM_LIVING - params.NUM_DEAD)
                fleet_0 = gear_idx - 1
                if 0 <= fleet_0 < _n_fd_fleets and i < len(fleet_dynamics.price):
                    _revenue[fleet_0] += (
                        out_gear_catch[month, i] * fleet_dynamics.price[i]
                    )

            _cost = np.zeros(_n_fd_fleets)
            for g in range(_n_fd_fleets):
                _cost[g] = (
                    fleet_dynamics.fixed_cost[g] / 12.0
                    + (fleet_dynamics.variable_cost[g] + fleet_dynamics.sailing_cost[g])
                    * _fleet_capacity[g]
                )

            _fleet_out_effort[month] = _fleet_effort
            _fleet_out_revenue[month] = _revenue
            _fleet_out_cost[month] = _cost
            _fleet_out_profit[month] = _revenue - _cost

    # Calculate annual values
    annual_biomass = np.zeros((n_years, n_groups))
    annual_catch = np.zeros((n_years, n_groups))
    annual_qb = np.zeros((n_years, n_groups))

    for yr in range(n_years):
        start_m = yr * 12 + 1
        end_m = (yr + 1) * 12 + 1
        annual_biomass[yr] = np.mean(out_biomass[start_m:end_m], axis=0)
        annual_catch[yr] = np.sum(out_catch[start_m:end_m], axis=0)

    # If Qlink accumulation was tracked, ensure shape is set
    if "annual_qlink" not in locals():
        annual_qlink = np.zeros((n_years, len(params.PreyFrom)))

    # If stanza_biomass was not computed (no stanzas), set to None
    if stanza_biomass is None:
        stanza_biomass_out = None
    else:
        stanza_biomass_out = stanza_biomass

    # Ecotracer annual averaging
    _ecotracer_result = None
    if _ecotracer_out is not None:
        from pypath.core.ecotracer import EcotracerResult

        n_eco_groups = _ecotracer_out.shape[1]
        annual_conc = np.zeros((n_years, n_eco_groups))
        for yr in range(n_years):
            start_m = yr * 12 + 1
            end_m = (yr + 1) * 12 + 1
            annual_conc[yr] = np.mean(_ecotracer_out[start_m:end_m], axis=0)

        group_names = [params.spname[i] for i in range(1, n_eco_groups + 1)]
        _ecotracer_result = EcotracerResult(
            out_Conc=_ecotracer_out,
            annual_Conc=annual_conc,
            group_names=group_names,
        )

    # Fleet dynamics annual averaging
    _fleet_result = None
    if _fleet_out_effort is not None:
        from pypath.core.fleet_dynamics import FleetDynamicsResult

        annual_effort = np.zeros((n_years, _n_fd_fleets))
        annual_profit = np.zeros((n_years, _n_fd_fleets))
        for yr in range(n_years):
            start_m = yr * 12 + 1
            end_m = (yr + 1) * 12 + 1
            annual_effort[yr] = np.mean(_fleet_out_effort[start_m:end_m], axis=0)
            annual_profit[yr] = np.sum(_fleet_out_profit[start_m:end_m], axis=0)

        fleet_names = []
        if hasattr(params, "fleet_idx") and params.fleet_idx is not None:
            for fi in params.fleet_idx:
                idx_1based = int(fi) + 1
                if idx_1based < len(params.spname):
                    fleet_names.append(params.spname[idx_1based])
                else:
                    fleet_names.append(f"Fleet{idx_1based}")
        else:
            fleet_names = [f"Fleet{i + 1}" for i in range(_n_fd_fleets)]

        _fleet_result = FleetDynamicsResult(
            out_Effort=_fleet_out_effort,
            out_Revenue=_fleet_out_revenue,
            out_Cost=_fleet_out_cost,
            out_Profit=_fleet_out_profit,
            annual_Effort=annual_effort,
            annual_Profit=annual_profit,
            fleet_names=fleet_names,
        )

    # Create end state
    end_state = RsimState(
        Biomass=state.copy(),
        N=np.zeros(n_groups),
        Ftime=scenario.start_state.Ftime.copy(),
    )

    # Build predator-prey identifiers for output
    pred_names = np.array(
        [params.spname[params.PreyTo[i]] for i in range(len(params.PreyTo))]
    )
    prey_names = np.array(
        [params.spname[params.PreyFrom[i]] for i in range(len(params.PreyFrom))]
    )

    # Gear catch identifiers
    gear_catch_sp = np.array(
        [params.spname[params.FishFrom[i]] for i in range(len(params.FishFrom))]
    )
    gear_catch_gear = np.array(
        [
            (
                params.spname[params.FishThrough[i]]
                if params.FishThrough[i] < len(params.spname)
                else f"Gear{params.FishThrough[i]}"
            )
            for i in range(len(params.FishThrough))
        ]
    )
    gear_catch_disp = np.where(params.FishTo == 0, "Landings", "Discards")

    # Return full monthly time series including the initial snapshot (index 0).
    # Tests and downstream code expect the initial state to be included as row 0.

    return RsimOutput(
        out_Biomass=out_biomass,
        out_Catch=out_catch,
        out_Gear_Catch=out_gear_catch,
        annual_Biomass=annual_biomass,
        annual_Catch=annual_catch,
        annual_QB=annual_qb,
        annual_Qlink=annual_qlink,
        stanza_biomass=stanza_biomass_out,
        end_state=end_state,
        crash_year=crash_year,
        crashed_groups=crashed_groups,
        pred=pred_names,
        prey=prey_names,
        Gear_Catch_sp=gear_catch_sp,
        Gear_Catch_gear=gear_catch_gear,
        Gear_Catch_disp=gear_catch_disp,
        start_state=copy.deepcopy(scenario.start_state),
        params={
            "NUM_GROUPS": params.NUM_GROUPS,
            "NUM_LIVING": params.NUM_LIVING,
            "years": n_years,
        },
        ecotracer=_ecotracer_result,
        fleet_dynamics=_fleet_result,
    )

ODE Derivatives

The consumption kernel and derivative vector used by the Ecosim ODE solver.

Key functions:

• deriv_vector() — compute dB/dt for all groups at a given state
• _compute_consumption_python() — foraging arena consumption matrix (Rpath-compatible)
• compute_biomeq() — fast equilibrium for NoIntegrate groups
• integrate_rk4() — single RK4 step
• integrate_ab() — single AB2 step with Rpath-style biomass bounds

pypath.core.ecosim_deriv

Ecosim derivative calculation and integration routines.

This module contains the core numerical routines for Ecosim simulation: - deriv_vector: Calculate derivatives for all state variables - RK4 and Adams-Bashforth integration methods - Prey switching and mediation functions - Primary production forcing

These are ported from the C++ ecosim.cpp file in Rpath.

SimState dataclass

Current state of the simulation.

Source code in pypath/core/ecosim_deriv.py

@dataclass
class SimState:
    """Current state of the simulation."""

    # Biomass and related state variables (indexed 0 to NUM_GROUPS)
    Biomass: np.ndarray  # Current biomass
    Ftime: np.ndarray  # Fishing time forcing

    # Consumption tracking
    QQ: np.ndarray  # Consumption Q[prey, pred] matrix

    # Forcing arrays
    force_bybio: np.ndarray  # Biomass forcing
    force_byprey: np.ndarray  # Prey-specific forcing

prey_switching

prey_switching(BB: ndarray, Bbase: ndarray, pred: int, ActiveLink: ndarray, switch_power: float = 2.0) -> np.ndarray

Calculate prey switching factors.

Prey switching occurs when predators preferentially consume more abundant prey, stabilizing the system. Uses a power function of relative abundance.

Parameters:

Name	Type	Description	Default
BB	ndarray	Current biomass array	required
Bbase	ndarray	Baseline biomass array	required
pred	int	Predator index	required
ActiveLink	ndarray	Active link matrix [prey, pred]	required
switch_power	float	Prey switching power (default 2.0, range 0-2) - 0: No switching - 1: Linear switching - 2: Strong switching (Murdoch switching)	2.0

Returns:

Type	Description
ndarray	Switching factors for each prey (indexed by prey)

Source code in pypath/core/ecosim_deriv.py

def prey_switching(
    BB: np.ndarray,
    Bbase: np.ndarray,
    pred: int,
    ActiveLink: np.ndarray,
    switch_power: float = 2.0,
) -> np.ndarray:
    """
    Calculate prey switching factors.

    Prey switching occurs when predators preferentially consume more abundant
    prey, stabilizing the system. Uses a power function of relative abundance.

    Parameters
    ----------
    BB : np.ndarray
        Current biomass array
    Bbase : np.ndarray
        Baseline biomass array
    pred : int
        Predator index
    ActiveLink : np.ndarray
        Active link matrix [prey, pred]
    switch_power : float
        Prey switching power (default 2.0, range 0-2)
        - 0: No switching
        - 1: Linear switching
        - 2: Strong switching (Murdoch switching)

    Returns
    -------
    np.ndarray
        Switching factors for each prey (indexed by prey)
    """
    n_groups = len(BB)
    switch_factor = np.ones(n_groups)

    if switch_power <= 0:
        return switch_factor

    # Sum of relative prey abundance for this predator
    total_rel = 0.0
    n_active = 0
    for prey in range(1, n_groups):
        if ActiveLink[prey, pred] and Bbase[prey] > 0:
            total_rel += (BB[prey] / Bbase[prey]) ** switch_power
            n_active += 1

    if total_rel <= 0:
        return switch_factor

    # Calculate switching factor for each prey
    for prey in range(1, n_groups):
        if ActiveLink[prey, pred] and Bbase[prey] > 0:
            rel_abund = (BB[prey] / Bbase[prey]) ** switch_power
            switch_factor[prey] = rel_abund / total_rel * n_active

    return switch_factor

mediation_function

mediation_function(mediation_type: int, med_bio: float, med_base: float, med_params: Dict[str, float]) -> float

.. deprecated:: Use :class:pypath.core.mediation.MediationShape and its evaluate() method instead. This function is kept for backward compatibility.

Calculate mediation effect on predation.

Mediation allows a third party (mediator) to affect the predator-prey interaction, representing effects like habitat provision or fear.

Parameters:

Name	Type	Description	Default
mediation_type	int	Type of mediation function: - 0: No mediation (returns 1.0) - 1: Positive mediation (more mediator = more predation) - 2: Negative mediation (more mediator = less predation) - 3: U-shaped (optimal at intermediate mediator biomass)	required
med_bio	float	Current mediator biomass	required
med_base	float	Baseline mediator biomass	required
med_params	dict	Parameters including 'low', 'high', 'shape'	required

Returns:

Type	Description
float	Mediation multiplier (>0)

Source code in pypath/core/ecosim_deriv.py

def mediation_function(
    mediation_type: int, med_bio: float, med_base: float, med_params: Dict[str, float]
) -> float:
    """.. deprecated::
        Use :class:`pypath.core.mediation.MediationShape` and its ``evaluate()``
        method instead. This function is kept for backward compatibility.

    Calculate mediation effect on predation.

    Mediation allows a third party (mediator) to affect the predator-prey
    interaction, representing effects like habitat provision or fear.

    Parameters
    ----------
    mediation_type : int
        Type of mediation function:
        - 0: No mediation (returns 1.0)
        - 1: Positive mediation (more mediator = more predation)
        - 2: Negative mediation (more mediator = less predation)
        - 3: U-shaped (optimal at intermediate mediator biomass)
    med_bio : float
        Current mediator biomass
    med_base : float
        Baseline mediator biomass
    med_params : dict
        Parameters including 'low', 'high', 'shape'

    Returns
    -------
    float
        Mediation multiplier (>0)
    """
    if mediation_type == 0 or med_base <= 0:
        return 1.0

    low = med_params.get("low", 0.5)
    high = med_params.get("high", 2.0)
    shape = med_params.get("shape", 1.0)

    x = med_bio / med_base  # Relative biomass

    if mediation_type == 1:  # Positive mediation
        # Saturating increase
        med_mult = low + (high - low) * (x**shape) / (1.0 + x**shape)
    elif mediation_type == 2:  # Negative mediation
        # Saturating decrease
        med_mult = high - (high - low) * (x**shape) / (1.0 + x**shape)
    elif mediation_type == 3:  # U-shaped
        # Optimal at x=1, declines at extremes
        diff = abs(x - 1.0)
        med_mult = high - (high - low) * (diff**shape) / (1.0 + diff**shape)
    else:
        med_mult = 1.0

    return max(med_mult, 0.001)  # Ensure positive

primary_production_forcing

primary_production_forcing(BB: ndarray, Bbase: ndarray, PB: ndarray, PP_forcing: ndarray, PP_type: ndarray, NUM_LIVING: int) -> np.ndarray

Calculate primary production with environmental forcing.

In Ecosim/Rpath, primary producers use density-dependent production to ensure stability. The production rate decreases as biomass increases above baseline, mimicking nutrient limitation.

Parameters:

Name	Type	Description	Default
BB	ndarray	Current biomass	required
Bbase	ndarray	Baseline biomass	required
PB	ndarray	Production/biomass ratios	required
PP_forcing	ndarray	Primary production forcing multipliers by group	required
PP_type	ndarray	Producer type by group: - 0: Not a producer (consumer) - 1: Primary producer (density-dependent, default) - 2: Detritus (no production)	required
NUM_LIVING	int	Number of living groups	required

Returns:

Type	Description
ndarray	Primary production rates

Source code in pypath/core/ecosim_deriv.py

def primary_production_forcing(
    BB: np.ndarray,
    Bbase: np.ndarray,
    PB: np.ndarray,
    PP_forcing: np.ndarray,
    PP_type: np.ndarray,
    NUM_LIVING: int,
) -> np.ndarray:
    """
    Calculate primary production with environmental forcing.

    In Ecosim/Rpath, primary producers use density-dependent production
    to ensure stability. The production rate decreases as biomass
    increases above baseline, mimicking nutrient limitation.

    Parameters
    ----------
    BB : np.ndarray
        Current biomass
    Bbase : np.ndarray
        Baseline biomass
    PB : np.ndarray
        Production/biomass ratios
    PP_forcing : np.ndarray
        Primary production forcing multipliers by group
    PP_type : np.ndarray
        Producer type by group:
        - 0: Not a producer (consumer)
        - 1: Primary producer (density-dependent, default)
        - 2: Detritus (no production)
    NUM_LIVING : int
        Number of living groups

    Returns
    -------
    np.ndarray
        Primary production rates
    """
    n_groups = len(BB)
    production = np.zeros(n_groups)

    for i in range(1, min(NUM_LIVING + 1, n_groups)):
        if PP_type[i] == 0:
            # Not a producer - production calculated from consumption
            continue
        elif PP_type[i] == 1:
            # Primary producer: density-dependent production
            # In Rpath/EwE, this follows: P = PB * B * forcing * (2 - B/Bbase)
            # This gives equilibrium at B = Bbase when forcing = 1
            # and ensures stability by reducing growth as B increases
            if Bbase[i] > 0:
                rel_bio = BB[i] / Bbase[i]
                # Production is PB * B at baseline, decreases as B increases
                # This factor = 2 - rel_bio ensures:
                # - At B = Bbase: factor = 1.0, production = PB * B
                # - At B = 2*Bbase: factor = 0.0, production = 0
                # - At B = 0: factor = 2.0, production = 2 * PB * B (rapid recovery)
                dd_factor = max(0, 2.0 - rel_bio)
                production[i] = PB[i] * BB[i] * PP_forcing[i] * dd_factor
            else:
                production[i] = PB[i] * BB[i] * PP_forcing[i]
        # PP_type == 2 is detritus, no production

    return production

deriv_vector

deriv_vector(state: ndarray, params: dict, forcing: dict, fishing: dict, t: float = 0.0) -> np.ndarray

Calculate derivatives for all state variables in Ecosim.

This is the core function that implements the Ecosim differential equations based on foraging arena theory with prey switching and mediation support.

The functional response is: C_ij = (a_ij * v_ij * B_i * B_j * T_j * S_ij * D_j * M_ij) / (v_ij + v_ijT_jD_j + a_ijB_jD_j + a_ijd_ijB_j*D_j^2)

Where: a_ij = base search rate (from QQ/BB setup) v_ij = vulnerability exchange rate B_i = prey biomass B_j = predator biomass T_j = time forcing on predator S_ij = prey switching factor D_j = handling time factor d_ij = handling time for this link M_ij = mediation multiplier

Parameters:

Name	Type	Description	Default
state	ndarray	Current state vector (biomass values) indexed 0 to NUM_GROUPS	required
params	dict	Model parameters containing: - NUM_GROUPS: Total number of groups - NUM_LIVING: Number of living groups - NUM_DEAD: Number of detritus groups - NUM_GEARS: Number of fishing gears - PB: Production/Biomass ratios - QB: Consumption/Biomass ratios - ActiveLink: Boolean array [prey, pred] of active links - DC: Diet composition matrix [prey, pred] - VV: Vulnerability parameters [prey, pred] - DD: Handling time parameters [prey, pred] - Bbase: Baseline biomass [group] - DetFrac: Fraction to detritus [group] - Unassim: Unassimilated fraction [group] - SwitchPower: Prey switching power (0-2, default 0) - PP_type: Producer type array [group] - Mediation: Mediation configuration dict	required
forcing	dict	Forcing arrays: - ForcedBio: Forced biomass values [group] - ForcedMigrate: Migration forcing [group] - ForcedCatch: Forced catch [group] - ForcedEffort: Forced effort [gear] - PP_forcing: Primary production forcing [group] - Ftime: Time forcing [group]	required
fishing	dict	Fishing parameters: - FishingMort: Base fishing mortality [group] - EffortCap: Effort cap [gear]	required
t	float	Current time (for time-varying forcing)	0.0

Returns:

Type	Description
ndarray	Derivative vector (dB/dt for each group)

Source code in pypath/core/ecosim_deriv.py

def deriv_vector(
    state: np.ndarray, params: dict, forcing: dict, fishing: dict, t: float = 0.0
) -> np.ndarray:
    """
    Calculate derivatives for all state variables in Ecosim.

    This is the core function that implements the Ecosim differential equations
    based on foraging arena theory with prey switching and mediation support.

    The functional response is:
        C_ij = (a_ij * v_ij * B_i * B_j * T_j * S_ij * D_j * M_ij) /
               (v_ij + v_ij*T_j*D_j + a_ij*B_j*D_j + a_ij*d_ij*B_j*D_j^2)

    Where:
        a_ij = base search rate (from QQ/BB setup)
        v_ij = vulnerability exchange rate
        B_i = prey biomass
        B_j = predator biomass
        T_j = time forcing on predator
        S_ij = prey switching factor
        D_j = handling time factor
        d_ij = handling time for this link
        M_ij = mediation multiplier

    Parameters
    ----------
    state : np.ndarray
        Current state vector (biomass values) indexed 0 to NUM_GROUPS
    params : dict
        Model parameters containing:
        - NUM_GROUPS: Total number of groups
        - NUM_LIVING: Number of living groups
        - NUM_DEAD: Number of detritus groups
        - NUM_GEARS: Number of fishing gears
        - PB: Production/Biomass ratios
        - QB: Consumption/Biomass ratios
        - ActiveLink: Boolean array [prey, pred] of active links
        - DC: Diet composition matrix [prey, pred]
        - VV: Vulnerability parameters [prey, pred]
        - DD: Handling time parameters [prey, pred]
        - Bbase: Baseline biomass [group]
        - DetFrac: Fraction to detritus [group]
        - Unassim: Unassimilated fraction [group]
        - SwitchPower: Prey switching power (0-2, default 0)
        - PP_type: Producer type array [group]
        - Mediation: Mediation configuration dict
    forcing : dict
        Forcing arrays:
        - ForcedBio: Forced biomass values [group]
        - ForcedMigrate: Migration forcing [group]
        - ForcedCatch: Forced catch [group]
        - ForcedEffort: Forced effort [gear]
        - PP_forcing: Primary production forcing [group]
        - Ftime: Time forcing [group]
    fishing : dict
        Fishing parameters:
        - FishingMort: Base fishing mortality [group]
        - EffortCap: Effort cap [gear]
    t : float
        Current time (for time-varying forcing)

    Returns
    -------
    np.ndarray
        Derivative vector (dB/dt for each group)
    """
    NUM_GROUPS = params["NUM_GROUPS"]
    NUM_LIVING = params["NUM_LIVING"]
    NUM_DEAD = params["NUM_DEAD"]
    NUM_GEARS = params.get("NUM_GEARS", 0)

    # Initialize output arrays
    deriv = np.zeros(NUM_GROUPS + 1)  # +1 for 0-indexing with outside

    # Extract parameters
    PB = params["PB"]
    QB = params.get("QB", np.zeros(NUM_GROUPS + 1))
    ActiveLink = params["ActiveLink"]
    VV = params["VV"]
    DD = params["DD"]
    Unassim = params.get("Unassim", np.zeros(NUM_GROUPS + 1))
    Bbase = params.get("Bbase", state.copy())  # Baseline biomass
    _SwitchPower = params.get("SwitchPower", 0.0)  # Prey switching power
    PP_type = params.get("PP_type", np.zeros(NUM_GROUPS + 1, dtype=int))
    _mediation = params.get("_mediation", None)
    # Pre-fetch spname and M0 once to avoid repeated dict lookups and
    # default-argument allocations ([None]*N, np.zeros) inside inner loops.
    spname_list = params.get("spname", None)
    M0_arr = params.get("M0", None)
    _NoIntegrate_raw = params.get("NoIntegrate", None)
    _TRACE_DEBUG_GROUPS = params.get("TRACE_DEBUG_GROUPS", None)

    # Current biomass (state variable)
    BB = state.copy()

    # Enforce NoIntegrate algebraic groups in stage evaluations
    # Some groups are marked 'NoIntegrate' to represent algebraic equilibria
    # (fast turnover). Ensure derivative evaluations always see these at
    # their baseline Bbase value so intermediate RK4 stages don't pollute
    # predation/functional response calculations.
    try:
        no_integrate_mask = (
            np.asarray(
                _NoIntegrate_raw
                if _NoIntegrate_raw is not None
                else np.zeros(NUM_GROUPS + 1)
            )
            != 0
        )
        if np.any(no_integrate_mask):
            Bbase_arr = params.get("Bbase", None)
            if Bbase_arr is not None:
                # apply baseline values for NoIntegrate groups to the local BB
                # (BB is already a copy from state.copy() above)
                BB[no_integrate_mask] = Bbase_arr[no_integrate_mask]
    except (TypeError, ValueError, IndexError):
        pass

    instrument_set = _resolve_instrument_groups(params, spname_list, NUM_GROUPS)

    # Initialize consumption matrix
    QQ = np.zeros((NUM_GROUPS + 1, NUM_GROUPS + 1))

    # =========================================================================
    # STEP 1: Calculate predation pressure from each predator on each prey
    # Using foraging arena functional response with prey switching
    #
    # From Rpath ecosim.cpp (vectorized version):
    # Q = QQ * PDY * pow(PYY, HandleSwitch * COUPLED) *
    #     ( DD / ( DD-1.0 + pow((1-Hself)*PYY + Hself*PySuite, HandleSwitch*COUPLED)) ) *
    #     ( VV / ( VV-1.0 + (1-Sself)*PDY + Sself*PdSuite) );
    #
    # Where:
    #   QQ = base consumption rate (DC * QB * Bpred_baseline)
    #   PDY = predYY = Ftime * Bpred / Bpred_baseline (relative predator biomass)
    #   PYY = preyYY = Bprey / Bprey_baseline * force_byprey (relative prey biomass)
    #   DD = handling time (large = no handling time effect, approaching 1.0)
    #   VV = vulnerability (large = no density dependence)
    # =========================================================================

    # Get time-varying forcing (default to 1.0)
    Ftime = forcing.get("Ftime", np.ones(NUM_GROUPS + 1))
    ForcedBio = forcing.get("ForcedBio", np.zeros(NUM_GROUPS + 1))
    PP_forcing = forcing.get("PP_forcing", np.ones(NUM_GROUPS + 1))
    ForcedPrey = forcing.get("ForcedPrey", np.ones(NUM_GROUPS + 1))
    ForcedMigrate = forcing.get("ForcedMigrate", np.zeros(NUM_GROUPS + 1))

    # Calculate relative biomass arrays (vectorized)
    # preyYY = Ftime * B / Bbase * prey_forcing (where Bbase > 0)
    # Ftime is applied to both preyYY and predYY to match Rpath C++ ecosim.cpp
    safe_bbase = np.where(Bbase > 0, Bbase, 1.0)
    preyYY = np.zeros(NUM_GROUPS + 1)
    preyYY[1:] = np.where(
        Bbase[1:] > 0,
        Ftime[1:] * BB[1:] / safe_bbase[1:] * ForcedPrey[1:],
        0.0,
    )

    # predYY = Ftime * B / Bbase (where Bbase > 0, living groups only)
    predYY = np.zeros(NUM_GROUPS + 1)
    sl = slice(1, NUM_LIVING + 1)
    predYY[sl] = np.where(
        Bbase[sl] > 0,
        Ftime[sl] * BB[sl] / safe_bbase[sl],
        0.0,
    )

    # Get base consumption matrix
    QQbase = params.get("QQbase", np.zeros((NUM_GROUPS + 1, NUM_GROUPS + 1)))

    # Extract suite-pooling parameters (None means old behaviour / no pooling)
    _ScrambleSelf = params.get("ScrambleSelf")
    _HandleSelf = params.get("HandleSelf")
    _PredPredWeight = params.get("PredPredWeight")
    _PreyPreyWeight = params.get("PreyPreyWeight")
    _HandleSwitch = params.get("HandleSwitch")
    _COUPLED = params.get("COUPLED", 1)

    # Compute mediation multipliers (if mediation functions are configured)
    _med_multipliers = None
    if _mediation is not None:
        _med_multipliers = _mediation.compute_group_multipliers(BB, Bbase, ActiveLink)

    # Compute fleet mediation multipliers (applied to fishing effort per gear)
    _fleet_med = None
    if _mediation is not None:
        _fleet_med = _mediation.compute_fleet_multipliers(BB, Bbase, NUM_GEARS)

    # Compute consumption matrix via pure-Python kernel.
    # Use pre-computed sparse link arrays when available (avoids iterating
    # over inactive links); otherwise fall back to the dense kernel.
    _link_prey = params.get("_link_prey", None)
    _link_pred = params.get("_link_pred", None)
    if _link_prey is not None and _link_pred is not None:
        _compute_consumption_sparse(
            QQ,
            BB,
            VV,
            DD,
            QQbase,
            preyYY,
            predYY,
            _link_prey,
            _link_pred,
            len(_link_prey),
            ScrambleSelf=_ScrambleSelf,
            HandleSelf=_HandleSelf,
            PredPredWeight=_PredPredWeight,
            PreyPreyWeight=_PreyPreyWeight,
            HandleSwitch=_HandleSwitch,
            COUPLED=_COUPLED,
            med_multipliers=_med_multipliers,
        )
    else:
        # ActiveLink may be a boolean array; ensure it is integer for numba compat.
        _active_int = (
            ActiveLink.astype(np.int64) if ActiveLink.dtype != np.int64 else ActiveLink
        )
        _compute_consumption(
            QQ,
            BB,
            _active_int,
            VV,
            DD,
            QQbase,
            preyYY,
            predYY,
            NUM_LIVING,
            NUM_GROUPS,
            ScrambleSelf=_ScrambleSelf,
            HandleSelf=_HandleSelf,
            PredPredWeight=_PredPredWeight,
            PreyPreyWeight=_PreyPreyWeight,
            HandleSwitch=_HandleSwitch,
            COUPLED=_COUPLED,
            med_multipliers=_med_multipliers,
        )

    # Post-loop instrumentation: log per-link breakdown for interesting groups
    if instrument_set:
        try:
            for pred in range(1, NUM_LIVING + 1):
                for prey in range(1, NUM_GROUPS + 1):
                    if QQ[prey, pred] <= 0.0:
                        continue
                    prey0 = prey - 1
                    pred0 = pred - 1
                    if prey0 in instrument_set or pred0 in instrument_set:
                        pname = spname_list[prey] if spname_list is not None else None
                        prname = spname_list[pred] if spname_list is not None else None
                        qbase = QQbase[prey, pred]
                        PYY = preyYY[prey]
                        PDY = predYY[pred]
                        dd = DD[prey, pred]
                        vv = VV[prey, pred]
                        dd_term = dd / (dd - 1.0 + max(PYY, 1e-10)) if dd > 1.0 else 1.0
                        vv_term = vv / (vv - 1.0 + max(PDY, 1e-10)) if vv > 1.0 else 1.0
                        logger.debug(
                            "INSTR Q prey=%s name=%s pred=%s name=%s qbase=%.6e PDY=%.6e PYY=%.6e dd_term=%.6e vv_term=%.6e Q_calc=%.6e",
                            prey,
                            pname,
                            pred,
                            prname,
                            qbase,
                            PDY,
                            PYY,
                            dd_term,
                            vv_term,
                            QQ[prey, pred],
                        )
        except Exception as e:
            logger.debug("Instrumentation error in Q calculation: %s", e)

    # =========================================================================
    # STEP 2: Apply forced biomass adjustments
    # =========================================================================
    for i in range(1, NUM_GROUPS + 1):
        if ForcedBio[i] > 0:
            BB[i] = ForcedBio[i]

    # =========================================================================
    # STEP 3: Calculate fishing mortality with forced effort
    # =========================================================================
    FishMort = np.zeros(NUM_GROUPS + 1)
    Catch = np.zeros(NUM_GROUPS + 1)

    ForcedEffort = forcing.get("ForcedEffort", np.ones(max(NUM_GEARS + 1, 1)))
    # Support both dict-like and dataclass fishing inputs
    if isinstance(fishing, dict):
        FishFrom = fishing.get("FishFrom", np.array([0]))
        FishThrough = fishing.get("FishThrough", np.array([0]))
        FishQ = fishing.get("FishQ", np.array([0.0]))
    else:
        FishFrom = getattr(fishing, "FishFrom", np.array([0]))
        FishThrough = getattr(fishing, "FishThrough", np.array([0]))
        FishQ = getattr(fishing, "FishQ", np.array([0.0]))

    # fleet_idx: 0-based array of fleet group indices, used to resolve gear
    # indices from FishThrough values without assuming canonical group ordering.
    if isinstance(params, dict):
        fleet_idx = params.get("fleet_idx", None)
    else:
        fleet_idx = getattr(params, "fleet_idx", None)

    # Build a fast lookup from 0-based group index to 1-based gear index.
    # Falls back to the legacy arithmetic when fleet_idx is not available.
    _gear_lookup = {}
    if fleet_idx is not None:
        for pos, grp_0 in enumerate(fleet_idx):
            _gear_lookup[int(grp_0)] = pos + 1  # 1-based gear index

    # Calculate fishing mortality with effort scaling per gear
    # FishThrough contains 1-based GROUP indices of fleets.
    for i in range(1, len(FishFrom)):
        grp = int(FishFrom[i])
        gear_group_idx = int(FishThrough[i])
        gear_0based = gear_group_idx - 1  # convert to 0-based group index
        if _gear_lookup:
            gear_idx = _gear_lookup.get(gear_0based, 0)
        else:
            # Legacy fallback: assumes canonical ordering
            gear_idx = gear_group_idx - NUM_LIVING - NUM_DEAD
        effort_mult = (
            ForcedEffort[gear_idx] if 0 < gear_idx < len(ForcedEffort) else 1.0
        )
        if _fleet_med is not None:
            effort_mult *= _fleet_med[gear_idx]
        FishMort[grp] += FishQ[i] * effort_mult

    for i in range(1, NUM_LIVING + 1):
        Catch[i] = FishMort[i] * BB[i]
        try:
            # i is spname index (1..); instrument_set uses 0-based group indices
            if instrument_set and (i - 1) in instrument_set:
                name = spname_list[i] if spname_list is not None else None
                logger.debug(
                    "INSTR FISH grp=%s name=%s FishMort=%.6e BB=%.6e Catch=%.6e",
                    i,
                    name,
                    FishMort[i],
                    BB[i],
                    Catch[i],
                )
        except Exception as e:
            logger.debug("Instrumentation error in fishing: %s", e)

    # Debugging: print fishing details for small models to trace if fishing is applied

    # =========================================================================
    # STEP 4: Calculate derivatives for living groups
    # =========================================================================

    # Calculate primary production for producers
    pp_rates = primary_production_forcing(
        BB, Bbase, PB, PP_forcing, PP_type, NUM_LIVING
    )

    # IBM integration: check if any groups are replaced by IBMs
    ibm_groups = params.get("ibm_groups", {})

    # Handle IBM groups first (non-numba-compatible path)
    for i in ibm_groups:
        if 1 <= i <= NUM_LIVING:
            from pypath.ibm.integration import apply_ibm_to_derivative

            spatial_ctx = params.get("_ibm_spatial_context_%d" % i, None)
            apply_ibm_to_derivative(
                deriv=deriv,
                QQ=QQ,
                BB=BB,
                ibm_group=ibm_groups[i],
                forcing=forcing,
                dt=params.get("_dt", 1 / 12),
                spatial_context=spatial_ctx,
            )

    # Prepare arrays for the numba-accelerated living-group derivative kernel
    _M0_safe = (
        M0_arr
        if (M0_arr is not None and isinstance(M0_arr, np.ndarray))
        else np.zeros(NUM_GROUPS + 1)
    )
    _GE_arr = np.zeros(NUM_GROUPS + 1)
    for _gi in range(1, NUM_LIVING + 1):
        if QB[_gi] > 0.0:
            _GE_arr[_gi] = PB[_gi] / QB[_gi]
    _ibm_mask = np.zeros(NUM_GROUPS + 1, dtype=np.int64)
    for _ibm_i in ibm_groups:
        if 0 <= _ibm_i <= NUM_GROUPS:
            _ibm_mask[_ibm_i] = 1
    _PP_type_int = np.asarray(PP_type, dtype=np.int64)

    _compute_living_derivs(
        deriv,
        QQ,
        BB,
        _M0_safe,
        ForcedMigrate,
        FishMort,
        pp_rates,
        _GE_arr,
        _PP_type_int,
        PB,
        QB,
        _ibm_mask,
        NUM_LIVING,
        NUM_GROUPS,
    )

    # Post-kernel instrumentation / debug logging for living groups
    # (kept outside numba kernel because it uses Python objects: strings, logging, etc.)
    _need_instr = bool(instrument_set) or _TRACE_DEBUG_GROUPS is not None

    if _need_instr:
        for i in range(1, NUM_LIVING + 1):
            if i in ibm_groups:
                continue

            # Recompute per-group terms for logging (cheap scalar ops)
            consumption = float(np.sum(QQ[1:, i]))
            predation_loss = float(np.sum(QQ[i, 1 : NUM_LIVING + 1]))
            m0 = float(_M0_safe[i])
            if PP_type[i] > 0:
                production = float(pp_rates[i])
            elif QB[i] > 0:
                production = float(_GE_arr[i] * consumption)
            else:
                production = float(PB[i] * BB[i])

            # Debug trace for specific groups if requested
            try:
                trace_groups = _TRACE_DEBUG_GROUPS
                if trace_groups is not None and i in trace_groups:
                    name = spname_list[i] if spname_list is not None else None
                    logger.debug(
                        "TRACE DERIV i=%s name=%s production=%.6e predation_loss=%.6e fish_loss=%.6e m0_loss=%.6e deriv=%.6e",
                        i,
                        name,
                        production,
                        predation_loss,
                        FishMort[i] * BB[i],
                        m0 * BB[i],
                        deriv[i],
                    )
            except Exception as e:
                logger.debug("TRACE_DEBUG_GROUPS instrumentation error: %s", e)

            # Instrumentation: detailed per-term breakdown for selected groups
            try:
                if instrument_set and (i - 1) in instrument_set:
                    name = spname_list[i] if spname_list is not None else None
                    unassim_loss = consumption * Unassim[i]
                    fish_loss = FishMort[i] * BB[i]
                    m0_loss = m0 * BB[i]
                    logger.debug(
                        "INSTR DERIV i=%s name=%s production=%.12e consumption=%.12e unassim_loss=%.12e predation_loss=%.12e fish_loss=%.12e m0_loss=%.12e deriv=%.12e",
                        i,
                        name,
                        production,
                        consumption,
                        unassim_loss,
                        predation_loss,
                        fish_loss,
                        m0_loss,
                        deriv[i],
                    )

                    if predation_loss > 0:
                        contribs = []
                        for pred2 in range(1, NUM_LIVING + 1):
                            qval = QQ[i, pred2]
                            if qval > 0:
                                pname = (
                                    spname_list[pred2]
                                    if spname_list is not None
                                    else None
                                )
                                contribs.append((pred2, pname, qval))
                        if contribs:
                            logger.debug("INSTR PREDATORS for prey i={}:".format(i))
                            for pid, pname, qv in contribs:
                                logger.debug(
                                    "  pred=%s name=%s Q=%.12e", pid, pname, qv
                                )
            except Exception as e:
                logger.debug("Instrumentation error in deriv breakdown: %s", e)

    # =========================================================================
    # STEP 5: Calculate derivatives for detritus groups
    # =========================================================================
    DetFrac_raw = params.get("DetFrac", np.zeros((NUM_GROUPS + 1, NUM_DEAD + 1)))
    # RsimParams may store detritus fractions in two formats:
    # 1) a full 2D array shaped (NUM_GROUPS+1, NUM_DEAD+1), or
    # 2) a flat link-list array with accompanying DetFrom/DetTo arrays.
    # Handle both formats robustly and normalize to a 2D matrix DetFrac.
    DetFrac = np.asarray(DetFrac_raw)
    if DetFrac.ndim == 2:
        # Already a matrix - ensure full width if it's a single-column or truncated
        if DetFrac.shape != (NUM_GROUPS + 1, NUM_DEAD + 1):
            mat = np.zeros((NUM_GROUPS + 1, NUM_DEAD + 1))
            # copy what we have into the left/top corner
            r = min(mat.shape[0], DetFrac.shape[0])
            c = min(mat.shape[1], DetFrac.shape[1])
            mat[:r, :c] = DetFrac[:r, :c]
            DetFrac = mat

    elif DetFrac.ndim == 1:
        # Link-list format: try to reconstruct a full matrix using DetFrom/DetTo
        det_from = getattr(params, "DetFrom", None)
        det_to = getattr(params, "DetTo", None)
        if det_from is not None and det_to is not None:
            mat = np.zeros((NUM_GROUPS + 1, NUM_DEAD + 1))
            # det_from/det_to are arrays of same length as DetFrac
            for k in range(len(DetFrac)):
                f = int(det_from[k])
                t = int(det_to[k])
                # DetTo is an absolute group index (0 = Outside, otherwise nliving+det_idx)
                if (
                    t >= (NUM_LIVING + 1)
                    and t <= (NUM_LIVING + NUM_DEAD)
                    and f >= 0
                    and f <= NUM_GROUPS
                ):
                    det_col = t - NUM_LIVING  # 1-based detritus column index
                    mat[f, det_col] += DetFrac[k]

            DetFrac = mat
        else:
            # Fallback: treat as single-column per-group values
            DetFrac = DetFrac.reshape((DetFrac.size, 1))
    else:
        # scalar/None or unexpected -> coerce to minimal matrix
        DetFrac = DetFrac.reshape((1, 1))

    # Universal application of fish-derived discard contributions (work for both
    # 2D DetFrac and link-list reconstructions). This centralizes the logic to
    # avoid duplication and eliminate discrepancies between formats.
    try:
        if isinstance(params, dict):
            fish_from = params.get("FishFrom", None)
            fish_to = params.get("FishTo", None)
            fish_q = params.get("FishQ", None)
        else:
            fish_from = getattr(params, "FishFrom", None)
            fish_to = getattr(params, "FishTo", None)
            fish_q = getattr(params, "FishQ", None)
        if fish_from is not None and fish_to is not None and fish_q is not None:
            fish_from = np.asarray(fish_from)
            fish_to = np.asarray(fish_to)
            fish_q = np.asarray(fish_q, dtype=float)

            # Ensure DetFrac has full row coverage for groups
            if DetFrac.shape[0] < NUM_GROUPS + 1:
                new_rows = NUM_GROUPS + 1
                new_cols = max(DetFrac.shape[1], NUM_DEAD + 1)
                new = np.zeros((new_rows, new_cols))
                new[: DetFrac.shape[0], : DetFrac.shape[1]] = DetFrac
                DetFrac = new

            for k in range(len(fish_from)):
                try:
                    f = int(fish_from[k])
                    t = int(fish_to[k])
                    if not (
                        t >= (NUM_LIVING + 1)
                        and t <= (NUM_LIVING + NUM_DEAD)
                        and f >= 0
                        and f <= NUM_GROUPS
                    ):
                        continue
                    det_col = t - NUM_LIVING
                    src_idx = f
                    fish_input = float(fish_q[k]) * float(BB[src_idx])
                    m0_arr = M0_arr if M0_arr is not None else np.zeros(NUM_GROUPS + 1)
                    qb_arr = QB
                    unassim_arr = Unassim

                    m0_pos = max(
                        0.0, float(m0_arr[src_idx]) if src_idx < len(m0_arr) else 0.0
                    )
                    qb_loss = (
                        float(qb_arr[src_idx])
                        if (src_idx < len(qb_arr) and not np.isnan(qb_arr[src_idx]))
                        else 0.0
                    )
                    unassim_val = (
                        float(unassim_arr[src_idx])
                        if src_idx < len(unassim_arr)
                        else 0.0
                    )
                    source_loss = (
                        m0_pos * float(BB[src_idx])
                        + float(BB[src_idx]) * qb_loss * unassim_val
                    )
                    frac = fish_input / (source_loss + 1e-30)
                    if frac > 0:
                        # Make sure DetFrac has enough columns
                        if DetFrac.shape[1] <= det_col:
                            # expand to required width
                            new = np.zeros((DetFrac.shape[0], det_col + 1))
                            new[:, : DetFrac.shape[1]] = DetFrac
                            DetFrac = new
                        DetFrac[src_idx, det_col] += frac
                        if params.get("VERBOSE_DEBUG", False):
                            logger.debug(
                                "DEBUG: added fish-derived DetFrac mat[%s,%s] += %.3e",
                                src_idx,
                                det_col,
                                frac,
                            )
                except Exception as e:
                    if params.get("VERBOSE_DEBUG", False):
                        logger.debug(
                            "DEBUG: failed to add fish-derived DetFrac (unified) for entry %s: %s",
                            k,
                            e,
                        )
                    continue
    except Exception as e:
        logger.debug("Fish-derived DetFrac computation error: %s", e)

    # Pre-compute total consumption by each predator once, avoiding redundant
    # np.sum(QQ[1:, pred]) calls inside the per-detritus-group loop.
    # Shape: (NUM_LIVING,) where index j corresponds to pred = j + 1.
    total_consump_by_pred = np.sum(QQ[1:, 1 : NUM_LIVING + 1], axis=0)

    # Pre-fetch detritus decay rates outside the loop
    decay_rate = params.get("DetDecay", np.zeros(NUM_DEAD + 1))
    _decay_rate = np.asarray(decay_rate, dtype=np.float64)

    # Ensure DetFrac is a contiguous 2D float64 array for the numba kernel
    _DetFrac = np.ascontiguousarray(DetFrac, dtype=np.float64)

    # Compute detritus derivatives via numba-accelerated (or pure-Python) kernel
    try:
        _compute_detritus_derivs(
            deriv,
            QQ,
            BB,
            total_consump_by_pred,
            Unassim,
            _DetFrac,
            _M0_safe,
            _decay_rate,
            NUM_LIVING,
            NUM_DEAD,
        )
    except (IndexError, ValueError):
        # Fallback: rich debug information and re-raise for inspection
        logger.error(
            "ERROR in detritus kernel: QQ.shape=%s DetFrac.shape=%s Unassim.shape=%s "
            "NUM_LIVING=%s NUM_DEAD=%s BB.shape=%s params_keys_sample=%s",
            getattr(QQ, "shape", type(QQ)),
            getattr(_DetFrac, "shape", type(_DetFrac)),
            getattr(Unassim, "shape", type(Unassim)),
            NUM_LIVING,
            NUM_DEAD,
            getattr(BB, "shape", type(BB)),
            list(params.keys())[:10],
        )
        raise

    # Post-kernel detritus instrumentation / debug logging
    for d in range(NUM_LIVING + 1, NUM_LIVING + NUM_DEAD + 1):
        det_idx = d - NUM_LIVING
        try:
            logger.debug(
                "DEBUG DetFrac ndim=%s shape=%s NUM_LIVING=%s NUM_DEAD=%s d=%s det_idx=%s",
                _DetFrac.ndim,
                _DetFrac.shape,
                NUM_LIVING,
                NUM_DEAD,
                d,
                det_idx,
            )
        except (TypeError, ValueError, AttributeError):
            logger.debug("DEBUG DetFrac: unable to inspect shape/ndim")

        try:
            logger.debug(
                "TRACE DETRITUS d=%s det_idx=%s deriv=%.12e",
                d,
                det_idx,
                deriv[d],
            )
        except Exception as e:
            logger.debug("Detritus debug error: %s", e)

        # Instrumentation: print per-pred and per-grp contributions when requested
        try:
            if instrument_set and (d - 1) in instrument_set:
                logger.debug(
                    "INSTR DETRITUS d=%s det_idx=%s -- per-pred unas contributions:",
                    d,
                    det_idx,
                )
                for pred in range(1, NUM_LIVING + 1):
                    total_consump = total_consump_by_pred[pred - 1]
                    contrib = (
                        total_consump
                        * Unassim[pred]
                        * (
                            _DetFrac[pred, det_idx]
                            if _DetFrac.shape[1] > det_idx
                            else 0
                        )
                    )
                    if contrib != 0:
                        pname = spname_list[pred] if spname_list is not None else None
                        logger.debug(
                            "  pred=%s name=%s total_consump=%.12e unassim=%.12e DetFrac=%.12e contrib=%.12e",
                            pred,
                            pname,
                            total_consump,
                            Unassim[pred],
                            _DetFrac[pred, det_idx],
                            contrib,
                        )

                logger.debug(
                    "INSTR DETRITUS d=%s det_idx=%s -- per-grp mort contributions:",
                    d,
                    det_idx,
                )
                _m0_vals = M0_arr if M0_arr is not None else np.zeros(NUM_GROUPS + 1)
                for grp in range(1, NUM_LIVING + 1):
                    contrib = (
                        _m0_vals[grp]
                        * BB[grp]
                        * (_DetFrac[grp, det_idx] if _DetFrac.shape[1] > det_idx else 0)
                    )
                    if contrib != 0:
                        gname = spname_list[grp] if spname_list is not None else None
                        logger.debug(
                            "  grp=%s name=%s M0=%.12e BB=%.12e DetFrac=%.12e contrib=%.12e",
                            grp,
                            gname,
                            _m0_vals[grp],
                            BB[grp],
                            _DetFrac[grp, det_idx],
                            contrib,
                        )
        except Exception as e:
            logger.debug("Detritus instrumentation error: %s", e)

    # Zero derivatives for NoIntegrate (fast-turnover) groups to enforce algebraic equilibrium
    try:
        # NoIntegrate: Rpath encodes fast-turnover groups as 0. Treat 0 as True for NoIntegrate
        # NoIntegrate uses 1 to indicate fast-turnover groups in params (1 = NoIntegrate)
        no_integrate = (
            np.asarray(
                _NoIntegrate_raw
                if _NoIntegrate_raw is not None
                else np.zeros(NUM_GROUPS + 1)
            )
            != 0
        )
        if np.any(no_integrate):
            deriv[no_integrate] = 0.0
    except (TypeError, ValueError, IndexError):
        pass

    return deriv

integrate_rk4

integrate_rk4(state: ndarray, params: dict, forcing: dict, fishing: dict, dt: float) -> np.ndarray

Runge-Kutta 4th order integration step.

Parameters:

Name	Type	Description	Default
state	ndarray	Current state vector	required
params	dict	Model parameters	required
forcing	dict	Forcing arrays	required
fishing	dict	Fishing parameters	required
dt	float	Time step	required

Returns:

Type	Description
ndarray	Updated state vector

Source code in pypath/core/ecosim_deriv.py

def integrate_rk4(
    state: np.ndarray, params: dict, forcing: dict, fishing: dict, dt: float
) -> np.ndarray:
    """
    Runge-Kutta 4th order integration step.

    Parameters
    ----------
    state : np.ndarray
        Current state vector
    params : dict
        Model parameters
    forcing : dict
        Forcing arrays
    fishing : dict
        Fishing parameters
    dt : float
        Time step

    Returns
    -------
    np.ndarray
        Updated state vector
    """
    k1 = deriv_vector(state, params, forcing, fishing)
    k2 = deriv_vector(state + 0.5 * dt * k1, params, forcing, fishing)
    k3 = deriv_vector(state + 0.5 * dt * k2, params, forcing, fishing)
    k4 = deriv_vector(state + dt * k3, params, forcing, fishing)

    new_state = state + (dt / 6.0) * (k1 + 2 * k2 + 2 * k3 + k4)

    # Ensure non-negative biomass
    new_state = np.maximum(new_state, 0.0)

    # Enforce NoIntegrate groups stay at baseline (if provided in params)
    try:
        # NoIntegrate uses 1 to indicate fast-turnover groups in params (1 = NoIntegrate)
        no_integrate = (
            np.asarray(params.get("NoIntegrate", np.zeros(len(new_state)))) != 0
        )
        if np.any(no_integrate):
            Bbase = params.get("Bbase")
            if Bbase is not None:
                new_state[no_integrate] = Bbase[no_integrate]
    except (TypeError, ValueError, IndexError):
        pass

    # Instrumentation: allow callers to obtain compact RK4 stage diagnostics via
    # params.instrument_callback (similar to AB instrumentation). Compute per-stage
    # QQ totals for requested groups and call the callback with a small payload.
    try:
        instr_groups = params.get("INSTRUMENT_GROUPS", None)
        cb = params.get("instrument_callback", None)
        if cb is None:
            cb = globals().get("_last_instrument_callback", None)
        if instr_groups is not None and cb is not None:
            # Resolve numeric or named groups to 0-based indices (reuse AB logic)
            idxs = set()
            spname = params.get("spname", None)
            if isinstance(instr_groups, (list, tuple)) and all(
                isinstance(x, (int, np.integer)) for x in instr_groups
            ):
                nums = [int(x) for x in instr_groups]
                max_idx = len(state) - 1
                try:
                    if (
                        nums
                        and any(v > max_idx for v in nums)
                        and all(1 <= v <= max_idx + 1 for v in nums)
                    ):
                        nums = [v - 1 for v in nums]
                except (TypeError, ValueError):
                    pass
                idxs.update(int(x) for x in nums)
            else:
                # Prefer mapping via model DataFrame when available for stable
                # group ordering; otherwise fallback to spname mapping.
                model_df = params.get("model", None)
                for g in instr_groups:
                    if isinstance(g, str):
                        if (
                            model_df is not None
                            and hasattr(model_df, "columns")
                            and "Group" in model_df.columns
                        ):
                            groups_list = list(model_df["Group"])
                            if g in groups_list:
                                idxs.add(groups_list.index(g))
                                continue
                        if spname is not None and g in spname:
                            sp_idx = spname.index(g)
                            if sp_idx > 0:
                                idxs.add(sp_idx - 1)
                    else:
                        try:
                            val = int(g)
                            idxs.add(val)
                        except (TypeError, ValueError):
                            pass
            if idxs:
                max_idx = len(state) - 1
                valid_idxs = sorted(i for i in idxs if 0 <= i <= max_idx)
                if valid_idxs:
                    # Compute QQ totals for each RK4 stage for the requested groups
                    try:
                        from pypath.core.ecosim import _compute_Q_matrix

                        stages = [
                            state,
                            state + 0.5 * dt * k1,
                            state + 0.5 * dt * k2,
                            state + dt * k3,
                        ]
                        stage_totals = []
                        for st in stages:
                            QQs = _compute_Q_matrix(
                                params, st, {"Ftime": np.ones_like(st)}
                            )
                            totals = [
                                float(np.nansum(QQs[:, i + 1])) for i in valid_idxs
                            ]
                            stage_totals.append(totals)

                        parent = (
                            params.get("_integration_parent_method")
                            if isinstance(params, dict)
                            else None
                        )
                        payload_method = parent if parent is not None else "RK4"
                        # Helpful debug: when used as a warmup for another method
                        # we may want to inspect resolved group indices to ensure
                        # name->index mapping matches caller expectations.

                        payload = {
                            "method": payload_method,
                            "groups": valid_idxs,
                            "stage_consumption_totals": stage_totals,
                            "dt": float(dt),
                        }
                        # If this RK4 call is being used solely as a warmup for
                        # another integrator (e.g., AB), skip invoking the
                        # instrumentation callback here to avoid confusing
                        # caller expectations about the payload contents
                        # (AB expects 'deriv_current' which RK4-stage payloads
                        # do not provide). This keeps the first instrumentation
                        # payload relevant to AB runs as the AB payload.
                        if parent is None:
                            cb(payload)
                        else:
                            logger.debug(
                                "INSTRUMENT-TRACE: skipping RK4-stage callback when used as warmup for parent=%s",
                                parent,
                            )
                    except Exception as e:
                        logger.debug("RK4 instrumentation error: %s", e)
    except Exception as e:
        logger.debug("RK4 outer instrumentation error: %s", e)

    return new_state

compute_biomeq

compute_biomeq(total_gain, total_loss, biomass, sorwt=0.5)

Compute fast-equilibrium biomass for NoIntegrate groups.

Rpath formula: biomeq = TotGain / (TotLoss / B) Then: new_B = (1-SORWT)biomeq + SORWTold_B

Source code in pypath/core/ecosim_deriv.py

def compute_biomeq(total_gain, total_loss, biomass, sorwt=0.5):
    """Compute fast-equilibrium biomass for NoIntegrate groups.

    Rpath formula: biomeq = TotGain / (TotLoss / B)
    Then: new_B = (1-SORWT)*biomeq + SORWT*old_B
    """
    if total_loss <= 0 or biomass <= 0:
        return biomass
    loss_rate = total_loss / biomass
    biomeq = total_gain / loss_rate
    return (1.0 - sorwt) * biomeq + sorwt * biomass

integrate_ab

integrate_ab(state: ndarray, derivs_history: list, params: dict, forcing: dict, fishing: dict, dt: float) -> Tuple[np.ndarray, np.ndarray]

Adams-Bashforth integration step.

Uses 2-step Adams-Bashforth method (matching Rpath) when history is available, falls back to Euler with no history.

Parameters:

Name	Type	Description	Default
state	ndarray	Current state vector	required
derivs_history	list	List of previous derivative vectors (most recent first)	required
params	dict	Model parameters	required
forcing	dict	Forcing arrays	required
fishing	dict	Fishing parameters	required
dt	float	Time step	required

Returns:

Type	Description
Tuple[ndarray, ndarray]	Updated state vector and new derivative

Source code in pypath/core/ecosim_deriv.py

def integrate_ab(
    state: np.ndarray,
    derivs_history: list,
    params: dict,
    forcing: dict,
    fishing: dict,
    dt: float,
) -> Tuple[np.ndarray, np.ndarray]:
    """
    Adams-Bashforth integration step.

    Uses 2-step Adams-Bashforth method (matching Rpath) when history is
    available, falls back to Euler with no history.

    Parameters
    ----------
    state : np.ndarray
        Current state vector
    derivs_history : list
        List of previous derivative vectors (most recent first)
    params : dict
        Model parameters
    forcing : dict
        Forcing arrays
    fishing : dict
        Fishing parameters
    dt : float
        Time step

    Returns
    -------
    Tuple[np.ndarray, np.ndarray]
        Updated state vector and new derivative
    """
    # Calculate current derivative
    deriv_current = deriv_vector(state, params, forcing, fishing)
    deriv_current = _sanitize_deriv(deriv_current)

    n_history = len(derivs_history)

    if n_history >= 1:
        # 2-step Adams-Bashforth (matches Rpath)
        # y_{n+1} = y_n + dt/2 * (3*f_n - f_{n-1})
        new_state = state + (dt / 2.0) * (
            3.0 * deriv_current - _sanitize_deriv(np.asarray(derivs_history[0]))
        )
    else:
        # Euler method (first step)
        new_state = state + dt * deriv_current

    # Rpath-style bounds: pmax(pmin(B, Bref*BIGNUM), Bref*EPSILON)
    Bbase = params.get("Bbase", state)
    EPSILON = 1e-15
    BIGNUM = 1e15
    pos_mask = Bbase[1:] > 0
    new_state[1:] = np.where(
        pos_mask,
        np.clip(new_state[1:], Bbase[1:] * EPSILON, Bbase[1:] * BIGNUM),
        np.maximum(new_state[1:], 0.0),
    )

    # Enforce NoIntegrate groups stay at baseline (if provided in params)
    try:
        no_integrate = (
            np.asarray(params.get("NoIntegrate", np.zeros(len(new_state)))) != 0
        )
        if np.any(no_integrate):
            Bbase_ni = params.get("Bbase")
            if Bbase_ni is not None:
                new_state[no_integrate] = Bbase_ni[no_integrate]
                deriv_current[no_integrate] = 0.0
    except (TypeError, ValueError, IndexError):
        pass

    # Instrumentation callback: if caller requested group-level instrumentation
    # (e.g., params.INSTRUMENT_GROUPS = ['Macrobenthos'] and provided
    # params.instrument_callback callable), call the callback with compact
    # numeric arrays to allow unit tests / debugging harnesses to inspect
    # intermediate AB behavior without parsing verbose logs.
    try:
        instr_groups = params.get("INSTRUMENT_GROUPS", None)
        # Prefer the original attribute-based INSTRUMENT_GROUPS (exported by rsim_run)
        # if present; this helps in cases where the params dict has been mutated
        # during warmup or other computations.
        # Ensure NUM_GROUPS is available for legacy numeric instrument group checks
        NUM_GROUPS = params.get("NUM_GROUPS", None)
        try:
            attr_ig = globals().get("_last_instrument_groups", None)
            if attr_ig is not None:
                # If attr_ig differs from the dict value, prefer the attribute
                # (it represents the caller's original intention).
                if instr_groups is None or instr_groups != attr_ig:
                    # If the attribute appears to be a numeric legacy 1-based
                    # list, convert it aggressively here so caller intent is
                    # preserved and a DeprecationWarning is emitted.
                    try:
                        if isinstance(attr_ig, (list, tuple)) and all(
                            isinstance(x, (int, float, np.integer)) for x in attr_ig
                        ):
                            nums = [int(x) for x in attr_ig]
                            # Convert numeric 1-based indices only when caller explicitly
                            # opts in via INSTRUMENT_ASSUME_1BASED or when numbers exceed
                            # the valid 0-based range but are within plausible 1-based
                            # bounds (1..NUM_GROUPS).
                            assume_flag = params.get("INSTRUMENT_ASSUME_1BASED", False)
                            if nums and (
                                assume_flag
                                or (
                                    any(v > NUM_GROUPS - 1 for v in nums)
                                    and all(1 <= v <= NUM_GROUPS for v in nums)
                                )
                            ):
                                import warnings as _warnings

                                _warnings.warn(
                                    "Numeric INSTRUMENT_GROUPS indices are expected to be 0-based. "
                                    "Detected probable 1-based indices — converting to 0-based for now. "
                                    "Please update your code to use 0-based indices.",
                                    DeprecationWarning,
                                    stacklevel=3,
                                )
                                nums = [v - 1 for v in nums]
                                instr_groups = nums
                                # write back normalization to params dict/attr if possible
                                try:
                                    params["INSTRUMENT_GROUPS"] = instr_groups
                                except (TypeError, KeyError):
                                    try:
                                        setattr(
                                            params, "INSTRUMENT_GROUPS", instr_groups
                                        )
                                    except (TypeError, AttributeError):
                                        pass
                            else:
                                instr_groups = attr_ig
                        else:
                            instr_groups = attr_ig
                    except (TypeError, ValueError):
                        instr_groups = attr_ig
        except (TypeError, ValueError):
            pass

        # Resolve instrumentation callback: prefer per-call params dict value, fallback
        # to module-level last-known callback (set by rsim_run) to handle callsites
        # that attach the callback as an attribute on the params object instead
        # of the params dict (legacy code paths).
        cb = params.get("instrument_callback", None)
        if cb is None:
            # Module-level fallback (set by rsim_run if available)
            try:
                cb = globals().get("_last_instrument_callback", None)
                if cb is not None:
                    logger.debug("INSTRUMENT: using module-level fallback callback")
            except (TypeError, AttributeError):
                cb = None
        # Print debug info without referencing undefined symbols
        try:
            logger.debug(
                "INSTRUMENT-DEBUG: instr_groups=%s cb_present=%s cb=%s",
                instr_groups,
                cb is not None,
                cb,
            )
        except (TypeError, ValueError):
            pass
        # Only proceed if caller requested instrumentation via instr_groups
        # and a callback is available.
        if instr_groups is not None and cb is not None:
            # Prefer a pre-normalized numeric list (0-based indices) when provided
            idxs = set()
            spname = params.get("spname", None)
            # If instr_groups is a list of numeric indices (possibly normalized),
            # use them directly; otherwise try to resolve names to indices.
            try:
                # treat as numeric list when all elements are ints
                if isinstance(instr_groups, (list, tuple)) and all(
                    isinstance(x, (int, np.integer)) for x in instr_groups
                ):
                    # Detailed tracing for numeric-based instrument group resolution
                    nums = [int(x) for x in instr_groups]
                    max_idx = len(state) - 1
                    try:
                        logger.debug(
                            "INSTRUMENT-TRACE: before conversion nums=%s max_idx=%s instr_groups_id=%s params_has=%s _last_instrument_groups=%s",
                            nums,
                            max_idx,
                            id(instr_groups),
                            (
                                "INSTRUMENT_GROUPS" in params
                                if isinstance(params, dict)
                                else hasattr(params, "INSTRUMENT_GROUPS")
                            ),
                            globals().get("_last_instrument_groups", None),
                        )
                    except (TypeError, ValueError):
                        pass

                    # Avoid double-conversion: assume numeric lists are already 0-based
                    # unless they contain values outside the valid 0-based range.
                    # Only convert if some values exceed the max 0-based index but are
                    # within the plausible 1-based range (1..max_idx+1).
                    try:
                        if (
                            nums
                            and any(v > max_idx for v in nums)
                            and all(1 <= v <= max_idx + 1 for v in nums)
                        ):
                            import warnings as _warnings

                            logger.debug(
                                "INSTRUMENT-TRACE: detected probable 1-based numeric indices %s; converting to 0-based",
                                nums,
                            )
                            _warnings.warn(
                                "Numeric INSTRUMENT_GROUPS indices are expected to be 0-based. "
                                "Detected probable 1-based indices — converting to 0-based for now. "
                                "Please update your code to use 0-based indices.",
                                DeprecationWarning,
                                stacklevel=3,
                            )
                            nums = [v - 1 for v in nums]
                    except (TypeError, ValueError):
                        pass

                    try:
                        logger.debug(
                            "INSTRUMENT-TRACE: after conversion (or no conversion) nums=%s",
                            nums,
                        )
                    except (TypeError, ValueError):
                        pass

                    # Update idxs with the resolved numeric values (assume normalized unless converted above)
                    idxs.update(int(x) for x in nums)
                    try:
                        logger.debug(
                            "INSTRUMENT-TRACE: idxs updated -> %s (raw), params['INSTRUMENT_GROUPS']=%s",
                            sorted(idxs),
                            (
                                params.get("INSTRUMENT_GROUPS", None)
                                if isinstance(params, dict)
                                else getattr(params, "INSTRUMENT_GROUPS", None)
                            ),
                        )
                    except (TypeError, ValueError):
                        pass
                else:
                    model_df = params.get("model", None)
                    for g in instr_groups:
                        if isinstance(g, str):
                            # Prefer model-defined ordering when available
                            if (
                                model_df is not None
                                and hasattr(model_df, "columns")
                                and "Group" in model_df.columns
                            ):
                                groups_list = list(model_df["Group"])
                                if g in groups_list:
                                    idxs.add(groups_list.index(g))
                                    continue
                            if spname is not None and g in spname:
                                sp_idx = spname.index(g)
                                if sp_idx > 0:
                                    idxs.add(sp_idx - 1)
                        else:
                            try:
                                val = int(g)
                                idxs.add(val)
                            except (TypeError, ValueError):
                                pass
            except (TypeError, ValueError):
                # Best-effort: if resolution fails, leave idxs empty
                idxs = set()
            # Filter indices to valid range and sort
            if idxs:
                max_idx = len(state) - 1
                valid_idxs = sorted(i for i in idxs if 0 <= i <= max_idx)

                # If we exported caller attribute INSTRUMENT_GROUPS earlier, use it
                # only as a fallback when dict-derived resolution failed. This avoids
                # preferring older caller attribute values that may be legacy 1-based
                # and lead to conflicting normalization choices.
                try:
                    attr_ig = globals().get("_last_instrument_groups", None)
                    if attr_ig is not None:
                        alt_idxs = set()
                        # Resolve attribute-provided groups similarly to dict ones
                        if isinstance(attr_ig, (list, tuple)):
                            if all(isinstance(x, (int, np.integer)) for x in attr_ig):
                                nums = [int(x) for x in attr_ig]
                                # Only convert attribute-provided numeric 1-based indices
                                # when caller explicitly opts in via INSTRUMENT_ASSUME_1BASED
                                if params.get("INSTRUMENT_ASSUME_1BASED", False):
                                    if (
                                        nums
                                        and any(v > max_idx for v in nums)
                                        and all(1 <= v <= max_idx + 1 for v in nums)
                                    ):
                                        import warnings as _warnings

                                        _warnings.warn(
                                            "Numeric INSTRUMENT_GROUPS indices are expected to be 0-based. "
                                            "Detected probable 1-based indices — converting to 0-based for now. "
                                            "Please update your code to use 0-based indices.",
                                            DeprecationWarning,
                                            stacklevel=3,
                                        )
                                        nums = [v - 1 for v in nums]
                                alt_idxs.update(int(x) for x in nums)
                            else:
                                for g in attr_ig:
                                    if (
                                        isinstance(g, str)
                                        and spname is not None
                                        and g in spname
                                    ):
                                        sp_idx = spname.index(g)
                                        if sp_idx > 0:
                                            alt_idxs.add(sp_idx - 1)
                                    else:
                                        try:
                                            val = int(g)
                                            alt_idxs.add(val)
                                        except (TypeError, ValueError):
                                            pass
                        elif isinstance(attr_ig, str) and spname is not None:
                            if attr_ig in spname:
                                sp_idx = spname.index(attr_ig)
                                if sp_idx > 0:
                                    alt_idxs.add(sp_idx - 1)

                        # Prefer attribute-derived indices when available (it represents
                        # the caller's original intent), falling back to dict-derived
                        # resolution only when attribute resolution fails.
                        alt_valid = sorted(i for i in alt_idxs if 0 <= i <= max_idx)
                        if alt_valid:
                            logger.debug(
                                "INSTRUMENT-TRACE: preferring attr_ig alt_valid=%s over dict-derived valid_idxs=%s",
                                alt_valid,
                                valid_idxs,
                            )
                            valid_idxs = alt_valid
                            # Also write back the normalized groups into params when possible
                            try:
                                normalized = list(valid_idxs)
                                try:
                                    params["INSTRUMENT_GROUPS"] = normalized
                                except (TypeError, KeyError):
                                    try:
                                        setattr(params, "INSTRUMENT_GROUPS", normalized)
                                    except (TypeError, AttributeError):
                                        pass
                                logger.debug(
                                    "INSTRUMENT-TRACE: wrote normalized attr_ig back to params: %s",
                                    normalized,
                                )
                            except (TypeError, ValueError):
                                pass
                except (TypeError, ValueError):
                    pass
                if valid_idxs:
                    idx_list = valid_idxs
                    # Collect history for these groups (may be empty)
                    hist = [np.asarray(h)[idx_list].tolist() for h in derivs_history]
                    payload = {
                        "method": "AB",
                        "groups": idx_list,
                        "deriv_current": np.asarray(deriv_current)[idx_list].tolist(),
                        "derivs_history": hist,
                        "new_state": np.asarray(new_state)[idx_list].tolist(),
                        "dt": float(dt),
                    }
                try:
                    try:
                        if (
                            isinstance(params, dict)
                            and params.get("VERBOSE_INSTRUMENTATION")
                        ) or getattr(params, "VERBOSE_INSTRUMENTATION", False):
                            logger.debug(
                                "INSTRUMENT-TRACE-PAYLOAD: idx_list=%s state_len=%s deriv_slice=%s new_state_slice=%s cb=%s params_INSTRUMENT_GROUPS=%s _last_instrument_groups=%s",
                                idx_list,
                                len(state),
                                np.asarray(deriv_current)[idx_list].tolist(),
                                np.asarray(new_state)[idx_list].tolist(),
                                cb,
                                (
                                    params.get("INSTRUMENT_GROUPS", None)
                                    if isinstance(params, dict)
                                    else getattr(params, "INSTRUMENT_GROUPS", None)
                                ),
                                globals().get("_last_instrument_groups", None),
                            )
                    except (TypeError, ValueError):
                        pass
                    logger.debug("INSTRUMENT: calling callback groups=%s", idx_list)
                    cb(payload)
                except Exception as e:
                    # Don't allow instrumentation failures to break integration
                    logger.debug("Instrumentation callback failed: %s", e)
    except Exception as e:
        logger.debug("AB outer instrumentation error: %s", e)

    return new_state, deriv_current

run_ecosim

run_ecosim(initial_state: ndarray, params: dict, forcing: dict, fishing: dict, years: float, dt: float = 1 / 12, method: str = 'ab', save_interval: int = 1) -> dict

Run Ecosim simulation.

Parameters:

Name	Type	Description	Default
initial_state	ndarray	Initial biomass vector	required
params	dict	Model parameters	required
forcing	dict	Forcing arrays	required
fishing	dict	Fishing parameters	required
years	float	Number of years to simulate	required
dt	float	Time step (fraction of year)	1 / 12
method	str	Integration method ('rk4' or 'ab')	'ab'
save_interval	int	Save state every N steps	1

Returns:

Type	Description
dict	Results containing: - time: Time points - biomass: Biomass time series [time, group] - catch: Catch time series [time, group]

Source code in pypath/core/ecosim_deriv.py

def run_ecosim(
    initial_state: np.ndarray,
    params: dict,
    forcing: dict,
    fishing: dict,
    years: float,
    dt: float = 1 / 12,  # Monthly time step
    method: str = "ab",  # 'rk4' or 'ab'
    save_interval: int = 1,
) -> dict:
    """
    Run Ecosim simulation.

    Parameters
    ----------
    initial_state : np.ndarray
        Initial biomass vector
    params : dict
        Model parameters
    forcing : dict
        Forcing arrays
    fishing : dict
        Fishing parameters
    years : float
        Number of years to simulate
    dt : float
        Time step (fraction of year)
    method : str
        Integration method ('rk4' or 'ab')
    save_interval : int
        Save state every N steps

    Returns
    -------
    dict
        Results containing:
        - time: Time points
        - biomass: Biomass time series [time, group]
        - catch: Catch time series [time, group]
    """
    n_steps = int(years / dt)
    n_groups = len(initial_state)

    # Initialize output arrays
    save_times = list(range(0, n_steps + 1, save_interval))
    n_saves = len(save_times)

    time_out = np.zeros(n_saves)
    biomass_out = np.zeros((n_saves, n_groups))

    # Initialize state
    state = initial_state.copy()
    derivs_history = []  # For Adams-Bashforth

    # Save initial state
    save_idx = 0
    time_out[save_idx] = 0.0
    biomass_out[save_idx] = state
    save_idx += 1

    # Main integration loop
    for step in range(1, n_steps + 1):
        t = step * dt

        # Update forcing for current time if time-varying
        # (This would interpolate forcing arrays to current time)

        if method == "rk4":
            state = integrate_rk4(state, params, forcing, fishing, dt)
        else:  # Adams-Bashforth
            state, new_deriv = integrate_ab(
                state, derivs_history, params, forcing, fishing, dt
            )
            # Update history (keep last 3)
            derivs_history.insert(0, new_deriv)
            if len(derivs_history) > 3:
                derivs_history.pop()

        # Save if at save interval
        if step in save_times:
            time_out[save_idx] = t
            biomass_out[save_idx] = state
            save_idx += 1

    return {
        "time": time_out,
        "biomass": biomass_out,
        "years": years,
        "dt": dt,
        "method": method,
    }

Advanced Ecosim (State Forcing & Diet Rewiring)

State-variable forcing and dynamic diet rewiring extensions for Ecosim.

pypath.core.ecosim_advanced

Advanced Ecosim features including state forcing and diet rewiring.

This module extends the base Ecosim functionality with: 1. Flexible state-variable forcing 2. Dynamic diet rewiring 3. Advanced forcing modes

apply_state_forcing

apply_state_forcing(state: ndarray, year: float, state_forcing: Optional[StateForcing], variable: StateVariable = StateVariable.BIOMASS) -> np.ndarray

Apply state forcing to current state vector.

Parameters:

Name	Type	Description	Default
state	ndarray	Current state vector (biomass, catch, etc.)	required
year	float	Current simulation year (fractional for monthly steps)	required
state_forcing	StateForcing or None	Forcing configuration	required
variable	StateVariable	Which variable is being forced	BIOMASS

Returns:

Type	Description
ndarray	Modified state vector

Source code in pypath/core/ecosim_advanced.py

def apply_state_forcing(
    state: np.ndarray,
    year: float,
    state_forcing: Optional[StateForcing],
    variable: StateVariable = StateVariable.BIOMASS,
) -> np.ndarray:
    """Apply state forcing to current state vector.

    Parameters
    ----------
    state : np.ndarray
        Current state vector (biomass, catch, etc.)
    year : float
        Current simulation year (fractional for monthly steps)
    state_forcing : StateForcing or None
        Forcing configuration
    variable : StateVariable
        Which variable is being forced

    Returns
    -------
    np.ndarray
        Modified state vector
    """
    if state_forcing is None:
        return state

    state_modified = state.copy()

    # Get all active forcing for this variable
    forcing_list = state_forcing.get_forcing(year, variable)

    for func, forced_value in forcing_list:
        group_idx = func.group_idx

        if group_idx == -1:
            # Apply to all groups
            indices: range | list[int] = range(len(state))
        else:
            # Apply to specific group
            indices = [group_idx]

        for idx in indices:
            if func.mode == ForcingMode.REPLACE:
                # Replace computed value with forced value
                state_modified[idx] = forced_value

            elif func.mode == ForcingMode.ADD:
                # Add forced value to computed value
                state_modified[idx] += forced_value

            elif func.mode == ForcingMode.MULTIPLY:
                # Multiply computed value by forced value
                state_modified[idx] *= forced_value

            elif func.mode == ForcingMode.RESCALE:
                # Rescale to match forced value
                # (maintains relative proportions)
                if state[idx] > 0:
                    _scale = forced_value / state[idx]
                    state_modified[idx] = forced_value
                else:
                    state_modified[idx] = forced_value

    return state_modified

apply_diet_rewiring

apply_diet_rewiring(biomass: ndarray, diet_rewiring: Optional[DietRewiring], month: int) -> Optional[np.ndarray]

Update diet matrix based on current biomass.

Parameters:

Name	Type	Description	Default
biomass	ndarray	Current biomass values	required
diet_rewiring	DietRewiring or None	Diet rewiring configuration	required
month	int	Current month (for update interval check)	required

Returns:

Type	Description
ndarray or None	Updated diet matrix, or None if no update

Source code in pypath/core/ecosim_advanced.py

def apply_diet_rewiring(
    biomass: np.ndarray, diet_rewiring: Optional[DietRewiring], month: int
) -> Optional[np.ndarray]:
    """Update diet matrix based on current biomass.

    Parameters
    ----------
    biomass : np.ndarray
        Current biomass values
    diet_rewiring : DietRewiring or None
        Diet rewiring configuration
    month : int
        Current month (for update interval check)

    Returns
    -------
    np.ndarray or None
        Updated diet matrix, or None if no update
    """
    if diet_rewiring is None or not diet_rewiring.enabled:
        return None

    # Check if it's time to update
    if month % diet_rewiring.update_interval != 0:
        return None

    # Update diet based on current biomass
    new_diet = diet_rewiring.update_diet(biomass)

    return new_diet

rsim_run_advanced

rsim_run_advanced(scenario: RsimScenario, state_forcing: Optional[StateForcing] = None, diet_rewiring: Optional[DietRewiring] = None, method: str = 'RK4', years: Optional[range] = None, verbose: bool = False) -> RsimOutput

Run Ecosim simulation with advanced forcing and diet rewiring.

This function extends the standard rsim_run with: - Flexible state-variable forcing (biomass, catch, recruitment, etc.) - Dynamic diet rewiring based on prey availability - Multiple forcing modes (replace, add, multiply, rescale)

Parameters:

Name	Type	Description	Default
scenario	RsimScenario	Standard Ecosim scenario	required
state_forcing	StateForcing	State-variable forcing configuration	None
diet_rewiring	DietRewiring	Diet rewiring configuration	None
method	str	Integration method ('RK4' or 'AB')	'RK4'
years	range	Years to simulate	None
verbose	bool	Print progress information	False

Returns:

Type	Description
RsimOutput	Simulation results with applied forcing

Examples:

>>> from pypath.core.forcing import create_biomass_forcing, create_diet_rewiring
>>>
>>> # Force phytoplankton biomass to observed values
>>> biomass_forcing = create_biomass_forcing(
...     group_idx=0,
...     observed_biomass={2000: 15.0, 2005: 18.0, 2010: 16.0},
...     mode='replace'
... )
>>>
>>> # Enable prey switching
>>> diet_rewiring = create_diet_rewiring(switching_power=2.5)
>>>
>>> # Run simulation
>>> result = rsim_run_advanced(
...     scenario,
...     state_forcing=biomass_forcing,
...     diet_rewiring=diet_rewiring
... )

Source code in pypath/core/ecosim_advanced.py

def rsim_run_advanced(
    scenario: RsimScenario,
    state_forcing: Optional[StateForcing] = None,
    diet_rewiring: Optional[DietRewiring] = None,
    method: str = "RK4",
    years: Optional[range] = None,
    verbose: bool = False,
) -> RsimOutput:
    """Run Ecosim simulation with advanced forcing and diet rewiring.

    This function extends the standard rsim_run with:
    - Flexible state-variable forcing (biomass, catch, recruitment, etc.)
    - Dynamic diet rewiring based on prey availability
    - Multiple forcing modes (replace, add, multiply, rescale)

    Parameters
    ----------
    scenario : RsimScenario
        Standard Ecosim scenario
    state_forcing : StateForcing, optional
        State-variable forcing configuration
    diet_rewiring : DietRewiring, optional
        Diet rewiring configuration
    method : str
        Integration method ('RK4' or 'AB')
    years : range, optional
        Years to simulate
    verbose : bool
        Print progress information

    Returns
    -------
    RsimOutput
        Simulation results with applied forcing

    Examples
    --------
    >>> from pypath.core.forcing import create_biomass_forcing, create_diet_rewiring
    >>>
    >>> # Force phytoplankton biomass to observed values
    >>> biomass_forcing = create_biomass_forcing(
    ...     group_idx=0,
    ...     observed_biomass={2000: 15.0, 2005: 18.0, 2010: 16.0},
    ...     mode='replace'
    ... )
    >>>
    >>> # Enable prey switching
    >>> diet_rewiring = create_diet_rewiring(switching_power=2.5)
    >>>
    >>> # Run simulation
    >>> result = rsim_run_advanced(
    ...     scenario,
    ...     state_forcing=biomass_forcing,
    ...     diet_rewiring=diet_rewiring
    ... )
    """

    params = scenario.params
    forcing = scenario.forcing
    _fishing = scenario.fishing

    # Initialize diet rewiring with base diet
    if diet_rewiring is not None and diet_rewiring.enabled:
        # Extract diet matrix from params
        # Need to reconstruct diet from predator-prey links
        n_prey = params.NUM_BIO
        n_pred = params.NUM_LIVING

        base_diet = np.zeros((n_prey + 1, n_pred + 1))

        for link in range(params.NumPredPreyLinks):
            prey_idx = params.PreyFrom[link]
            pred_idx = params.PreyTo[link]

            # Base proportion (will be normalized)
            base_diet[prey_idx, pred_idx] = params.QQ[link]

        # Normalize
        for pred in range(n_pred + 1):
            total = np.sum(base_diet[:, pred])
            if total > 0:
                base_diet[:, pred] /= total

        diet_rewiring.initialize(base_diet)

        if verbose:
            logger.info(
                f"Initialized diet rewiring (power={diet_rewiring.switching_power})"
            )

    # Determine years to run
    if years is None:
        n_months = forcing.ForcedBio.shape[0]
        n_years = n_months // 12
    else:
        n_years = len(years)
        n_months = n_years * 12

    n_groups = params.NUM_GROUPS + 1

    # Initialize output arrays
    out_biomass = np.zeros((n_months + 1, n_groups))
    out_catch = np.zeros((n_months + 1, n_groups))
    out_gear_catch = np.zeros((n_months + 1, params.NumFishingLinks + 1))

    # Initialize state
    state = scenario.start_state.Biomass.copy()
    out_biomass[0] = state

    # Track diet changes
    diet_changes = 0

    # Main simulation loop
    for month in range(n_months):
        year_num = month // 12
        month_in_year = month % 12
        current_year = scenario.start_year + year_num + month_in_year / 12.0

        if verbose and month % 12 == 0:
            logger.debug(
                f"Year {year_num + 1}/{n_years}: mean biomass = {np.mean(state[1 : params.NUM_LIVING + 1]):.2f}"
            )

        # Apply diet rewiring if enabled
        if diet_rewiring is not None:
            new_diet = apply_diet_rewiring(state, diet_rewiring, month)

            if new_diet is not None:
                # Update QQ values in params based on new diet
                # This would require modifying the params.QQ array
                # For now, just track that it happened
                diet_changes += 1

                if verbose:
                    logger.debug(f"  Diet rewiring applied at month {month}")

        # Get derivative
        # Note: This simplified version doesn't actually integrate
        # In full implementation, would call integrate_rk4 or integrate_ab
        # For now, just demonstrate the forcing application

        # Simulate one time step (placeholder - real version would integrate)
        # This is where the actual RK4 or AB integration would happen
        # state_new = integrate_rk4(state, params_dict, forcing_matrices, ...)

        # For demonstration, use simple Euler step
        # In real implementation, this would be the full RK4/AB integration
        # that's already in ecosim_deriv.py

        # Apply biomass forcing AFTER integration (replace computed biomass)
        if state_forcing is not None:
            state = apply_state_forcing(
                state, current_year, state_forcing, StateVariable.BIOMASS
            )

        # Store results
        out_biomass[month + 1] = state

        # Check for crashes
        living_biomass = state[1 : params.NUM_LIVING + 1]
        if np.any(living_biomass < 1e-4):
            if verbose:
                crashed = np.where(living_biomass < 1e-4)[0]
                logger.warning(f"Crash detected at month {month}, groups: {crashed}")

    # Convert to annual (simplified - real version aggregates properly)
    annual_biomass = out_biomass[::12]  # Every 12th month

    # Create output (simplified - real version fills all fields)
    from pypath.core.ecosim import RsimState

    # Create end state with all required fields
    # Use start_state N and Ftime since this simplified version doesn't track them
    end_state = RsimState(
        Biomass=state.copy(),
        N=scenario.start_state.N.copy(),
        Ftime=scenario.start_state.Ftime.copy(),
        SpawnBio=(
            scenario.start_state.SpawnBio.copy()
            if scenario.start_state.SpawnBio is not None
            else None
        ),
        StanzaPred=(
            scenario.start_state.StanzaPred.copy()
            if scenario.start_state.StanzaPred is not None
            else None
        ),
        EggsStanza=(
            scenario.start_state.EggsStanza.copy()
            if scenario.start_state.EggsStanza is not None
            else None
        ),
        NageS=(
            scenario.start_state.NageS.copy()
            if scenario.start_state.NageS is not None
            else None
        ),
        WageS=(
            scenario.start_state.WageS.copy()
            if scenario.start_state.WageS is not None
            else None
        ),
        QageS=(
            scenario.start_state.QageS.copy()
            if scenario.start_state.QageS is not None
            else None
        ),
    )

    output = RsimOutput(
        out_Biomass=out_biomass,
        out_Catch=out_catch,
        out_Gear_Catch=out_gear_catch,
        annual_Biomass=annual_biomass,
        annual_Catch=np.zeros_like(annual_biomass),
        annual_QB=np.zeros((n_years + 1, n_groups)),
        annual_Qlink=np.zeros((n_years + 1, params.NumPredPreyLinks + 1)),
        stanza_biomass=None,
        end_state=end_state,
        crash_year=-1,
        crashed_groups=set(),
        pred=np.array([]),
        prey=np.array([]),
        Gear_Catch_sp=np.array([]),
        Gear_Catch_gear=np.array([]),
        Gear_Catch_disp=np.array([]),
        start_state=scenario.start_state,
        params={
            "NUM_GROUPS": params.NUM_GROUPS,
            "NUM_LIVING": params.NUM_LIVING,
            "years": n_years,
        },
    )

    if verbose:
        logger.info("Simulation complete:")
        logger.info(f"  Total diet rewiring updates: {diet_changes}")
        if state_forcing:
            logger.info(f"  Active forcing functions: {len(state_forcing.functions)}")

    return output

create_advanced_scenario

create_advanced_scenario(base_scenario: RsimScenario, state_forcing: Optional[StateForcing] = None, diet_rewiring: Optional[DietRewiring] = None) -> tuple[RsimScenario, StateForcing, DietRewiring]

Create advanced scenario with forcing and rewiring.

Parameters:

Name	Type	Description	Default
base_scenario	RsimScenario	Base Ecosim scenario	required
state_forcing	StateForcing	State forcing configuration	None
diet_rewiring	DietRewiring	Diet rewiring configuration	None

Returns:

Name	Type	Description
scenario	RsimScenario	Base scenario (unchanged)
state_forcing	StateForcing	State forcing (created if None)
diet_rewiring	DietRewiring	Diet rewiring (created if None)

Source code in pypath/core/ecosim_advanced.py

def create_advanced_scenario(
    base_scenario: RsimScenario,
    state_forcing: Optional[StateForcing] = None,
    diet_rewiring: Optional[DietRewiring] = None,
) -> tuple[RsimScenario, StateForcing, DietRewiring]:
    """Create advanced scenario with forcing and rewiring.

    Parameters
    ----------
    base_scenario : RsimScenario
        Base Ecosim scenario
    state_forcing : StateForcing, optional
        State forcing configuration
    diet_rewiring : DietRewiring, optional
        Diet rewiring configuration

    Returns
    -------
    scenario : RsimScenario
        Base scenario (unchanged)
    state_forcing : StateForcing
        State forcing (created if None)
    diet_rewiring : DietRewiring
        Diet rewiring (created if None)
    """
    if state_forcing is None:
        state_forcing = StateForcing()

    if diet_rewiring is None:
        diet_rewiring = DietRewiring(enabled=False)

    return base_scenario, state_forcing, diet_rewiring

Stanzas (Multi-Stanza Groups)

pypath.core.stanzas

Multi-stanza (age-structured) groups for PyPath.

This module implements age-structured population dynamics using Von Bertalanffy growth and stage-based mortality rates.

Based on Rpath's rpath.stanzas() and rsim.stanzas() functions.

EcosimStanzaParams dataclass

Container for all multi-stanza parameters.

Attributes: n_stanza_groups: Number of stanza groups stanza_groups: List of StanzaGroup objects stanza_individuals: List of StanzaIndividual objects st_groups: DataFrame with stanza calculations per age

Source code in pypath/core/stanzas.py

@dataclass
class EcosimStanzaParams:
    """Container for all multi-stanza parameters.

    Attributes:
        n_stanza_groups: Number of stanza groups
        stanza_groups: List of StanzaGroup objects
        stanza_individuals: List of StanzaIndividual objects
        st_groups: DataFrame with stanza calculations per age
    """

    n_stanza_groups: int = 0
    stanza_groups: List[StanzaGroup] = field(default_factory=list)
    stanza_individuals: List[StanzaIndividual] = field(default_factory=list)
    st_groups: Dict[int, pd.DataFrame] = field(default_factory=dict)

RsimStanzas dataclass

Stanza parameters for Ecosim simulation.

Contains age-structured dynamics parameters needed by the simulation engine.

Source code in pypath/core/stanzas.py

@dataclass
class RsimStanzas:
    """Stanza parameters for Ecosim simulation.

    Contains age-structured dynamics parameters needed by
    the simulation engine.
    """

    n_split: int = 0
    n_stanzas: np.ndarray = field(default_factory=lambda: np.array([0]))
    ecopath_code: np.ndarray = field(default_factory=lambda: np.zeros((2, 2)))
    age1: np.ndarray = field(default_factory=lambda: np.zeros((2, 2)))
    age2: np.ndarray = field(default_factory=lambda: np.zeros((2, 2)))

    # Age-at-size arrays (rows=months, cols=species)
    base_wage_s: np.ndarray = field(default_factory=lambda: np.zeros((2, 2)))
    base_nage_s: np.ndarray = field(default_factory=lambda: np.zeros((2, 2)))
    base_qage_s: np.ndarray = field(default_factory=lambda: np.zeros((2, 2)))

    # Maturity and recruitment
    wmat: np.ndarray = field(default_factory=lambda: np.array([0.0, 0.0]))
    rec_power: np.ndarray = field(default_factory=lambda: np.array([0.0, 0.0]))
    recruits: np.ndarray = field(default_factory=lambda: np.array([0.0, 0.0]))
    vbgf_d: np.ndarray = field(default_factory=lambda: np.array([0.0, 0.0]))
    r_zero_s: np.ndarray = field(default_factory=lambda: np.array([0.0, 0.0]))
    vbm: np.ndarray = field(default_factory=lambda: np.array([0.0, 0.0]))

    # Growth coefficients
    split_alpha: np.ndarray = field(default_factory=lambda: np.zeros((2, 2)))

    # Spawning
    spawn_x: np.ndarray = field(default_factory=lambda: np.array([0.0, 0.0]))
    spawn_energy: np.ndarray = field(default_factory=lambda: np.array([0.0, 0.0]))
    base_eggs_stanza: np.ndarray = field(default_factory=lambda: np.array([0.0, 0.0]))
    base_spawn_bio: np.ndarray = field(default_factory=lambda: np.array([0.0, 0.0]))
    r_scale_split: np.ndarray = field(default_factory=lambda: np.array([0.0, 0.0]))
    base_stanza_pred: np.ndarray = field(default_factory=lambda: np.array([0.0, 0.0]))

StanzaGroup dataclass

Parameters for a single multi-stanza species group.

Attributes: stanza_group_num: Index of this stanza group (1-based) n_stanzas: Number of age stanzas in this group vbgf_ksp: Von Bertalanffy K parameter (annual) vbgf_d: Von Bertalanffy d parameter (default 2/3) wmat: Weight at 50% maturity relative to Winf bab: Biomass accumulation / background mortality rec_power: Recruitment power parameter recruits: Base number of recruits (R) last_month: Final month of the oldest age class

Source code in pypath/core/stanzas.py

@dataclass
class StanzaGroup:
    """Parameters for a single multi-stanza species group.

    Attributes:
        stanza_group_num: Index of this stanza group (1-based)
        n_stanzas: Number of age stanzas in this group
        vbgf_ksp: Von Bertalanffy K parameter (annual)
        vbgf_d: Von Bertalanffy d parameter (default 2/3)
        wmat: Weight at 50% maturity relative to Winf
        bab: Biomass accumulation / background mortality
        rec_power: Recruitment power parameter
        recruits: Base number of recruits (R)
        last_month: Final month of the oldest age class
    """

    stanza_group_num: int
    n_stanzas: int
    vbgf_ksp: float
    vbgf_d: float = 0.66667
    wmat: float = 0.0
    bab: float = 0.0
    rec_power: float = 1.0
    recruits: float = 0.0
    last_month: int = 0

StanzaIndividual dataclass

Parameters for an individual stanza (age class) within a group.

Attributes: stanza_group_num: Index of parent stanza group stanza_num: Index of this stanza within group (1-based) group_num: Ecopath group number for this stanza group_name: Name of this stanza group in model first: First month of this age class last: Last month of this age class z: Total mortality rate (annual) leading: True if this is the leading (reference) stanza biomass: Calculated biomass qb: Calculated Q/B

Source code in pypath/core/stanzas.py

@dataclass
class StanzaIndividual:
    """Parameters for an individual stanza (age class) within a group.

    Attributes:
        stanza_group_num: Index of parent stanza group
        stanza_num: Index of this stanza within group (1-based)
        group_num: Ecopath group number for this stanza
        group_name: Name of this stanza group in model
        first: First month of this age class
        last: Last month of this age class
        z: Total mortality rate (annual)
        leading: True if this is the leading (reference) stanza
        biomass: Calculated biomass
        qb: Calculated Q/B
    """

    stanza_group_num: int
    stanza_num: int
    group_num: int
    group_name: str
    first: int
    last: int
    z: float
    leading: bool = False
    biomass: float = 0.0
    qb: float = 0.0

calculate_survival

calculate_survival(z_by_month: ndarray, bab: float = 0.0) -> np.ndarray

Calculate cumulative survival to each age.

Parameters:

Name	Type	Description	Default
z_by_month	ndarray	Monthly mortality rate for each month	required
bab	float	Background/accumulation mortality rate (annual)	0.0

Returns:

Type	Description
ndarray	Cumulative survival probability to each age

Source code in pypath/core/stanzas.py

def calculate_survival(z_by_month: np.ndarray, bab: float = 0.0) -> np.ndarray:
    """Calculate cumulative survival to each age.

    Parameters
    ----------
    z_by_month : np.ndarray
        Monthly mortality rate for each month
    bab : float
        Background/accumulation mortality rate (annual)

    Returns
    -------
    np.ndarray
        Cumulative survival probability to each age
    """
    monthly_z = (z_by_month + bab) / 12.0
    monthly_survival = np.exp(-monthly_z)
    # Shift survival - first month survival is 1.0
    monthly_survival = np.concatenate([[1.0], monthly_survival[:-1]])
    return np.cumprod(monthly_survival)

create_stanza_params

create_stanza_params(groups: List[Dict[str, Any]], individuals: List[Dict[str, Any]]) -> EcosimStanzaParams

Create EcosimStanzaParams from dictionaries.

Convenience function to create stanza parameters from dictionary inputs.

Parameters:

Name	Type	Description	Default
groups	List[Dict[str, Any]]	List of dictionaries with stanza group parameters. Required keys: stanza_group_num, n_stanzas, vbgf_ksp. Optional keys: vbgf_d, wmat, bab, rec_power.	required
individuals	List[Dict[str, Any]]	List of dictionaries with individual stanza parameters. Required keys: stanza_group_num, stanza_num, group_num, group_name, first, last, z. Optional keys: leading.	required

Returns:

Type	Description
EcosimStanzaParams	EcosimStanzaParams object

Examples:

>>> groups = [{'stanza_group_num': 1, 'n_stanzas': 2, 'vbgf_ksp': 0.3}]
>>> individuals = [
...     {'stanza_group_num': 1, 'stanza_num': 1, 'group_num': 1,
...      'group_name': 'Fish_juv', 'first': 0, 'last': 11,
...      'z': 1.5, 'leading': False},
...     {'stanza_group_num': 1, 'stanza_num': 2, 'group_num': 2,
...      'group_name': 'Fish_adult', 'first': 12, 'last': 60,
...      'z': 0.5, 'leading': True}
... ]
>>> params = create_stanza_params(groups, individuals)

Source code in pypath/core/stanzas.py

def create_stanza_params(
    groups: List[Dict[str, Any]], individuals: List[Dict[str, Any]]
) -> EcosimStanzaParams:
    """Create EcosimStanzaParams from dictionaries.

    Convenience function to create stanza parameters from
    dictionary inputs.

    Parameters
    ----------
    groups : List[Dict[str, Any]]
        List of dictionaries with stanza group parameters.
        Required keys: stanza_group_num, n_stanzas, vbgf_ksp.
        Optional keys: vbgf_d, wmat, bab, rec_power.
    individuals : List[Dict[str, Any]]
        List of dictionaries with individual stanza parameters.
        Required keys: stanza_group_num, stanza_num, group_num,
        group_name, first, last, z.
        Optional keys: leading.

    Returns
    -------
    EcosimStanzaParams
        EcosimStanzaParams object

    Examples
    --------
        >>> groups = [{'stanza_group_num': 1, 'n_stanzas': 2, 'vbgf_ksp': 0.3}]
        >>> individuals = [
        ...     {'stanza_group_num': 1, 'stanza_num': 1, 'group_num': 1,
        ...      'group_name': 'Fish_juv', 'first': 0, 'last': 11,
        ...      'z': 1.5, 'leading': False},
        ...     {'stanza_group_num': 1, 'stanza_num': 2, 'group_num': 2,
        ...      'group_name': 'Fish_adult', 'first': 12, 'last': 60,
        ...      'z': 0.5, 'leading': True}
        ... ]
        >>> params = create_stanza_params(groups, individuals)
    """
    stanza_groups = []
    for g in groups:
        sg = StanzaGroup(
            stanza_group_num=g["stanza_group_num"],
            n_stanzas=g["n_stanzas"],
            vbgf_ksp=g["vbgf_ksp"],
            vbgf_d=g.get("vbgf_d", 0.66667),
            wmat=g.get("wmat", 0.0),
            bab=g.get("bab", 0.0),
            rec_power=g.get("rec_power", 1.0),
        )
        stanza_groups.append(sg)

    stanza_individuals = []
    for ind in individuals:
        si = StanzaIndividual(
            stanza_group_num=ind["stanza_group_num"],
            stanza_num=ind["stanza_num"],
            group_num=ind["group_num"],
            group_name=ind["group_name"],
            first=ind["first"],
            last=ind["last"],
            z=ind["z"],
            leading=ind.get("leading", False),
        )
        stanza_individuals.append(si)

    return EcosimStanzaParams(
        n_stanza_groups=len(groups),
        stanza_groups=stanza_groups,
        stanza_individuals=stanza_individuals,
    )

rpath_stanzas

rpath_stanzas(rpath_params: RpathParams) -> RpathParams

Calculate biomass and consumption for multi-stanza groups.

Uses the leading stanza to calculate biomass and consumption of trailing stanzas necessary to support the leading stanza.

This implements Von Bertalanffy growth to distribute biomass across age classes based on the leading stanza's biomass.

Parameters:

Name	Type	Description	Default
rpath_params	RpathParams	RpathParams object with stanza information	required

Returns:

Type	Description
RpathParams	Updated RpathParams with calculated stanza biomass and Q/B

Source code in pypath/core/stanzas.py

def rpath_stanzas(rpath_params: RpathParams) -> RpathParams:
    """Calculate biomass and consumption for multi-stanza groups.

    Uses the leading stanza to calculate biomass and consumption
    of trailing stanzas necessary to support the leading stanza.

    This implements Von Bertalanffy growth to distribute biomass
    across age classes based on the leading stanza's biomass.

    Parameters
    ----------
    rpath_params : RpathParams
        RpathParams object with stanza information

    Returns
    -------
    RpathParams
        Updated RpathParams with calculated stanza biomass and Q/B
    """
    # Check if stanzas exist
    if rpath_params.stanzas is None:
        return rpath_params

    stanza_params = rpath_params.stanzas
    if stanza_params.n_stanza_groups == 0:
        return rpath_params

    n_split = stanza_params.n_stanza_groups

    # Process each stanza group
    for isp in range(n_split):
        stanza_group = stanza_params.stanza_groups[isp]

        # Get stanzas for this group
        group_stanzas = [
            s for s in stanza_params.stanza_individuals if s.stanza_group_num == isp + 1
        ]
        group_stanzas.sort(key=lambda x: x.stanza_num)

        _n_stanzas = len(group_stanzas)

        # Find the leading stanza
        leading_stanza = None
        for st in group_stanzas:
            if st.leading:
                leading_stanza = st
                break

        if leading_stanza is None:
            raise ValueError(f"No leading stanza found for stanza group {isp + 1}")

        # Calculate last month using biomass accumulation method
        # This finds the age at which 99.999% of cumulative biomass is reached
        st_max = group_stanzas[-1]

        # Get growth parameters
        k_monthly = (stanza_group.vbgf_ksp * 3) / 12.0
        d = stanza_group.vbgf_d
        bab = stanza_group.bab

        # Calculate out to a very long time (5999 months = ~500 years)
        ages = np.arange(st_max.first, 6000)
        monthly_z = (st_max.z + bab) / 12.0

        # Survival and biomass
        nn = np.cumprod(
            np.concatenate([[1.0], np.exp(-monthly_z * np.ones(len(ages) - 1))])
        )
        bb = nn * von_bertalanffy_weight(ages, k_monthly, d)

        # Cumulative biomass fraction
        bb_cum = np.cumsum(bb) / np.sum(bb)

        # Find age at 99.999% cumulative biomass
        idx = int(np.searchsorted(bb_cum, 0.99999, side="left"))
        if idx >= len(ages):
            idx = len(ages) - 1
        last_month = int(np.ceil((ages[idx] + 1) / 12.0) * 12 - 1)

        stanza_group.last_month = last_month

        # Update oldest stanza's last month
        group_stanzas[-1].last = last_month

        # Build age-structured table for this group
        all_ages = np.arange(group_stanzas[0].first, last_month + 1)

        st_group = pd.DataFrame(
            {
                "age": all_ages,
                "WageS": von_bertalanffy_weight(all_ages, k_monthly, d),
            }
        )
        st_group["QageS"] = von_bertalanffy_consumption(st_group["WageS"].values, d)

        # Calculate survival for each age
        # Need to assign Z by stanza
        z_by_age = np.zeros(len(all_ages))
        for st in group_stanzas:
            mask = (all_ages >= st.first) & (all_ages <= st.last)
            z_by_age[mask] = st.z

        st_group["Survive"] = calculate_survival(z_by_age, bab)

        # Biomass and consumption relative values
        st_group["B"] = st_group["Survive"] * st_group["WageS"]
        st_group["Q"] = st_group["Survive"] * st_group["QageS"]

        # Calculate relative biomass/consumption for each stanza
        for st in group_stanzas:
            mask = (st_group["age"] >= st.first) & (st_group["age"] <= st.last)
            st.bs_num = st_group.loc[mask, "B"].sum()
            st.qs_num = st_group.loc[mask, "Q"].sum()

        # Total biomass and consumption denominators
        bs_denom = sum(st.bs_num for st in group_stanzas)
        qs_denom = sum(st.qs_num for st in group_stanzas)

        # Relative fractions
        for st in group_stanzas:
            st.bs = st.bs_num / bs_denom if bs_denom > 0 else 0
            st.qs = st.qs_num / qs_denom if qs_denom > 0 else 0

        # Get leading stanza biomass from model
        leading_idx = rpath_params.model[
            rpath_params.model["Group"] == leading_stanza.group_name
        ].index[0]
        leading_biomass = rpath_params.model.loc[leading_idx, "Biomass"]
        leading_qb = rpath_params.model.loc[leading_idx, "QB"]

        # Calculate total biomass and consumption from leading
        if leading_stanza.bs > 0:
            total_biomass = leading_biomass / leading_stanza.bs
        else:
            total_biomass = leading_biomass

        if leading_stanza.qs > 0:
            total_cons = leading_qb * leading_biomass / leading_stanza.qs
        else:
            total_cons = leading_qb * leading_biomass

        # Distribute to other stanzas
        for st in group_stanzas:
            st.biomass = st.bs * total_biomass
            st.qb = (st.qs * total_cons) / st.biomass if st.biomass > 0 else 0

        # Calculate recruits (numbers at age 0)
        bio_per_egg = st_group.loc[
            (st_group["age"] >= leading_stanza.first)
            & (st_group["age"] <= leading_stanza.last),
            "B",
        ].sum()

        if bio_per_egg > 0:
            recruits = leading_biomass / bio_per_egg
        else:
            recruits = 0

        stanza_group.recruits = recruits

        # Numbers at age
        st_group["NageS"] = st_group["Survive"] * recruits

        # Store in params
        stanza_params.st_groups[isp + 1] = st_group

        # Update model DataFrame with calculated values
        for st in group_stanzas:
            model_idx = rpath_params.model[
                rpath_params.model["Group"] == st.group_name
            ].index
            if len(model_idx) > 0:
                rpath_params.model.loc[model_idx[0], "Biomass"] = st.biomass
                rpath_params.model.loc[model_idx[0], "QB"] = st.qb

    return rpath_params

rsim_stanzas

rsim_stanzas(rpath_params: RpathParams, state: ndarray, params: dict) -> RsimStanzas

Initialize stanza parameters for Ecosim simulation.

Creates the stanza parameter structure needed by rsim_run().

Parameters:

Name	Type	Description	Default
rpath_params	RpathParams	RpathParams object with stanza information	required
state	ndarray	RsimState object with initial state	required
params	dict	RsimParams object with simulation parameters	required

Returns:

Type	Description
RsimStanzas	RsimStanzas object with simulation parameters

Source code in pypath/core/stanzas.py

def rsim_stanzas(
    rpath_params: RpathParams, state: np.ndarray, params: dict
) -> RsimStanzas:
    """Initialize stanza parameters for Ecosim simulation.

    Creates the stanza parameter structure needed by rsim_run().

    Parameters
    ----------
    rpath_params : RpathParams
        RpathParams object with stanza information
    state : np.ndarray
        RsimState object with initial state
    params : dict
        RsimParams object with simulation parameters

    Returns
    -------
    RsimStanzas
        RsimStanzas object with simulation parameters
    """
    rstan = RsimStanzas()

    # Check if stanzas exist
    if rpath_params.stanzas is None or rpath_params.stanzas.n_stanza_groups == 0:
        # Return empty stanza structure
        rstan.n_split = 0
        rstan.n_stanzas = np.array([0, 0])
        rstan.ecopath_code = np.zeros((2, 2))
        rstan.age1 = np.zeros((2, 2))
        rstan.age2 = np.zeros((2, 2))
        rstan.base_wage_s = np.zeros((2, 2))
        rstan.base_nage_s = np.zeros((2, 2))
        rstan.base_qage_s = np.zeros((2, 2))
        rstan.wmat = np.array([0.0, 0.0])
        rstan.rec_power = np.array([0.0, 0.0])
        rstan.recruits = np.array([0.0, 0.0])
        rstan.vbgf_d = np.array([0.0, 0.0])
        rstan.r_zero_s = np.array([0.0, 0.0])
        rstan.vbm = np.array([0.0, 0.0])
        rstan.split_alpha = np.zeros((2, 2))
        rstan.spawn_x = np.array([0.0, 0.0])
        rstan.spawn_energy = np.array([0.0, 0.0])
        rstan.base_eggs_stanza = np.array([0.0, 0.0])
        rstan.base_spawn_bio = np.array([0.0, 0.0])
        rstan.r_scale_split = np.array([0.0, 0.0])
        rstan.base_stanza_pred = np.zeros(params.NUM_GROUPS + 1)
        return rstan

    stanza_params = rpath_params.stanzas
    n_split = stanza_params.n_stanza_groups

    rstan.n_split = n_split

    # Get max stanzas and max months
    max_stanzas = max(sg.n_stanzas for sg in stanza_params.stanza_groups)
    max_months = max(sg.last_month for sg in stanza_params.stanza_groups) + 1

    # Initialize arrays with leading zeros for C-style indexing
    rstan.n_stanzas = np.zeros(n_split + 1, dtype=int)
    rstan.ecopath_code = np.full((n_split + 1, max_stanzas + 1), np.nan)
    rstan.age1 = np.full((n_split + 1, max_stanzas + 1), np.nan)
    rstan.age2 = np.full((n_split + 1, max_stanzas + 1), np.nan)
    rstan.base_wage_s = np.full((max_months, n_split + 1), np.nan)
    rstan.base_nage_s = np.full((max_months, n_split + 1), np.nan)
    rstan.base_qage_s = np.full((max_months, n_split + 1), np.nan)
    rstan.split_alpha = np.full((max_months, n_split + 1), np.nan)

    # Stanza pred accumulator (extra leading slot for 1-based indexing)
    s_pred = np.zeros(params.NUM_GROUPS + 2)

    # Process each stanza group
    for isp in range(n_split):
        stanza_group = stanza_params.stanza_groups[isp]
        rstan.n_stanzas[isp + 1] = stanza_group.n_stanzas

        # Get stanzas for this group
        group_stanzas = [
            s for s in stanza_params.stanza_individuals if s.stanza_group_num == isp + 1
        ]
        group_stanzas.sort(key=lambda x: x.stanza_num)

        # Fill in age codes
        for ist, st in enumerate(group_stanzas):
            rstan.ecopath_code[isp + 1, ist + 1] = st.group_num
            rstan.age1[isp + 1, ist + 1] = st.first
            rstan.age2[isp + 1, ist + 1] = st.last

        # Get age-structured data
        if isp + 1 in stanza_params.st_groups:
            st_group = stanza_params.st_groups[isp + 1]
            n_rows = len(st_group)
            rstan.base_wage_s[:n_rows, isp + 1] = st_group["WageS"].values
            rstan.base_nage_s[:n_rows, isp + 1] = st_group["NageS"].values
            rstan.base_qage_s[:n_rows, isp + 1] = st_group["QageS"].values

    # Maturity and recruitment parameters
    rstan.wmat = np.zeros(n_split + 1)
    rstan.rec_power = np.zeros(n_split + 1)
    rstan.recruits = np.zeros(n_split + 1)
    rstan.vbgf_d = np.zeros(n_split + 1)
    rstan.r_zero_s = np.zeros(n_split + 1)
    rstan.vbm = np.zeros(n_split + 1)

    for isp, sg in enumerate(stanza_params.stanza_groups):
        rstan.wmat[isp + 1] = sg.wmat
        rstan.rec_power[isp + 1] = sg.rec_power
        rstan.recruits[isp + 1] = sg.recruits
        rstan.vbgf_d[isp + 1] = sg.vbgf_d
        rstan.r_zero_s[isp + 1] = sg.recruits
        # Energy required to grow a unit in weight (scaled to Winf=1)
        rstan.vbm[isp + 1] = 1.0 - 3.0 * sg.vbgf_ksp / 12.0

    # Calculate spawning biomass and eggs
    eggs = np.zeros(n_split + 1)
    for isp in range(n_split):
        stanza_group = stanza_params.stanza_groups[isp]
        if isp + 1 in stanza_params.st_groups:
            st_group = stanza_params.st_groups[isp + 1]
            # Sum eggs from mature individuals
            mature_mask = st_group["WageS"] > rstan.wmat[isp + 1]
            if mature_mask.any():
                eggs[isp + 1] = (
                    st_group.loc[mature_mask, "NageS"]
                    * (st_group.loc[mature_mask, "WageS"] - rstan.wmat[isp + 1])
                ).sum()

    # Initialize split alpha growth coefficients
    for isp in range(n_split):
        stanza_group = stanza_params.stanza_groups[isp]
        group_stanzas = [
            s for s in stanza_params.stanza_individuals if s.stanza_group_num == isp + 1
        ]
        group_stanzas.sort(key=lambda x: x.stanza_num)

        if isp + 1 not in stanza_params.st_groups:
            continue

        st_group = stanza_params.st_groups[isp + 1]

        for ist, st in enumerate(group_stanzas):
            ieco = st.group_num
            first = st.first
            last = st.last

            # Calculate predation for this stanza
            mask = (st_group["age"] >= first) & (st_group["age"] <= last)
            pred = (st_group.loc[mask, "NageS"] * st_group.loc[mask, "QageS"]).sum()

            # Get consumption
            start_eaten_by = st.qb * st.biomass

            if start_eaten_by > 0:
                # Calculate split alpha
                wage_s = st_group["WageS"].values
                wage_s_next = np.roll(wage_s, -1)
                wage_s_next[-1] = wage_s[-1]

                split_alpha = (
                    (wage_s_next - rstan.vbm[isp + 1] * wage_s) * pred / start_eaten_by
                )
                rstan.split_alpha[first : last + 1, isp + 1] = split_alpha[
                    first : last + 1
                ]

            s_pred[ieco + 1] = pred

        # Carry over final split alpha to plus group
        last_stanza = group_stanzas[-1]
        final_age = last_stanza.last
        if final_age > 0 and final_age < max_months:
            rstan.split_alpha[final_age, isp + 1] = rstan.split_alpha[
                final_age - 1, isp + 1
            ]

    # Misc parameters
    # Spawn X is Beverton-Holt. 10000 = off, 2 = half saturation
    rstan.spawn_x = np.concatenate([[0.0], np.full(n_split, 10000.0)])
    rstan.spawn_energy = np.concatenate([[0.0], np.ones(n_split)])
    rstan.base_eggs_stanza = eggs
    rstan.base_spawn_bio = eggs.copy()
    rstan.r_scale_split = np.concatenate([[0.0], np.ones(n_split)])
    rstan.base_stanza_pred = s_pred

    return rstan

split_set_pred

split_set_pred(stanzas: RsimStanzas, state: ndarray, params: dict) -> None

Set predation rates for stanza groups.

Updates the consumption calculations for multi-stanza groups based on current biomass.

Parameters:

Name	Type	Description	Default
stanzas	RsimStanzas	RsimStanzas object	required
state	ndarray	RsimState with current biomass	required
params	dict	RsimParams with model parameters	required

Source code in pypath/core/stanzas.py

def split_set_pred(stanzas: RsimStanzas, state: np.ndarray, params: dict) -> None:
    """Set predation rates for stanza groups.

    Updates the consumption calculations for multi-stanza
    groups based on current biomass.

    Parameters
    ----------
    stanzas : RsimStanzas
        RsimStanzas object
    state : np.ndarray
        RsimState with current biomass
    params : dict
        RsimParams with model parameters
    """
    if stanzas.n_split == 0:
        return

    s_pred = np.zeros(params.NUM_GROUPS + 2)

    for isp in range(1, stanzas.n_split + 1):
        n_stanzas = stanzas.n_stanzas[isp]

        if n_stanzas == 0:
            continue

        for ist in range(1, n_stanzas + 1):
            ieco = int(stanzas.ecopath_code[isp, ist])
            first = int(stanzas.age1[isp, ist])
            last = int(stanzas.age2[isp, ist])

            # Calculate total consumption for this stanza
            pred = 0.0
            for age in range(first, last + 1):
                nage_s = stanzas.base_nage_s[age, isp]
                qage_s = stanzas.base_qage_s[age, isp]

                if not np.isnan(nage_s) and not np.isnan(qage_s):
                    pred += nage_s * qage_s

            s_pred[ieco + 1] = pred

    stanzas.base_stanza_pred = s_pred

split_update

split_update(stanzas: RsimStanzas, state: ndarray, params: dict, sim_month: int) -> None

Update stanza age structure for a simulation month.

This updates the numbers-at-age, weight-at-age, and recruitment for multi-stanza groups.

Called monthly during Ecosim simulation.

Parameters:

Name	Type	Description	Default
stanzas	RsimStanzas	RsimStanzas object	required
state	ndarray	RsimState with current biomass	required
params	dict	RsimParams with model parameters	required
sim_month	int	Current simulation month	required

Source code in pypath/core/stanzas.py

def split_update(
    stanzas: RsimStanzas, state: np.ndarray, params: dict, sim_month: int
) -> None:
    """Update stanza age structure for a simulation month.

    This updates the numbers-at-age, weight-at-age, and
    recruitment for multi-stanza groups.

    Called monthly during Ecosim simulation.

    Parameters
    ----------
    stanzas : RsimStanzas
        RsimStanzas object
    state : np.ndarray
        RsimState with current biomass
    params : dict
        RsimParams with model parameters
    sim_month : int
        Current simulation month
    """
    if stanzas.n_split == 0:
        return

    for isp in range(1, stanzas.n_split + 1):
        n_stanzas = stanzas.n_stanzas[isp]

        if n_stanzas == 0:
            continue

        # Get Von Bertalanffy parameters
        _vbm = stanzas.vbm[isp]
        _vbgf_d = stanzas.vbgf_d[isp]

        # Get current spawning biomass
        spawn_bio = 0.0
        wmat = stanzas.wmat[isp]

        # Sum spawning biomass from mature age classes
        for ist in range(1, n_stanzas + 1):
            first = int(stanzas.age1[isp, ist])
            last = int(stanzas.age2[isp, ist])

            for age in range(first, last + 1):
                wage_s = stanzas.base_wage_s[age, isp]
                nage_s = stanzas.base_nage_s[age, isp]

                if wage_s > wmat and not np.isnan(wage_s) and not np.isnan(nage_s):
                    spawn_bio += nage_s * (wage_s - wmat)

        stanzas.base_spawn_bio[isp] = spawn_bio

        # Calculate recruitment using Beverton-Holt if spawn_x < 10000
        spawn_x = stanzas.spawn_x[isp]
        r_zero = stanzas.r_zero_s[isp]
        base_spawn = stanzas.base_eggs_stanza[isp]

        if spawn_x < 9999 and base_spawn > 0:
            # Beverton-Holt recruitment
            rel_spawn = spawn_bio / base_spawn
            recruits = (
                r_zero * rel_spawn / (1.0 + (spawn_x - 1.0) * rel_spawn / spawn_x)
            )
        else:
            recruits = stanzas.recruits[isp]

        # Update numbers at age (aging process)
        # Shift numbers forward by one month
        new_nage = np.roll(stanzas.base_nage_s[:, isp], 1)
        new_nage[0] = recruits  # New recruits enter at age 0

        # Apply mortality
        for ist in range(1, n_stanzas + 1):
            ieco = int(stanzas.ecopath_code[isp, ist])
            first = int(stanzas.age1[isp, ist])
            last = int(stanzas.age2[isp, ist])

            # Get current mortality from state (guard against indexing issues)
            if hasattr(params, "MzeroMort") and (ieco + 1) < len(params.MzeroMort):
                m0 = params.MzeroMort[ieco + 1]
            else:
                m0 = 0.0

            # Apply monthly mortality
            monthly_z = m0 / 12.0
            survival = np.exp(-monthly_z)

            for age in range(first, last + 1):
                if age < len(new_nage):
                    new_nage[age] *= survival

        stanzas.base_nage_s[:, isp] = new_nage

von_bertalanffy_consumption

von_bertalanffy_consumption(wage_s: ndarray, d: float = 0.66667) -> np.ndarray

Calculate consumption at age from weight.

Q(a) = W(a)^d

Parameters:

Name	Type	Description	Default
wage_s	ndarray	Weight at age relative to Winf	required
d	float	Allometric exponent (default 2/3)	0.66667

Returns:

Type	Description
ndarray	Consumption at each age

Source code in pypath/core/stanzas.py

def von_bertalanffy_consumption(wage_s: np.ndarray, d: float = 0.66667) -> np.ndarray:
    """Calculate consumption at age from weight.

    Q(a) = W(a)^d

    Parameters
    ----------
    wage_s : np.ndarray
        Weight at age relative to Winf
    d : float
        Allometric exponent (default 2/3)

    Returns
    -------
    np.ndarray
        Consumption at each age
    """
    return wage_s**d

von_bertalanffy_weight

von_bertalanffy_weight(age: ndarray, k: float, d: float = 0.66667) -> np.ndarray

Calculate weight at age using Von Bertalanffy growth model.

W(a) = (1 - exp(-K * (1-d) * a))^(1/(1-d))

Weight is relative to Winf (asymptotic weight = 1).

Parameters:

Name	Type	Description	Default
age	ndarray	Age in months	required
k	float	Monthly K parameter (Ksp * 3 / 12)	required
d	float	Allometric exponent (default 2/3)	0.66667

Returns:

Type	Description
ndarray	Weight relative to Winf at each age

Raises:

Type	Description
ValueError	If d is not in the open interval (0, 1).

Source code in pypath/core/stanzas.py

def von_bertalanffy_weight(age: np.ndarray, k: float, d: float = 0.66667) -> np.ndarray:
    """Calculate weight at age using Von Bertalanffy growth model.

    W(a) = (1 - exp(-K * (1-d) * a))^(1/(1-d))

    Weight is relative to Winf (asymptotic weight = 1).

    Parameters
    ----------
    age : np.ndarray
        Age in months
    k : float
        Monthly K parameter (Ksp * 3 / 12)
    d : float
        Allometric exponent (default 2/3)

    Returns
    -------
    np.ndarray
        Weight relative to Winf at each age

    Raises
    ------
    ValueError
        If d is not in the open interval (0, 1).
    """
    if not (0 < d < 1):
        raise ValueError(f"d must be in (0, 1), got {d}")
    return (1.0 - np.exp(-k * (1.0 - d) * age)) ** (1.0 / (1.0 - d))

Adjustments

pypath.core.adjustments

Adjustment functions for Ecosim scenarios.

This module provides functions to modify fishing rates, forcing functions, and other scenario parameters over time.

Based on Rpath's adjust.fishing(), adjust.forcing(), and adjust.scenario() functions.

adjust_fishing

adjust_fishing(scenario: RsimScenario, parameter: str, group: Union[str, int, List[Union[str, int]]], sim_year: Union[int, range, List[int]], value: Union[float, ndarray], sim_month: Optional[Union[int, range, List[int]]] = None) -> RsimScenario

Adjust fishing parameters in an Ecosim scenario.

Modifies fishing-related forcing matrices (ForcedEffort, ForcedFRate, or ForcedCatch) for specified groups and time periods.

Parameters:

Name	Type	Description	Default
scenario	RsimScenario	RsimScenario object to modify	required
parameter	str	One of 'ForcedEffort', 'ForcedFRate', or 'ForcedCatch'	required
group	Union[str, int, List[Union[str, int]]]	Group name(s) or index(es) to modify. Can be: - Single group name (str) or index (int) - List of group names or indices	required
sim_year	Union[int, range, List[int]]	Year(s) to modify. Can be: - Single year (int) - Range of years (range object) - List of years	required
value	Union[float, ndarray]	New value(s) to set. Can be: - Single value applied to all specified cells - Array matching the shape of selected cells	required
sim_month	Optional[Union[int, range, List[int]]]	Optional month(s) to modify (1-12). Only used for ForcedEffort which is monthly. If None, modifies all months.	None

Returns:

Type	Description
RsimScenario	Modified scenario object

Examples:

>>> # Double fishing mortality for 'Fish' group in years 10-20
>>> scenario = adjust_fishing(
...     scenario,
...     parameter='ForcedFRate',
...     group='Fish',
...     sim_year=range(10, 21),
...     value=0.5
... )

>>> # Set catch quota
>>> scenario = adjust_fishing(
...     scenario,
...     parameter='ForcedCatch',
...     group=['Cod', 'Haddock'],
...     sim_year=2025,
...     value=100.0
... )

Source code in pypath/core/adjustments.py

def adjust_fishing(
    scenario: RsimScenario,
    parameter: str,
    group: Union[str, int, List[Union[str, int]]],
    sim_year: Union[int, range, List[int]],
    value: Union[float, np.ndarray],
    sim_month: Optional[Union[int, range, List[int]]] = None,
) -> RsimScenario:
    """Adjust fishing parameters in an Ecosim scenario.

    Modifies fishing-related forcing matrices (ForcedEffort, ForcedFRate,
    or ForcedCatch) for specified groups and time periods.

    Parameters
    ----------
    scenario : RsimScenario
        RsimScenario object to modify
    parameter : str
        One of 'ForcedEffort', 'ForcedFRate', or 'ForcedCatch'
    group : Union[str, int, List[Union[str, int]]]
        Group name(s) or index(es) to modify. Can be:
        - Single group name (str) or index (int)
        - List of group names or indices
    sim_year : Union[int, range, List[int]]
        Year(s) to modify. Can be:
        - Single year (int)
        - Range of years (range object)
        - List of years
    value : Union[float, np.ndarray]
        New value(s) to set. Can be:
        - Single value applied to all specified cells
        - Array matching the shape of selected cells
    sim_month : Optional[Union[int, range, List[int]]]
        Optional month(s) to modify (1-12). Only used for
        ForcedEffort which is monthly. If None, modifies all months.

    Returns
    -------
    RsimScenario
        Modified scenario object

    Examples
    --------
        >>> # Double fishing mortality for 'Fish' group in years 10-20
        >>> scenario = adjust_fishing(
        ...     scenario,
        ...     parameter='ForcedFRate',
        ...     group='Fish',
        ...     sim_year=range(10, 21),
        ...     value=0.5
        ... )

        >>> # Set catch quota
        >>> scenario = adjust_fishing(
        ...     scenario,
        ...     parameter='ForcedCatch',
        ...     group=['Cod', 'Haddock'],
        ...     sim_year=2025,
        ...     value=100.0
        ... )
    """
    valid_params = ["ForcedEffort", "ForcedFRate", "ForcedCatch"]
    if parameter not in valid_params:
        raise ValueError(f"parameter must be one of {valid_params}")

    # Get the fishing matrix
    fishing_matrix = getattr(scenario.fishing, parameter)

    # Convert group to indices
    group_indices = _resolve_group_indices(scenario, group, parameter)

    # Convert years to row indices
    year_indices = _resolve_year_indices(scenario, sim_year, parameter)

    # For ForcedEffort (monthly), handle month selection
    if parameter == "ForcedEffort" and sim_month is not None:
        row_indices = _resolve_month_indices(
            year_indices, sim_month, fishing_matrix.shape[0]
        )
    else:
        row_indices = year_indices

    # Set values
    if np.isscalar(value):
        for gi in group_indices:
            for ri in row_indices:
                fishing_matrix[ri, gi] = value
    else:
        # Value is an array - must match shape
        value = np.asarray(value)
        if value.shape == (len(row_indices), len(group_indices)):
            for i, ri in enumerate(row_indices):
                for j, gi in enumerate(group_indices):
                    fishing_matrix[ri, gi] = value[i, j]
        elif value.shape == (len(row_indices),):
            # Broadcast across groups
            for gi in group_indices:
                for i, ri in enumerate(row_indices):
                    fishing_matrix[ri, gi] = value[i]
        else:
            raise ValueError(f"value shape {value.shape} doesn't match selection")

    return scenario

adjust_forcing

adjust_forcing(scenario: RsimScenario, parameter: str, group: Union[str, int, List[Union[str, int]]], sim_year: Union[int, range, List[int]], sim_month: Union[int, range, List[int]], value: Union[float, ndarray]) -> RsimScenario

Adjust forcing parameters in an Ecosim scenario.

Modifies environmental forcing matrices (ForcedPrey, ForcedMort, ForcedRecs, ForcedSearch, ForcedActresp, ForcedMigrate, ForcedBio) for specified groups and time periods.

Parameters:

Name	Type	Description	Default
scenario	RsimScenario	RsimScenario object to modify	required
parameter	str	One of: - 'ForcedPrey': Prey availability multiplier - 'ForcedMort': Additional mortality multiplier - 'ForcedRecs': Recruitment multiplier - 'ForcedSearch': Search rate multiplier - 'ForcedActresp': Active respiration multiplier - 'ForcedMigrate': Migration rate (additive) - 'ForcedBio': Biomass forcing (-1 = off)	required
group	Union[str, int, List[Union[str, int]]]	Group name(s) or index(es) to modify	required
sim_year	Union[int, range, List[int]]	Year(s) to modify	required
sim_month	Union[int, range, List[int]]	Month(s) to modify (1-12)	required
value	Union[float, ndarray]	New value(s) to set	required

Returns:

Type	Description
RsimScenario	Modified scenario object

Examples:

>>> # Reduce prey availability in summer
>>> scenario = adjust_forcing(
...     scenario,
...     parameter='ForcedPrey',
...     group='Zooplankton',
...     sim_year=range(1, 51),
...     sim_month=[6, 7, 8],
...     value=0.8
... )

>>> # Add pulse recruitment
>>> scenario = adjust_forcing(
...     scenario,
...     parameter='ForcedRecs',
...     group='Fish',
...     sim_year=15,
...     sim_month=3,
...     value=2.0
... )

Source code in pypath/core/adjustments.py

def adjust_forcing(
    scenario: RsimScenario,
    parameter: str,
    group: Union[str, int, List[Union[str, int]]],
    sim_year: Union[int, range, List[int]],
    sim_month: Union[int, range, List[int]],
    value: Union[float, np.ndarray],
) -> RsimScenario:
    """Adjust forcing parameters in an Ecosim scenario.

    Modifies environmental forcing matrices (ForcedPrey, ForcedMort,
    ForcedRecs, ForcedSearch, ForcedActresp, ForcedMigrate, ForcedBio)
    for specified groups and time periods.

    Parameters
    ----------
    scenario : RsimScenario
        RsimScenario object to modify
    parameter : str
        One of:
        - 'ForcedPrey': Prey availability multiplier
        - 'ForcedMort': Additional mortality multiplier
        - 'ForcedRecs': Recruitment multiplier
        - 'ForcedSearch': Search rate multiplier
        - 'ForcedActresp': Active respiration multiplier
        - 'ForcedMigrate': Migration rate (additive)
        - 'ForcedBio': Biomass forcing (-1 = off)
    group : Union[str, int, List[Union[str, int]]]
        Group name(s) or index(es) to modify
    sim_year : Union[int, range, List[int]]
        Year(s) to modify
    sim_month : Union[int, range, List[int]]
        Month(s) to modify (1-12)
    value : Union[float, np.ndarray]
        New value(s) to set

    Returns
    -------
    RsimScenario
        Modified scenario object

    Examples
    --------
        >>> # Reduce prey availability in summer
        >>> scenario = adjust_forcing(
        ...     scenario,
        ...     parameter='ForcedPrey',
        ...     group='Zooplankton',
        ...     sim_year=range(1, 51),
        ...     sim_month=[6, 7, 8],
        ...     value=0.8
        ... )

        >>> # Add pulse recruitment
        >>> scenario = adjust_forcing(
        ...     scenario,
        ...     parameter='ForcedRecs',
        ...     group='Fish',
        ...     sim_year=15,
        ...     sim_month=3,
        ...     value=2.0
        ... )
    """
    valid_params = [
        "ForcedPrey",
        "ForcedMort",
        "ForcedRecs",
        "ForcedSearch",
        "ForcedActresp",
        "ForcedMigrate",
        "ForcedBio",
    ]
    if parameter not in valid_params:
        raise ValueError(f"parameter must be one of {valid_params}")

    # Get the forcing matrix
    forcing_matrix = getattr(scenario.forcing, parameter)

    # Convert group to indices
    group_indices = _resolve_group_indices(scenario, group, parameter, is_forcing=True)

    # Convert years to row indices
    year_indices = _resolve_year_indices(scenario, sim_year, parameter)

    # Convert to monthly row indices
    row_indices = _resolve_month_indices(
        year_indices, sim_month, forcing_matrix.shape[0]
    )

    # Set values
    if np.isscalar(value):
        for gi in group_indices:
            for ri in row_indices:
                forcing_matrix[ri, gi] = value
    else:
        value = np.asarray(value)
        if value.shape == (len(row_indices), len(group_indices)):
            for i, ri in enumerate(row_indices):
                for j, gi in enumerate(group_indices):
                    forcing_matrix[ri, gi] = value[i, j]
        elif value.shape == (len(row_indices),):
            for gi in group_indices:
                for i, ri in enumerate(row_indices):
                    forcing_matrix[ri, gi] = value[i]
        else:
            raise ValueError(f"value shape {value.shape} doesn't match selection")

    return scenario

adjust_group_parameter

adjust_group_parameter(scenario: RsimScenario, group: Union[str, int], parameter: str, value: float) -> RsimScenario

Adjust a parameter for a specific group.

Modifies group-level parameters in the scenario's params object.

Parameters:

Name	Type	Description	Default
scenario	RsimScenario	RsimScenario object to modify	required
group	Union[str, int]	Group name or index	required
parameter	str	Parameter name. Options include: - 'MzeroMort': Background mortality - 'UnassimRespFrac': Unassimilated fraction - 'ActiveRespFrac': Active respiration fraction - 'FtimeAdj': Feeding time adjustment - 'PBopt': Optimal P/B	required
value	float	New value to set	required

Returns:

Type	Description
RsimScenario	Modified scenario object

Source code in pypath/core/adjustments.py

def adjust_group_parameter(
    scenario: RsimScenario, group: Union[str, int], parameter: str, value: float
) -> RsimScenario:
    """Adjust a parameter for a specific group.

    Modifies group-level parameters in the scenario's params object.

    Parameters
    ----------
    scenario : RsimScenario
        RsimScenario object to modify
    group : Union[str, int]
        Group name or index
    parameter : str
        Parameter name. Options include:
        - 'MzeroMort': Background mortality
        - 'UnassimRespFrac': Unassimilated fraction
        - 'ActiveRespFrac': Active respiration fraction
        - 'FtimeAdj': Feeding time adjustment
        - 'PBopt': Optimal P/B
    value : float
        New value to set

    Returns
    -------
    RsimScenario
        Modified scenario object
    """
    group_idx = _get_group_index(scenario, group) + 1  # +1 for "Outside"

    if hasattr(scenario.params, parameter):
        param_array = getattr(scenario.params, parameter)
        if isinstance(param_array, np.ndarray) and len(param_array) > group_idx:
            param_array[group_idx] = value
        else:
            raise ValueError(
                f"Parameter '{parameter}' not accessible at index {group_idx}"
            )
    else:
        raise AttributeError(f"Parameter '{parameter}' not found in scenario.params")

    return scenario

adjust_scenario

adjust_scenario(scenario: RsimScenario, parameter: str, value: Union[float, int, ndarray]) -> RsimScenario

Adjust global scenario parameters.

Modifies simulation-wide parameters in the scenario's params object.

Parameters:

Name	Type	Description	Default
scenario	RsimScenario	RsimScenario object to modify	required
parameter	str	Parameter name to modify. Common options: - 'BURN_YEARS': Number of burn-in years (-1 = off) - 'COUPLED': Coupling flag (0 = uncoupled, 1 = coupled) - 'RK4_STEPS': Integration steps per month - 'SENSE_LIMIT': Sensitivity limits [min, max]	required
value	Union[float, int, ndarray]	New value to set	required

Returns:

Type	Description
RsimScenario	Modified scenario object

Examples:

>>> # Enable burn-in period
>>> scenario = adjust_scenario(scenario, 'BURN_YEARS', 10)

>>> # Change integration precision
>>> scenario = adjust_scenario(scenario, 'RK4_STEPS', 8)

Source code in pypath/core/adjustments.py

def adjust_scenario(
    scenario: RsimScenario, parameter: str, value: Union[float, int, np.ndarray]
) -> RsimScenario:
    """Adjust global scenario parameters.

    Modifies simulation-wide parameters in the scenario's params object.

    Parameters
    ----------
    scenario : RsimScenario
        RsimScenario object to modify
    parameter : str
        Parameter name to modify. Common options:
        - 'BURN_YEARS': Number of burn-in years (-1 = off)
        - 'COUPLED': Coupling flag (0 = uncoupled, 1 = coupled)
        - 'RK4_STEPS': Integration steps per month
        - 'SENSE_LIMIT': Sensitivity limits [min, max]
    value : Union[float, int, np.ndarray]
        New value to set

    Returns
    -------
    RsimScenario
        Modified scenario object

    Examples
    --------
        >>> # Enable burn-in period
        >>> scenario = adjust_scenario(scenario, 'BURN_YEARS', 10)

        >>> # Change integration precision
        >>> scenario = adjust_scenario(scenario, 'RK4_STEPS', 8)
    """
    if hasattr(scenario.params, parameter):
        setattr(scenario.params, parameter, value)
    else:
        raise AttributeError(f"Parameter '{parameter}' not found in scenario.params")

    return scenario

create_fishing_ramp

create_fishing_ramp(scenario: RsimScenario, group: Union[str, int], start_year: int, end_year: int, start_value: float, end_value: float, parameter: str = 'ForcedFRate') -> RsimScenario

Create a linear ramp in fishing pressure.

Convenience function to linearly interpolate fishing between two values over a range of years.

Parameters:

Name	Type	Description	Default
scenario	RsimScenario	RsimScenario object to modify	required
group	Union[str, int]	Group to modify	required
start_year	int	First year of ramp	required
end_year	int	Last year of ramp	required
start_value	float	Value at start_year	required
end_value	float	Value at end_year	required
parameter	str	Fishing parameter to modify	'ForcedFRate'

Returns:

Type	Description
RsimScenario	Modified scenario object

Source code in pypath/core/adjustments.py

def create_fishing_ramp(
    scenario: RsimScenario,
    group: Union[str, int],
    start_year: int,
    end_year: int,
    start_value: float,
    end_value: float,
    parameter: str = "ForcedFRate",
) -> RsimScenario:
    """Create a linear ramp in fishing pressure.

    Convenience function to linearly interpolate fishing between
    two values over a range of years.

    Parameters
    ----------
    scenario : RsimScenario
        RsimScenario object to modify
    group : Union[str, int]
        Group to modify
    start_year : int
        First year of ramp
    end_year : int
        Last year of ramp
    start_value : float
        Value at start_year
    end_value : float
        Value at end_year
    parameter : str
        Fishing parameter to modify

    Returns
    -------
    RsimScenario
        Modified scenario object
    """
    years = list(range(start_year, end_year + 1))
    values = np.linspace(start_value, end_value, len(years))

    return adjust_fishing(
        scenario, parameter=parameter, group=group, sim_year=years, value=values
    )

create_pulse_forcing

create_pulse_forcing(scenario: RsimScenario, group: Union[str, int], pulse_years: List[int], pulse_months: Union[int, List[int]], magnitude: float, parameter: str = 'ForcedRecs') -> RsimScenario

Create pulse forcing events.

Convenience function to add periodic pulse events (e.g., recruitment pulses, mortality events).

Parameters:

Name	Type	Description	Default
scenario	RsimScenario	RsimScenario object to modify	required
group	Union[str, int]	Group to modify	required
pulse_years	List[int]	List of years with pulse events	required
pulse_months	Union[int, List[int]]	Month(s) when pulse occurs	required
magnitude	float	Multiplier for pulse (>1 = increase, <1 = decrease)	required
parameter	str	Forcing parameter to modify	'ForcedRecs'

Returns:

Type	Description
RsimScenario	Modified scenario object

Source code in pypath/core/adjustments.py

def create_pulse_forcing(
    scenario: RsimScenario,
    group: Union[str, int],
    pulse_years: List[int],
    pulse_months: Union[int, List[int]],
    magnitude: float,
    parameter: str = "ForcedRecs",
) -> RsimScenario:
    """Create pulse forcing events.

    Convenience function to add periodic pulse events
    (e.g., recruitment pulses, mortality events).

    Parameters
    ----------
    scenario : RsimScenario
        RsimScenario object to modify
    group : Union[str, int]
        Group to modify
    pulse_years : List[int]
        List of years with pulse events
    pulse_months : Union[int, List[int]]
        Month(s) when pulse occurs
    magnitude : float
        Multiplier for pulse (>1 = increase, <1 = decrease)
    parameter : str
        Forcing parameter to modify

    Returns
    -------
    RsimScenario
        Modified scenario object
    """
    for year in pulse_years:
        scenario = adjust_forcing(
            scenario,
            parameter=parameter,
            group=group,
            sim_year=year,
            sim_month=pulse_months,
            value=magnitude,
        )

    return scenario

create_seasonal_forcing

create_seasonal_forcing(scenario: RsimScenario, group: Union[str, int], years: Union[range, List[int]], monthly_values: List[float], parameter: str = 'ForcedPrey') -> RsimScenario

Create seasonal forcing pattern.

Applies a repeating 12-month pattern of forcing values across multiple years.

Parameters:

Name	Type	Description	Default
scenario	RsimScenario	RsimScenario object to modify	required
group	Union[str, int]	Group to modify	required
years	Union[range, List[int]]	Years to apply pattern	required
monthly_values	List[float]	List of 12 values, one per month	required
parameter	str	Forcing parameter to modify	'ForcedPrey'

Returns:

Type	Description
RsimScenario	Modified scenario object

Examples:

>>> # Higher prey availability in summer
>>> seasonal = [0.8, 0.9, 1.0, 1.1, 1.2, 1.3,
...             1.3, 1.2, 1.1, 1.0, 0.9, 0.8]
>>> scenario = create_seasonal_forcing(
...     scenario, 'Zooplankton', range(1, 51), seasonal
... )

Source code in pypath/core/adjustments.py

def create_seasonal_forcing(
    scenario: RsimScenario,
    group: Union[str, int],
    years: Union[range, List[int]],
    monthly_values: List[float],
    parameter: str = "ForcedPrey",
) -> RsimScenario:
    """Create seasonal forcing pattern.

    Applies a repeating 12-month pattern of forcing values
    across multiple years.

    Parameters
    ----------
    scenario : RsimScenario
        RsimScenario object to modify
    group : Union[str, int]
        Group to modify
    years : Union[range, List[int]]
        Years to apply pattern
    monthly_values : List[float]
        List of 12 values, one per month
    parameter : str
        Forcing parameter to modify

    Returns
    -------
    RsimScenario
        Modified scenario object

    Examples
    --------
        >>> # Higher prey availability in summer
        >>> seasonal = [0.8, 0.9, 1.0, 1.1, 1.2, 1.3,
        ...             1.3, 1.2, 1.1, 1.0, 0.9, 0.8]
        >>> scenario = create_seasonal_forcing(
        ...     scenario, 'Zooplankton', range(1, 51), seasonal
        ... )
    """
    if len(monthly_values) != 12:
        raise ValueError("monthly_values must have exactly 12 elements")

    if isinstance(years, range):
        years = list(years)

    for month in range(1, 13):
        scenario = adjust_forcing(
            scenario,
            parameter=parameter,
            group=group,
            sim_year=years,
            sim_month=month,
            value=monthly_values[month - 1],
        )

    return scenario

set_handling_time

set_handling_time(scenario: RsimScenario, predator: Union[str, int], prey: Union[str, int], value: float) -> RsimScenario

Set handling time (d) for a predator-prey link.

Handling time controls predator satiation: - d = 1000: Off (default) - d = 0: Maximum satiation effect

Parameters:

Name	Type	Description	Default
scenario	RsimScenario	RsimScenario object to modify	required
predator	Union[str, int]	Predator group name or index	required
prey	Union[str, int]	Prey group name or index	required
value	float	New handling time value	required

Returns:

Type	Description
RsimScenario	Modified scenario object

Source code in pypath/core/adjustments.py

def set_handling_time(
    scenario: RsimScenario,
    predator: Union[str, int],
    prey: Union[str, int],
    value: float,
) -> RsimScenario:
    """Set handling time (d) for a predator-prey link.

    Handling time controls predator satiation:
    - d = 1000: Off (default)
    - d = 0: Maximum satiation effect

    Parameters
    ----------
    scenario : RsimScenario
        RsimScenario object to modify
    predator : Union[str, int]
        Predator group name or index
    prey : Union[str, int]
        Prey group name or index
    value : float
        New handling time value

    Returns
    -------
    RsimScenario
        Modified scenario object
    """
    pred_idx = _get_group_index(scenario, predator)
    prey_idx = _get_group_index(scenario, prey)

    # Find the link
    params = scenario.params
    for i in range(1, params.NumPredPreyLinks + 1):
        if params.PreyTo[i] == pred_idx and params.PreyFrom[i] == prey_idx:
            params.DD[i] = value
            return scenario

    raise ValueError(f"No predator-prey link found between {predator} and {prey}")

set_vulnerability

set_vulnerability(scenario: RsimScenario, predator: Union[str, int], prey: Union[str, int], value: float) -> RsimScenario

Set vulnerability (v) for a predator-prey link.

Vulnerability controls the functional response shape: - v = 1: Linear (Type I) - v = 2: Holling Type II (default) - v > 2: Approaches Type III

Parameters:

Name	Type	Description	Default
scenario	RsimScenario	RsimScenario object to modify	required
predator	Union[str, int]	Predator group name or index	required
prey	Union[str, int]	Prey group name or index	required
value	float	New vulnerability value	required

Returns:

Type	Description
RsimScenario	Modified scenario object

Source code in pypath/core/adjustments.py

def set_vulnerability(
    scenario: RsimScenario,
    predator: Union[str, int],
    prey: Union[str, int],
    value: float,
) -> RsimScenario:
    """Set vulnerability (v) for a predator-prey link.

    Vulnerability controls the functional response shape:
    - v = 1: Linear (Type I)
    - v = 2: Holling Type II (default)
    - v > 2: Approaches Type III

    Parameters
    ----------
    scenario : RsimScenario
        RsimScenario object to modify
    predator : Union[str, int]
        Predator group name or index
    prey : Union[str, int]
        Prey group name or index
    value : float
        New vulnerability value

    Returns
    -------
    RsimScenario
        Modified scenario object
    """
    pred_idx = _get_group_index(scenario, predator)
    prey_idx = _get_group_index(scenario, prey)

    # Find the link
    params = scenario.params
    for i in range(1, params.NumPredPreyLinks + 1):
        if params.PreyTo[i] == pred_idx and params.PreyFrom[i] == prey_idx:
            params.VV[i] = value
            return scenario

    raise ValueError(f"No predator-prey link found between {predator} and {prey}")

Forcing

pypath.core.forcing

Advanced forcing mechanisms for Ecosim simulations.

This module provides: 1. State-variable forcing (biomass, catch, etc.) 2. Dynamic diet rewiring based on prey availability 3. Flexible forcing modes (replace, add, multiply) 4. Temporal interpolation for sub-annual time steps

DietRewiring dataclass

Dynamic diet matrix rewiring based on prey availability.

Allows predator diet preferences to change over time in response to changing prey abundance (prey switching, adaptive foraging).

Attributes:

Name	Type	Description
enabled	bool	Whether diet rewiring is active
switching_power	float	Prey switching exponent (higher = more switching)
min_proportion	float	Minimum diet proportion to maintain (prevents division by zero)
update_interval	int	How often to update diet (in months)
base_diet	ndarray	Original diet matrix (n_prey x n_pred)
current_diet	ndarray	Current diet matrix (updated each interval)

Source code in pypath/core/forcing.py

@dataclass
class DietRewiring:
    """Dynamic diet matrix rewiring based on prey availability.

    Allows predator diet preferences to change over time in response to
    changing prey abundance (prey switching, adaptive foraging).

    Attributes
    ----------
    enabled : bool
        Whether diet rewiring is active
    switching_power : float
        Prey switching exponent (higher = more switching)
    min_proportion : float
        Minimum diet proportion to maintain (prevents division by zero)
    update_interval : int
        How often to update diet (in months)
    base_diet : np.ndarray
        Original diet matrix (n_prey x n_pred)
    current_diet : np.ndarray
        Current diet matrix (updated each interval)
    """

    enabled: bool = False
    switching_power: float = 2.0
    min_proportion: float = 0.001
    update_interval: int = 12  # Monthly
    base_diet: Optional[np.ndarray] = None
    current_diet: Optional[np.ndarray] = None

    def initialize(self, diet_matrix: np.ndarray):
        """Initialize with base diet matrix.

        Parameters
        ----------
        diet_matrix : np.ndarray
            Base diet proportions (n_prey x n_pred)
        """
        self.base_diet = diet_matrix.copy()
        self.current_diet = diet_matrix.copy()

    def update_diet(
        self, prey_biomass: np.ndarray, predator_idx: Optional[int] = None
    ) -> "np.ndarray | None":
        """Update diet preferences based on prey availability.

        Uses a prey switching model where diet preferences shift toward
        more abundant prey species.

        Parameters
        ----------
        prey_biomass : np.ndarray
            Current biomass of all prey groups
        predator_idx : int, optional
            Update only this predator (None = update all)

        Returns
        -------
        np.ndarray
            Updated diet matrix

        Notes
        -----
        The prey switching model:

        new_diet[prey, pred] = base_diet[prey, pred] * (biomass[prey] / B_ref[prey])^power

        Then normalize so sum of diet = 1 for each predator.

        Higher switching_power = stronger response to biomass changes.
        """
        if not self.enabled:
            return None

        if self.base_diet is None:
            return self.current_diet

        n_prey, n_pred = self.base_diet.shape
        new_diet = self.current_diet.copy()

        # Calculate relative prey availability
        # Only use first n_prey entries (matching diet matrix)
        prey_biomass_subset = prey_biomass[:n_prey]
        prey_availability = np.maximum(prey_biomass_subset, self.min_proportion)

        # Update diet for specified predator(s)
        pred_range = range(n_pred) if predator_idx is None else [predator_idx]

        for pred in pred_range:
            # Get base diet for this predator
            base_prefs = self.base_diet[:, pred]

            # Only update where there's a base preference
            active_prey = base_prefs > self.min_proportion

            if not np.any(active_prey):
                continue

            # Apply prey switching model
            # new_pref = base_pref * (availability)^power
            new_prefs = base_prefs.copy()
            new_prefs[active_prey] = base_prefs[active_prey] * np.power(
                prey_availability[active_prey]
                / np.mean(prey_availability[active_prey]),
                self.switching_power,
            )

            # Ensure minimum proportions
            new_prefs = np.maximum(new_prefs, self.min_proportion)

            # Normalize to sum to 1
            total = np.sum(new_prefs)
            if total > 0:
                new_diet[:, pred] = new_prefs / total

        self.current_diet = new_diet
        return new_diet

    def reset(self):
        """Reset diet to base values."""
        if self.base_diet is not None:
            self.current_diet = self.base_diet.copy()

initialize

initialize(diet_matrix: ndarray)

Initialize with base diet matrix.

Parameters:

Name	Type	Description	Default
diet_matrix	ndarray	Base diet proportions (n_prey x n_pred)	required

Source code in pypath/core/forcing.py

def initialize(self, diet_matrix: np.ndarray):
    """Initialize with base diet matrix.

    Parameters
    ----------
    diet_matrix : np.ndarray
        Base diet proportions (n_prey x n_pred)
    """
    self.base_diet = diet_matrix.copy()
    self.current_diet = diet_matrix.copy()

reset

reset()

Reset diet to base values.

Source code in pypath/core/forcing.py

def reset(self):
    """Reset diet to base values."""
    if self.base_diet is not None:
        self.current_diet = self.base_diet.copy()

update_diet

update_diet(prey_biomass: ndarray, predator_idx: Optional[int] = None) -> 'np.ndarray | None'

Update diet preferences based on prey availability.

Uses a prey switching model where diet preferences shift toward more abundant prey species.

Parameters:

Name	Type	Description	Default
prey_biomass	ndarray	Current biomass of all prey groups	required
predator_idx	int	Update only this predator (None = update all)	None

Returns:

Type	Description
ndarray	Updated diet matrix

Notes

The prey switching model:

new_diet[prey, pred] = base_diet[prey, pred] * (biomass[prey] / B_ref[prey])^power

Then normalize so sum of diet = 1 for each predator.

Higher switching_power = stronger response to biomass changes.

Source code in pypath/core/forcing.py

def update_diet(
    self, prey_biomass: np.ndarray, predator_idx: Optional[int] = None
) -> "np.ndarray | None":
    """Update diet preferences based on prey availability.

    Uses a prey switching model where diet preferences shift toward
    more abundant prey species.

    Parameters
    ----------
    prey_biomass : np.ndarray
        Current biomass of all prey groups
    predator_idx : int, optional
        Update only this predator (None = update all)

    Returns
    -------
    np.ndarray
        Updated diet matrix

    Notes
    -----
    The prey switching model:

    new_diet[prey, pred] = base_diet[prey, pred] * (biomass[prey] / B_ref[prey])^power

    Then normalize so sum of diet = 1 for each predator.

    Higher switching_power = stronger response to biomass changes.
    """
    if not self.enabled:
        return None

    if self.base_diet is None:
        return self.current_diet

    n_prey, n_pred = self.base_diet.shape
    new_diet = self.current_diet.copy()

    # Calculate relative prey availability
    # Only use first n_prey entries (matching diet matrix)
    prey_biomass_subset = prey_biomass[:n_prey]
    prey_availability = np.maximum(prey_biomass_subset, self.min_proportion)

    # Update diet for specified predator(s)
    pred_range = range(n_pred) if predator_idx is None else [predator_idx]

    for pred in pred_range:
        # Get base diet for this predator
        base_prefs = self.base_diet[:, pred]

        # Only update where there's a base preference
        active_prey = base_prefs > self.min_proportion

        if not np.any(active_prey):
            continue

        # Apply prey switching model
        # new_pref = base_pref * (availability)^power
        new_prefs = base_prefs.copy()
        new_prefs[active_prey] = base_prefs[active_prey] * np.power(
            prey_availability[active_prey]
            / np.mean(prey_availability[active_prey]),
            self.switching_power,
        )

        # Ensure minimum proportions
        new_prefs = np.maximum(new_prefs, self.min_proportion)

        # Normalize to sum to 1
        total = np.sum(new_prefs)
        if total > 0:
            new_diet[:, pred] = new_prefs / total

    self.current_diet = new_diet
    return new_diet

ForcingFunction dataclass

Single forcing function for a state variable.

Attributes:

Name	Type	Description
group_idx	int	Index of group to force (-1 for all groups)
variable	StateVariable	Which state variable to force
mode	ForcingMode	How to apply the forcing
time_series	ndarray	Time series of forced values (years)
years	ndarray	Year indices corresponding to time_series
interpolate	bool	Whether to interpolate between annual values
active	bool	Whether this forcing is currently active

Source code in pypath/core/forcing.py

@dataclass
class ForcingFunction:
    """Single forcing function for a state variable.

    Attributes
    ----------
    group_idx : int
        Index of group to force (-1 for all groups)
    variable : StateVariable
        Which state variable to force
    mode : ForcingMode
        How to apply the forcing
    time_series : np.ndarray
        Time series of forced values (years)
    years : np.ndarray
        Year indices corresponding to time_series
    interpolate : bool
        Whether to interpolate between annual values
    active : bool
        Whether this forcing is currently active
    """

    group_idx: int
    variable: StateVariable
    mode: ForcingMode
    time_series: np.ndarray
    years: np.ndarray
    interpolate: bool = True
    active: bool = True

    def get_value(self, year: float) -> float:
        """Get forced value at given year (with interpolation).

        Parameters
        ----------
        year : float
            Simulation year (can be fractional for monthly time steps)

        Returns
        -------
        float
            Forced value at this time
        """
        if not self.active:
            return np.nan

        # Check if year is in range
        if year < self.years[0] or year > self.years[-1]:
            # Outside range - return NaN (no forcing)
            return np.nan

        if self.interpolate:
            # Linear interpolation
            return np.interp(year, self.years, self.time_series)
        else:
            # Use nearest year
            idx = np.argmin(np.abs(self.years - year))
            return self.time_series[idx]

get_value

get_value(year: float) -> float

Get forced value at given year (with interpolation).

Parameters:

Name	Type	Description	Default
year	float	Simulation year (can be fractional for monthly time steps)	required

Returns:

Type	Description
float	Forced value at this time

Source code in pypath/core/forcing.py

def get_value(self, year: float) -> float:
    """Get forced value at given year (with interpolation).

    Parameters
    ----------
    year : float
        Simulation year (can be fractional for monthly time steps)

    Returns
    -------
    float
        Forced value at this time
    """
    if not self.active:
        return np.nan

    # Check if year is in range
    if year < self.years[0] or year > self.years[-1]:
        # Outside range - return NaN (no forcing)
        return np.nan

    if self.interpolate:
        # Linear interpolation
        return np.interp(year, self.years, self.time_series)
    else:
        # Use nearest year
        idx = np.argmin(np.abs(self.years - year))
        return self.time_series[idx]

ForcingMode

Bases: Enum

Mode for applying forced values.

Source code in pypath/core/forcing.py

class ForcingMode(Enum):
    """Mode for applying forced values."""

    REPLACE = "replace"  # Replace state variable with forced value
    ADD = "add"  # Add forced value to computed value
    MULTIPLY = "multiply"  # Multiply computed value by forced value
    RESCALE = "rescale"  # Rescale to match forced value

StateForcing dataclass

Collection of forcing functions for state variables.

Attributes:

Name	Type	Description
functions	list[ForcingFunction]	List of individual forcing functions

Source code in pypath/core/forcing.py

@dataclass
class StateForcing:
    """Collection of forcing functions for state variables.

    Attributes
    ----------
    functions : list[ForcingFunction]
        List of individual forcing functions
    """

    functions: List[ForcingFunction] = field(default_factory=list)

    def add_forcing(
        self,
        group_idx: int,
        variable: Union[str, StateVariable],
        time_series: Union[np.ndarray, pd.Series, Dict[int, float]],
        years: Optional[np.ndarray] = None,
        mode: Union[str, ForcingMode] = ForcingMode.REPLACE,
        interpolate: bool = True,
    ):
        """Add a forcing function.

        Parameters
        ----------
        group_idx : int
            Index of group to force
        variable : str or StateVariable
            Which state variable to force
        time_series : array-like or dict
            Time series of forced values
            If dict, keys are years and values are forced values
        years : array-like, optional
            Year indices (required if time_series is array)
        mode : str or ForcingMode
            How to apply forcing ("replace", "add", "multiply", "rescale")
        interpolate : bool
            Whether to interpolate between annual values

        Examples
        --------
        >>> forcing = StateForcing()
        >>> # Force phytoplankton biomass to observed series
        >>> forcing.add_forcing(
        ...     group_idx=0,
        ...     variable='biomass',
        ...     time_series={2000: 15.0, 2001: 18.0, 2002: 16.0},
        ...     mode='replace'
        ... )
        >>>
        >>> # Add recruitment pulse for herring in 2005
        >>> forcing.add_forcing(
        ...     group_idx=3,
        ...     variable='recruitment',
        ...     time_series={2005: 2.5},  # 2.5x normal recruitment
        ...     mode='multiply'
        ... )
        """
        # Convert variable to enum
        if isinstance(variable, str):
            variable = StateVariable(variable.lower())

        # Convert mode to enum
        if isinstance(mode, str):
            mode = ForcingMode(mode.lower())

        # Handle dict input
        if isinstance(time_series, dict):
            years = np.array(list(time_series.keys()))
            time_series = np.array(list(time_series.values()))
        elif isinstance(time_series, pd.Series):
            years = time_series.index.values
            time_series = time_series.values
        else:
            time_series = np.asarray(time_series)

        if years is None:
            raise ValueError("years must be provided if time_series is not a dict")

        years = np.asarray(years)

        # Create forcing function
        func = ForcingFunction(
            group_idx=group_idx,
            variable=variable,
            mode=mode,
            time_series=time_series,
            years=years,
            interpolate=interpolate,
            active=True,
        )

        self.functions.append(func)

    def get_forcing(
        self, year: float, variable: StateVariable, group_idx: Optional[int] = None
    ) -> List[Tuple[ForcingFunction, float]]:
        """Get all active forcing values for a variable at given time.

        Parameters
        ----------
        year : float
            Current simulation year
        variable : StateVariable
            Which state variable to query
        group_idx : int, optional
            Specific group index (None = all groups)

        Returns
        -------
        list of (ForcingFunction, float)
            List of (forcing function, forced value) tuples
        """
        results = []

        for func in self.functions:
            if not func.active or func.variable != variable:
                continue

            # Check if this forcing applies to the group
            if group_idx is not None:
                if func.group_idx != -1 and func.group_idx != group_idx:
                    continue

            value = func.get_value(year)
            if not np.isnan(value):
                results.append((func, value))

        return results

    def remove_forcing(self, group_idx: int, variable: Union[str, StateVariable]):
        """Remove forcing for a specific group and variable.

        Parameters
        ----------
        group_idx : int
            Index of group
        variable : str or StateVariable
            Which state variable
        """
        if isinstance(variable, str):
            variable = StateVariable(variable.lower())

        self.functions = [
            f
            for f in self.functions
            if not (f.group_idx == group_idx and f.variable == variable)
        ]

add_forcing

add_forcing(group_idx: int, variable: Union[str, StateVariable], time_series: Union[ndarray, Series, Dict[int, float]], years: Optional[ndarray] = None, mode: Union[str, ForcingMode] = ForcingMode.REPLACE, interpolate: bool = True)

Add a forcing function.

Parameters:

Name	Type	Description	Default
group_idx	int	Index of group to force	required
variable	str or StateVariable	Which state variable to force	required
time_series	array - like or dict	Time series of forced values If dict, keys are years and values are forced values	required
years	array - like	Year indices (required if time_series is array)	None
mode	str or ForcingMode	How to apply forcing ("replace", "add", "multiply", "rescale")	REPLACE
interpolate	bool	Whether to interpolate between annual values	True

Examples:

>>> forcing = StateForcing()
>>> # Force phytoplankton biomass to observed series
>>> forcing.add_forcing(
...     group_idx=0,
...     variable='biomass',
...     time_series={2000: 15.0, 2001: 18.0, 2002: 16.0},
...     mode='replace'
... )
>>>
>>> # Add recruitment pulse for herring in 2005
>>> forcing.add_forcing(
...     group_idx=3,
...     variable='recruitment',
...     time_series={2005: 2.5},  # 2.5x normal recruitment
...     mode='multiply'
... )

Source code in pypath/core/forcing.py

def add_forcing(
    self,
    group_idx: int,
    variable: Union[str, StateVariable],
    time_series: Union[np.ndarray, pd.Series, Dict[int, float]],
    years: Optional[np.ndarray] = None,
    mode: Union[str, ForcingMode] = ForcingMode.REPLACE,
    interpolate: bool = True,
):
    """Add a forcing function.

    Parameters
    ----------
    group_idx : int
        Index of group to force
    variable : str or StateVariable
        Which state variable to force
    time_series : array-like or dict
        Time series of forced values
        If dict, keys are years and values are forced values
    years : array-like, optional
        Year indices (required if time_series is array)
    mode : str or ForcingMode
        How to apply forcing ("replace", "add", "multiply", "rescale")
    interpolate : bool
        Whether to interpolate between annual values

    Examples
    --------
    >>> forcing = StateForcing()
    >>> # Force phytoplankton biomass to observed series
    >>> forcing.add_forcing(
    ...     group_idx=0,
    ...     variable='biomass',
    ...     time_series={2000: 15.0, 2001: 18.0, 2002: 16.0},
    ...     mode='replace'
    ... )
    >>>
    >>> # Add recruitment pulse for herring in 2005
    >>> forcing.add_forcing(
    ...     group_idx=3,
    ...     variable='recruitment',
    ...     time_series={2005: 2.5},  # 2.5x normal recruitment
    ...     mode='multiply'
    ... )
    """
    # Convert variable to enum
    if isinstance(variable, str):
        variable = StateVariable(variable.lower())

    # Convert mode to enum
    if isinstance(mode, str):
        mode = ForcingMode(mode.lower())

    # Handle dict input
    if isinstance(time_series, dict):
        years = np.array(list(time_series.keys()))
        time_series = np.array(list(time_series.values()))
    elif isinstance(time_series, pd.Series):
        years = time_series.index.values
        time_series = time_series.values
    else:
        time_series = np.asarray(time_series)

    if years is None:
        raise ValueError("years must be provided if time_series is not a dict")

    years = np.asarray(years)

    # Create forcing function
    func = ForcingFunction(
        group_idx=group_idx,
        variable=variable,
        mode=mode,
        time_series=time_series,
        years=years,
        interpolate=interpolate,
        active=True,
    )

    self.functions.append(func)

get_forcing

get_forcing(year: float, variable: StateVariable, group_idx: Optional[int] = None) -> List[Tuple[ForcingFunction, float]]

Get all active forcing values for a variable at given time.

Parameters:

Name	Type	Description	Default
year	float	Current simulation year	required
variable	StateVariable	Which state variable to query	required
group_idx	int	Specific group index (None = all groups)	None

Returns:

Type	Description
list of (ForcingFunction, float)	List of (forcing function, forced value) tuples

Source code in pypath/core/forcing.py

def get_forcing(
    self, year: float, variable: StateVariable, group_idx: Optional[int] = None
) -> List[Tuple[ForcingFunction, float]]:
    """Get all active forcing values for a variable at given time.

    Parameters
    ----------
    year : float
        Current simulation year
    variable : StateVariable
        Which state variable to query
    group_idx : int, optional
        Specific group index (None = all groups)

    Returns
    -------
    list of (ForcingFunction, float)
        List of (forcing function, forced value) tuples
    """
    results = []

    for func in self.functions:
        if not func.active or func.variable != variable:
            continue

        # Check if this forcing applies to the group
        if group_idx is not None:
            if func.group_idx != -1 and func.group_idx != group_idx:
                continue

        value = func.get_value(year)
        if not np.isnan(value):
            results.append((func, value))

    return results

remove_forcing

remove_forcing(group_idx: int, variable: Union[str, StateVariable])

Remove forcing for a specific group and variable.

Parameters:

Name	Type	Description	Default
group_idx	int	Index of group	required
variable	str or StateVariable	Which state variable	required

Source code in pypath/core/forcing.py

def remove_forcing(self, group_idx: int, variable: Union[str, StateVariable]):
    """Remove forcing for a specific group and variable.

    Parameters
    ----------
    group_idx : int
        Index of group
    variable : str or StateVariable
        Which state variable
    """
    if isinstance(variable, str):
        variable = StateVariable(variable.lower())

    self.functions = [
        f
        for f in self.functions
        if not (f.group_idx == group_idx and f.variable == variable)
    ]

StateVariable

Bases: Enum

State variables that can be forced.

Source code in pypath/core/forcing.py

class StateVariable(Enum):
    """State variables that can be forced."""

    BIOMASS = "biomass"
    CATCH = "catch"
    FISHING_MORTALITY = "fishing_mortality"
    RECRUITMENT = "recruitment"
    MORTALITY = "mortality"
    MIGRATION = "migration"
    PRIMARY_PRODUCTION = "primary_production"

create_biomass_forcing

create_biomass_forcing(group_idx: int, observed_biomass: Union[ndarray, Series, Dict[int, float]], years: Optional[ndarray] = None, mode: str = 'replace', interpolate: bool = True) -> StateForcing

Convenience function to create biomass forcing.

Parameters:

Name	Type	Description	Default
group_idx	int	Index of group to force	required
observed_biomass	array - like or dict	Observed biomass time series	required
years	array - like	Year indices	None
mode	str	Forcing mode ("replace", "add", "multiply")	'replace'
interpolate	bool	Whether to interpolate monthly values	True

Returns:

Type	Description
StateForcing	Forcing object ready to use

Examples:

>>> # Force phytoplankton to observed biomass
>>> forcing = create_biomass_forcing(
...     group_idx=0,
...     observed_biomass={2000: 15.0, 2005: 18.0, 2010: 16.0},
...     mode='replace'
... )

Source code in pypath/core/forcing.py

def create_biomass_forcing(
    group_idx: int,
    observed_biomass: Union[np.ndarray, pd.Series, Dict[int, float]],
    years: Optional[np.ndarray] = None,
    mode: str = "replace",
    interpolate: bool = True,
) -> StateForcing:
    """Convenience function to create biomass forcing.

    Parameters
    ----------
    group_idx : int
        Index of group to force
    observed_biomass : array-like or dict
        Observed biomass time series
    years : array-like, optional
        Year indices
    mode : str
        Forcing mode ("replace", "add", "multiply")
    interpolate : bool
        Whether to interpolate monthly values

    Returns
    -------
    StateForcing
        Forcing object ready to use

    Examples
    --------
    >>> # Force phytoplankton to observed biomass
    >>> forcing = create_biomass_forcing(
    ...     group_idx=0,
    ...     observed_biomass={2000: 15.0, 2005: 18.0, 2010: 16.0},
    ...     mode='replace'
    ... )
    """
    forcing = StateForcing()
    forcing.add_forcing(
        group_idx=group_idx,
        variable=StateVariable.BIOMASS,
        time_series=observed_biomass,
        years=years,
        mode=mode,
        interpolate=interpolate,
    )
    return forcing

create_diet_rewiring

create_diet_rewiring(switching_power: float = 2.0, min_proportion: float = 0.001, update_interval: int = 12) -> DietRewiring

Convenience function to create diet rewiring configuration.

Parameters:

Name	Type	Description	Default
switching_power	float	Prey switching exponent (1.0 = proportional, >1 = switching)	2.0
min_proportion	float	Minimum diet proportion to maintain	0.001
update_interval	int	How often to update diet (months)	12

Returns:

Type	Description
DietRewiring	Diet rewiring object ready to use

Examples:

>>> # Enable strong prey switching
>>> rewiring = create_diet_rewiring(switching_power=3.0)

Source code in pypath/core/forcing.py

def create_diet_rewiring(
    switching_power: float = 2.0,
    min_proportion: float = 0.001,
    update_interval: int = 12,
) -> DietRewiring:
    """Convenience function to create diet rewiring configuration.

    Parameters
    ----------
    switching_power : float
        Prey switching exponent (1.0 = proportional, >1 = switching)
    min_proportion : float
        Minimum diet proportion to maintain
    update_interval : int
        How often to update diet (months)

    Returns
    -------
    DietRewiring
        Diet rewiring object ready to use

    Examples
    --------
    >>> # Enable strong prey switching
    >>> rewiring = create_diet_rewiring(switching_power=3.0)
    """
    return DietRewiring(
        enabled=True,
        switching_power=switching_power,
        min_proportion=min_proportion,
        update_interval=update_interval,
    )

create_recruitment_forcing

create_recruitment_forcing(group_idx: int, recruitment_multiplier: Union[ndarray, Dict[int, float]], years: Optional[ndarray] = None, interpolate: bool = False) -> StateForcing

Convenience function to create recruitment forcing.

Parameters:

Name	Type	Description	Default
group_idx	int	Index of group to force	required
recruitment_multiplier	array - like or dict	Recruitment multiplier (1.0 = normal, 2.0 = double, etc.)	required
years	array - like	Year indices	None
interpolate	bool	Whether to interpolate (usually False for recruitment pulses)	False

Returns:

Type	Description
StateForcing	Forcing object ready to use

Examples:

>>> # Strong recruitment in 2005, weak in 2010
>>> forcing = create_recruitment_forcing(
...     group_idx=3,
...     recruitment_multiplier={2005: 3.0, 2010: 0.5}
... )

Source code in pypath/core/forcing.py

def create_recruitment_forcing(
    group_idx: int,
    recruitment_multiplier: Union[np.ndarray, Dict[int, float]],
    years: Optional[np.ndarray] = None,
    interpolate: bool = False,
) -> StateForcing:
    """Convenience function to create recruitment forcing.

    Parameters
    ----------
    group_idx : int
        Index of group to force
    recruitment_multiplier : array-like or dict
        Recruitment multiplier (1.0 = normal, 2.0 = double, etc.)
    years : array-like, optional
        Year indices
    interpolate : bool
        Whether to interpolate (usually False for recruitment pulses)

    Returns
    -------
    StateForcing
        Forcing object ready to use

    Examples
    --------
    >>> # Strong recruitment in 2005, weak in 2010
    >>> forcing = create_recruitment_forcing(
    ...     group_idx=3,
    ...     recruitment_multiplier={2005: 3.0, 2010: 0.5}
    ... )
    """
    forcing = StateForcing()
    forcing.add_forcing(
        group_idx=group_idx,
        variable=StateVariable.RECRUITMENT,
        time_series=recruitment_multiplier,
        years=years,
        mode=ForcingMode.MULTIPLY,
        interpolate=interpolate,
    )
    return forcing

Optimization

pypath.core.optimization

Bayesian optimization for Ecosim parameter calibration.

This module provides tools to optimize Ecosim parameters to match observed time series data using Bayesian optimization with Gaussian Processes.

EcosimOptimizer

Bayesian optimizer for Ecosim parameters.

Calibrates Ecosim parameters to match observed biomass time series using Bayesian optimization with Gaussian Processes.

Parameters:

Name	Type	Description	Default
model	Rpath	Balanced Ecopath model	required
params	RpathParams	Model parameters	required
observed_data	dict	Dictionary mapping group indices to observed biomass time series Example: {1: np.array([1.0, 1.2, 1.1, ...]), 2: np.array([0.5, 0.6, ...])}	required
years	range	Years to simulate	required
objective	str or callable	Objective function to minimize. Options: - 'mse': Mean squared error - 'mape': Mean absolute percentage error - 'nrmse': Normalized root mean squared error - 'loglik': Negative log-likelihood - callable: Custom function(y_true, y_pred) -> float	'mse'
verbose	bool	Print optimization progress	True

Attributes:

Name	Type	Description
model	Rpath	Ecopath model
params	RpathParams	Model parameters
observed_data	dict	Observed time series
years	range	Simulation years
objective_func	callable	Objective function
verbose	bool	Verbosity flag
n_calls	int	Number of function evaluations performed

Source code in pypath/core/optimization.py

class EcosimOptimizer:
    """Bayesian optimizer for Ecosim parameters.

    Calibrates Ecosim parameters to match observed biomass time series using
    Bayesian optimization with Gaussian Processes.

    Parameters
    ----------
    model : Rpath
        Balanced Ecopath model
    params : RpathParams
        Model parameters
    observed_data : dict
        Dictionary mapping group indices to observed biomass time series
        Example: {1: np.array([1.0, 1.2, 1.1, ...]), 2: np.array([0.5, 0.6, ...])}
    years : range
        Years to simulate
    objective : str or callable
        Objective function to minimize. Options:
        - 'mse': Mean squared error
        - 'mape': Mean absolute percentage error
        - 'nrmse': Normalized root mean squared error
        - 'loglik': Negative log-likelihood
        - callable: Custom function(y_true, y_pred) -> float
    verbose : bool
        Print optimization progress

    Attributes
    ----------
    model : Rpath
        Ecopath model
    params : RpathParams
        Model parameters
    observed_data : dict
        Observed time series
    years : range
        Simulation years
    objective_func : callable
        Objective function
    verbose : bool
        Verbosity flag
    n_calls : int
        Number of function evaluations performed
    """

    def __init__(
        self,
        model: Rpath,
        params: RpathParams,
        observed_data: Dict[int, np.ndarray],
        years: range,
        objective: str = "mse",
        verbose: bool = True,
    ):
        if not HAS_SKOPT:
            raise ImportError(
                "scikit-optimize is required for Bayesian optimization. "
                "Install with: pip install scikit-optimize"
            )

        self.model = model
        self.params = params
        self.observed_data = observed_data
        self.years = years
        self.verbose = verbose
        self.n_calls = 0

        # Set objective function
        if isinstance(objective, str):
            objective_funcs = {
                "mse": mean_squared_error,
                "mape": mean_absolute_percentage_error,
                "nrmse": normalized_root_mean_squared_error,
                "loglik": log_likelihood,
            }
            if objective not in objective_funcs:
                raise ValueError(
                    f"Unknown objective: {objective}. Choose from {list(objective_funcs.keys())}"
                )
            self.objective_func = objective_funcs[objective]
        else:
            self.objective_func = objective

        # Validate observed data
        self._validate_observed_data()

    def _validate_observed_data(self) -> None:
        """Validate observed data format and dimensions."""
        n_years = len(self.years)
        for group_idx, data in self.observed_data.items():
            if len(data) != n_years:
                raise ValueError(
                    f"Observed data for group {group_idx} has {len(data)} points "
                    f"but simulation has {n_years} years"
                )
            if group_idx < 1 or group_idx > self.model.NUM_LIVING:
                raise ValueError(
                    f"Group index {group_idx} out of range [1, {self.model.NUM_LIVING}]"
                )

    def _run_simulation(self, param_dict: Dict[str, float]) -> np.ndarray:
        """Run Ecosim simulation with given parameters.

        Parameters
        ----------
        param_dict : dict
            Dictionary of parameter values

        Returns
        -------
        np.ndarray
            Simulated biomass for observed groups
        """
        # Create scenario with parameters
        scenario = rsim_scenario(self.model, self.params, years=self.years)

        # Update parameters
        for param_name, value in param_dict.items():
            self._update_scenario_parameter(scenario, param_name, value)

        # Run simulation
        try:
            result = rsim_run(scenario, method="RK4")

            # Extract biomass for observed groups
            simulated = {}
            for group_idx in self.observed_data.keys():
                # Annual biomass: shape (n_years, n_groups+1)
                # Group indices start at 1 (0 is "Outside")
                simulated[group_idx] = result.annual_Biomass[:, group_idx]

            return simulated
        except Exception as e:
            if self.verbose:
                logger.error(f"Simulation failed with parameters {param_dict}: {e}")
            # Return high penalty for failed simulations
            return None

    def _update_scenario_parameter(
        self, scenario: RsimScenario, param_name: str, value: float
    ) -> None:
        """Update a parameter in the scenario.

        Parameters
        ----------
        scenario : RsimScenario
            Simulation scenario
        param_name : str
            Parameter name (e.g., 'VV_1', 'QQ_5', 'vulnerability')
        value : float
            Parameter value
        """
        if param_name == "vulnerability":
            # Update base vulnerability for all groups
            scenario.params.VV[:] = value
        elif param_name.startswith("VV_"):
            # Update specific group vulnerability
            group_idx = int(param_name.split("_")[1])
            scenario.params.VV[group_idx] = value
        elif param_name.startswith("QQ_"):
            # Update specific link QQ
            link_idx = int(param_name.split("_")[1])
            scenario.params.QQ[link_idx] = value
        elif param_name.startswith("DD_"):
            # Update specific link DD
            link_idx = int(param_name.split("_")[1])
            scenario.params.DD[link_idx] = value
        elif param_name.startswith("PB_"):
            # Update specific group PB
            group_idx = int(param_name.split("_")[1])
            scenario.params.PBopt[group_idx] = value
        elif param_name.startswith("QB_"):
            # Update specific group QB
            group_idx = int(param_name.split("_")[1])
            scenario.params.QBopt[group_idx] = value
        else:
            raise ValueError(f"Unknown parameter: {param_name}")

    def _calculate_objective(self, simulated: Dict[int, np.ndarray]) -> float:
        """Calculate objective function value.

        Parameters
        ----------
        simulated : dict
            Simulated biomass for each group

        Returns
        -------
        float
            Objective function value (lower is better)
        """
        if simulated is None:
            return 1e10  # High penalty for failed simulations

        total_error = 0.0
        n_groups = len(self.observed_data)

        for group_idx, observed in self.observed_data.items():
            predicted = simulated[group_idx]
            error = self.objective_func(observed, predicted)
            total_error += error

        # Average across groups
        return total_error / n_groups

    def optimize(
        self,
        param_bounds: Dict[str, Tuple[float, float]],
        n_calls: int = 50,
        n_initial_points: int = 10,
        random_state: int = 42,
    ) -> OptimizationResult:
        """Run Bayesian optimization.

        Parameters
        ----------
        param_bounds : dict
            Dictionary mapping parameter names to (min, max) bounds
            Example: {'vulnerability': (1.0, 5.0), 'VV_3': (1.0, 10.0)}
        n_calls : int
            Number of function evaluations
        n_initial_points : int
            Number of random initial points before Bayesian optimization
        random_state : int
            Random seed for reproducibility

        Returns
        -------
        OptimizationResult
            Optimization results including best parameters and convergence
        """
        import time

        start_time = time.time()

        # Define search space
        dimensions = []
        param_names = []
        for name, (low, high) in param_bounds.items():
            dimensions.append(Real(low, high, name=name))
            param_names.append(name)

        # Store all evaluations
        all_params_list = []
        all_scores = []

        # Define objective function for skopt
        @use_named_args(dimensions)
        def objective(**params):
            self.n_calls += 1

            if self.verbose:
                logger.info(f"=== Iteration {self.n_calls}/{n_calls} ===")
                logger.info(
                    "Parameters: %s", {k: f"{v:.4f}" for k, v in params.items()}
                )

            # Run simulation
            simulated = self._run_simulation(params)

            # Calculate objective
            score = self._calculate_objective(simulated)

            if self.verbose:
                logger.info(f"Objective: {score:.6f}")

            # Store results
            all_params_list.append(params.copy())
            all_scores.append(score)

            return score

        # Run optimization
        if self.verbose:
            logger.info(f"Starting Bayesian optimization with {n_calls} evaluations...")
            logger.info(f"Optimizing parameters: {list(param_bounds.keys())}")
            logger.info(f"Observed groups: {list(self.observed_data.keys())}")
            logger.info(f"Simulation years: {len(self.years)}")

        self.n_calls = 0
        result = gp_minimize(
            objective,
            dimensions,
            n_calls=n_calls,
            n_initial_points=n_initial_points,
            random_state=random_state,
            verbose=False,
        )

        optimization_time = time.time() - start_time

        # Extract results
        best_params = {name: value for name, value in zip(param_names, result.x)}
        best_score = result.fun
        convergence = [np.min(all_scores[: i + 1]) for i in range(len(all_scores))]

        if self.verbose:
            logger.info(f"{'=' * 60}")
            logger.info("OPTIMIZATION COMPLETE")
            logger.info(f"{'=' * 60}")
            logger.info(f"Best score: {best_score:.6f}")
            logger.info("Best parameters:")
            for name, value in best_params.items():
                logger.info(f"  {name}: {value:.4f}")
            logger.info(f"Total evaluations: {self.n_calls}")
            logger.info(f"Optimization time: {optimization_time:.2f} seconds")
            logger.info(f"{'=' * 60}")

        return OptimizationResult(
            best_params=best_params,
            best_score=best_score,
            n_iterations=self.n_calls,
            convergence=convergence,
            all_params=all_params_list,
            all_scores=all_scores,
            optimization_time=optimization_time,
        )

    def validate(
        self,
        params: Dict[str, float],
        test_data: Optional[Dict[int, np.ndarray]] = None,
    ) -> Dict[str, Any]:
        """Validate optimized parameters on test data.

        Parameters
        ----------
        params : dict
            Parameter values to validate
        test_data : dict, optional
            Test data. If None, uses training data (self.observed_data)

        Returns
        -------
        dict
            Validation metrics for each group and overall
        """
        if test_data is None:
            test_data = self.observed_data

        # Run simulation with optimized parameters
        simulated = self._run_simulation(params)

        if simulated is None:
            return {"error": "Simulation failed"}

        # Calculate metrics for each group
        results = {}
        for group_idx, observed in test_data.items():
            predicted = simulated[group_idx]

            results[f"group_{group_idx}"] = {
                "mse": mean_squared_error(observed, predicted),
                "mape": mean_absolute_percentage_error(observed, predicted),
                "nrmse": normalized_root_mean_squared_error(observed, predicted),
                "correlation": np.corrcoef(observed, predicted)[0, 1],
            }

        # Calculate overall metrics
        all_observed = np.concatenate([test_data[idx] for idx in test_data.keys()])
        all_predicted = np.concatenate([simulated[idx] for idx in test_data.keys()])

        results["overall"] = {
            "mse": mean_squared_error(all_observed, all_predicted),
            "mape": mean_absolute_percentage_error(all_observed, all_predicted),
            "nrmse": normalized_root_mean_squared_error(all_observed, all_predicted),
            "correlation": np.corrcoef(all_observed, all_predicted)[0, 1],
        }

        return results

optimize

optimize(param_bounds: Dict[str, Tuple[float, float]], n_calls: int = 50, n_initial_points: int = 10, random_state: int = 42) -> OptimizationResult

Run Bayesian optimization.

Parameters:

Name	Type	Description	Default
param_bounds	dict	Dictionary mapping parameter names to (min, max) bounds Example: {'vulnerability': (1.0, 5.0), 'VV_3': (1.0, 10.0)}	required
n_calls	int	Number of function evaluations	50
n_initial_points	int	Number of random initial points before Bayesian optimization	10
random_state	int	Random seed for reproducibility	42

Returns:

Type	Description
OptimizationResult	Optimization results including best parameters and convergence

Source code in pypath/core/optimization.py

def optimize(
    self,
    param_bounds: Dict[str, Tuple[float, float]],
    n_calls: int = 50,
    n_initial_points: int = 10,
    random_state: int = 42,
) -> OptimizationResult:
    """Run Bayesian optimization.

    Parameters
    ----------
    param_bounds : dict
        Dictionary mapping parameter names to (min, max) bounds
        Example: {'vulnerability': (1.0, 5.0), 'VV_3': (1.0, 10.0)}
    n_calls : int
        Number of function evaluations
    n_initial_points : int
        Number of random initial points before Bayesian optimization
    random_state : int
        Random seed for reproducibility

    Returns
    -------
    OptimizationResult
        Optimization results including best parameters and convergence
    """
    import time

    start_time = time.time()

    # Define search space
    dimensions = []
    param_names = []
    for name, (low, high) in param_bounds.items():
        dimensions.append(Real(low, high, name=name))
        param_names.append(name)

    # Store all evaluations
    all_params_list = []
    all_scores = []

    # Define objective function for skopt
    @use_named_args(dimensions)
    def objective(**params):
        self.n_calls += 1

        if self.verbose:
            logger.info(f"=== Iteration {self.n_calls}/{n_calls} ===")
            logger.info(
                "Parameters: %s", {k: f"{v:.4f}" for k, v in params.items()}
            )

        # Run simulation
        simulated = self._run_simulation(params)

        # Calculate objective
        score = self._calculate_objective(simulated)

        if self.verbose:
            logger.info(f"Objective: {score:.6f}")

        # Store results
        all_params_list.append(params.copy())
        all_scores.append(score)

        return score

    # Run optimization
    if self.verbose:
        logger.info(f"Starting Bayesian optimization with {n_calls} evaluations...")
        logger.info(f"Optimizing parameters: {list(param_bounds.keys())}")
        logger.info(f"Observed groups: {list(self.observed_data.keys())}")
        logger.info(f"Simulation years: {len(self.years)}")

    self.n_calls = 0
    result = gp_minimize(
        objective,
        dimensions,
        n_calls=n_calls,
        n_initial_points=n_initial_points,
        random_state=random_state,
        verbose=False,
    )

    optimization_time = time.time() - start_time

    # Extract results
    best_params = {name: value for name, value in zip(param_names, result.x)}
    best_score = result.fun
    convergence = [np.min(all_scores[: i + 1]) for i in range(len(all_scores))]

    if self.verbose:
        logger.info(f"{'=' * 60}")
        logger.info("OPTIMIZATION COMPLETE")
        logger.info(f"{'=' * 60}")
        logger.info(f"Best score: {best_score:.6f}")
        logger.info("Best parameters:")
        for name, value in best_params.items():
            logger.info(f"  {name}: {value:.4f}")
        logger.info(f"Total evaluations: {self.n_calls}")
        logger.info(f"Optimization time: {optimization_time:.2f} seconds")
        logger.info(f"{'=' * 60}")

    return OptimizationResult(
        best_params=best_params,
        best_score=best_score,
        n_iterations=self.n_calls,
        convergence=convergence,
        all_params=all_params_list,
        all_scores=all_scores,
        optimization_time=optimization_time,
    )

validate

validate(params: Dict[str, float], test_data: Optional[Dict[int, ndarray]] = None) -> Dict[str, Any]

Validate optimized parameters on test data.

Parameters:

Name	Type	Description	Default
params	dict	Parameter values to validate	required
test_data	dict	Test data. If None, uses training data (self.observed_data)	None

Returns:

Type	Description
dict	Validation metrics for each group and overall

Source code in pypath/core/optimization.py

def validate(
    self,
    params: Dict[str, float],
    test_data: Optional[Dict[int, np.ndarray]] = None,
) -> Dict[str, Any]:
    """Validate optimized parameters on test data.

    Parameters
    ----------
    params : dict
        Parameter values to validate
    test_data : dict, optional
        Test data. If None, uses training data (self.observed_data)

    Returns
    -------
    dict
        Validation metrics for each group and overall
    """
    if test_data is None:
        test_data = self.observed_data

    # Run simulation with optimized parameters
    simulated = self._run_simulation(params)

    if simulated is None:
        return {"error": "Simulation failed"}

    # Calculate metrics for each group
    results = {}
    for group_idx, observed in test_data.items():
        predicted = simulated[group_idx]

        results[f"group_{group_idx}"] = {
            "mse": mean_squared_error(observed, predicted),
            "mape": mean_absolute_percentage_error(observed, predicted),
            "nrmse": normalized_root_mean_squared_error(observed, predicted),
            "correlation": np.corrcoef(observed, predicted)[0, 1],
        }

    # Calculate overall metrics
    all_observed = np.concatenate([test_data[idx] for idx in test_data.keys()])
    all_predicted = np.concatenate([simulated[idx] for idx in test_data.keys()])

    results["overall"] = {
        "mse": mean_squared_error(all_observed, all_predicted),
        "mape": mean_absolute_percentage_error(all_observed, all_predicted),
        "nrmse": normalized_root_mean_squared_error(all_observed, all_predicted),
        "correlation": np.corrcoef(all_observed, all_predicted)[0, 1],
    }

    return results

OptimizationResult dataclass

Results from Bayesian optimization.

Attributes:

Name	Type	Description
best_params	dict	Best parameter values found
best_score	float	Best objective function value (lower is better)
n_iterations	int	Number of optimization iterations
convergence	list	Objective function values over iterations
all_params	list	All parameter combinations tried
all_scores	list	All objective function values
optimization_time	float	Total optimization time in seconds

Source code in pypath/core/optimization.py

@dataclass
class OptimizationResult:
    """Results from Bayesian optimization.

    Attributes
    ----------
    best_params : dict
        Best parameter values found
    best_score : float
        Best objective function value (lower is better)
    n_iterations : int
        Number of optimization iterations
    convergence : list
        Objective function values over iterations
    all_params : list
        All parameter combinations tried
    all_scores : list
        All objective function values
    optimization_time : float
        Total optimization time in seconds
    """

    best_params: Dict[str, float]
    best_score: float
    n_iterations: int
    convergence: List[float]
    all_params: List[Dict[str, float]]
    all_scores: List[float]
    optimization_time: float

log_likelihood

log_likelihood(y_true: ndarray, y_pred: ndarray, sigma: float = 0.1) -> float

Calculate negative log-likelihood (Gaussian).

Parameters:

Name	Type	Description	Default
y_true	ndarray	Observed values	required
y_pred	ndarray	Predicted values	required
sigma	float	Standard deviation of measurement error	0.1

Returns:

Type	Description
float	Negative log-likelihood

Source code in pypath/core/optimization.py

def log_likelihood(y_true: np.ndarray, y_pred: np.ndarray, sigma: float = 0.1) -> float:
    """Calculate negative log-likelihood (Gaussian).

    Parameters
    ----------
    y_true : np.ndarray
        Observed values
    y_pred : np.ndarray
        Predicted values
    sigma : float
        Standard deviation of measurement error

    Returns
    -------
    float
        Negative log-likelihood
    """
    n = len(y_true)
    return 0.5 * n * np.log(2 * np.pi * sigma**2) + np.sum((y_true - y_pred) ** 2) / (
        2 * sigma**2
    )

mean_absolute_percentage_error

mean_absolute_percentage_error(y_true: ndarray, y_pred: ndarray) -> float

Calculate mean absolute percentage error.

Parameters:

Name	Type	Description	Default
y_true	ndarray	Observed values	required
y_pred	ndarray	Predicted values	required

Returns:

Type	Description
float	Mean absolute percentage error

Source code in pypath/core/optimization.py

def mean_absolute_percentage_error(y_true: np.ndarray, y_pred: np.ndarray) -> float:
    """Calculate mean absolute percentage error.

    Parameters
    ----------
    y_true : np.ndarray
        Observed values
    y_pred : np.ndarray
        Predicted values

    Returns
    -------
    float
        Mean absolute percentage error
    """
    # Avoid division by zero
    mask = y_true != 0
    return np.mean(np.abs((y_true[mask] - y_pred[mask]) / y_true[mask])) * 100

mean_squared_error

mean_squared_error(y_true: ndarray, y_pred: ndarray) -> float

Calculate mean squared error between observed and predicted values.

Parameters:

Name	Type	Description	Default
y_true	ndarray	Observed values	required
y_pred	ndarray	Predicted values	required

Returns:

Type	Description
float	Mean squared error

Source code in pypath/core/optimization.py

def mean_squared_error(y_true: np.ndarray, y_pred: np.ndarray) -> float:
    """Calculate mean squared error between observed and predicted values.

    Parameters
    ----------
    y_true : np.ndarray
        Observed values
    y_pred : np.ndarray
        Predicted values

    Returns
    -------
    float
        Mean squared error
    """
    return np.mean((y_true - y_pred) ** 2)

normalized_root_mean_squared_error

normalized_root_mean_squared_error(y_true: ndarray, y_pred: ndarray) -> float

Calculate normalized root mean squared error.

Parameters:

Name	Type	Description	Default
y_true	ndarray	Observed values	required
y_pred	ndarray	Predicted values	required

Returns:

Type	Description
float	Normalized RMSE

Source code in pypath/core/optimization.py

def normalized_root_mean_squared_error(y_true: np.ndarray, y_pred: np.ndarray) -> float:
    """Calculate normalized root mean squared error.

    Parameters
    ----------
    y_true : np.ndarray
        Observed values
    y_pred : np.ndarray
        Predicted values

    Returns
    -------
    float
        Normalized RMSE
    """
    rmse = np.sqrt(np.mean((y_true - y_pred) ** 2))
    y_range = np.max(y_true) - np.min(y_true)
    if y_range <= 0:
        raise ValueError(
            "Cannot compute NRMSE: y_true has zero range (all values identical)"
        )
    return rmse / y_range

plot_fit

plot_fit(optimizer: EcosimOptimizer, params: Dict[str, float], save_path: Optional[str] = None)

Plot observed vs simulated biomass time series.

Parameters:

Name	Type	Description	Default
optimizer	EcosimOptimizer	Optimizer instance with observed data	required
params	dict	Parameter values to simulate	required
save_path	str	Path to save figure	None

Source code in pypath/core/optimization.py

def plot_fit(
    optimizer: EcosimOptimizer,
    params: Dict[str, float],
    save_path: Optional[str] = None,
):
    """Plot observed vs simulated biomass time series.

    Parameters
    ----------
    optimizer : EcosimOptimizer
        Optimizer instance with observed data
    params : dict
        Parameter values to simulate
    save_path : str, optional
        Path to save figure
    """
    import matplotlib.pyplot as plt

    # Run simulation
    simulated = optimizer._run_simulation(params)

    if simulated is None:
        logger.error("Simulation failed!")
        return None

    # Create figure
    n_groups = len(optimizer.observed_data)
    n_cols = min(3, n_groups)
    n_rows = (n_groups + n_cols - 1) // n_cols

    fig, axes = plt.subplots(n_rows, n_cols, figsize=(5 * n_cols, 4 * n_rows))
    if n_groups == 1:
        axes = np.array([axes])
    axes = axes.flatten()

    # Plot each group
    years = list(optimizer.years)
    for i, (group_idx, observed) in enumerate(optimizer.observed_data.items()):
        predicted = simulated[group_idx]
        group_name = optimizer.model.Group[group_idx]

        axes[i].plot(years, observed, "o-", label="Observed", linewidth=2, markersize=6)
        axes[i].plot(
            years, predicted, "s--", label="Simulated", linewidth=2, markersize=5
        )
        axes[i].set_xlabel("Year")
        axes[i].set_ylabel("Biomass")
        axes[i].set_title(f"{group_name} (Group {group_idx})")
        axes[i].legend()
        axes[i].grid(True, alpha=0.3)

        # Add metrics
        mse = mean_squared_error(observed, predicted)
        corr = np.corrcoef(observed, predicted)[0, 1]
        axes[i].text(
            0.05,
            0.95,
            f"MSE: {mse:.4f}\nCorr: {corr:.3f}",
            transform=axes[i].transAxes,
            verticalalignment="top",
            bbox=dict(boxstyle="round", facecolor="wheat", alpha=0.5),
        )

    # Hide unused subplots
    for i in range(n_groups, len(axes)):
        axes[i].axis("off")

    plt.tight_layout()

    if save_path:
        plt.savefig(save_path, dpi=300, bbox_inches="tight")

    return fig

plot_optimization_results

plot_optimization_results(result: OptimizationResult, save_path: Optional[str] = None)

Plot optimization convergence and parameter distributions.

Parameters:

Name	Type	Description	Default
result	OptimizationResult	Optimization results	required
save_path	str	Path to save figure	None

Source code in pypath/core/optimization.py

def plot_optimization_results(
    result: OptimizationResult, save_path: Optional[str] = None
):
    """Plot optimization convergence and parameter distributions.

    Parameters
    ----------
    result : OptimizationResult
        Optimization results
    save_path : str, optional
        Path to save figure
    """
    import matplotlib.pyplot as plt

    fig, axes = plt.subplots(1, 2, figsize=(12, 4))

    # Convergence plot
    axes[0].plot(result.convergence, "b-", linewidth=2)
    axes[0].scatter(
        range(len(result.all_scores)),
        result.all_scores,
        c=result.all_scores,
        cmap="viridis",
        alpha=0.5,
        s=30,
    )
    axes[0].set_xlabel("Iteration")
    axes[0].set_ylabel("Best Objective Value")
    axes[0].set_title("Optimization Convergence")
    axes[0].grid(True, alpha=0.3)

    # Parameter evolution
    param_names = list(result.best_params.keys())
    n_params = len(param_names)

    if n_params <= 4:
        # Show all parameters if few enough
        for i, name in enumerate(param_names):
            values = [p[name] for p in result.all_params]
            axes[1].scatter(range(len(values)), values, label=name, alpha=0.6, s=30)
        axes[1].set_xlabel("Iteration")
        axes[1].set_ylabel("Parameter Value")
        axes[1].set_title("Parameter Evolution")
        axes[1].legend()
        axes[1].grid(True, alpha=0.3)
    else:
        # Show histogram of best parameters
        best_values = list(result.best_params.values())
        axes[1].barh(param_names, best_values, color="steelblue")
        axes[1].set_xlabel("Best Parameter Value")
        axes[1].set_title("Optimized Parameters")
        axes[1].grid(True, alpha=0.3, axis="x")

    plt.tight_layout()

    if save_path:
        plt.savefig(save_path, dpi=300, bbox_inches="tight")

    return fig

Plotting

pypath.core.plotting

Plotting module for PyPath.

This module provides visualization functions for Ecopath models and Ecosim simulation results using matplotlib and optionally plotly.

Functions include: - Food web network diagrams - Biomass time series - Catch time series - Trophic level distributions - Mixed Trophic Impacts heatmaps

Based on Rpath's plotting functions.

plot_biomass

plot_biomass(output: RsimOutput, groups: Optional[List[int]] = None, relative: bool = False, title: str = 'Biomass Time Series', figsize: Tuple[int, int] = (12, 6), legend_loc: str = 'best', ax: Optional[Axes] = None) -> plt.Figure

Plot biomass time series from Ecosim simulation.

Parameters:

Name	Type	Description	Default
output	RsimOutput	Simulation results	required
groups	list of int	Group indices to plot (default: all living)	None
relative	bool	If True, plot relative to initial biomass	False
title	str	Plot title	'Biomass Time Series'
figsize	tuple	Figure size	(12, 6)
legend_loc	str	Legend location	'best'
ax	Axes	Matplotlib axes	None

Returns:

Type	Description
Figure

Source code in pypath/core/plotting.py

def plot_biomass(
    output: RsimOutput,
    groups: Optional[List[int]] = None,
    relative: bool = False,
    title: str = "Biomass Time Series",
    figsize: Tuple[int, int] = (12, 6),
    legend_loc: str = "best",
    ax: Optional[plt.Axes] = None,
) -> plt.Figure:
    """Plot biomass time series from Ecosim simulation.

    Parameters
    ----------
    output : RsimOutput
        Simulation results
    groups : list of int, optional
        Group indices to plot (default: all living)
    relative : bool
        If True, plot relative to initial biomass
    title : str
        Plot title
    figsize : tuple
        Figure size
    legend_loc : str
        Legend location
    ax : Axes, optional
        Matplotlib axes

    Returns
    -------
    matplotlib.Figure
    """
    biomass = output.out_Biomass_annual
    n_years, n_groups = biomass.shape

    if groups is None:
        # Plot all groups with significant biomass
        groups = [i for i in range(1, n_groups) if biomass[0, i] > 0]

    if ax is None:
        fig, ax = plt.subplots(figsize=figsize)
    else:
        fig = ax.figure

    years = np.arange(1, n_years + 1)

    for grp in groups:
        y = biomass[:, grp]
        if relative and y[0] > 0:
            y = y / y[0]
        ax.plot(years, y, label=f"Group {grp}", linewidth=1.5)

    ax.set_xlabel("Year", fontsize=11)
    ylabel = "Relative Biomass (B/B₀)" if relative else "Biomass"
    ax.set_ylabel(ylabel, fontsize=11)
    ax.set_title(title, fontsize=12)

    if relative:
        ax.axhline(y=1, color="k", linestyle="--", alpha=0.5)

    ax.legend(loc=legend_loc, fontsize=9)
    ax.grid(True, alpha=0.3)

    plt.tight_layout()
    return fig

plot_biomass_grid

plot_biomass_grid(output: RsimOutput, groups: Optional[List[int]] = None, n_cols: int = 4, relative: bool = True, figsize: Optional[Tuple[int, int]] = None) -> plt.Figure

Plot biomass as a grid of subplots.

Parameters:

Name	Type	Description	Default
output	RsimOutput	Simulation results	required
groups	list of int	Group indices to plot	None
n_cols	int	Number of columns in grid	4
relative	bool	Plot relative to initial biomass	True
figsize	tuple	Figure size	None

Returns:

Type	Description
Figure

Source code in pypath/core/plotting.py

def plot_biomass_grid(
    output: RsimOutput,
    groups: Optional[List[int]] = None,
    n_cols: int = 4,
    relative: bool = True,
    figsize: Optional[Tuple[int, int]] = None,
) -> plt.Figure:
    """Plot biomass as a grid of subplots.

    Parameters
    ----------
    output : RsimOutput
        Simulation results
    groups : list of int, optional
        Group indices to plot
    n_cols : int
        Number of columns in grid
    relative : bool
        Plot relative to initial biomass
    figsize : tuple, optional
        Figure size

    Returns
    -------
    matplotlib.Figure
    """
    biomass = output.out_Biomass_annual
    n_years, n_groups = biomass.shape

    if groups is None:
        groups = [i for i in range(1, n_groups) if biomass[0, i] > 0]

    n_plots = len(groups)
    n_rows = (n_plots + n_cols - 1) // n_cols

    if figsize is None:
        figsize = (3 * n_cols, 2.5 * n_rows)

    fig, axes = plt.subplots(n_rows, n_cols, figsize=figsize, squeeze=False)
    axes = axes.flatten()

    years = np.arange(1, n_years + 1)

    for idx, grp in enumerate(groups):
        ax = axes[idx]
        y = biomass[:, grp]

        if relative and y[0] > 0:
            y = y / y[0]
            ax.axhline(y=1, color="k", linestyle="--", alpha=0.3)

        ax.plot(years, y, color="steelblue", linewidth=1.5)
        ax.set_title(f"Group {grp}", fontsize=10)
        ax.tick_params(labelsize=8)
        ax.grid(True, alpha=0.3)

    # Hide empty subplots
    for idx in range(len(groups), len(axes)):
        axes[idx].set_visible(False)

    plt.suptitle(
        "Biomass Time Series" + (" (Relative)" if relative else ""), fontsize=12
    )
    plt.tight_layout()
    return fig

plot_biomass_interactive

plot_biomass_interactive(output: RsimOutput, groups: Optional[List[int]] = None, relative: bool = False, title: str = 'Biomass Time Series') -> Any

Create interactive biomass plot with Plotly.

Parameters:

Name	Type	Description	Default
output	RsimOutput	Simulation results	required
groups	list of int	Groups to plot	None
relative	bool	Plot relative to initial	False
title	str	Plot title	'Biomass Time Series'

Returns:

Type	Description
Figure

Source code in pypath/core/plotting.py

def plot_biomass_interactive(
    output: RsimOutput,
    groups: Optional[List[int]] = None,
    relative: bool = False,
    title: str = "Biomass Time Series",
) -> Any:
    """Create interactive biomass plot with Plotly.

    Parameters
    ----------
    output : RsimOutput
        Simulation results
    groups : list of int, optional
        Groups to plot
    relative : bool
        Plot relative to initial
    title : str
        Plot title

    Returns
    -------
    plotly.graph_objects.Figure
    """
    if not HAS_PLOTLY:
        raise ImportError(
            "plotly is required for interactive plots. Install with: pip install plotly"
        )

    biomass = output.out_Biomass_annual
    n_years, n_groups = biomass.shape

    if groups is None:
        groups = [i for i in range(1, n_groups) if biomass[0, i] > 0]

    fig = go.Figure()

    years = np.arange(1, n_years + 1)

    for grp in groups:
        y = biomass[:, grp]
        if relative and y[0] > 0:
            y = y / y[0]

        fig.add_trace(
            go.Scatter(
                x=years,
                y=y,
                mode="lines",
                name=f"Group {grp}",
                hovertemplate="Year: %{x}<br>Biomass: %{y:.4f}<extra></extra>",
            )
        )

    ylabel = "Relative Biomass (B/B₀)" if relative else "Biomass"

    fig.update_layout(
        title=title,
        xaxis_title="Year",
        yaxis_title=ylabel,
        hovermode="x unified",
        template="plotly_white",
    )

    if relative:
        fig.add_hline(y=1, line_dash="dash", line_color="gray", opacity=0.5)

    return fig

plot_catch

plot_catch(output: RsimOutput, groups: Optional[List[int]] = None, title: str = 'Catch Time Series', figsize: Tuple[int, int] = (12, 6), stacked: bool = False, ax: Optional[Axes] = None) -> plt.Figure

Plot catch time series from Ecosim simulation.

Parameters:

Name	Type	Description	Default
output	RsimOutput	Simulation results	required
groups	list of int	Group indices to plot	None
title	str	Plot title	'Catch Time Series'
figsize	tuple	Figure size	(12, 6)
stacked	bool	If True, create stacked area plot	False
ax	Axes	Matplotlib axes	None

Returns:

Type	Description
Figure

Source code in pypath/core/plotting.py

def plot_catch(
    output: RsimOutput,
    groups: Optional[List[int]] = None,
    title: str = "Catch Time Series",
    figsize: Tuple[int, int] = (12, 6),
    stacked: bool = False,
    ax: Optional[plt.Axes] = None,
) -> plt.Figure:
    """Plot catch time series from Ecosim simulation.

    Parameters
    ----------
    output : RsimOutput
        Simulation results
    groups : list of int, optional
        Group indices to plot
    title : str
        Plot title
    figsize : tuple
        Figure size
    stacked : bool
        If True, create stacked area plot
    ax : Axes, optional
        Matplotlib axes

    Returns
    -------
    matplotlib.Figure
    """
    catch = output.out_Catch_annual
    n_years, n_groups = catch.shape

    if groups is None:
        # Plot groups with any catch
        groups = [i for i in range(1, n_groups) if np.sum(catch[:, i]) > 0]

    if not groups:
        # No catch - return empty plot
        fig, ax = plt.subplots(figsize=figsize)
        ax.text(
            0.5, 0.5, "No catch data", ha="center", va="center", transform=ax.transAxes
        )
        ax.set_title(title)
        return fig

    if ax is None:
        fig, ax = plt.subplots(figsize=figsize)
    else:
        fig = ax.figure

    years = np.arange(1, n_years + 1)

    if stacked:
        catch_data = [catch[:, grp] for grp in groups]
        labels = [f"Group {grp}" for grp in groups]
        ax.stackplot(years, catch_data, labels=labels, alpha=0.7)
    else:
        for grp in groups:
            ax.plot(years, catch[:, grp], label=f"Group {grp}", linewidth=1.5)

    ax.set_xlabel("Year", fontsize=11)
    ax.set_ylabel("Catch", fontsize=11)
    ax.set_title(title, fontsize=12)
    ax.legend(loc="best", fontsize=9)
    ax.grid(True, alpha=0.3)

    plt.tight_layout()
    return fig

plot_ecosim_summary

plot_ecosim_summary(output: RsimOutput, groups: Optional[List[int]] = None, figsize: Tuple[int, int] = (14, 10)) -> plt.Figure

Create summary plot with biomass, relative biomass, and catch.

Parameters:

Name	Type	Description	Default
output	RsimOutput	Simulation results	required
groups	list of int	Groups to plot	None
figsize	tuple	Figure size	(14, 10)

Returns:

Type	Description
Figure

Source code in pypath/core/plotting.py

def plot_ecosim_summary(
    output: RsimOutput,
    groups: Optional[List[int]] = None,
    figsize: Tuple[int, int] = (14, 10),
) -> plt.Figure:
    """Create summary plot with biomass, relative biomass, and catch.

    Parameters
    ----------
    output : RsimOutput
        Simulation results
    groups : list of int, optional
        Groups to plot
    figsize : tuple
        Figure size

    Returns
    -------
    matplotlib.Figure
    """
    fig, axes = plt.subplots(2, 2, figsize=figsize)

    plot_biomass(output, groups=groups, ax=axes[0, 0], relative=False)
    axes[0, 0].set_title("Absolute Biomass")

    plot_biomass(output, groups=groups, ax=axes[0, 1], relative=True)
    axes[0, 1].set_title("Relative Biomass (B/B₀)")

    plot_catch(output, groups=groups, ax=axes[1, 0], stacked=False)
    axes[1, 0].set_title("Catch by Group")

    plot_catch(output, groups=groups, ax=axes[1, 1], stacked=True)
    axes[1, 1].set_title("Total Catch (Stacked)")

    plt.tight_layout()
    return fig

plot_foodweb

plot_foodweb(rpath: Rpath, title: str = 'Food Web', layout: str = 'trophic', node_size_by: str = 'biomass', edge_width_by: str = 'flow', show_labels: bool = True, min_flow: float = 0.01, figsize: Tuple[int, int] = (12, 10), cmap: str = 'viridis', ax: Optional[Axes] = None) -> plt.Figure

Plot food web network diagram.

Parameters:

Name	Type	Description	Default
rpath	Rpath	Balanced Ecopath model	required
title	str	Plot title	'Food Web'
layout	str	Node layout: 'trophic' (y=TL), 'spring', 'circular'	'trophic'
node_size_by	str	What to scale node size by: 'biomass', 'production', 'equal'	'biomass'
edge_width_by	str	What to scale edge width by: 'flow', 'diet', 'equal'	'flow'
show_labels	bool	Show group labels	True
min_flow	float	Minimum flow to show (relative to max)	0.01
figsize	tuple	Figure size	(12, 10)
cmap	str	Colormap for trophic levels	'viridis'
ax	Axes	Matplotlib axes to plot on	None

Returns:

Type	Description
Figure	The figure object

Source code in pypath/core/plotting.py

def plot_foodweb(
    rpath: Rpath,
    title: str = "Food Web",
    layout: str = "trophic",
    node_size_by: str = "biomass",
    edge_width_by: str = "flow",
    show_labels: bool = True,
    min_flow: float = 0.01,
    figsize: Tuple[int, int] = (12, 10),
    cmap: str = "viridis",
    ax: Optional[plt.Axes] = None,
) -> plt.Figure:
    """Plot food web network diagram.

    Parameters
    ----------
    rpath : Rpath
        Balanced Ecopath model
    title : str
        Plot title
    layout : str
        Node layout: 'trophic' (y=TL), 'spring', 'circular'
    node_size_by : str
        What to scale node size by: 'biomass', 'production', 'equal'
    edge_width_by : str
        What to scale edge width by: 'flow', 'diet', 'equal'
    show_labels : bool
        Show group labels
    min_flow : float
        Minimum flow to show (relative to max)
    figsize : tuple
        Figure size
    cmap : str
        Colormap for trophic levels
    ax : Axes, optional
        Matplotlib axes to plot on

    Returns
    -------
    matplotlib.Figure
        The figure object
    """
    if not HAS_NETWORKX:
        raise ImportError(
            "networkx is required for food web plots. Install with: pip install networkx"
        )

    n_living = rpath.NUM_LIVING
    n_dead = rpath.NUM_DEAD
    n_total = n_living + n_dead

    # Create directed graph
    G = nx.DiGraph()

    # Add nodes
    # Rpath arrays are 0-based over NUM_GROUPS; groups 0..n_living-1 are
    # living and n_living..n_total-1 are detritus. DC is (NUM_GROUPS + 1,
    # NUM_LIVING), so its columns are predators and its rows are prey.
    for i in range(n_total):
        G.add_node(
            i, tl=rpath.TL[i], biomass=rpath.Biomass[i], is_detritus=i >= n_living
        )

    # Add edges (from prey to predator)
    max_flow = 0
    for pred in range(n_living):
        for prey in range(n_total):
            if rpath.DC[prey, pred] > 0:
                flow = rpath.DC[prey, pred] * rpath.QB[pred] * rpath.Biomass[pred]
                max_flow = max(max_flow, flow)
                G.add_edge(prey, pred, flow=flow, diet=rpath.DC[prey, pred])

    # Filter small flows
    edges_to_remove = []
    for u, v, data in G.edges(data=True):
        if data["flow"] < min_flow * max_flow:
            edges_to_remove.append((u, v))
    G.remove_edges_from(edges_to_remove)

    # Calculate layout
    if layout == "trophic":
        # Position by trophic level (y) and spread horizontally
        pos = {}
        tl_groups = {}
        for node in G.nodes():
            tl = round(G.nodes[node]["tl"], 1)
            if tl not in tl_groups:
                tl_groups[tl] = []
            tl_groups[tl].append(node)

        for tl, nodes in tl_groups.items():
            n = len(nodes)
            for i, node in enumerate(nodes):
                x = (i - (n - 1) / 2) * 0.8
                pos[node] = (x, tl)
    elif layout == "spring":
        pos = nx.spring_layout(G, seed=42)
    elif layout == "circular":
        pos = nx.circular_layout(G)
    else:
        pos = nx.spring_layout(G, seed=42)

    # Calculate node sizes
    if node_size_by == "biomass":
        max_bio = max(rpath.Biomass[:n_total])
        node_sizes = [500 + 2000 * (rpath.Biomass[i] / max_bio) for i in G.nodes()]
    elif node_size_by == "production":
        prods = [rpath.PB[i] * rpath.Biomass[i] for i in G.nodes()]
        max_prod = max(prods) if max(prods) > 0 else 1
        node_sizes = [500 + 2000 * (p / max_prod) for p in prods]
    else:
        node_sizes = [800] * len(G.nodes())

    # Calculate edge widths
    if edge_width_by == "flow":
        edge_widths = []
        for u, v in G.edges():
            w = G.edges[u, v]["flow"] / max_flow if max_flow > 0 else 0
            edge_widths.append(0.5 + 4 * w)
    elif edge_width_by == "diet":
        edge_widths = [0.5 + 4 * G.edges[u, v]["diet"] for u, v in G.edges()]
    else:
        edge_widths = [1.5] * len(G.edges())

    # Node colors by trophic level
    trophic_levels = [G.nodes[i]["tl"] for i in G.nodes()]

    # Create figure
    if ax is None:
        fig, ax = plt.subplots(figsize=figsize)
    else:
        fig = ax.figure

    # Draw network
    nx.draw_networkx_nodes(
        G,
        pos,
        node_size=node_sizes,
        node_color=trophic_levels,
        cmap=plt.colormaps[cmap],
        ax=ax,
        alpha=0.8,
    )

    nx.draw_networkx_edges(
        G,
        pos,
        width=edge_widths,
        edge_color="gray",
        alpha=0.5,
        arrows=True,
        arrowsize=15,
        connectionstyle="arc3,rad=0.1",
        ax=ax,
    )

    if show_labels:
        names = _group_labels(rpath, n_total)
        labels = {i: names[i] for i in G.nodes()}
        nx.draw_networkx_labels(G, pos, labels, font_size=8, ax=ax)

    # Add colorbar for trophic levels
    sm = plt.cm.ScalarMappable(
        cmap=plt.colormaps[cmap],
        norm=plt.Normalize(vmin=min(trophic_levels), vmax=max(trophic_levels)),
    )
    sm.set_array([])
    cbar = plt.colorbar(sm, ax=ax, shrink=0.6)
    cbar.set_label("Trophic Level")

    ax.set_title(title, fontsize=14)
    ax.axis("off")

    plt.tight_layout()
    return fig

plot_foodweb_interactive

plot_foodweb_interactive(rpath: Rpath, title: str = 'Food Web', min_flow: float = 0.01) -> Any

Create interactive food web plot with Plotly.

Parameters:

Name	Type	Description	Default
rpath	Rpath	Balanced model	required
title	str	Plot title	'Food Web'
min_flow	float	Minimum flow to show	0.01

Returns:

Type	Description
Figure

Source code in pypath/core/plotting.py

def plot_foodweb_interactive(
    rpath: Rpath,
    title: str = "Food Web",
    min_flow: float = 0.01,
) -> Any:
    """Create interactive food web plot with Plotly.

    Parameters
    ----------
    rpath : Rpath
        Balanced model
    title : str
        Plot title
    min_flow : float
        Minimum flow to show

    Returns
    -------
    plotly.graph_objects.Figure
    """
    if not HAS_PLOTLY:
        raise ImportError(
            "plotly is required for interactive plots. Install with: pip install plotly"
        )
    if not HAS_NETWORKX:
        raise ImportError(
            "networkx is required for food web plots. Install with: pip install networkx"
        )

    n_living = rpath.NUM_LIVING
    n_dead = rpath.NUM_DEAD
    n_total = n_living + n_dead

    # Build graph for layout
    G = nx.DiGraph()
    for i in range(n_total):
        G.add_node(i, tl=rpath.TL[i], biomass=rpath.Biomass[i])

    max_flow = 0
    edges = []
    for pred in range(n_living):
        for prey in range(n_total):
            if rpath.DC[prey, pred] > 0:
                flow = rpath.DC[prey, pred] * rpath.QB[pred] * rpath.Biomass[pred]
                max_flow = max(max_flow, flow)
                G.add_edge(prey, pred)
                edges.append((prey, pred, flow))

    # Layout
    pos = {}
    tl_groups = {}
    for node in G.nodes():
        tl = round(rpath.TL[node], 1)
        if tl not in tl_groups:
            tl_groups[tl] = []
        tl_groups[tl].append(node)

    for tl, nodes in tl_groups.items():
        n = len(nodes)
        for i, node in enumerate(nodes):
            x = (i - (n - 1) / 2) * 0.8
            pos[node] = (x, tl)

    # Node trace
    node_x = [pos[node][0] for node in G.nodes()]
    node_y = [pos[node][1] for node in G.nodes()]
    labels = _group_labels(rpath, n_total)
    node_text = [
        f"{labels[n]}<br>TL: {rpath.TL[n]:.2f}<br>B: {rpath.Biomass[n]:.4f}"
        for n in G.nodes()
    ]
    node_size = [
        10 + 30 * rpath.Biomass[n] / max(rpath.Biomass[:n_total]) for n in G.nodes()
    ]

    node_trace = go.Scatter(
        x=node_x,
        y=node_y,
        mode="markers+text",
        hoverinfo="text",
        text=[labels[n] for n in G.nodes()],
        hovertext=node_text,
        textposition="top center",
        marker=dict(
            size=node_size,
            color=[rpath.TL[n] for n in G.nodes()],
            colorscale="Viridis",
            colorbar=dict(title="Trophic Level"),
            line_width=2,
        ),
    )

    # Edge traces
    edge_traces = []
    for prey, pred, flow in edges:
        if flow >= min_flow * max_flow:
            x0, y0 = pos[prey]
            x1, y1 = pos[pred]
            width = 1 + 4 * flow / max_flow

            edge_traces.append(
                go.Scatter(
                    x=[x0, x1, None],
                    y=[y0, y1, None],
                    mode="lines",
                    line=dict(width=width, color="gray"),
                    hoverinfo="none",
                    showlegend=False,
                )
            )

    fig = go.Figure(data=edge_traces + [node_trace])

    fig.update_layout(
        title=title,
        showlegend=False,
        hovermode="closest",
        xaxis=dict(showgrid=False, zeroline=False, showticklabels=False),
        yaxis=dict(
            showgrid=False, zeroline=False, showticklabels=False, title="Trophic Level"
        ),
        template="plotly_white",
    )

    return fig

plot_mti_heatmap

plot_mti_heatmap(mti: ndarray, group_names: Optional[List[str]] = None, title: str = 'Mixed Trophic Impacts', figsize: Tuple[int, int] = (10, 8), cmap: str = 'RdBu_r', ax: Optional[Axes] = None) -> plt.Figure

Plot Mixed Trophic Impacts as a heatmap.

Parameters:

Name	Type	Description	Default
mti	ndarray	MTI matrix from mixed_trophic_impacts()	required
group_names	list of str	Names for groups	None
title	str	Plot title	'Mixed Trophic Impacts'
figsize	tuple	Figure size	(10, 8)
cmap	str	Colormap	'RdBu_r'
ax	Axes	Matplotlib axes	None

Returns:

Type	Description
Figure

Source code in pypath/core/plotting.py

def plot_mti_heatmap(
    mti: np.ndarray,
    group_names: Optional[List[str]] = None,
    title: str = "Mixed Trophic Impacts",
    figsize: Tuple[int, int] = (10, 8),
    cmap: str = "RdBu_r",
    ax: Optional[plt.Axes] = None,
) -> plt.Figure:
    """Plot Mixed Trophic Impacts as a heatmap.

    Parameters
    ----------
    mti : np.ndarray
        MTI matrix from mixed_trophic_impacts()
    group_names : list of str, optional
        Names for groups
    title : str
        Plot title
    figsize : tuple
        Figure size
    cmap : str
        Colormap
    ax : Axes, optional
        Matplotlib axes

    Returns
    -------
    matplotlib.Figure
    """
    n = mti.shape[0]

    if group_names is None:
        group_names = [f"G{i}" for i in range(1, n + 1)]

    if ax is None:
        fig, ax = plt.subplots(figsize=figsize)
    else:
        fig = ax.figure

    # Symmetric colormap around zero
    vmax = np.max(np.abs(mti))
    vmin = -vmax

    im = ax.imshow(mti, cmap=cmap, vmin=vmin, vmax=vmax, aspect="auto")

    # Colorbar
    cbar = plt.colorbar(im, ax=ax, shrink=0.8)
    cbar.set_label("Impact")

    # Labels
    ax.set_xticks(range(n))
    ax.set_yticks(range(n))
    ax.set_xticklabels(group_names, rotation=45, ha="right", fontsize=8)
    ax.set_yticklabels(group_names, fontsize=8)

    ax.set_xlabel("Impacted", fontsize=11)
    ax.set_ylabel("Impacting", fontsize=11)
    ax.set_title(title, fontsize=12)

    plt.tight_layout()
    return fig

plot_trophic_spectrum

plot_trophic_spectrum(rpath: Rpath, by: str = 'biomass', n_bins: int = 10, title: str = 'Trophic Spectrum', figsize: Tuple[int, int] = (10, 6), ax: Optional[Axes] = None) -> plt.Figure

Plot trophic spectrum (biomass or production by trophic level).

Parameters:

Name	Type	Description	Default
rpath	Rpath	Balanced model	required
by	str	What to aggregate: 'biomass', 'production', 'consumption'	'biomass'
n_bins	int	Number of trophic level bins	10
title	str	Plot title	'Trophic Spectrum'
figsize	tuple	Figure size	(10, 6)
ax	Axes	Matplotlib axes	None

Returns:

Type	Description
Figure

Source code in pypath/core/plotting.py

def plot_trophic_spectrum(
    rpath: Rpath,
    by: str = "biomass",
    n_bins: int = 10,
    title: str = "Trophic Spectrum",
    figsize: Tuple[int, int] = (10, 6),
    ax: Optional[plt.Axes] = None,
) -> plt.Figure:
    """Plot trophic spectrum (biomass or production by trophic level).

    Parameters
    ----------
    rpath : Rpath
        Balanced model
    by : str
        What to aggregate: 'biomass', 'production', 'consumption'
    n_bins : int
        Number of trophic level bins
    title : str
        Plot title
    figsize : tuple
        Figure size
    ax : Axes, optional
        Matplotlib axes

    Returns
    -------
    matplotlib.Figure
    """
    n_living = rpath.NUM_LIVING

    # Get values and trophic levels
    # Living groups occupy indices 0..n_living-1 of the 0-based Rpath arrays.
    tl = rpath.TL[:n_living]

    if by == "biomass":
        values = rpath.Biomass[:n_living]
        ylabel = "Biomass"
    elif by == "production":
        values = rpath.PB[:n_living] * rpath.Biomass[:n_living]
        ylabel = "Production"
    elif by == "consumption":
        values = rpath.QB[:n_living] * rpath.Biomass[:n_living]
        ylabel = "Consumption"
    else:
        raise ValueError(f"Unknown 'by' value: {by}")

    # Create bins
    tl_min, tl_max = np.floor(np.min(tl)), np.ceil(np.max(tl))
    bins = np.linspace(tl_min, tl_max, n_bins + 1)
    bin_centers = (bins[:-1] + bins[1:]) / 2

    # Aggregate
    aggregated = np.zeros(n_bins)
    for i in range(len(tl)):
        bin_idx = np.digitize(tl[i], bins) - 1
        bin_idx = min(bin_idx, n_bins - 1)
        aggregated[bin_idx] += values[i]

    if ax is None:
        fig, ax = plt.subplots(figsize=figsize)
    else:
        fig = ax.figure

    ax.bar(
        bin_centers,
        aggregated,
        width=bins[1] - bins[0],
        color="steelblue",
        edgecolor="black",
        alpha=0.7,
    )

    ax.set_xlabel("Trophic Level", fontsize=11)
    ax.set_ylabel(ylabel, fontsize=11)
    ax.set_title(title, fontsize=12)
    ax.grid(True, alpha=0.3, axis="y")

    plt.tight_layout()
    return fig

save_plots

save_plots(figures: Union[Figure, List[Figure]], filename: str, dpi: int = 150, format: str = 'png') -> None

Save matplotlib figure(s) to file.

Parameters:

Name	Type	Description	Default
figures	Figure or list of Figure	Figure(s) to save	required
filename	str	Output filename (without extension for multiple figures)	required
dpi	int	Resolution	150
format	str	Output format ('png', 'pdf', 'svg')	'png'

Source code in pypath/core/plotting.py

def save_plots(
    figures: Union[plt.Figure, List[plt.Figure]],
    filename: str,
    dpi: int = 150,
    format: str = "png",
) -> None:
    """Save matplotlib figure(s) to file.

    Parameters
    ----------
    figures : Figure or list of Figure
        Figure(s) to save
    filename : str
        Output filename (without extension for multiple figures)
    dpi : int
        Resolution
    format : str
        Output format ('png', 'pdf', 'svg')
    """
    if isinstance(figures, plt.Figure):
        figures = [figures]

    if len(figures) == 1:
        figures[0].savefig(f"{filename}.{format}", dpi=dpi, bbox_inches="tight")
    else:
        for i, fig in enumerate(figures):
            fig.savefig(f"{filename}_{i + 1}.{format}", dpi=dpi, bbox_inches="tight")

Analysis & Network Indices

Mixed Trophic Impacts, network indices (connectance, omnivory), and Ecosim output summary statistics.

pypath.core.analysis

Analysis and diagnostics module for PyPath.

This module provides functions for analyzing Ecopath models and Ecosim simulation results, including: - Mixed Trophic Impacts (MTI) - Network indices (connectance, omnivory index, etc.) - Ecosim output summary statistics - Model diagnostics and validation

Based on Rpath's analysis functions.

NetworkIndices dataclass

Container for food web network indices.

Attributes:

Name	Type	Description
n_groups	int	Number of groups
n_living	int	Number of living groups
n_links	int	Number of trophic links (non-zero diet entries)
connectance	float	Links / (living groups)^2
linkage_density	float	Links / living groups
omnivory_index	float	Mean variance of prey trophic levels
system_omnivory	float	Total system omnivory
mean_trophic_level	float	Biomass-weighted mean trophic level
max_trophic_level	float	Maximum trophic level
total_biomass	float	Sum of all biomass
total_throughput	float	Sum of all flows
transfer_efficiency	float	Mean trophic transfer efficiency
finn_cycling_index	float	Fraction of throughput recycled

Source code in pypath/core/analysis.py

@dataclass
class NetworkIndices:
    """Container for food web network indices.

    Attributes
    ----------
    n_groups : int
        Number of groups
    n_living : int
        Number of living groups
    n_links : int
        Number of trophic links (non-zero diet entries)
    connectance : float
        Links / (living groups)^2
    linkage_density : float
        Links / living groups
    omnivory_index : float
        Mean variance of prey trophic levels
    system_omnivory : float
        Total system omnivory
    mean_trophic_level : float
        Biomass-weighted mean trophic level
    max_trophic_level : float
        Maximum trophic level
    total_biomass : float
        Sum of all biomass
    total_throughput : float
        Sum of all flows
    transfer_efficiency : float
        Mean trophic transfer efficiency
    finn_cycling_index : float
        Fraction of throughput recycled
    """

    n_groups: int = 0
    n_living: int = 0
    n_links: int = 0
    connectance: float = 0.0
    linkage_density: float = 0.0
    omnivory_index: float = 0.0
    system_omnivory: float = 0.0
    mean_trophic_level: float = 0.0
    max_trophic_level: float = 0.0
    total_biomass: float = 0.0
    total_throughput: float = 0.0
    transfer_efficiency: float = 0.0
    finn_cycling_index: float = 0.0

EcosimSummary dataclass

Summary statistics for Ecosim simulation results.

Attributes:

Name	Type	Description
group_names	list	Names of groups
years	int	Number of years simulated

Biomass statistics

biomass_start : np.ndarray Initial biomass biomass_end : np.ndarray Final biomass biomass_min : np.ndarray Minimum biomass over simulation biomass_max : np.ndarray Maximum biomass over simulation biomass_mean : np.ndarray Mean biomass over simulation biomass_cv : np.ndarray Coefficient of variation of biomass biomass_change : np.ndarray Relative change (end/start - 1)

Catch statistics

total_catch : np.ndarray Total catch over simulation mean_annual_catch : np.ndarray Mean annual catch catch_cv : np.ndarray Coefficient of variation of catch

Source code in pypath/core/analysis.py

@dataclass
class EcosimSummary:
    """Summary statistics for Ecosim simulation results.

    Attributes
    ----------
    group_names : list
        Names of groups
    years : int
        Number of years simulated

    Biomass statistics
    ------------------
    biomass_start : np.ndarray
        Initial biomass
    biomass_end : np.ndarray
        Final biomass
    biomass_min : np.ndarray
        Minimum biomass over simulation
    biomass_max : np.ndarray
        Maximum biomass over simulation
    biomass_mean : np.ndarray
        Mean biomass over simulation
    biomass_cv : np.ndarray
        Coefficient of variation of biomass
    biomass_change : np.ndarray
        Relative change (end/start - 1)

    Catch statistics
    ----------------
    total_catch : np.ndarray
        Total catch over simulation
    mean_annual_catch : np.ndarray
        Mean annual catch
    catch_cv : np.ndarray
        Coefficient of variation of catch
    """

    group_names: List[str] = field(default_factory=list)
    years: int = 0

    # Biomass
    biomass_start: np.ndarray = field(default_factory=lambda: np.array([]))
    biomass_end: np.ndarray = field(default_factory=lambda: np.array([]))
    biomass_min: np.ndarray = field(default_factory=lambda: np.array([]))
    biomass_max: np.ndarray = field(default_factory=lambda: np.array([]))
    biomass_mean: np.ndarray = field(default_factory=lambda: np.array([]))
    biomass_cv: np.ndarray = field(default_factory=lambda: np.array([]))
    biomass_change: np.ndarray = field(default_factory=lambda: np.array([]))

    # Catch
    total_catch: np.ndarray = field(default_factory=lambda: np.array([]))
    mean_annual_catch: np.ndarray = field(default_factory=lambda: np.array([]))
    catch_cv: np.ndarray = field(default_factory=lambda: np.array([]))

mixed_trophic_impacts

mixed_trophic_impacts(rpath: Rpath) -> np.ndarray

Calculate Mixed Trophic Impacts matrix.

MTI measures the direct and indirect effects of a small change in biomass of each group on all other groups. Positive values indicate that increasing the impacting group benefits the impacted group.

MTI = (I - Q)^-1 * diag(DC) * (I - DC)^-1

where: - Q[i,j] = proportion of j's production consumed by i - DC[i,j] = diet composition (fraction of i's diet from j)

Parameters:

Name	Type	Description	Default
rpath	Rpath	Balanced Ecopath model	required

Returns:

Type	Description
ndarray	MTI matrix [impacting, impacted] where: - Rows are impacting groups - Columns are impacted groups - Values show relative impact

Example

mti = mixed_trophic_impacts(rpath)

Impact of group 1 on group 2

impact = mti[1, 2]

Source code in pypath/core/analysis.py

def mixed_trophic_impacts(rpath: Rpath) -> np.ndarray:
    """Calculate Mixed Trophic Impacts matrix.

    MTI measures the direct and indirect effects of a small change in
    biomass of each group on all other groups. Positive values indicate
    that increasing the impacting group benefits the impacted group.

    MTI = (I - Q)^-1 * diag(DC) * (I - DC)^-1

    where:
    - Q[i,j] = proportion of j's production consumed by i
    - DC[i,j] = diet composition (fraction of i's diet from j)

    Parameters
    ----------
    rpath : Rpath
        Balanced Ecopath model

    Returns
    -------
    np.ndarray
        MTI matrix [impacting, impacted] where:
        - Rows are impacting groups
        - Columns are impacted groups
        - Values show relative impact

    Example
    -------
    >>> mti = mixed_trophic_impacts(rpath)
    >>> # Impact of group 1 on group 2
    >>> impact = mti[1, 2]
    """
    n_groups = rpath.NUM_LIVING + rpath.NUM_DEAD

    # Diet composition as a square (prey x predator) matrix over living+detritus
    # groups. Rpath arrays are 0-indexed; rpath.DC has one row per prey group
    # (plus a trailing import row) and one column per living predator.
    DC = np.zeros((n_groups, n_groups))
    n_pred = min(rpath.DC.shape[1], n_groups)
    DC[:, :n_pred] = rpath.DC[:n_groups, :n_pred]

    # Calculate Q matrix: Q[i,j] = proportion of j consumed by i
    Q = np.zeros((n_groups, n_groups))

    for pred in range(n_groups):
        for prey in range(n_groups):
            if rpath.Biomass[pred] > 0 and rpath.QB[pred] > 0:
                # Consumption of prey by pred
                consump = DC[prey, pred] * rpath.QB[pred] * rpath.Biomass[pred]
                # Production of prey
                prod = rpath.PB[prey] * rpath.Biomass[prey]
                if prod > 0:
                    Q[pred, prey] = consump / prod

    # Calculate MTI using Leontief inverse
    eye = np.eye(n_groups)

    try:
        # Use net food web matrix approach (avoid allocating unused inverses)
        net = DC - Q.T  # Diet minus proportion consumed

        # MTI as Leontief inverse of net matrix
        mti = np.linalg.inv(eye - net) - eye

    except np.linalg.LinAlgError:
        # Matrix is singular, use pseudoinverse
        net = DC - Q.T
        mti = np.linalg.pinv(eye - net) - eye

    return mti

keystoneness_index

keystoneness_index(rpath: Rpath, mti: Optional[ndarray] = None) -> np.ndarray

Calculate keystoneness index for each group.

Keystoneness = overall impact * log(1/biomass_proportion)

High keystoneness indicates groups that have disproportionate impact relative to their biomass.

Parameters:

Name	Type	Description	Default
rpath	Rpath	Balanced Ecopath model	required
mti	ndarray	Pre-computed MTI matrix. If None, will be calculated.	None

Returns:

Type	Description
ndarray	Keystoneness index for each living and detritus group, aligned with rpath.Group[:NUM_LIVING + NUM_DEAD] (0-indexed, same order as the MTI matrix).

Source code in pypath/core/analysis.py

def keystoneness_index(rpath: Rpath, mti: Optional[np.ndarray] = None) -> np.ndarray:
    """Calculate keystoneness index for each group.

    Keystoneness = overall impact * log(1/biomass_proportion)

    High keystoneness indicates groups that have disproportionate
    impact relative to their biomass.

    Parameters
    ----------
    rpath : Rpath
        Balanced Ecopath model
    mti : np.ndarray, optional
        Pre-computed MTI matrix. If None, will be calculated.

    Returns
    -------
    np.ndarray
        Keystoneness index for each living and detritus group, aligned with
        ``rpath.Group[:NUM_LIVING + NUM_DEAD]`` (0-indexed, same order as the
        MTI matrix).
    """
    if mti is None:
        mti = mixed_trophic_impacts(rpath)

    n_groups = mti.shape[0]
    keystoneness = np.zeros(n_groups)

    # Total biomass
    total_bio = np.sum(rpath.Biomass[:n_groups])

    for i in range(n_groups):
        # Overall impact: sum of absolute impacts excluding self
        impact = np.sum(np.abs(mti[i, :])) - np.abs(mti[i, i])

        # Biomass proportion
        bio_prop = rpath.Biomass[i] / total_bio if total_bio > 0 else 0

        # Keystoneness
        if bio_prop > 0:
            keystoneness[i] = impact * np.log(1.0 / bio_prop)
        else:
            keystoneness[i] = 0

    return keystoneness

calculate_network_indices

calculate_network_indices(rpath: Rpath) -> NetworkIndices

Calculate food web network indices.

Parameters:

Name	Type	Description	Default
rpath	Rpath	Balanced Ecopath model	required

Returns:

Type	Description
NetworkIndices	Container with all calculated indices

Source code in pypath/core/analysis.py

def calculate_network_indices(rpath: Rpath) -> NetworkIndices:
    """Calculate food web network indices.

    Parameters
    ----------
    rpath : Rpath
        Balanced Ecopath model

    Returns
    -------
    NetworkIndices
        Container with all calculated indices
    """
    n_living = rpath.NUM_LIVING
    n_dead = rpath.NUM_DEAD
    n_total = n_living + n_dead

    # Count trophic links
    n_links = 0
    for pred in range(n_living):
        for prey in range(n_total):
            if rpath.DC[prey, pred] > 0:
                n_links += 1

    # Connectance (living groups only)
    connectance = n_links / (n_living**2) if n_living > 0 else 0

    # Linkage density
    linkage_density = n_links / n_living if n_living > 0 else 0

    # Omnivory index: variance of prey trophic levels per consumer
    omnivory_sum = 0.0
    n_consumers = 0

    for pred in range(n_living):
        prey_tls = []
        prey_fracs = []

        for prey in range(n_total):
            if rpath.DC[prey, pred] > 0:
                prey_tls.append(rpath.TL[prey])
                prey_fracs.append(rpath.DC[prey, pred])

        if len(prey_tls) > 1:
            # Weighted mean TL
            mean_tl = np.average(prey_tls, weights=prey_fracs)
            # Weighted variance
            var_tl = np.average((np.array(prey_tls) - mean_tl) ** 2, weights=prey_fracs)
            omnivory_sum += var_tl
            n_consumers += 1

    omnivory_index = omnivory_sum / n_consumers if n_consumers > 0 else 0

    # System omnivory: weighted by consumption
    system_omni = 0.0
    total_consump = 0.0

    for pred in range(n_living):
        if rpath.QB[pred] > 0:
            consump = rpath.QB[pred] * rpath.Biomass[pred]
            total_consump += consump

            prey_tls = []
            prey_fracs = []
            for prey in range(n_total):
                if rpath.DC[prey, pred] > 0:
                    prey_tls.append(rpath.TL[prey])
                    prey_fracs.append(rpath.DC[prey, pred])

            if len(prey_tls) > 1:
                mean_tl = np.average(prey_tls, weights=prey_fracs)
                var_tl = np.average(
                    (np.array(prey_tls) - mean_tl) ** 2, weights=prey_fracs
                )
                system_omni += var_tl * consump

    system_omnivory = system_omni / total_consump if total_consump > 0 else 0

    # Mean and max trophic level
    biomass = rpath.Biomass[:n_living]
    tl = rpath.TL[:n_living]

    mean_trophic_level = np.average(tl, weights=biomass) if np.sum(biomass) > 0 else 0
    max_trophic_level = np.max(tl) if len(tl) > 0 else 0

    # Total biomass and throughput
    total_biomass = np.sum(rpath.Biomass[:n_total])

    # Throughput: sum of consumption + respiration + flow to detritus
    total_throughput = 0.0
    for grp in range(n_living):
        if rpath.QB[grp] > 0:
            total_throughput += rpath.QB[grp] * rpath.Biomass[grp]
        total_throughput += rpath.PB[grp] * rpath.Biomass[grp]

    # Transfer efficiency (between adjacent trophic levels)
    from pypath.core.indicators import finn_cycling_index as _finn_cycling_index
    from pypath.core.indicators import transfer_efficiency as _transfer_efficiency

    try:
        _te_array = _transfer_efficiency(rpath)
        transfer_efficiency = (
            float(np.mean(_te_array[_te_array > 0])) if np.any(_te_array > 0) else 0.0
        )
    except (AttributeError, TypeError, IndexError, ValueError) as e:
        # pypath.core.indicators still assumes 1-indexed Rpath arrays
        logger.warning("transfer_efficiency unavailable: %s", e)
        transfer_efficiency = 0.0

    # Finn Cycling Index
    try:
        finn_cycling_index = _finn_cycling_index(rpath)
    except (AttributeError, TypeError, IndexError, ValueError) as e:
        # pypath.core.indicators still assumes 1-indexed Rpath arrays
        logger.warning("finn_cycling_index unavailable: %s", e)
        finn_cycling_index = 0.0

    return NetworkIndices(
        n_groups=n_total,
        n_living=n_living,
        n_links=n_links,
        connectance=connectance,
        linkage_density=linkage_density,
        omnivory_index=omnivory_index,
        system_omnivory=system_omnivory,
        mean_trophic_level=mean_trophic_level,
        max_trophic_level=max_trophic_level,
        total_biomass=total_biomass,
        total_throughput=total_throughput,
        transfer_efficiency=transfer_efficiency,
        finn_cycling_index=finn_cycling_index,
    )

summarize_ecosim_output

summarize_ecosim_output(output: RsimOutput, scenario: Optional[RsimScenario] = None) -> EcosimSummary

Calculate summary statistics for Ecosim output.

Parameters:

Name	Type	Description	Default
output	RsimOutput	Simulation results	required
scenario	RsimScenario	Original scenario (for group names)	None

Returns:

Type	Description
EcosimSummary	Summary statistics

Source code in pypath/core/analysis.py

def summarize_ecosim_output(
    output: RsimOutput, scenario: Optional[RsimScenario] = None
) -> EcosimSummary:
    """Calculate summary statistics for Ecosim output.

    Parameters
    ----------
    output : RsimOutput
        Simulation results
    scenario : RsimScenario, optional
        Original scenario (for group names)

    Returns
    -------
    EcosimSummary
        Summary statistics
    """
    biomass = output.out_Biomass_annual
    catch = output.out_Catch_annual

    n_years, n_groups = biomass.shape

    # Get group names
    if scenario is not None:
        group_names = scenario.params.spname[1:n_groups]
    else:
        group_names = [f"Group_{i}" for i in range(1, n_groups)]

    # Biomass statistics
    biomass_start = biomass[0, :]
    biomass_end = biomass[-1, :]
    biomass_min = np.min(biomass, axis=0)
    biomass_max = np.max(biomass, axis=0)
    biomass_mean = np.mean(biomass, axis=0)
    biomass_std = np.std(biomass, axis=0)

    # Coefficient of variation — safe division to avoid RuntimeWarning on zeros
    biomass_cv = np.divide(
        biomass_std,
        biomass_mean,
        out=np.zeros_like(biomass_std),
        where=biomass_mean > 0,
    )

    # Relative change — safe division
    biomass_change = np.divide(
        biomass_end,
        biomass_start,
        out=np.zeros_like(biomass_end),
        where=biomass_start > 0,
    )
    biomass_change = np.where(biomass_start > 0, biomass_change - 1, 0)

    # Catch statistics
    total_catch = np.sum(catch, axis=0)
    mean_annual_catch = np.mean(catch, axis=0)
    catch_std = np.std(catch, axis=0)
    catch_cv = np.divide(
        catch_std,
        mean_annual_catch,
        out=np.zeros_like(catch_std),
        where=mean_annual_catch > 0,
    )

    return EcosimSummary(
        group_names=list(group_names),
        years=n_years,
        biomass_start=biomass_start,
        biomass_end=biomass_end,
        biomass_min=biomass_min,
        biomass_max=biomass_max,
        biomass_mean=biomass_mean,
        biomass_cv=biomass_cv,
        biomass_change=biomass_change,
        total_catch=total_catch,
        mean_annual_catch=mean_annual_catch,
        catch_cv=catch_cv,
    )

compare_scenarios

compare_scenarios(outputs: List[RsimOutput], names: List[str], groups: Optional[List[int]] = None) -> pd.DataFrame

Compare multiple Ecosim scenarios.

Parameters:

Name	Type	Description	Default
outputs	list of RsimOutput	Simulation results to compare	required
names	list of str	Names for each scenario	required
groups	list of int	Group indices to compare (default: all living groups)	None

Returns:

Type	Description
DataFrame	Comparison table with biomass changes per scenario

Source code in pypath/core/analysis.py

def compare_scenarios(
    outputs: List[RsimOutput], names: List[str], groups: Optional[List[int]] = None
) -> pd.DataFrame:
    """Compare multiple Ecosim scenarios.

    Parameters
    ----------
    outputs : list of RsimOutput
        Simulation results to compare
    names : list of str
        Names for each scenario
    groups : list of int, optional
        Group indices to compare (default: all living groups)

    Returns
    -------
    pd.DataFrame
        Comparison table with biomass changes per scenario
    """
    if len(outputs) != len(names):
        raise ValueError("Number of outputs must match number of names")

    n_groups = outputs[0].out_Biomass_annual.shape[1]

    if groups is None:
        groups = list(range(1, n_groups))

    # Build comparison DataFrame
    data = {"Group": [f"Group_{g}" for g in groups]}

    for output, name in zip(outputs, names):
        start = output.out_Biomass_annual[0, groups]
        end = output.out_Biomass_annual[-1, groups]
        change = np.where(start > 0, (end / start - 1) * 100, 0)
        data[f"{name}_pct_change"] = change
        data[f"{name}_final_bio"] = end

    return pd.DataFrame(data)

check_ecopath_balance

check_ecopath_balance(rpath: Rpath, tolerance: float = 0.01) -> Dict[str, Any]

Check Ecopath model balance.

Verifies that the model satisfies mass-balance constraints: - EE <= 1 for all groups - Consumption = Production + Respiration + Unassimilated for consumers - Diet compositions sum to 1

Parameters:

Name	Type	Description	Default
rpath	Rpath	Balanced model to check	required
tolerance	float	Acceptable deviation from balance	0.01

Returns:

Type	Description
dict	Diagnostics including: - is_balanced: bool - ee_issues: list of groups with EE > 1 - diet_issues: list of groups with diet sum != 1 - messages: list of diagnostic messages

Source code in pypath/core/analysis.py

def check_ecopath_balance(rpath: Rpath, tolerance: float = 0.01) -> Dict[str, Any]:
    """Check Ecopath model balance.

    Verifies that the model satisfies mass-balance constraints:
    - EE <= 1 for all groups
    - Consumption = Production + Respiration + Unassimilated for consumers
    - Diet compositions sum to 1

    Parameters
    ----------
    rpath : Rpath
        Balanced model to check
    tolerance : float
        Acceptable deviation from balance

    Returns
    -------
    dict
        Diagnostics including:
        - is_balanced: bool
        - ee_issues: list of groups with EE > 1
        - diet_issues: list of groups with diet sum != 1
        - messages: list of diagnostic messages
    """
    results = {
        "is_balanced": True,
        "ee_issues": [],
        "diet_issues": [],
        "balance_issues": [],
        "messages": [],
    }

    def _name(i: int) -> str:
        try:
            return str(rpath.Group[i])
        except (AttributeError, IndexError, TypeError):
            return f"Group {i}"

    # Check EE (Rpath arrays are 0-indexed)
    for i in range(rpath.NUM_LIVING):
        if rpath.EE[i] > 1.0 + tolerance:
            results["ee_issues"].append(i)
            results["is_balanced"] = False
            results["messages"].append(f"{_name(i)}: EE = {rpath.EE[i]:.4f} > 1")

    # Check diet sums (all prey rows incl. import for each living predator)
    for pred in range(rpath.NUM_LIVING):
        if rpath.QB[pred] > 0:  # Is a consumer
            diet_sum = np.sum(rpath.DC[:, pred])
            if abs(diet_sum - 1.0) > tolerance:
                results["diet_issues"].append(pred)
                results["messages"].append(
                    f"{_name(pred)}: Diet sum = {diet_sum:.4f} != 1"
                )

    # Check production/consumption balance
    for i in range(rpath.NUM_LIVING):
        if rpath.QB[i] > 0:
            _consumption = rpath.QB[i] * rpath.Biomass[i]
            _production = rpath.PB[i] * rpath.Biomass[i]

            # GE = P/Q should be reasonable (0 < GE < 1)
            ge = rpath.PB[i] / rpath.QB[i] if rpath.QB[i] > 0 else 0
            if ge > 1.0 + tolerance or ge < 0:
                results["balance_issues"].append(i)
                results["messages"].append(f"{_name(i)}: GE = {ge:.4f} (should be 0-1)")

    if not results["messages"]:
        results["messages"].append("Model is properly balanced")

    return results

check_ecosim_stability

check_ecosim_stability(scenario: RsimScenario, burn_years: int = 10) -> Dict[str, Any]

Check Ecosim scenario stability.

Runs a short burn-in simulation to verify the model reaches equilibrium.

Parameters:

Name	Type	Description	Default
scenario	RsimScenario	Scenario to check	required
burn_years	int	Years to run for stability check	10

Returns:

Type	Description
dict	Stability diagnostics including: - is_stable: bool - crashed_groups: list of groups that crashed - unstable_groups: list of groups with > 50% change - messages: list of diagnostic messages

Source code in pypath/core/analysis.py

def check_ecosim_stability(
    scenario: RsimScenario, burn_years: int = 10
) -> Dict[str, Any]:
    """Check Ecosim scenario stability.

    Runs a short burn-in simulation to verify the model
    reaches equilibrium.

    Parameters
    ----------
    scenario : RsimScenario
        Scenario to check
    burn_years : int
        Years to run for stability check

    Returns
    -------
    dict
        Stability diagnostics including:
        - is_stable: bool
        - crashed_groups: list of groups that crashed
        - unstable_groups: list of groups with > 50% change
        - messages: list of diagnostic messages
    """
    # Run short simulation
    # Create a modified scenario for burn-in
    import copy

    from pypath.core.ecosim import rsim_run

    burn_scenario = copy.deepcopy(scenario)

    # Run simulation
    output = rsim_run(burn_scenario, method="RK4")

    results = {
        "is_stable": True,
        "crashed_groups": [],
        "unstable_groups": [],
        "messages": [],
    }

    biomass = output.out_Biomass_annual
    n_groups = biomass.shape[1]

    for i in range(1, n_groups):
        start_bio = biomass[0, i]
        end_bio = biomass[-1, i]

        if start_bio > 0:
            # Check for crash
            if end_bio < 1e-6:
                results["crashed_groups"].append(i)
                results["is_stable"] = False
                results["messages"].append(f"Group {i}: Crashed to near zero")

            # Check for instability (> 50% change)
            change = abs(end_bio / start_bio - 1)
            if change > 0.5:
                results["unstable_groups"].append(i)
                results["messages"].append(
                    f"Group {i}: {change * 100:.1f}% change during burn-in"
                )

    if not results["messages"]:
        results["messages"].append("Model is stable at equilibrium")

    return results

export_ecopath_to_dataframe

export_ecopath_to_dataframe(rpath: Rpath) -> Dict[str, pd.DataFrame]

Export Ecopath model to DataFrames.

Parameters:

Name	Type	Description	Default
rpath	Rpath	Balanced model	required

Returns:

Type	Description
dict	Dictionary of DataFrames: - 'groups': Group parameters - 'diet': Diet composition matrix - 'flows': Flow matrix

Source code in pypath/core/analysis.py

def export_ecopath_to_dataframe(rpath: Rpath) -> Dict[str, pd.DataFrame]:
    """Export Ecopath model to DataFrames.

    Parameters
    ----------
    rpath : Rpath
        Balanced model

    Returns
    -------
    dict
        Dictionary of DataFrames:
        - 'groups': Group parameters
        - 'diet': Diet composition matrix
        - 'flows': Flow matrix
    """
    n_groups = rpath.NUM_LIVING + rpath.NUM_DEAD

    # Groups DataFrame
    names = [str(g) for g in rpath.Group[:n_groups]]
    groups_data = {
        "Group": names,
        "Type": ["Living"] * rpath.NUM_LIVING + ["Detritus"] * rpath.NUM_DEAD,
        "TL": rpath.TL[:n_groups],
        "Biomass": rpath.Biomass[:n_groups],
        "PB": rpath.PB[:n_groups],
        "QB": rpath.QB[:n_groups],
        "EE": rpath.EE[:n_groups],
    }
    groups_df = pd.DataFrame(groups_data)

    # Diet matrix (rows = prey, columns = living predators)
    diet_df = pd.DataFrame(
        rpath.DC[:n_groups, : rpath.NUM_LIVING],
        index=names,
        columns=names[: rpath.NUM_LIVING],
    )

    # Simplified flows
    flows_data = []
    for pred in range(rpath.NUM_LIVING):
        for prey in range(n_groups):
            if rpath.DC[prey, pred] > 0:
                flow = rpath.DC[prey, pred] * rpath.QB[pred] * rpath.Biomass[pred]
                flows_data.append(
                    {
                        "From": names[prey],
                        "To": names[pred],
                        "Diet_Fraction": rpath.DC[prey, pred],
                        "Flow": flow,
                    }
                )

    flows_df = pd.DataFrame(flows_data)

    return {"groups": groups_df, "diet": diet_df, "flows": flows_df}

export_ecosim_to_dataframe

export_ecosim_to_dataframe(output: RsimOutput, scenario: Optional[RsimScenario] = None) -> Dict[str, pd.DataFrame]

Export Ecosim results to DataFrames.

Parameters:

Name	Type	Description	Default
output	RsimOutput	Simulation results	required
scenario	RsimScenario	Original scenario for metadata	None

Returns:

Type	Description
dict	Dictionary of DataFrames: - 'biomass_annual': Annual biomass - 'catch_annual': Annual catch - 'biomass_monthly': Monthly biomass (if available)

Source code in pypath/core/analysis.py

def export_ecosim_to_dataframe(
    output: RsimOutput, scenario: Optional[RsimScenario] = None
) -> Dict[str, pd.DataFrame]:
    """Export Ecosim results to DataFrames.

    Parameters
    ----------
    output : RsimOutput
        Simulation results
    scenario : RsimScenario, optional
        Original scenario for metadata

    Returns
    -------
    dict
        Dictionary of DataFrames:
        - 'biomass_annual': Annual biomass
        - 'catch_annual': Annual catch
        - 'biomass_monthly': Monthly biomass (if available)
    """
    n_years, n_groups = output.out_Biomass_annual.shape

    # Get group names
    if scenario is not None:
        names = scenario.params.spname[1:n_groups]
    else:
        names = [f"Group_{i}" for i in range(1, n_groups)]

    # Annual biomass
    biomass_df = pd.DataFrame(
        output.out_Biomass_annual[:, 1:], columns=names, index=range(1, n_years + 1)
    )
    biomass_df.index.name = "Year"

    # Annual catch
    catch_df = pd.DataFrame(
        output.out_Catch_annual[:, 1:], columns=names, index=range(1, n_years + 1)
    )
    catch_df.index.name = "Year"

    results = {"biomass_annual": biomass_df, "catch_annual": catch_df}

    # Monthly data if available
    if hasattr(output, "out_Biomass") and output.out_Biomass is not None:
        n_months = output.out_Biomass.shape[0]
        biomass_monthly = pd.DataFrame(
            output.out_Biomass[:, 1:], columns=names, index=range(n_months)
        )
        biomass_monthly.index.name = "Month"
        results["biomass_monthly"] = biomass_monthly

    return results

Autofix (Stability Diagnostics)

Automatic parameter diagnostics and repair routines to prevent Ecosim simulation crashes and improve model stability.

Key functions:

• diagnose_crash_causes() — identify critical issues (EE > 1, incomplete diets) and warnings (low biomass, high vulnerability, extreme QQ)
• autofix_parameters() — automatically cap vulnerabilities, enforce minimum biomass, reduce extreme density dependence
• validate_and_fix_scenario() — combined validation and repair in one step
• AutofixResult — dataclass with applied fixes and diagnostic info

See the Autofix Guide for practical usage.

pypath.core.autofix

Automatic parameter calibration and fixing for Ecosim stability.

This module provides diagnostic and automatic fixing routines to prevent simulation crashes and improve model stability.

AutofixResult dataclass

Results from automatic parameter fixing.

Attributes:

Name	Type	Description
success	bool	Whether fixes were successful
fixes_applied	list	List of fixes that were applied
warnings	list	List of warnings about potential issues
original_params	dict	Original parameter values before fixing

Source code in pypath/core/autofix.py

@dataclass
class AutofixResult:
    """Results from automatic parameter fixing.

    Attributes
    ----------
    success : bool
        Whether fixes were successful
    fixes_applied : list
        List of fixes that were applied
    warnings : list
        List of warnings about potential issues
    original_params : dict
        Original parameter values before fixing
    """

    success: bool
    fixes_applied: list
    warnings: list
    original_params: dict

diagnose_crash_causes

diagnose_crash_causes(rpath: Rpath, params: RsimParams) -> Dict[str, Any]

Diagnose potential causes of simulation crashes.

Parameters:

Name	Type	Description	Default
rpath	Rpath	Balanced Ecopath model	required
params	RsimParams	Ecosim parameters	required

Returns:

Type	Description
dict	Diagnostic results with issues and recommendations

Source code in pypath/core/autofix.py

def diagnose_crash_causes(
    rpath: Rpath,
    params: RsimParams,
) -> Dict[str, Any]:
    """Diagnose potential causes of simulation crashes.

    Parameters
    ----------
    rpath : Rpath
        Balanced Ecopath model
    params : RsimParams
        Ecosim parameters

    Returns
    -------
    dict
        Diagnostic results with issues and recommendations
    """
    issues = {"critical": [], "warnings": [], "recommendations": []}

    # 1. Check for EE > 1 (overfishing/overconsumption)
    for i in range(1, rpath.NUM_LIVING + 1):
        if rpath.EE[i] > 1.0:
            issues["critical"].append(
                {
                    "type": "ee_too_high",
                    "group": i,
                    "value": rpath.EE[i],
                    "message": f"Group {i} ({rpath.Group[i]}): EE = {rpath.EE[i]:.3f} > 1.0",
                    "fix": "Reduce fishing mortality or consumption by predators",
                }
            )

    # 2. Check for very low initial biomass
    for i in range(1, rpath.NUM_LIVING + 1):
        if params.B_BaseRef[i] < 0.001:
            issues["warnings"].append(
                {
                    "type": "low_biomass",
                    "group": i,
                    "value": params.B_BaseRef[i],
                    "message": f"Group {i} ({rpath.Group[i]}): Very low biomass = {params.B_BaseRef[i]:.6f}",
                    "fix": "Increase initial biomass or remove group",
                }
            )

    # 3. Check for very high vulnerability (VV >> 2) - vectorized
    high_vv_mask = params.VV > MAX_VULNERABILITY_SAFE
    high_vv_indices = np.where(high_vv_mask)[0]
    for i in high_vv_indices:
        prey_idx = params.PreyFrom[i]
        pred_idx = params.PreyTo[i]
        issues["warnings"].append(
            {
                "type": "high_vulnerability",
                "link": i,
                "prey": prey_idx,
                "predator": pred_idx,
                "value": params.VV[i],
                "message": f"Link {i}: VV = {params.VV[i]:.2f} (very high vulnerability)",
                "fix": "Reduce vulnerability to prevent rapid depletion",
            }
        )

    # 4. Check for unrealistic QB/PB ratios - vectorized
    living_indices = np.arange(1, rpath.NUM_LIVING + 1)
    qb = np.array(rpath.QB[1 : rpath.NUM_LIVING + 1])
    pb = np.array(rpath.PB[1 : rpath.NUM_LIVING + 1])

    # Only check where both QB and PB are positive
    valid_mask = (qb > 0) & (pb > 0)
    qb_pb_ratio = np.divide(qb, pb, where=valid_mask, out=np.zeros_like(qb))

    # GE = PB/QB should be between 0.05 and 0.5 for most consumers
    unrealistic_mask = valid_mask & (
        (qb_pb_ratio < MIN_QB_PB_RATIO) | (qb_pb_ratio > MAX_QB_PB_RATIO)
    )
    unrealistic_indices = living_indices[unrealistic_mask]

    for idx, i in enumerate(unrealistic_indices):
        ratio = qb_pb_ratio[i - 1]  # Adjust index for 0-based array
        issues["warnings"].append(
            {
                "type": "unrealistic_qb_pb",
                "group": i,
                "qb": rpath.QB[i],
                "pb": rpath.PB[i],
                "ratio": ratio,
                "message": f"Group {i} ({rpath.Group[i]}): QB/PB = {ratio:.2f} (unusual)",
                "fix": "Check QB and PB values - GE should be 0.05-0.5",
            }
        )

    # 5. Check for very high QQ (density-dependent catchability) - vectorized
    high_qq_mask = params.QQ > MAX_QQ_SAFE
    high_qq_indices = np.where(high_qq_mask)[0]
    for i in high_qq_indices:
        prey_idx = params.PreyFrom[i]
        pred_idx = params.PreyTo[i]
        issues["recommendations"].append(
            {
                "type": "high_qq",
                "link": i,
                "value": params.QQ[i],
                "message": f"Link {i}: QQ = {params.QQ[i]:.2f} (strong density dependence)",
                "fix": "Consider reducing QQ to avoid rapid crashes",
            }
        )

    # 6. Check for missing prey (predator with no food) - vectorized
    # Identify consumers (QB > 0)
    consumer_mask = np.array([rpath.QB[i] > 0 for i in range(1, rpath.NUM_LIVING + 1)])
    consumer_indices = np.arange(1, rpath.NUM_LIVING + 1)[consumer_mask]

    # Calculate diet totals for all consumers at once
    for pred in consumer_indices:
        # Sum diet proportions (only living groups can be prey in DC)
        total_diet = np.sum(rpath.DC[pred, : rpath.NUM_LIVING])

        if total_diet < DIET_SUM_THRESHOLD:  # Diet should sum to ~1
            issues["critical"].append(
                {
                    "type": "incomplete_diet",
                    "group": pred,
                    "diet_sum": total_diet,
                    "message": f"Group {pred} ({rpath.Group[pred]}): Diet sums to {total_diet:.3f} < 1.0",
                    "fix": "Complete diet composition or add import",
                }
            )

    return issues

autofix_parameters

autofix_parameters(rpath: Rpath, params: RsimParams, aggressive: bool = False) -> Tuple[RsimParams, AutofixResult]

Automatically fix parameters to improve stability.

Parameters:

Name	Type	Description	Default
rpath	Rpath	Balanced Ecopath model	required
params	RsimParams	Ecosim parameters to fix	required
aggressive	bool	If True, apply more aggressive fixes	False

Returns:

Type	Description
RsimParams	Fixed parameters
AutofixResult	Summary of fixes applied

Source code in pypath/core/autofix.py

def autofix_parameters(
    rpath: Rpath, params: RsimParams, aggressive: bool = False
) -> Tuple[RsimParams, AutofixResult]:
    """Automatically fix parameters to improve stability.

    Parameters
    ----------
    rpath : Rpath
        Balanced Ecopath model
    params : RsimParams
        Ecosim parameters to fix
    aggressive : bool
        If True, apply more aggressive fixes

    Returns
    -------
    RsimParams
        Fixed parameters
    AutofixResult
        Summary of fixes applied
    """
    fixes_applied = []
    warnings = []
    original = {}

    # Make a copy to modify
    import copy

    fixed_params = copy.deepcopy(params)

    # Fix 1: Cap vulnerability at reasonable values
    max_vv = 5.0 if not aggressive else 3.0
    for i in range(len(fixed_params.VV)):
        if fixed_params.VV[i] > max_vv:
            original[f"VV_{i}"] = fixed_params.VV[i]
            fixed_params.VV[i] = max_vv
            fixes_applied.append(
                f"Capped VV[{i}] from {original[f'VV_{i}']:.2f} to {max_vv}"
            )

    # Fix 2: Ensure minimum biomass
    for i in range(1, rpath.NUM_LIVING + 1):
        if (
            fixed_params.B_BaseRef[i] < MIN_BIOMASS_VIABLE
            and fixed_params.B_BaseRef[i] > 0
        ):
            original[f"B_{i}"] = fixed_params.B_BaseRef[i]
            fixed_params.B_BaseRef[i] = MIN_BIOMASS_VIABLE
            fixes_applied.append(
                f"Increased B[{i}] from {original[f'B_{i}']:.6f} to {MIN_BIOMASS_VIABLE}"
            )

    # Fix 3: Reduce QQ for very strong density dependence
    max_qq = 3.0 if not aggressive else 2.0
    for i in range(len(fixed_params.QQ)):
        if fixed_params.QQ[i] > max_qq:
            original[f"QQ_{i}"] = fixed_params.QQ[i]
            fixed_params.QQ[i] = max_qq
            fixes_applied.append(
                f"Capped QQ[{i}] from {original[f'QQ_{i}']:.2f} to {max_qq}"
            )

    # Fix 4: Adjust DD (prey switching) for extreme values
    for i in range(len(fixed_params.DD)):
        if fixed_params.DD[i] > MAX_PREY_SWITCHING_POWER:
            original[f"DD_{i}"] = fixed_params.DD[i]
            fixed_params.DD[i] = (
                DEFAULT_PREY_SWITCHING_POWER  # More moderate prey switching
            )
            fixes_applied.append(
                f"Reduced DD[{i}] from {original[f'DD_{i}']:.2f} to {DEFAULT_PREY_SWITCHING_POWER}"
            )
        elif fixed_params.DD[i] < MIN_PREY_SWITCHING_POWER:
            original[f"DD_{i}"] = fixed_params.DD[i]
            fixed_params.DD[i] = 1.0
            fixes_applied.append(
                f"Increased DD[{i}] from {original[f'DD_{i}']:.2f} to 1.0"
            )

    # Fix 5: Warn about EE > 1 (can't fix in Ecosim params)
    for i in range(1, rpath.NUM_LIVING + 1):
        if rpath.EE[i] > 1.0:
            warnings.append(
                f"Group {i} ({rpath.Group[i]}): EE = {rpath.EE[i]:.3f} > 1.0 "
                "(requires Ecopath rebalancing)"
            )

    result = AutofixResult(
        success=len(warnings) == 0,
        fixes_applied=fixes_applied,
        warnings=warnings,
        original_params=original,
    )

    return fixed_params, result

validate_and_fix_scenario

validate_and_fix_scenario(scenario: RsimScenario, rpath: Rpath, auto_fix: bool = True, verbose: bool = True) -> Tuple[RsimScenario, Dict[str, Any]]

Validate scenario and optionally apply automatic fixes.

Parameters:

Name	Type	Description	Default
scenario	RsimScenario	Ecosim scenario to validate	required
rpath	Rpath	Original Ecopath model	required
auto_fix	bool	Whether to automatically fix parameters	True
verbose	bool	Whether to print diagnostic messages	True

Returns:

Type	Description
RsimScenario	Validated (and potentially fixed) scenario
dict	Diagnostic report

Source code in pypath/core/autofix.py

def validate_and_fix_scenario(
    scenario: RsimScenario, rpath: Rpath, auto_fix: bool = True, verbose: bool = True
) -> Tuple[RsimScenario, Dict[str, Any]]:
    """Validate scenario and optionally apply automatic fixes.

    Parameters
    ----------
    scenario : RsimScenario
        Ecosim scenario to validate
    rpath : Rpath
        Original Ecopath model
    auto_fix : bool
        Whether to automatically fix parameters
    verbose : bool
        Whether to print diagnostic messages

    Returns
    -------
    RsimScenario
        Validated (and potentially fixed) scenario
    dict
        Diagnostic report
    """
    report = {"valid": True, "issues": [], "fixes": [], "warnings": []}

    # Diagnose issues
    diagnosis = diagnose_crash_causes(rpath, scenario.params)

    # Check for critical issues
    if diagnosis["critical"]:
        report["valid"] = False
        report["issues"] = diagnosis["critical"]

        if verbose:
            logger.warning("=" * 70)
            logger.warning("CRITICAL ISSUES DETECTED")
            logger.warning("=" * 70)
            for issue in diagnosis["critical"]:
                logger.warning(f"  • {issue['message']}")
                logger.warning(f"    Fix: {issue['fix']}")

    # Apply automatic fixes if requested
    if auto_fix and (diagnosis["critical"] or diagnosis["warnings"]):
        if verbose:
            logger.info("=" * 70)
            logger.info("APPLYING AUTOMATIC FIXES")
            logger.info("=" * 70)

        fixed_params, fix_result = autofix_parameters(rpath, scenario.params)

        if fix_result.fixes_applied:
            scenario.params = fixed_params
            report["fixes"] = fix_result.fixes_applied
            report["valid"] = fix_result.success

            if verbose:
                for fix in fix_result.fixes_applied:
                    logger.info(f"  ✓ {fix}")

        if fix_result.warnings:
            report["warnings"] = fix_result.warnings
            if verbose:
                logger.warning("WARNINGS:")
                for warning in fix_result.warnings:
                    logger.warning(f"  ⚠ {warning}")

    # Log recommendations
    if verbose and diagnosis["recommendations"]:
        logger.info("=" * 70)
        logger.info("RECOMMENDATIONS")
        logger.info("=" * 70)
        for rec in diagnosis["recommendations"]:
            logger.info(f"  • {rec['message']}")

    if verbose:
        logger.info("=" * 70)
        if report["valid"]:
            logger.info("VALIDATION: PASSED ✓")
        else:
            logger.warning("VALIDATION: FAILED - Manual fixes required")
        logger.info("=" * 70)

    return scenario, report

Sparse Link Array

Compressed prey-predator link lists for efficient consumption kernel computation in sparse food webs.

pypath.core.link_array

Compressed link-list for sparse food webs.

Pre-computes arrays of active prey-predator link indices so that the consumption kernel can iterate only over active links instead of the full (NUM_GROUPS+1) x (NUM_GROUPS+1) matrix. For a 50-group model with 70% sparsity this eliminates 70% of iterations.

ActiveLinkArray dataclass

Pre-computed arrays of active prey-predator link indices.

Attributes:

Name	Type	Description
prey	ndarray	1-D int64 array of prey indices for each active link.
pred	ndarray	1-D int64 array of predator indices for each active link.
n_links	int	Number of active links.

Source code in pypath/core/link_array.py

@dataclass
class ActiveLinkArray:
    """Pre-computed arrays of active prey-predator link indices.

    Attributes
    ----------
    prey : np.ndarray
        1-D int64 array of prey indices for each active link.
    pred : np.ndarray
        1-D int64 array of predator indices for each active link.
    n_links : int
        Number of active links.
    """

    prey: np.ndarray  # int64 shape (n_links,)
    pred: np.ndarray  # int64 shape (n_links,)
    n_links: int

    @classmethod
    def from_bool_matrix(cls, active: np.ndarray) -> "ActiveLinkArray":
        """Build an ActiveLinkArray from a boolean (or int) ActiveLink matrix.

        Parameters
        ----------
        active : np.ndarray
            Boolean or integer matrix of shape (N, N) where ``active[prey, pred]``
            is truthy when the link is active.

        Returns
        -------
        ActiveLinkArray
            Compressed representation containing only the active links.
        """
        prey, pred = np.nonzero(active)
        return cls(
            prey=prey.astype(np.int64),
            pred=pred.astype(np.int64),
            n_links=len(prey),
        )

from_bool_matrix classmethod

from_bool_matrix(active: ndarray) -> ActiveLinkArray

Build an ActiveLinkArray from a boolean (or int) ActiveLink matrix.

Parameters:

Name	Type	Description	Default
active	ndarray	Boolean or integer matrix of shape (N, N) where active[prey, pred] is truthy when the link is active.	required

Returns:

Type	Description
ActiveLinkArray	Compressed representation containing only the active links.

Source code in pypath/core/link_array.py

@classmethod
def from_bool_matrix(cls, active: np.ndarray) -> "ActiveLinkArray":
    """Build an ActiveLinkArray from a boolean (or int) ActiveLink matrix.

    Parameters
    ----------
    active : np.ndarray
        Boolean or integer matrix of shape (N, N) where ``active[prey, pred]``
        is truthy when the link is active.

    Returns
    -------
    ActiveLinkArray
        Compressed representation containing only the active links.
    """
    prey, pred = np.nonzero(active)
    return cls(
        prey=prey.astype(np.int64),
        pred=pred.astype(np.int64),
        n_links=len(prey),
    )

Constants

Physical and biological constants used throughout PyPath.

pypath.core.constants

Physical and biological constants for ecosystem modeling.

This module centralizes magic numbers and constants used throughout PyPath, improving maintainability and reducing errors from scattered hard-coded values.

Time Series & Calibration

Time series data structures for observed data and calibration against EwE reference series.

pypath.core.timeseries

EwE time series data structures and driver application.

Provides data classes for observed and forced time series used in Ecosim calibration and scenario forcing.

EweTimeSeries dataclass

A single EwE time series.

Parameters:

Name	Type	Description	Default
series_id	int	Unique identifier for this series.	required
name	str	Human-readable name (e.g. "Cod biomass").	required
dat_type	int	DatType constant indicating the series type.	required
group_idx	int or None	0-based group index, or None for fleet-level series. Note: this differs from EcosimOptimizer which uses 1-based indices.	required
fleet_idx	int or None	0-based fleet index, or None for group-level series.	required
values	ndarray	Time series values, shape (n_timesteps,). NaN for missing.	required
weight	float	Weighting factor for SS objective (default 1.0).	1.0
dataset_id	int	Dataset grouping identifier (default 0).	0

Source code in pypath/core/timeseries.py

@dataclass
class EweTimeSeries:
    """A single EwE time series.

    Parameters
    ----------
    series_id : int
        Unique identifier for this series.
    name : str
        Human-readable name (e.g. "Cod biomass").
    dat_type : int
        DatType constant indicating the series type.
    group_idx : int or None
        **0-based** group index, or None for fleet-level series.
        Note: this differs from EcosimOptimizer which uses 1-based indices.
    fleet_idx : int or None
        **0-based** fleet index, or None for group-level series.
    values : np.ndarray
        Time series values, shape (n_timesteps,). NaN for missing.
    weight : float
        Weighting factor for SS objective (default 1.0).
    dataset_id : int
        Dataset grouping identifier (default 0).
    """

    series_id: int
    name: str
    dat_type: int
    group_idx: int | None
    fleet_idx: int | None
    values: np.ndarray
    weight: float = 1.0
    dataset_id: int = 0

EweTimeSeriesCollection dataclass

Container for multiple EwE time series with filtered views.

On construction, all series are NaN-padded to the length of the longest series, and n_timesteps is set to that uniform length.

Parameters:

Name	Type	Description	Default
series	list[EweTimeSeries]	List of time series to include.	list()

Source code in pypath/core/timeseries.py

@dataclass
class EweTimeSeriesCollection:
    """Container for multiple EwE time series with filtered views.

    On construction, all series are NaN-padded to the length of the longest
    series, and ``n_timesteps`` is set to that uniform length.

    Parameters
    ----------
    series : list[EweTimeSeries]
        List of time series to include.
    """

    series: list[EweTimeSeries] = field(default_factory=list)
    n_timesteps: int = field(init=False, default=0)

    def __post_init__(self) -> None:
        if not self.series:
            self.n_timesteps = 0
            return
        max_len = max(len(s.values) for s in self.series)
        self.n_timesteps = max_len
        for s in self.series:
            if len(s.values) < max_len:
                padded = np.full(max_len, np.nan)
                padded[: len(s.values)] = s.values
                s.values = padded

    @property
    def observed_biomass(self) -> list[EweTimeSeries]:
        """Series with dat_type in {0 (relative), 1 (absolute)}."""
        return [
            s
            for s in self.series
            if s.dat_type in (DATTYPE_REL_BIOMASS, DATTYPE_ABS_BIOMASS)
        ]

    @property
    def observed_catch(self) -> list[EweTimeSeries]:
        """Series with dat_type == 6 (catch)."""
        return [s for s in self.series if s.dat_type == DATTYPE_CATCH]

    @property
    def forced_biomass(self) -> list[EweTimeSeries]:
        """Series with dat_type == -1 (forced biomass)."""
        return [s for s in self.series if s.dat_type == DATTYPE_FORCED_BIOMASS]

    @property
    def forced_effort(self) -> list[EweTimeSeries]:
        """Series with dat_type == 3 (effort)."""
        return [s for s in self.series if s.dat_type == DATTYPE_EFFORT]

    def to_observed_dict(self, n_timesteps: int) -> dict[int, np.ndarray]:
        """Convert observed biomass series to {group_idx: array} dict.

        Arrays are padded with NaN or truncated to ``n_timesteps``.
        Compatible with EcosimOptimizer's observed_data format (note:
        EcosimOptimizer uses 1-based group indices; this returns 0-based).
        """
        result: dict[int, np.ndarray] = {}
        for s in self.observed_biomass:
            if s.group_idx is None:
                continue
            vals = s.values
            if len(vals) >= n_timesteps:
                result[s.group_idx] = vals[:n_timesteps].copy()
            else:
                padded = np.full(n_timesteps, np.nan)
                padded[: len(vals)] = vals
                result[s.group_idx] = padded
        return result

    def to_dataframe(self) -> "pd.DataFrame":
        """Convert to a DataFrame in simple format (time, group, value, dat_type).

        Suitable for CSV export and round-tripping.
        """
        import pandas as pd

        rows = []
        for s in self.series:
            for t, v in enumerate(s.values):
                if not np.isnan(v):
                    rows.append(
                        {
                            "time": t + 1,
                            "group": s.group_idx
                            if s.group_idx is not None
                            else s.fleet_idx,
                            "value": v,
                            "dat_type": s.dat_type,
                        }
                    )
        return pd.DataFrame(rows)

observed_biomass property

observed_biomass: list[EweTimeSeries]

Series with dat_type in {0 (relative), 1 (absolute)}.

observed_catch property

observed_catch: list[EweTimeSeries]

Series with dat_type == 6 (catch).

forced_biomass property

forced_biomass: list[EweTimeSeries]

Series with dat_type == -1 (forced biomass).

forced_effort property

forced_effort: list[EweTimeSeries]

Series with dat_type == 3 (effort).

to_observed_dict

to_observed_dict(n_timesteps: int) -> dict[int, np.ndarray]

Convert observed biomass series to {group_idx: array} dict.

Arrays are padded with NaN or truncated to n_timesteps. Compatible with EcosimOptimizer's observed_data format (note: EcosimOptimizer uses 1-based group indices; this returns 0-based).

Source code in pypath/core/timeseries.py

def to_observed_dict(self, n_timesteps: int) -> dict[int, np.ndarray]:
    """Convert observed biomass series to {group_idx: array} dict.

    Arrays are padded with NaN or truncated to ``n_timesteps``.
    Compatible with EcosimOptimizer's observed_data format (note:
    EcosimOptimizer uses 1-based group indices; this returns 0-based).
    """
    result: dict[int, np.ndarray] = {}
    for s in self.observed_biomass:
        if s.group_idx is None:
            continue
        vals = s.values
        if len(vals) >= n_timesteps:
            result[s.group_idx] = vals[:n_timesteps].copy()
        else:
            padded = np.full(n_timesteps, np.nan)
            padded[: len(vals)] = vals
            result[s.group_idx] = padded
    return result

to_dataframe

to_dataframe() -> 'pd.DataFrame'

Convert to a DataFrame in simple format (time, group, value, dat_type).

Suitable for CSV export and round-tripping.

Source code in pypath/core/timeseries.py

def to_dataframe(self) -> "pd.DataFrame":
    """Convert to a DataFrame in simple format (time, group, value, dat_type).

    Suitable for CSV export and round-tripping.
    """
    import pandas as pd

    rows = []
    for s in self.series:
        for t, v in enumerate(s.values):
            if not np.isnan(v):
                rows.append(
                    {
                        "time": t + 1,
                        "group": s.group_idx
                        if s.group_idx is not None
                        else s.fleet_idx,
                        "value": v,
                        "dat_type": s.dat_type,
                    }
                )
    return pd.DataFrame(rows)

apply_timeseries_drivers

apply_timeseries_drivers(scenario: 'RsimScenario', collection: EweTimeSeriesCollection) -> None

Apply driver time series to an Ecosim scenario's forcing arrays.

Modifies scenario in place. Only processes driver series (forced biomass, effort, fishing mortality). Observed series are ignored.

Parameters:

Name	Type	Description	Default
scenario	RsimScenario	The Ecosim scenario to modify.	required
collection	EweTimeSeriesCollection	Time series collection containing driver series.	required

Raises:

Type	Description
ValueError	If any forced biomass values are negative (excluding NaN).

Source code in pypath/core/timeseries.py

def apply_timeseries_drivers(
    scenario: "RsimScenario",
    collection: EweTimeSeriesCollection,
) -> None:
    """Apply driver time series to an Ecosim scenario's forcing arrays.

    Modifies ``scenario`` in place. Only processes driver series
    (forced biomass, effort, fishing mortality). Observed series are ignored.

    Parameters
    ----------
    scenario : RsimScenario
        The Ecosim scenario to modify.
    collection : EweTimeSeriesCollection
        Time series collection containing driver series.

    Raises
    ------
    ValueError
        If any forced biomass values are negative (excluding NaN).
    """
    n_groups = scenario.params.NUM_GROUPS
    n_gears = scenario.params.NUM_GEARS

    for s in collection.forced_biomass:
        if s.group_idx is None:
            continue
        if s.group_idx >= n_groups:
            warnings.warn(
                f"Time series '{s.name}' references group index {s.group_idx} "
                f"but model only has {n_groups} groups. Skipping.",
                UserWarning,
                stacklevel=2,
            )
            continue
        valid_vals = s.values[~np.isnan(s.values)]
        if len(valid_vals) > 0 and np.any(valid_vals < 0):
            raise ValueError(
                f"Time series '{s.name}' contains negative forced biomass values."
            )
        col = s.group_idx + 1
        n_months = scenario.forcing.ForcedBio.shape[0]
        scenario.forcing.ForcedBio[:, col] = _interpolate_to_length(s.values, n_months)

    for s in collection.forced_effort:
        if s.fleet_idx is None:
            continue
        if s.fleet_idx >= n_gears:
            warnings.warn(
                f"Time series '{s.name}' references fleet index {s.fleet_idx} "
                f"but model only has {n_gears} fleets. Skipping.",
                UserWarning,
                stacklevel=2,
            )
            continue
        col = s.fleet_idx + 1
        n_months = scenario.fishing.ForcedEffort.shape[0]
        scenario.fishing.ForcedEffort[:, col] = _interpolate_to_length(
            s.values, n_months
        )

    fmort_series = [
        s for s in collection.series if s.dat_type == DATTYPE_FISHING_MORTALITY
    ]
    for s in fmort_series:
        if s.group_idx is None:
            continue
        if s.group_idx >= n_groups:
            warnings.warn(
                f"Time series '{s.name}' references group index {s.group_idx} "
                f"but model only has {n_groups} groups. Skipping.",
                UserWarning,
                stacklevel=2,
            )
            continue
        col = s.group_idx + 1
        n_years = scenario.fishing.ForcedFRate.shape[0]
        scenario.fishing.ForcedFRate[:, col] = _interpolate_to_length(s.values, n_years)

load_timeseries

load_timeseries(path: str | Path) -> EweTimeSeriesCollection

Load time series from a file, dispatching by extension.

Supported extensions: - .csv -> CSV loader (simple format) - .eweaccdb, .ewemdb, .accdb -> EwE database reader

Parameters:

Name	Type	Description	Default
path	str or Path	Path to the time series file.	required

Returns:

Type	Description
EweTimeSeriesCollection

Raises:

Type	Description
ValueError	If the file extension is not recognized.

Source code in pypath/core/timeseries.py

def load_timeseries(path: str | Path) -> EweTimeSeriesCollection:
    """Load time series from a file, dispatching by extension.

    Supported extensions:
    - ``.csv`` -> CSV loader (simple format)
    - ``.eweaccdb``, ``.ewemdb``, ``.accdb`` -> EwE database reader

    Parameters
    ----------
    path : str or Path
        Path to the time series file.

    Returns
    -------
    EweTimeSeriesCollection

    Raises
    ------
    ValueError
        If the file extension is not recognized.
    """
    path = Path(path)
    ext = path.suffix.lower()
    if ext == ".csv":
        from pypath.io.timeseries_csv import load_timeseries_csv

        return load_timeseries_csv(path, format="simple")
    elif ext in (".eweaccdb", ".ewemdb", ".accdb"):
        from pypath.io.ewemdb import read_timeseries

        return read_timeseries(str(path))
    else:
        raise ValueError(
            f"Unsupported file extension '{ext}'. "
            f"Use .csv, .eweaccdb, .ewemdb, or .accdb."
        )

Calibration

Sum-of-squares fitting against reference time series.

pypath.core.calibration

Ecosim calibration via sum-of-squares fitting to time series data.

Provides fit_to_timeseries() for optimizing Ecosim vulnerability (VV) and primary production (PP) parameters against observed time series.

CalibrationResult dataclass

Result of time series calibration.

Parameters:

Name	Type	Description	Default
best_vv	ndarray	Fitted vulnerability values, one per pred-prey link.	required
best_pp	ndarray or None	Fitted primary production anomaly (if fit_pp was True).	required
ss	float	Final sum-of-squares value.	required
ss_by_group	dict[int, float]	SS contribution per group index (0-based).	required
n_iterations	int	Number of optimizer iterations performed.	required
converged	bool	Whether the optimizer converged.	required
fitted_scenario	RsimScenario or None	Scenario with best-fit parameters applied.	required
link_map	list[tuple[int, int]]	(prey_idx, pred_idx) 0-based for each entry in best_vv.	required

Source code in pypath/core/calibration.py

@dataclass
class CalibrationResult:
    """Result of time series calibration.

    Parameters
    ----------
    best_vv : np.ndarray
        Fitted vulnerability values, one per pred-prey link.
    best_pp : np.ndarray or None
        Fitted primary production anomaly (if fit_pp was True).
    ss : float
        Final sum-of-squares value.
    ss_by_group : dict[int, float]
        SS contribution per group index (0-based).
    n_iterations : int
        Number of optimizer iterations performed.
    converged : bool
        Whether the optimizer converged.
    fitted_scenario : RsimScenario or None
        Scenario with best-fit parameters applied.
    link_map : list[tuple[int, int]]
        (prey_idx, pred_idx) 0-based for each entry in best_vv.
    """

    best_vv: np.ndarray
    best_pp: np.ndarray | None
    ss: float
    ss_by_group: dict[int, float]
    n_iterations: int
    converged: bool
    fitted_scenario: RsimScenario | None
    link_map: list[tuple[int, int]]

fit_to_timeseries

fit_to_timeseries(rpath_model, params, timeseries, *, fit_vv: bool = True, fit_pp: bool = False, fit_groups: list[int] | None = None, vv_bounds: tuple = (1.0, 100.0), pp_bounds: tuple = (0.0, 2.0), method: str = 'differential_evolution', max_iterations: int = 1000, verbose: bool = False) -> CalibrationResult

Fit Ecosim parameters to observed time series data.

Parameters:

Name	Type	Description	Default
rpath_model	Rpath	Balanced Ecopath model.	required
params	RpathParams	Model parameters.	required
timeseries	EweTimeSeriesCollection or dict	Observed time series. If dict, treated as {group_idx: np.array} of relative biomass (0-based group indices).	required
fit_vv	bool	Fit vulnerability (VV) parameters (default True).	True
fit_pp	bool	Fit primary production anomaly. Not yet implemented.	False
fit_groups	list[int] or None	0-based group indices to fit. None = all groups with observed data.	None
vv_bounds	tuple	(min, max) bounds for VV parameters.	(1.0, 100.0)
pp_bounds	tuple	(min, max) bounds for PP parameters (reserved).	(0.0, 2.0)
method	str	"differential_evolution" or "minimize" (L-BFGS-B).	'differential_evolution'
max_iterations	int	Maximum optimizer iterations.	1000
verbose	bool	Print progress.	False

Returns:

Type	Description
CalibrationResult

Source code in pypath/core/calibration.py

def fit_to_timeseries(
    rpath_model,
    params,
    timeseries,
    *,
    fit_vv: bool = True,
    fit_pp: bool = False,
    fit_groups: list[int] | None = None,
    vv_bounds: tuple = (1.0, 100.0),
    pp_bounds: tuple = (0.0, 2.0),
    method: str = "differential_evolution",
    max_iterations: int = 1000,
    verbose: bool = False,
) -> CalibrationResult:
    """Fit Ecosim parameters to observed time series data.

    Parameters
    ----------
    rpath_model : Rpath
        Balanced Ecopath model.
    params : RpathParams
        Model parameters.
    timeseries : EweTimeSeriesCollection or dict
        Observed time series. If dict, treated as {group_idx: np.array}
        of relative biomass (0-based group indices).
    fit_vv : bool
        Fit vulnerability (VV) parameters (default True).
    fit_pp : bool
        Fit primary production anomaly. Not yet implemented.
    fit_groups : list[int] or None
        0-based group indices to fit. None = all groups with observed data.
    vv_bounds : tuple
        (min, max) bounds for VV parameters.
    pp_bounds : tuple
        (min, max) bounds for PP parameters (reserved).
    method : str
        "differential_evolution" or "minimize" (L-BFGS-B).
    max_iterations : int
        Maximum optimizer iterations.
    verbose : bool
        Print progress.

    Returns
    -------
    CalibrationResult
    """
    from pypath.core.ecosim import rsim_run, rsim_scenario
    from pypath.core.timeseries import (
        DATTYPE_REL_BIOMASS,
        EweTimeSeries,
        EweTimeSeriesCollection,
        apply_timeseries_drivers,
    )

    if fit_pp:
        raise NotImplementedError(
            "Primary production fitting (fit_pp=True) is not yet implemented. "
            "It will be added in a future release."
        )

    # Convert dict input to EweTimeSeriesCollection
    if isinstance(timeseries, dict):
        series_list = []
        for grp_idx, values in timeseries.items():
            series_list.append(
                EweTimeSeries(
                    series_id=grp_idx,
                    name=f"Group_{grp_idx}",
                    dat_type=DATTYPE_REL_BIOMASS,
                    group_idx=grp_idx,
                    fleet_idx=None,
                    values=values,
                )
            )
        timeseries = EweTimeSeriesCollection(series_list)

    n_obs_years = timeseries.n_timesteps
    if n_obs_years < 2:
        raise ValueError("Need at least 2 observed timesteps for calibration.")
    years = range(1, n_obs_years + 1)

    # Build base scenario
    scenario = rsim_scenario(rpath_model, params, years=years)

    # Apply driver series
    apply_timeseries_drivers(scenario, timeseries)

    # Build observed data dict
    observed: dict[int, np.ndarray] = {}
    weights: dict[int, float] = {}
    relative: dict[int, bool] = {}

    for s in timeseries.observed_biomass:
        if s.group_idx is not None:
            observed[s.group_idx] = s.values[:n_obs_years]
            weights[s.group_idx] = s.weight
            relative[s.group_idx] = s.dat_type == DATTYPE_REL_BIOMASS

    for s in timeseries.observed_catch:
        if s.group_idx is not None and s.group_idx not in observed:
            observed[s.group_idx] = s.values[:n_obs_years]
            weights[s.group_idx] = s.weight
            relative[s.group_idx] = False

    if not observed:
        raise ValueError("No observed series found in timeseries collection.")

    if fit_groups is None:
        fit_groups = list(observed.keys())

    # Build link map: PreyFrom/PreyTo are 1-based
    link_indices = []
    link_map = []
    n_links = len(scenario.params.PreyFrom)
    for i in range(1, n_links):
        prey = scenario.params.PreyFrom[i] - 1  # to 0-based
        pred = scenario.params.PreyTo[i] - 1
        if prey in fit_groups or pred in fit_groups:
            link_indices.append(i)
            link_map.append((prey, pred))

    if not link_indices and fit_vv:
        raise ValueError("No pred-prey links found for the specified fit_groups.")

    bounds = []
    if fit_vv:
        bounds.extend([vv_bounds] * len(link_indices))

    n_vv = len(link_indices) if fit_vv else 0
    iteration_count = [0]

    def objective(param_vector):
        if fit_vv:
            for j, link_idx in enumerate(link_indices):
                scenario.params.VV[link_idx] = param_vector[j]

        try:
            output = rsim_run(scenario)
        except (RuntimeError, ValueError, FloatingPointError) as e:
            logger.warning("Simulation failed during optimization: %s", e)
            return 1e10

        predicted: dict[int, np.ndarray] = {}
        n_months = output.out_Biomass.shape[0]
        months_per_year = n_months // n_obs_years if n_obs_years > 0 else 12

        for grp_idx in observed:
            col = grp_idx + 1
            if col >= output.out_Biomass.shape[1]:
                continue
            annual = np.zeros(n_obs_years)
            for yr in range(n_obs_years):
                start = yr * months_per_year
                end = min(start + months_per_year, n_months)
                if start < n_months:
                    annual[yr] = np.mean(output.out_Biomass[start:end, col])
            predicted[grp_idx] = annual

        ss, _ = _compute_ss(observed, predicted, weights, relative)

        iteration_count[0] += 1
        if verbose and iteration_count[0] % 50 == 0:
            logger.info("Iteration %d: SS = %.6f", iteration_count[0], ss)

        return ss

    if method == "differential_evolution":
        from scipy.optimize import differential_evolution

        result = differential_evolution(
            objective,
            bounds=bounds,
            maxiter=max_iterations,
            seed=42,
            tol=1e-6,
            polish=True,
        )
        best_params = result.x
        converged = result.success
        final_ss = result.fun

    elif method == "minimize":
        from scipy.optimize import minimize

        x0 = np.array([scenario.params.VV[i] for i in link_indices])
        result = minimize(
            objective,
            x0,
            method="L-BFGS-B",
            bounds=bounds,
            options={"maxiter": max_iterations},
        )
        best_params = result.x
        converged = result.success
        final_ss = result.fun

    else:
        raise ValueError(
            f"Unknown method: {method!r}. Use 'differential_evolution' or 'minimize'."
        )

    best_vv = best_params[:n_vv] if fit_vv else np.array([])

    if fit_vv:
        for j, link_idx in enumerate(link_indices):
            scenario.params.VV[link_idx] = best_vv[j]

    # Compute final SS breakdown
    try:
        output = rsim_run(scenario)
        predicted_final: dict[int, np.ndarray] = {}
        n_months = output.out_Biomass.shape[0]
        months_per_year = n_months // n_obs_years if n_obs_years > 0 else 12
        for grp_idx in observed:
            col = grp_idx + 1
            if col >= output.out_Biomass.shape[1]:
                continue
            annual = np.zeros(n_obs_years)
            for yr in range(n_obs_years):
                start = yr * months_per_year
                end = min(start + months_per_year, n_months)
                if start < n_months:
                    annual[yr] = np.mean(output.out_Biomass[start:end, col])
            predicted_final[grp_idx] = annual
        _, ss_by_group = _compute_ss(observed, predicted_final, weights, relative)
    except Exception:
        ss_by_group = {}

    return CalibrationResult(
        best_vv=best_vv,
        best_pp=None,
        ss=final_ss,
        ss_by_group=ss_by_group,
        n_iterations=iteration_count[0],
        converged=converged,
        fitted_scenario=scenario,
        link_map=link_map,
    )

Mediation Functions

Trophic mediation functions that modify predator-prey vulnerability based on the biomass of a mediating group.

pypath.core.mediation

Mediation functions for Ecosim predation modification.

Mediation allows a third species (mediator) to modify predator-prey interactions, fleet catchability, or landing proportions based on the mediator's relative biomass and a user-defined response shape.

MediationShape dataclass

A mediation response shape defined by X-Y point pairs.

Parameters:

Name	Type	Description	Default
shape_id	int	Unique identifier for this shape.	required
name	str	Human-readable name.	required
x_points	ndarray	Relative biomass values (mediator B / B_base).	required
y_points	ndarray	Corresponding multiplier values.	required

Source code in pypath/core/mediation.py

@dataclass
class MediationShape:
    """A mediation response shape defined by X-Y point pairs.

    Parameters
    ----------
    shape_id : int
        Unique identifier for this shape.
    name : str
        Human-readable name.
    x_points : np.ndarray
        Relative biomass values (mediator B / B_base).
    y_points : np.ndarray
        Corresponding multiplier values.
    """

    shape_id: int
    name: str
    x_points: np.ndarray
    y_points: np.ndarray

    def evaluate(self, relative_biomass: float) -> float:
        """Evaluate the shape at a given relative biomass via linear interpolation.

        Values outside the x_points range are clamped to the nearest endpoint.
        """
        if len(self.x_points) <= 1:
            return float(self.y_points[0]) if len(self.y_points) > 0 else 1.0
        return float(np.interp(relative_biomass, self.x_points, self.y_points))

evaluate

evaluate(relative_biomass: float) -> float

Evaluate the shape at a given relative biomass via linear interpolation.

Values outside the x_points range are clamped to the nearest endpoint.

Source code in pypath/core/mediation.py

def evaluate(self, relative_biomass: float) -> float:
    """Evaluate the shape at a given relative biomass via linear interpolation.

    Values outside the x_points range are clamped to the nearest endpoint.
    """
    if len(self.x_points) <= 1:
        return float(self.y_points[0]) if len(self.y_points) > 0 else 1.0
    return float(np.interp(relative_biomass, self.x_points, self.y_points))

MediationLink dataclass

Maps a mediation shape to a specific interaction.

Exactly one target type should be specified: - Group: prey_idx and pred_idx both set - Fleet: fleet_idx set - Landings: landing_group_idx and landing_fleet_idx both set

All indices are 0-based.

Source code in pypath/core/mediation.py

@dataclass
class MediationLink:
    """Maps a mediation shape to a specific interaction.

    Exactly one target type should be specified:
    - Group: prey_idx and pred_idx both set
    - Fleet: fleet_idx set
    - Landings: landing_group_idx and landing_fleet_idx both set

    All indices are 0-based.
    """

    shape_id: int
    mediator_idx: int
    prey_idx: int | None = None
    pred_idx: int | None = None
    fleet_idx: int | None = None
    landing_group_idx: int | None = None
    landing_fleet_idx: int | None = None
    weight: float = 1.0

MediationCollection dataclass

Container for mediation shapes and their link assignments.

Source code in pypath/core/mediation.py

@dataclass
class MediationCollection:
    """Container for mediation shapes and their link assignments."""

    shapes: list[MediationShape]
    links: list[MediationLink]

    @property
    def group_links(self) -> list[MediationLink]:
        return [
            link
            for link in self.links
            if link.prey_idx is not None and link.pred_idx is not None
        ]

    @property
    def fleet_links(self) -> list[MediationLink]:
        return [link for link in self.links if link.fleet_idx is not None]

    @property
    def landing_links(self) -> list[MediationLink]:
        return [link for link in self.links if link.landing_group_idx is not None]

    def _get_shape(self, shape_id: int) -> MediationShape | None:
        for s in self.shapes:
            if s.shape_id == shape_id:
                return s
        return None

    def compute_group_multipliers(
        self, BB: np.ndarray, Bbase: np.ndarray, ActiveLink: np.ndarray
    ) -> np.ndarray:
        """Compute 2D (n+1, n+1) multiplier matrix for group mediation.

        For each group link, evaluate the shape at BB[mediator+1]/Bbase[mediator+1]
        and set mult[prey+1, pred+1]. Multiple links on the same pair multiply together.
        """
        n_plus_1 = len(BB)
        mult = np.ones((n_plus_1, n_plus_1))
        for link in self.group_links:
            shape = self._get_shape(link.shape_id)
            if shape is None:
                continue
            med_col = link.mediator_idx + 1
            if med_col >= n_plus_1 or Bbase[med_col] == 0:
                continue
            rel_b = BB[med_col] / Bbase[med_col]
            val = shape.evaluate(rel_b) * link.weight
            prey_row = link.prey_idx + 1
            pred_col = link.pred_idx + 1
            if prey_row < n_plus_1 and pred_col < n_plus_1:
                mult[prey_row, pred_col] *= val
        return mult

    def compute_fleet_multipliers(
        self, BB: np.ndarray, Bbase: np.ndarray, n_fleets: int
    ) -> np.ndarray:
        """Compute per-fleet multiplier array.

        Each fleet link evaluates the shape at mediator relative biomass.
        Default 1.0 for unaffected fleets.
        """
        mult = np.ones(n_fleets)
        for link in self.fleet_links:
            shape = self._get_shape(link.shape_id)
            if shape is None:
                continue
            med_col = link.mediator_idx + 1
            if med_col >= len(BB) or Bbase[med_col] == 0:
                continue
            rel_b = BB[med_col] / Bbase[med_col]
            val = shape.evaluate(rel_b) * link.weight
            if link.fleet_idx is not None and link.fleet_idx < n_fleets:
                mult[link.fleet_idx] *= val
        return mult

    def compute_landing_multipliers(
        self, BB: np.ndarray, Bbase: np.ndarray, n_fleets: int, n_groups: int
    ) -> np.ndarray:
        """Compute (n_fleets, n_groups) multiplier matrix for landings.

        Default 1.0 for unaffected fleet-group combinations.
        """
        mult = np.ones((n_fleets, n_groups))
        for link in self.landing_links:
            shape = self._get_shape(link.shape_id)
            if shape is None:
                continue
            med_col = link.mediator_idx + 1
            if med_col >= len(BB) or Bbase[med_col] == 0:
                continue
            rel_b = BB[med_col] / Bbase[med_col]
            val = shape.evaluate(rel_b) * link.weight
            fi = link.landing_fleet_idx
            gi = link.landing_group_idx
            if fi is not None and gi is not None and fi < n_fleets and gi < n_groups:
                mult[fi, gi] *= val
        return mult

compute_group_multipliers

compute_group_multipliers(BB: ndarray, Bbase: ndarray, ActiveLink: ndarray) -> np.ndarray

Compute 2D (n+1, n+1) multiplier matrix for group mediation.

For each group link, evaluate the shape at BB[mediator+1]/Bbase[mediator+1] and set mult[prey+1, pred+1]. Multiple links on the same pair multiply together.

Source code in pypath/core/mediation.py

def compute_group_multipliers(
    self, BB: np.ndarray, Bbase: np.ndarray, ActiveLink: np.ndarray
) -> np.ndarray:
    """Compute 2D (n+1, n+1) multiplier matrix for group mediation.

    For each group link, evaluate the shape at BB[mediator+1]/Bbase[mediator+1]
    and set mult[prey+1, pred+1]. Multiple links on the same pair multiply together.
    """
    n_plus_1 = len(BB)
    mult = np.ones((n_plus_1, n_plus_1))
    for link in self.group_links:
        shape = self._get_shape(link.shape_id)
        if shape is None:
            continue
        med_col = link.mediator_idx + 1
        if med_col >= n_plus_1 or Bbase[med_col] == 0:
            continue
        rel_b = BB[med_col] / Bbase[med_col]
        val = shape.evaluate(rel_b) * link.weight
        prey_row = link.prey_idx + 1
        pred_col = link.pred_idx + 1
        if prey_row < n_plus_1 and pred_col < n_plus_1:
            mult[prey_row, pred_col] *= val
    return mult

compute_fleet_multipliers

compute_fleet_multipliers(BB: ndarray, Bbase: ndarray, n_fleets: int) -> np.ndarray

Compute per-fleet multiplier array.

Each fleet link evaluates the shape at mediator relative biomass. Default 1.0 for unaffected fleets.

Source code in pypath/core/mediation.py

def compute_fleet_multipliers(
    self, BB: np.ndarray, Bbase: np.ndarray, n_fleets: int
) -> np.ndarray:
    """Compute per-fleet multiplier array.

    Each fleet link evaluates the shape at mediator relative biomass.
    Default 1.0 for unaffected fleets.
    """
    mult = np.ones(n_fleets)
    for link in self.fleet_links:
        shape = self._get_shape(link.shape_id)
        if shape is None:
            continue
        med_col = link.mediator_idx + 1
        if med_col >= len(BB) or Bbase[med_col] == 0:
            continue
        rel_b = BB[med_col] / Bbase[med_col]
        val = shape.evaluate(rel_b) * link.weight
        if link.fleet_idx is not None and link.fleet_idx < n_fleets:
            mult[link.fleet_idx] *= val
    return mult

compute_landing_multipliers

compute_landing_multipliers(BB: ndarray, Bbase: ndarray, n_fleets: int, n_groups: int) -> np.ndarray

Compute (n_fleets, n_groups) multiplier matrix for landings.

Default 1.0 for unaffected fleet-group combinations.

Source code in pypath/core/mediation.py

def compute_landing_multipliers(
    self, BB: np.ndarray, Bbase: np.ndarray, n_fleets: int, n_groups: int
) -> np.ndarray:
    """Compute (n_fleets, n_groups) multiplier matrix for landings.

    Default 1.0 for unaffected fleet-group combinations.
    """
    mult = np.ones((n_fleets, n_groups))
    for link in self.landing_links:
        shape = self._get_shape(link.shape_id)
        if shape is None:
            continue
        med_col = link.mediator_idx + 1
        if med_col >= len(BB) or Bbase[med_col] == 0:
            continue
        rel_b = BB[med_col] / Bbase[med_col]
        val = shape.evaluate(rel_b) * link.weight
        fi = link.landing_fleet_idx
        gi = link.landing_group_idx
        if fi is not None and gi is not None and fi < n_fleets and gi < n_groups:
            mult[fi, gi] *= val
    return mult

make_positive_shape

make_positive_shape(shape_id: int = 0, name: str = 'positive', low: float = 0.5, high: float = 2.0, shape: float = 1.0, n_points: int = 9) -> MediationShape

Create a positive (increasing) mediation shape.

y = low + (high - low) * x^shape / (1 + x^shape)

Source code in pypath/core/mediation.py

def make_positive_shape(
    shape_id: int = 0,
    name: str = "positive",
    low: float = 0.5,
    high: float = 2.0,
    shape: float = 1.0,
    n_points: int = 9,
) -> MediationShape:
    """Create a positive (increasing) mediation shape.

    y = low + (high - low) * x^shape / (1 + x^shape)
    """
    x = np.linspace(0.0, 2.0, n_points)
    y = low + (high - low) * x**shape / (1.0 + x**shape)
    return MediationShape(shape_id=shape_id, name=name, x_points=x, y_points=y)

make_negative_shape

make_negative_shape(shape_id: int = 0, name: str = 'negative', low: float = 0.5, high: float = 2.0, shape: float = 1.0, n_points: int = 9) -> MediationShape

Create a negative (decreasing) mediation shape.

y = high - (high - low) * x^shape / (1 + x^shape)

Source code in pypath/core/mediation.py

def make_negative_shape(
    shape_id: int = 0,
    name: str = "negative",
    low: float = 0.5,
    high: float = 2.0,
    shape: float = 1.0,
    n_points: int = 9,
) -> MediationShape:
    """Create a negative (decreasing) mediation shape.

    y = high - (high - low) * x^shape / (1 + x^shape)
    """
    x = np.linspace(0.0, 2.0, n_points)
    y = high - (high - low) * x**shape / (1.0 + x**shape)
    return MediationShape(shape_id=shape_id, name=name, x_points=x, y_points=y)

make_ushape

make_ushape(shape_id: int = 0, name: str = 'u-shaped', low: float = 0.5, high: float = 2.0, shape: float = 1.0, n_points: int = 9) -> MediationShape

Create a U-shaped mediation shape (peaks at x=1.0).

y = high - (high - low) * |x-1|^shape / (1 + |x-1|^shape)

Source code in pypath/core/mediation.py

def make_ushape(
    shape_id: int = 0,
    name: str = "u-shaped",
    low: float = 0.5,
    high: float = 2.0,
    shape: float = 1.0,
    n_points: int = 9,
) -> MediationShape:
    """Create a U-shaped mediation shape (peaks at x=1.0).

    y = high - (high - low) * |x-1|^shape / (1 + |x-1|^shape)
    """
    x = np.linspace(0.0, 2.0, n_points)
    abs_diff = np.abs(x - 1.0)
    y = high - (high - low) * abs_diff**shape / (1.0 + abs_diff**shape)
    return MediationShape(shape_id=shape_id, name=name, x_points=x, y_points=y)

Pedigree & Monte Carlo

Pedigree-based parameter uncertainty and Monte Carlo sampling.

pypath.core.pedigree

Pedigree-based parameter distributions and sampling.

Pedigree values (coefficients of variation) define parameter uncertainty. This module converts pedigree CVs to statistical distributions and generates parameter samples for Monte Carlo analysis.

ScalarDistribution dataclass

A single scalar parameter's sampling distribution (log-normal).

Parameters:

Name	Type	Description	Default
param_name	str	Parameter name (e.g. "Biomass", "PB", "QB").	required
group_idx	int	0-based group index.	required
base_value	float	Current Ecopath value.	required
cv	float	Coefficient of variation from pedigree.	required
bounds	tuple[float, float] | None	Optional hard bounds for rejection sampling.	None

Source code in pypath/core/pedigree.py

@dataclass
class ScalarDistribution:
    """A single scalar parameter's sampling distribution (log-normal).

    Parameters
    ----------
    param_name : str
        Parameter name (e.g. "Biomass", "PB", "QB").
    group_idx : int
        0-based group index.
    base_value : float
        Current Ecopath value.
    cv : float
        Coefficient of variation from pedigree.
    bounds : tuple[float, float] | None
        Optional hard bounds for rejection sampling.
    """

    param_name: str
    group_idx: int
    base_value: float
    cv: float
    bounds: tuple[float, float] | None = None

DietDistribution dataclass

A predator's diet composition distribution (Dirichlet).

Parameters:

Name	Type	Description	Default
pred_idx	int	0-based predator group index.	required
base_proportions	ndarray	Current diet column (prey proportions, sum=1).	required
cv	float	Controls Dirichlet concentration (higher CV = more spread).	required

Source code in pypath/core/pedigree.py

@dataclass
class DietDistribution:
    """A predator's diet composition distribution (Dirichlet).

    Parameters
    ----------
    pred_idx : int
        0-based predator group index.
    base_proportions : np.ndarray
        Current diet column (prey proportions, sum=1).
    cv : float
        Controls Dirichlet concentration (higher CV = more spread).
    """

    pred_idx: int
    base_proportions: np.ndarray
    cv: float

PedigreeConfig dataclass

Configuration for pedigree-to-CV mapping.

EwE 6 stores pedigree as (VarName, LevelID) pairs in the Pedigree table, where each VarName has its own set of levels with IndexValue (the CV).

In the Python API, params.pedigree values are treated as CVs directly. PedigreeConfig is only needed when importing from EwE databases.

Source code in pypath/core/pedigree.py

@dataclass
class PedigreeConfig:
    """Configuration for pedigree-to-CV mapping.

    EwE 6 stores pedigree as (VarName, LevelID) pairs in the Pedigree table,
    where each VarName has its own set of levels with IndexValue (the CV).

    In the Python API, params.pedigree values are treated as CVs directly.
    PedigreeConfig is only needed when importing from EwE databases.
    """

    level_to_cv: dict[str, dict[int, float]] = field(default_factory=dict)

build_distributions

build_distributions(params: 'RpathParams', config: PedigreeConfig | None = None) -> list[ParameterDistribution]

Build parameter distributions from pedigree CVs.

Parameters:

Name	Type	Description	Default
params	RpathParams	Ecopath parameters with pedigree DataFrame.	required
config	PedigreeConfig	EwE database pedigree mapping (for converting LevelIDs to CVs).	None

Returns:

Type	Description
list[ParameterDistribution]	Distributions for all parameters with CV > 0.

Source code in pypath/core/pedigree.py

def build_distributions(
    params: "RpathParams",
    config: PedigreeConfig | None = None,
) -> list[ParameterDistribution]:
    """Build parameter distributions from pedigree CVs.

    Parameters
    ----------
    params : RpathParams
        Ecopath parameters with pedigree DataFrame.
    config : PedigreeConfig, optional
        EwE database pedigree mapping (for converting LevelIDs to CVs).

    Returns
    -------
    list[ParameterDistribution]
        Distributions for all parameters with CV > 0.
    """

    pedigree = params.pedigree
    if pedigree is None:
        return []

    # Warn if all pedigree values are default 1.0
    numeric_cols = [c for c in pedigree.columns if c != "Group"]
    all_vals = pedigree[numeric_cols].values.flatten()
    all_vals = all_vals[~np.isnan(all_vals.astype(float))]
    if len(all_vals) > 0 and np.allclose(all_vals, 1.0):
        warnings.warn(
            "All pedigree values are 1.0 (default = 100% CV). "
            "Consider setting pedigree values before MC analysis.",
            UserWarning,
            stacklevel=2,
        )

    model = params.model
    distributions: list[ParameterDistribution] = []

    # Scalar parameters: Biomass, PB, QB
    scalar_params = ["Biomass", "PB", "QB"]
    for param_name in scalar_params:
        if param_name not in pedigree.columns:
            continue
        for idx in range(len(model)):
            group_type = model.loc[idx, "Type"]
            # Skip detritus (type=2) for PB/QB
            if group_type == 2 and param_name in ("PB", "QB"):
                continue
            # Skip fleets (type=3)
            if group_type == 3:
                continue
            # Producers don't have QB
            if group_type == 1 and param_name == "QB":
                continue

            cv = float(pedigree.loc[idx, param_name])
            if np.isnan(cv) or cv <= 0:
                continue

            base_val = model.loc[idx, param_name]
            if np.isnan(base_val) or base_val <= 0:
                continue

            distributions.append(
                ScalarDistribution(
                    param_name=param_name,
                    group_idx=idx,
                    base_value=float(base_val),
                    cv=cv,
                )
            )

    # Diet distributions: one per consumer with Diet CV > 0
    if "Diet" in pedigree.columns:
        consumer_mask = model["Type"] == 0
        for idx in range(len(model)):
            if not consumer_mask.iloc[idx]:
                continue
            cv = float(pedigree.loc[idx, "Diet"])
            if np.isnan(cv) or cv <= 0:
                continue

            group_name = model.loc[idx, "Group"]
            if group_name not in params.diet.columns:
                continue
            diet_col = params.diet[group_name].values.astype(float)
            # Only include if diet has non-zero entries
            if np.nansum(diet_col) <= 0:
                continue

            distributions.append(
                DietDistribution(
                    pred_idx=idx,
                    base_proportions=diet_col,
                    cv=cv,
                )
            )

    return distributions

sample_parameters

sample_parameters(distributions: list[ParameterDistribution], n_samples: int, method: str = 'lhs', rng: Generator | None = None) -> list[dict]

Generate parameter samples from distributions.

Parameters:

Name	Type	Description	Default
distributions	list[ParameterDistribution]	Parameter distributions from build_distributions().	required
n_samples	int	Number of samples to generate.	required
method	str	"lhs" for Latin Hypercube Sampling, "random" for direct sampling.	'lhs'
rng	Generator	Random number generator for reproducibility.	None

Returns:

Type	Description
list[dict]	N parameter sets. Keys are (param_name, group_idx) tuples.

Source code in pypath/core/pedigree.py

def sample_parameters(
    distributions: list[ParameterDistribution],
    n_samples: int,
    method: str = "lhs",
    rng: np.random.Generator | None = None,
) -> list[dict]:
    """Generate parameter samples from distributions.

    Parameters
    ----------
    distributions : list[ParameterDistribution]
        Parameter distributions from build_distributions().
    n_samples : int
        Number of samples to generate.
    method : str
        "lhs" for Latin Hypercube Sampling, "random" for direct sampling.
    rng : np.random.Generator, optional
        Random number generator for reproducibility.

    Returns
    -------
    list[dict]
        N parameter sets. Keys are (param_name, group_idx) tuples.
    """
    if rng is None:
        rng = np.random.default_rng()

    scalars = [d for d in distributions if isinstance(d, ScalarDistribution)]
    diets = [d for d in distributions if isinstance(d, DietDistribution)]

    # Generate scalar samples
    if method == "lhs" and len(scalars) > 0:
        from scipy.stats.qmc import LatinHypercube

        sampler = LatinHypercube(d=len(scalars), seed=rng)
        unit_samples = sampler.random(n=n_samples)  # (n_samples, n_scalars)
        scalar_samples = np.empty_like(unit_samples)
        for j, dist in enumerate(scalars):
            sigma = math.sqrt(math.log(1 + dist.cv**2))
            mu = math.log(dist.base_value) - sigma**2 / 2
            # Map uniform [0,1] to lognormal via inverse CDF
            from scipy.stats import lognorm

            scalar_samples[:, j] = lognorm.ppf(
                unit_samples[:, j],
                s=sigma,
                scale=math.exp(mu),
            )
    else:
        # Direct random sampling
        scalar_samples = np.empty((n_samples, len(scalars)))
        for j, dist in enumerate(scalars):
            sigma = math.sqrt(math.log(1 + dist.cv**2))
            mu = math.log(dist.base_value) - sigma**2 / 2
            scalar_samples[:, j] = rng.lognormal(mean=mu, sigma=sigma, size=n_samples)

    # Generate diet samples (always direct — no LHS for Dirichlet)
    # Note: the import row (last element) is included in Dirichlet sampling
    # if it has a non-zero proportion. This means import fraction varies
    # with other diet proportions. To fix import, set its proportion to 0.
    diet_samples: list[list[np.ndarray]] = []
    for dist in diets:
        nonzero_mask = dist.base_proportions > 0
        p_nonzero = dist.base_proportions[nonzero_mask]
        alpha = p_nonzero / dist.cv**2
        samples_for_diet = []
        for _ in range(n_samples):
            sampled = rng.dirichlet(alpha)
            full = np.zeros_like(dist.base_proportions)
            full[nonzero_mask] = sampled
            samples_for_diet.append(full)
        diet_samples.append(samples_for_diet)

    # Assemble into list of dicts
    result = []
    for i in range(n_samples):
        sample: dict = {}
        for j, dist in enumerate(scalars):
            sample[(dist.param_name, dist.group_idx)] = float(scalar_samples[i, j])
        for k, dist in enumerate(diets):
            sample[("Diet", dist.pred_idx)] = diet_samples[k][i]
        result.append(sample)

    return result

apply_sample

apply_sample(params: 'RpathParams', sample: dict) -> 'RpathParams'

Apply a parameter sample to a copy of RpathParams.

Parameters:

Name	Type	Description	Default
params	RpathParams	Original parameters (not modified).	required
sample	dict	Parameter sample from sample_parameters().	required

Returns:

Type	Description
RpathParams	New params with sampled values applied.

Source code in pypath/core/pedigree.py

def apply_sample(params: "RpathParams", sample: dict) -> "RpathParams":
    """Apply a parameter sample to a copy of RpathParams.

    Parameters
    ----------
    params : RpathParams
        Original parameters (not modified).
    sample : dict
        Parameter sample from sample_parameters().

    Returns
    -------
    RpathParams
        New params with sampled values applied.
    """
    from pypath.core.params import RpathParams

    new_model = params.model.copy()
    new_diet = params.diet.copy()

    # Deep copy stanzas if present
    new_stanzas = copy.deepcopy(params.stanzas)

    for key, value in sample.items():
        param_name, idx = key
        if param_name == "Diet":
            group_name = new_model.loc[idx, "Group"]
            if group_name in new_diet.columns:
                new_diet[group_name] = value
        else:
            new_model.loc[idx, param_name] = value

    return RpathParams(
        model=new_model,
        diet=new_diet,
        stanzas=new_stanzas,
        pedigree=params.pedigree,
        remarks=params.remarks,
        ecosim=params.ecosim,
    )

pypath.core.montecarlo

Monte Carlo uncertainty analysis for Ecopath/Ecosim.

Runs ensemble simulations with parameter sampling from pedigree-defined distributions. Supports parallel execution and streaming statistics.

MCConfig dataclass

Monte Carlo run configuration.

Source code in pypath/core/montecarlo.py

@dataclass
class MCConfig:
    """Monte Carlo run configuration."""

    n_samples: int = 1000
    method: str = "lhs"
    seed: int | None = None
    ecopath_only: bool = False
    ecosim_years: range | None = None
    store_runs: bool = False
    n_jobs: int = 1
    mediation: Any = None
    ecosim_method: str = "RK4"
    eco_area: float = 1.0

MCResult dataclass

Monte Carlo ensemble results.

Source code in pypath/core/montecarlo.py

@dataclass
class MCResult:
    """Monte Carlo ensemble results."""

    n_total: int
    n_feasible: int
    n_ecosim: int
    ecopath_stats: dict[str, pd.DataFrame]
    ecosim_stats: dict[str, np.ndarray] | None
    ecopath_runs: list[dict] | None
    ecosim_runs: list[np.ndarray] | None
    feasibility_rate: float
    parameter_samples: pd.DataFrame | None

    def to_dataframe(self) -> pd.DataFrame:
        """Return ecopath_stats as a single flat DataFrame."""
        frames = []
        for param_name, df in self.ecopath_stats.items():
            df_copy = df.copy()
            df_copy.insert(0, "parameter", param_name)
            frames.append(df_copy)
        if frames:
            return pd.concat(frames, ignore_index=True)
        return pd.DataFrame()

    def to_dict(self) -> dict:
        """Return JSON-serializable summary dict."""
        return {
            "n_total": self.n_total,
            "n_feasible": self.n_feasible,
            "n_ecosim": self.n_ecosim,
            "feasibility_rate": self.feasibility_rate,
            "ecopath_stats": {
                k: v.to_dict(orient="list") for k, v in self.ecopath_stats.items()
            },
        }

to_dataframe

to_dataframe() -> pd.DataFrame

Return ecopath_stats as a single flat DataFrame.

Source code in pypath/core/montecarlo.py

def to_dataframe(self) -> pd.DataFrame:
    """Return ecopath_stats as a single flat DataFrame."""
    frames = []
    for param_name, df in self.ecopath_stats.items():
        df_copy = df.copy()
        df_copy.insert(0, "parameter", param_name)
        frames.append(df_copy)
    if frames:
        return pd.concat(frames, ignore_index=True)
    return pd.DataFrame()

to_dict

to_dict() -> dict

Return JSON-serializable summary dict.

Source code in pypath/core/montecarlo.py

def to_dict(self) -> dict:
    """Return JSON-serializable summary dict."""
    return {
        "n_total": self.n_total,
        "n_feasible": self.n_feasible,
        "n_ecosim": self.n_ecosim,
        "feasibility_rate": self.feasibility_rate,
        "ecopath_stats": {
            k: v.to_dict(orient="list") for k, v in self.ecopath_stats.items()
        },
    }

run_montecarlo

run_montecarlo(params: 'RpathParams', config: MCConfig | None = None, *, pedigree_config: 'PedigreeConfig | None' = None, progress_callback: Callable[[int, int], None] | None = None) -> MCResult

Run Monte Carlo uncertainty analysis.

Parameters:

Name	Type	Description	Default
params	RpathParams	Base Ecopath parameters.	required
config	MCConfig	MC configuration. Defaults to MCConfig().	None
pedigree_config	PedigreeConfig	EwE pedigree mapping.	None
progress_callback	callable	Called with (current_sample, total_samples) after each run.	None

Returns:

Type	Description
MCResult

Source code in pypath/core/montecarlo.py

def run_montecarlo(
    params: "RpathParams",
    config: MCConfig | None = None,
    *,
    pedigree_config: "PedigreeConfig | None" = None,
    progress_callback: Callable[[int, int], None] | None = None,
) -> MCResult:
    """Run Monte Carlo uncertainty analysis.

    Parameters
    ----------
    params : RpathParams
        Base Ecopath parameters.
    config : MCConfig, optional
        MC configuration. Defaults to MCConfig().
    pedigree_config : PedigreeConfig, optional
        EwE pedigree mapping.
    progress_callback : callable, optional
        Called with (current_sample, total_samples) after each run.

    Returns
    -------
    MCResult
    """
    from pypath.core.pedigree import (
        apply_sample,
        build_distributions,
        sample_parameters,
    )

    if config is None:
        config = MCConfig()

    rng = np.random.default_rng(config.seed)
    distributions = build_distributions(params, pedigree_config)

    if len(distributions) == 0:
        warnings.warn("No distributions to sample (all CVs are 0).", UserWarning)

    samples = sample_parameters(distributions, config.n_samples, config.method, rng)

    # Collect results — exclude fleet groups (type=3) from biomass stats
    n_groups = int((params.model["Type"] != 3).sum())
    ecopath_biomass = []
    ecopath_runs_list = [] if config.store_runs else None
    ecosim_biomass_list = []
    ecosim_runs_list = [] if config.store_runs else None
    n_feasible = 0
    n_ecosim = 0

    for i, sample in enumerate(samples):
        sampled_params = apply_sample(params, sample)
        rpath_result = _run_single_ecopath(sampled_params, config.eco_area)

        if rpath_result is not None:
            n_feasible += 1
            bio = (
                rpath_result.Biomass[:n_groups]
                if hasattr(rpath_result, "Biomass")
                else None
            )
            if bio is not None:
                ecopath_biomass.append(bio.copy())
            if config.store_runs:
                ecopath_runs_list.append(
                    {
                        "Biomass": bio.copy() if bio is not None else None,
                    }
                )

            if not config.ecopath_only:
                ecosim_bio = _run_single_ecosim(rpath_result, sampled_params, config)
                if ecosim_bio is not None:
                    n_ecosim += 1
                    ecosim_biomass_list.append(ecosim_bio)
                    if config.store_runs:
                        ecosim_runs_list.append(ecosim_bio.copy())

        if progress_callback is not None:
            progress_callback(i + 1, config.n_samples)

    # Compute ecopath statistics
    ecopath_stats = {}
    if ecopath_biomass:
        bio_array = np.array(ecopath_biomass)  # (n_feasible, n_groups)
        ecopath_stats["Biomass"] = pd.DataFrame(
            {
                "mean": np.mean(bio_array, axis=0),
                "std": np.std(bio_array, axis=0),
                "p5": np.percentile(bio_array, 5, axis=0),
                "p25": np.percentile(bio_array, 25, axis=0),
                "p50": np.percentile(bio_array, 50, axis=0),
                "p75": np.percentile(bio_array, 75, axis=0),
                "p95": np.percentile(bio_array, 95, axis=0),
            }
        )

    # Compute ecosim statistics
    ecosim_stats = None
    if ecosim_biomass_list:
        # All arrays should have same shape; exclude padding col 0
        min_t = min(b.shape[0] for b in ecosim_biomass_list)
        stacked = np.array([b[:min_t, 1 : n_groups + 1] for b in ecosim_biomass_list])
        # stacked: (n_ecosim, timesteps, n_groups)
        ecosim_stats = {
            "Biomass": np.stack(
                [
                    np.mean(stacked, axis=0),
                    np.std(stacked, axis=0),
                    np.percentile(stacked, 5, axis=0),
                    np.percentile(stacked, 25, axis=0),
                    np.percentile(stacked, 50, axis=0),
                    np.percentile(stacked, 75, axis=0),
                    np.percentile(stacked, 95, axis=0),
                ],
                axis=-1,
            ),  # (timesteps, n_groups, 7)
        }

    feasibility_rate = n_feasible / config.n_samples if config.n_samples > 0 else 0.0

    return MCResult(
        n_total=config.n_samples,
        n_feasible=n_feasible,
        n_ecosim=n_ecosim,
        ecopath_stats=ecopath_stats,
        ecosim_stats=ecosim_stats,
        ecopath_runs=ecopath_runs_list,
        ecosim_runs=ecosim_runs_list,
        feasibility_rate=feasibility_rate,
        parameter_samples=None,
    )

Sensitivity Analysis

Morris OAT screening and Sobol variance-based sensitivity analysis.

pypath.core.sensitivity

Sensitivity analysis for Ecopath/Ecosim models.

Morris elementary effects screening and optional Sobol variance-based sensitivity analysis (requires SALib).

MorrisResult dataclass

Morris elementary effects screening results.

Source code in pypath/core/sensitivity.py

@dataclass
class MorrisResult:
    """Morris elementary effects screening results."""

    parameter_names: list[str]
    mu_star: np.ndarray
    sigma: np.ndarray
    mu: np.ndarray
    output_name: str = "Biomass"

SobolResult dataclass

Sobol variance-based sensitivity indices.

Source code in pypath/core/sensitivity.py

@dataclass
class SobolResult:
    """Sobol variance-based sensitivity indices."""

    parameter_names: list[str]
    S1: np.ndarray
    ST: np.ndarray
    S1_conf: np.ndarray
    ST_conf: np.ndarray
    output_name: str = "Biomass"

SensitivityConfig dataclass

Sensitivity analysis configuration.

Source code in pypath/core/sensitivity.py

@dataclass
class SensitivityConfig:
    """Sensitivity analysis configuration."""

    method: str = "morris"
    n_trajectories: int = 10
    n_levels: int = 4
    n_samples: int = 1024
    seed: int | None = None
    n_jobs: int = 1
    output_variable: str = "Biomass"
    output_group_idx: int | None = None
    ecopath_only: bool = False
    ecosim_years: range | None = None

run_sensitivity

run_sensitivity(params: 'RpathParams', config: SensitivityConfig | None = None, *, pedigree_config: 'PedigreeConfig | None' = None, progress_callback: Callable[[int, int], None] | None = None) -> MorrisResult | SobolResult

Run sensitivity analysis on Ecopath/Ecosim model.

Parameters:

Name	Type	Description	Default
params	RpathParams	Base Ecopath parameters.	required
config	SensitivityConfig	Sensitivity configuration.	None
pedigree_config	PedigreeConfig	EwE pedigree mapping.	None
progress_callback	callable	Called with (current, total) after each model evaluation.	None

Returns:

Type	Description
MorrisResult or SobolResult

Source code in pypath/core/sensitivity.py

def run_sensitivity(
    params: "RpathParams",
    config: SensitivityConfig | None = None,
    *,
    pedigree_config: "PedigreeConfig | None" = None,
    progress_callback: Callable[[int, int], None] | None = None,
) -> MorrisResult | SobolResult:
    """Run sensitivity analysis on Ecopath/Ecosim model.

    Parameters
    ----------
    params : RpathParams
        Base Ecopath parameters.
    config : SensitivityConfig, optional
        Sensitivity configuration.
    pedigree_config : PedigreeConfig, optional
        EwE pedigree mapping.
    progress_callback : callable, optional
        Called with (current, total) after each model evaluation.

    Returns
    -------
    MorrisResult or SobolResult
    """
    from pypath.core.ecopath import rpath as run_rpath
    from pypath.core.pedigree import (
        ScalarDistribution,
        apply_sample,
        build_distributions,
    )

    if config is None:
        config = SensitivityConfig()

    if config.method == "sobol" and not HAS_SALIB:
        raise ImportError("Install SALib for Sobol analysis: pip install SALib")

    rng = np.random.default_rng(config.seed)
    distributions = build_distributions(params, pedigree_config)
    scalars = [d for d in distributions if isinstance(d, ScalarDistribution)]

    if len(scalars) == 0:
        raise ValueError("No scalar distributions to analyze (all CVs are 0).")

    k = len(scalars)
    param_names = [f"{d.param_name}_{d.group_idx}" for d in scalars]

    def _evaluate(x_unit: np.ndarray) -> float:
        """Map unit hypercube point to params, run model, extract output."""
        sample = {}
        for j, dist in enumerate(scalars):
            sigma = math.sqrt(math.log(1 + dist.cv**2))
            mu = math.log(dist.base_value) - sigma**2 / 2
            from scipy.stats import lognorm

            val = float(lognorm.ppf(x_unit[j], s=sigma, scale=math.exp(mu)))
            sample[(dist.param_name, dist.group_idx)] = val

        sampled_params = apply_sample(params, sample)
        try:
            with warnings.catch_warnings():
                warnings.simplefilter("ignore")
                rpath_result = run_rpath(sampled_params)
            if config.output_group_idx is not None:
                return float(rpath_result.Biomass[config.output_group_idx])
            # Use nansum to skip fleet groups (which have NaN biomass)
            n_bio = int((params.model["Type"] != 3).sum())
            return float(np.nansum(rpath_result.Biomass[:n_bio]))
        except Exception:
            return np.nan

    if config.method == "morris":
        trajectories = _generate_morris_trajectories(
            k,
            config.n_trajectories,
            config.n_levels,
            rng,
        )
        n_evals = len(trajectories)
        y_values = np.empty(n_evals)
        for i in range(n_evals):
            y_values[i] = _evaluate(trajectories[i])
            if progress_callback:
                progress_callback(i + 1, n_evals)

        result = _compute_elementary_effects(
            trajectories,
            y_values,
            k,
            config.n_trajectories,
            config.n_levels,
        )
        result.parameter_names = param_names
        result.output_name = config.output_variable
        return result

    elif config.method == "sobol":
        n_runs = config.n_samples * (2 * k + 2)
        if n_runs > 10000:
            warnings.warn(
                f"Sobol analysis requires {n_runs} model evaluations.",
                UserWarning,
            )

        problem = {
            "num_vars": k,
            "names": param_names,
            "bounds": [[0.0, 1.0]] * k,
        }
        X = saltelli.sample(problem, config.n_samples, seed=config.seed)
        Y = np.empty(len(X))
        for i in range(len(X)):
            Y[i] = _evaluate(X[i])
            if progress_callback:
                progress_callback(i + 1, len(X))

        # Impute NaN with mean (SALib requires exact N*(2k+2) rows)
        nan_mask = np.isnan(Y)
        n_nan = np.sum(nan_mask)
        if n_nan > len(Y) * 0.5:
            raise RuntimeError("More than 50% of model evaluations failed.")
        if n_nan > 0:
            Y[nan_mask] = np.nanmean(Y)
            logger.warning("Imputed %d NaN evaluations with mean for Sobol.", n_nan)

        Si = salib_sobol.analyze(problem, Y)
        return SobolResult(
            parameter_names=param_names,
            S1=Si["S1"],
            ST=Si["ST"],
            S1_conf=Si["S1_conf"],
            ST_conf=Si["ST_conf"],
            output_name=config.output_variable,
        )

    raise ValueError(f"Unknown method: {config.method}")

Ecotracer (Contaminant Tracking)

Track contaminant concentrations through the food web coupled to Ecosim biomass dynamics.

pypath.core.ecotracer

Ecotracer: contaminant tracking through the food web.

Tracks contaminant concentrations alongside Ecosim biomass dynamics. Each group has initial concentration, environmental/immigration inputs, decay, assimilation, and metabolism rates.

EcotracerParams dataclass

Per-group tracer parameters.

All arrays are 0-based, length n_groups = NUM_LIVING + NUM_DEAD. No fleets, no padding column.

Parameters:

Name	Type	Description	Default
czero	ndarray	Initial concentration per group (n_groups,).	required
cenv	ndarray	Environmental input concentration (n_groups,).	required
cimmig	ndarray	Immigration input concentration (n_groups,).	required
cdecay	ndarray	Decay rate (n_groups,).	required
cassim	ndarray	Assimilation proportion, 0-1 (n_groups,).	required
cmetab	ndarray	Metabolism loss rate (n_groups,).	required

Source code in pypath/core/ecotracer.py

@dataclass
class EcotracerParams:
    """Per-group tracer parameters.

    All arrays are 0-based, length n_groups = NUM_LIVING + NUM_DEAD.
    No fleets, no padding column.

    Parameters
    ----------
    czero : np.ndarray
        Initial concentration per group (n_groups,).
    cenv : np.ndarray
        Environmental input concentration (n_groups,).
    cimmig : np.ndarray
        Immigration input concentration (n_groups,).
    cdecay : np.ndarray
        Decay rate (n_groups,).
    cassim : np.ndarray
        Assimilation proportion, 0-1 (n_groups,).
    cmetab : np.ndarray
        Metabolism loss rate (n_groups,).
    """

    czero: np.ndarray
    cenv: np.ndarray
    cimmig: np.ndarray
    cdecay: np.ndarray
    cassim: np.ndarray
    cmetab: np.ndarray

EcotracerResult dataclass

Output time series from Ecotracer simulation.

Parameters:

Name	Type	Description	Default
out_Conc	ndarray	Monthly concentrations (n_months+1, n_groups). Index 0 is initial state.	required
annual_Conc	ndarray	Annual average concentrations (n_years, n_groups).	required
group_names	list[str]	Group name labels.	required

Source code in pypath/core/ecotracer.py

@dataclass
class EcotracerResult:
    """Output time series from Ecotracer simulation.

    Parameters
    ----------
    out_Conc : np.ndarray
        Monthly concentrations (n_months+1, n_groups). Index 0 is initial state.
    annual_Conc : np.ndarray
        Annual average concentrations (n_years, n_groups).
    group_names : list[str]
        Group name labels.
    """

    out_Conc: np.ndarray
    annual_Conc: np.ndarray
    group_names: list[str]

create_ecotracer_params

create_ecotracer_params(n_groups: int) -> EcotracerParams

Create EcotracerParams with sensible defaults.

Defaults: czero=0, cenv=0, cimmig=0, cdecay=0, cassim=1.0, cmetab=0.

Source code in pypath/core/ecotracer.py

def create_ecotracer_params(n_groups: int) -> EcotracerParams:
    """Create EcotracerParams with sensible defaults.

    Defaults: czero=0, cenv=0, cimmig=0, cdecay=0, cassim=1.0, cmetab=0.
    """
    return EcotracerParams(
        czero=np.zeros(n_groups),
        cenv=np.zeros(n_groups),
        cimmig=np.zeros(n_groups),
        cdecay=np.zeros(n_groups),
        cassim=np.ones(n_groups),
        cmetab=np.zeros(n_groups),
    )

ecotracer_deriv

ecotracer_deriv(conc: ndarray, biomass: ndarray, Q_matrix: ndarray, params: EcotracerParams, detritus_fate: ndarray | None = None, n_living: int = 0) -> np.ndarray

Compute dC/dt for all groups.

Parameters:

Name	Type	Description	Default
conc	ndarray	Current concentrations (n_groups,).	required
biomass	ndarray	Current biomass (n_groups,).	required
Q_matrix	ndarray	Consumption matrix Q[prey, pred] (n_groups, n_groups), 0-based.	required
params	EcotracerParams	Tracer parameters.	required
detritus_fate	ndarray	Detritus fate fractions (n_living, n_detritus). When None, detritus only decays.	None
n_living	int	Number of living groups (groups 0..n_living-1 are living, n_living..n_groups-1 are detritus).	0

Returns:

Type	Description
ndarray	dC/dt for each group (n_groups,).

Source code in pypath/core/ecotracer.py

def ecotracer_deriv(
    conc: np.ndarray,
    biomass: np.ndarray,
    Q_matrix: np.ndarray,
    params: EcotracerParams,
    detritus_fate: np.ndarray | None = None,
    n_living: int = 0,
) -> np.ndarray:
    """Compute dC/dt for all groups.

    Parameters
    ----------
    conc : np.ndarray
        Current concentrations (n_groups,).
    biomass : np.ndarray
        Current biomass (n_groups,).
    Q_matrix : np.ndarray
        Consumption matrix Q[prey, pred] (n_groups, n_groups), 0-based.
    params : EcotracerParams
        Tracer parameters.
    detritus_fate : np.ndarray, optional
        Detritus fate fractions (n_living, n_detritus). When None, detritus
        only decays.
    n_living : int
        Number of living groups (groups 0..n_living-1 are living,
        n_living..n_groups-1 are detritus).

    Returns
    -------
    np.ndarray
        dC/dt for each group (n_groups,).
    """
    n_groups = len(conc)
    deriv = np.zeros(n_groups)

    # Living groups: dietary intake + environmental inputs - losses
    for i in range(n_living):
        # Dietary intake: cassim_i * sum_j(Q[j, i] * C[j]) / B_i
        if biomass[i] > _BIOMASS_THRESHOLD:
            dietary_intake = (
                params.cassim[i] * np.dot(Q_matrix[:, i], conc) / biomass[i]
            )
        else:
            dietary_intake = 0.0

        deriv[i] = (
            dietary_intake
            + params.cenv[i]
            + params.cimmig[i]
            - (params.cdecay[i] + params.cmetab[i]) * conc[i]
        )

    # Detritus groups: contaminant from dead matter + cenv - decay
    for i in range(n_living, n_groups):
        det_input = 0.0
        if detritus_fate is not None:
            det_idx = i - n_living
            if det_idx < detritus_fate.shape[1]:
                # Weighted average of contributor concentrations
                for j in range(n_living):
                    det_input += detritus_fate[j, det_idx] * conc[j]

        deriv[i] = (
            det_input
            + params.cenv[i]
            + params.cimmig[i]
            - (params.cdecay[i] + params.cmetab[i]) * conc[i]
        )

    return deriv

ecotracer_step

ecotracer_step(conc: ndarray, biomass: ndarray, Q_matrix: ndarray, params: EcotracerParams, dt: float, detritus_fate: ndarray | None = None, n_living: int = 0) -> np.ndarray

Analytic update for tracer concentration (unconditionally stable).

For each group i: input_i = dietary_intake_i + cenv_i + cimmig_i loss_rate_i = cdecay_i + cmetab_i if loss_rate_i > 0: C_i(t+dt) = input_i/loss_rate_i + (C_i - input_i/loss_rate_i) * exp(-loss_rate_i*dt) else: C_i(t+dt) = C_i + input_i * dt

Parameters:

Name	Type	Description	Default
conc	ndarray	Current concentrations (n_groups,).	required
biomass	ndarray	Current biomass (n_groups,).	required
Q_matrix	ndarray	Consumption matrix Q[prey, pred] (n_groups, n_groups), 0-based.	required
params	EcotracerParams	Tracer parameters.	required
dt	float	Timestep (typically 1/12 for monthly).	required
detritus_fate	ndarray	Detritus fate fractions (n_living, n_detritus).	None
n_living	int	Number of living groups.	0

Returns:

Type	Description
ndarray	Updated concentrations (n_groups,), clamped to >= 0.

Source code in pypath/core/ecotracer.py

def ecotracer_step(
    conc: np.ndarray,
    biomass: np.ndarray,
    Q_matrix: np.ndarray,
    params: EcotracerParams,
    dt: float,
    detritus_fate: np.ndarray | None = None,
    n_living: int = 0,
) -> np.ndarray:
    """Analytic update for tracer concentration (unconditionally stable).

    For each group i:
      input_i = dietary_intake_i + cenv_i + cimmig_i
      loss_rate_i = cdecay_i + cmetab_i
      if loss_rate_i > 0:
          C_i(t+dt) = input_i/loss_rate_i + (C_i - input_i/loss_rate_i) * exp(-loss_rate_i*dt)
      else:
          C_i(t+dt) = C_i + input_i * dt

    Parameters
    ----------
    conc : np.ndarray
        Current concentrations (n_groups,).
    biomass : np.ndarray
        Current biomass (n_groups,).
    Q_matrix : np.ndarray
        Consumption matrix Q[prey, pred] (n_groups, n_groups), 0-based.
    params : EcotracerParams
        Tracer parameters.
    dt : float
        Timestep (typically 1/12 for monthly).
    detritus_fate : np.ndarray, optional
        Detritus fate fractions (n_living, n_detritus).
    n_living : int
        Number of living groups.

    Returns
    -------
    np.ndarray
        Updated concentrations (n_groups,), clamped to >= 0.
    """
    n_groups = len(conc)
    new_conc = np.zeros(n_groups)

    # Compute instantaneous inputs for each group
    for i in range(n_groups):
        # Dietary intake (living groups only)
        if i < n_living and biomass[i] > _BIOMASS_THRESHOLD:
            dietary_intake = (
                params.cassim[i] * np.dot(Q_matrix[:, i], conc) / biomass[i]
            )
        elif i >= n_living:
            # Detritus input
            dietary_intake = 0.0
            if detritus_fate is not None:
                det_idx = i - n_living
                if det_idx < detritus_fate.shape[1]:
                    for j in range(n_living):
                        dietary_intake += detritus_fate[j, det_idx] * conc[j]
        else:
            dietary_intake = 0.0

        total_input = dietary_intake + params.cenv[i] + params.cimmig[i]
        loss_rate = params.cdecay[i] + params.cmetab[i]

        if loss_rate > 0:
            # Analytic solution: exact for constant input within timestep
            equilibrium = total_input / loss_rate
            new_conc[i] = equilibrium + (conc[i] - equilibrium) * math.exp(
                -loss_rate * dt
            )
        else:
            # No loss: simple linear accumulation
            new_conc[i] = conc[i] + total_input * dt

    # Clamp to non-negative
    np.clip(new_conc, 0.0, None, out=new_conc)
    return new_conc

Fleet Dynamics

Dynamic fleet effort response to profitability with quota management.

pypath.core.fleet_dynamics

Fleet Dynamics: profit-responsive effort and TAC quota management.

Models fleet capacity dynamics where effort responds to economic profit signals, and total allowable catch (TAC) quotas can cap fishing activity.

Each fleet has capacity that grows when profitable and depreciates otherwise. Effort is derived from capacity via an efficiency power relationship.

FleetEconParams dataclass

Economic parameters for fleet dynamics.

All cost/price arrays are indexed by fishing link (1-based externally, but stored as 0-based arrays here).

Parameters:

Name	Type	Description	Default
fixed_cost	ndarray	Fixed annual cost per fleet (n_fleets,). Does not depend on effort.	required
variable_cost	ndarray	Variable cost per fleet per unit capacity (n_fleets,).	required
sailing_cost	ndarray	Sailing cost per fleet per unit capacity (n_fleets,).	required
price	ndarray	Price per unit catch per fishing link (n_links,).	required
cap_depreciate	ndarray	Capacity depreciation rate per fleet (n_fleets,).	required
cap_base_growth	ndarray	Base capacity growth rate per fleet when profitable (n_fleets,).	required
eff_power	ndarray	Efficiency power: effort = capacity ** eff_power (n_fleets,).	required
tac	ndarray or None	Total allowable catch (n_fleets, n_groups). None means no TAC limits.	None

Source code in pypath/core/fleet_dynamics.py

@dataclass
class FleetEconParams:
    """Economic parameters for fleet dynamics.

    All cost/price arrays are indexed by fishing link (1-based externally,
    but stored as 0-based arrays here).

    Parameters
    ----------
    fixed_cost : np.ndarray
        Fixed annual cost per fleet (n_fleets,). Does not depend on effort.
    variable_cost : np.ndarray
        Variable cost per fleet per unit capacity (n_fleets,).
    sailing_cost : np.ndarray
        Sailing cost per fleet per unit capacity (n_fleets,).
    price : np.ndarray
        Price per unit catch per fishing link (n_links,).
    cap_depreciate : np.ndarray
        Capacity depreciation rate per fleet (n_fleets,).
    cap_base_growth : np.ndarray
        Base capacity growth rate per fleet when profitable (n_fleets,).
    eff_power : np.ndarray
        Efficiency power: effort = capacity ** eff_power (n_fleets,).
    tac : np.ndarray or None
        Total allowable catch (n_fleets, n_groups). None means no TAC limits.
    """

    fixed_cost: np.ndarray
    variable_cost: np.ndarray
    sailing_cost: np.ndarray
    price: np.ndarray
    cap_depreciate: np.ndarray
    cap_base_growth: np.ndarray
    eff_power: np.ndarray
    tac: np.ndarray | None = None

FleetDynamicsResult dataclass

Output time series from fleet dynamics simulation.

Parameters:

Name	Type	Description	Default
out_Effort	ndarray	Monthly effort per fleet (n_months, n_fleets).	required
out_Revenue	ndarray	Monthly revenue per fleet (n_months, n_fleets).	required
out_Cost	ndarray	Monthly cost per fleet (n_months, n_fleets).	required
out_Profit	ndarray	Monthly profit per fleet (n_months, n_fleets).	required
annual_Effort	ndarray	Annual average effort per fleet (n_years, n_fleets).	required
annual_Profit	ndarray	Annual total profit per fleet (n_years, n_fleets).	required
fleet_names	list[str]	Fleet name labels.	required

Source code in pypath/core/fleet_dynamics.py

@dataclass
class FleetDynamicsResult:
    """Output time series from fleet dynamics simulation.

    Parameters
    ----------
    out_Effort : np.ndarray
        Monthly effort per fleet (n_months, n_fleets).
    out_Revenue : np.ndarray
        Monthly revenue per fleet (n_months, n_fleets).
    out_Cost : np.ndarray
        Monthly cost per fleet (n_months, n_fleets).
    out_Profit : np.ndarray
        Monthly profit per fleet (n_months, n_fleets).
    annual_Effort : np.ndarray
        Annual average effort per fleet (n_years, n_fleets).
    annual_Profit : np.ndarray
        Annual total profit per fleet (n_years, n_fleets).
    fleet_names : list[str]
        Fleet name labels.
    """

    out_Effort: np.ndarray
    out_Revenue: np.ndarray
    out_Cost: np.ndarray
    out_Profit: np.ndarray
    annual_Effort: np.ndarray
    annual_Profit: np.ndarray
    fleet_names: list[str]

create_fleet_econ_params

create_fleet_econ_params(n_fleets: int, n_links: int) -> FleetEconParams

Create FleetEconParams with sensible defaults.

Defaults: all cost/depreciation rates zero, eff_power=1.0, tac=None.

Parameters:

Name	Type	Description	Default
n_fleets	int	Number of fleets.	required
n_links	int	Number of fishing links (fleet-group combinations).	required

Returns:

Type	Description
FleetEconParams	Parameter object with zero arrays and eff_power=1.0.

Source code in pypath/core/fleet_dynamics.py

def create_fleet_econ_params(n_fleets: int, n_links: int) -> FleetEconParams:
    """Create FleetEconParams with sensible defaults.

    Defaults: all cost/depreciation rates zero, eff_power=1.0, tac=None.

    Parameters
    ----------
    n_fleets : int
        Number of fleets.
    n_links : int
        Number of fishing links (fleet-group combinations).

    Returns
    -------
    FleetEconParams
        Parameter object with zero arrays and eff_power=1.0.
    """
    return FleetEconParams(
        fixed_cost=np.zeros(n_fleets),
        variable_cost=np.zeros(n_fleets),
        sailing_cost=np.zeros(n_fleets),
        price=np.zeros(n_links),
        cap_depreciate=np.zeros(n_fleets),
        cap_base_growth=np.zeros(n_fleets),
        eff_power=np.ones(n_fleets),
        tac=None,
    )

fleet_dynamics_step

fleet_dynamics_step(capacity: ndarray, monthly_catch: ndarray, cumulative_catch: ndarray, params: FleetEconParams, fish_through: ndarray, fish_from: ndarray, fleet_lookup: dict, n_fleets: int, dt: float = 1.0 / 12) -> tuple[np.ndarray, np.ndarray]

Advance fleet capacity and effort by one time step.

Computes revenue from catches, costs from capacity, a profit signal, then updates capacity using a logistic-style ODE.

Parameters:

Name	Type	Description	Default
capacity	ndarray	Current fleet capacities (n_fleets,). Modified in place via copy.	required
monthly_catch	ndarray	Catch from this month's fishing links (n_links,). 1-based index 0 unused.	required
cumulative_catch	ndarray	Cumulative annual catch per fleet per group (n_fleets, n_groups). Not modified here; used externally.	required
params	FleetEconParams	Economic parameters.	required
fish_through	ndarray	Fleet group index per fishing link (1-based, length n_links+1, index 0 unused).	required
fish_from	ndarray	Prey group index per fishing link (1-based, length n_links+1, index 0 unused).	required
fleet_lookup	dict	Maps gear_0based (int) -> 1-based gear array index (int).	required
n_fleets	int	Number of fleets.	required
dt	float	Time step in years (default 1/12 for monthly).	1.0 / 12

Returns:

Name	Type	Description
new_capacity	ndarray	Updated fleet capacities (n_fleets,).
effort	ndarray	Fleet effort this step (n_fleets,), effort = capacity ** eff_power.

Source code in pypath/core/fleet_dynamics.py

def fleet_dynamics_step(
    capacity: np.ndarray,
    monthly_catch: np.ndarray,
    cumulative_catch: np.ndarray,
    params: FleetEconParams,
    fish_through: np.ndarray,
    fish_from: np.ndarray,
    fleet_lookup: dict,
    n_fleets: int,
    dt: float = 1.0 / 12,
) -> tuple[np.ndarray, np.ndarray]:
    """Advance fleet capacity and effort by one time step.

    Computes revenue from catches, costs from capacity, a profit signal,
    then updates capacity using a logistic-style ODE.

    Parameters
    ----------
    capacity : np.ndarray
        Current fleet capacities (n_fleets,). Modified in place via copy.
    monthly_catch : np.ndarray
        Catch from this month's fishing links (n_links,). 1-based index 0 unused.
    cumulative_catch : np.ndarray
        Cumulative annual catch per fleet per group (n_fleets, n_groups).
        Not modified here; used externally.
    params : FleetEconParams
        Economic parameters.
    fish_through : np.ndarray
        Fleet group index per fishing link (1-based, length n_links+1,
        index 0 unused).
    fish_from : np.ndarray
        Prey group index per fishing link (1-based, length n_links+1,
        index 0 unused).
    fleet_lookup : dict
        Maps gear_0based (int) -> 1-based gear array index (int).
    n_fleets : int
        Number of fleets.
    dt : float
        Time step in years (default 1/12 for monthly).

    Returns
    -------
    new_capacity : np.ndarray
        Updated fleet capacities (n_fleets,).
    effort : np.ndarray
        Fleet effort this step (n_fleets,), effort = capacity ** eff_power.
    """
    new_capacity = capacity.copy()
    revenue = np.zeros(n_fleets)
    cost = np.zeros(n_fleets)

    # Step 1: Compute revenue per fleet from fishing links
    # price array has same length as FishFrom (index 0 unused, like FishFrom[0])
    for i in range(1, len(monthly_catch)):
        gear_0based = int(fish_through[i]) - 1
        gear_idx = fleet_lookup.get(gear_0based, 0)
        if gear_idx == 0:
            continue
        fleet_0 = gear_idx - 1
        if fleet_0 < 0 or fleet_0 >= n_fleets:
            continue
        price_i = params.price[i] if i < len(params.price) else 0.0
        revenue[fleet_0] += monthly_catch[i] * price_i

    # Step 2: Compute cost per fleet
    for g in range(n_fleets):
        cost[g] = (
            params.fixed_cost[g] / 12.0
            + (params.variable_cost[g] + params.sailing_cost[g]) * new_capacity[g]
        )

    # Step 3: Compute profit
    profit = revenue - cost

    # Step 4–6: Update capacity
    for g in range(n_fleets):
        denom = max(revenue[g], cost[g])
        if denom <= _EPSILON:
            denom = _EPSILON
        profit_signal = profit[g] / denom

        # Capacity ODE: dC/dt = (cap_base_growth * max(signal, 0) - cap_depreciate) * C
        growth_term = params.cap_base_growth[g] * max(profit_signal, 0.0)
        decay_term = params.cap_depreciate[g]
        new_capacity[g] += (growth_term - decay_term) * new_capacity[g] * dt
        new_capacity[g] = max(new_capacity[g], _CAPACITY_FLOOR)

    # Step 7: Effort from capacity
    effort = new_capacity**params.eff_power

    return new_capacity, effort

apply_quota_caps

apply_quota_caps(fish_q: ndarray, cumulative_catch: ndarray, tac: ndarray, fish_through: ndarray, fish_from: ndarray, fleet_lookup: dict) -> np.ndarray

Zero out fishing catchability for links that have reached their TAC.

Parameters:

Name	Type	Description	Default
fish_q	ndarray	Current FishQ values per fishing link (n_links+1,), index 0 unused.	required
cumulative_catch	ndarray	Cumulative annual catch (n_fleets, n_groups), 0-based indices.	required
tac	ndarray	Total allowable catch allocation (n_fleets, n_groups), 0-based.	required
fish_through	ndarray	Fleet group index per fishing link (1-based, length n_links+1).	required
fish_from	ndarray	Prey group index per fishing link (1-based, length n_links+1).	required
fleet_lookup	dict	Maps gear_0based (int) -> 1-based gear array index (int).	required

Returns:

Type	Description
ndarray	Copy of fish_q with zeroed entries for TAC-exhausted links.

Source code in pypath/core/fleet_dynamics.py

def apply_quota_caps(
    fish_q: np.ndarray,
    cumulative_catch: np.ndarray,
    tac: np.ndarray,
    fish_through: np.ndarray,
    fish_from: np.ndarray,
    fleet_lookup: dict,
) -> np.ndarray:
    """Zero out fishing catchability for links that have reached their TAC.

    Parameters
    ----------
    fish_q : np.ndarray
        Current FishQ values per fishing link (n_links+1,), index 0 unused.
    cumulative_catch : np.ndarray
        Cumulative annual catch (n_fleets, n_groups), 0-based indices.
    tac : np.ndarray
        Total allowable catch allocation (n_fleets, n_groups), 0-based.
    fish_through : np.ndarray
        Fleet group index per fishing link (1-based, length n_links+1).
    fish_from : np.ndarray
        Prey group index per fishing link (1-based, length n_links+1).
    fleet_lookup : dict
        Maps gear_0based (int) -> 1-based gear array index (int).

    Returns
    -------
    np.ndarray
        Copy of fish_q with zeroed entries for TAC-exhausted links.
    """
    new_fish_q = fish_q.copy()
    n_links = len(fish_q) - 1  # index 0 is unused padding

    for i in range(1, n_links + 1):
        gear_0based = int(fish_through[i]) - 1
        gear_idx = fleet_lookup.get(gear_0based, 0)
        if gear_idx == 0:
            continue
        fleet_0 = gear_idx - 1

        group_0 = int(fish_from[i]) - 1
        if group_0 < 0:
            continue

        n_fleets, n_groups = tac.shape
        if fleet_0 < 0 or fleet_0 >= n_fleets:
            continue
        if group_0 >= n_groups:
            continue

        if cumulative_catch[fleet_0, group_0] >= tac[fleet_0, group_0]:
            new_fish_q[i] = 0.0

    return new_fish_q

Ecological Indicators

Ecosystem-level indicators including Ulanowicz flow analysis, Finn Cycling Index, transfer efficiency, and system maturity indices.

pypath.core.indicators

Ecological indicators: flow analysis and ecosystem summary metrics.

Provides Ulanowicz ascendency framework (TST, ascendency, capacity, overhead, Finn cycling index) and ecosystem summary indicators (MTL catch, Marine Trophic Index, Shannon diversity, Kempton Q, gross efficiency).

FlowAnalysis dataclass

Results of Ulanowicz flow analysis.

Attributes:

Name	Type	Description
total_system_throughput	float	TST: sum of all flows through the system.
ascendency	float	System organization (bits x flow).
capacity	float	Development capacity (upper bound for ascendency).
overhead	float	Capacity - Ascendency (resilience reserve).
relative_ascendency	float	Ascendency / Capacity [0-1].
finn_cycling_index	float	Fraction of TST recycled [0-1].
transfer_efficiency	ndarray	Per-trophic-level transfer efficiency array.

Source code in pypath/core/indicators.py

@dataclass
class FlowAnalysis:
    """Results of Ulanowicz flow analysis.

    Attributes
    ----------
    total_system_throughput : float
        TST: sum of all flows through the system.
    ascendency : float
        System organization (bits x flow).
    capacity : float
        Development capacity (upper bound for ascendency).
    overhead : float
        Capacity - Ascendency (resilience reserve).
    relative_ascendency : float
        Ascendency / Capacity [0-1].
    finn_cycling_index : float
        Fraction of TST recycled [0-1].
    transfer_efficiency : np.ndarray
        Per-trophic-level transfer efficiency array.
    """

    total_system_throughput: float
    ascendency: float
    capacity: float
    overhead: float
    relative_ascendency: float
    finn_cycling_index: float
    transfer_efficiency: np.ndarray

EcosystemIndicators dataclass

Ecosystem summary indicators from balanced Ecopath model.

Attributes:

Name	Type	Description
mtl_catch	float	Mean trophic level of catch.
marine_trophic_index	float	MTL of catch excluding groups with TL < 3.25.
catch_biomass_ratio	float	Total catch / total living biomass.
gross_efficiency	float	Total catch / net primary production.
shannon_diversity	float	Shannon H' of biomass (living groups), natural log.
kempton_q	float	Biomass evenness in TL 3-4 range.

Source code in pypath/core/indicators.py

@dataclass
class EcosystemIndicators:
    """Ecosystem summary indicators from balanced Ecopath model.

    Attributes
    ----------
    mtl_catch : float
        Mean trophic level of catch.
    marine_trophic_index : float
        MTL of catch excluding groups with TL < 3.25.
    catch_biomass_ratio : float
        Total catch / total living biomass.
    gross_efficiency : float
        Total catch / net primary production.
    shannon_diversity : float
        Shannon H' of biomass (living groups), natural log.
    kempton_q : float
        Biomass evenness in TL 3-4 range.
    """

    mtl_catch: float
    marine_trophic_index: float
    catch_biomass_ratio: float
    gross_efficiency: float
    shannon_diversity: float
    kempton_q: float

SystemMaturityIndices dataclass

Odum's ecosystem development / maturity indicators.

Attributes:

Name	Type	Description
total_production	float	Sum of production across all living groups (P = Σ PB×B).
total_respiration	float	Sum of respiration across all living groups (R = Σ QB×B×Unassim + metabolism).
total_biomass	float	Sum of biomass across all living groups.
net_production	float	Total production minus total respiration (P - R).
pr_ratio	float	Production / Respiration ratio. Mature ecosystems approach 1.0.
b_tst_ratio	float	Total biomass / total system throughput. Higher in mature ecosystems.
mean_path_length	float	Average number of trophic transfers per unit of energy. Computed as TST / total consumption at TL 1.

Source code in pypath/core/indicators.py

@dataclass
class SystemMaturityIndices:
    """Odum's ecosystem development / maturity indicators.

    Attributes
    ----------
    total_production : float
        Sum of production across all living groups (P = Σ PB×B).
    total_respiration : float
        Sum of respiration across all living groups (R = Σ QB×B×Unassim + metabolism).
    total_biomass : float
        Sum of biomass across all living groups.
    net_production : float
        Total production minus total respiration (P - R).
    pr_ratio : float
        Production / Respiration ratio. Mature ecosystems approach 1.0.
    b_tst_ratio : float
        Total biomass / total system throughput. Higher in mature ecosystems.
    mean_path_length : float
        Average number of trophic transfers per unit of energy.
        Computed as TST / total consumption at TL 1.
    """

    total_production: float
    total_respiration: float
    total_biomass: float
    net_production: float
    pr_ratio: float
    b_tst_ratio: float
    mean_path_length: float

flow_analysis

flow_analysis(rpath: Rpath) -> FlowAnalysis

Compute Ulanowicz flow analysis for a balanced Ecopath model.

Parameters:

Name	Type	Description	Default
rpath	Rpath	Balanced Ecopath model with computed trophic levels.	required

Returns:

Type	Description
FlowAnalysis	TST, ascendency, capacity, overhead, relative ascendency, Finn cycling index, and per-level transfer efficiency.

Source code in pypath/core/indicators.py

def flow_analysis(rpath: Rpath) -> FlowAnalysis:
    """Compute Ulanowicz flow analysis for a balanced Ecopath model.

    Parameters
    ----------
    rpath : Rpath
        Balanced Ecopath model with computed trophic levels.

    Returns
    -------
    FlowAnalysis
        TST, ascendency, capacity, overhead, relative ascendency,
        Finn cycling index, and per-level transfer efficiency.
    """
    T, n_internal = _build_flow_matrix(rpath)
    n_total = T.shape[0]

    # Total System Throughput
    tst = np.sum(T)

    if tst == 0:
        return FlowAnalysis(
            total_system_throughput=0.0,
            ascendency=0.0,
            capacity=0.0,
            overhead=0.0,
            relative_ascendency=0.0,
            finn_cycling_index=0.0,
            transfer_efficiency=np.array([]),
        )

    # Marginal totals (T[receiver, sender] convention)
    t_row = np.sum(T, axis=1)  # row sums: total inflow to each destination
    t_col = np.sum(T, axis=0)  # col sums: total outflow from each source

    # Ascendency: A = Σ T[i,j] * log2(T[i,j] * TST / (T_in[i] * T_out[j]))
    # T_in[i] = t_row[i], T_out[j] = t_col[j]
    ascendency = 0.0
    for i in range(n_total):
        for j in range(n_total):
            if T[i, j] > 0 and t_row[i] > 0 and t_col[j] > 0:
                ascendency += T[i, j] * np.log2(T[i, j] * tst / (t_row[i] * t_col[j]))

    # Capacity: C = -Σ T[i,j] * log2(T[i,j] / TST)
    capacity = 0.0
    for i in range(n_total):
        for j in range(n_total):
            if T[i, j] > 0:
                capacity -= T[i, j] * np.log2(T[i, j] / tst)

    overhead = capacity - ascendency
    relative_ascendency = ascendency / capacity if capacity > 0 else 0.0

    # Finn Cycling Index (stub - implemented in Task 2)
    fci = _finn_cycling_index_from_matrix(T, n_internal)

    # Transfer Efficiency (stub - implemented in Task 3)
    te = _transfer_efficiency_from_rpath(rpath)

    return FlowAnalysis(
        total_system_throughput=tst,
        ascendency=ascendency,
        capacity=capacity,
        overhead=overhead,
        relative_ascendency=relative_ascendency,
        finn_cycling_index=fci,
        transfer_efficiency=te,
    )

finn_cycling_index

finn_cycling_index(rpath: Rpath) -> float

Compute Finn Cycling Index for a balanced Ecopath model.

The Finn Cycling Index (FCI) measures the fraction of total system throughput that is recycled. Values near 0 indicate linear flow; values near 1 indicate high recycling.

Parameters:

Name	Type	Description	Default
rpath	Rpath	Balanced Ecopath model.	required

Returns:

Type	Description
float	Finn Cycling Index in [0, 1].

Source code in pypath/core/indicators.py

def finn_cycling_index(rpath: Rpath) -> float:
    """Compute Finn Cycling Index for a balanced Ecopath model.

    The Finn Cycling Index (FCI) measures the fraction of total system
    throughput that is recycled. Values near 0 indicate linear flow;
    values near 1 indicate high recycling.

    Parameters
    ----------
    rpath : Rpath
        Balanced Ecopath model.

    Returns
    -------
    float
        Finn Cycling Index in [0, 1].
    """
    T, n_internal = _build_flow_matrix(rpath)
    return _finn_cycling_index_from_matrix(T, n_internal)

transfer_efficiency

transfer_efficiency(rpath: Rpath) -> np.ndarray

Compute per-trophic-level transfer efficiency.

Uses simplified integer-bin approach: groups are binned by floor(TL), and efficiency is computed as the ratio of flow from level L to level L+1 divided by total input to level L.

Parameters:

Name	Type	Description	Default
rpath	Rpath	Balanced Ecopath model.	required

Returns:

Type	Description
ndarray	Transfer efficiency per TL bin (starting from TL 2). Empty array if no groups at TL >= 2.

Source code in pypath/core/indicators.py

def transfer_efficiency(rpath: Rpath) -> np.ndarray:
    """Compute per-trophic-level transfer efficiency.

    Uses simplified integer-bin approach: groups are binned by
    floor(TL), and efficiency is computed as the ratio of flow
    from level L to level L+1 divided by total input to level L.

    Parameters
    ----------
    rpath : Rpath
        Balanced Ecopath model.

    Returns
    -------
    np.ndarray
        Transfer efficiency per TL bin (starting from TL 2).
        Empty array if no groups at TL >= 2.
    """
    return _transfer_efficiency_from_rpath(rpath)

ecosystem_indicators

ecosystem_indicators(rpath: Rpath) -> EcosystemIndicators

Compute ecosystem summary indicators from a balanced Ecopath model.

Parameters:

Name	Type	Description	Default
rpath	Rpath	Balanced Ecopath model.	required

Returns:

Type	Description
EcosystemIndicators	Static ecosystem summary metrics.

Source code in pypath/core/indicators.py

def ecosystem_indicators(rpath: Rpath) -> EcosystemIndicators:
    """Compute ecosystem summary indicators from a balanced Ecopath model.

    Parameters
    ----------
    rpath : Rpath
        Balanced Ecopath model.

    Returns
    -------
    EcosystemIndicators
        Static ecosystem summary metrics.
    """
    n_living = rpath.NUM_LIVING
    n_dead = rpath.NUM_DEAD
    n_internal = n_living + n_dead

    # Compute catch per group
    # Landings/Discards are (NUM_GROUPS, NUM_GEARS), 0-based: sum all gears.
    catch = np.zeros(n_internal)
    for i in range(n_internal):
        catch[i] = np.sum(rpath.Landings[i, :]) + np.sum(rpath.Discards[i, :])

    total_catch = np.sum(catch)
    tl_internal = rpath.TL[:n_internal]

    # --- MTL catch ---
    if total_catch > 0:
        mtl_catch = np.sum(tl_internal * catch) / total_catch
    else:
        mtl_catch = np.nan

    # --- Marine Trophic Index (TL >= 3.25 only) ---
    mti_mask = (catch > 0) & (tl_internal >= 3.25)
    mti_catch = catch[mti_mask]
    mti_tl = tl_internal[mti_mask]
    if np.sum(mti_catch) > 0:
        marine_trophic_index = np.sum(mti_tl * mti_catch) / np.sum(mti_catch)
    else:
        marine_trophic_index = np.nan

    # --- Catch/Biomass ratio (living groups only) ---
    living_biomass = np.sum(rpath.Biomass[:n_living])
    catch_biomass_ratio = total_catch / living_biomass if living_biomass > 0 else np.nan

    # --- Gross efficiency (catch / NPP) ---
    npp = 0.0
    for i in range(n_living):
        if rpath.type[i] == 1:  # producer
            npp += rpath.PB[i] * rpath.Biomass[i]
    gross_efficiency = total_catch / npp if npp > 0 else np.nan

    # --- Shannon diversity (living groups with B > 0) ---
    living_b = []
    for i in range(n_living):
        if rpath.type[i] in (0, 1) and rpath.Biomass[i] > 0:
            living_b.append(rpath.Biomass[i])

    if len(living_b) > 0:
        living_b = np.array(living_b)
        total_b = np.sum(living_b)
        p = living_b / total_b
        shannon_diversity = -np.sum(p * np.log(p))
    else:
        shannon_diversity = np.nan

    # --- Kempton Q (TL in [3, 4)) ---
    q_biomasses = []
    for i in range(n_living):
        if rpath.type[i] in (0, 1) and 3.0 <= rpath.TL[i] < 4.0:
            q_biomasses.append(rpath.Biomass[i])

    if len(q_biomasses) >= 4:
        q_biomasses = np.sort(q_biomasses)
        b25 = np.percentile(q_biomasses, 25)
        b75 = np.percentile(q_biomasses, 75)
        s = len(q_biomasses)
        if b75 > b25 and b25 > 0:
            kempton_q = 0.5 * s / (np.log(b75) - np.log(b25))
        else:
            kempton_q = np.nan
    else:
        kempton_q = np.nan

    return EcosystemIndicators(
        mtl_catch=mtl_catch,
        marine_trophic_index=marine_trophic_index,
        catch_biomass_ratio=catch_biomass_ratio,
        gross_efficiency=gross_efficiency,
        shannon_diversity=shannon_diversity,
        kempton_q=kempton_q,
    )

system_maturity

system_maturity(rpath: Rpath) -> SystemMaturityIndices

Compute Odum's ecosystem maturity indicators.

Parameters:

Name	Type	Description	Default
rpath	Rpath	Balanced Ecopath model.	required

Returns:

Type	Description
SystemMaturityIndices

Source code in pypath/core/indicators.py

def system_maturity(rpath: Rpath) -> SystemMaturityIndices:
    """Compute Odum's ecosystem maturity indicators.

    Parameters
    ----------
    rpath : Rpath
        Balanced Ecopath model.

    Returns
    -------
    SystemMaturityIndices
    """
    n_living = rpath.NUM_LIVING
    n_dead = rpath.NUM_DEAD
    n_internal = n_living + n_dead

    # Total production: Σ PB[i] × B[i] for all living groups
    total_production = 0.0
    for i in range(n_living):
        total_production += rpath.PB[i] * rpath.Biomass[i]

    # Total respiration: for each consumer, R = QB×B×(1-Unassim) - PB×B
    # For producers, R = PB×B - net primary production exported
    # Simplified: R = Σ (QB×B - PB×B) for consumers, PB×B×(1-EE) for producers
    # EwE approach: respiration = assimilated consumption - production
    total_respiration = 0.0
    for i in range(n_living):
        if rpath.type[i] == 1:  # producer
            # Producer respiration = production - what's consumed by others
            # Simplification: R = P × (1 - EE) for producers
            total_respiration += rpath.PB[i] * rpath.Biomass[i] * (1.0 - rpath.EE[i])
        else:  # consumer
            # R = assimilated food - production = QB×B×(1-Unassim) - PB×B
            assimilated = rpath.QB[i] * rpath.Biomass[i] * (1.0 - rpath.Unassim[i])
            production = rpath.PB[i] * rpath.Biomass[i]
            resp = assimilated - production
            total_respiration += max(0.0, resp)

    total_biomass = float(np.sum(rpath.Biomass[:n_living]))
    net_production = total_production - total_respiration
    pr_ratio = total_production / total_respiration if total_respiration > 0 else np.nan

    # B/TST ratio
    T, _ = _build_flow_matrix(rpath)
    tst = float(np.sum(T))
    b_tst_ratio = total_biomass / tst if tst > 0 else np.nan

    # Mean path length: TST / total input at base level
    # Base input = total consumption at TL 1 (primary production + detrital input)
    base_input = 0.0
    for i in range(n_internal):
        if rpath.type[i] == 1:  # producer
            base_input += rpath.PB[i] * rpath.Biomass[i]
        elif rpath.type[i] == 2:  # detritus
            # Detrital input from outside
            det_input = getattr(rpath, "DetInput", None)
            if det_input is not None and i < len(det_input):
                base_input += det_input[i]
    mean_path_length = tst / base_input if base_input > 0 else np.nan

    return SystemMaturityIndices(
        total_production=total_production,
        total_respiration=total_respiration,
        total_biomass=total_biomass,
        net_production=net_production,
        pr_ratio=pr_ratio,
        b_tst_ratio=b_tst_ratio,
        mean_path_length=mean_path_length,
    )

ecosystem_indicators_timeseries

ecosystem_indicators_timeseries(output: RsimOutput, scenario: RsimScenario, rpath: Rpath) -> pd.DataFrame

Compute ecosystem indicators per year from Ecosim output.

Parameters:

Name	Type	Description	Default
output	RsimOutput	Ecosim simulation output with annual_Biomass and annual_Catch.	required
scenario	RsimScenario	Ecosim scenario for group count validation.	required
rpath	Rpath	Balanced Ecopath model for trophic levels and group types.	required

Returns:

Type	Description
DataFrame	Columns: year, mtl_catch, marine_trophic_index, catch_biomass_ratio, gross_efficiency, shannon_diversity. One row per year.

Source code in pypath/core/indicators.py

def ecosystem_indicators_timeseries(
    output: RsimOutput,
    scenario: RsimScenario,
    rpath: Rpath,
) -> pd.DataFrame:
    """Compute ecosystem indicators per year from Ecosim output.

    Parameters
    ----------
    output : RsimOutput
        Ecosim simulation output with annual_Biomass and annual_Catch.
    scenario : RsimScenario
        Ecosim scenario for group count validation.
    rpath : Rpath
        Balanced Ecopath model for trophic levels and group types.

    Returns
    -------
    pd.DataFrame
        Columns: year, mtl_catch, marine_trophic_index,
        catch_biomass_ratio, gross_efficiency, shannon_diversity.
        One row per year.
    """
    import pandas as pd

    n_years = output.annual_Biomass.shape[0]
    n_living = rpath.NUM_LIVING
    n_dead = rpath.NUM_DEAD
    n_internal = n_living + n_dead

    # Validate array dimensions match scenario
    if output.annual_Biomass.shape[1] < n_internal + 1:
        logger.warning(
            "annual_Biomass has %d columns but need %d for %d groups",
            output.annual_Biomass.shape[1],
            n_internal + 1,
            n_internal,
        )

    rows = []
    for yr in range(n_years):
        # Two indexing conventions meet here. Ecosim output arrays are
        # 1-based with index 0 = "Outside", while Rpath arrays are 0-based
        # over NUM_GROUPS. Ecopath group g therefore sits at Ecosim index
        # g + 1, and the two are sliced separately rather than together.
        biomass = output.annual_Biomass[yr]  # 1-based (0 = Outside)
        catch_arr = output.annual_Catch[yr]  # 1-based (0 = Outside)

        catch_internal = catch_arr[1 : n_internal + 1]
        tl_internal = rpath.TL[:n_internal]
        total_catch = np.sum(catch_internal)

        # MTL catch
        if total_catch > 0:
            mtl_catch = np.sum(tl_internal * catch_internal) / total_catch
        else:
            mtl_catch = np.nan

        # Marine Trophic Index (TL >= 3.25)
        mti_mask = (catch_internal > 0) & (tl_internal >= 3.25)
        mti_c = catch_internal[mti_mask]
        mti_t = tl_internal[mti_mask]
        if np.sum(mti_c) > 0:
            marine_trophic_index = np.sum(mti_t * mti_c) / np.sum(mti_c)
        else:
            marine_trophic_index = np.nan

        # Catch/Biomass ratio (living groups)
        living_b = np.sum(biomass[1 : n_living + 1])
        catch_biomass_ratio = total_catch / living_b if living_b > 0 else np.nan

        # Gross efficiency (catch / NPP using dynamic biomass)
        # PB is static (from Ecopath); biomass is dynamic (from Ecosim)
        npp = 0.0
        for i in range(n_living):
            if rpath.type[i] == 1:  # producer
                npp += rpath.PB[i] * biomass[i + 1]
        gross_efficiency = total_catch / npp if npp > 0 else np.nan

        # Shannon diversity (living groups with B > 0)
        living_bio = []
        for i in range(n_living):
            if rpath.type[i] in (0, 1) and biomass[i + 1] > 0:
                living_bio.append(biomass[i + 1])

        if len(living_bio) > 0:
            living_bio = np.array(living_bio)
            total_b = np.sum(living_bio)
            p = living_bio / total_b
            shannon_diversity = -np.sum(p * np.log(p))
        else:
            shannon_diversity = np.nan

        rows.append(
            {
                "year": yr,
                "mtl_catch": mtl_catch,
                "marine_trophic_index": marine_trophic_index,
                "catch_biomass_ratio": catch_biomass_ratio,
                "gross_efficiency": gross_efficiency,
                "shannon_diversity": shannon_diversity,
            }
        )

    return pd.DataFrame(rows)