Skip to content

Simulator backends

openlithohub.simulators is the vendor-neutral interface for lithography forward simulation. The bundled HopkinsSimulator is the reference implementation; CalibreSimulator and TachyonSimulator are commercial adapters that require the respective vendor toolchain on PATH and a license. Both support mock_mode (config.extra["mock_mode"] = True) for testing and CI without the commercial binary.

The module also re-exports load_source_intensity, load_zernike_coefficients, and zernike_phase_map so callers can drive the Hopkins forward model with measured-source maps and Zernike-pupil aberrations without reaching into _utils.optics.

Registry

openlithohub.simulators.registry

Open registry of simulator backends, keyed by string name.

Resist / Lithography Backend Selection Guide

This registry dispatches to several fidelity tiers of lithography simulation:

Lightweight built-in (default) :func:~openlithohub._utils.resist_model.apply_differentiable_resist provides a fast sigmoid-threshold resist with optional Gaussian acid diffusion. This is the default path when config.resist_backend == "ctr".

High-fidelity Dill/Mack exposure + development Available via the diffcfd_litho backend, which uses :class:~openlithohub.plugins.diffcfd_process.DiffCFDLithoSimulator. Requires the [diffcfd] extra. Models Beer-Lambert exposure with PAC bleaching (Dill) and solvent-dependent dissolution (Mack).

High-fidelity CAR/PEB resist Available via the diffnano resist backend, which uses :class:~openlithohub.plugins.diffnano_resist.DiffNanoResistAdapter. Requires the [diffnano] extra. Models acid diffusion, PEB diffusion, and sigmoid development with calibratable contrast.

Hopkins forward model The bundled :class:~openlithohub.simulators.hopkins_sim.HopkinsSimulator provides the core Hopkins/SOCS aerial-image simulation. DiffNano also ships diffnano.solvers.litho.HopkinsLithoModel (a simplified PSF model that is functionally equivalent to the Hopkins path here). For new work, prefer the core HopkinsSimulator which supports multiple illumination types and SOCS kernel caching.

See docs/resist_capability_matrix.md for the full capability comparison.

get_simulator(name, config=None)

Construct a simulator by name.

Parameters:

Name Type Description Default
name str

Registered backend name (e.g. "hopkins").

 required
config SimulatorConfig | None

Optional :class:SimulatorConfig.

 None

Raises:

Type Description
KeyError

If name is not registered and not a known plugin backend.
Source code in src/openlithohub/simulators/registry.py 
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
def get_simulator(
    name: str,
    config: SimulatorConfig | None = None,
) -> BaseSimulator:
    """Construct a simulator by name.

    Args:
        name: Registered backend name (e.g. ``"hopkins"``).
        config: Optional :class:`SimulatorConfig`.

    Raises:
        KeyError: If ``name`` is not registered and not a known plugin backend.
    """

    # Try plugin lazy-load first
    if name not in _REGISTRY and name in _PLUGIN_BACKENDS:
        extra = _PLUGIN_BACKENDS[name][0]
        if _try_load_plugin_backend(name):
            cls = _REGISTRY[name]
            return cls(config)
        raise KeyError(
            f"Backend {name!r} requires the [{extra}] extra.  "
            f"Install with:  pip install openlithohub[{extra}]"
        )

    try:
        cls = _REGISTRY[name]
    except KeyError as exc:
        raise KeyError(f"Unknown simulator {name!r}; registered: {list_simulators()}") from exc
    return cls(config)

list_simulators()

Return the names of all registered simulator backends, sorted.

Source code in src/openlithohub/simulators/registry.py 
124
125
126
127
def list_simulators() -> list[str]:
    """Return the names of all registered simulator backends, sorted."""

    return sorted(_REGISTRY)

register_simulator(name, cls)

Register a simulator class under name.

Overwrites any previous registration to keep the API simple — users that want defensiveness can guard with name in list_simulators().

Source code in src/openlithohub/simulators/registry.py 
85
86
87
88
89
90
91
92
def register_simulator(name: str, cls: type[BaseSimulator]) -> None:
    """Register a simulator class under ``name``.

    Overwrites any previous registration to keep the API simple — users
    that want defensiveness can guard with ``name in list_simulators()``.
    """

    _REGISTRY[name] = cls

describe_simulators()

Return (name, class) pairs for every registered simulator, sorted by name.

Used by the CLI to print human-readable backend listings without reaching into _REGISTRY from the outside.

Source code in src/openlithohub/simulators/registry.py 
146
147
148
149
150
151
152
153
def describe_simulators() -> list[tuple[str, type[BaseSimulator]]]:
    """Return ``(name, class)`` pairs for every registered simulator, sorted by name.

    Used by the CLI to print human-readable backend listings without
    reaching into ``_REGISTRY`` from the outside.
    """

    return sorted(_REGISTRY.items())

Base interface

openlithohub.simulators.base

Simulator base class and result/config dataclasses.

BaseSimulator

Bases: ABC

Abstract simulator backend.

A simulator maps mask -> SimulatorResult. The ABC makes no assumption about differentiability; callers that need gradients should pick a backend that documents support (e.g. :class:HopkinsSimulator).

Implementations should be cheap to construct — heavy state (kernel caches, tool licenses) belongs in :meth:prepare so that callers can decide when to pay the cost.

Source code in src/openlithohub/simulators/base.py 
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
class BaseSimulator(ABC):
    """Abstract simulator backend.

    A simulator maps ``mask -> SimulatorResult``. The ABC makes no
    assumption about differentiability; callers that need gradients
    should pick a backend that documents support (e.g.
    :class:`HopkinsSimulator`).

    Implementations should be cheap to construct — heavy state (kernel
    caches, tool licenses) belongs in :meth:`prepare` so that callers
    can decide when to pay the cost.
    """

    name: str = "base"
    differentiable: bool = False

    def __init__(self, config: SimulatorConfig | None = None) -> None:
        self.config = config or SimulatorConfig()

    def prepare(self) -> None:
        """Eagerly initialise backend state (kernels, tool sessions).

        Default no-op. Override when there is meaningful setup cost so
        that callers can amortise it across many simulate() calls.
        """

    def with_config(self, config: SimulatorConfig) -> BaseSimulator:
        """Return a sibling simulator using ``config``, sharing cached state where possible.

        Default builds a fresh instance via ``type(self)(config)``. Subclasses
        with expensive per-config setup (SOCS kernels, vendor sessions) should
        override to clone cheaply when the new config only differs in fields
        the cached state does not depend on (typically ``dose`` / ``threshold``).
        """
        return type(self)(config)

    @abstractmethod
    def simulate(self, mask: torch.Tensor) -> SimulatorResult:
        """Simulate the aerial image (and resist contour, if available).

        Args:
            mask: Real-valued mask. Shape ``(H, W)`` or ``(B, 1, H, W)``,
                values in ``[0, 1]``.

        Returns:
            A :class:`SimulatorResult` with the same spatial shape as
            ``mask``.
        """

    def __repr__(self) -> str:
        return f"{type(self).__name__}(name={self.name!r}, differentiable={self.differentiable})"

