pysie2d 0.2.0__tar.gz

pysie2d-0.2.0/PKG-INFO

@@ -0,0 +1,150 @@
+Metadata-Version: 2.3
+Name: pysie2d
+Version: 0.2.0
+Summary: 2-D boundary-integral (Müller BIE) solver for electromagnetic scattering from a cylinder in a homogeneous background.
+Author: Claudio Silvestre Castro
+Author-email: Claudio Silvestre Castro <claudio.silvestre.castro@gmail.com>
+License: MIT
+Requires-Dist: numpy>=1.26
+Requires-Dist: scipy>=1.11
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+
+# pysie2d
+
+A 2-D surface-integral-equation solver for time-harmonic
+electromagnetic scattering from a single smooth cylinder — circular or
+Gielis-superformula cross-section, embedded in a homogeneous background. Validated
+against analytic Mie theory, with a typed public API and CI.
+
+## Scope and non-goals
+
+This package is distilled from a larger private research code; it deliberately
+covers only the **homogeneous-background, single-particle core** — the part
+that can be validated end-to-end against a closed-form reference. Potential extensions
+in the mid/long-term include slab waveguide backgrounds, multiple-particle simulations,
+and quasinormal-mode searches based on the surface-integral matrix operator.
+
+## Figures
+
+Relative error of the scattering efficiency `Q_sca` versus the number of
+boundary points, converging toward analytic Mie theory (both polarisations):
+
+![Convergence to Mie theory](figures/convergence_study.png)
+
+Near field of a Gielis `m = 6` star under plane-wave illumination (scattered
+field outside the boundary, internal field inside):
+
+![Near-field map](figures/nearfield_map.png)
+
+Relative local density of states (Purcell map) around the same Gielis `m = 6`
+star, at one of its `qsca` resonances: a line-dipole emitter placed in a red
+lobe decays faster than in free space (`1 + 4·Im S > 1`), while blue regions
+suppress it. The six-fold pattern mirrors the particle's symmetry. The drive
+*and* the decay rate of an embedded emitter both come from this map — it is the
+entry point of quantum-dynamics calculations downstream:
+
+![Purcell map](figures/purcell_map.png)
+
+Regenerate them with:
+
+```bash
+uv run python examples/convergence_study.py
+uv run python examples/nearfield_map.py
+uv run python examples/purcell_map.py
+```
+
+## Formulation (summary)
+
+- The cylinder is invariant along its axis, so Maxwell reduces to a scalar
+  Helmholtz problem for one field component (`E_y` for TE, `H_y` for TM).
+- The self-consistent field solution is given **everywhere** in terms of the surface field and its normal derivative;
+  matching across the interface gives a Fredholm integral equation of the second kind.
+- Discretising the boundary with `nn` quadrature points yields a dense
+  `2nn × 2nn` complex system `M(λ)·ei = rhs`, solved directly.
+- The logarithmic Green-function singularity is handled analytically in the
+  diagonal terms; complex wavenumbers are supported throughout.
+- Lengths are in nm, the time convention is `exp(-iωt)`, and outgoing waves are
+  `H_n^{(1)}`.
+
+Full details and every sign/layout convention are in
+[docs/conventions.md](docs/conventions.md). The analytic reference is Bohren &
+Huffman, *Absorption and Scattering of Light by Small Particles*, ch. 8; the
+surface-integral formulation follows [Valencia et al's formulation](https://doi.org/10.1364/JOSAB.20.002150).
+
+## Validation
+
+The physics test suite compares the solver against analytic Mie theory for a
+circular cylinder: scattering / extinction / absorption efficiencies, the
+optical theorem on a lossy particle, energy conservation on a lossless one, the
+convergence rate, and the 2-D `1/√(kr)` far-field decay. At `nn = 300` the
+efficiencies agree with Mie to a few parts in `10³`; the error decreases with
+`nn` until it reaches the fixed angular-quadrature floor of the far-field
+integrator. See `tests/` for the exact tolerances and the reasoning behind them.
+
+The line-dipole / self-Green machinery (v0.2) is validated the same way:
+reciprocity of the scattered field (to `10⁻⁶`), the free-space limit
+(`LDOS → 1` far from the particle), LDOS positivity, and — the strong anchor —
+the self-Green function of a circular cylinder against its closed-form
+Graf-addition-theorem sum on both `Re S` and `Im S`. That near-field anchor
+converges at first order in `nn`, so it is run at `nn = 1000` to reach `1 %`;
+the resolved scattered-field sign convention is recorded in
+[docs/conventions.md](docs/conventions.md).
+
+## Install / run / test
+
+Requires Python 3.12 and [uv](https://docs.astral.sh/uv/).
+
+```bash
+uv sync                       # create the environment
+uv run pytest                 # run the validation suite
+uv run ruff format --check .  # formatting
+uv run ruff check .           # lint
+```
+
+Minimal use:
+
+```python
+from pysie2d import BIESolver, Geometry, Material
+
+geom = Geometry.gielis(rad=200, n_pts=300, m=0)   # circular cylinder, nm
+mat = Material(n_core=1.5, n_clad=1.0, pol=2)      # TE
+result = BIESolver(geom, mat).scatter(wavelength=600.0)
+
+print(result.efficiencies())                       # {'qsca', 'qext', 'qabs'}
+```
+
+Line-dipole emitter and Purcell effect:
+
+```python
+from pysie2d import BIESolver, Geometry, Material, relative_ldos
+
+geom = Geometry.gielis(rad=200, n_pts=300, m=6, n1=6, n2=12, n3=12)  # Gielis star
+solver = BIESolver(geom, Material(n_core=2.0))
+print(relative_ldos(solver, wavelength=540.0, x_s=430.0, z_s=0.0))  # LDOS vs free space
+```
+
+## Performance
+
+The system is a dense `2nn × 2nn` complex matrix; at `nn = 300` (a `600 × 600`
+solve) a single wavelength takes below one second in a modern computer, so wavelength
+sweeps are cheap serial `for` loops — no parallelism required.
+
+For a Purcell map, every grid point is a different source position, hence a
+different right-hand side — but the matrix `M(λ)` is the same for all of them.
+`relative_ldos_map` therefore factorises `M` **once** with
+`scipy.linalg.lu_factor` and reuses it across all sources (`lu_solve`), turning
+what would be an hour-long sweep into a few seconds.
+
+## Roadmap
+
+- **v0.1.0** — core scattering: plane-wave excitation, near/far fields,
+  cross-section efficiencies, Mie validation, convergence study, CI.
+- **v0.2.0** — line-dipole (point-source) excitation and the self-Green
+  function → relative LDOS / Purcell maps. _(this release)_
+- **v0.3.0** — quasi-normal-mode extraction via Beyn's contour method,
+  validated against analytic Mie resonances.
+
+## License
+
+MIT — see [LICENSE](LICENSE).

pysie2d-0.2.0/README.md

@@ -0,0 +1,138 @@
+# pysie2d
+
+A 2-D surface-integral-equation solver for time-harmonic
+electromagnetic scattering from a single smooth cylinder — circular or
+Gielis-superformula cross-section, embedded in a homogeneous background. Validated
+against analytic Mie theory, with a typed public API and CI.
+
+## Scope and non-goals
+
+This package is distilled from a larger private research code; it deliberately
+covers only the **homogeneous-background, single-particle core** — the part
+that can be validated end-to-end against a closed-form reference. Potential extensions
+in the mid/long-term include slab waveguide backgrounds, multiple-particle simulations,
+and quasinormal-mode searches based on the surface-integral matrix operator.
+
+## Figures
+
+Relative error of the scattering efficiency `Q_sca` versus the number of
+boundary points, converging toward analytic Mie theory (both polarisations):
+
+![Convergence to Mie theory](figures/convergence_study.png)
+
+Near field of a Gielis `m = 6` star under plane-wave illumination (scattered
+field outside the boundary, internal field inside):
+
+![Near-field map](figures/nearfield_map.png)
+
+Relative local density of states (Purcell map) around the same Gielis `m = 6`
+star, at one of its `qsca` resonances: a line-dipole emitter placed in a red
+lobe decays faster than in free space (`1 + 4·Im S > 1`), while blue regions
+suppress it. The six-fold pattern mirrors the particle's symmetry. The drive
+*and* the decay rate of an embedded emitter both come from this map — it is the
+entry point of quantum-dynamics calculations downstream:
+
+![Purcell map](figures/purcell_map.png)
+
+Regenerate them with:
+
+```bash
+uv run python examples/convergence_study.py
+uv run python examples/nearfield_map.py
+uv run python examples/purcell_map.py
+```
+
+## Formulation (summary)
+
+- The cylinder is invariant along its axis, so Maxwell reduces to a scalar
+  Helmholtz problem for one field component (`E_y` for TE, `H_y` for TM).
+- The self-consistent field solution is given **everywhere** in terms of the surface field and its normal derivative;
+  matching across the interface gives a Fredholm integral equation of the second kind.
+- Discretising the boundary with `nn` quadrature points yields a dense
+  `2nn × 2nn` complex system `M(λ)·ei = rhs`, solved directly.
+- The logarithmic Green-function singularity is handled analytically in the
+  diagonal terms; complex wavenumbers are supported throughout.
+- Lengths are in nm, the time convention is `exp(-iωt)`, and outgoing waves are
+  `H_n^{(1)}`.
+
+Full details and every sign/layout convention are in
+[docs/conventions.md](docs/conventions.md). The analytic reference is Bohren &
+Huffman, *Absorption and Scattering of Light by Small Particles*, ch. 8; the
+surface-integral formulation follows [Valencia et al's formulation](https://doi.org/10.1364/JOSAB.20.002150).
+
+## Validation
+
+The physics test suite compares the solver against analytic Mie theory for a
+circular cylinder: scattering / extinction / absorption efficiencies, the
+optical theorem on a lossy particle, energy conservation on a lossless one, the
+convergence rate, and the 2-D `1/√(kr)` far-field decay. At `nn = 300` the
+efficiencies agree with Mie to a few parts in `10³`; the error decreases with
+`nn` until it reaches the fixed angular-quadrature floor of the far-field
+integrator. See `tests/` for the exact tolerances and the reasoning behind them.
+
+The line-dipole / self-Green machinery (v0.2) is validated the same way:
+reciprocity of the scattered field (to `10⁻⁶`), the free-space limit
+(`LDOS → 1` far from the particle), LDOS positivity, and — the strong anchor —
+the self-Green function of a circular cylinder against its closed-form
+Graf-addition-theorem sum on both `Re S` and `Im S`. That near-field anchor
+converges at first order in `nn`, so it is run at `nn = 1000` to reach `1 %`;
+the resolved scattered-field sign convention is recorded in
+[docs/conventions.md](docs/conventions.md).
+
+## Install / run / test
+
+Requires Python 3.12 and [uv](https://docs.astral.sh/uv/).
+
+```bash
+uv sync                       # create the environment
+uv run pytest                 # run the validation suite
+uv run ruff format --check .  # formatting
+uv run ruff check .           # lint
+```
+
+Minimal use:
+
+```python
+from pysie2d import BIESolver, Geometry, Material
+
+geom = Geometry.gielis(rad=200, n_pts=300, m=0)   # circular cylinder, nm
+mat = Material(n_core=1.5, n_clad=1.0, pol=2)      # TE
+result = BIESolver(geom, mat).scatter(wavelength=600.0)
+
+print(result.efficiencies())                       # {'qsca', 'qext', 'qabs'}
+```
+
+Line-dipole emitter and Purcell effect:
+
+```python
+from pysie2d import BIESolver, Geometry, Material, relative_ldos
+
+geom = Geometry.gielis(rad=200, n_pts=300, m=6, n1=6, n2=12, n3=12)  # Gielis star
+solver = BIESolver(geom, Material(n_core=2.0))
+print(relative_ldos(solver, wavelength=540.0, x_s=430.0, z_s=0.0))  # LDOS vs free space
+```
+
+## Performance
+
+The system is a dense `2nn × 2nn` complex matrix; at `nn = 300` (a `600 × 600`
+solve) a single wavelength takes below one second in a modern computer, so wavelength
+sweeps are cheap serial `for` loops — no parallelism required.
+
+For a Purcell map, every grid point is a different source position, hence a
+different right-hand side — but the matrix `M(λ)` is the same for all of them.
+`relative_ldos_map` therefore factorises `M` **once** with
+`scipy.linalg.lu_factor` and reuses it across all sources (`lu_solve`), turning
+what would be an hour-long sweep into a few seconds.
+
+## Roadmap
+
+- **v0.1.0** — core scattering: plane-wave excitation, near/far fields,
+  cross-section efficiencies, Mie validation, convergence study, CI.
+- **v0.2.0** — line-dipole (point-source) excitation and the self-Green
+  function → relative LDOS / Purcell maps. _(this release)_
+- **v0.3.0** — quasi-normal-mode extraction via Beyn's contour method,
+  validated against analytic Mie resonances.
+
+## License
+
+MIT — see [LICENSE](LICENSE).

pysie2d-0.2.0/pyproject.toml

@@ -0,0 +1,67 @@
+[project]
+name = "pysie2d"
+version = "0.2.0"
+description = "2-D boundary-integral (Müller BIE) solver for electromagnetic scattering from a cylinder in a homogeneous background."
+readme = "README.md"
+license = { text = "MIT" }
+authors = [
+    { name = "Claudio Silvestre Castro", email = "claudio.silvestre.castro@gmail.com" },
+]
+requires-python = ">=3.12"
+dependencies = ["numpy>=1.26", "scipy>=1.11"]
+
+[build-system]
+requires = ["uv_build>=0.10.12,<0.11.0"]
+build-backend = "uv_build"
+
+[dependency-groups]
+dev = ["pytest>=8", "ruff>=0.8", "matplotlib>=3.9"]
+
+[tool.ruff]
+line-length = 88
+src = ["src", "tests"]
+
+[tool.ruff.lint]
+select = ["E", "F", "D", "N", "B", "I", "C4", "A"]
+ignore = [
+    "D203", "D204", "D213", "D215", "D400", "D401",
+    "D404", "D406", "D407", "D408", "D409", "D413",
+]
+
+[tool.ruff.lint.pydocstyle]
+convention = "google"
+
+[tool.ruff.lint.per-file-ignores]
+"tests/*" = ["D"]  # test names are the documentation
+# Keep the Bessel/Hankel math notation (J_n, H_n) that maps directly onto the
+# cited Bohren & Huffman equations; snake_case would obscure the reference.
+"src/pysie2d/reference/mie.py" = ["N806"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+
+[tool.semantic_release]
+version_toml = ["pyproject.toml:project.version"]
+commit_parser = "conventional"
+commit_parser_options = { ignore_merge_commits = true }
+major_on_zero = false
+build_command = "uv build"
+
+[tool.semantic_release.branches.main]
+match = "main"
+prerelease = false
+
+[tool.semantic_release.changelog]
+changelog_file = "CHANGELOG.md"
+exclude_commit_patterns = [
+    '''chore(?:\([^)]*?\))?: .+''',
+    '''ci(?:\([^)]*?\))?: .+''',
+    '''test(?:\([^)]*?\))?: .+''',
+    '''Merged? .*''',
+]
+
+[tool.semantic_release.remote]
+type = "github"
+
+[tool.semantic_release.publish]
+upload_to_vcs_release = true

pysie2d-0.2.0/src/pysie2d/__init__.py

@@ -0,0 +1,40 @@
+"""pysie2d — 2-D boundary-integral scattering solver (homogeneous background).
+
+Public API:
+    Geometry: Gielis-superformula boundary parameterisation.
+    Material: optical properties of the scatterer.
+    BIESolver: solver façade; call ``scatter``/``scatter_dipole`` to obtain a
+        ``ScatterResult``.
+    ScatterResult: carries the solution and exposes far/near-field analysis.
+    assemble_matrix: the vectorised BIE system-matrix assembly.
+    plane_wave_rhs, line_dipole_rhs: excitation right-hand sides.
+    eval_field, far_field: field-evaluation primitives.
+    self_green, relative_ldos, relative_ldos_map: self-Green function and
+        LDOS / Purcell-effect analysis (line-dipole excitation).
+"""
+
+from .fields import eval_field, far_field
+from .geometry import Geometry
+from .green import relative_ldos, relative_ldos_map, self_green
+from .kernels import assemble_matrix, assemble_matrix_reference
+from .material import Material
+from .solver import BIESolver, ScatterResult
+from .sources import line_dipole_rhs, plane_wave_rhs
+
+__version__ = "0.2.0"
+
+__all__ = [
+    "BIESolver",
+    "Geometry",
+    "Material",
+    "ScatterResult",
+    "assemble_matrix",
+    "assemble_matrix_reference",
+    "eval_field",
+    "far_field",
+    "line_dipole_rhs",
+    "plane_wave_rhs",
+    "relative_ldos",
+    "relative_ldos_map",
+    "self_green",
+]

pysie2d-0.2.0/src/pysie2d/fields.py

@@ -0,0 +1,166 @@
+"""Field evaluation: far-field amplitude and arbitrary-point near fields."""
+
+import numpy as np
+
+from .kernels import hank0, hank1
+
+PI = np.pi
+
+
+# ---------------------------------------------------------------------------
+# Far-field amplitude  (subroutine efi)
+# ---------------------------------------------------------------------------
+
+
+def far_field(
+    nn: int,
+    nff: int,
+    lambd: float,
+    f: np.ndarray,
+    g: np.ndarray,
+    df: np.ndarray,
+    dg: np.ndarray,
+    delt: float | np.ndarray,
+    ei: np.ndarray,
+) -> tuple[np.ndarray, np.ndarray]:
+    """Compute the 2-D far-field scattering amplitude.
+
+    Args:
+        nn: Number of boundary points.
+        nff: Number of far-field angles.
+        lambd: Wavelength (nm).
+        f: (nn,) boundary x coordinates (nm).
+        g: (nn,) boundary z coordinates (nm).
+        df: (nn,) first derivative of f w.r.t. θ.
+        dg: (nn,) first derivative of g w.r.t. θ.
+        delt: Quadrature θ-step (scalar or per-point array).
+        ei: complex (2nn,) BIE solution vector.
+
+    Returns:
+        amp: complex (nff,) far-field amplitude.
+        angles: float (nff,) observation angles (rad), from −π to π.
+    """
+    wnum = 2.0 * PI / lambd
+    angles = -PI + np.arange(nff) * 2.0 * PI / (nff - 1.0)
+    se = np.sin(angles)
+    co = np.cos(angles)
+
+    # shape (nn, nff)
+    arg = -1j * wnum * (f[:, None] * se + g[:, None] * co)
+    phi_j = ei[:nn, None]
+    chi_j = ei[nn:, None]
+    puto = 1j * wnum * (dg[:, None] * se - df[:, None] * co) * phi_j - chi_j
+    # delt may be a scalar or a per-point (nn,) array
+    delt_col = np.reshape(delt, (-1, 1)) if np.ndim(delt) > 0 else delt
+    amp = np.sum(np.exp(arg) * puto * delt_col, axis=0)
+
+    return amp, angles
+
+
+# ---------------------------------------------------------------------------
+# Inside/outside test  (subroutine eicero)
+# ---------------------------------------------------------------------------
+
+
+def _is_outside(
+    x1: float,
+    x3: float,
+    f: np.ndarray,
+    g: np.ndarray,
+    df: np.ndarray,
+    dg: np.ndarray,
+) -> bool:
+    """Return True if (x1, x3) is outside the particle.
+
+    Uses the sign of the dot product between the displacement vector and the
+    outward normal at the nearest boundary point. This nearest-neighbour
+    heuristic is reliable for convex and mildly star-shaped boundaries, but
+    unreliable for extreme concave superformula shapes.
+
+    Args:
+        x1: Observation x-coordinate (nm).
+        x3: Observation z-coordinate (nm).
+        f: (nn,) boundary x coordinates (nm).
+        g: (nn,) boundary z coordinates (nm).
+        df: (nn,) first derivative of f w.r.t. θ.
+        dg: (nn,) first derivative of g w.r.t. θ.
+
+    Returns:
+        True if the point lies outside the particle.
+    """
+    imin = np.argmin((x1 - f) ** 2 + (x3 - g) ** 2)
+    norm = -(x1 - f[imin]) * dg[imin] + (x3 - g[imin]) * df[imin]
+    return norm > 0.0
+
+
+# ---------------------------------------------------------------------------
+# Scattered field at arbitrary points
+# ---------------------------------------------------------------------------
+
+
+def eval_field(
+    ei: np.ndarray,
+    nn: int,
+    f: np.ndarray,
+    df: np.ndarray,
+    g: np.ndarray,
+    dg: np.ndarray,
+    delt: float | np.ndarray,
+    wnum: complex,
+    x_pts: np.ndarray,
+    z_pts: np.ndarray,
+    ri: complex | None = None,
+) -> np.ndarray:
+    """Evaluate the field at arbitrary (x, z) points.
+
+    Uses the BIE representation formula (Huygens principle) for exterior points.
+    For interior points, the same formula is used with the particle wavenumber
+    wn1 = ri * wnum when ri is provided; otherwise interior points return 0+0j.
+
+    Never evaluate on or very near the boundary: the representation-formula
+    integrand is near-singular there and degrades within roughly 2–3 boundary-
+    point spacings (~2π·rad/nn) of the surface. Keep observation points at
+    least ~5 spacings away.
+
+    Args:
+        ei: complex (2nn,) BIE solution vector (φ = ei[:nn], χ = ei[nn:]).
+        nn: Number of boundary points.
+        f: (nn,) boundary x coordinates (nm).
+        df: (nn,) first derivative of f w.r.t. θ.
+        g: (nn,) boundary z coordinates (nm).
+        dg: (nn,) first derivative of g w.r.t. θ.
+        delt: Quadrature θ-step.
+        wnum: Background wavenumber 2π/λ.
+        x_pts: (M,) observation x-coordinates (nm).
+        z_pts: (M,) observation z-coordinates (nm).
+        ri: Particle refractive index (relative to background). When provided,
+            interior points are evaluated using wn1 = ri * wnum. When None
+            (default), interior points return 0+0j.
+
+    Returns:
+        field: complex (M,) field E_y at each observation point (exterior
+            scattered field outside, interior field inside when ri is given).
+    """
+    x_pts = np.asarray(x_pts)
+    z_pts = np.asarray(z_pts)
+    n_pts = len(x_pts)
+    field = np.zeros(n_pts, dtype=complex)
+
+    wn1 = ri * wnum if ri is not None else None
+
+    for j in range(n_pts):
+        outside = _is_outside(x_pts[j], z_pts[j], f, g, df, dg)
+        if not outside and wn1 is None:
+            continue
+        xmf = x_pts[j] - f
+        zmg = z_pts[j] - g
+        dist = np.sqrt(xmf**2 + zmg**2)
+        arg2 = -dg * xmf + df * zmg
+        k = wnum if outside else wn1
+        arg1 = k * dist
+        sum_h = np.sum(
+            (k**2 * arg2 * hank1(arg1) / arg1 * ei[:nn] - hank0(arg1) * ei[nn:]) * delt
+        )
+        field[j] = (1j / 4.0) * sum_h
+
+    return field