gcubed.experiments

Public setup and runtime infrastructure for G-Cubed experiments.

@dataclass(frozen=True)
class ChartpackSetupConfiguration:

One chartpack output declaration normalised for generation.

ChartpackSetupConfiguration( file_name: str, title: str, charts: tuple[Mapping[str, object], ...] = (), first_result_year: int | None = None, last_result_year: int | None = None, derivations: tuple[str, ...] = (), max_series_per_chart: int = 25, data: Mapping[str, object] | None = None)
file_name: str
title: str
charts: tuple[Mapping[str, object], ...] = ()
first_result_year: int | None = None
last_result_year: int | None = None
derivations: tuple[str, ...] = ()
max_series_per_chart: int = 25
data: Mapping[str, object] | None = None
def as_writer_mapping(self) -> dict[str, object]:

Return the canonical declaration shape required by the writer.

@dataclass(frozen=True)
class DesignSetupConfiguration:

One ordered design output and its explicit layer membership.

DesignSetupConfiguration( file_name: str, name: str, layer_ids: tuple[str, ...], key: str | None = None)
file_name: str
name: str
layer_ids: tuple[str, ...]
key: str | None = None
@dataclass(frozen=True)
class CatalogueVariable:

One variable and its ordered, arbitrary metadata dimensions.

CatalogueVariable(name: str, prefix: str, dimensions: tuple[tuple[str, str], ...])
name: str
prefix: str
dimensions: tuple[tuple[str, str], ...]
members_by_dimension: dict[str, str]

Return this variable's dimension-to-member mapping.

@dataclass(frozen=True)
class BaselineRunOptions:

User-editable switches for one ordinary baseline invocation.

BaselineRunOptions( force_model_to_resolve: bool = False, show_final_results: bool = False)
force_model_to_resolve: bool = False
show_final_results: bool = False
@dataclass(frozen=True)
class ExperimentRunOptions:

User-editable switches shared by ordinary and local experiment runs.

ExperimentRunOptions( ask_to_solve_model_if_missing: bool = True, solve_model_if_missing: bool = False, show_final_results: bool = False)
ask_to_solve_model_if_missing: bool = True
solve_model_if_missing: bool = False
show_final_results: bool = False
@dataclass(frozen=True)
class MemberGroup:

One named, dimension-neutral ordered member selection.

MemberGroup(members: tuple[str, ...])
members: tuple[str, ...]
@dataclass(frozen=True)
class ResolvedSelector:

One selector with its model-resolved members in declaration order.

ResolvedSelector(dimension: str, members: tuple[str, ...])
dimension: str
members: tuple[str, ...]
@dataclass(frozen=True)
class ResolvedVariableSelection:

Exact variables plus metadata required by downstream artefact builders.

ResolvedVariableSelection( variable_prefix: str, variables: tuple[str, ...], records: tuple[CatalogueVariable, ...], selectors: tuple[ResolvedSelector, ...])
variable_prefix: str
variables: tuple[str, ...]
records: tuple[CatalogueVariable, ...]
selectors: tuple[ResolvedSelector, ...]
@dataclass(frozen=True)
class SetupConfiguration(collections.abc.Mapping[str, object]):

A validated setup-only document with normalised typed declarations.

SetupConfiguration( path: pathlib.Path, kind: SetupKind, model: Mapping[str, object], artefacts: Mapping[str, object], member_groups: Mapping[str, MemberGroup], layers: tuple[Mapping[str, object], ...], maintained_layers: tuple[Mapping[str, object], ...], targets: TargetSetupConfiguration | None, designs: tuple[DesignSetupConfiguration, ...], chartpacks: tuple[ChartpackSetupConfiguration, ...], data: Mapping[str, object])
path: pathlib.Path
kind: SetupKind
model: Mapping[str, object]
artefacts: Mapping[str, object]
member_groups: Mapping[str, MemberGroup]
layers: tuple[Mapping[str, object], ...]
maintained_layers: tuple[Mapping[str, object], ...]
targets: TargetSetupConfiguration | None
designs: tuple[DesignSetupConfiguration, ...]
chartpacks: tuple[ChartpackSetupConfiguration, ...]
data: Mapping[str, object]
chartpack: ChartpackSetupConfiguration

Return the first chartpack for callers written before plural support.

class SetupConfigurationError(builtins.ValueError):

Raised when a setup configuration violates its public contract.

@dataclass(frozen=True)
class SetupContext:

A loaded setup document and paths implied by the retained model layout.

SetupContext( source_path: pathlib.Path, setup_configuration_path: pathlib.Path, setup_script_path: pathlib.Path | None, configuration: SetupConfiguration, simulation_directory: pathlib.Path, simulations_directory: pathlib.Path, model_directory: pathlib.Path, model_configuration_path: pathlib.Path, templates_directory: pathlib.Path, report_template_path: pathlib.Path | None, root_results_directory: pathlib.Path, model_results_directory: pathlib.Path, results_directory: pathlib.Path, baseline_results_directory: pathlib.Path | None)
source_path: pathlib.Path
setup_configuration_path: pathlib.Path
setup_script_path: pathlib.Path | None
configuration: SetupConfiguration
simulation_directory: pathlib.Path
simulations_directory: pathlib.Path
model_directory: pathlib.Path
model_configuration_path: pathlib.Path
templates_directory: pathlib.Path
report_template_path: pathlib.Path | None
root_results_directory: pathlib.Path
model_results_directory: pathlib.Path
results_directory: pathlib.Path
baseline_results_directory: pathlib.Path | None
kind: SetupKind