prepare()

Eagerly initialise backend state (kernels, tool sessions).

Default no-op. Override when there is meaningful setup cost so that callers can amortise it across many simulate() calls.

Source code in src/openlithohub/simulators/base.py 
152
153
154
155
156
157
def prepare(self) -> None:
    """Eagerly initialise backend state (kernels, tool sessions).

    Default no-op. Override when there is meaningful setup cost so
    that callers can amortise it across many simulate() calls.
    """

with_config(config)

Return a sibling simulator using config, sharing cached state where possible.

Default builds a fresh instance via type(self)(config). Subclasses with expensive per-config setup (SOCS kernels, vendor sessions) should override to clone cheaply when the new config only differs in fields the cached state does not depend on (typically dose / threshold).

Source code in src/openlithohub/simulators/base.py 
159
160
161
162
163
164
165
166
167
def with_config(self, config: SimulatorConfig) -> BaseSimulator:
    """Return a sibling simulator using ``config``, sharing cached state where possible.

    Default builds a fresh instance via ``type(self)(config)``. Subclasses
    with expensive per-config setup (SOCS kernels, vendor sessions) should
    override to clone cheaply when the new config only differs in fields
    the cached state does not depend on (typically ``dose`` / ``threshold``).
    """
    return type(self)(config)

simulate(mask) abstractmethod

Simulate the aerial image (and resist contour, if available).

Parameters:

Name Type Description Default
mask Tensor

Real-valued mask. Shape (H, W) or (B, 1, H, W), values in [0, 1].

 required

Returns:

Name Type Description
A SimulatorResult

class:SimulatorResult with the same spatial shape as
SimulatorResult

mask.
Source code in src/openlithohub/simulators/base.py 
169
170
171
172
173
174
175
176
177
178
179
180
@abstractmethod
def simulate(self, mask: torch.Tensor) -> SimulatorResult:
    """Simulate the aerial image (and resist contour, if available).

    Args:
        mask: Real-valued mask. Shape ``(H, W)`` or ``(B, 1, H, W)``,
            values in ``[0, 1]``.

    Returns:
        A :class:`SimulatorResult` with the same spatial shape as
        ``mask``.
    """

SimulatorConfig dataclass

Vendor-neutral simulator configuration.

Backends are free to ignore fields they don't model and to read extra options from :attr:extra. We deliberately keep the surface small — fields here must mean the same thing across every backend.

Attributes:

Name Type Description
wavelength_nm float

Exposure wavelength. 193 = ArF, 13.5 = EUV.
na float

Numerical aperture (image-side).
sigma float

Outer partial-coherence factor.
sigma_inner float

Inner sigma for annular/dipole/quasar (0 = circular).
pixel_size_nm float

Physical size of one mask pixel.
defocus_nm float

Defocus offset.
dose float

Linear dose multiplier.
threshold float

Resist intensity threshold for binarization (0–1 relative to dose). Backends that do not expose a threshold knob round at the model's nominal value.
resist_backend str

Select resist model. "ctr" = built-in CTR (bit-identical legacy), "diffnano" = DiffNano high-precision resist plugin. Plugin backends raise :class:~openlithohub.plugins.OptionalPluginError when not installed.
extra dict[str, Any]

Backend-specific options. Treated as opaque by the ABC.
Source code in src/openlithohub/simulators/base.py 
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
@dataclass(frozen=True)
class SimulatorConfig:
    """Vendor-neutral simulator configuration.

    Backends are free to ignore fields they don't model and to read
    extra options from :attr:`extra`. We deliberately keep the surface
    small — fields here must mean the same thing across every backend.

    Attributes:
        wavelength_nm: Exposure wavelength. 193 = ArF, 13.5 = EUV.
        na: Numerical aperture (image-side).
        sigma: Outer partial-coherence factor.
        sigma_inner: Inner sigma for annular/dipole/quasar (0 = circular).
        pixel_size_nm: Physical size of one mask pixel.
        defocus_nm: Defocus offset.
        dose: Linear dose multiplier.
        threshold: Resist intensity threshold for binarization (0–1
            relative to ``dose``). Backends that do not expose a
            threshold knob round at the model's nominal value.
        resist_backend: Select resist model. ``"ctr"`` = built-in CTR
            (bit-identical legacy), ``"diffnano"`` = DiffNano high-precision
            resist plugin.  Plugin backends raise
            :class:`~openlithohub.plugins.OptionalPluginError` when not
            installed.
        extra: Backend-specific options. Treated as opaque by the ABC.
    """

    wavelength_nm: float = WAVELENGTH_ARF_NM
    na: float = NA_IMMERSION
    sigma: float = SIGMA_OUTER_DEFAULT
    sigma_inner: float = SIGMA_INNER_DEFAULT
    pixel_size_nm: float = PIXEL_SIZE_NM_DEFAULT
    defocus_nm: float = DEFOCUS_NM_DEFAULT
    dose: float = DOSE_DEFAULT
    # Per Yang2023_LithoBench §3.2 (NeurIPS 2023),
    # threshold = 0.225 is the canonical resist cutoff used to score
    # ICCAD16 mask layouts on the simulated wafer image. Confidence A.
    threshold: float = THRESHOLD_ICCAD16
    # Acid diffusion length in nm. 0.0 (default) produces bit-identical
    # results to the legacy hard-threshold CTR model; positive values
    # enable gaussian acid diffusion before binarization.
    resist_diffusion_nm: float = RESIST_DIFFUSION_NM_DEFAULT
    # Base quencher concentration subtracted from acid field after
    # diffusion. 0.0 disables quencher neutralization.
    quencher: float = QUENCHER_DEFAULT
    # Resist model selector. "ctr" = built-in, "diffnano" = plugin.
    resist_backend: str = "ctr"
    extra: dict[str, Any] = field(default_factory=dict)

SimulatorResult dataclass

Output of a simulator forward pass.

Attributes:

Name Type Description
aerial Tensor

Aerial intensity image, same spatial shape as mask.
resist Tensor | None

Optional binarized resist contour (0/1) at :attr:SimulatorConfig.threshold. None if the backend does not produce one (callers should threshold aerial).
backend str

