wavesimpro 0.9.0__py3-none-any.whl

wavesimpro/json_helper.py

@@ -0,0 +1,755 @@
+"""
+Helper functions to build WavesimProperties JSON structure
+
+This module provides Python functions to build the correct JSON structure
+that matches RayfosCommandModels.WavesimProperties C# class.
+
+Ported from examples/wavesim_json_helper.py with fixes for MATLAB API parity.
+"""
+
+import json
+import uuid
+from typing import List, Dict, Any, Optional
+
+
+def create_simulation_domain(
+    size_x: float = 10.0,
+    size_y: float = 10.0,
+    size_z: float = 10.0,
+    center_x: float = 0.0,
+    center_y: float = 0.0,
+    center_z: float = 0.0,
+    unit: str = "Micrometers"
+) -> Dict[str, Any]:
+    """
+    Create SimulationDomain structure
+
+    Args:
+        size_x, size_y, size_z: Domain size (width, height, depth)
+        center_x, center_y, center_z: Domain center position
+        unit: Unit of measurement (Micrometers, Nanometers, etc.)
+    """
+    return {
+        "PositioningMode": "CenterAndSize",
+        "Position": {
+            "X": {"Value": center_x, "Unit": unit},
+            "Y": {"Value": center_y, "Unit": unit},
+            "Z": {"Value": center_z, "Unit": unit}
+        },
+        "Size": {
+            "Width": {"Value": size_x, "Unit": unit},
+            "Height": {"Value": size_y, "Unit": unit},
+            "Depth": {"Value": size_z, "Unit": unit}
+        },
+    }
+
+
+def create_stl_primitive(
+    name: str,
+    file_id: str,
+    medium_id: str,
+    center_x: float = 0.0,
+    center_y: float = 0.0,
+    center_z: float = 0.0,
+    rotation_x: float = 0.0,
+    rotation_y: float = 0.0,
+    rotation_z: float = 0.0,
+    scale_x: float = 1.0,
+    scale_y: float = 1.0,
+    scale_z: float = 1.0,
+    unit: str = "Micrometers"
+) -> Dict[str, Any]:
+    """
+    Create STL primitive structure
+
+    Args:
+        name: Primitive name
+        file_id: ID or filename of uploaded STL file
+        medium_id: Medium/Material ID to use
+        center_x, center_y, center_z: Position
+        rotation_x, rotation_y, rotation_z: Rotation angles in degrees
+        scale_x, scale_y, scale_z: Scale factors
+        unit: Unit of measurement
+    """
+    return {
+        "Id": str(uuid.uuid4()),
+        "Name": name,
+        "ShapeType": "StlModel",
+        "MediumId": medium_id,
+        "PositioningMode": "CenterAndSize",
+        "Position": {
+            "X": {"Value": center_x, "Unit": unit},
+            "Y": {"Value": center_y, "Unit": unit},
+            "Z": {"Value": center_z, "Unit": unit}
+        },
+        "PositionAnchor": "Center",
+        "Rotation": {
+            "X": rotation_x,
+            "Y": rotation_y,
+            "Z": rotation_z
+        },
+        "StlDataId": file_id,
+        "ScaleFactors": {
+            "X": scale_x,
+            "Y": scale_y,
+            "Z": scale_z
+        },
+        "_tempStlData": {}
+    }
+
+
+def create_box_primitive(
+    name: str,
+    medium_id: str,
+    center_x: float,
+    center_y: float,
+    center_z: float,
+    size_x: float,
+    size_y: float,
+    size_z: float,
+    unit: str = "Micrometers"
+) -> Dict[str, Any]:
+    """Create a box primitive"""
+    return {
+        "Type": "Box",
+        "Name": name,
+        "MediumId": medium_id,
+        "PositioningMode": "CenterAndSize",
+        "Position": {
+            "X": {"Value": center_x, "Unit": unit},
+            "Y": {"Value": center_y, "Unit": unit},
+            "Z": {"Value": center_z, "Unit": unit}
+        },
+        "Size": {
+            "X": {"Value": size_x, "Unit": unit},
+            "Y": {"Value": size_y, "Unit": unit},
+            "Z": {"Value": size_z, "Unit": unit}
+        }
+    }
+
+
+def create_medium(
+    medium_id: str,
+    name: str,
+    refractive_index_real: float,
+    refractive_index_imag: float = 0.0,
+    category: str = "dielectric",
+    description: Optional[str] = None,
+    color: Optional[str] = None
+) -> Dict[str, Any]:
+    """
+    Create medium/material structure
+
+    Args:
+        medium_id: Unique ID for this medium (lowercase with hyphens)
+        name: Display name
+        refractive_index_real: Real part of refractive index
+        refractive_index_imag: Imaginary part (for absorption)
+        category: Material category ("gas", "dielectric", "semiconductor", "metal")
+        description: Optional description
+        color: Hex color code (e.g., "#FF0000")
+    """
+    medium = {
+        "id": medium_id,
+        "name": name,
+        "category": category,
+        "mediumType": "medium",
+        "inputMethod": "refractive_index",
+        "primaryReal": refractive_index_real,
+        "primaryImaginary": refractive_index_imag,
+        "permeabilityReal": 1,
+        "permeabilityImaginary": 0
+    }
+    if description:
+        medium["description"] = description
+    if color:
+        medium["Color"] = color
+    return medium
+
+
+def create_point_source(
+    name: str = "PointSource1",
+    position_x: float = 0.0,
+    position_y: float = 0.0,
+    position_z: float = 0.0,
+    amplitude_real: float = 1.0,
+    amplitude_imag: float = 0.0,
+    polarization: str = "None",
+    unit: str = "Micrometers"
+) -> Dict[str, Any]:
+    """
+    Create Point source
+
+    Args:
+        name: Source name
+        position_x, position_y, position_z: Source position
+        amplitude_real, amplitude_imag: Complex amplitude
+        polarization: "None", "X", "Y", "Z"
+        unit: Unit of measurement
+    """
+    return {
+        "Id": str(uuid.uuid4()),
+        "Name": name,
+        "SourceType": "Point",
+        "isEnabled": True,
+        "UseInternalPythonSource": False,
+        "Position": {
+            "X": {"Value": position_x, "Unit": unit},
+            "Y": {"Value": position_y, "Unit": unit},
+            "Z": {"Value": position_z, "Unit": unit}
+        },
+        "Polarization": polarization,
+        "Amplitude": {
+            "Real": amplitude_real,
+            "Imaginary": amplitude_imag
+        }
+    }
+
+
+def create_plane_wave_source(
+    name: str = "PlaneWave1",
+    position_x: float = 0.0,
+    position_y: float = 0.0,
+    position_z: float = 0.0,
+    source_plane: str = "XZ",
+    amplitude_real: float = 1.0,
+    amplitude_imag: float = 0.0,
+    size_x: float = 10.0,
+    size_y: float = 10.0,
+    size_z: float = 10.0,
+    polarization: str = "None",
+    theta: Optional[float] = None,
+    phi: Optional[float] = None,
+    origin: str = "center",
+    unit: str = "Micrometers"
+) -> Dict[str, Any]:
+    """
+    Create PlaneWave source
+
+    Args:
+        name: Source name
+        position_x, position_y, position_z: Source position
+        source_plane: "X", "Y", "Z", "XY", "YZ", "XZ" (UPPERCASE)
+        amplitude_real, amplitude_imag: Complex amplitude
+        size_x, size_y, size_z: Source dimensions
+        polarization: "None", "X", "Y", "Z" (UPPERCASE)
+        theta: Incident angle in radians (optional)
+        phi: Azimuthal angle in radians (optional)
+        origin: "center" or "topleft"
+        unit: Unit of measurement
+    """
+    source = {
+        "SourceType": "PlaneWave",
+        "Name": name,
+        "IsEnabled": True,
+        "Position": {
+            "X": {"Value": position_x, "Unit": unit},
+            "Y": {"Value": position_y, "Unit": unit},
+            "Z": {"Value": position_z, "Unit": unit}
+        },
+        "Polarization": polarization,
+        "Amplitude": {
+            "Real": amplitude_real,
+            "Imaginary": amplitude_imag
+        },
+        "SourcePlane": source_plane,
+        "Size": {
+            "Width": {"Value": size_x, "Unit": unit},
+            "Height": {"Value": size_y, "Unit": unit},
+            "Depth": {"Value": size_z, "Unit": unit}
+        },
+        "Origin": origin
+    }
+
+    if theta is not None:
+        source["Theta"] = theta
+    if phi is not None:
+        source["Phi"] = phi
+
+    return source
+
+
+def create_gaussian_beam_source(
+    name: str = "GaussianBeam1",
+    position_x: float = 0.0,
+    position_y: float = 0.0,
+    position_z: float = 0.0,
+    source_plane: str = "XZ",
+    amplitude_real: float = 1.0,
+    amplitude_imag: float = 0.0,
+    size_x: float = 10.0,
+    size_y: float = 10.0,
+    size_z: float = 10.0,
+    polarization: str = "None",
+    alpha: float = 3.0,
+    sigma: Optional[float] = None,
+    theta: Optional[float] = None,
+    phi: Optional[float] = None,
+    origin: str = "center",
+    unit: str = "Micrometers"
+) -> Dict[str, Any]:
+    """
+    Create GaussianBeam source
+
+    Args:
+        name: Source name
+        position_x, position_y, position_z: Source position
+        source_plane: "X", "Y", "Z", "XY", "YZ", "XZ"
+        amplitude_real, amplitude_imag: Complex amplitude
+        size_x, size_y, size_z: Source dimensions
+        polarization: "None", "X", "Y", "Z"
+        alpha: Gaussian width factor (default: 3.0)
+        sigma: Standard deviation (optional, overrides alpha)
+        theta: Incident angle in radians (optional)
+        phi: Azimuthal angle in radians (optional)
+        origin: "center" or "topleft"
+        unit: Unit of measurement
+    """
+    source = {
+        "SourceType": "GaussianBeam",
+        "Name": name,
+        "IsEnabled": True,
+        "Position": {
+            "X": {"Value": position_x, "Unit": unit},
+            "Y": {"Value": position_y, "Unit": unit},
+            "Z": {"Value": position_z, "Unit": unit}
+        },
+        "Polarization": polarization,
+        "Amplitude": {
+            "Real": amplitude_real,
+            "Imaginary": amplitude_imag
+        },
+        "SourcePlane": source_plane,
+        "Size": {
+            "X": {"Value": size_x, "Unit": unit},
+            "Y": {"Value": size_y, "Unit": unit},
+            "Z": {"Value": size_z, "Unit": unit}
+        },
+        "Alpha": alpha,
+        "Origin": origin
+    }
+
+    if sigma is not None:
+        source["Sigma"] = sigma
+    if theta is not None:
+        source["Theta"] = theta
+    if phi is not None:
+        source["Phi"] = phi
+
+    return source
+
+
+def create_voxels_model_primitive(
+    name: str,
+    voxels_data_id: str,
+    medium_id: str,
+    center_x: float = 0.0,
+    center_y: float = 0.0,
+    center_z: float = 0.0,
+    voxel_size_x: float = 0.1,
+    voxel_size_y: float = 0.1,
+    voxel_size_z: float = 0.1,
+    grid_nx: int = 32,
+    grid_ny: int = 32,
+    grid_nz: int = 32,
+    data_format: str = "Float32",
+    data_type: str = "RefractiveIndex",
+    unit: str = "Micrometers"
+) -> Dict[str, Any]:
+    """
+    Create VoxelsModel primitive for arbitrary refractive index distributions
+
+    Args:
+        name: Primitive name
+        voxels_data_id: ID of uploaded binary voxel data file
+        medium_id: Medium/Material ID for the primitive
+        center_x, center_y, center_z: Center position
+        voxel_size_x, voxel_size_y, voxel_size_z: Size of each voxel
+        grid_nx, grid_ny, grid_nz: Number of voxels in each dimension
+        data_format: 'Float32', 'Float64', 'Complex64', 'Complex128'
+        data_type: 'RefractiveIndex', 'ComplexRefractiveIndex', 'Permittivity', 'ComplexPermittivity'
+        unit: Unit of measurement
+    """
+    return {
+        "ShapeType": "VoxelsModel",
+        "Name": name,
+        "MediumId": medium_id,
+        "VoxelsDataId": voxels_data_id,
+        "Position": {
+            "X": {"Value": center_x, "Unit": unit},
+            "Y": {"Value": center_y, "Unit": unit},
+            "Z": {"Value": center_z, "Unit": unit}
+        },
+        "SourceVoxelSize": {
+            "X": voxel_size_x,
+            "Y": voxel_size_y,
+            "Z": voxel_size_z
+        },
+        "SourceGridDimensions": {
+            "X": grid_nx,
+            "Y": grid_ny,
+            "Z": grid_nz
+        },
+        "DataFormat": data_format,
+        "DataType": data_type,
+        "Rotation": {"X": 0, "Y": 0, "Z": 0}
+    }
+
+
+def create_custom_field_source(
+    name: str,
+    field_data_id: str,
+    position_x: float = 0.0,
+    position_y: float = 0.0,
+    position_z: float = 0.0,
+    grid_nx: int = 1,
+    grid_ny: int = 1,
+    grid_nz: int = 1,
+    polarization: str = "X",
+    amplitude_real: float = 1.0,
+    amplitude_imag: float = 0.0,
+    data_format: str = "Complex64",
+    origin: str = "center",
+    unit: str = "Micrometers"
+) -> Dict[str, Any]:
+    """
+    Create CustomField source for pre-computed field distributions (e.g., eigenmodes)
+
+    Backend derives voxel size from the simulation domain settings.
+
+    Args:
+        name: Source name
+        field_data_id: ID of uploaded complex field data file
+        position_x, position_y, position_z: Source position
+        grid_nx, grid_ny, grid_nz: Grid dimensions of field data
+        polarization: 'X', 'Y', 'Z', 'None'
+        amplitude_real, amplitude_imag: Amplitude scaling
+        data_format: 'Complex64' or 'Complex128'
+        origin: 'center' or 'topleft'
+        unit: Unit of measurement
+    """
+    return {
+        "SourceType": "CustomField",
+        "Name": name,
+        "IsEnabled": True,
+        "FieldDataId": field_data_id,
+        "Position": {
+            "X": {"Value": position_x, "Unit": unit},
+            "Y": {"Value": position_y, "Unit": unit},
+            "Z": {"Value": position_z, "Unit": unit}
+        },
+        "Polarization": polarization,
+        "Origin": origin,
+        "Amplitude": {
+            "Real": amplitude_real,
+            "Imaginary": amplitude_imag
+        },
+        "GridDimensions": {
+            "X": grid_nx,
+            "Y": grid_ny,
+            "Z": grid_nz
+        },
+        "DataFormat": data_format,
+    }
+
+
+def create_custom_from_file_source(
+    name: str,
+    file_id: str,
+    position_x: float = 0.0,
+    position_y: float = 0.0,
+    position_z: float = 0.0,
+    file_format: str = "JsonV2",
+    unit: str = "Micrometers"
+) -> Dict[str, Any]:
+    """
+    Create CustomFromFile source (external file)
+
+    Args:
+        name: Source name
+        file_id: ID or filename of uploaded source file
+        position_x, position_y, position_z: Source position
+        file_format: "JsonV2", "NumpyNpy", "MatlabMat", "RawBinary"
+        unit: Unit of measurement
+    """
+    return {
+        "SourceType": "CustomFromFile",
+        "Name": name,
+        "IsEnabled": True,
+        "Position": {
+            "X": {"Value": position_x, "Unit": unit},
+            "Y": {"Value": position_y, "Unit": unit},
+            "Z": {"Value": position_z, "Unit": unit}
+        },
+        "FileDataId": file_id,
+        "FileFormat": file_format
+    }
+
+
+def create_field_monitor(
+    name: str,
+    center_x: float,
+    center_y: float,
+    center_z: float,
+    size_x: float,
+    size_y: float,
+    size_z: float,
+    plane: str = "xy",
+    record_ex: bool = True,
+    record_ey: bool = True,
+    record_ez: bool = True,
+    record_hx: bool = False,
+    record_hy: bool = False,
+    record_hz: bool = False,
+    unit: str = "Micrometers"
+) -> Dict[str, Any]:
+    """
+    Create field monitor
+
+    Args:
+        name: Monitor name
+        center_x, center_y, center_z: Monitor center position
+        size_x, size_y, size_z: Monitor size (use 0 for 2D plane)
+        plane: Monitor plane "xy", "yz", "xz" (lowercase)
+        record_ex, record_ey, record_ez: Record E-field components
+        record_hx, record_hy, record_hz: Record H-field components
+        unit: Unit of measurement
+    """
+    return {
+        "id": str(uuid.uuid4()),
+        "name": name,
+        "monitorType": "field",
+        "isEnabled": True,
+        "PositioningMode": "CenterAndSize",
+        "Position": {
+            "X": {"Value": center_x, "Unit": unit},
+            "Y": {"Value": center_y, "Unit": unit},
+            "Z": {"Value": center_z, "Unit": unit}
+        },
+        "Size": {
+            "Width": {"Value": size_x, "Unit": unit},
+            "Height": {"Value": size_y, "Unit": unit},
+            "Depth": {"Value": size_z, "Unit": unit}
+        },
+        "plane": plane,
+        "spatialSampling": {"x": 1, "y": 1, "z": 1},
+        "RecordEx": record_ex,
+        "RecordEy": record_ey,
+        "RecordEz": record_ez,
+        "RecordHx": record_hx,
+        "RecordHy": record_hy,
+        "RecordHz": record_hz
+    }
+
+
+def create_flux_monitor(
+    name: str,
+    center_x: float,
+    center_y: float,
+    center_z: float,
+    size_x: float,
+    size_y: float,
+    size_z: float,
+    plane: str = "xy",
+    unit: str = "Micrometers"
+) -> Dict[str, Any]:
+    """
+    Create flux monitor
+
+    Args:
+        name: Monitor name
+        center_x, center_y, center_z: Monitor center position
+        size_x, size_y, size_z: Monitor size (use 0 for 2D plane)
+        plane: Monitor plane "xy", "yz", "xz" (lowercase)
+        unit: Unit of measurement
+    """
+    return {
+        "monitorType": "flux",
+        "Name": name,
+        "IsEnabled": True,
+        "PositioningMode": "CenterAndSize",
+        "Position": {
+            "X": {"Value": center_x, "Unit": unit},
+            "Y": {"Value": center_y, "Unit": unit},
+            "Z": {"Value": center_z, "Unit": unit}
+        },
+        "Size": {
+            "X": {"Value": size_x, "Unit": unit},
+            "Y": {"Value": size_y, "Unit": unit},
+            "Z": {"Value": size_z, "Unit": unit}
+        },
+        "Plane": plane
+    }
+
+
+def create_permittivity_monitor(
+    name: str,
+    center_x: float,
+    center_y: float,
+    center_z: float,
+    size_x: float,
+    size_y: float,
+    size_z: float,
+    plane: str = "xy",
+    unit: str = "Micrometers"
+) -> Dict[str, Any]:
+    """
+    Create permittivity monitor
+
+    Args:
+        name: Monitor name
+        center_x, center_y, center_z: Monitor center position
+        size_x, size_y, size_z: Monitor size (use 0 for 2D plane)
+        plane: Monitor plane "xy", "yz", "xz" (lowercase)
+        unit: Unit of measurement
+    """
+    return {
+        "id": str(uuid.uuid4()),
+        "name": name,
+        "monitorType": "permittivity",
+        "isEnabled": True,
+        "PositioningMode": "CenterAndSize",
+        "Position": {
+            "X": {"Value": center_x, "Unit": unit},
+            "Y": {"Value": center_y, "Unit": unit},
+            "Z": {"Value": center_z, "Unit": unit}
+        },
+        "Size": {
+            "Width": {"Value": size_x, "Unit": unit},
+            "Height": {"Value": size_y, "Unit": unit},
+            "Depth": {"Value": size_z, "Unit": unit}
+        },
+        "plane": plane,
+        "spatialSampling": {"x": 1, "y": 1, "z": 1}
+    }
+
+
+def create_wavesim_properties(
+    simulation_domain: Dict[str, Any],
+    primitives: List[Dict[str, Any]],
+    input_sources: List[Dict[str, Any]],
+    mediums: List[Dict[str, Any]],
+    monitors: List[Dict[str, Any]],
+    background_medium_id: str = "",
+    wavelength: float = 1.55,
+    voxel_size: float = 0.05,
+    wavelength_unit: str = "Micrometers",
+    voxel_unit: str = "Micrometers",
+    boundary_size_um: float = 0.0,
+    residual_norm_threshold: float = 1.0e-6,
+    residual_norm_max_iterations: int = 10000,
+    periodic_x: bool = False,
+    periodic_y: bool = False,
+    periodic_z: bool = False
+) -> Dict[str, Any]:
+    """
+    Create complete WavesimProperties structure
+
+    This is the top-level structure that should be serialized to JSON
+    and passed as argumentsJson to create_command().
+
+    Args:
+        simulation_domain: Domain from create_simulation_domain()
+        primitives: List of primitive structures
+        input_sources: List of source structures
+        mediums: List of medium structures
+        monitors: List of monitor structures
+        background_medium_id: ID of background medium
+        wavelength: Wavelength value
+        voxel_size: Voxel size value
+        wavelength_unit: Wavelength unit (default: 'Micrometers')
+        voxel_unit: Voxel size unit (default: 'Micrometers')
+        boundary_size_um: Boundary size in micrometers
+        residual_norm_threshold: Convergence threshold
+        residual_norm_max_iterations: Max iterations
+        periodic_x, periodic_y, periodic_z: Periodic boundary conditions
+    """
+    return {
+        "SimulationDomain": simulation_domain,
+        "BackgroundMediumId": background_medium_id,
+        "Primitives": primitives,
+        "InputSources": input_sources,
+        "Mediums": mediums,
+        "Monitors": monitors,
+        "Wavelength": {
+            "Value": wavelength,
+            "Unit": wavelength_unit
+        },
+        "VoxelSize": {
+            "Value": voxel_size,
+            "Unit": voxel_unit
+        },
+        "BoundarySize": {
+            "Value": boundary_size_um,
+            "Unit": "Micrometers"
+        },
+        "ResidualNormThreshold": residual_norm_threshold,
+        "ResidualNormMaxIterations": residual_norm_max_iterations,
+        "PeriodicX": periodic_x,
+        "PeriodicY": periodic_y,
+        "PeriodicZ": periodic_z,
+        "DefaultLengthUnit": "Micrometers",
+        "CoordinateSystemCenter": {
+            "X": {"Value": 0.0, "Unit": "Micrometers"},
+            "Y": {"Value": 0.0, "Unit": "Micrometers"},
+            "Z": {"Value": 0.0, "Unit": "Micrometers"}
+        }
+    }
+
+
+def parse_progress_data(progress_obj: Optional[Dict[str, Any]]) -> Dict[str, Any]:
+    """
+    Parse CommandProgressDto with nested JSON strings.
+
+    Args:
+        progress_obj: CommandProgressDto dict from get_command_status()
+
+    Returns:
+        Dict with parsed progress fields: status, iteration, percentage,
+        max_iterations, residual_norm, threshold
+    """
+    info: Dict[str, Any] = {}
+
+    if not progress_obj:
+        return info
+
+    if "status" in progress_obj:
+        info["status"] = progress_obj["status"]
+
+    # Parse Progress JSON string
+    progress_str = progress_obj.get("progress")
+    if progress_str:
+        try:
+            if isinstance(progress_str, str):
+                import json as _json
+                progress_data = _json.loads(progress_str)
+            else:
+                progress_data = progress_str
+
+            if "iteration" in progress_data:
+                info["iteration"] = progress_data["iteration"]
+            if "percentage" in progress_data:
+                info["percentage"] = progress_data["percentage"]
+            if "max_iterations" in progress_data:
+                info["max_iterations"] = progress_data["max_iterations"]
+        except (json.JSONDecodeError, TypeError, ValueError):
+            pass
+
+    # Parse Data JSON string
+    data_str = progress_obj.get("data")
+    if data_str:
+        try:
+            if isinstance(data_str, str):
+                import json as _json
+                data_obj = _json.loads(data_str)
+            else:
+                data_obj = data_str
+
+            if "residual_norm" in data_obj:
+                info["residual_norm"] = data_obj["residual_norm"]
+            if "residual_norm_threshold" in data_obj:
+                info["threshold"] = data_obj["residual_norm_threshold"]
+        except (json.JSONDecodeError, TypeError, ValueError):
+            pass
+
+    return info