wavesimpro 1.16.0__tar.gz → 1.17.0__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: wavesimpro
-Version: 1.16.0
+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
@@ -75,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.16.0 → wavesimpro-1.17.0}/README.md

@@ -52,4 +52,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.16.0 → wavesimpro-1.17.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "wavesimpro"
-version = "1.16.0"
+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.16.0 → wavesimpro-1.17.0}/src/wavesimpro/__init__.py

@@ -55,7 +55,7 @@ from .json_helper import (
     parse_progress_data,
 )
 
-__version__ = "1.16.0"
+__version__ = "1.17.0"
 __all__ = [
     # Client
     "RayfosClient",

{wavesimpro-1.16.0 → 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

{wavesimpro-1.16.0 → wavesimpro-1.17.0}/src/wavesimpro/execute.py

@@ -19,7 +19,7 @@ from typing import Tuple, Optional, Callable, Dict, Any, List, Union, Sequence
 
 import numpy as np
 
-from .client import RayfosClient
+from .client import RayfosClient, preflight_cost_summary
 from .binary_utils import (
     upload_array_as_binary_zipped,
     upload_source_field_as_binary_zipped,
@@ -147,6 +147,7 @@ def execute_via_api(
     alpha: float = 0.75,
     keep_residuals_list: bool = False,
     strict_validation: bool = False,
+    sampling_warnings: bool = True,
     gpu_memory_max_gb: Optional[float] = None,
     monitors: Optional[List[Dict[str, Any]]] = None,
     pseudo_propagation_distance: float = 0.0,
@@ -374,6 +375,7 @@ def execute_via_api(
             engine_preference=engine_preference,
             use_gpu=use_gpu,
             is_vectorial=is_vectorial,
+            max_iterations=max_iterations,
         )
     except Exception as exc:
         logger.warning(f"Preflight check failed ({exc}). Proceeding without it.")
@@ -393,6 +395,12 @@ def execute_via_api(
         (logger.warning if status == "warning" else logger.info)(f"Preflight: {pre_description}")
         for s in suggestions:
             logger.info(f"  Suggestion: {s}")
+        cost_line = preflight_cost_summary(pre)
+        if cost_line:
+            logger.info(f"Preflight: {cost_line}")
+            cost = pre.get("cost") or {}
+            if cost.get("allowed") is False and cost.get("enforced", True):
+                raise RuntimeError(f"Preflight refused the simulation before upload: {cost_line}")
 
     # 6. Create or reuse project/version
     auto_create = not project_id or not version_id
@@ -422,6 +430,7 @@ def execute_via_api(
         em_data, sources_info, wavelength, ps,
         threshold, max_iterations, boundary_width, is_vectorial,
         strict_validation=strict_validation,
+        sampling_warnings=sampling_warnings,
         gpu_memory_max_gb=gpu_memory_max_gb,
         periodic=periodic,
         pseudo_propagation_distance=pseudo_propagation_distance,

{wavesimpro-1.16.0 → wavesimpro-1.17.0}/src/wavesimpro/json_helper.py

@@ -1160,16 +1160,34 @@ def create_monitor(
     Create a monitor: a positioned 3D subcube (region of interest) of the field.
 
     The monitor result is written in the same binary format as output.bin
-    (complex64, all polarization components), so it is read with read_monitor_binary
-    / read_binary_field. Matches RayfosCommandModels.WavesimMonitor — there is a single
-    monitor type; there is no per-component recording, plane, frequency or decimation
-    (large monitors are decimated at fetch time, like output.bin).
+    (complex64, all polarization components) at FULL resolution — nothing is
+    downsampled on the way to you — so it is read with read_monitor_binary /
+    read_binary_field. Matches RayfosCommandModels.WavesimMonitor.
 
     Two positioning modes:
       - CenterAndSize (default): ``center_*`` is the cuboid centre, ``size_*`` its
         Width/Height/Depth (X/Y/Z extents).
       - MinMaxBounds: pass ``min_bounds`` and ``max_bounds`` as (x, y, z) corners; the
-        center/size arguments are then ignored.
+        center/size arguments are then ignored (Position/Size are filled in from the
+        corners so every reader, Studio included, sees the same box).
+
+    Coordinates are relative to the coordinate-system centre of the setup (0 unless
+    you moved it); the domain itself is centred there.
+
+    Which voxels a monitor selects (the same rule on every axis): 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 (its centre is at -S/2 + (i+0.5)*v, for even and odd N alike). The
+    monitor takes the OUTER COVER of its box: every voxel the box 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, and a
+    zero-thickness box selects the one voxel containing the plane. So a box of
+    exactly k voxels aligned to the grid returns k planes, while the same box
+    centred on a voxel centre straddles k+1. The realised region is never smaller
+    than what you asked for (unless clamped by the domain). The compute node writes
+    the exact result per monitor to ``monitors.json`` next to the monitor files:
+    inclusive voxel index ranges, the shape, the voxel size and the realised
+    physical box (``Run.monitor_regions()`` reads it). Work in multiples of the
+    voxel size, aligned to voxel faces, when you need an exact plane count.
 
     Args:
         name: Monitor name.
@@ -1186,6 +1204,11 @@ def create_monitor(
         return {"X": _len(t[0]), "Y": _len(t[1]), "Z": _len(t[2])}
 
     use_bounds = min_bounds is not None and max_bounds is not None
+    if use_bounds:
+        lo = [min(float(a), float(b)) for a, b in zip(min_bounds, max_bounds)]
+        hi = [max(float(a), float(b)) for a, b in zip(min_bounds, max_bounds)]
+        center_x, center_y, center_z = [(l + h) / 2 for l, h in zip(lo, hi)]
+        size_x, size_y, size_z = [h - l for l, h in zip(lo, hi)]
     return {
         "Id": str(uuid.uuid4()),
         "Name": name,
@@ -1205,7 +1228,6 @@ def create_monitor(
         "MaxBounds": _xyz(max_bounds) if use_bounds else None,
     }
 
-
 def create_wavesim_properties(
     simulation_domain: Dict[str, Any],
     primitives: List[Dict[str, Any]],

{wavesimpro-1.16.0 → wavesimpro-1.17.0}/src/wavesimpro/runs.py

@@ -34,7 +34,7 @@ from .binary_utils import (
     upload_array_as_binary_zipped,
     upload_source_field_as_binary_zipped,
 )
-from .client import RayfosClient, command_status_name, is_terminal_command_status
+from .client import RayfosClient, command_status_name, is_terminal_command_status, preflight_cost_summary
 from .json_helper import (
     create_custom_field_source,
     create_simulation_domain,
@@ -536,8 +536,9 @@ class Setup:
             subpixel_factor=self.subpixel_factor if any_smooth else None,
         )
 
-    def validate(self, strict: bool = False) -> List[str]:
-        """Client-side parameter validation (the server preflight decides memory)."""
+    def validate(self, strict: bool = False, sampling_warnings: bool = True) -> List[str]:
+        """Client-side parameter validation (the server preflight decides memory).
+        ``sampling_warnings=False`` silences the pixels-per-wavelength advisory."""
         dx, dy, dz = self.pixel_sizes
         sources_info = []
         for s in self.field_sources:
@@ -551,7 +552,7 @@ class Setup:
             domain.array if domain is not None else None,
             sources_info, self.wavelength, self.pixel_sizes,
             self.threshold, self.max_iterations, self.boundary_width, self.is_vectorial,
-            strict_validation=strict, periodic=self.periodic,
+            strict_validation=strict, sampling_warnings=sampling_warnings, periodic=self.periodic,
             pseudo_propagation_distance=self.pseudo_propagation_distance,
             data_type=domain.data_type if domain is not None else "Permittivity",
             grid_shape=self.grid, n_max=self.n_max(),
@@ -574,6 +575,7 @@ def submit(
     version_id: Optional[str] = None,
     machine_service_url: Optional[str] = None,
     strict_validation: bool = False,
+    sampling_warnings: bool = True,
     description: Optional[str] = None,
     client: Optional[RayfosClient] = None,
 ) -> "Run":
@@ -588,6 +590,8 @@ def submit(
         project_id, version_id: reuse an existing project/version instead of creating one.
         machine_service_url: talk to a machine service directly (local mode).
         strict_validation: soft validation issues raise instead of warning.
+        sampling_warnings: False silences the "pixels per wavelength" advisory when the
+            sampling is deliberate (Nyquist warnings stay).
         description: project name / job label (default: ``setup.name`` or the calling script).
         client: a ready ``RayfosClient`` (tests / custom sessions); api_key/api_url are then unused.
     """
@@ -617,7 +621,7 @@ def submit(
                 f"Monitors: {len(setup.monitors)}")
 
     # 1. Client-side validation and overlap check (nothing uploaded yet).
-    setup.validate(strict=strict_validation)
+    setup.validate(strict=strict_validation, sampling_warnings=sampling_warnings)
     setup.check_overlaps()
     props_preview = setup.to_properties()  # raises early on an inconsistent setup
 
@@ -627,7 +631,7 @@ def submit(
     try:
         pre = client.preflight_check(domain_um=setup.domain_um, voxel_um=ps, boundary_sides_um=sides,
                                      periodic=setup.periodic, engine_preference=engine, use_gpu=use_gpu,
-                                     is_vectorial=vectorial)
+                                     is_vectorial=vectorial, max_iterations=setup.max_iterations)
     except Exception as exc:  # the preflight is advisory when the endpoint is unreachable
         logger.warning(f"Preflight check failed ({exc}). Proceeding without it.")
         pre = None
@@ -641,6 +645,12 @@ def submit(
         (logger.warning if status == "warning" else logger.info)(f"Preflight: {text}")
         for s in suggestions:
             logger.info(f"  Suggestion: {s}")
+        cost_line = preflight_cost_summary(pre)
+        if cost_line:
+            logger.info(f"Preflight: {cost_line}")
+            cost = pre.get("cost") or {}
+            if cost.get("allowed") is False and cost.get("enforced", True):
+                raise RuntimeError(f"Preflight refused the simulation before upload: {cost_line}")
 
     # 3. Project / version.
     if not project_id or not version_id:
@@ -905,6 +915,23 @@ class Run:
             data = gzip.decompress(data)
         return json.loads(data.decode("utf-8-sig"))
 
+    def monitor_regions(self) -> Dict[str, Dict[str, Any]]:
+        """What each monitor file actually contains, from the ``monitors.json`` the compute node
+        writes next to the ``monitor_<name>.bin`` files: ``{name: {"File", "IndexMin", "IndexMax"
+        (inclusive voxel indices, x/y/z), "Shape", "VoxelSizeUm", "DomainShape", "RequestedMinUm",
+        "RequestedMaxUm", "RealisedMinUm", "RealisedMaxUm"}}``. The realised box is the outer cover
+        of the requested one (see ``create_monitor``), in the monitor's own coordinates. Raises
+        ``FileNotFoundError`` for runs from nodes older than 1.17 (no monitors.json)."""
+        f = self.find_file("monitors.json")
+        if f is None:
+            raise FileNotFoundError("the run has no monitors.json: no monitor, or the compute node predates 1.17")
+        data = self.client.download_file_data(self.project_id, self.version_id, f["id"], command_id=self.command_id)
+        if data[:2] == b"\x1f\x8b":
+            import gzip
+            data = gzip.decompress(data)
+        doc = json.loads(data.decode("utf-8-sig"))
+        return {m.get("Name", ""): m for m in doc.get("Monitors", [])}
+
     def download(self, name: str, dest: Optional[Union[str, Path]] = None) -> Path:
         """Download one output file by name (e.g. ``"output.bin"``, ``"wavesim.json"``,
         ``"permittivityDomain1.bin"``). ``dest`` is a directory or a file path; default:
@@ -952,7 +979,8 @@ class Run:
         return self._read_file("output.bin", dims)
 
     def get_monitors(self) -> List[np.ndarray]:
-        """The monitor fields, in the order the monitors were added (disabled ones skipped)."""
+        """The monitor fields, in the order the monitors were added (disabled ones skipped), at
+        full resolution. ``monitor_regions()`` tells which voxels each one holds."""
         self._ensure_done()
         by_name = {f["name"].lower(): f for f in self.list_files()}
         ordered = [(m.get("Name", ""), monitor_output_filename(m.get("Name", "")))

{wavesimpro-1.16.0 → wavesimpro-1.17.0}/src/wavesimpro/simulate.py

@@ -42,6 +42,7 @@ _defaults = {
     "engine_preference": "Any",
     "use_gpu": None,
     "strict_validation": False,
+    "sampling_warnings": True,
     "gpu_memory_max_gb": None,
 }
 
@@ -55,6 +56,7 @@ def configure(
     engine_preference: Optional[str] = None,
     use_gpu: Optional[bool] = None,
     strict_validation=_UNSET,
+    sampling_warnings: Optional[bool] = None,
     gpu_memory_max_gb=_UNSET,
 ):
     """Set module-level defaults for remote execution.
@@ -72,6 +74,9 @@ def configure(
         strict_validation: When True, soft validation issues (currently: a
             source field larger than the domain) raise instead of warning.
             Default False — simulations are not stopped by these.
+        sampling_warnings: False silences the advisory "Only N pixels per
+            wavelength ... recommend >= 10" when your sampling is deliberate.
+            Nyquist-limit warnings are kept. Default True.
         gpu_memory_max_gb: DEPRECATED and ignored (1.6.2). Memory fit is
             decided by the server preflight (/api/preflightCheck), which knows
             the engine's real allocation model and the registered machines'
@@ -92,6 +97,8 @@ def configure(
         _defaults["use_gpu"] = use_gpu
     if strict_validation is not _UNSET:
         _defaults["strict_validation"] = bool(strict_validation)
+    if sampling_warnings is not None:
+        _defaults["sampling_warnings"] = bool(sampling_warnings)
     if gpu_memory_max_gb is not _UNSET:
         _defaults["gpu_memory_max_gb"] = gpu_memory_max_gb
 
@@ -115,6 +122,7 @@ def simulate(
     crop_boundaries: bool = True,  # local only — accepted and ignored
     callback: Optional[Callable] = None,
     strict_validation: Optional[bool] = None,
+    sampling_warnings: Optional[bool] = None,  # False silences the pixels-per-wavelength advisory
     gpu_memory_max_gb=_UNSET,
     monitors=None,   # list of dicts from create_monitor(); each captures a 3D ROI of the field
     pseudo_propagation_distance: float = 0.0,  # μm; 0 = off. Overrides max_iterations. C++ engine only.
@@ -178,6 +186,9 @@ def simulate(
     effective_strict = (
         _defaults["strict_validation"] if strict_validation is None else bool(strict_validation)
     )
+    effective_sampling = (
+        _defaults["sampling_warnings"] if sampling_warnings is None else bool(sampling_warnings)
+    )
     effective_gpu_max = (
         _defaults["gpu_memory_max_gb"] if gpu_memory_max_gb is _UNSET else gpu_memory_max_gb
     )
@@ -239,6 +250,7 @@ def simulate(
         keep_residuals_list=full_residuals,
         progress_callback=_progress_cb,
         strict_validation=effective_strict,
+        sampling_warnings=effective_sampling,
         gpu_memory_max_gb=effective_gpu_max,
         monitors=monitors,
         pseudo_propagation_distance=pseudo_propagation_distance,
@@ -278,6 +290,7 @@ def simulate_pro(
     description: Optional[str] = None,
     server: Optional[str] = None,
     strict_validation: Optional[bool] = None,
+    sampling_warnings: Optional[bool] = None,  # False silences the pixels-per-wavelength advisory
     gpu_memory_max_gb=_UNSET,
     monitors=None,   # list of dicts from create_monitor(); each captures a 3D ROI of the field
     pseudo_propagation_distance: float = 0.0,  # μm; 0 = off. Overrides max_iterations. C++ engine only.
@@ -329,6 +342,9 @@ def simulate_pro(
     effective_strict = (
         _defaults["strict_validation"] if strict_validation is None else bool(strict_validation)
     )
+    effective_sampling = (
+        _defaults["sampling_warnings"] if sampling_warnings is None else bool(sampling_warnings)
+    )
     effective_gpu_max = (
         _defaults["gpu_memory_max_gb"] if gpu_memory_max_gb is _UNSET else gpu_memory_max_gb
     )
@@ -391,6 +407,7 @@ def simulate_pro(
         keep_residuals_list=full_residuals,
         progress_callback=_progress_cb,
         strict_validation=effective_strict,
+        sampling_warnings=effective_sampling,
         gpu_memory_max_gb=effective_gpu_max,
         monitors=monitors,
         pseudo_propagation_distance=pseudo_propagation_distance,

{wavesimpro-1.16.0 → wavesimpro-1.17.0}/src/wavesimpro/validate.py

@@ -53,6 +53,7 @@ def validate_parameters(
     periodic: Optional[tuple] = None,
     pseudo_propagation_distance: float = 0.0,
     data_type: str = "RefractiveIndex",
+    sampling_warnings: bool = True,   # False silences the "pixels per wavelength" advisory; Nyquist warnings stay
 ) -> List[str]:
     """
     Validate simulation parameters before upload.
@@ -213,7 +214,7 @@ def validate_parameters(
                 if not anisotropic:
                     break
             pixels_per_wavelength = wavelength / (n_max * max(pixel_sizes))
-            if pixels_per_wavelength < 10:
+            if pixels_per_wavelength < 10 and sampling_warnings:
                 warnings.append(
                     f"Only {pixels_per_wavelength:.1f} pixels per wavelength in the "
                     f"highest-index medium (n_max={n_max:.2f}) on the coarsest axis. Recommend >= 10 "

{wavesimpro-1.16.0 → wavesimpro-1.17.0}/src/wavesimpro.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: wavesimpro
-Version: 1.16.0
+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
@@ -75,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.