Skip to content

Cloud API

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.

Result caching

Passing check_cache=True to sim.run() looks for a completed cloud job with byte-identical inputs and reuses its results instead of submitting a new job:

sp = sim.run(check_cache=True)

The cache key is derived from the files written by write_config() — the same bytes the solver consumes — rather than from the simulation object, so it also covers changes to the generated solver script. A lookup failure is never fatal: it degrades to a normal submit.

check_cache 

check_cache(job_type: str, input_hash: str) -> str | None

Look up a previously completed job with identical inputs.

Never raises: a cache lookup is an optimization, so an unsupported SDK, a transient network error, or a server error all degrade to a miss and the caller submits the job normally. Those degraded paths are logged at WARNING — silently returning a miss makes a permanently broken lookup indistinguishable from a cold cache.

Parameters:

  • job_type (str) –

    Solver name, e.g. "meep" or "palace".

  • input_hash (str) –

    Value from :func:gsim.hashing.compute_input_hash.

Returns:

  • str | None –

    job_id of the cached job, or None on a miss.

check_cache_for_dir 

check_cache_for_dir(input_dir: str | Path, job_type: str) -> tuple[str, str | None]

Hash a prepared input directory and look it up in the cloud cache.

Parameters:

  • input_dir (str | Path) –

    Directory holding the files that would be uploaded.

  • job_type (str) –

    Solver name, e.g. "meep" or "palace".

Returns:

  • str –

    (input_hash, job_id) where job_id is None on a cache

  • str | None –

    miss. The hash is returned either way so the caller can pass it to

  • tuple[str, str | None] –

    func:upload and populate the cache for the next run.

compute_input_hash 

compute_input_hash(input_dir: str | Path, job_type: str) -> str

Compute the cloud cache key for a prepared simulation input directory.

Folds the solver name and the gsim version into the directory digest. Including the gsim version is deliberately conservative: gsim generates the solver driver script, so an upgrade may change results even when the written inputs are byte-identical. It can be dropped once the server-side key includes the solver image version.

Parameters:

  • input_dir (str | Path) –

    Directory holding the files that will be uploaded.

  • job_type (str) –

    Solver name, e.g. "meep" or "palace".

Returns:

  • str –

    "sha256:<hex>" — the value to pass as input_hash.

Raises:

Example

compute_input_hash("./sim", "meep") # doctest: +SKIP 'sha256:6a1f...'