simulo 0.26.0__py3-none-any.whl

simulo/_client/templates/training/app.py.tmpl

@@ -0,0 +1,235 @@
+"""{{APP_NAME}} — a Simulo training app (scaffolded by `simulo create`).
+
+Balances a pole on a cart with PPO, out of the box. Submit it with::
+
+    simulo run app.py --num-envs 4096 --max-iterations 200
+
+The CLI maps each ``--flag`` onto ``train``'s own parameters — no extra
+boilerplate; run with no flags to use the defaults. Submitting only
+writes/uploads the job — it does NOT train on this machine. Once logged in
+(``simulo login``), the SAME command uploads and runs this on the Simulo cloud
+instead, following its logs automatically.
+
+WHERE TO EDIT
+-------------
+* ``{{APP_NAME}}Task`` — ``build()`` the scene and write the observation / reward /
+  termination logic for your own robot and task.
+* ``train`` (the ``@app.job``) — training hyperparameters and what gets returned;
+  its parameters ARE the app's CLI flags (``num_envs`` -> ``--num-envs``).
+"""
+
+from __future__ import annotations
+
+import math
+from typing import Any, Tuple
+
+import simulo
+
+# The cartpole robot — a global-catalog asset. Swap the ref for your own robot
+# (``simulo asset publish`` your own USD/URDF, or browse the catalog with
+# ``simulo asset list --global``).
+cartpole = simulo.Asset.from_registry("simulo/robot/cartpole:v1")
+
+# A named, durable, writable volume for the trained checkpoint (created on first
+# use). Locally the runner backs it with ~/.simulo/volumes/{{APP_NAME}}-checkpoints/;
+# ``vol.path`` only resolves inside a running job (execution mode).
+vol = simulo.Volume.from_name("{{APP_NAME}}-checkpoints", create_if_missing=True)
+
+# Advanced: pick a different Simulo runtime — App("name", runtime=simulo.Runtime.from_registry("simulo/gpu-rl:2026.06")). See the Runtimes docs.
+app = simulo.App("{{APP_NAME}}", mounts={"/out": vol})
+
+# The ONE module-level heavy import, deferred under the runtime guard so submit
+# records it as a remote import instead of resolving it.
+with app.runtime.imports():
+    import torch  # noqa: F401  (resolved only in execution mode, on the worker)
+
+
+@app.runtime.torch_jit
+def _compute_rewards(
+    rew_scale_alive: float,
+    rew_scale_terminated: float,
+    rew_scale_pole_pos: float,
+    rew_scale_cart_vel: float,
+    rew_scale_pole_vel: float,
+    pole_pos: torch.Tensor,
+    pole_vel: torch.Tensor,
+    cart_pos: torch.Tensor,
+    cart_vel: torch.Tensor,
+    reset_terminated: torch.Tensor,
+) -> torch.Tensor:
+    """JIT-compiled reward kernel. EDIT: score your own task here."""
+    pole_pos = pole_pos.squeeze()
+    pole_vel = pole_vel.squeeze()
+    cart_pos = cart_pos.squeeze()
+    cart_vel = cart_vel.squeeze()
+    reset_terminated = reset_terminated.squeeze()
+
+    rew_alive = rew_scale_alive * (1.0 - reset_terminated.float())
+    rew_termination = rew_scale_terminated * reset_terminated.float()
+    rew_pole_pos = rew_scale_pole_pos * torch.square(pole_pos)
+    rew_cart_vel = rew_scale_cart_vel * torch.abs(cart_vel)
+    rew_pole_vel = rew_scale_pole_vel * torch.abs(pole_vel)
+
+    reward: torch.Tensor = rew_alive + rew_termination + rew_pole_pos + rew_cart_vel + rew_pole_vel
+    # Keep the (num_envs,) per-env reward contract even when num_envs == 1.
+    return reward.view(-1)
+
+
+class {{APP_NAME}}Task(simulo.Task):
+    """Balance a pole on a cart. EDIT: replace with your own robot and task.
+
+    Observation (4-dim): pole angle, pole angular velocity, cart position, cart
+    velocity. Action (1-dim): scaled horizontal force on the cart.
+    """
+
+    observation_dim = 4
+    action_dim = 1
+
+    episode_length_s = 5.0
+    action_scale = 100.0  # [N]
+
+    max_cart_pos = 3.0  # [m]
+    initial_pole_angle_range = (-0.25, 0.25)  # fraction of pi [rad]
+
+    rew_scale_alive = 1.0
+    rew_scale_terminated = -2.0
+    rew_scale_pole_pos = -1.0
+    rew_scale_cart_vel = -0.01
+    rew_scale_pole_vel = -0.005
+
+    # Framework-injected at runtime by ``simulo.core.Task`` / ``LearningEnv``
+    # (declared here only so the type checker sees the names the methods read;
+    # the annotations are PEP 563 strings and never shadow the inherited values).
+    device: str
+    max_episode_length: int
+    episode_length_buf: torch.Tensor
+    reset_terminated: torch.Tensor
+
+    def build(self, scene: simulo.Scene) -> None:
+        # EDIT: swap the ground / light / robot below for your own scene.
+        scene.add(simulo.Terrain.plane(name="ground"), at="/", per_environment=False)
+        scene.add(
+            simulo.Light.dome(name="light", intensity=2000.0, color=(0.75, 0.75, 0.75)),
+            at="/",
+            per_environment=False,
+        )
+        self.robot = simulo.Robot(asset=cartpole, initial_pose=simulo.Pose.identity())
+        scene.add(self.robot, at="/World/Robot")
+
+    def on_start(self, env: simulo.LearningEnv) -> None:
+        self._cart_dof_idx = self.robot.find_joints("slider_to_cart")
+        self._pole_dof_idx = self.robot.find_joints("cart_to_pole")
+        # robot.state is the supported, typed way to read live state (robot.internals
+        # is the unstable engine escape hatch — see the Scene, Robot & World docs).
+        self._joint_pos = self.robot.state.joint_positions
+        self._joint_vel = self.robot.state.joint_velocities
+
+    def get_observations(self) -> torch.Tensor:
+        # EDIT: return your own observation vector.
+        pole_idx = self._pole_dof_idx[0]
+        cart_idx = self._cart_dof_idx[0]
+        pole_pos = self._joint_pos[:, pole_idx].view(-1, 1)
+        pole_vel = self._joint_vel[:, pole_idx].view(-1, 1)
+        cart_pos = self._joint_pos[:, cart_idx].view(-1, 1)
+        cart_vel = self._joint_vel[:, cart_idx].view(-1, 1)
+        return torch.cat((pole_pos, pole_vel, cart_pos, cart_vel), dim=-1)
+
+    def get_rewards(self) -> torch.Tensor:
+        return _compute_rewards(
+            self.rew_scale_alive,
+            self.rew_scale_terminated,
+            self.rew_scale_pole_pos,
+            self.rew_scale_cart_vel,
+            self.rew_scale_pole_vel,
+            self._joint_pos[:, self._pole_dof_idx[0]],
+            self._joint_vel[:, self._pole_dof_idx[0]],
+            self._joint_pos[:, self._cart_dof_idx[0]],
+            self._joint_vel[:, self._cart_dof_idx[0]],
+            self.reset_terminated,
+        )
+
+    def get_dones(self) -> Tuple[torch.Tensor, torch.Tensor]:
+        # EDIT: your own termination condition.
+        self._joint_pos = self.robot.state.joint_positions
+        self._joint_vel = self.robot.state.joint_velocities
+        pole_idx = self._pole_dof_idx[0]
+        cart_idx = self._cart_dof_idx[0]
+        truncated = self.episode_length_buf >= self.max_episode_length - 1
+        cart_out = torch.abs(self._joint_pos[:, cart_idx]) > self.max_cart_pos
+        pole_fallen = torch.abs(self._joint_pos[:, pole_idx]) > math.pi / 2
+        terminated = cart_out | pole_fallen
+        return terminated, truncated
+
+    def apply_actions(self, actions: torch.Tensor) -> None:
+        self.robot.set_joint_effort_target(self.action_scale * actions, joint_ids=self._cart_dof_idx)
+
+    def reset_idx(self, env_ids: torch.Tensor) -> None:
+        num_resets = len(env_ids)
+        if num_resets == 0:
+            return
+        self.robot.reset(env_ids)
+        pole_idx = self._pole_dof_idx[0]
+        # robot.state has no default-joint-value equivalent, so this stays on the
+        # internals escape hatch (there is nothing unstable about reading it here,
+        # just no supported, typed name for it yet).
+        joint_pos = self.robot.internals.default_joint_pos[env_ids].clone()
+        random_angles = torch.empty(num_resets, device=self.device).uniform_(
+            self.initial_pole_angle_range[0] * math.pi,
+            self.initial_pole_angle_range[1] * math.pi,
+        )
+        joint_pos[:, pole_idx] += random_angles
+        # set_joint_state writes both positions and velocities through the engine's
+        # own command path (Articulation.write_joint_state_to_sim ->
+        # write_joint_{position,velocity}_to_sim), which updates robot.state's
+        # backing buffers in place AND pushes to the physics view in the same call.
+        # self._joint_pos / self._joint_vel are the SAME objects as those buffers
+        # (the hold-safety contract on core/robot.py), so they are already current
+        # after this call — no separate write into either tensor is needed, and
+        # robot.state's contract is never write into a member's tensor directly.
+        joint_vel = self.robot.internals.default_joint_vel[env_ids]
+        self.robot.set_joint_state(joint_pos, velocities=joint_vel, env_ids=env_ids)
+
+
+# Retries are safe: ResumableCheckpoint declares periodic checkpoints (every 50
+# iterations) and resume defaults to "auto", so a retried / preempted run resumes
+# from the latest checkpoint instead of restarting.
+# system= picks a GPU tier from the published catalog; run `simulo systems` to see them.
+@app.job(
+    system=simulo.SystemType.TIER_1,
+    timeout=8 * 60 * 60,
+    retries=2,
+    callbacks=[simulo.callbacks.ResumableCheckpoint(every=50)],
+)
+def train(num_envs: int = 4096, max_iterations: int = 200) -> dict[str, Any]:
+    """Train a policy with PPO and save the checkpoint. EDIT: swap the trainer/algorithm.
+
+    Args:
+        num_envs: Number of parallel environments to simulate.
+        max_iterations: Number of PPO policy-update iterations.
+
+    Returns:
+        A JSON-serialisable dict: the saved ``checkpoint`` path plus training stats.
+    """
+    env = simulo.LearningEnv(
+        task={{APP_NAME}}Task(),
+        num_envs=num_envs,
+        device="cuda",
+        dt=1.0 / 120.0,
+        physics_steps_per_action=2,
+        env_spacing=4.0,
+        headless=True,
+        seed=42,
+    )
+    trainer = simulo.RLTrainer(env=env, algorithm="PPO", device="cuda", seed=42)
+
+    stats = trainer.train(max_iterations=max_iterations)
+
+    # Persist the trained policy to the durable volume (resolved in execution mode).
+    checkpoint = f"{vol.path}/{{APP_NAME}}_final.pt"
+    trainer.save(checkpoint)
+
+    # Close the trainer before the environment so skrl releases its resources first.
+    trainer.close()
+    env.close()
+
+    return {"checkpoint": checkpoint, "num_envs": num_envs, **stats}

