simulo 0.26.0__py3-none-any.whl

simulo/_client/templates/__init__.py

@@ -0,0 +1,21 @@
+"""Starter-app templates shipped INSIDE the ``simulo`` wheel.
+
+The repo's ``demos/`` tree lives outside the packaged ``src/`` layout and never
+reaches a real ``pip install simulo`` user — this package is the fix. Each
+subdirectory (``training/``, ``inference/``, ``scenario/``) holds a ``--type``
+choice for ``simulo create``: an ``app.py.tmpl`` + a ``simuloignore.tmpl``.
+
+The ``.tmpl`` suffix is load-bearing, not cosmetic: these files contain
+``import torch`` and other content that is not a valid, importable module on
+its own, so the suffix keeps ruff / black / isort / mypy --strict / pytest
+collection off them (all of those tools glob ``*.py``). ``simulo create``
+reads them via ``importlib.resources.files(__name__)`` (never ``__file__`` path
+math, which breaks once this package is zipped/installed) and substitutes the
+single ``{{APP_NAME}}`` token with ``str.replace`` — this is not a template
+engine.
+
+This ``__init__.py`` itself exists so ``importlib.resources.files(__name__)``
+resolves this templates directory as a real package (required for
+``setuptools.packages.find`` to discover it, and for ``package-data`` in
+``pyproject.toml`` to ship the ``.tmpl`` files inside it).
+"""

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

@@ -0,0 +1,316 @@
+"""{{APP_NAME}} — a Simulo train -> evaluate -> infer app (scaffolded by `simulo create`).
+
+Three ``@app.job`` functions sharing two volumes (checkpoints + reports) — a full
+policy lifecycle in one app, self-contained: ``train`` produces its own checkpoint,
+so ``evaluate`` / ``rollout`` are never stranded waiting on another app.
+``--job`` picks the stage and the CLI maps the remaining ``--flags`` onto that
+job's own parameters. Submit ONE stage per ``simulo run`` (each stage is a
+separate command; run them in order)::
+
+    simulo run app.py --job train    --num-envs 512 --max-iterations 20
+    simulo run app.py --job evaluate --num-episodes 10 --num-rounds 5
+    simulo run app.py --job rollout  --num-steps 200
+
+WHERE TO EDIT
+-------------
+* ``{{APP_NAME}}Task`` — ``build()`` the scene and write the observation / reward /
+  termination logic for your own robot and task.
+* ``train`` / ``evaluate`` / ``rollout`` — hyperparameters, metrics, what gets
+  recorded; each job's parameters ARE its CLI flags (``num_envs`` -> ``--num-envs``).
+"""
+
+from __future__ import annotations
+
+import math
+import os
+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")
+
+# Two named, durable volumes: one for the trained checkpoints (the skrl checkpoint
+# and the exported TorchScript policy), one for the JSON reports + MCAP recording.
+checkpoints = simulo.Volume.from_name("{{APP_NAME}}-checkpoints", create_if_missing=True)
+reports = simulo.Volume.from_name("{{APP_NAME}}-reports", 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={"/checkpoints": checkpoints, "/reports": reports})
+
+# 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)
+
+# Stable filenames inside the checkpoint volume, shared across the three jobs.
+_CHECKPOINT_FILE = "{{APP_NAME}}_final.pt"
+_POLICY_FILE = "{{APP_NAME}}_policy.pt"
+
+
+@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
+    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)
+
+
+def _make_env(num_envs: int) -> Any:
+    """Construct the shared environment (same sim settings across all three jobs)."""
+    return 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,
+    )
+
+
+# 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 = 512, max_iterations: int = 20) -> dict[str, Any]:
+    """Train a policy, then save the checkpoint AND export a TorchScript policy.
+
+    Saves two artefacts to the checkpoint volume: the skrl checkpoint (consumed by
+    ``evaluate``) and a deterministic TorchScript policy (consumed by ``rollout``
+    via ``simulo.RLPlayer``).
+    """
+    env = _make_env(num_envs)
+    trainer = simulo.RLTrainer(env=env, algorithm="PPO", device="cuda", seed=42)
+
+    stats = trainer.train(max_iterations=max_iterations)
+
+    checkpoint = f"{checkpoints.path}/{_CHECKPOINT_FILE}"
+    policy_path = f"{checkpoints.path}/{_POLICY_FILE}"
+    trainer.save(checkpoint)
+    trainer.export_policy(policy_path)
+
+    # Close the trainer before the environment so skrl releases its resources first.
+    trainer.close()
+    env.close()
+
+    return {"checkpoint": checkpoint, "policy": policy_path, "num_envs": num_envs, **stats}
+
+
+@app.job(system=simulo.SystemType.TIER_1, timeout=2 * 60 * 60)
+def evaluate(num_episodes: int = 10, num_rounds: int = 5) -> dict[str, Any]:
+    """Evaluate the saved checkpoint over several rounds; aggregate with numpy."""
+    import json
+
+    import numpy as np
+
+    checkpoint = f"{checkpoints.path}/{_CHECKPOINT_FILE}"
+    reward_target = float(os.environ.get("SIMULO_EVAL_REWARD_TARGET", "75.0"))
+
+    env = _make_env(num_envs=64)
+    trainer = simulo.RLTrainer(env=env, algorithm="PPO", device="cuda", seed=42)
+
+    round_rewards: list[float] = []
+    round_lengths: list[float] = []
+    for _ in range(num_rounds):
+        metrics = trainer.evaluate(checkpoint=checkpoint, num_episodes=num_episodes)
+        round_rewards.append(float(metrics["mean_reward"]))
+        round_lengths.append(float(metrics["mean_length"]))
+
+    trainer.close()
+    env.close()
+
+    rewards = np.array(round_rewards, dtype=np.float64)
+    lengths = np.array(round_lengths, dtype=np.float64)
+    report = {
+        "checkpoint": checkpoint,
+        "num_rounds": num_rounds,
+        "num_episodes": num_episodes,
+        "reward_target": reward_target,
+        "mean_reward": float(rewards.mean()),
+        "std_reward": float(rewards.std()),
+        "mean_length": float(lengths.mean()),
+        "success_rate": float((rewards >= reward_target).mean()),
+    }
+
+    report_path = f"{reports.path}/eval_report.json"
+    with open(report_path, "w") as fh:
+        json.dump(report, fh, indent=2)
+    print(f"[{{APP_NAME}}] Wrote eval report to {report_path}")
+
+    return {"report": report_path, **report}
+
+
+@app.job(system=simulo.SystemType.TIER_1, timeout=1 * 60 * 60)
+def rollout(num_steps: int = 200) -> dict[str, Any]:
+    """Inference path: play the exported TorchScript policy and record it to MCAP.
+
+    No trainer and no skrl here — ``simulo.RLPlayer`` auto-detects the TorchScript
+    policy ``train`` exported and drives it directly. ``record=simulo.RecordConfig(...)``
+    captures the rollout to an MCAP flight recording in the report volume.
+    """
+    import json
+
+    policy_path = f"{checkpoints.path}/{_POLICY_FILE}"
+    mcap_path = f"{reports.path}/rollout.mcap"
+
+    env = _make_env(num_envs=1)
+    # A TorchScript checkpoint makes the player run the policy directly — trainer-free.
+    player = simulo.RLPlayer(env=env, checkpoint=policy_path, device="cuda")
+    record = simulo.RecordConfig(output_path=mcap_path, policy_checkpoint=policy_path, robot_model="{{APP_NAME}}")
+    stats = player.play(num_steps=num_steps, record=record)
+
+    player.close()
+    env.close()
+
+    summary = {"policy": policy_path, "mcap": mcap_path, **stats}
+
+    summary_path = f"{reports.path}/rollout_summary.json"
+    with open(summary_path, "w") as fh:
+        json.dump(summary, fh, indent=2)
+    print(f"[{{APP_NAME}}] Wrote rollout summary to {summary_path}")
+
+    return {"summary": summary_path, **summary}