Name of the simulator that produced the result.
metadata dict[str, Any]

Free-form per-backend metadata (e.g. license info, vendor version, kernel count). Treated as opaque.
Source code in src/openlithohub/simulators/base.py 
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
@dataclass
class SimulatorResult:
    """Output of a simulator forward pass.

    Attributes:
        aerial: Aerial intensity image, same spatial shape as mask.
        resist: Optional binarized resist contour (0/1) at
            :attr:`SimulatorConfig.threshold`. ``None`` if the backend
            does not produce one (callers should threshold ``aerial``).
        backend: Name of the simulator that produced the result.
        metadata: Free-form per-backend metadata (e.g. license info,
            vendor version, kernel count). Treated as opaque.
    """

    aerial: torch.Tensor
    resist: torch.Tensor | None = None
    backend: str = ""
    metadata: dict[str, Any] = field(default_factory=dict)

    def _repr_html_(self) -> str:
        from openlithohub.jupyter._html import (
            kv_table,
            mask_thumbnail_png_b64,
            panel,
            png_b64_to_img_tag,
        )

        shape = "x".join(str(d) for d in tuple(self.aerial.shape))
        rows = [
            ("backend", self.backend or "—"),
            ("aerial shape", shape),
            ("aerial dtype", str(self.aerial.dtype)),
            ("resist", "yes" if self.resist is not None else "no"),
        ]
        for k, v in list(self.metadata.items())[:6]:
            rows.append((f"meta:{k}", str(v)))

        preview_tensor = self.resist if self.resist is not None else self.aerial
        preview = preview_tensor
        if preview_tensor is not None:
            preview = preview_tensor.detach().cpu()
            if preview.numel() > 0:
                lo, hi = float(preview.min()), float(preview.max())
                if hi > lo:
                    preview = (preview - lo) / (hi - lo)
        img_html = png_b64_to_img_tag(
            mask_thumbnail_png_b64(preview),
            alt=self.backend or "simulation",
        )
        body = (
            f'<div style="display:flex;gap:10px;align-items:flex-start;">'
            f'<div style="flex:0 0 auto;">{img_html}</div>'
            f'<div style="flex:1 1 auto;">{kv_table(rows)}</div>'
            f"</div>"
        )
        return panel(title="SimulatorResult", header_html="", body_html=body)

Hopkins reference adapter

openlithohub.simulators.hopkins_sim

Hopkins/SOCS simulator adapter — the bundled reference backend.

HopkinsSimulator

Bases: BaseSimulator

Differentiable Hopkins/SOCS simulator.

Wraps :func:openlithohub._utils.hopkins.simulate_aerial_image_hopkins. The full forward pass is auto-differentiable, so this adapter is the right choice when used as a training-loop oracle for ILT or AI-OPC.

Backend-specific options read from config.extra:

  • illumination (circular | annular | dipole | quasar) — source shape, default circular.
  • num_kernels (int) — SOCS truncation order, default 24 (per Yang2023_LithoBench §3.2 / Table II — the reference SOCS decomposition for ICCAD16 evaluation).
  • dipole_angle_deg, pole_opening_deg — pole geometry for dipole/quasar.
Source code in src/openlithohub/simulators/hopkins_sim.py 
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
class HopkinsSimulator(BaseSimulator):
    """Differentiable Hopkins/SOCS simulator.

    Wraps :func:`openlithohub._utils.hopkins.simulate_aerial_image_hopkins`.
    The full forward pass is auto-differentiable, so this adapter is the
    right choice when used as a training-loop oracle for ILT or AI-OPC.

    Backend-specific options read from ``config.extra``:

    * ``illumination`` (``circular`` | ``annular`` | ``dipole`` |
      ``quasar``) — source shape, default ``circular``.
    * ``num_kernels`` (int) — SOCS truncation order, default 24
      (per Yang2023_LithoBench §3.2 / Table II — the reference SOCS
      decomposition for ICCAD16 evaluation).
    * ``dipole_angle_deg``, ``pole_opening_deg`` — pole geometry for
      dipole/quasar.
    """

    name = "hopkins"
    differentiable = True

    def __init__(self, config: SimulatorConfig | None = None) -> None:
        super().__init__(config)
        self._hparams = self._build_hparams(self.config)

    def with_config(self, config: SimulatorConfig) -> HopkinsSimulator:
        """Clone, reusing cached SOCS kernels when only dose/threshold changed.

        SOCS kernel construction depends on optical fields
        (wavelength/NA/sigma/illumination/defocus/pixel_size_nm/num_kernels).
        When those are unchanged, we can hand the new sibling our pre-built
        :class:`HopkinsParams` instead of recomputing.
        """
        sibling = type(self).__new__(type(self))
        BaseSimulator.__init__(sibling, config)
        if self._hparams_match(config):
            sibling._hparams = self._hparams
        else:
            sibling._hparams = self._build_hparams(config)
        return sibling

    def _hparams_match(self, other: SimulatorConfig) -> bool:
        a, b = self.config, other
        if (
            a.wavelength_nm != b.wavelength_nm
            or a.na != b.na
            or a.sigma != b.sigma
            or a.sigma_inner != b.sigma_inner
            or a.pixel_size_nm != b.pixel_size_nm
            or a.defocus_nm != b.defocus_nm
        ):
            return False
        ax = a.extra or {}
        bx = b.extra or {}
        keys = ("num_kernels", "illumination", "dipole_angle_deg", "pole_opening_deg")
        return all(ax.get(k) == bx.get(k) for k in keys)

    @staticmethod
    def _build_hparams(config: SimulatorConfig) -> HopkinsParams:
        extra = config.extra or {}
        return HopkinsParams(
            wavelength_nm=config.wavelength_nm,
            na=config.na,
            sigma=config.sigma,
            sigma_inner=config.sigma_inner,
            pixel_size_nm=config.pixel_size_nm,
            num_kernels=int(extra.get("num_kernels", NUM_KERNELS_DEFAULT)),
            illumination=extra.get("illumination", "circular"),
            dipole_angle_deg=float(extra.get("dipole_angle_deg", 0.0)),
            pole_opening_deg=float(extra.get("pole_opening_deg", POLE_OPENING_DEG_DEFAULT)),
            defocus_nm=config.defocus_nm,
        )

    def simulate(self, mask: torch.Tensor) -> SimulatorResult:
        aerial = simulate_aerial_image_hopkins(
            mask,
            params=self._hparams,
            dose=self.config.dose,
        )
        # Issue #52: do NOT scale the threshold by dose. `simulate_aerial_image_hopkins`
        # already multiplies the aerial by dose; if we also multiply the threshold by
        # dose, the comparison `aerial >= threshold * dose` reduces to
        # `aerial_unit >= threshold_unit` — i.e. dose is fully cancelled and the
        # resist contour is invariant under dose. The physical convention is the
        # opposite: changing dose changes the resist contour at a *fixed* clearing
        # threshold, since the resist's clearing intensity is a chemical
        # invariant. PW dose corners, stochastic / Monte-Carlo dose jitter, and
        # PVB dose-axis variation all relied on this.
        threshold = self.config.threshold
        # Opt-in acid diffusion: when resist_diffusion_nm > 0 or quencher > 0,
        # blur the aerial image (proportional to photoacid concentration) and
        # subtract quencher before binarization. Both default to 0.0, which
        # skips this block entirely for bit-identical legacy behavior.
        if self.config.resist_diffusion_nm > 0.0 or self.config.quencher > 0.0:
            sigma_px = self.config.resist_diffusion_nm / max(self.config.pixel_size_nm, 1e-6)
            if sigma_px > 0.1:
                aerial = _gaussian_diffuse(aerial, sigma_px)
            aerial = (aerial - self.config.quencher).clamp(min=0.0)

        # Resist backend dispatch: "ctr" = built-in, "diffnano" = plugin.
        if self.config.resist_backend == "diffnano":
            resist = self._apply_diffnano_resist(aerial)
        else:
            resist = (aerial >= threshold).to(aerial.dtype)

        return SimulatorResult(
            aerial=aerial,
            resist=resist,
            backend=self.name,
            metadata={
                "illumination": self._hparams.illumination,
                "num_kernels": self._hparams.num_kernels,
                "differentiable": True,
                "resist_backend": self.config.resist_backend,
            },
        )

    def _apply_diffnano_resist(self, aerial: torch.Tensor) -> torch.Tensor:
        from openlithohub.plugins.diffnano_resist import DiffNanoResistAdapter

        adapter = DiffNanoResistAdapter(
            acid_diffusion_length_nm=self.config.resist_diffusion_nm or ACID_DIFFUSION_LENGTH_NM,
            threshold_dose=self.config.threshold,
            pixel_size_nm=self.config.pixel_size_nm,
        )
        result = adapter(aerial)
        return (result >= 0.5).to(aerial.dtype)