simulo/_client/templates/training/simuloignore.tmpl

@@ -0,0 +1,29 @@
+# Gitignore-style excludes for `simulo run` / `simulo create --type training`'s
+# {{APP_NAME}}. Applied on top of the packager's own built-in excludes (assets/,
+# datasets/, checkpoints/, outputs/, logs/, .git/, __pycache__/, .simulo/, and
+# *.usd(a|c)/*.pt/*.pth/*.onnx/*.mcap/*.mp4/*.pyc) — the extra patterns below cover
+# things that default set does not.
+
+# Trained checkpoints and exported policies (already written to a Volume via
+# vol.path — never need to be part of the packaged source bundle).
+*.pt
+*.pth
+*.ckpt
+
+# Python virtual environments.
+.venv/
+venv/
+env/
+
+# Local secrets / environment overrides — never bundle these.
+.env
+.env.*
+
+# Editor / OS cruft.
+.DS_Store
+*.swp
+
+# Data blobs.
+*.npy
+*.npz
+data/

simulo/_client/view_fragment.py

@@ -0,0 +1,21 @@
+"""Dependency-free version-2 viewer-fragment builder shared by the CLI contract test."""
+
+from __future__ import annotations
+
+import urllib.parse
+
+
+def build_view_fragment_url(
+    viewer_url: str,
+    *,
+    session_token: str,
+    gateway_url: str,
+    job_id: str,
+) -> str:
+    """Build the exact frozen version-2 browser URL.
+
+    The launch secret rides the URL fragment, never the query string. The
+    names are an exact reconciliation contract with Console and viewer.
+    """
+    fragment = urllib.parse.urlencode({"launch": session_token, "gateway": gateway_url, "job": job_id, "v": "2"})
+    return f"{viewer_url}#{fragment}"

