Cloud

Previous

run_simulation 

run_simulation(
    config_dir: str | Path,
    job_type: Literal["palace", "meep"] = "palace",
    verbose: bool = True,
    on_started: Callable | None = None,
    parent_dir: str | Path | None = None,
) -> RunResult

Run a simulation on GDSFactory+ cloud (blocking).

This function handles the complete workflow: 1. Uploads simulation files from config_dir 2. Starts the simulation job 3. Creates a structured directory sim-data-{job_name}/ with input/ (config files) and output/ (results) sub-dirs 4. Waits for completion 5. Downloads results into output/

Parameters:

  • config_dir (str | Path) –

    Directory containing the simulation config files.

  • job_type (Literal['palace', 'meep'], default: 'palace' ) –

    Type of simulation (default: "palace").

  • verbose (bool, default: True ) –

    Print progress messages (default True).

  • on_started (Callable | None, default: None ) –

    Optional callback called with job object when simulation starts.

  • parent_dir (str | Path | None, default: None ) –

    Where to create the sim directory. Defaults to the current working directory.

Returns:

  • RunResult –

    RunResult with sim_dir, files dict, and job_name.

Raises:

Example
result = gcloud.run_simulation("./sim", job_type="palace")
Uploading simulation... done
Job started: palace-abc123
Waiting for completion... done (2m 34s)
Downloading results... done
print(result.sim_dir)
sim-data-palace-abc123/

get_status 

get_status(job_id: str) -> str

Get the current status of a cloud job.

Parameters:

  • job_id (str) –

    Job identifier.

Returns:

  • str –

    Status string — one of "created", "queued",

  • str –

    "running", "completed", "failed".

wait_for_results 

wait_for_results(
    *job_ids: str,
    verbose: Literal["quiet", "status", "full"] = "status",
    parent_dir: str | Path | None = None,
    poll_interval: float = 5.0,
) -> Any

Wait for one or more jobs to finish, then download and parse results.

Accepts job IDs as positional args or a single list/tuple::

wait_for_results(id1, id2)
wait_for_results([id1, id2])

For a single job, returns the parsed result directly. For multiple jobs, returns a list of results (same order as input).

Parameters:

  • *job_ids (str, default: () ) –

    One or more job ID strings, or a single list/tuple of IDs.

  • verbose (Literal['quiet', 'status', 'full'], default: 'status' ) –

    Output mode: "quiet" — no output. "status" — status line only (default). "full" — stream solver logs live (timestamps stripped).

  • parent_dir (str | Path | None, default: None ) –

    Where to create sim-data directories (default: cwd).

  • poll_interval (float, default: 5.0 ) –

    Seconds between status polls (default 5.0).

Returns:

  • Any –

    Parsed result (single job) or list of parsed results (multiple jobs).

RunResult dataclass 

RunResult(sim_dir: Path, files: dict[str, Path] = dict(), job_name: str = '')

Result of a cloud simulation run.

Attributes:

  • sim_dir (Path) –

    Root directory ({job_type}_{job_name}/).

  • files (dict[str, Path]) –

    Flat mapping of filename → Path inside output/.

  • job_name (str) –

    Cloud job identifier.

Common