simulo/_client/templates/inference/simuloignore.tmpl

@@ -0,0 +1,30 @@
+# Gitignore-style excludes for `simulo run` / `simulo create --type inference`'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
+# checkpoints.path / reports.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/templates/scenario/app.py.tmpl

@@ -0,0 +1,93 @@
+"""{{APP_NAME}} — a Simulo scenario app (scaffolded by `simulo create`).
+
+A headless scene with NO learning: build a world, step it, and shut it down.
+Submit it with::
+
+    simulo run app.py --num-steps 1000 --num-envs 4
+
+The CLI maps each ``--flag`` onto ``simulate``'s own parameters — no extra
+boilerplate; run with no flags to use the defaults. Submitting only
+writes/uploads the job — it does NOT run the scene 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}}Scenario.build`` — populate the scene: terrain, lights, robots, assets.
+* ``on_start`` / ``on_step`` / ``on_shutdown`` — your own simulation logic.
+* ``simulate`` (the ``@app.job``) — simulation length and what gets returned;
+  its parameters ARE the app's CLI flags (``num_steps`` -> ``--num-steps``).
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+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")
+
+
+class {{APP_NAME}}Scenario(simulo.Scenario):  # -> ScenarioProtocol at submit, real class on worker
+    """A minimal scene: a ground plane, a light, and a robot. EDIT: build your own.
+
+    Critical rule: everything a Scenario does must be expressible with
+    ``simulo.Terrain`` / ``simulo.Light`` / ``simulo.Robot`` / ``simulo.Asset`` —
+    no ``torch`` here (this class is defined, but never instantiated, at submit).
+    """
+
+    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) -> None:
+        """Called once after build() and runtime initialization. EDIT: setup here."""
+
+    def on_step(self) -> None:
+        """Called every simulation step. EDIT: your per-step logic here."""
+
+    def on_shutdown(self) -> None:
+        """Called during cleanup. EDIT: final logging / saving here."""
+
+
+# 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}}")
+
+
+# system= picks a GPU tier from the published catalog; run `simulo systems` to see them.
+@app.job(system=simulo.SystemType.TIER_1, timeout=30 * 60)
+def simulate(num_steps: int = 1000, num_envs: int = 4) -> dict[str, Any]:
+    """Run the scenario headless on the worker. EDIT: device / step count / env count.
+
+    Args:
+        num_steps: Number of simulation steps to run.
+        num_envs: Number of parallel environments (robots added in ``build`` are
+            automatically replicated across all of them).
+
+    Returns:
+        A JSON-serialisable dict summarising the run.
+    """
+    # simulo.run is execution-only (it resolves to an inert stand-in at
+    # submit and to the real simulo.scenario.run on the worker); job bodies
+    # never run at submit, so it needs no extra import here. Keep this call
+    # INSIDE the job body: the identical line at MODULE scope would silently
+    # do nothing at submit (an inert stand-in, no error) yet launch a real
+    # simulation at import time on the worker.
+    simulo.run(
+        {{APP_NAME}}Scenario,
+        device="cuda",
+        headless=True,
+        max_steps=num_steps,
+        num_envs=num_envs,
+    )
+    return {"steps": num_steps, "num_envs": num_envs}

simulo/_client/templates/scenario/simuloignore.tmpl

@@ -0,0 +1,27 @@
+# Gitignore-style excludes for `simulo run` / `simulo create --type scenario`'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.
+
+# Any saved state this scenario writes locally.
+*.pt
+*.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/