Utility Functions

This page documents utility functions available as a Python API.

Copying Experiments

The experimaestro.copy_experiment module provides functions to copy experiments between workspaces (local or remote via SSH). This is the same logic used by the experiments copy CLI command.

Quick Start

from experimaestro.copy_experiment import copy_experiment
from experimaestro.settings import get_workspace

src = get_workspace("cluster", include_remote=True)
dst = get_workspace("local")
result = copy_experiment(src, dst, "my_experiment", "20260121_105710")
print(f"Copied {result.jobs_copied} jobs, skipped {result.jobs_skipped}")
if result.errors:
    print(f"Errors: {result.errors}")

What Gets Copied

  • The experiment run directory (experiments/<id>/<run_id>/) — metadata, events, configs

  • All job directories referenced in jobs.jsonl — outputs, logs, params

  • Jobs that already exist at the destination are skipped

Path Rewriting

Since experimaestro 2.4, paths inside params.json objects are stored relative to the job root or workspace (see serialization), so they survive a copy without any rewriting. The top-level "workspace" field is still rewritten to point to the destination workspace, and entries written by older versions (absolute {"type": "path", "value": "/..."}) are rewritten as before for backward compatibility.

Atomic Staging

Each job is first rsynced into a temporary staging directory (.xpm-staging/) inside the destination workspace, then moved to its final location. This prevents partial copies from leaving broken state.

API Reference

class experimaestro.copy_experiment.CopyResult(jobs_copied: int = 0, jobs_skipped: int = 0, errors: list[str] = <factory>)

Result of a copy_experiment operation.

experimaestro.copy_experiment.copy_experiment(src_workspace: WorkspaceSettings, dst_workspace: WorkspaceSettings, experiment_id: str, run_id: str, dry_run: bool = False) → CopyResult

Copy an experiment run and its jobs from source to destination workspace.

Each job directory is first rsynced into a staging area inside the destination workspace, then atomically moved to its final location. Workspace-dependent paths in params.json are rewritten after copy.

Parameters:

  • src_workspace – Source workspace settings.

  • dst_workspace – Destination workspace settings.

  • experiment_id – The experiment identifier.

  • run_id – The resolved run ID (not "current").

  • dry_run – If True, show what would be copied without actually copying.

Returns:

A CopyResult with counts of copied/skipped jobs and any errors.

experimaestro.copy_experiment.list_experiments(ws: WorkspaceSettings) → list[str]

List experiment IDs in a workspace.

experimaestro.copy_experiment.list_runs(ws: WorkspaceSettings, experiment_id: str) → list[str]

List run IDs for an experiment in a workspace.

experimaestro.copy_experiment.resolve_current_run(ws: WorkspaceSettings, experiment_id: str) → str | None

Resolve the current symlink for an experiment.

Returns the run_id string, or None if no current symlink exists.

experimaestro.copy_experiment.format_run_id(run_id: str) → str

Format a run ID like 20260118_170744 into 2026-01-18 17:07:44.

Returns run_id unchanged if it doesn’t match the expected format.

experimaestro.copy_experiment.read_jobs_jsonl(ws: WorkspaceSettings, experiment_id: str, run_id: str) → list[ExperimentJobInformation]

Read jobs.jsonl from a workspace (local or remote).

experimaestro.copy_experiment.resolve_workspace_path(ws: WorkspaceSettings) → str

Get the absolute workspace path (resolving ~ for remote).