wavesimpro 1.9.0__tar.gz → 1.10.1__tar.gz

{wavesimpro-1.9.0 → wavesimpro-1.10.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: wavesimpro
-Version: 1.9.0
+Version: 1.10.1
 Summary: WavesimPro Python API — cloud execution client for the Rayfos simulation platform
 Author: Rayfos
 Project-URL: Repository, https://github.com/rayfos/wavesimpro
@@ -59,8 +59,15 @@ field = wp.read_binary_field(run.download("output.bin"))
 
 ## What the API covers
 
-- Setup helpers for domains, media, primitives (box, STL, voxel arrays), sources
-  (point, plane wave, Gaussian beam, custom field, engine-solved waveguide mode) and monitors.
+- Setup helpers for domains, media, primitives (box, sphere, ellipsoid, cylinder, cone,
+  N-sided prism, STL, GDSII layouts, voxel arrays), sources (point, plane wave, Gaussian beam,
+  custom field, custom-from-file, engine-solved waveguide mode) and monitors:
+  `create_box_primitive`, `create_sphere_primitive`, `create_ellipsoid_primitive`,
+  `create_cylinder_primitive`, `create_cone_primitive`, `create_prism_primitive`,
+  `create_stl_primitive`, `create_gds_primitive` (with `create_gds_layer_config` /
+  `create_gds_structure_override`), `create_voxels_model_primitive`.
+- Per-primitive sub-pixel flag (`subpixel=True/False` on every shape, STL and GDSII helper)
+  to choose which shapes get smoothed interfaces.
 - Per-axis pixel sizes (`pixel_size=[dx, dy, dz]`) and sub-pixel permittivity averaging
   (`subpixel_factor=`), when the compute node supports them.
 - Preflight memory check and cost estimate before a run.

{wavesimpro-1.9.0 → wavesimpro-1.10.1}/README.md

@@ -36,8 +36,15 @@ field = wp.read_binary_field(run.download("output.bin"))
 
 ## What the API covers
 
-- Setup helpers for domains, media, primitives (box, STL, voxel arrays), sources
-  (point, plane wave, Gaussian beam, custom field, engine-solved waveguide mode) and monitors.
+- Setup helpers for domains, media, primitives (box, sphere, ellipsoid, cylinder, cone,
+  N-sided prism, STL, GDSII layouts, voxel arrays), sources (point, plane wave, Gaussian beam,
+  custom field, custom-from-file, engine-solved waveguide mode) and monitors:
+  `create_box_primitive`, `create_sphere_primitive`, `create_ellipsoid_primitive`,
+  `create_cylinder_primitive`, `create_cone_primitive`, `create_prism_primitive`,
+  `create_stl_primitive`, `create_gds_primitive` (with `create_gds_layer_config` /
+  `create_gds_structure_override`), `create_voxels_model_primitive`.
+- Per-primitive sub-pixel flag (`subpixel=True/False` on every shape, STL and GDSII helper)
+  to choose which shapes get smoothed interfaces.
 - Per-axis pixel sizes (`pixel_size=[dx, dy, dz]`) and sub-pixel permittivity averaging
   (`subpixel_factor=`), when the compute node supports them.
 - Preflight memory check and cost estimate before a run.

{wavesimpro-1.9.0 → wavesimpro-1.10.1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "wavesimpro"
-version = "1.9.0"
+version = "1.10.1"
 description = "WavesimPro Python API — cloud execution client for the Rayfos simulation platform"
 readme = "README.md"
 requires-python = ">=3.8"

{wavesimpro-1.9.0 → wavesimpro-1.10.1}/src/wavesimpro/__init__.py

@@ -6,7 +6,7 @@ supporting both cloud and local deployment modes, as well as direct interaction
 with RayfosMachineService via its REST API.
 """
 
-from .client import RayfosClient
+from .client import RayfosClient, command_status_name, is_terminal_command_status
 from .config import ClientConfig
 from .exceptions import (
     RayfosAPIError,
@@ -33,6 +33,14 @@ from .json_helper import (
     create_simulation_domain,
     create_stl_primitive,
     create_box_primitive,
+    create_sphere_primitive,
+    create_ellipsoid_primitive,
+    create_cylinder_primitive,
+    create_cone_primitive,
+    create_prism_primitive,
+    create_gds_primitive,
+    create_gds_layer_config,
+    create_gds_structure_override,
     create_medium,
     create_point_source,
     create_plane_wave_source,
@@ -46,10 +54,12 @@ from .json_helper import (
     parse_progress_data,
 )
 
-__version__ = "1.9.0"
+__version__ = "1.10.1"
 __all__ = [
     # Client
     "RayfosClient",
+    "command_status_name",
+    "is_terminal_command_status",
     "ClientConfig",
     # Exceptions
     "RayfosAPIError",
@@ -78,6 +88,14 @@ __all__ = [
     "create_simulation_domain",
     "create_stl_primitive",
     "create_box_primitive",
+    "create_sphere_primitive",
+    "create_ellipsoid_primitive",
+    "create_cylinder_primitive",
+    "create_cone_primitive",
+    "create_prism_primitive",
+    "create_gds_primitive",
+    "create_gds_layer_config",
+    "create_gds_structure_override",
     "create_medium",
     "create_point_source",
     "create_plane_wave_source",

{wavesimpro-1.9.0 → wavesimpro-1.10.1}/src/wavesimpro/client.py

@@ -77,6 +77,49 @@ def _make_progress_callback(total_bytes: int, desc: str):
 logger = logging.getLogger(__name__)
 
 
+
+# CommandStatus enum (C# RayfosCommandModels) by value; the server sends the NAME in "status"
+# (JsonStringEnumConverter). Older servers sent the integer in "commandStatus".
+_COMMAND_STATUS_BY_INT = {
+    0: 'New', 1: 'Assigned', 2: 'SentToMachine', 3: 'SendToMachineForceCancellation',
+    4: 'SendToMachineForceDeleteTask', 5: 'RequestedForceCancellationInMachine',
+    6: 'RequestedForceStopTaskInMachine', 7: 'Cancelled', 8: 'Deleted', 9: 'Running',
+    10: 'Completed', 11: 'Failed', 12: 'FailedRemovedFromMachine',
+}
+_TERMINAL_STATUSES = {'Cancelled', 'Deleted', 'Completed', 'Failed', 'FailedRemovedFromMachine'}
+
+
+def command_status_name(status: Dict[str, Any]) -> str:
+    """The command state name from a command-status dict, whatever the server version.
+
+    Reads ``status`` (current servers: the enum name, e.g. ``"Completed"``), falling back to the
+    legacy ``commandStatus`` / ``CommandStatus`` (integer or name). Returns ``"Unknown"`` when absent.
+    """
+    if not isinstance(status, dict):
+        return 'Unknown'
+    for key in ('status', 'Status', 'commandStatus', 'CommandStatus'):
+        raw = status.get(key)
+        if raw is None or raw == '':
+            continue
+        if isinstance(raw, bool):
+            continue
+        if isinstance(raw, int):
+            return _COMMAND_STATUS_BY_INT.get(raw, f'Unknown({raw})')
+        text = str(raw).strip()
+        if text.isdigit():
+            return _COMMAND_STATUS_BY_INT.get(int(text), f'Unknown({text})')
+        for name in _COMMAND_STATUS_BY_INT.values():
+            if name.lower() == text.lower():
+                return name
+        return text
+    return 'Unknown'
+
+
+def is_terminal_command_status(name: str) -> bool:
+    """True for Completed, Failed, FailedRemovedFromMachine, Cancelled and Deleted."""
+    return name in _TERMINAL_STATUSES
+
+
 class RayfosClient:
     """
     Client for interacting with RayfosJobServer API
@@ -740,9 +783,9 @@ class RayfosClient:
         
         Example:
             >>> version = client.get_project_version(project_id, version_id)
-            >>> if version.get('command') and version['command'].get('outputFiles'):
-            ...     for file in version['command']['outputFiles']:
-            ...         print(f"Output file: {file['originalFileName']}")
+            >>> for file_id in version.get('outputFileIds', []):
+            ...     info = client.get_file_info(project_id, version_id, file_id)
+            ...     print(f"Output file: {info.get('fileName')} ({info.get('fileSize')} bytes)")
         """
         return self._get(f"/api/projects/{project_id}/versions/{version_id}")
     
@@ -1287,7 +1330,7 @@ class RayfosClient:
         Returns:
             File metadata dictionary
         """
-        return self._get(f"/api/projects/{project_id}/versions/{version_id}/files/{file_id}")
+        return self._get(f"/api/projects/{project_id}/versions/{version_id}/files/{file_id}/metadata")
     
     # ========================================================================
     # COMMAND OPERATIONS
@@ -1382,7 +1425,8 @@ class RayfosClient:
                 Ignored when using a local machine service URL.
 
         Returns:
-            Command status dictionary with the created command ID and status
+            Command status dictionary. The command id is under ``"id"`` and, for convenience,
+            ``"commandId"``; the state is under ``"status"`` (read it with ``command_status_name``).
 
         Example:
             >>> command = client.create_command(project_id, version_id,
@@ -1390,9 +1434,17 @@ class RayfosClient:
             >>> print(f"Command created: {command['id']}")
         """
         if self.config.machine_service_url:
-            return self._create_command_machine_service(project_id, version_id)
+            result = self._create_command_machine_service(project_id, version_id)
         else:
-            return self._create_command_cloud(project_id, version_id, engine_preference, use_gpu, preferred_machine_id)
+            result = self._create_command_cloud(project_id, version_id, engine_preference, use_gpu, preferred_machine_id)
+        # The server names the command id "id"; other API calls and version records use "commandId".
+        # Return both so either spelling works.
+        if isinstance(result, dict):
+            cid = result.get('id') or result.get('commandId') or result.get('Id')
+            if cid:
+                result.setdefault('id', cid)
+                result.setdefault('commandId', cid)
+        return result
     
     def _create_command_machine_service(
         self,
@@ -1439,35 +1491,8 @@ class RayfosClient:
     
     @staticmethod
     def _parse_command_status(status_raw) -> str:
-        """
-        Parse commandStatus from C# enum (integer) to string name
-        
-        Args:
-            status_raw: Either integer enum value or string name
-        
-        Returns:
-            String name of the status
-        """
-        # CommandStatus enum from C# RayfosCommandModels
-        COMMAND_STATUS_MAP = {
-            0: 'New',
-            1: 'Assigned', 
-            2: 'SentToMachine',
-            3: 'SendToMachineForceCancellation',
-            4: 'SendToMachineForceDeleteTask',
-            5: 'RequestedForceCancellationInMachine',
-            6: 'RequestedForceStopTaskInMachine',
-            7: 'Cancelled',
-            8: 'Deleted',
-            9: 'Running',
-            10: 'Completed',
-            11: 'Failed',
-            12: 'FailedRemovedFromMachine'
-        }
-        
-        if isinstance(status_raw, int):
-            return COMMAND_STATUS_MAP.get(status_raw, f'Unknown({status_raw})')
-        return status_raw
+        """Command state name from an integer (legacy ``commandStatus``) or a name (current ``status``)."""
+        return command_status_name({"status": status_raw})
     
     @staticmethod
     def _parse_progress_data(progress_obj) -> Dict[str, Any]:
@@ -1542,16 +1567,16 @@ class RayfosClient:
             command_id: Command UUID
         
         Returns:
-            CommandStatusDto dictionary with status, progress, and output files
-            Note: commandStatus is returned as integer from C#, use _parse_command_status() to convert
-        
+            Command-status dict: ``id``, ``status`` (enum name such as ``"Running"`` or
+            ``"Completed"``), ``statusText``, ``progressValue``. Older servers sent
+            the state as the integer ``commandStatus``; :func:`command_status_name` reads either.
+
         Example:
             >>> status = client.get_command_status("command-uuid")
-            >>> status_name = client._parse_command_status(status['commandStatus'])
-            >>> print(f"Status: {status_name}")
-            >>> print(f"Progress: {status.get('progressValue', 0)}%")
-            >>> if status['commandStatus'] == 10:  # Completed
-            ...     print(f"Output files: {status.get('outputFileIds', [])}")
+            >>> name = command_status_name(status)          # "Running", "Completed", ...
+            >>> print(f"{name}: {status.get('statusText')} ({status.get('progressValue', 0)}%)")
+            >>> if name == "Completed":
+            ...     files = client.get_project_version(project_id, version_id)["outputFileIds"]
         """
         # Always call RayfosJobServer directly for command status (user endpoint)
         # Machine service is only for file operations, not command status
@@ -1561,113 +1586,73 @@ class RayfosClient:
         self,
         command_id: str,
         poll_interval: float = 2.0,
-        timeout: Optional[float] = None,
+        timeout: Optional[float] = 24 * 3600,
         progress_callback: Optional[callable] = None
     ) -> Dict[str, Any]:
         """
-        Wait for a command to complete (synchronous execution)
-        
-        This method polls the command status until it reaches a terminal state
-        (Completed, Failed, Cancelled). Useful for blocking until simulation finishes.
-        
+        Wait for a command to finish (synchronous execution).
+
+        Polls :meth:`get_command_status` until the command reaches a terminal state and returns the
+        final status dict on ``Completed``. The state is read with :func:`command_status_name`, which
+        understands both the current ``status`` field (enum name) and the legacy ``commandStatus``
+        integer, so this works against every server version.
+
         Args:
-            command_id: Command UUID to wait for
-            poll_interval: Seconds between status checks (default: 2.0)
-            timeout: Maximum seconds to wait before raising TimeoutError (default: None - no timeout)
-            progress_callback: Optional callback(status_dict) called on each status check
-        
+            command_id: Command UUID (``create_command(...)["id"]``, also available as ``["commandId"]``)
+            poll_interval: Seconds between status checks (default 2.0)
+            timeout: Maximum seconds to wait (default 24 h; ``None`` waits forever)
+            progress_callback: Optional ``callback(status_dict)`` called on each poll
+
         Returns:
-            Final CommandStatusDto dictionary when command completes
-        
+            Final command-status dict (``status == "Completed"``). To get the result files, list the
+            version's ``outputFileIds`` (``get_project_version(project_id, version_id)["outputFileIds"]``,
+            then ``download_file``); the ``outputFileIds`` field
+            of the status is not filled by current servers.
+
         Raises:
-            TimeoutError: If timeout is reached before completion
-            RayfosAPIError: If command fails or is cancelled
-        
+            TimeoutError: the command did not finish within ``timeout`` seconds
+            RayfosAPIError: the command failed, was cancelled or was deleted
+
         Example:
-            >>> # Create command
-            >>> command = client.create_command(project_id, version_id, args_json)
-            >>> 
-            >>> # Wait for completion with progress updates
-            >>> def show_progress(status):
-            ...     print(f"Progress: {status.get('progressValue', 0)}% - {status.get('statusText', 'Running')}")
-            >>> 
-            >>> final_status = client.wait_for_command_completion(
-            ...     command['id'],
-            ...     progress_callback=show_progress,
-            ...     timeout=3600  # 1 hour timeout
-            ... )
-            >>> print(f"Command completed! Output files: {final_status.get('outputFileIds', [])}")
+            >>> command = client.create_command(project_id, version_id)
+            >>> final = client.wait_for_command_completion(command["id"], timeout=3600,
+            ...     progress_callback=lambda s: print(command_status_name(s), s.get("statusText")))
         """
         import time
-        
-        # CommandStatus enum values from C# (serialized as integers)
-        # New=0, Assigned=1, SentToMachine=2, etc.
-        COMMAND_STATUS = {
-            0: 'New',
-            1: 'Assigned', 
-            2: 'SentToMachine',
-            3: 'SendToMachineForceCancellation',
-            4: 'SendToMachineForceDeleteTask',
-            5: 'RequestedForceCancellationInMachine',
-            6: 'RequestedForceStopTaskInMachine',
-            7: 'Cancelled',
-            8: 'Deleted',
-            9: 'Running',
-            10: 'Completed',
-            11: 'Failed',
-            12: 'FailedRemovedFromMachine'
-        }
-        
-        # Terminal states (by integer value and name)
-        TERMINAL_STATUS_INTS = {7, 8, 10, 11, 12}  # Cancelled, Deleted, Completed, Failed, FailedRemovedFromMachine
-        TERMINAL_STATUS_NAMES = {'Cancelled', 'Deleted', 'Completed', 'Failed', 'FailedRemovedFromMachine'}
-        
+
         start_time = time.time()
-        
         while True:
-            # Check timeout
-            if timeout and (time.time() - start_time) > timeout:
-                raise TimeoutError(f"Command {command_id} did not complete within {timeout} seconds")
-            
-            # Get current status
             status = self.get_command_status(command_id)
-            command_status_raw = status.get('commandStatus')
-            
-            # Handle both integer (from C# enum) and string formats
-            if isinstance(command_status_raw, int):
-                command_status = COMMAND_STATUS.get(command_status_raw, f'Unknown({command_status_raw})')
-                is_terminal = command_status_raw in TERMINAL_STATUS_INTS
-            else:
-                command_status = command_status_raw
-                is_terminal = command_status in TERMINAL_STATUS_NAMES
-            
-            # Call progress callback if provided
+            name = command_status_name(status)
+
             if progress_callback:
                 progress_callback(status)
-            
-            # Check if command reached terminal state
-            if is_terminal:
-                if command_status in ('Completed', 10):
+
+            if is_terminal_command_status(name):
+                if name == 'Completed':
                     return status
-                elif command_status in ('Failed', 'FailedRemovedFromMachine', 11, 12):
-                    error_msg = status.get('statusText', 'Command failed')
-                    raise RayfosAPIError(f"Command {command_id} failed: {error_msg}")
-                elif command_status in ('Cancelled', 7):
+                detail = status.get('statusText') or ''
+                if name in ('Failed', 'FailedRemovedFromMachine'):
+                    raise RayfosAPIError(f"Command {command_id} failed: {detail or name}")
+                if name == 'Cancelled':
                     raise RayfosAPIError(f"Command {command_id} was cancelled")
-                elif command_status in ('Deleted', 8):
-                    raise RayfosAPIError(f"Command {command_id} was deleted")
-            
-            # Wait before next poll
+                raise RayfosAPIError(f"Command {command_id} was deleted")
+
+            if timeout is not None and (time.time() - start_time) > timeout:
+                raise TimeoutError(f"Command {command_id} did not finish within {timeout:.0f} s (last status: {name})")
+
             time.sleep(poll_interval)
-    
+
     def create_command_and_wait(
         self,
         project_id: str,
         version_id: str,
         local_machine_service_id: Optional[str] = None,
         poll_interval: float = 2.0,
-        timeout: Optional[float] = None,
-        progress_callback: Optional[callable] = None
+        timeout: Optional[float] = 24 * 3600,
+        progress_callback: Optional[callable] = None,
+        engine_preference: str = 'Any',
+        use_gpu: Optional[bool] = None,
     ) -> Dict[str, Any]:
         """
         Create a command and wait for it to complete (synchronous execution)
@@ -1706,8 +1691,11 @@ class RayfosClient:
             ...     client.download_file(project_id, version_id, file_id, f"output/{file_id}")
         """
         # Create the command (async)
-        command_status = self.create_command(project_id, version_id, local_machine_service_id)
-        command_id = command_status.get('id')
+        # local_machine_service_id pins the run to that compute node (it used to be passed, by
+        # position, as the engine preference, which the server rejects).
+        command_status = self.create_command(project_id, version_id, engine_preference=engine_preference,
+                                             use_gpu=use_gpu, preferred_machine_id=local_machine_service_id)
+        command_id = command_status.get('id') or command_status.get('commandId')
         
         if not command_id:
             raise RayfosAPIError("Failed to create command: no command ID returned")
@@ -1898,46 +1886,7 @@ class RayfosClient:
         )
         return self._handle_response(response)
 
-    def parse_command_status(self, status_value: int) -> str:
-        """
-        Parse commandStatus from C# enum (integer) to string name
-        
-        Args:
-            status_value: Integer status code from CommandStatusDto
-        
-        Returns:
-            Human-readable status name
-        
-        CommandStatus enum values from C# RayfosCommandModels:
-            0 = New
-            1 = Assigned
-            2 = SentToMachine
-            3 = SendToMachineForceCancellation
-            4 = SendToMachineForceDeleteTask
-            5 = RequestedForceCancellationInMachine
-            6 = RequestedForceStopTaskInMachine
-            7 = Cancelled
-            8 = Deleted
-            9 = Running
-            10 = Completed
-            11 = Failed
-            12 = FailedRemovedFromMachine
-        """
-        status_map = {
-            0: "New",
-            1: "Assigned",
-            2: "SentToMachine",
-            3: "SendToMachineForceCancellation",
-            4: "SendToMachineForceDeleteTask",
-            5: "RequestedForceCancellationInMachine",
-            6: "RequestedForceStopTaskInMachine",
-            7: "Cancelled",
-            8: "Deleted",
-            9: "Running",
-            10: "Completed",
-            11: "Failed",
-            12: "FailedRemovedFromMachine",
-        }
-        
-        return status_map.get(status_value, f"Unknown({status_value})")
+    def parse_command_status(self, status_value) -> str:
+        """Command state name from an integer (legacy ``commandStatus``) or a name (current ``status``)."""
+        return command_status_name({"status": status_value})
 

{wavesimpro-1.9.0 → wavesimpro-1.10.1}/src/wavesimpro/json_helper.py

@@ -42,6 +42,84 @@ def create_simulation_domain(
     }
 
 
+# ---------------------------------------------------------------------------
+# Primitive helpers
+#
+# Every primitive dict mirrors RayfosCommandModels.PrimitiveBase (Primitives.cs):
+#   Id (uuid), Name, ShapeType (enum serialised as its name, e.g. "Cylinder"),
+#   MediumId, Position {X,Y,Z: Length}, PositionAnchor (enum name), Rotation
+#   {X,Y,Z} in degrees, plus the per-shape properties. Lengths are {Value, Unit}.
+#   "PositioningMode": "CenterAndSize" is the Studio bookkeeping key the existing
+#   helpers already emit (ignored by the server).
+#
+# Sub-pixel flag ("SubPixel"): True = this primitive's interface voxels are
+# probe-averaged (create_wavesim_properties' subpixel_factor probes per axis);
+# False = centre-sampled staircase for this primitive; None (default) = key
+# omitted, the primitive follows the simulation-level PermittivitySampling.Mode
+# (the pre-1.10 behaviour).
+# ---------------------------------------------------------------------------
+
+_POSITION_ANCHORS = (
+    "Center", "BottomLeftFront", "BottomCenter", "BottomRightFront", "BottomLeftBack",
+    "BottomRightBack", "TopCenter", "TopLeftFront", "TopRightFront", "TopLeftBack", "TopRightBack",
+)
+# Anchors each shape's GetCanonicalCenterPosition() accepts (others throw on the server).
+_BOX_ANCHORS = ("Center", "BottomLeftFront", "BottomCenter", "TopCenter")
+_AXIAL_ANCHORS = ("Center", "BottomCenter", "TopCenter")   # Cylinder, Cone, Prism
+_AXES = ("X", "Y", "Z")
+
+
+def _check_anchor(anchor: str, allowed: Tuple[str, ...], shape: str) -> str:
+    a = str(anchor)
+    if a not in allowed:
+        raise ValueError(f"position_anchor for {shape} must be one of {list(allowed)}, got {anchor!r}")
+    return a
+
+
+def _check_axis(axis: str) -> str:
+    a = str(axis).upper()
+    if a not in _AXES:
+        raise ValueError(f"axis must be 'X', 'Y' or 'Z', got {axis!r}")
+    return a
+
+
+def _length(value: float, unit: str) -> Dict[str, Any]:
+    return {"Value": float(value), "Unit": unit}
+
+
+def _primitive_base(
+    shape_type: str,
+    name: str,
+    medium_id: str,
+    x: float,
+    y: float,
+    z: float,
+    rotation_x: float,
+    rotation_y: float,
+    rotation_z: float,
+    position_anchor: str,
+    unit: str,
+    subpixel: Optional[bool],
+) -> Dict[str, Any]:
+    prim: Dict[str, Any] = {
+        "Id": str(uuid.uuid4()),
+        "Name": name,
+        "ShapeType": shape_type,
+        "MediumId": medium_id,
+        "PositioningMode": "CenterAndSize",
+        "Position": {"X": _length(x, unit), "Y": _length(y, unit), "Z": _length(z, unit)},
+        "PositionAnchor": position_anchor,
+        "Rotation": {"X": float(rotation_x), "Y": float(rotation_y), "Z": float(rotation_z)},
+    }
+    _apply_subpixel(prim, subpixel)
+    return prim
+
+
+def _apply_subpixel(prim: Dict[str, Any], subpixel: Optional[bool]) -> None:
+    if subpixel is not None:
+        prim["SubPixel"] = bool(subpixel)
+
+
 def create_stl_primitive(
     name: str,
     file_id: str,
@@ -55,7 +133,8 @@ def create_stl_primitive(
     scale_x: float = 1.0,
     scale_y: float = 1.0,
     scale_z: float = 1.0,
-    unit: str = "Micrometers"
+    unit: str = "Micrometers",
+    subpixel: Optional[bool] = None,
 ) -> Dict[str, Any]:
     """
     Create STL primitive structure
@@ -68,8 +147,10 @@ def create_stl_primitive(
         rotation_x, rotation_y, rotation_z: Rotation angles in degrees
         scale_x, scale_y, scale_z: Scale factors
         unit: Unit of measurement
+        subpixel: True = sub-pixel average this mesh's interface voxels, False = staircase,
+            None (default) = key omitted, follow the simulation-level setting.
     """
-    return {
+    prim = {
         "Id": str(uuid.uuid4()),
         "Name": name,
         "ShapeType": "StlModel",
@@ -94,6 +175,8 @@ def create_stl_primitive(
         },
         "_tempStlData": {}
     }
+    _apply_subpixel(prim, subpixel)
+    return prim
 
 
 def create_box_primitive(
@@ -105,19 +188,46 @@ def create_box_primitive(
     size_x: float,
     size_y: float,
     size_z: float,
-    unit: str = "Micrometers"
+    unit: str = "Micrometers",
+    subpixel: Optional[bool] = None,
+    position_anchor: str = "Center",
+    rotation_x: float = 0.0,
+    rotation_y: float = 0.0,
+    rotation_z: float = 0.0,
 ) -> Dict[str, Any]:
-    """Create a box primitive"""
-    return {
+    """
+    Create a box primitive (BoxPrimitive, CenterAndSize representation).
+
+    Args:
+        name: Primitive name
+        medium_id: Medium/Material ID
+        center_x, center_y, center_z: Position (what it refers to is set by position_anchor)
+        size_x, size_y, size_z: Full extents along X/Y/Z (Size.Width/Height/Depth)
+        unit: Unit of measurement for position and size
+        subpixel: True = sub-pixel average this box's interface voxels, False = staircase,
+            None (default) = key omitted, follow the simulation-level setting.
+        position_anchor: "Center" (default), "BottomLeftFront" (minimum corner),
+            "BottomCenter" (centre of the -Y face) or "TopCenter" (centre of the +Y face).
+            The server rejects any other anchor for a box.
+        rotation_x, rotation_y, rotation_z: Rotation in degrees
+    """
+    anchor = _check_anchor(position_anchor, _BOX_ANCHORS, "Box")
+    prim: Dict[str, Any] = {
+        "Id": str(uuid.uuid4()),
+        # "Type" kept for older servers; "ShapeType" is the canonical discriminator (same value).
         "Type": "Box",
+        "ShapeType": "Box",
         "Name": name,
         "MediumId": medium_id,
         "PositioningMode": "CenterAndSize",
+        "Representation": "CenterAndSize",
         "Position": {
             "X": {"Value": center_x, "Unit": unit},
             "Y": {"Value": center_y, "Unit": unit},
             "Z": {"Value": center_z, "Unit": unit}
         },
+        "PositionAnchor": anchor,
+        "Rotation": {"X": float(rotation_x), "Y": float(rotation_y), "Z": float(rotation_z)},
         # Size3D on the server is Width/Height/Depth (X/Y/Z keys were silently ignored → 4 µm default).
         "Size": {
             "Width": {"Value": size_x, "Unit": unit},
@@ -125,6 +235,338 @@ def create_box_primitive(
             "Depth": {"Value": size_z, "Unit": unit}
         }
     }
+    _apply_subpixel(prim, subpixel)
+    return prim
+
+
+def create_sphere_primitive(
+    name: str,
+    medium_id: str,
+    center_x: float,
+    center_y: float,
+    center_z: float,
+    radius: float,
+    rotation_x: float = 0.0,
+    rotation_y: float = 0.0,
+    rotation_z: float = 0.0,
+    position_anchor: str = "Center",
+    unit: str = "Micrometers",
+    subpixel: Optional[bool] = None,
+) -> Dict[str, Any]:
+    """
+    Create a sphere primitive (SpherePrimitive).
+
+    Args:
+        name: Primitive name
+        medium_id: Medium/Material ID
+        center_x, center_y, center_z: Sphere centre
+        radius: Radius (Length in ``unit``)
+        rotation_x, rotation_y, rotation_z: Rotation in degrees (no effect on a sphere)
+        position_anchor: Stored as given (default "Center"); the server always treats
+            Position as the centre of a sphere.
+        unit: Unit of measurement
+        subpixel: True / False / None (follow the simulation-level setting)
+    """
+    anchor = _check_anchor(position_anchor, _POSITION_ANCHORS, "Sphere")
+    prim = _primitive_base("Sphere", name, medium_id, center_x, center_y, center_z,
+                           rotation_x, rotation_y, rotation_z, anchor, unit, subpixel)
+    prim["Radius"] = _length(radius, unit)
+    return prim
+
+
+def create_ellipsoid_primitive(
+    name: str,
+    medium_id: str,
+    center_x: float,
+    center_y: float,
+    center_z: float,
+    radius_x: float,
+    radius_y: float,
+    radius_z: float,
+    rotation_x: float = 0.0,
+    rotation_y: float = 0.0,
+    rotation_z: float = 0.0,
+    position_anchor: str = "Center",
+    unit: str = "Micrometers",
+    subpixel: Optional[bool] = None,
+) -> Dict[str, Any]:
+    """
+    Create an ellipsoid primitive (EllipsoidPrimitive).
+
+    Args:
+        name: Primitive name
+        medium_id: Medium/Material ID
+        center_x, center_y, center_z: Ellipsoid centre
+        radius_x, radius_y, radius_z: Semi-axes along X/Y/Z (before rotation)
+        rotation_x, rotation_y, rotation_z: Rotation in degrees
+        position_anchor: Stored as given (default "Center"); the server always treats
+            Position as the centre of an ellipsoid.
+        unit: Unit of measurement
+        subpixel: True / False / None (follow the simulation-level setting)
+    """
+    anchor = _check_anchor(position_anchor, _POSITION_ANCHORS, "Ellipsoid")
+    prim = _primitive_base("Ellipsoid", name, medium_id, center_x, center_y, center_z,
+                           rotation_x, rotation_y, rotation_z, anchor, unit, subpixel)
+    prim["RadiusX"] = _length(radius_x, unit)
+    prim["RadiusY"] = _length(radius_y, unit)
+    prim["RadiusZ"] = _length(radius_z, unit)
+    return prim
+
+
+def create_cylinder_primitive(
+    name: str,
+    medium_id: str,
+    position_x: float,
+    position_y: float,
+    position_z: float,
+    radius: float,
+    height: float,
+    axis: str = "Z",
+    rotation_x: float = 0.0,
+    rotation_y: float = 0.0,
+    rotation_z: float = 0.0,
+    position_anchor: str = "BottomCenter",
+    unit: str = "Micrometers",
+    subpixel: Optional[bool] = None,
+) -> Dict[str, Any]:
+    """
+    Create a cylinder primitive (CylinderPrimitive).
+
+    Args:
+        name: Primitive name
+        medium_id: Medium/Material ID
+        position_x, position_y, position_z: Anchor point (see position_anchor)
+        radius: Radius
+        height: Extent along ``axis``
+        axis: "X", "Y" or "Z" (default "Z")
+        rotation_x, rotation_y, rotation_z: Rotation in degrees
+        position_anchor: "BottomCenter" (default, as the server and Studio): Position is the
+            centre of the base face and the cylinder extends +height along ``axis``;
+            "Center": Position is the geometric centre; "TopCenter": centre of the top face.
+        unit: Unit of measurement
+        subpixel: True / False / None (follow the simulation-level setting)
+    """
+    anchor = _check_anchor(position_anchor, _AXIAL_ANCHORS, "Cylinder")
+    prim = _primitive_base("Cylinder", name, medium_id, position_x, position_y, position_z,
+                           rotation_x, rotation_y, rotation_z, anchor, unit, subpixel)
+    prim["Radius"] = _length(radius, unit)
+    prim["Height"] = _length(height, unit)
+    prim["Axis"] = _check_axis(axis)
+    return prim
+
+
+def create_cone_primitive(
+    name: str,
+    medium_id: str,
+    position_x: float,
+    position_y: float,
+    position_z: float,
+    radius: float,
+    height: float,
+    axis: str = "Z",
+    rotation_x: float = 0.0,
+    rotation_y: float = 0.0,
+    rotation_z: float = 0.0,
+    position_anchor: str = "BottomCenter",
+    unit: str = "Micrometers",
+    subpixel: Optional[bool] = None,
+) -> Dict[str, Any]:
+    """
+    Create a cone primitive (ConePrimitive). The base is a disc of ``radius``; the apex
+    lies ``height`` further along +``axis``.
+
+    Args:
+        name: Primitive name
+        medium_id: Medium/Material ID
+        position_x, position_y, position_z: Anchor point (see position_anchor)
+        radius: Base radius
+        height: Base-to-apex distance along ``axis``
+        axis: "X", "Y" or "Z" (default "Z")
+        rotation_x, rotation_y, rotation_z: Rotation in degrees
+        position_anchor: "BottomCenter" (default, as the server and Studio): Position is the
+            centre of the base; "Center": Position is the CENTROID (height/4 above the base,
+            not height/2); "TopCenter": Position is the apex.
+        unit: Unit of measurement
+        subpixel: True / False / None (follow the simulation-level setting)
+    """
+    anchor = _check_anchor(position_anchor, _AXIAL_ANCHORS, "Cone")
+    prim = _primitive_base("Cone", name, medium_id, position_x, position_y, position_z,
+                           rotation_x, rotation_y, rotation_z, anchor, unit, subpixel)
+    prim["Radius"] = _length(radius, unit)
+    prim["Height"] = _length(height, unit)
+    prim["Axis"] = _check_axis(axis)
+    return prim
+
+
+def create_prism_primitive(
+    name: str,
+    medium_id: str,
+    position_x: float,
+    position_y: float,
+    position_z: float,
+    radius: float,
+    height: float,
+    number_of_sides: int = 6,
+    axis: str = "Z",
+    top_scale: float = 1.0,
+    twist_degrees: float = 0.0,
+    rotation_x: float = 0.0,
+    rotation_y: float = 0.0,
+    rotation_z: float = 0.0,
+    position_anchor: str = "BottomCenter",
+    unit: str = "Micrometers",
+    subpixel: Optional[bool] = None,
+) -> Dict[str, Any]:
+    """
+    Create a regular N-sided prism primitive (PrismPrimitive): a regular polygon with
+    ``number_of_sides`` corners on a circle of ``radius`` extruded ``height`` along ``axis``.
+
+    Args:
+        name: Primitive name
+        medium_id: Medium/Material ID
+        position_x, position_y, position_z: Anchor point (see position_anchor)
+        radius: Circumradius of the bottom polygon
+        height: Extent along ``axis``
+        number_of_sides: Polygon corners, integer >= 3 (3 = triangular prism, 4 = square,
+            large N approaches a cylinder). Default 6.
+        axis: "X", "Y" or "Z" (default "Z")
+        top_scale: Top-ring radius factor: 1 = straight prism (default), 0 = pyramid,
+            > 1 = flared
+        twist_degrees: Rotation of the top ring about ``axis`` in degrees (default 0)
+        rotation_x, rotation_y, rotation_z: Rotation in degrees
+        position_anchor: "BottomCenter" (default, as the server and Studio), "Center" or
+            "TopCenter" (±height/2 along ``axis``, as for a cylinder).
+        unit: Unit of measurement
+        subpixel: True / False / None (follow the simulation-level setting)
+    """
+    anchor = _check_anchor(position_anchor, _AXIAL_ANCHORS, "Prism")
+    n = int(number_of_sides)
+    if n != number_of_sides or n < 3:
+        raise ValueError(f"number_of_sides must be an integer >= 3, got {number_of_sides!r}")
+    if top_scale < 0:
+        raise ValueError(f"top_scale must be >= 0, got {top_scale!r}")
+    prim = _primitive_base("Prism", name, medium_id, position_x, position_y, position_z,
+                           rotation_x, rotation_y, rotation_z, anchor, unit, subpixel)
+    prim["Radius"] = _length(radius, unit)
+    prim["Height"] = _length(height, unit)
+    prim["Axis"] = _check_axis(axis)
+    prim["NumberOfSides"] = n
+    prim["TopScale"] = float(top_scale)
+    prim["TwistDegrees"] = float(twist_degrees)
+    return prim
+
+
+def create_gds_layer_config(
+    layer_number: int,
+    medium_id: Optional[str] = None,
+    height_um: Optional[float] = None,
+    z_offset_um: Optional[float] = None,
+) -> Dict[str, Any]:
+    """
+    Per-layer settings for create_gds_primitive(layer_configs=...) (GdsLayerConfig).
+
+    Args:
+        layer_number: GDS layer number
+        medium_id: Medium for this layer; None = the GDS primitive's medium_id
+        height_um: Extrusion thickness in micrometres; None = the primitive's layer_height_um
+        z_offset_um: Bottom of the layer in micrometres relative to the primitive;
+            None = auto-stacked
+    """
+    cfg: Dict[str, Any] = {"LayerNumber": int(layer_number)}
+    if medium_id is not None:
+        cfg["MediumId"] = medium_id
+    if height_um is not None:
+        cfg["Height"] = float(height_um)
+    if z_offset_um is not None:
+        cfg["ZOffset"] = float(z_offset_um)
+    return cfg
+
+
+def create_gds_structure_override(
+    structure_name: str,
+    layer_overrides: Optional[List[Dict[str, Any]]] = None,
+) -> Dict[str, Any]:
+    """
+    Per-structure (GDS cell) overrides for create_gds_primitive(structure_overrides=...)
+    (GdsStructureConfig). ``layer_overrides`` is a list built with create_gds_layer_config()
+    (same keys as GdsStructureLayerOverride: LayerNumber, MediumId, Height, ZOffset); unset
+    fields inherit from the primitive's layer_configs.
+    """
+    cfg: Dict[str, Any] = {"StructureName": structure_name}
+    if layer_overrides is not None:
+        cfg["LayerOverrides"] = list(layer_overrides)
+    return cfg
+
+
+def create_gds_primitive(
+    name: str,
+    file_id: str,
+    medium_id: str,
+    center_x: float = 0.0,
+    center_y: float = 0.0,
+    center_z: float = 0.0,
+    layer_height_um: float = 1.0,
+    selected_layers: Optional[List[int]] = None,
+    layer_configs: Optional[List[Dict[str, Any]]] = None,
+    structure_overrides: Optional[List[Dict[str, Any]]] = None,
+    metadata_file_id: Optional[str] = None,
+    voxelization_method: str = "ViaStl",
+    rotation_x: float = 0.0,
+    rotation_y: float = 0.0,
+    rotation_z: float = 0.0,
+    scale_x: float = 1.0,
+    scale_y: float = 1.0,
+    scale_z: float = 1.0,
+    position_anchor: str = "Center",
+    unit: str = "Micrometers",
+    subpixel: Optional[bool] = None,
+) -> Dict[str, Any]:
+    """
+    Create a GDSII layout primitive (GdsModelPrimitive) from an uploaded .gds file.
+
+    The layout's polygons are extruded per layer; Position is the centre of the top
+    structure's bounding box. Layer thickness and offsets are plain numbers in
+    MICROMETRES on the server model (not Length objects), whatever ``unit`` is.
+
+    Args:
+        name: Primitive name
+        file_id: File id of the uploaded GDS file (GdsDataId), as for create_stl_primitive
+        medium_id: Default medium for every layer
+        center_x, center_y, center_z: Position of the layout centre
+        layer_height_um: Default extrusion thickness of each layer in µm (LayerHeight)
+        selected_layers: Layer numbers to include; None = all layers
+        layer_configs: Per-layer settings from create_gds_layer_config(); None = every layer
+            uses medium_id / layer_height_um (legacy mode)
+        structure_overrides: Per-structure (cell) overrides from
+            create_gds_structure_override(); None = none
+        metadata_file_id: Optional uploaded layer-metadata YML file id (GdsMetadataId)
+        voxelization_method: "ViaStl" (default) or "Direct"
+        rotation_x, rotation_y, rotation_z: Rotation in degrees
+        scale_x, scale_y, scale_z: Scale factors
+        position_anchor: Stored as given (default "Center"); the server treats Position as
+            the layout centre whatever the anchor.
+        unit: Unit of Position
+        subpixel: True / False / None (follow the simulation-level setting)
+    """
+    anchor = _check_anchor(position_anchor, _POSITION_ANCHORS, "GdsModel")
+    method = str(voxelization_method)
+    if method not in ("ViaStl", "Direct"):
+        raise ValueError(f"voxelization_method must be 'ViaStl' or 'Direct', got {voxelization_method!r}")
+    prim = _primitive_base("GdsModel", name, medium_id, center_x, center_y, center_z,
+                           rotation_x, rotation_y, rotation_z, anchor, unit, subpixel)
+    prim["GdsDataId"] = file_id
+    prim["ScaleFactors"] = {"X": float(scale_x), "Y": float(scale_y), "Z": float(scale_z)}
+    prim["LayerHeight"] = float(layer_height_um)
+    prim["VoxelizationMethod"] = method
+    if metadata_file_id is not None:
+        prim["GdsMetadataId"] = metadata_file_id
+    if selected_layers is not None:
+        prim["SelectedLayers"] = [int(n) for n in selected_layers]
+    if layer_configs is not None:
+        prim["LayerConfigs"] = list(layer_configs)
+    if structure_overrides is not None:
+        prim["StructureOverrides"] = list(structure_overrides)
+    return prim
 
 
 def create_medium(
@@ -189,9 +631,8 @@ def create_point_source(
     return {
         "Id": str(uuid.uuid4()),
         "Name": name,
-        "Id": str(uuid.uuid4()),
         "SourceType": "Point",
-        "isEnabled": True,
+        "IsEnabled": True,
         "UseInternalPythonSource": False,
         "Position": {
             "X": {"Value": position_x, "Unit": unit},
@@ -357,7 +798,9 @@ def create_voxels_model_primitive(
     grid_nz: int = 32,
     data_format: str = "Float32",
     data_type: str = "RefractiveIndex",
-    unit: str = "Micrometers"
+    unit: str = "Micrometers",
+    subpixel: Optional[bool] = None,
+    antialias_width: Optional[float] = None,
 ) -> Dict[str, Any]:
     """
     Create VoxelsModel primitive for arbitrary refractive index distributions
@@ -372,6 +815,19 @@ def create_voxels_model_primitive(
         data_format: 'Float32', 'Float64', 'Complex64', 'Complex128'
         data_type: 'RefractiveIndex', 'ComplexRefractiveIndex', 'Permittivity', 'ComplexPermittivity'
         unit: Unit of measurement
+
+        subpixel: True anti-aliases the array on the service:
+            - array at the simulation voxel size: softened IN PLACE by a normalised Gaussian of
+              ``antialias_width`` voxels on the permittivity (same resolution, volume kept).
+              On reference shapes it halves the interface error vs true sub-pixel values.
+            - array finer by a whole number per axis (voxel size = simulation voxel / k): each
+              k_x x k_y x k_z block is averaged into one simulation voxel (the same rule as the
+              shapes' sub-pixel probes); cells the array only partly covers blend with what
+              lies underneath.
+            None/False: the array must be at the simulation voxel size and is copied voxel for
+            voxel. The simulation-level ``subpixel_factor`` does not apply to voxel arrays.
+        antialias_width: Gaussian width (standard deviation, voxels) for the in-place case;
+            None = 0.5 (best on average); thin waveguides prefer ~0.7. Range 0.1-3.
     """
     return {
         "ShapeType": "VoxelsModel",
@@ -395,7 +851,9 @@ def create_voxels_model_primitive(
         },
         "DataFormat": data_format,
         "DataType": data_type,
-        "Rotation": {"X": 0, "Y": 0, "Z": 0}
+        "Rotation": {"X": 0, "Y": 0, "Z": 0},
+        **({"SubPixel": bool(subpixel)} if subpixel is not None else {}),
+        **({"AntiAliasWidth": float(antialias_width)} if antialias_width is not None else {}),
     }
 
 
@@ -701,6 +1159,16 @@ def create_wavesim_properties(
             derives the iteration count from this distance and it OVERRIDES
             residual_norm_max_iterations (threshold still stops the run early).
             C++ engine only.
+        subpixel_factor: Sub-pixel probe count per axis, s (1..64, 16 is the reference
+            value). It is used by every primitive whose SubPixel is true; a primitive with
+            no explicit flag follows the simulation-level mode, which this argument sets to
+            SubPixel (s > 1) — so passing it alone smooths every primitive, STL and GDSII
+            (the pre-1.10 behaviour). Per-primitive flags (``subpixel=True`` on the
+            primitive helpers) are the preferred way to choose which shapes are smoothed.
+            When this is None but some primitive carries an explicit flag, the factor is
+            emitted with Mode "Staircase" and s = 16, so flagged primitives have a probe
+            count and unflagged ones stay staircased. VoxelsModel arrays are never
+            re-sampled.
     """
     props = {
         "SimulationDomain": simulation_domain,
@@ -764,6 +1232,8 @@ def create_wavesim_properties(
     # Staircase. The service probes each voxel of primitives / STL / GDSII at
     # subpixel_factor points per axis and stores the mean permittivity; it does NOT
     # re-sample a VoxelsModel array (average that yourself before upload).
+    # Mode is the default for primitives without an explicit "SubPixel" flag; flagged
+    # primitives decide for themselves and use Factor as their probe count.
     if subpixel_factor is not None:
         s = int(subpixel_factor)
         if s < 1 or s > 64:
@@ -774,6 +1244,13 @@ def create_wavesim_properties(
             "Rule": "ArithmeticMean",
             "InterfaceOnly": True,
         }
+    elif any(isinstance(p, dict) and "SubPixel" in p for p in (primitives or [])):
+        props["PermittivitySampling"] = {
+            "Mode": "Staircase",
+            "Factor": 16,
+            "Rule": "ArithmeticMean",
+            "InterfaceOnly": True,
+        }
 
     return props
 

{wavesimpro-1.9.0 → wavesimpro-1.10.1}/src/wavesimpro.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: wavesimpro
-Version: 1.9.0
+Version: 1.10.1
 Summary: WavesimPro Python API — cloud execution client for the Rayfos simulation platform
 Author: Rayfos
 Project-URL: Repository, https://github.com/rayfos/wavesimpro
@@ -59,8 +59,15 @@ field = wp.read_binary_field(run.download("output.bin"))
 
 ## What the API covers
 
-- Setup helpers for domains, media, primitives (box, STL, voxel arrays), sources
-  (point, plane wave, Gaussian beam, custom field, engine-solved waveguide mode) and monitors.
+- Setup helpers for domains, media, primitives (box, sphere, ellipsoid, cylinder, cone,
+  N-sided prism, STL, GDSII layouts, voxel arrays), sources (point, plane wave, Gaussian beam,
+  custom field, custom-from-file, engine-solved waveguide mode) and monitors:
+  `create_box_primitive`, `create_sphere_primitive`, `create_ellipsoid_primitive`,
+  `create_cylinder_primitive`, `create_cone_primitive`, `create_prism_primitive`,
+  `create_stl_primitive`, `create_gds_primitive` (with `create_gds_layer_config` /
+  `create_gds_structure_override`), `create_voxels_model_primitive`.
+- Per-primitive sub-pixel flag (`subpixel=True/False` on every shape, STL and GDSII helper)
+  to choose which shapes get smoothed interfaces.
 - Per-axis pixel sizes (`pixel_size=[dx, dy, dz]`) and sub-pixel permittivity averaging
   (`subpixel_factor=`), when the compute node supports them.
 - Preflight memory check and cost estimate before a run.

{wavesimpro-1.9.0 → wavesimpro-1.10.1}/src/wavesimpro.egg-info/SOURCES.txt

@@ -16,4 +16,5 @@ src/wavesimpro.egg-info/PKG-INFO
 src/wavesimpro.egg-info/SOURCES.txt
 src/wavesimpro.egg-info/dependency_links.txt
 src/wavesimpro.egg-info/requires.txt
-src/wavesimpro.egg-info/top_level.txt
+src/wavesimpro.egg-info/top_level.txt
+tests/test_command_wait.py

wavesimpro-1.10.1/tests/test_command_wait.py

@@ -0,0 +1,64 @@
+"""wait_for_command_completion must work with both server shapes of the command status:
+current servers send the state NAME in "status"; older ones sent an integer "commandStatus"."""
+import pytest
+
+from wavesimpro import RayfosClient, command_status_name, is_terminal_command_status
+from wavesimpro.exceptions import RayfosAPIError
+
+
+class FakeClient(RayfosClient):
+    """RayfosClient whose HTTP layer is replaced by a scripted sequence of status replies."""
+
+    def __init__(self, replies, created=None):  # noqa: D401 - no network setup
+        self._replies = list(replies)
+        self._created = created
+        self.created_with = None
+
+    def get_command_status(self, command_id):
+        return self._replies.pop(0) if len(self._replies) > 1 else self._replies[0]
+
+    def create_command(self, project_id, version_id, engine_preference='Any', use_gpu=None, preferred_machine_id=None):
+        self.created_with = dict(engine_preference=engine_preference, use_gpu=use_gpu, preferred_machine_id=preferred_machine_id)
+        return dict(self._created)
+
+
+def test_current_server_shape_returns_on_completed():
+    c = FakeClient([{"id": "c1", "status": "Running"}, {"id": "c1", "status": "Completed", "outputFileIds": ["f"]}])
+    final = c.wait_for_command_completion("c1", poll_interval=0, timeout=5)
+    assert final["outputFileIds"] == ["f"]
+
+
+def test_legacy_integer_shape_still_works():
+    c = FakeClient([{"commandStatus": 9}, {"commandStatus": 10}])
+    assert c.wait_for_command_completion("c1", poll_interval=0, timeout=5)["commandStatus"] == 10
+
+
+@pytest.mark.parametrize("state", ["Failed", "FailedRemovedFromMachine", "Cancelled", "Deleted"])
+def test_terminal_failures_raise(state):
+    c = FakeClient([{"status": state, "statusText": "boom"}])
+    with pytest.raises(RayfosAPIError):
+        c.wait_for_command_completion("c1", poll_interval=0, timeout=5)
+
+
+def test_timeout_names_the_last_state():
+    c = FakeClient([{"status": "Running"}])
+    with pytest.raises(TimeoutError, match="Running"):
+        c.wait_for_command_completion("c1", poll_interval=0.01, timeout=0.05)
+
+
+def test_status_helpers():
+    assert command_status_name({"status": "Completed"}) == "Completed"
+    assert command_status_name({"status": "completed"}) == "Completed"
+    assert command_status_name({"commandStatus": 11}) == "Failed"
+    assert command_status_name({"commandStatus": "10"}) == "Completed"
+    assert command_status_name({"status": "", "commandStatus": 9}) == "Running"
+    assert command_status_name({}) == "Unknown"
+    assert is_terminal_command_status("Completed") and not is_terminal_command_status("Running")
+    assert RayfosClient._parse_command_status("Running") == "Running"
+    assert RayfosClient._parse_command_status(10) == "Completed"
+
+
+def test_create_command_and_wait_pins_the_machine_and_accepts_either_id_key():
+    c = FakeClient([{"status": "Completed"}], created={"commandId": "c9", "status": "New"})
+    c.create_command_and_wait("p", "v", local_machine_service_id="node-1", poll_interval=0, timeout=5)
+    assert c.created_with == {"engine_preference": "Any", "use_gpu": None, "preferred_machine_id": "node-1"}