simulo/_client/view_session_api.py

@@ -0,0 +1,122 @@
+"""HTTP client for the live-view session mint endpoint (stdlib only, torch-free).
+
+Wire contract (live-visualization plan, control-plane half; see
+``simulo_control_plane.jobs.view_sessions.mint_view_session``):
+``POST /v1/jobs/{job_id}/view-session`` mints a short-lived (TTL <= 5 min)
+gateway-audience session for watching a running ``--viewstream`` job's live
+3D scene over the browser. Success (200) response body::
+
+    {"viewerUrl": "...", "gatewayUrl": "...", "sessionToken": "...", "expiresAt": "..."}
+
+Error responses use the standard ``{"error": {"code", "message", "request_id"}}``
+envelope. The PINNED codes this client's caller (the thin client's CLI module)
+depends on by name (do not rename without updating both sides) — all raised
+as :class:`ViewSessionApiHTTPError` with ``exc.code``/``exc.status`` set from
+the body/status:
+
+* 409 ``stream_endpoint_not_ready`` — the ONLY transient/retryable one: the
+  worker claim->registration gap, or a lapsed-lease-pending-reap window.
+* 409 ``job_not_running`` — the job is no longer running (a race after the
+  caller confirmed ``running``, or a job that finished between poll and mint).
+* 409 ``job_not_viewstream`` — the job was never submitted with ``--viewstream``.
+* 404 ``job_not_found`` — unknown or cross-org job id (anti-enumeration).
+  This is the mint route's ONLY pinned 404 code. The caller
+  (the thin client's ``_mint_view_session``) relies on that: by the time it
+  mints, ``get_job`` has already confirmed the job exists, so it treats any
+  OTHER 404 — e.g. Starlette's default unmatched-route 404 (wrapped in the
+  standard envelope with ``code == "Not Found"`` by the control plane's
+  global ``HTTPException`` handler) or a non-envelope 404 from a proxy in
+  front of it (``code == "http_error"``, this client's fallback code when
+  the body isn't the structured envelope) — as proof the ``/view-session``
+  route itself isn't deployed in this environment (e.g. prod, which is
+  staging-only for view sessions today), and degrades gracefully instead of
+  printing the raw ``code: message``.
+* 503 ``view_sessions_disabled`` — the control plane has view sessions
+  fail-closed disabled (its gateway service token is not configured, so the
+  live-view chain has nothing to talk to).
+* 429 ``rate_limit_exceeded`` — per-user mint rate limit (30/min).
+
+The route path is a LOCAL constant here rather than something imported from
+``simulo.interfaces.platform.runs`` — deliberately: PR3 owns the control
+plane's implementation (and any shared wire-contract module it lands
+alongside it), and this client codes directly against the exact path/response
+shape the plan specifies so the two PRs can land independently without a
+file-level merge conflict. Reconcile into a shared
+``simulo.interfaces.platform`` constant in a follow-up once PR3 has merged,
+if a shared module materializes.
+
+Shares request plumbing (structured-error parsing, the https-when-token
+guard, the foreign-host bearer rule) with ``jobs_api.py``/``submit_api.py``
+via ``http.py`` — one request path, not reimplemented a third time.
+"""
+
+from __future__ import annotations
+
+import urllib.parse
+from typing import Any, Optional
+
+from simulo._client import http
+from simulo.interfaces.platform.runs import JOB_SCOPE_MINE
+
+#: ``POST`` — mint a live-view session for a running ``--viewstream`` job.
+#: ``.format(job_id=...)``.
+VIEW_SESSION_ROUTE_TEMPLATE = "/v1/jobs/{job_id}/view-session"
+
+_REQUEST_TIMEOUT_S = 10.0  # every outbound call has an explicit timeout (NFR)
+_UNAVAILABLE_HINT = "Check SIMULO_API_URL / SIMULO_ENV, and that you are logged in (`simulo login`)."
+
+#: Required fields of a well-formed mint response (see module docstring).
+_REQUIRED_FIELDS = ("viewerUrl", "gatewayUrl", "sessionToken", "expiresAt")
+
+# Backward-compatible-style aliases — same convention as jobs_api.py /
+# submit_api.py: these are literally ``http.HttpError``/``http.HttpHTTPError``
+# (not new subclasses), so callers that already catch ``JobsApiError`` (also
+# ``http.HttpError``) catch these too without any extra wiring.
+ViewSessionApiError = http.HttpError
+ViewSessionApiHTTPError = http.HttpHTTPError
+
+
+class ViewSessionApiClient:
+    """Client for ``POST /v1/jobs/{job_id}/view-session``."""
+
+    def __init__(self, base_url: str, *, token: Optional[str] = None) -> None:
+        if not base_url.startswith(("http://", "https://")):
+            raise ViewSessionApiError(f"API base URL must be an http(s) URL, got {base_url!r}.")
+        self._base_url = base_url.rstrip("/")
+        self._token = token
+
+    @property
+    def base_url(self) -> str:
+        return self._base_url
+
+    def create_view_session(self, job_id: str, *, scope: str = JOB_SCOPE_MINE) -> dict[str, Any]:
+        """Mint a view session for *job_id*.
+
+        Raises :class:`ViewSessionApiHTTPError` on any non-2xx response — the
+        caller (the thin client's CLI module) distinguishes the ONE retryable
+        claim->registration-gap error CODE (``stream_endpoint_not_ready``,
+        pinned with PR3) from every other code (e.g. ``job_not_viewstream``,
+        which is also a 409 — classify by ``exc.code``, never by
+        ``exc.status`` alone), letting non-retryable ones propagate unchanged
+        so the server's own error message reaches the user.
+        """
+        path = VIEW_SESSION_ROUTE_TEMPLATE.format(job_id=http.quote_path_segment(job_id))
+        payload = http.request_json(
+            "POST",
+            self._base_url + path + "?" + urllib.parse.urlencode({"scope": scope}),
+            token=self._token,
+            api_base_url=self._base_url,
+            json_body={},
+            timeout=_REQUEST_TIMEOUT_S,
+            unavailable_hint=_UNAVAILABLE_HINT,
+        )
+        if not isinstance(payload, dict):
+            raise ViewSessionApiError("Malformed view-session response: expected a JSON object.")
+        # Security NIT: report only the MISSING field NAMES, never the raw
+        # payload — a malformed response could otherwise echo a partial
+        # sessionToken (or other sensitive value) into an exception message
+        # that ends up printed to the terminal or captured in a log.
+        missing = [field for field in _REQUIRED_FIELDS if field not in payload]
+        if missing:
+            raise ViewSessionApiError(f"Malformed view-session response: missing field(s) {missing}.")
+        return payload