with_config(config)

Clone, reusing cached SOCS kernels when only dose/threshold changed.

SOCS kernel construction depends on optical fields (wavelength/NA/sigma/illumination/defocus/pixel_size_nm/num_kernels). When those are unchanged, we can hand the new sibling our pre-built :class:HopkinsParams instead of recomputing.

Source code in src/openlithohub/simulators/hopkins_sim.py 
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
def with_config(self, config: SimulatorConfig) -> HopkinsSimulator:
    """Clone, reusing cached SOCS kernels when only dose/threshold changed.

    SOCS kernel construction depends on optical fields
    (wavelength/NA/sigma/illumination/defocus/pixel_size_nm/num_kernels).
    When those are unchanged, we can hand the new sibling our pre-built
    :class:`HopkinsParams` instead of recomputing.
    """
    sibling = type(self).__new__(type(self))
    BaseSimulator.__init__(sibling, config)
    if self._hparams_match(config):
        sibling._hparams = self._hparams
    else:
        sibling._hparams = self._build_hparams(config)
    return sibling

Commercial adapters

openlithohub.simulators.commercial

Commercial simulator adapter protocol and shared utilities.

Defines :class:CommercialSimulatorAdapter, the protocol that every vendor-specific adapter (Tachyon, Calibre, …) must satisfy. Provides common machinery for pre-flight checks, file I/O, and mock mode so each concrete adapter stays thin.

CommercialSimulatorAdapter

Bases: Protocol

Protocol shared by all commercial simulator adapters.

Concrete adapters (Tachyon, Calibre) must provide: - :meth:preflight — verify toolchain + license - :meth:simulate — forward simulation - :attr:mock_mode — whether the adapter runs without the real tool

Source code in src/openlithohub/simulators/commercial.py 
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
@runtime_checkable
class CommercialSimulatorAdapter(Protocol):
    """Protocol shared by all commercial simulator adapters.

    Concrete adapters (Tachyon, Calibre) must provide:
    - :meth:`preflight` — verify toolchain + license
    - :meth:`simulate`  — forward simulation
    - :attr:`mock_mode`  — whether the adapter runs without the real tool
    """

    mock_mode: bool

    def preflight(self) -> PreflightStatus:
        """Check that the toolchain binary exists and a license is reachable."""
        ...

    def simulate(self, mask: torch.Tensor) -> SimulatorResult: ...

preflight()

Check that the toolchain binary exists and a license is reachable.

Source code in src/openlithohub/simulators/commercial.py 
48
49
50
def preflight(self) -> PreflightStatus:
    """Check that the toolchain binary exists and a license is reachable."""
    ...

PreflightStatus dataclass

Source code in src/openlithohub/simulators/commercial.py 
28
29
30
31
32
33
@dataclass(frozen=True)
class PreflightStatus:
    ok: bool
    tool_found: bool = False
    license_ok: bool = False
    messages: tuple[str, ...] = ()

ToolchainError

Bases: RuntimeError

Raised when a required commercial toolchain is not available.

Source code in src/openlithohub/simulators/commercial.py 
24
25
class ToolchainError(RuntimeError):
    """Raised when a required commercial toolchain is not available."""

openlithohub.simulators.calibre

Siemens EDA Calibre nmOPC simulator adapter.

Real Calibre integration requires the Calibre toolchain on PATH plus a valid license file. The adapter supports mock_mode for testing and CI.

CalibreSimulator

Bases: BaseSimulator

Adapter for Siemens EDA Calibre nmOPC.

config.extra should carry:

  • calibre_home (str) -- install root containing bin/calibre.
  • runset (str) -- path to the SVRF runset to execute.
  • layer_map (dict[str, int], optional) -- maps OpenLithoHub layer names to Calibre layer numbers.
  • license_server (str, optional) -- for non-default flexlm setups.
  • mock_mode (bool, optional) -- run in mock mode without the real toolchain. Defaults to False.
