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], ...] = (), version: int | str = 1, first_result_year: int | None = None, last_result_year: int | None = None, table_of_contents: bool = False, sector_selection_dimensions: tuple[str, ...] = (), sector_selection_include_default: bool = False, 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], ...] = ()

version: int | str = 1

first_result_year: int | None = None

last_result_year: int | None = None

table_of_contents: bool = False

sector_selection_dimensions: tuple[str, ...] = ()

sector_selection_include_default: bool = False

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.

Inherited Members

collections.abc.Mapping: get; keys; items; values

class SetupConfigurationError(builtins.ValueError):

Raised when a setup configuration violates its public contract.

Inherited Members

builtins.BaseException: BaseException; with_traceback; add_note; args

@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'>

Inherited Members

enum.Enum: name; value
builtins.str: encode; replace; split; rsplit; join; capitalize; casefold; title; center; count; expandtabs; find; partition; index; ljust; lower; lstrip; rfind; rindex; rjust; rstrip; rpartition; splitlines; strip; swapcase; translate; upper; startswith; endswith; removeprefix; removesuffix; isascii; islower; isupper; istitle; isspace; isdecimal; isdigit; isnumeric; isalpha; isalnum; isidentifier; isprintable; zfill; format; format_map; maketrans

@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.

Inherited Members

builtins.BaseException: BaseException; with_traceback; add_note; args

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'>

Inherited Members

enum.Enum: name; value
builtins.str: encode; replace; split; rsplit; join; capitalize; casefold; title; center; count; expandtabs; find; partition; index; ljust; lower; lstrip; rfind; rindex; rjust; rstrip; rpartition; splitlines; strip; swapcase; translate; upper; startswith; endswith; removeprefix; removesuffix; isascii; islower; isupper; istitle; isspace; isdecimal; isdigit; isnumeric; isalpha; isalnum; isidentifier; isprintable; zfill; format; format_map; maketrans

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 = (), derivations: gcubed.derivations.Derivations | None = None) -> 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.