simulo/_client/volume.py

@@ -0,0 +1,71 @@
+"""``Volume`` — a named, durable, writable mount (implements ``VolumeProtocol``).
+
+Locally a volume is a metadata handle. Its on-disk ``path`` only exists in
+execution mode, where the backend runner has created the directory and exported
+``SIMULO_VOLUME_<name>``.
+"""
+
+import os
+
+from simulo._client._mounts import volume_env_key
+from simulo._client.mode import EXECUTION, current_mode
+from simulo.interfaces.exceptions import ResourceNotFoundError
+
+
+class Volume:
+    """A named, durable, writable volume mounted into running jobs.
+
+    Declare it as an app mount and read/write :attr:`path` from the job body::
+
+        checkpoints = simulo.Volume.from_name("checkpoints", create_if_missing=True)
+        app = simulo.App("train", runtime=runtime, mounts={"checkpoints": checkpoints})
+
+    At submit time a volume is only a metadata handle — :attr:`path` resolves
+    exclusively inside a running job, after the platform has mounted it.
+
+    Args:
+        name: Non-empty volume name, unique within your workspace.
+        create_if_missing: Create the volume on first use instead of failing.
+
+    Raises:
+        ValueError: if ``name`` is empty or whitespace-only.
+    """
+
+    def __init__(self, name: str, *, create_if_missing: bool = False) -> None:
+        if not name or not name.strip():
+            raise ValueError("Volume name must be a non-empty string.")
+        self._name = name
+        self._create_if_missing = create_if_missing
+
+    @classmethod
+    def from_name(cls, name: str, *, create_if_missing: bool = False) -> "Volume":
+        """Get a handle to the volume called ``name`` — the canonical constructor."""
+        return cls(name, create_if_missing=create_if_missing)
+
+    @property
+    def name(self) -> str:
+        """The volume's name."""
+        return self._name
+
+    @property
+    def create_if_missing(self) -> bool:
+        """Whether the platform creates the volume on first use instead of failing."""
+        return self._create_if_missing
+
+    @property
+    def path(self) -> str:
+        """Local mount path — only meaningful inside a running job (execution).
+
+        Reads ``SIMULO_VOLUME_<name>`` set by the runner. Raises outside
+        execution mode, or if the runner did not mount this volume.
+        """
+        if current_mode() != EXECUTION:
+            raise ResourceNotFoundError(
+                f"Volume {self._name!r}.path is only available inside a running job "
+                f"(SIMULO_MODE={EXECUTION!r}); it is not resolvable during packaging."
+            )
+        key = volume_env_key(self._name)
+        mount = os.environ.get(key)
+        if mount is None:
+            raise ResourceNotFoundError(f"Volume {self._name!r} is not mounted (env var {key} is unset).")
+        return mount