Source code in src/openlithohub/simulators/calibre.py 
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
class CalibreSimulator(BaseSimulator):
    """Adapter for Siemens EDA Calibre nmOPC.

    ``config.extra`` should carry:

    * ``calibre_home`` (str) -- install root containing ``bin/calibre``.
    * ``runset`` (str) -- path to the SVRF runset to execute.
    * ``layer_map`` (dict[str, int], optional) -- maps OpenLithoHub layer
      names to Calibre layer numbers.
    * ``license_server`` (str, optional) -- for non-default flexlm setups.
    * ``mock_mode`` (bool, optional) -- run in mock mode without the real
      toolchain. Defaults to ``False``.
    """

    name = "calibre"
    differentiable = False

    def __init__(self, config: SimulatorConfig | None = None) -> None:
        super().__init__(config)
        self.mock_mode: bool = bool(self.config.extra.get("mock_mode", False))
        if not self.mock_mode:
            self._validate_config()

    def _validate_config(self) -> None:
        extra = self.config.extra
        for key in ("calibre_home", "runset"):
            if key not in extra:
                raise ValueError(
                    f"CalibreSimulator requires config.extra[{key!r}]; "
                    f"got keys={sorted(extra.keys())}"
                )

    def preflight(self) -> PreflightStatus:
        """Check Calibre binary and license availability."""
        if self.mock_mode:
            return PreflightStatus(ok=True, tool_found=True, license_ok=True)

        extra = self.config.extra
        home = extra.get("calibre_home", "")
        search = (str(Path(home) / "bin"),) if home else ()
        binary = _find_binary(_CALIBRE_BIN, search)
        tool_found = binary is not None
        license_ok = _check_license_env(_LICENSE_VARS)
        messages: list[str] = []
        if not tool_found:
            messages.append(
                f"Cannot find {_CALIBRE_BIN} on PATH or in {home}/bin. "
                "Install Calibre or set calibre_home in config.extra."
            )
        if not license_ok:
            messages.append(
                "No Calibre license detected. Set MGLS_LICENSE_FILE or "
                "LM_LICENSE_FILE environment variable."
            )
        return PreflightStatus(
            ok=tool_found and license_ok,
            tool_found=tool_found,
            license_ok=license_ok,
            messages=tuple(messages),
        )

    def simulate(self, mask: torch.Tensor) -> SimulatorResult:
        """Run Calibre nmOPC forward simulation.

        In mock mode, produces a threshold-based approximation that
        simulates basic OPC behaviour without the commercial tool.
        """
        spatial_shape = mask.shape[-2:]
        if self.mock_mode:
            return self._mock_simulate(mask)

        status = self.preflight()
        if not status.ok:
            raise ToolchainError("Calibre preflight failed: " + "; ".join(status.messages))

        with tempfile.TemporaryDirectory(prefix="calibre_") as tmpdir:
            mask_file = Path(tmpdir) / "mask.txt"
            write_mask_gdsii(mask, mask_file, self.config.pixel_size_nm / 1000.0)
            output_file = Path(tmpdir) / "aerial.txt"
            cmd = self._build_command(mask_file, output_file)
            run_subprocess(cmd, cwd=tmpdir)
            if not output_file.exists():
                raise ToolchainError(
                    "Calibre completed but produced no output file. Check runset configuration."
                )
            aerial = read_aerial_image(output_file, (int(spatial_shape[0]), int(spatial_shape[1])))

        return SimulatorResult(
            aerial=aerial,
            resist=(aerial > self.config.threshold).float(),
            backend=self.name,
            metadata={"mock": False, "runset": self.config.extra.get("runset", "")},
        )

    def _build_command(self, mask_file: Path, output_file: Path) -> list[str]:
        extra = self.config.extra
        home = extra["calibre_home"]
        binary = _find_binary(_CALIBRE_BIN, (str(Path(home) / "bin"),))
        if binary is None:
            binary = _CALIBRE_BIN
        runset = extra["runset"]
        return [
            binary,
            "-batch",
            "-runset",
            runset,
            "-mask",
            str(mask_file),
            "-output",
            str(output_file),
        ]

    def _mock_simulate(self, mask: torch.Tensor) -> SimulatorResult:
        """Produce a synthetic aerial image using blur + edge erosion."""
        import torch.nn.functional as functional

        mask_2d = mask.detach().cpu().float()
        if mask_2d.ndim == 4:
            mask_2d = mask_2d.squeeze(0).squeeze(0)
        elif mask_2d.ndim == 3:
            mask_2d = mask_2d.squeeze(0)

        kernel_size = 7
        sigma = 1.5
        coords = torch.arange(kernel_size, dtype=torch.float32) - kernel_size // 2
        gauss_1d = torch.exp(-(coords**2) / (2 * sigma**2))
        gauss_1d = gauss_1d / gauss_1d.sum()
        kernel = gauss_1d[:, None] * gauss_1d[None, :]
        kernel = kernel.unsqueeze(0).unsqueeze(0)

        padded = mask_2d.unsqueeze(0).unsqueeze(0)
        aerial = functional.conv2d(padded, kernel, padding=kernel_size // 2).squeeze(0).squeeze(0)

        aerial = aerial * self.config.dose
        aerial = aerial.clamp(0.0, 1.0)

        if mask.ndim == 4:
            aerial = aerial.unsqueeze(0).unsqueeze(0)
        elif mask.ndim == 3:
            aerial = aerial.unsqueeze(0)

        resist = (aerial > self.config.threshold).float()
        return SimulatorResult(
            aerial=aerial,
            resist=resist,
            backend=self.name,
            metadata={"mock": True},
        )

preflight()

Check Calibre binary and license availability.

Source code in src/openlithohub/simulators/calibre.py 
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
def preflight(self) -> PreflightStatus:
    """Check Calibre binary and license availability."""
    if self.mock_mode:
        return PreflightStatus(ok=True, tool_found=True, license_ok=True)

    extra = self.config.extra
    home = extra.get("calibre_home", "")
    search = (str(Path(home) / "bin"),) if home else ()
    binary = _find_binary(_CALIBRE_BIN, search)
    tool_found = binary is not None
    license_ok = _check_license_env(_LICENSE_VARS)
    messages: list[str] = []
    if not tool_found:
        messages.append(
            f"Cannot find {_CALIBRE_BIN} on PATH or in {home}/bin. "
            "Install Calibre or set calibre_home in config.extra."
        )
    if not license_ok:
        messages.append(
            "No Calibre license detected. Set MGLS_LICENSE_FILE or "
            "LM_LICENSE_FILE environment variable."
        )
    return PreflightStatus(
        ok=tool_found and license_ok,
        tool_found=tool_found,
        license_ok=license_ok,
        messages=tuple(messages),
    )

simulate(mask)

Run Calibre nmOPC forward simulation.

In mock mode, produces a threshold-based approximation that simulates basic OPC behaviour without the commercial tool.

Source code in src/openlithohub/simulators/calibre.py 
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
def simulate(self, mask: torch.Tensor) -> SimulatorResult:
    """Run Calibre nmOPC forward simulation.

    In mock mode, produces a threshold-based approximation that
    simulates basic OPC behaviour without the commercial tool.
    """
    spatial_shape = mask.shape[-2:]
    if self.mock_mode:
        return self._mock_simulate(mask)

    status = self.preflight()
    if not status.ok:
        raise ToolchainError("Calibre preflight failed: " + "; ".join(status.messages))

    with tempfile.TemporaryDirectory(prefix="calibre_") as tmpdir:
        mask_file = Path(tmpdir) / "mask.txt"
        write_mask_gdsii(mask, mask_file, self.config.pixel_size_nm / 1000.0)
        output_file = Path(tmpdir) / "aerial.txt"
        cmd = self._build_command(mask_file, output_file)
        run_subprocess(cmd, cwd=tmpdir)
        if not output_file.exists():
            raise ToolchainError(
                "Calibre completed but produced no output file. Check runset configuration."
            )
        aerial = read_aerial_image(output_file, (int(spatial_shape[0]), int(spatial_shape[1])))

    return SimulatorResult(
        aerial=aerial,
        resist=(aerial > self.config.threshold).float(),
        backend=self.name,
        metadata={"mock": False, "runset": self.config.extra.get("runset", "")},
    )

openlithohub.simulators.tachyon

ASML Brion Tachyon simulator adapter.

Real Tachyon integration requires the Tachyon toolchain on PATH plus a license. The adapter supports a mock_mode that produces plausible synthetic results for testing and CI.

TachyonSimulator

Bases: BaseSimulator

Adapter for ASML Brion Tachyon lithography simulator.

config.extra should carry:

  • tachyon_home (str) -- install root containing the Tachyon binary.
  • recipe (str) -- path to the .tcl recipe to execute.
  • layer_map (dict[str, int], optional) -- OpenLithoHub layer to Tachyon layer mapping.
  • mock_mode (bool, optional) -- run in mock mode without the real toolchain. Defaults to False.
Source code in src/openlithohub/simulators/tachyon.py 
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
class TachyonSimulator(BaseSimulator):
    """Adapter for ASML Brion Tachyon lithography simulator.

    ``config.extra`` should carry:

    * ``tachyon_home`` (str) -- install root containing the Tachyon binary.
    * ``recipe`` (str) -- path to the ``.tcl`` recipe to execute.
    * ``layer_map`` (dict[str, int], optional) -- OpenLithoHub layer to
      Tachyon layer mapping.
    * ``mock_mode`` (bool, optional) -- run in mock mode without the real
      toolchain. Defaults to ``False``.
    """

    name = "tachyon"
    differentiable = False

    def __init__(self, config: SimulatorConfig | None = None) -> None:
        super().__init__(config)
        self.mock_mode: bool = bool(self.config.extra.get("mock_mode", False))
        if not self.mock_mode:
            self._validate_config()

    def _validate_config(self) -> None:
        extra = self.config.extra
        for key in ("tachyon_home", "recipe"):
            if key not in extra:
                raise ValueError(
                    f"TachyonSimulator requires config.extra[{key!r}]; "
                    f"got keys={sorted(extra.keys())}"
                )

    def preflight(self) -> PreflightStatus:
        """Check Tachyon binary and license availability."""
        if self.mock_mode:
            return PreflightStatus(ok=True, tool_found=True, license_ok=True)

        extra = self.config.extra
        home = extra.get("tachyon_home", "")
        search = (str(Path(home) / "bin"),) if home else ()
        binary = _find_binary(_TACHYON_BIN, search)
        tool_found = binary is not None
        license_ok = _check_license_env(_LICENSE_VARS)
        messages: list[str] = []
        if not tool_found:
            messages.append(
                f"Cannot find {_TACHYON_BIN} on PATH or in {home}/bin. "
                "Install Tachyon or set tachyon_home in config.extra."
            )
        if not license_ok:
            messages.append(
                "No Tachyon license detected. Set TACHYON_LICENSE or "
                "LM_LICENSE_FILE environment variable."
            )
        return PreflightStatus(
            ok=tool_found and license_ok,
            tool_found=tool_found,
            license_ok=license_ok,
            messages=tuple(messages),
        )

    def simulate(self, mask: torch.Tensor) -> SimulatorResult:
        """Run Tachyon forward simulation.

        In mock mode, produces a Gaussian-blurred approximation of the mask
        that mimics a low-fidelity aerial image without requiring the
        commercial tool.
        """
        spatial_shape = mask.shape[-2:]
        if self.mock_mode:
            return self._mock_simulate(mask)

        status = self.preflight()
        if not status.ok:
            raise ToolchainError("Tachyon preflight failed: " + "; ".join(status.messages))

        with tempfile.TemporaryDirectory(prefix="tachyon_") as tmpdir:
            mask_file = Path(tmpdir) / "mask.txt"
            write_mask_gdsii(mask, mask_file, self.config.pixel_size_nm / 1000.0)
            output_file = Path(tmpdir) / "aerial.txt"
            cmd = self._build_command(mask_file, output_file)
            run_subprocess(cmd, cwd=tmpdir)
            if not output_file.exists():
                raise ToolchainError(
                    "Tachyon completed but produced no output file. Check recipe configuration."
                )
            aerial = read_aerial_image(output_file, (int(spatial_shape[0]), int(spatial_shape[1])))

        return SimulatorResult(
            aerial=aerial,
            resist=(aerial > self.config.threshold).float(),
            backend=self.name,
            metadata={"mock": False, "recipe": self.config.extra.get("recipe", "")},
        )

    def _build_command(self, mask_file: Path, output_file: Path) -> list[str]:
        extra = self.config.extra
        home = extra["tachyon_home"]
        binary = _find_binary(_TACHYON_BIN, (str(Path(home) / "bin"),))
        if binary is None:
            binary = _TACHYON_BIN
        recipe = extra["recipe"]
        return [
            binary,
            "-recipe",
            recipe,
            "-mask",
            str(mask_file),
            "-output",
            str(output_file),
        ]

    def _mock_simulate(self, mask: torch.Tensor) -> SimulatorResult:
        """Produce a synthetic aerial image using a simple Gaussian blur."""
        import torch.nn.functional as functional

        mask_2d = mask.detach().cpu().float()
        if mask_2d.ndim == 4:
            mask_2d = mask_2d.squeeze(0).squeeze(0)
        elif mask_2d.ndim == 3:
            mask_2d = mask_2d.squeeze(0)

        kernel_size = 9
        sigma = 2.0
        coords = torch.arange(kernel_size, dtype=torch.float32) - kernel_size // 2
        gauss_1d = torch.exp(-(coords**2) / (2 * sigma**2))
        gauss_1d = gauss_1d / gauss_1d.sum()
        kernel = gauss_1d[:, None] * gauss_1d[None, :]
        kernel = kernel.unsqueeze(0).unsqueeze(0)

        padded = mask_2d.unsqueeze(0).unsqueeze(0)
        aerial = functional.conv2d(padded, kernel, padding=kernel_size // 2).squeeze(0).squeeze(0)

        # Clamp to [0, 1] and apply dose
        aerial = aerial * self.config.dose
        aerial = aerial.clamp(0.0, 1.0)

        # Restore batch dimensions if input was batched
        if mask.ndim == 4:
            aerial = aerial.unsqueeze(0).unsqueeze(0)
        elif mask.ndim == 3:
            aerial = aerial.unsqueeze(0)

        resist = (aerial > self.config.threshold).float()
        return SimulatorResult(
            aerial=aerial,
            resist=resist,
            backend=self.name,
            metadata={"mock": True},
        )

preflight()

Check Tachyon binary and license availability.

Source code in src/openlithohub/simulators/tachyon.py 
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
def preflight(self) -> PreflightStatus:
    """Check Tachyon binary and license availability."""
    if self.mock_mode:
        return PreflightStatus(ok=True, tool_found=True, license_ok=True)

    extra = self.config.extra
    home = extra.get("tachyon_home", "")
    search = (str(Path(home) / "bin"),) if home else ()
    binary = _find_binary(_TACHYON_BIN, search)
    tool_found = binary is not None
    license_ok = _check_license_env(_LICENSE_VARS)
    messages: list[str] = []
    if not tool_found:
        messages.append(
            f"Cannot find {_TACHYON_BIN} on PATH or in {home}/bin. "
            "Install Tachyon or set tachyon_home in config.extra."
        )
    if not license_ok:
        messages.append(
            "No Tachyon license detected. Set TACHYON_LICENSE or "
            "LM_LICENSE_FILE environment variable."
        )
    return PreflightStatus(
        ok=tool_found and license_ok,
        tool_found=tool_found,
        license_ok=license_ok,
        messages=tuple(messages),
    )

simulate(mask)

Run Tachyon forward simulation.

In mock mode, produces a Gaussian-blurred approximation of the mask that mimics a low-fidelity aerial image without requiring the commercial tool.

Source code in src/openlithohub/simulators/tachyon.py 
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
def simulate(self, mask: torch.Tensor) -> SimulatorResult:
    """Run Tachyon forward simulation.

    In mock mode, produces a Gaussian-blurred approximation of the mask
    that mimics a low-fidelity aerial image without requiring the
    commercial tool.
    """
    spatial_shape = mask.shape[-2:]
    if self.mock_mode:
        return self._mock_simulate(mask)

    status = self.preflight()
    if not status.ok:
        raise ToolchainError("Tachyon preflight failed: " + "; ".join(status.messages))

    with tempfile.TemporaryDirectory(prefix="tachyon_") as tmpdir:
        mask_file = Path(tmpdir) / "mask.txt"
        write_mask_gdsii(mask, mask_file, self.config.pixel_size_nm / 1000.0)
        output_file = Path(tmpdir) / "aerial.txt"
        cmd = self._build_command(mask_file, output_file)
        run_subprocess(cmd, cwd=tmpdir)
        if not output_file.exists():
            raise ToolchainError(
                "Tachyon completed but produced no output file. Check recipe configuration."
            )
        aerial = read_aerial_image(output_file, (int(spatial_shape[0]), int(spatial_shape[1])))

    return SimulatorResult(
        aerial=aerial,
        resist=(aerial > self.config.threshold).float(),
        backend=self.name,
        metadata={"mock": False, "recipe": self.config.extra.get("recipe", "")},
    )

Measured-source / Zernike-pupil I/O

openlithohub._utils.optics

Standardized I/O for measured sources and pupil aberrations.

Hopkins / SOCS already accepts parametric sources (circular, annular, dipole, quasar) and a clean defocus-only pupil. Real production OPC needs more:

  • Measured / freeform source intensity — a TIFF or PNG dumped from the scanner illuminator, or a custom shape designed by SMO. This is loaded as a 2-D [N, N] array on normalized pupil coordinates (σx, σy) ∈ [-1, 1].
  • Pupil aberrations as Zernike coefficients — typically tens of Zernikes (Z2..Z37 or higher) measured on the scanner. We parse a small text/JSON/CSV file mapping Noll-indexed terms → coefficients in waves of OPD, and synthesize a phase map on the same normalized pupil grid.

Both outputs are plain torch.Tensor so they can be plugged into a custom Hopkins / SOCS run without further conversion. These three functions are re-exported from :mod:openlithohub.simulators for discoverability — the bundled :class:HopkinsSimulator does not yet consume them through SimulatorConfig.extra; users who need measured-source or Zernike-pupil pathing currently do so by calling :func:openlithohub._utils.hopkins.simulate_aerial_image_hopkins directly with the loaded tensor injected into a custom params object. Wiring through the public HopkinsSimulator is roadmap (item #65 in the bug-triage list once the API knobs are settled).

Coordinate convention: normalized pupil coordinates run from -1 to +1 across the diameter, with the unit circle being the NA-defined edge. The center pixel is at (σx, σy) = (0, 0). For a square N x N grid this places the center at index (N-1) / 2.

load_source_intensity(path, *, grid_size=None, normalize=True, device='cpu')

Load a measured source intensity image as a square [N, N] tensor.

Supports any format Pillow can read: TIFF (16-bit OK), PNG, BMP, etc. The image is converted to float32 in the range [0, ∞), optionally resized to grid_size (bilinear), and optionally normalized so the sum is 1 (which is what Hopkins J(f) expects).

Parameters:

Name Type Description Default
path str | Path

Image file.

 required
grid_size int | None

If given, resize to [grid_size, grid_size] with bilinear interpolation. If None, keep the native shape but require it to be square.

 None
normalize bool

If True (default), rescale so the source sums to 1.

 True
device str | device

Torch device for the output tensor.

 'cpu'

Returns:

Type Description
Tensor

Float32 tensor on device of shape [N, N] in normalized
Tensor

pupil-coordinate layout (origin at the geometric center).
Source code in src/openlithohub/_utils/optics.py 
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
def load_source_intensity(
    path: str | Path,
    *,
    grid_size: int | None = None,
    normalize: bool = True,
    device: str | torch.device = "cpu",
) -> torch.Tensor:
    """Load a measured source intensity image as a square ``[N, N]`` tensor.

    Supports any format Pillow can read: TIFF (16-bit OK), PNG, BMP, etc.
    The image is converted to float32 in the range ``[0, ∞)``, optionally
    resized to ``grid_size`` (bilinear), and optionally normalized so the
    sum is 1 (which is what Hopkins ``J(f)`` expects).

    Args:
        path: Image file.
        grid_size: If given, resize to ``[grid_size, grid_size]`` with
            bilinear interpolation. If ``None``, keep the native shape
            but require it to be square.
        normalize: If True (default), rescale so the source sums to 1.
        device: Torch device for the output tensor.

    Returns:
        Float32 tensor on ``device`` of shape ``[N, N]`` in normalized
        pupil-coordinate layout (origin at the geometric center).
    """
    try:
        from PIL import Image
    except ImportError as e:
        raise ImportError(
            "Pillow is required to load source intensity images. Install with: pip install Pillow"
        ) from e

    p = Path(path)
    if not p.exists():
        raise FileNotFoundError(f"Source intensity image not found: {p}")

    with Image.open(p) as img:
        # 'F' = 32-bit float, preserves dynamic range from 16-bit TIFFs etc.
        arr = torch.from_numpy(_pil_to_float32(img).copy())

    if arr.ndim != 2:
        raise ValueError(f"Source intensity must be 2-D (grayscale); got shape {tuple(arr.shape)}")

    if grid_size is None:
        if arr.shape[0] != arr.shape[1]:
            raise ValueError(
                f"Source intensity must be square when grid_size is unset; got {tuple(arr.shape)}"
            )
    else:
        arr = (
            torch.nn.functional.interpolate(
                arr.unsqueeze(0).unsqueeze(0),
                size=(grid_size, grid_size),
                mode="bilinear",
                align_corners=False,
            )
            .squeeze(0)
            .squeeze(0)
        )

    arr = arr.clamp(min=0.0)
    if normalize:
        total = arr.sum()
        if total <= 0:
            raise ValueError("Source intensity has total zero/negative — cannot normalize.")
        arr = arr / total

    return arr.to(device=device, dtype=torch.float32).contiguous()

load_zernike_coefficients(path)

Parse a Zernike coefficient file → {noll_index: coeff_in_waves}.

Three formats are supported, dispatched by extension:

  • .json — flat object {"4": 0.05, "11": -0.02, ...} or a nested form {"zernikes": {"4": 0.05, ...}}.
  • .csv — header row required, columns noll and coeff (case-insensitive). Other columns are ignored.
  • .txt — whitespace-separated noll coeff pairs, # comments.

Coefficients are interpreted as waves of OPD (the scanner / Synopsys convention). Z1 (piston) is silently dropped — it has no optical effect and many vendor tools include it as a sanity column.

Source code in src/openlithohub/_utils/optics.py 
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
def load_zernike_coefficients(path: str | Path) -> dict[int, float]:
    """Parse a Zernike coefficient file → ``{noll_index: coeff_in_waves}``.

    Three formats are supported, dispatched by extension:

    * ``.json`` — flat object ``{"4": 0.05, "11": -0.02, ...}`` or a
      nested form ``{"zernikes": {"4": 0.05, ...}}``.
    * ``.csv`` — header row required, columns ``noll`` and ``coeff``
      (case-insensitive). Other columns are ignored.
    * ``.txt`` — whitespace-separated ``noll coeff`` pairs, ``#`` comments.

    Coefficients are interpreted as **waves of OPD** (the scanner /
    Synopsys convention). Z1 (piston) is silently dropped — it has no
    optical effect and many vendor tools include it as a sanity column.
    """
    p = Path(path)
    if not p.exists():
        raise FileNotFoundError(f"Zernike file not found: {p}")

    suffix = p.suffix.lower()
    if suffix == ".json":
        raw = _zernike_from_json(p)
    elif suffix == ".csv":
        raw = _zernike_from_csv(p)
    elif suffix in (".txt", ".dat", ".zer"):
        raw = _zernike_from_txt(p)
    else:
        raise ValueError(f"Unsupported Zernike format: {suffix!r}. Use .json, .csv, or .txt.")

    out: dict[int, float] = {}
    for noll, coeff in raw.items():
        if noll == 1:
            continue
        if noll < 1:
            raise ValueError(f"Noll indices are 1-based; got {noll}.")
        if noll not in _NOLL_TO_NM:
            raise ValueError(
                f"Noll index {noll} is beyond the supported range "
                f"(1..{max(_NOLL_TO_NM)}); add it to _NOLL_TO_NM if needed."
            )
        out[noll] = coeff
    return out

zernike_phase_map(coeffs, grid_size, *, device='cpu')

Synthesize a pupil OPD map from Noll-indexed Zernike coefficients.

Returns a real [N, N] tensor of optical path difference in waves (multiply by 2π to get phase in radians, or by the wavelength to get OPD in nm). Outside the unit pupil the map is set to 0.

Parameters:

Name Type Description Default
coeffs dict[int, float]

{noll_index: coeff_in_waves} (e.g. from :func:load_zernike_coefficients).

 required
grid_size int

Output grid edge N.

 required
device str | device

Torch device.

 'cpu'
Source code in src/openlithohub/_utils/optics.py 
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
def zernike_phase_map(
    coeffs: dict[int, float],
    grid_size: int,
    *,
    device: str | torch.device = "cpu",
) -> torch.Tensor:
    """Synthesize a pupil OPD map from Noll-indexed Zernike coefficients.

    Returns a real ``[N, N]`` tensor of optical path difference in waves
    (multiply by ``2π`` to get phase in radians, or by the wavelength to
    get OPD in nm). Outside the unit pupil the map is set to 0.

    Args:
        coeffs: ``{noll_index: coeff_in_waves}`` (e.g. from
            :func:`load_zernike_coefficients`).
        grid_size: Output grid edge ``N``.
        device: Torch device.
    """
    if grid_size < 2:
        raise ValueError(f"grid_size must be ≥ 2; got {grid_size}.")

    # Normalized pupil coords on [-1, 1].
    axis = torch.linspace(-1.0, 1.0, grid_size, device=device, dtype=torch.float32)
    yy, xx = torch.meshgrid(axis, axis, indexing="ij")
    rho = torch.sqrt(xx * xx + yy * yy)
    theta = torch.atan2(yy, xx)
    inside = rho <= 1.0

    opd = torch.zeros((grid_size, grid_size), device=device, dtype=torch.float32)
    for noll, c in coeffs.items():
        if c == 0.0:
            continue
        n, m = _NOLL_TO_NM[noll]
        z = _zernike_nm(n, m, rho, theta)
        opd = opd + float(c) * z
    return opd * inside.to(opd.dtype)