Return the discriminator loaded from YAML, never from a filename.

class SetupKind(builtins.str, enum.Enum):

Purpose of a setup document, independent of its entry-point filename.

BASELINE = <SetupKind.BASELINE: 'baseline'>
EXPERIMENT = <SetupKind.EXPERIMENT: 'experiment'>
@dataclass(frozen=True)
class TargetSetupConfiguration:

One generated optimisation-target CSV declaration.

TargetSetupConfiguration( data_file_name: str, first_year: int, last_year: int, variables: tuple[Mapping[str, object], ...], derivations: tuple[str, ...] = ())
data_file_name: str
first_year: int
last_year: int
variables: tuple[Mapping[str, object], ...]
derivations: tuple[str, ...] = ()
@dataclass(frozen=True)
class VariableCatalogue:

An immutable sequence of model variables in source-catalogue order.

VariableCatalogue( variables: tuple[CatalogueVariable, ...])
variables: tuple[CatalogueVariable, ...]
names: tuple[str, ...]

Return exact variable names in stable catalogue order.

class VariableResolutionError(builtins.ValueError):

Raised when a variable declaration cannot be resolved unambiguously.

class WorkflowType(builtins.str, enum.Enum):

Legacy run-adapter discriminator, no longer part of setup YAML.

STANDARD = <WorkflowType.STANDARD: 'standard'>
OPTIMISATION = <WorkflowType.OPTIMISATION: 'optimisation'>
FIXED_POINT = <WorkflowType.FIXED_POINT: 'fixed_point'>
def build_variable_catalogue( source: VariableCatalogue | pandas.DataFrame | object, *, dimension_columns: Sequence[str] | None = None) -> VariableCatalogue:

Normalize a dataframe or SymData-like object into a stable catalogue.

Dataframes may describe arbitrary dimensions with a mapping-valued dimensions column, a SYM-style sets value such as "sectors=a01,regions=USA", or explicitly named dimension_columns. A SymData-like object is any object exposing such a dataframe through its variable_summary attribute.

def chart_catalogue( sym_data: gcubed.sym_data.SymData, *, derivation_names: object = ()) -> pandas.DataFrame:

Return model and declared derived metadata suitable for chart setup.

def configured_derivation_names( configuration: SetupConfiguration) -> tuple[str, ...]:

Return derivations needed to resolve target and chart declarations.

def generate_setup_artefacts(source_path: pathlib.Path) -> tuple[pathlib.Path, ...]:

Generate only declared layers, targets, designs, and chartpacks.

def generate_setup_artefacts_from_configuration( configuration: SetupConfiguration, *, simulation_directory: pathlib.Path, catalogue: pandas.DataFrame | object, last_projection_year: int) -> tuple[pathlib.Path, ...]:

Preflight and atomically replace the complete declared setup write set.

def generate_setup_chartpack( configuration: SetupConfiguration, *, simulation_directory: pathlib.Path, catalogue: pandas.DataFrame | object, overwrite: bool | None = None) -> pathlib.Path:

Generate the first declared chartpack for compatibility callers.

def load_setup_data(path: pathlib.Path) -> dict[str, object]:

Load setup YAML and return a copy of its canonical setup-only mapping.

def load_setup_configuration( path: pathlib.Path) -> SetupConfiguration:

Load one strict setup-only version-1 document from path.

def resolve_selector_members( catalogue: VariableCatalogue | pandas.DataFrame | object, *, variable_prefix: str, selectors: Sequence[Mapping[str, object]], member_groups: Mapping[str, MemberGroup | Mapping[str, object]] | None = None) -> tuple[ResolvedSelector, ...]:

Resolve ordered selector records, including member-group references.

def resolve_setup_context( source_path: pathlib.Path, *, setup_configuration_file_name: str = 'setup.yaml') -> SetupContext:

Resolve setup paths from an explicit YAML document or Python entry point.

A Python source path selects a sibling setup document with the conventional setup.yaml name. The Python filename itself is deliberately unrestricted so historical entry-point names continue to work. Every other source path is treated as the explicitly selected setup document.

def resolve_variable_selection( catalogue: VariableCatalogue | pandas.DataFrame | object, declaration: Mapping[str, object], *, member_groups: Mapping[str, MemberGroup | Mapping[str, object]] | None = None, require_explicit_varying_dimensions: bool = False) -> ResolvedVariableSelection:

Resolve one exact or selector-based variable declaration.

Matching variables always retain catalogue order. When require_explicit_varying_dimensions is true, every dimension that varies after filtering must appear in the ordered selectors so a later chart splitter has an unambiguous grouping priority.

def resolve_variables( catalogue: VariableCatalogue | pandas.DataFrame | object, declaration: Mapping[str, object], *, member_groups: Mapping[str, MemberGroup | Mapping[str, object]] | None = None, require_explicit_varying_dimensions: bool = False) -> tuple[str, ...]:

Resolve a declaration to exact names in stable catalogue order.

def run_baseline( source_path: pathlib.Path, *, run_options: BaselineRunOptions | None = None) -> None:

Solve or load a model, produce baseline projections, and report them.

def run_experiment( source_path: pathlib.Path, *, run_options: ExperimentRunOptions | None = None, validate_baseline: Callable[[gcubed.projections.baseline_projections.BaselineProjections], None] | None = None) -> None:

Run one standard experiment with an optional local closure validator.

def run_setup( source_path: pathlib.Path, *, run_options: BaselineRunOptions | ExperimentRunOptions | None = None) -> None:

Run a standard baseline or experiment selected by its setup kind.