Skip to content

Run Execution

The experiment launcher is graphids.exp.run. It accepts a typed RunConfig, constructs Ray TorchTrainer directly, and runs the worker loop that builds data/model/trainer objects from YAML config.

Current stages:

  • fit / test -> Lightning trainer launch with config-driven data/model instantiation, Ray Lightning strategy/environment, and Ray checkpoint/metric reporting.

Ray normally uses its report callback for checkpointing. Supplying a Lightning ModelCheckpoint callback also enables Lightning checkpointing by default; an explicit trainer.enable_checkpointing setting takes precedence.

Sha256ModelCheckpoint(save_last=True) saves the latest eligible epoch even when its monitored score ties or regresses. Best-checkpoint selection remains separate, and every saved checkpoint has a SHA256 sidecar.

graphids.exp.run

run

Construct and execute one validated run locally or through Ray Train.

build_component

build_component(spec: Any) -> Any

Build a component config, or return an instantiated class-path object.

build is the optional construction hook at this config boundary. Errors from the builder propagate unchanged.

Source code in graphids/exp/run.py
def build_component(spec: Any) -> Any:
    """Build a component config, or return an instantiated class-path object.

    ``build`` is the optional construction hook at this config boundary.
    Errors from the builder propagate unchanged.
    """
    resolved = resolve_spec(spec)
    builder = getattr(resolved, "build", None)
    return builder() if builder is not None else resolved

execute_run

execute_run(run: RunConfig, *, ray: bool = False) -> dict[str, Any]

Own the run lifecycle; tracking and Ray consume the saved result.

Source code in graphids/exp/run.py
def execute_run(run: RunConfig, *, ray: bool = False) -> dict[str, Any]:
    """Own the run lifecycle; tracking and Ray consume the saved result."""
    writer = True
    if ray:
        from ray import train

        writer = train.get_context().get_world_rank() == 0
    logger = None
    mode = tracking_mode()
    if writer:
        write_config(run)
        record_status(run, "running", message="worker_started", tracking_mode=mode)
    try:
        if (
            run.resources.accelerator == "gpu"
            and run.payload.model.get("type") == "event_graph_mamba"
            and run.payload.model.get("backend", "official") == "official"
        ):
            from graphids.runtime_checks import assert_mamba_backend

            assert_mamba_backend()
        if writer and mode == "online":
            logger = make_logger(run)
        result = run_lightning(run, logger=logger, ray=ray)
        if writer:
            record_status(run, "finished", result=result)
        if logger is not None and logger.run_id is not None:
            logger.experiment.set_terminated(logger.run_id, status="FINISHED")
        return result
    except BaseException as exc:
        if writer:
            record_status(run, "failed", failure=f"{type(exc).__name__}: {exc}")
        if logger is not None and logger.run_id is not None:
            logger.experiment.set_terminated(logger.run_id, status="FAILED")
        raise

launch_run

launch_run(run: RunConfig, *, address: str | None = None) -> RunSummary

Launch the supported single-worker run in a local or allocated Ray cluster.

Source code in graphids/exp/run.py
def launch_run(run: RunConfig, *, address: str | None = None) -> RunSummary:
    """Launch the supported single-worker run in a local or allocated Ray cluster."""
    try:
        import ray
        from ray.train import RunConfig as RayRunConfig
        from ray.train import ScalingConfig
        from ray.train.torch import TorchTrainer
    except ModuleNotFoundError as exc:
        raise RuntimeError(
            "Ray is not installed. Install the project dependencies before launching experiments."
        ) from exc

    try:
        if not ray.is_initialized():
            ray.init(address=address, ignore_reinit_error=True)
        resources = run.resources
        use_gpu = resources.accelerator == "gpu" or resources.gpus_per_worker > 0
        worker_resources = {"CPU": max(1, resources.cpus_per_worker)}
        if use_gpu:
            worker_resources["GPU"] = resources.gpus_per_worker or 1
        TorchTrainer(
            _worker_loop,
            train_loop_config={"run": run.model_dump(mode="json")},
            scaling_config=ScalingConfig(
                num_workers=1,
                use_gpu=use_gpu,
                resources_per_worker=worker_resources,
            ),
            run_config=RayRunConfig(
                storage_path=str(run.outputs.run_dir.parent),
                name=run.outputs.run_dir.name,
            ),
        ).fit()
    except BaseException as exc:
        manifest = load_manifest(run.outputs.run_dir, name=run.outputs.manifest_name)
        if manifest is None or manifest.status != "failed":
            write_config(run)
            record_status(
                run,
                "failed",
                failure=f"{type(exc).__name__}: {exc}",
                tracking_mode=tracking_mode(),
            )
        raise
    summary = summarize_run(run.outputs.run_dir)
    if summary is None:
        raise RuntimeError(
            f"Ray run finished without a GraphIDS manifest: {run.outputs.run_dir}"
        )
    return summary

probe_ray_train_imports

probe_ray_train_imports() -> dict[str, str]

Import the Ray APIs GraphIDS relies on and return their module paths.

Source code in graphids/exp/run.py
def probe_ray_train_imports() -> dict[str, str]:
    """Import the Ray APIs GraphIDS relies on and return their module paths."""
    try:
        from ray.train import RunConfig as RayRunConfig
        from ray.train import ScalingConfig
        from ray.train.lightning import (
            RayDDPStrategy,
            RayLightningEnvironment,
            RayTrainReportCallback,
            prepare_trainer,
        )
        from ray.train.torch import TorchTrainer
    except ModuleNotFoundError as exc:
        raise RuntimeError(
            "Ray is not installed. Install the project dependencies before launching experiments."
        ) from exc

    return {
        "RunConfig": RayRunConfig.__module__,
        "ScalingConfig": ScalingConfig.__module__,
        "TorchTrainer": TorchTrainer.__module__,
        "prepare_trainer": prepare_trainer.__module__,
        "RayDDPStrategy": RayDDPStrategy.__module__,
        "RayLightningEnvironment": RayLightningEnvironment.__module__,
        "RayTrainReportCallback": RayTrainReportCallback.__module__,
    }

resolve_spec

resolve_spec(spec: Any) -> Any

Resolve a nested component/class-path spec without calling build().

Source code in graphids/exp/run.py
def resolve_spec(spec: Any) -> Any:
    """Resolve a nested component/class-path spec without calling ``build()``."""
    if isinstance(spec, BaseModel):
        spec = spec.model_dump(mode="json")
    if isinstance(spec, list):
        return [resolve_spec(item) for item in spec]
    if not isinstance(spec, Mapping):
        return spec
    if "class_path" in spec:
        class_path = str(spec["class_path"])
        module_path, _, class_name = class_path.rpartition(".")
        cls = getattr(importlib.import_module(module_path), class_name)
        init_args = {
            k: resolve_spec(v) for k, v in dict(spec.get("init_args") or {}).items()
        }
        return cls(**init_args)

    if "type" in spec:
        match spec["type"]:
            case "can_event_dm":
                from graphids.data.config import CANEventDataConfig

                config_class = CANEventDataConfig
            case "event_graph_mamba":
                from graphids.models.config import EventGraphMambaConfig

                config_class = EventGraphMambaConfig
            case _:
                raise ValueError(f"unknown component type: {spec['type']!r}")
        return config_class.model_validate(
            {k: resolve_spec(v) for k, v in spec.items()}
        )

    return {k: resolve_spec(v) for k, v in spec.items()}

execute_run also supports local Lightning diagnostics. records owns durable status/results; tracking owns MLflow exports. Execution is limited to one node/device, matching the active event contract.