wavesimpro 1.6.5__tar.gz → 1.10.0__tar.gz

wavesimpro-1.10.0/PKG-INFO

@@ -0,0 +1,76 @@
+Metadata-Version: 2.4
+Name: wavesimpro
+Version: 1.10.0
+Summary: WavesimPro Python API — cloud execution client for the Rayfos simulation platform
+Author: Rayfos
+Project-URL: Repository, https://github.com/rayfos/wavesimpro
+Keywords: wavesim,simulation,electromagnetic,rayfos,api
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Scientific/Engineering
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+Requires-Dist: numpy>=1.20.0
+Requires-Dist: requests>=2.28.0
+Requires-Dist: python-dotenv>=1.0.0
+Requires-Dist: tqdm>=4.60.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0.0; extra == "dev"
+Requires-Dist: black>=23.0.0; extra == "dev"
+Requires-Dist: mypy>=1.0.0; extra == "dev"
+
+# 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")],
+    sources=[wp.create_mode_source("in", 0, 0, -8.0, polarization="X")],
+    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.
+- 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.
+
+See `CHANGELOG.md` for what each version added. Issues and feature requests: support@rayfos.com.

wavesimpro-1.10.0/README.md

@@ -0,0 +1,53 @@
+# 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")],
+    sources=[wp.create_mode_source("in", 0, 0, -8.0, polarization="X")],
+    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.
+- 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.
+
+See `CHANGELOG.md` for what each version added. Issues and feature requests: support@rayfos.com.

{wavesimpro-1.6.5 → wavesimpro-1.10.0}/pyproject.toml

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

{wavesimpro-1.6.5 → wavesimpro-1.10.0}/src/wavesimpro/__init__.py

@@ -33,10 +33,19 @@ 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,
     create_gaussian_beam_source,
+    create_mode_source,
     create_voxels_model_primitive,
     create_custom_field_source,
     create_custom_from_file_source,
@@ -45,7 +54,7 @@ from .json_helper import (
     parse_progress_data,
 )
 
