wavesimpro 0.9.0__py3-none-any.whl

wavesimpro/config.py

@@ -0,0 +1,123 @@
+"""
+Configuration module for WavesimPythonAPI
+"""
+
+import os
+from typing import Optional
+from dataclasses import dataclass
+
+
+@dataclass
+class ClientConfig:
+    """
+    Configuration for the Rayfos API client
+    
+    Attributes:
+        api_token: User API token for authentication
+        server_url: Base URL of RayfosJobServer for project management (default: server.rayfos.com)
+        machine_service_url: Optional URL of RayfosMachineService for file uploads
+        timeout: Request timeout in seconds
+        verify_ssl: Whether to verify SSL certificates for server_url
+        verify_ssl_machine_service: Whether to verify SSL certificates for machine_service_url
+    """
+    
+    api_token: str
+    server_url: str = "https://server.rayfos.com"
+    machine_service_url: Optional[str] = None
+    timeout: int = 30
+    verify_ssl: bool = True
+    verify_ssl_machine_service: bool = True
+    
+    def __post_init__(self):
+        """Validate configuration after initialization"""
+        # Remove trailing slashes from URLs
+        if self.server_url:
+            self.server_url = self.server_url.rstrip('/')
+        if self.machine_service_url:
+            self.machine_service_url = self.machine_service_url.rstrip('/')
+            
+            # Auto-detect SSL verification for localhost machine service
+            if not hasattr(self, '_verify_ssl_ms_set'):
+                if "localhost" in self.machine_service_url or "127.0.0.1" in self.machine_service_url:
+                    self.verify_ssl_machine_service = False
+    
+    @classmethod
+    def from_env(cls) -> "ClientConfig":
+        """
+        Create configuration from environment variables
+        
+        Environment variables:
+            RAYFOS_API_TOKEN: API token (required)
+            RAYFOS_SERVER_URL: Project server URL (optional, defaults to server.rayfos.com)
+            RAYFOS_MACHINE_SERVICE_URL: Machine service URL for file uploads (optional)
+        
+        Returns:
+            ClientConfig instance
+        
+        Raises:
+            ValueError: If required environment variables are missing
+        """
+        api_token = os.getenv("RAYFOS_API_TOKEN")
+        if not api_token:
+            raise ValueError("RAYFOS_API_TOKEN environment variable is required")
+        
+        # Get server URL (defaults to cloud server)
+        server_url = os.getenv("RAYFOS_SERVER_URL", "https://server.rayfos.com")
+        
+        # Get optional machine service URL for file uploads
+        machine_service_url = os.getenv("RAYFOS_MACHINE_SERVICE_URL")
+        
+        # SSL verification for main server (always True for production servers)
+        verify_ssl = True
+        if "localhost" in server_url or "127.0.0.1" in server_url:
+            verify_ssl = False
+        
+        # SSL verification for machine service (auto-detect localhost)
+        verify_ssl_machine_service = True
+        if machine_service_url and ("localhost" in machine_service_url or "127.0.0.1" in machine_service_url):
+            verify_ssl_machine_service = False
+        
+        return cls(
+            api_token=api_token,
+            server_url=server_url,
+            machine_service_url=machine_service_url,
+            timeout=30,
+            verify_ssl=verify_ssl,
+            verify_ssl_machine_service=verify_ssl_machine_service,
+        )
+    
+    def get_api_url(self, endpoint: str) -> str:
+        """
+        Get the full URL for an API endpoint
+        
+        Args:
+            endpoint: API endpoint path (e.g., '/api/projects')
+        
+        Returns:
+            Full URL
+        """
+        if not endpoint.startswith('/'):
+            endpoint = f'/{endpoint}'
+        return f"{self.server_url}{endpoint}"
+    
+    def get_machine_service_url(self, endpoint: str) -> str:
+        """
+        Get the full URL for a machine service endpoint
+        
+        Args:
+            endpoint: Machine service endpoint path
+        
+        Returns:
+            Full URL
+        
+        Raises:
+            ValueError: If machine_service_url is not configured
+        """
+        if not self.machine_service_url:
+            raise ValueError("Machine service URL is not configured")
+        
+        if not endpoint.startswith('/'):
+            endpoint = f'/{endpoint}'
+        return f"{self.machine_service_url}{endpoint}"
+
+

wavesimpro/exceptions.py

