gcubed.linearisation.equation_structure

Shared structural metadata for linear-model memory planning.

The SYM equation-map file determines both which equation functions must be evaluated for a perturbed RHS variable and which dense partial-derivative blocks can be materialized. Reading it once keeps preflight estimates and the linearisation implementation on the same structural contract.

type VariablePosition = tuple[str, int]

type PartialMatrixKey = tuple[str, str]

@dataclass(frozen=True)

class LinearisationEquationStructure:

Equation routing and structural partial counts from one SYM map.

Attributes: equations_map: RHS vector positions mapped to affected LHS positions. partial_nonzero_counts: Conservative structural entry count for each materialized LHS/RHS partial-derivative block.

LinearisationEquationStructure( equations_map: dict[VariablePosition, list[VariablePosition]], partial_nonzero_counts: dict[PartialMatrixKey, int])

equations_map: dict[VariablePosition, list[VariablePosition]]

partial_nonzero_counts: dict[PartialMatrixKey, int]

def load_equation_structure( equation_map_file: pathlib.Path) -> LinearisationEquationStructure:

Load derivative routing and block counts from a SYM equation map.

Args: equation_map_file: Two-column SYM *_eqnmap.csv path.

Returns: Shared equation routing and structural matrix counts.

Raises: FileNotFoundError: Propagated when the equation map is absent. ValueError: Raised for malformed rows or an RHS row before any LHS.