-__version__ = "1.6.5"
+__version__ = "1.10.0"
 __all__ = [
     # Client
     "RayfosClient",
@@ -77,10 +86,19 @@ __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",
     "create_gaussian_beam_source",
+    "create_mode_source",
     "create_voxels_model_primitive",
     "create_custom_field_source",
     "create_custom_from_file_source",

{wavesimpro-1.6.5 → wavesimpro-1.10.0}/src/wavesimpro/client.py

@@ -280,7 +280,7 @@ class RayfosClient:
     def preflight_check(
         self,
         domain_um: tuple,
-        voxel_um: float,
+        voxel_um,   # float, or (dx, dy, dz) µm for a per-axis grid
         boundary_sides_um: Sequence[Tuple[float, float]],
         periodic: tuple = (False, False, False),
         engine_preference: str = "Any",
@@ -329,6 +329,12 @@ class RayfosClient:
         def _um(v: float) -> Dict[str, Any]:
             return {"value": float(v), "unit": "Micrometers"}
 
+        voxels = (tuple(float(v) for v in voxel_um)
+                  if isinstance(voxel_um, (list, tuple)) else (float(voxel_um),) * 3)
+        if len(voxels) != 3:
+            raise ValueError("voxel_um must be one number or (dx, dy, dz)")
+        anisotropic = any(abs(v - voxels[0]) > 1e-6 * max(voxels) for v in voxels)
+
         body = {
             "wavesimProperties": {
                 "simulationDomain": {
@@ -336,7 +342,11 @@ class RayfosClient:
                     "position": {"x": _um(0.0), "y": _um(0.0), "z": _um(0.0)},
                     "size": {"width": _um(size_x), "height": _um(size_y), "depth": _um(size_z)},
                 },
-                "voxelSize": _um(voxel_um),
+                # voxelSize = the smallest axis (what scalar readers use); voxelSizes carries
+                # the per-axis pitch so the estimator sizes the grid the engine will pad.
+                "voxelSize": _um(min(voxels)),
+                **({"voxelSizes": {"x": _um(voxels[0]), "y": _um(voxels[1]), "z": _um(voxels[2])}}
+                   if anisotropic else {}),
                 # boundarySize is the symmetric fallback older servers read; the
                 # per-side widths below are what the current estimator uses.
                 "boundarySize": _um(sides[0][0]),

{wavesimpro-1.6.5 → wavesimpro-1.10.0}/src/wavesimpro/execute.py

@@ -92,11 +92,37 @@ def _normalize_boundary_widths(boundary_widths) -> Optional[List[Tuple[float, fl
     return out
 
 
+def pixel_sizes_um(pixel_size) -> Tuple[float, float, float]:
+    """
+    Normalise a pixel size to a per-axis (dx, dy, dz) tuple in micrometres.
+
+    ``pixel_size`` may be one number (isotropic, the usual case) or three
+    ``[dx, dy, dz]`` (anisotropic: coarsen axes the field is band-limited along,
+    e.g. the transverse axes of a paraxial beam or a weakly guiding waveguide;
+    Python engine only). Every axis must be positive.
+    """
+    if isinstance(pixel_size, (int, float, np.integer, np.floating)):
+        p = float(pixel_size)
+        return (p, p, p)
+    vals = tuple(float(v) for v in pixel_size)
+    if len(vals) != 3:
+        raise ValueError(f"pixel_size must be one number or [dx, dy, dz], got {pixel_size!r}")
+    if any(v <= 0 for v in vals):
+        raise ValueError(f"pixel_size components must be positive, got {vals}")
+    return vals  # type: ignore[return-value]
+
+
+def is_anisotropic(pixel_sizes: Sequence[float]) -> bool:
+    """True when the three pitches differ beyond float round-off."""
+    m = max(pixel_sizes)
+    return any(abs(v - pixel_sizes[0]) > 1e-6 * m for v in pixel_sizes)
+
+
 def execute_via_api(
     refractive_index: np.ndarray,
     source,
     wavelength: float,
-    pixel_size: float,
+    pixel_size,   # float, or [dx, dy, dz] µm (see pixel_sizes_um)
     threshold: float = 1e-2,
     max_iterations: int = 1000,
     boundary_width: Optional[float] = None,  # in MICROMETERS; REQUIRED unless boundary_widths is given
@@ -134,7 +160,9 @@ def execute_via_api(
             - dict with 'Es' (complex field array) and 'position' ([x,y,z] or [x,y,z,pol])
             - list of such dicts for multiple sources
         wavelength: Wavelength in micrometers
-        pixel_size: Pixel size in micrometers
+        pixel_size: Pixel size in micrometers — one number, or [dx, dy, dz] for a
+            per-axis grid (coarsen axes the field is band-limited along; Python
+            engine only, see pixel_sizes_um)
         threshold: Convergence threshold (default: 1e-2)
         max_iterations: Max iterations (default: 1000)
         boundary_width: Absorbing boundary width in MICROMETERS (μm). Required —
@@ -248,13 +276,17 @@ def execute_via_api(
 
     logger.info(f"  Domain: [{nx}, {ny}, {nz}]")
     logger.info(f"  Wavelength: {wavelength:.3f} um")
-    logger.info(f"  Pixel size: {pixel_size:.3f} um")
+    ps = pixel_sizes_um(pixel_size)
+    anisotropic = is_anisotropic(ps)
+    ps_min = min(ps)
+    ps_label = f"({ps[0]:.4g}, {ps[1]:.4g}, {ps[2]:.4g})" if anisotropic else f"{ps[0]:.3f}"
+    logger.info(f"  Pixel size: {ps_label} um")
     logger.info(f"  Threshold: {threshold:.2e}")
     logger.info(f"  Max iterations: {max_iterations}")
     if pseudo_propagation_distance > 0:
         logger.info(f"  Pseudo propagation distance: {pseudo_propagation_distance} um (overrides max iterations)")
     if boundary_sides_um is None:
-        logger.info(f"  Boundary width: {boundary_width} um ({int(round(boundary_width / pixel_size))} pixels)")
+        logger.info(f"  Boundary width: {boundary_width} um ({int(round(boundary_width / ps_min))} pixels on the finest axis)")
     else:
         logger.info("  Boundary widths (um): " + "  ".join(
             f"{ax}:[{left:g}, {right:g}]" for ax, (left, right) in zip("XYZ", boundary_sides_um)))
@@ -318,9 +350,9 @@ def execute_via_api(
 
     # 5b. Preflight check — abort BEFORE creating a project / uploading anything
     #     if the simulation won't fit on the available compute targets.
-    domain_x_um = float(nx) * float(pixel_size)
-    domain_y_um = float(ny) * float(pixel_size)
-    domain_z_um = float(nz) * float(pixel_size)
+    domain_x_um = float(nx) * ps[0]
+    domain_y_um = float(ny) * ps[1]
+    domain_z_um = float(nz) * ps[2]
     #     The preflight describes exactly the grid the engine will pad: the same
     #     per-side boundary widths that go into the submitted properties.
     preflight_sides_um = (boundary_sides_um if boundary_sides_um is not None
@@ -328,7 +360,7 @@ def execute_via_api(
     try:
         pre = client.preflight_check(
             domain_um=(domain_x_um, domain_y_um, domain_z_um),
-            voxel_um=float(pixel_size),
+            voxel_um=ps,
             boundary_sides_um=preflight_sides_um,
             periodic=(bool(periodic[0]), bool(periodic[1]), bool(periodic[2])),
             engine_preference=engine_preference,
@@ -379,7 +411,7 @@ def execute_via_api(
 
     # 7. Validate parameters
     validate_parameters(
-        em_data, sources_info, wavelength, pixel_size,
+        em_data, sources_info, wavelength, ps,
         threshold, max_iterations, boundary_width, is_vectorial,
         strict_validation=strict_validation,
         gpu_memory_max_gb=gpu_memory_max_gb,
@@ -424,9 +456,9 @@ def execute_via_api(
 
     # 10. Build WavesimProperties payload
     logger.info("Building command payload...")
-    domain_x_um = float(nx) * float(pixel_size)
-    domain_y_um = float(ny) * float(pixel_size)
-    domain_z_um = float(nz) * float(pixel_size)
+    domain_x_um = float(nx) * ps[0]
+    domain_y_um = float(ny) * ps[1]
+    domain_z_um = float(nz) * ps[2]
 
     simulation_domain = create_simulation_domain(domain_x_um, domain_y_um, domain_z_um)
     background_medium = create_medium("background", "Background", background_ri)
@@ -435,7 +467,7 @@ def execute_via_api(
     voxel_primitive = create_voxels_model_primitive(
         primitive_name, em_data_id, "background",
         0.0, 0.0, 0.0,
-        float(pixel_size), float(pixel_size), float(pixel_size),
+        ps[0], ps[1], ps[2],
         int(nx), int(ny), int(nz),
         "Complex64", data_type,
     )
@@ -459,9 +491,9 @@ def execute_via_api(
         # centre, world 0,0,0).  Keeping every client emitting the same shape
         # of WavesimProperties means the server has one coordinate path, not
         # one per client.
-        src_extent_x = float(src_nx) * float(pixel_size)
-        src_extent_y = float(src_ny) * float(pixel_size)
-        src_extent_z = float(src_nz) * float(pixel_size)
+        src_extent_x = float(src_nx) * ps[0]
+        src_extent_y = float(src_ny) * ps[1]
+        src_extent_z = float(src_nz) * ps[2]
         position_x_centered = float(src["position"][0]) + src_extent_x / 2.0 - domain_x_um / 2.0
         position_y_centered = float(src["position"][1]) + src_extent_y / 2.0 - domain_y_um / 2.0
         position_z_centered = float(src["position"][2]) + src_extent_z / 2.0 - domain_z_um / 2.0
@@ -493,7 +525,8 @@ def execute_via_api(
         monitors=monitors or [],
         background_medium_id="background",
         wavelength=float(wavelength),
-        voxel_size=float(pixel_size),
+        voxel_size=ps_min,                                  # smallest axis: scalar readers over-resolve
+        voxel_sizes=list(ps) if anisotropic else None,      # per-axis pitch, Python engine only
         boundary_size_um=boundary_size_um,
         boundary_sides_um=boundary_sides_um,
         boundary_strength=boundary_strength,
@@ -534,7 +567,7 @@ def execute_via_api(
     print(f"  Version   : {version_id}")
     print(f"  Command   : {command_id}")
     print(f"  Mode      : {_mode}")
-    print(f"  Domain    : {_domain_str}  lambda={wavelength} um  dx={pixel_size} um")
+    print(f"  Domain    : {_domain_str}  lambda={wavelength} um  dx={ps_label} um")
     print(f"  Engine    : {_engine}  |  GPU: {_gpu}")
     if preferred_machine_id:
         print(f"  Machine   : {preferred_machine_id}")