wavesimpro 1.10.2__tar.gz → 1.17.0__tar.gz

{wavesimpro-1.10.2 → wavesimpro-1.17.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: wavesimpro
-Version: 1.10.2
+Version: 1.17.0
 Summary: WavesimPro Python API — cloud execution client for the Rayfos simulation platform
 Author: Rayfos
 Project-URL: Repository, https://github.com/rayfos/wavesimpro
@@ -50,7 +50,8 @@ props = wp.create_wavesim_properties(
     domain=wp.create_simulation_domain(20, 20, 20),
     mediums=[wp.create_medium("Silicon", 3.48, 0.0)],
     primitives=[wp.create_box_primitive("core", 0, 0, 0, 10, 0.5, 20, medium="Silicon")],
-    sources=[wp.create_mode_source("in", 0, 0, -8.0, polarization="X")],
+    # TE0 solved by the engine on the z = -6 um voxel layer (index 40 of 200), launched along +z
+    sources=[wp.create_mode_source("in", 0, 0, -6.0, axis="z", plane_index=40, polarization="TE")],
     monitors=[wp.create_monitor("out", 0, 0, 8.0, 10, 10, 0)],
 )
 run = wp.simulate(props, name="strip waveguide")
@@ -74,4 +75,38 @@ field = wp.read_binary_field(run.download("output.bin"))
 - Preflight memory check and cost estimate before a run.
 - Binary upload/download helpers for permittivity volumes, source fields and monitors.
 
+## Monitors: which voxels you get
+
+A monitor is an axis-aligned box in micrometres, relative to the coordinate-system centre. The
+domain of N voxels spans [-S/2, S/2], so voxel *i* occupies [-S/2 + i·v, -S/2 + (i+1)·v] with
+v = S/N (centre at -S/2 + (i+0.5)·v, for even and odd N alike). The compute node extracts the
+**outer cover** of the box: every voxel it touches — first index floor(lo), last index
+ceil(hi) − 1 with lo/hi the box edges in voxel units. An edge exactly on a voxel face does not
+pull in the neighbour; a zero-thickness box is the one voxel containing the plane. So a box of
+exactly k voxels aligned to the grid gives k planes, and the same box centred on a voxel centre
+straddles k + 1; the result is never smaller than what you asked for unless the domain clamps it.
+
+The node writes `monitors.json` next to the `monitor_<name>.bin` files with, per monitor, the
+inclusive index ranges, the shape, the voxel size and the realised physical box; read it with
+`run.monitor_regions()`. Monitor files are full resolution — nothing is downsampled on download.
+
+## Cost before upload
+
+`client.preflight_check(..., max_iterations=n)` (called for you by `simulate*`, `submit` and
+`execute_via_api`) returns a `cost` block on the cloud server: the upper-bound compute-token
+cost at the run's iteration cap (voxels × iterations × field components × rate), your remaining
+balance and whether the submit would be allowed. The run is charged for the iterations it
+actually takes. The high-level calls stop before uploading anything when the cost is refused.
+`client.get_quota()` returns the balance; `client.estimate_cost(project_id, version_id)` prices a
+saved version.
+
+## Errors and warnings
+
+Every `RayfosAPIError` message carries the server's full detail: the message, each
+`errors[]`/`warnings[]` entry and, for a quota refusal, the estimated cost and remaining balance.
+Pass `sampling_warnings=False` (or `configure(sampling_warnings=False)`) to silence the
+"pixels per wavelength" advisory when your sampling is deliberate; Nyquist warnings stay.
+`run.status()["commandStatus"]["engine"]` names the engine the node actually ran (`"Cpp"` or
+`"Python"`), also for `engine="Any"`.
+
 See `CHANGELOG.md` for what each version added. Issues and feature requests: support@rayfos.com.

wavesimpro-1.17.0/README.md

@@ -0,0 +1,89 @@
+# wavesimpro
+
+Python client for the Rayfos Wavesim cloud: build a simulation setup, run it on a Rayfos
+compute node, and read the results back as NumPy arrays.
+
+Wavesim is a single-wavelength frequency-domain solver (vectorial Maxwell when a polarized
+source is present, scalar Helmholtz otherwise). This package talks to the Rayfos JobServer
+REST API; it does not contain the solver.
+
+## Install
+
+```bash
+pip install wavesimpro
+python -m wavesimpro setup      # one-time: API key + server URL wizard
+```
+
+The wizard stores the credentials; `wavesimpro.configure(api_key=..., api_url=...)` sets
+them for one process instead.
+
+## Quick start
+
+```python
+import wavesimpro as wp
+
+props = wp.create_wavesim_properties(
+    wavelength=1.0, pixel_size=0.1, boundary_width=5.0,
+    domain=wp.create_simulation_domain(20, 20, 20),
+    mediums=[wp.create_medium("Silicon", 3.48, 0.0)],
+    primitives=[wp.create_box_primitive("core", 0, 0, 0, 10, 0.5, 20, medium="Silicon")],
+    # TE0 solved by the engine on the z = -6 um voxel layer (index 40 of 200), launched along +z
+    sources=[wp.create_mode_source("in", 0, 0, -6.0, axis="z", plane_index=40, polarization="TE")],
+    monitors=[wp.create_monitor("out", 0, 0, 8.0, 10, 10, 0)],
+)
+run = wp.simulate(props, name="strip waveguide")
+field = wp.read_binary_field(run.download("output.bin"))
+```
+
+## What the API covers
+
+- 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. Off by default: a setup with no averaged
+  shape is voxelised exactly as before 1.10 and runs on every compute node.
+- 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.
+- Binary upload/download helpers for permittivity volumes, source fields and monitors.
+
+## Monitors: which voxels you get
+
+A monitor is an axis-aligned box in micrometres, relative to the coordinate-system centre. The
+domain of N voxels spans [-S/2, S/2], so voxel *i* occupies [-S/2 + i·v, -S/2 + (i+1)·v] with
+v = S/N (centre at -S/2 + (i+0.5)·v, for even and odd N alike). The compute node extracts the
+**outer cover** of the box: every voxel it touches — first index floor(lo), last index
+ceil(hi) − 1 with lo/hi the box edges in voxel units. An edge exactly on a voxel face does not
+pull in the neighbour; a zero-thickness box is the one voxel containing the plane. So a box of
+exactly k voxels aligned to the grid gives k planes, and the same box centred on a voxel centre
+straddles k + 1; the result is never smaller than what you asked for unless the domain clamps it.
+
+The node writes `monitors.json` next to the `monitor_<name>.bin` files with, per monitor, the
+inclusive index ranges, the shape, the voxel size and the realised physical box; read it with
+`run.monitor_regions()`. Monitor files are full resolution — nothing is downsampled on download.
+
+## Cost before upload
+
+`client.preflight_check(..., max_iterations=n)` (called for you by `simulate*`, `submit` and
+`execute_via_api`) returns a `cost` block on the cloud server: the upper-bound compute-token
+cost at the run's iteration cap (voxels × iterations × field components × rate), your remaining
+balance and whether the submit would be allowed. The run is charged for the iterations it
+actually takes. The high-level calls stop before uploading anything when the cost is refused.
+`client.get_quota()` returns the balance; `client.estimate_cost(project_id, version_id)` prices a
+saved version.
+
+## Errors and warnings
+
+Every `RayfosAPIError` message carries the server's full detail: the message, each
+`errors[]`/`warnings[]` entry and, for a quota refusal, the estimated cost and remaining balance.
+Pass `sampling_warnings=False` (or `configure(sampling_warnings=False)`) to silence the
+"pixels per wavelength" advisory when your sampling is deliberate; Nyquist warnings stay.
+`run.status()["commandStatus"]["engine"]` names the engine the node actually ran (`"Cpp"` or
+`"Python"`), also for `engine="Any"`.
+
+See `CHANGELOG.md` for what each version added. Issues and feature requests: support@rayfos.com.

{wavesimpro-1.10.2 → wavesimpro-1.17.0}/pyproject.toml

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

{wavesimpro-1.10.2 → wavesimpro-1.17.0}/src/wavesimpro/__init__.py

@@ -29,6 +29,7 @@ from .binary_utils import (
 from .validate import validate_parameters, ParameterValidationError
 from .execute import execute_via_api
 from .simulate import simulate, simulate_pro, configure
+from .studio_mode import solve_studio_mode, add_studio_mode_source, mode_slice
 from .json_helper import (
     create_simulation_domain,
     create_stl_primitive,
@@ -54,7 +55,7 @@ from .json_helper import (
     parse_progress_data,
 )
 
-__version__ = "1.10.2"
+__version__ = "1.17.0"
 __all__ = [
     # Client
     "RayfosClient",

{wavesimpro-1.10.2 → wavesimpro-1.17.0}/src/wavesimpro/client.py

@@ -248,10 +248,11 @@ class RayfosClient:
         except requests.exceptions.HTTPError as e:
             status_code = response.status_code
             
-            # Try to get error message from response
+            # The server's full error detail: message + errors[].details + the quota figures of
+            # a 402. It used to be only "message"; the useful part sat in exception.response.text.
             try:
                 error_data = response.json()
-                message = error_data.get("message") or error_data.get("error") or str(e)
+                message = format_error_body(error_data, str(e))
             except ValueError:
                 message = response.text or str(e)
             
@@ -329,10 +330,11 @@ class RayfosClient:
         engine_preference: str = "Any",
         use_gpu: Optional[bool] = None,
         is_vectorial: Optional[bool] = None,
+        max_iterations: Optional[int] = None,
     ) -> Dict[str, Any]:
         """
         Ask the server whether a simulation of the given shape will fit on the
-        available compute targets, BEFORE uploading any files.
+        available compute targets, and what it will cost, BEFORE uploading any files.
 
         This calls POST /api/preflightCheck. The server runs the engine's own
         memory predictor (Wavesim.MemoryPredict) on exactly the grid the engine
@@ -352,16 +354,31 @@ class RayfosClient:
             is_vectorial: True = Maxwell (3 field components), False = Helmholtz
                 (scalar). Memory differs ~3x, so always pass it: this payload
                 carries no sources for the server to infer it from.
+            max_iterations: the run's residual-norm iteration cap. The cost is
+                priced on it (voxels x iterations x components x rate), so pass
+                the value the run will use; None = the server default (10000).
 
         Returns:
             PreflightCheckResponse dict with keys:
               - status: "Ok" | "Warning" | "Error"
               - description: one-sentence verdict (memory, grid, which machine fits)
               - gpuPathMemoryGB / cpuPathMemoryGB: peak memory of each path
+              - hostMemoryGB: peak system RAM on the compute node for the requested
+                path (voxelization, or the result field gathered back to the host);
+                checked against each node's RAM since server 1.17.0
               - estimate: { nx, ny, nz, paddedNx, ..., totalMemoryGB, ... } for the requested path
               - machines: [{ machineId, gpuMemoryGB, cpuMemoryGB, fitsOnGpu, fitsOnCpu, ... }]
               - recommendedMachineId
               - suggestedAdjustments: [str, ...]
+              - cost (cloud server only, else absent/None): the compute-token
+                check the submit will apply:
+                  { allowed, reason, enforced, computeTokensRemaining,
+                    estimate: { estimatedCost, iterations, totalVoxels,
+                                componentsPerCell, rate, target, ... } }
+                estimatedCost is the UPPER BOUND (max_iterations); the run is
+                reconciled to the iterations it actually took. Stop before
+                uploading when cost["allowed"] is False. See
+                ``preflight_cost_summary`` for a one-line rendering.
         """
         size_x, size_y, size_z = domain_um
         periodic_x, periodic_y, periodic_z = periodic
@@ -399,6 +416,7 @@ class RayfosClient:
                 "periodicX": bool(periodic_x),
                 "periodicY": bool(periodic_y),
                 "periodicZ": bool(periodic_z),
+                **({"residualNormMaxIterations": int(max_iterations)} if max_iterations else {}),
             },
             "enginePreference": engine_preference,
             "useGpu": use_gpu,
@@ -415,6 +433,38 @@ class RayfosClient:
         response = self.session.post(url, json=body, timeout=self.config.timeout, verify=verify)
         return self._handle_response(response)
 
+    def get_quota(self) -> Dict[str, Any]:
+        """
+        The caller's compute-token and storage quota: GET /api/quota/me.
+
+        Returns a dict with (camelCase) ``computeTokensGranted``, ``computeTokensUsed``,
+        ``computeTokensReserved``, ``computeTokensRemaining``, the storage figures and the
+        allowance period. ``computeTokensRemaining`` is what a submit is checked against.
+        """
+        return self._get("/api/quota/me")
+
+    def estimate_cost(
+        self,
+        project_id: str,
+        version_id: str,
+        use_gpu: Optional[bool] = None,
+        engine_preference: str = "Any",
+    ) -> Dict[str, Any]:
+        """
+        Price a SAVED version without submitting it: POST /api/quota/estimate.
+
+        Same result shape as the ``cost`` block of ``preflight_check``: ``allowed``,
+        ``reason``, ``computeTokensRemaining`` and ``estimate.estimatedCost`` (the upper
+        bound at the version's max iterations). Use ``preflight_check(..., max_iterations=)``
+        instead when nothing has been uploaded yet.
+        """
+        return self._post("/api/quota/estimate", json={
+            "projectId": project_id,
+            "versionId": version_id,
+            "useGpu": use_gpu,
+            "enginePreference": engine_preference,
+        })
+
     def get_projects(self) -> List[Dict[str, Any]]:
         """
         Get all projects for the authenticated user
@@ -1890,3 +1940,61 @@ class RayfosClient:
         """Command state name from an integer (legacy ``commandStatus``) or a name (current ``status``)."""
         return command_status_name({"status": status_value})
 
+
+def format_error_body(data: Any, fallback: str) -> str:
+    """Render a Rayfos error body in full: ``message``, then each of ``errors[]`` /
+    ``warnings[]`` (strings, or ``{code, message, field, details}`` objects from the server's
+    simulation validation), then the figures of a quota refusal (402: ``estimatedCost``,
+    ``remaining``, ``resolution``, ``maxGridCells``)."""
+    if not isinstance(data, dict):
+        return str(data) if data else fallback
+    parts = []
+    head = data.get("message") or data.get("error") or data.get("title") or data.get("detail")
+    parts.append(str(head) if head else fallback)
+    for key, label in (("errors", "error"), ("warnings", "warning")):
+        items = data.get(key)
+        if not isinstance(items, list):
+            continue
+        for it in items:
+            if isinstance(it, dict):
+                bits = [str(it[k]) for k in ("field", "code", "message", "details", "detail") if it.get(k)]
+                text = ": ".join(bits) if bits else str(it)
+            else:
+                text = str(it)
+            parts.append(f"  [{label}] {text}")
+    quota = [f"{k}={data[k]}" for k in ("reason", "estimatedCost", "remaining", "resolution", "totalVoxels", "maxGridCells")
+             if data.get(k) is not None]
+    if quota:
+        parts.append("  " + ", ".join(quota))
+    return "\n".join(parts)
+
+
+def preflight_cost_summary(preflight: Optional[Dict[str, Any]]) -> Optional[str]:
+    """One line describing the ``cost`` block of a ``preflight_check`` result, or None when the
+    server did not price the run (local machine service / older server)."""
+    cost = (preflight or {}).get("cost") if isinstance(preflight, dict) else None
+    if not isinstance(cost, dict):
+        return None
+    est = cost.get("estimate") or {}
+    tokens = est.get("estimatedCost")
+    remaining = cost.get("computeTokensRemaining")
+    iters = est.get("iterations")
+    voxels = est.get("totalVoxels")
+    comps = est.get("componentsPerCell")
+    text = f"Cost: up to {tokens:,} compute tokens" if isinstance(tokens, (int, float)) else "Cost: unknown"
+    detail = []
+    if voxels:
+        detail.append(f"{voxels:,} voxels")
+    if iters:
+        detail.append(f"max {iters:,} iterations")
+    if comps:
+        detail.append(f"{comps} component(s)")
+    if detail:
+        text += " (" + " x ".join(detail) + "; charged for the iterations actually run)"
+    if isinstance(remaining, (int, float)):
+        text += f"; balance {remaining:,}"
+    if cost.get("enforced") is False:
+        text += "; quota not enforced on this server"
+    elif cost.get("allowed") is False:
+        text += f"; NOT allowed ({cost.get('reason')})"
+    return text