I/O & Config

YAML configuration loading, validation, and run artifact management.

Config Loader

config_loader

YAML config loading with Pydantic v2 validation.

All configuration sections are Pydantic BaseModel subclasses loaded from a YAML file via :func:load_config. Fields use SI units where applicable and match the names used in the corresponding core datamodels.

ProjectConfig

Bases: BaseModel

Top-level project configuration combining all sections.

ProjectSection

Bases: BaseModel

Project metadata and output settings.

ScenarioSection

Bases: BaseModel

Link scenario configuration (frequency, bandwidth, polarization).

TerminalSection

Bases: BaseModel

Single terminal definition (ground station or satellite).

TerminalsSection

Bases: BaseModel

TX and RX terminal pair.

AntennaSection

Bases: BaseModel

TX and RX antenna configuration pair.

AntennaEndConfig

Bases: BaseModel

Antenna configuration for one end of the link (TX or RX).

ParametricAntennaConfig

Bases: BaseModel

Configuration for a fixed-gain parametric antenna.

PamAntennaConfig

Bases: BaseModel

Configuration for a PAM phased-array antenna.

CouplingConfig

Bases: BaseModel

EdgeFEM mutual-coupling configuration.

RFChainSection

Bases: BaseModel

RF chain configuration (power, losses, noise, optional cascaded stages).

RFStageConfig

Bases: BaseModel

Configuration for a single RF stage in a cascaded chain.

PropagationSection

Bases: BaseModel

Propagation model configuration with optional composite components.

PropagationComponentConfig

Bases: BaseModel

Configuration for a single propagation loss component.

ModemSection

Bases: BaseModel

Modem configuration (DVB-S2 ModCod table and ACM policy).

WorldSection

Bases: BaseModel

World/mission simulation configuration (time window, trajectory).

WorldOpsPolicy

Bases: BaseModel

Operational policy constraints for world simulation.

ReportsSection

Bases: BaseModel

Report generation settings.

PayloadSection

Bases: BaseModel

Multi-beam payload configuration (beams, grid, beam selection).

BeamConfig

Bases: BaseModel

Configuration for a single beam in a multi-beam payload.

CosineAntennaConfig

Bases: BaseModel

Configuration for a cosine-rolloff antenna pattern.

load_config

load_config(path)

Load and validate a YAML config file.

Parameters:

Name	Type	Description	Default
path	str or Path	Path to the YAML configuration file.	required

Returns:

Type	Description
ProjectConfig	Validated project configuration.

Raises:

Type	Description
ValidationError	If the YAML content fails schema validation.

Source code in src/opensatcom/io/config_loader.py

def load_config(path: str | Path) -> ProjectConfig:
    """Load and validate a YAML config file.

    Parameters
    ----------
    path : str or Path
        Path to the YAML configuration file.

    Returns
    -------
    ProjectConfig
        Validated project configuration.

    Raises
    ------
    pydantic.ValidationError
        If the YAML content fails schema validation.
    """
    with open(path) as f:
        raw = yaml.safe_load(f)
    return ProjectConfig.model_validate(raw)

Run Context

RunContext

RunContext(output_dir='./runs', run_id='')

Manages a run output directory and artifact saving.

Creates a timestamped directory under output_dir and provides convenience methods for persisting configs, results, and plots.

Parameters:

Name	Type	Description	Default
output_dir	str	Base output directory (default "./runs").	'./runs'
run_id	str	Optional identifier appended to the directory name.	''

Source code in src/opensatcom/io/workspace.py

def __init__(self, output_dir: str = "./runs", run_id: str = "") -> None:
    timestamp = datetime.now(timezone.utc).strftime("%Y%m%d_%H%M%S")
    suffix = f"_{run_id}" if run_id else ""
    self.run_dir = Path(output_dir) / f"run_{timestamp}{suffix}"
    self.plots_dir = self.run_dir / "plots"
    self.run_dir.mkdir(parents=True, exist_ok=True)
    self.plots_dir.mkdir(exist_ok=True)

beam_maps_dir property

beam_maps_dir

Directory for beam map artifacts (created on first access).

save_config_snapshot

save_config_snapshot(config)

Save config snapshot as YAML.

Parameters:

Name	Type	Description	Default
config	dict	Configuration dictionary to serialise.	required

Returns:

Type	Description
Path	Path to the saved YAML file.

Source code in src/opensatcom/io/workspace.py

def save_config_snapshot(self, config: dict[str, Any]) -> Path:
    """Save config snapshot as YAML.

    Parameters
    ----------
    config : dict
        Configuration dictionary to serialise.

    Returns
    -------
    Path
        Path to the saved YAML file.
    """
    path = self.run_dir / "config_snapshot.yaml"
    with open(path, "w") as f:
        yaml.dump(config, f, default_flow_style=False, sort_keys=False)
    return path

save_results_parquet

save_results_parquet(df)

Save results as parquet.

Parameters:

Name	Type	Description	Default
df	DataFrame	Results DataFrame.	required

Returns:

Type	Description
Path	Path to the saved parquet file.

Source code in src/opensatcom/io/workspace.py

def save_results_parquet(self, df: pd.DataFrame) -> Path:
    """Save results as parquet.

    Parameters
    ----------
    df : pandas.DataFrame
        Results DataFrame.

    Returns
    -------
    Path
        Path to the saved parquet file.
    """
    path = self.run_dir / "results.parquet"
    df.to_parquet(path, index=False)
    return path

save_breakdown_csv

save_breakdown_csv(df)

Save link breakdown as CSV.

Parameters:

Name	Type	Description	Default
df	DataFrame	Breakdown DataFrame.	required

Returns:

Type	Description
Path	Path to the saved CSV file.

Source code in src/opensatcom/io/workspace.py

def save_breakdown_csv(self, df: pd.DataFrame) -> Path:
    """Save link breakdown as CSV.

    Parameters
    ----------
    df : pandas.DataFrame
        Breakdown DataFrame.

    Returns
    -------
    Path
        Path to the saved CSV file.
    """
    path = self.run_dir / "link_breakdown.csv"
    df.to_csv(path, index=False)
    return path

save_beammap_parquet

save_beammap_parquet(df)

Save beam map results as parquet.

Parameters:

Name	Type	Description	Default
df	DataFrame	Beam map DataFrame from BeamMap.to_dataframe().	required

Returns:

Type	Description
Path	Path to the saved parquet file.

Source code in src/opensatcom/io/workspace.py

def save_beammap_parquet(self, df: pd.DataFrame) -> Path:
    """Save beam map results as parquet.

    Parameters
    ----------
    df : pandas.DataFrame
        Beam map DataFrame from ``BeamMap.to_dataframe()``.

    Returns
    -------
    Path
        Path to the saved parquet file.
    """
    path = self.beam_maps_dir / "beam_map.parquet"
    df.to_parquet(path, index=False)
    return path