@@ -0,0 +1,40 @@
+"""
+Exception classes for WavesimPythonAPI
+"""
+
+
+class RayfosAPIError(Exception):
+    """Base exception for all Rayfos API errors"""
+    
+    def __init__(self, message: str, status_code: int = None, response=None):
+        self.message = message
+        self.status_code = status_code
+        self.response = response
+        super().__init__(self.message)
+
+
+class AuthenticationError(RayfosAPIError):
+    """Raised when authentication fails"""
+    pass
+
+
+class NotFoundError(RayfosAPIError):
+    """Raised when a resource is not found (404)"""
+    pass
+
+
+class ValidationError(RayfosAPIError):
+    """Raised when input validation fails (400)"""
+    pass
+
+
+class ServerError(RayfosAPIError):
+    """Raised when the server encounters an error (5xx)"""
+    pass
+
+
+class ConfigurationError(RayfosAPIError):
+    """Raised when configuration is invalid"""
+    pass
+
+

wavesimpro/execute.py

@@ -0,0 +1,461 @@
+"""
+High-level single-call execution function for Wavesim simulations.
+
+Ported from MATLAB executeViaRayfosAPI.m. Provides a single function that
+handles the full workflow: credential loading, project creation, file upload,
+command submission, polling, result download.
+"""
+
+import os
+import json
+import math
+import time
+import logging
+from typing import Tuple, Optional, Callable, Dict, Any, List
+
+import numpy as np
+
+from .client import RayfosClient
+from .binary_utils import (
+    upload_array_as_binary_zipped,
+    upload_source_field_as_binary_zipped,
+    read_binary_field,
+)
+from .json_helper import (
+    create_simulation_domain,
+    create_medium,
+    create_voxels_model_primitive,
+    create_custom_field_source,
+    create_wavesim_properties,
+    parse_progress_data,
+)
+from .validate import validate_parameters
+
+logger = logging.getLogger(__name__)
+
+
+def _extract_file_id(file_info: dict) -> str:
+    """Extract file ID from upload response (handles different field names)."""
+    for key in ("fileId", "id", "blobName"):
+        if key in file_info:
+            return file_info[key]
+    raise KeyError(f"No file ID found in upload response. Keys: {list(file_info.keys())}")
+
+
+def execute_via_api(
+    refractive_index: np.ndarray,
+    source,
+    wavelength: float,
+    pixel_size: float,
+    threshold: float = 1e-2,
+    max_iterations: int = 1000,
+    boundary_width: int = 0,
+    is_vectorial: bool = True,
+    data_type: str = "RefractiveIndex",
+    api_url: Optional[str] = None,
+    api_key: Optional[str] = None,
+    periodic: tuple = (False, False, False),
+    project_id: Optional[str] = None,
+    version_id: Optional[str] = None,
+    machine_service_url: Optional[str] = None,
+    description: str = "Wavesim Python API",
+    poll_interval: float = 10.0,
+    progress_callback: Optional[Callable[[Dict[str, Any]], None]] = None,
+    engine_preference: str = "Any",
+    use_gpu: Optional[bool] = None,
+) -> Tuple[np.ndarray, bool]:
+    """
+    Execute a Wavesim simulation via the Rayfos REST API.
+
+    Single-call function that handles the full simulation workflow.
+
+    Args:
+        refractive_index: [nx, ny, nz] array (refractive index or permittivity)
+        source: Source specification. Can be:
+            - 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
+        threshold: Convergence threshold (default: 1e-2)
+        max_iterations: Max iterations (default: 1000)
+        boundary_width: Boundary width in pixels (default: 0)
+        is_vectorial: True for Maxwell, False for Helmholtz (default: True)
+        data_type: 'RefractiveIndex' or 'Permittivity' (default: 'RefractiveIndex')
+        api_url: API base URL (default: from RAYFOS_API_URL env var)
+        api_key: API key (default: from RAYFOS_API_KEY env var)
+        project_id: Existing project ID (default: auto-create)
+        version_id: Existing version ID (default: auto-create)
+        machine_service_url: Machine service URL (default: from RAYFOS_MACHINE_SERVICE_URL env var)
+        description: Command description
+        poll_interval: Polling interval in seconds (default: 10.0)
+        progress_callback: Optional callback(progress_dict) called during polling
+        engine_preference: Engine to use — 'Any' (default), 'Python', or 'Cpp'.
+            'Any' lets the job server pick the best available machine.
+            Ignored when machine_service_url is set (local mode always uses that machine).
+        use_gpu: GPU selection — None (auto, default), True (require GPU), False (force CPU).
+            Ignored when machine_service_url is set.
+
+    Returns:
+        Tuple of (E_field, converged):
+            - E_field: Complex output field array. Vectorial: [3, nx, ny, nz], Scalar: [nx, ny, nz]
+            - converged: True if simulation completed successfully
+    """
+    # 1. Load credentials
+    api_url = api_url or os.environ.get("RAYFOS_API_URL", "http://localhost:5159")
+    api_key = api_key or os.environ.get("RAYFOS_API_KEY")
+    if not api_key:
+        raise ValueError("API key must be provided or set in RAYFOS_API_KEY environment variable")
+
+    project_id = project_id or os.environ.get("RAYFOS_PROJECT_ID")
+    version_id = version_id or os.environ.get("RAYFOS_VERSION_ID")
+    machine_service_url = machine_service_url or os.environ.get("RAYFOS_MACHINE_SERVICE_URL")
+
+    # Auto-detect SSL
+    verify_ssl = not ("localhost" in api_url.lower() or "127.0.0.1" in api_url)
+    verify_ssl_machine = True
+    if machine_service_url:
+        verify_ssl_machine = not ("localhost" in machine_service_url.lower() or "127.0.0.1" in machine_service_url)
+
+    logger.info("=" * 60)
+    logger.info("Wavesim Python API - Rayfos REST Execution")
+    logger.info("=" * 60)
+    logger.info(f"  Mode: {'Vectorial (Maxwell)' if is_vectorial else 'Scalar (Helmholtz)'}")
+    logger.info(f"  API URL: {api_url}")
+    logger.info(f"  Engine: {engine_preference}  GPU: {'auto' if use_gpu is None else ('GPU' if use_gpu else 'CPU')}")
+
+    # 2. Extract domain info
+    nx, ny, nz = refractive_index.shape[:3]
+
+    logger.info(f"  Domain: [{nx}, {ny}, {nz}]")
+    logger.info(f"  Wavelength: {wavelength:.3f} um")
+    logger.info(f"  Pixel size: {pixel_size:.3f} um")
+    logger.info(f"  Threshold: {threshold:.2e}")
+    logger.info(f"  Max iterations: {max_iterations}")
+    logger.info(f"  Boundary width: {boundary_width} pixels")
+
+    # 3. Prepare electromagnetic data
+    if data_type == "RefractiveIndex":
+        background_ri = float(np.min(np.real(refractive_index)))
+    else:
+        background_ri = float(np.sqrt(np.min(np.real(refractive_index))))
+    em_data = refractive_index
+
+    # 4. Prepare sources
+    if isinstance(source, dict):
+        source = [source]
+    elif not isinstance(source, list):
+        source = [source]
+
+    sources_info = []
+    for i, src_item in enumerate(source):
+        es = src_item["Es"]
+        position = src_item["position"]
+
+        # Extract polarization
+        if len(position) >= 4:
+            pol_matlab = position[3]
+            if is_vectorial:
+                pol_python = int(pol_matlab) - 1  # MATLAB 1-based -> Python 0-based
+            else:
+                pol_python = -1
+        else:
+            pol_python = 0 if is_vectorial else -1
+
+        src_x_um = float(position[0])
+        src_y_um = float(position[1])
+        src_z_um = float(position[2])
+
+        sources_info.append({
+            "field": es,
+            "position": [src_x_um, src_y_um, src_z_um],
+            "polarization": pol_python,
+        })
+        logger.info(
+            f"  Source {i + 1}: pos=[{src_x_um:.4f}, {src_y_um:.4f}, {src_z_um:.4f}] um, "
+            f"shape={es.shape}, pol={pol_python}"
+        )
+
+    # 5. Create client
+    logger.info("Connecting to Rayfos API...")
+    client = RayfosClient(
+        api_token=api_key,
+        server_url=api_url,
+        machine_service_url=machine_service_url,
+        verify_ssl=verify_ssl,
+        verify_ssl_machine_service=verify_ssl_machine,
+    )
+
+    # 6. Create or reuse project/version
+    auto_create = not project_id or not version_id
+    if auto_create:
+        logger.info("Creating project...")
+        project_result = client.create_project(
+            name=f"{description} - Wavesim Python API",
+            app="wavesim",
+            description=f"Multi-source simulation ({len(sources_info)} source(s))",
+        )
+        project_id = project_result["id"]
+        versions = project_result.get("versions", [])
+        if not versions:
+            raise RuntimeError("No version found in created project")
+        version_result = versions[0]
+        version_id = version_result["id"]
+        properties_id = version_result["propertiesId"]
+        logger.info(f"  Project ID: {project_id}")
+        logger.info(f"  Version ID: {version_id}")
+    else:
+        logger.info(f"Using existing project: {project_id}")
+        version_info = client.get_project_version(project_id, version_id)
+        properties_id = version_info["propertiesId"]
+
+    # 7. Validate parameters
+    validate_parameters(
+        em_data, sources_info, wavelength, pixel_size,
+        threshold, max_iterations, boundary_width, is_vectorial
+    )
+
+    # 8. Upload RI/permittivity
+    logger.info(f"Uploading electromagnetic data ({data_type})...")
+    if np.isrealobj(em_data):
+        binary_data_type = "float32"
+    else:
+        binary_data_type = "complex64"
+
+    filename = "refractive_index.bin" if data_type == "RefractiveIndex" else "permittivity.bin"
+    em_file_info = upload_array_as_binary_zipped(
+        client, project_id, version_id, em_data, filename, binary_data_type
+    )
+    em_data_id = _extract_file_id(em_file_info)
+    logger.info(f"  Uploaded {data_type} (ID: {em_data_id})")
+
+    # 9. Upload sources
+    logger.info("Uploading input sources...")
+    source_ids = []
+    for i, src in enumerate(sources_info):
+        src_filename = f"source{i}.bin"
+        src_file_info = upload_source_field_as_binary_zipped(
+            client, project_id, version_id, src["field"], src_filename, "complex64"
+        )
+        src_id = _extract_file_id(src_file_info)
+        source_ids.append(src_id)
+        logger.info(f"  Source {i + 1} uploaded (ID: {src_id})")
+
+    # 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)
+
+    simulation_domain = create_simulation_domain(domain_x_um, domain_y_um, domain_z_um)
+    background_medium = create_medium("background", "Background", background_ri)
+
+    primitive_name = data_type.lower().replace(" ", "_") + "_map"
+    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),
+        int(nx), int(ny), int(nz),
+        "Complex64", data_type,
+    )
+
+    input_sources = []
+    for i, src in enumerate(sources_info):
+        src_shape = src["field"].shape
+        while len(src_shape) < 3:
+            src_shape = src_shape + (1,)
+        src_nx, src_ny, src_nz = src_shape[0], src_shape[1], src_shape[2]
+
+        pol_num = src["polarization"]
+        pol_map = {0: "x", 1: "y", 2: "z"}
+        pol_str = pol_map.get(pol_num, "none")
+
+        custom_source = create_custom_field_source(
+            name=f"source_{i + 1}",
+            field_data_id=source_ids[i],
+            position_x=src["position"][0],
+            position_y=src["position"][1],
+            position_z=src["position"][2],
+            grid_nx=src_nx,
+            grid_ny=src_ny,
+            grid_nz=src_nz,
+            polarization=pol_str,
+            amplitude_real=1.0,
+            amplitude_imag=0.0,
+            data_format="Complex64",
+            origin="topleft",
+        )
+        input_sources.append(custom_source)
+
+    boundary_size_um = float(boundary_width) * float(pixel_size)
+
+    props = create_wavesim_properties(
+        simulation_domain=simulation_domain,
+        primitives=[voxel_primitive],
+        input_sources=input_sources,
+        mediums=[background_medium],
+        monitors=[],
+        background_medium_id="background",
+        wavelength=float(wavelength),
+        voxel_size=float(pixel_size),
+        boundary_size_um=boundary_size_um,
+        residual_norm_threshold=float(threshold),
+        residual_norm_max_iterations=int(max_iterations),
+        periodic_x=bool(periodic[0]),
+        periodic_y=bool(periodic[1]),
+        periodic_z=bool(periodic[2]),
+    )
+
+    logger.info(f"  Payload created with {len(sources_info)} source(s)")
+
+    # 11. Update properties
+    logger.info("Updating project properties...")
+    client.update_project_properties(properties_id, props)
+
+    # 12. Submit command
+    logger.info("Submitting simulation command...")
+    cmd_status = client.create_command(project_id, version_id, engine_preference, use_gpu)
+    command_id = cmd_status.get("commandId") or cmd_status.get("id")
+    if not command_id:
+        raise RuntimeError("No command ID found in response")
+    logger.info(f"  Command ID: {command_id}")
+
+    # 13. Poll for completion
+    logger.info("Waiting for simulation to complete...")
+    start_time = time.time()
+    consecutive_errors = 0
+    max_consecutive_errors = 3
+    final_status = None
+
+    while True:
+        try:
+            status = client.get_command_status(command_id)
+            consecutive_errors = 0
+        except Exception as e:
+            consecutive_errors += 1
+            if consecutive_errors >= max_consecutive_errors:
+                raise RuntimeError(
+                    f"Failed to get command status after {consecutive_errors} attempts. "
+                    f"Last error: {e}. Command ID: {command_id}"
+                )
+            logger.warning(
+                f"Status check failed (attempt {consecutive_errors}/{max_consecutive_errors}): {e}. "
+                f"Retrying in {poll_interval}s..."
+            )
+            time.sleep(poll_interval)
+            continue
+
+        elapsed = time.time() - start_time
+        status_str = status.get("status", "Unknown")
+
+        # Parse progress if available
+        progress_dto = status.get("progressDto")
+        if progress_dto:
+            progress_info = parse_progress_data(progress_dto)
+            if progress_callback:
+                progress_callback(progress_info)
+
+            residual = progress_info.get("residual_norm")
+            iteration = progress_info.get("iteration")
+            if residual is not None:
+                logger.info(f"  [{elapsed:.0f}s] {status_str} (residual: {residual:.2e}, iter: {iteration})")
+            elif iteration is not None:
+                max_iter = progress_info.get("max_iterations", "?")
+                logger.info(f"  [{elapsed:.0f}s] {status_str} (iter {iteration}/{max_iter})")
+            else:
+                logger.info(f"  [{elapsed:.0f}s] {status_str}")
+        else:
+            logger.info(f"  [{elapsed:.0f}s] {status_str}")
+
+        if status_str in ("Completed", "Failed", "Cancelled"):
+            final_status = status
+            break
+
+        time.sleep(poll_interval)
+
+    total_time = time.time() - start_time
+
+    if final_status.get("status") != "Completed":
+        # Build detailed error message
+        error_parts = [f"Simulation ended with status: {final_status.get('status')}"]
+        for field in ("errorMessage", "ErrorMessage", "statusText", "StatusText"):
+            val = final_status.get(field)
+            if val:
+                error_parts.append(str(val))
+        progress_dto = final_status.get("progressDto") or final_status.get("progress") or final_status.get("Progress")
+        if progress_dto and isinstance(progress_dto, dict):
+            for field in ("progress", "Progress"):
+                val = progress_dto.get(field)
+                if val:
+                    error_parts.append(f"Details: {val}")
+            data_field = progress_dto.get("data") or progress_dto.get("Data")
+            if data_field:
+                try:
+                    if isinstance(data_field, str):
+                        data_obj = json.loads(data_field)
+                    else:
+                        data_obj = data_field
+                    if "residual_norm" in data_obj:
+                        error_parts.append(f"Final residual: {data_obj['residual_norm']:.2e}")
+                    if "error" in data_obj and data_obj["error"]:
+                        error_parts.append(f"Error: {data_obj['error']}")
+                except (json.JSONDecodeError, TypeError):
+                    error_parts.append(f"Data: {data_field}")
+        raise RuntimeError(". ".join(error_parts))
+
+    logger.info(f"  Simulation completed in {total_time:.1f} seconds!")
+
+    # 14. Download output field
+    logger.info("Downloading results...")
+    server_info = client.get_server_info()
+    use_machine_service = server_info["uses_machine_service"]
+
+    output_file_id = None
+
+    if use_machine_service:
+        files = client.list_command_files(command_id)
+        logger.info(f"  Found {len(files)} files from machine service")
+        for f in files:
+            fname = f.get("fileName") or f.get("originalFileName", "")
+            if fname.lower() == "output.bin":
+                output_file_id = f.get("blobName")
+                break
+    else:
+        version_info = client.get_project_version(project_id, version_id)
+        output_file_ids = version_info.get("outputFileIds", [])
+        logger.info(f"  Found {len(output_file_ids)} output file IDs from cloud storage")
+        for fid in output_file_ids:
+            try:
+                preview = client.get_file_preview(project_id, version_id, fid)
+                fname = preview.get("fileName") or preview.get("originalFileName", "")
+                if fname.lower() == "output.bin":
+                    output_file_id = fid  # Use the original ID from outputFileIds
+                    break
+            except Exception:
+                continue
+
+    if not output_file_id:
+        raise RuntimeError("output.bin not found in command files")
+
+    logger.info(f"  Found output.bin (ID: {output_file_id})")
+
+    # Download to memory
+    output_data = client.download_file_data(project_id, version_id, output_file_id)
+    logger.info(f"  Downloaded {len(output_data) / (1024 * 1024):.2f} MB")
+
+    # 15. Parse output
+    logger.info("Reading output field...")
+    if is_vectorial:
+        dims = (3, nx, ny, nz)
+    else:
+        dims = (nx, ny, nz)
+
+    E = read_binary_field(output_data, dims, "Complex64")
+    logger.info(f"  Output shape: {E.shape}")
+
+    converged = final_status.get("status") == "Completed"
+
+    logger.info("=" * 60)
+    logger.info("Simulation completed successfully!")
+    logger.info("=" * 60)
+
+    return E, converged