Simulation

Simulation preserves the true model, the assumed reconstruction model, and the ground-truth object. Use explicit seeds for reproducible camera and illumination effects. The simulation guide shows the complete workflow.

SyntheticObject

SyntheticObject(field: ComplexArray)

Rust-owned high-resolution complex sample field.

The complex128 field is shaped (height, width) and indexed (row, column). Magnitude represents amplitude transmission and argument represents phase delay in radians. Construction copies Python-owned arrays.

field property

field: ComplexArray

Return a copy of the complex128 field shaped (height, width).

shape property

shape: Shape2D

Return the object shape as (height, width).

label property

label: str | None

Return the optional generator label.

constant staticmethod

constant(
    shape: Shape2D,
    amplitude: float = 1.0,
    phase: float = 0.0,
) -> SyntheticObject

Create a constant field with nonnegative amplitude and radian phase.

amplitude_only staticmethod

amplitude_only(amplitude: FloatArray) -> SyntheticObject

Create a zero-phase object from a finite nonnegative 2D amplitude array.

phase_only staticmethod

phase_only(phase: FloatArray) -> SyntheticObject

Create a unit-amplitude object from a finite 2D radian phase array.

from_amplitude_phase staticmethod

from_amplitude_phase(
    amplitude: FloatArray, phase: FloatArray
) -> SyntheticObject

Combine matching 2D amplitude and radian-phase arrays into a field.

from_amplitude_image staticmethod

from_amplitude_image(path: Path) -> SyntheticObject

Load a grayscale image normalized to [0, 1] as amplitude.

from_amplitude_phase_images staticmethod

from_amplitude_phase_images(
    amplitude_path: Path,
    phase_path: Path,
    phase_extent: float,
) -> SyntheticObject

Load matching grayscale amplitude and phase images.

Black and white phase pixels map linearly to -phase_extent and +phase_extent radians. Image decoding runs without the Python GIL.

phase_disk staticmethod

phase_disk(
    shape: Shape2D, radius_pixels: float, phase_shift: float
) -> SyntheticObject

Create a centered unit-amplitude disk with a radian phase shift.

siemens_star staticmethod

siemens_star(
    shape: Shape2D, spokes: int
) -> SyntheticObject

Create a centered binary-amplitude Siemens star with at least two spokes.

resolution_target staticmethod

resolution_target(shape: Shape2D) -> SyntheticObject

Create deterministic horizontal and vertical binary bar groups.

random_phase staticmethod

random_phase(
    shape: Shape2D, standard_deviation: float, seed: int
) -> SyntheticObject

Create unit amplitude with seeded zero-mean Gaussian phase in radians.

particle_field staticmethod

particle_field(
    shape: Shape2D, particles: int, seed: int
) -> SyntheticObject

Create a seeded unit-amplitude field with dark single-pixel particles.

mixed_test_pattern staticmethod

mixed_test_pattern(shape: Shape2D) -> SyntheticObject

Create a deterministic mixed amplitude-and-phase smoke-test target.

biological_like staticmethod

biological_like(
    shape: Shape2D, features: int, seed: int
) -> SyntheticObject

Create seeded smooth absorption and phase blobs for testing.

This convenient target is not a tissue-specific physical model.

CameraModel

CameraModel(
    *,
    photons_per_pixel: float = 1000.0,
    gain_counts_per_electron: float = 1.0,
    offset_counts: float = 0.0,
    read_noise_electrons: float = 0.0,
    dark_current_electrons: float = 0.0,
    shot_noise: bool = False,
    pixel_sensitivity: FloatArray | None = None,
    bit_depth: int | None = 16,
    saturation_counts: float | None = None,
    quantize: bool = True,
    bad_pixels: Sequence[int] = (),
    bad_pixel_value_counts: float | None = None,
)

Detector response and acquisition-noise model.

Parameters:

Name	Type	Description	Default
photons_per_pixel	float	Positive expected photoelectrons at unit optical intensity.	1000.0
gain_counts_per_electron	float	Positive linear conversion gain in digital counts per electron.	1.0
offset_counts	float	Finite additive electronic bias in digital counts.	0.0
read_noise_electrons	float	Nonnegative Gaussian read-noise standard deviation per pixel.	0.0
dark_current_electrons	float	Nonnegative expected dark-current electrons per pixel and exposure.	0.0
shot_noise	bool	Whether to Poisson-sample photoelectrons and dark current.	False
pixel_sensitivity	FloatArray | None	Optional nonnegative float64 sensitivity map shaped like one detector frame, (height, width).	None
bit_depth	int | None	Optional digitizer bit depth in [1, 53]; None disables the corresponding 2**bits - 1 clipping limit.	16
saturation_counts	float | None	Optional nonnegative clipping threshold in digital counts.	None
quantize	bool	Whether to round final counts to integer-valued float64 values.	True
bad_pixels	Sequence[int]	Unique row-major detector indices replaced after other effects.	()
bad_pixel_value_counts	float | None	Replacement value for bad_pixels in digital counts.	None

ideal staticmethod

ideal() -> CameraModel

Return a unit-response detector without noise, clipping, or quantization.

IlluminationAcquisitionErrors

IlluminationAcquisitionErrors(
    *,
    frame_gain_relative_std: float = 0.0,
    missing_frames: Sequence[int] = (),
    source_permutation: Sequence[int] | None = None,
)

Non-geometric illumination errors injected during simulation.

Parameters:

Name	Type	Description	Default
frame_gain_relative_std	float	Nonnegative one-sigma Gaussian frame-gain variation relative to each frame's compiled gain.	0.0
missing_frames	Sequence[int]	Unique zero-based acquisition frames whose illumination is forced to zero.	()
source_permutation	Sequence[int] | None	Optional complete permutation assigning a true source to each compiled source slot.	None

SimulationResult

Measurements and retained ground truth from one simulated acquisition.

measurements property

measurements: MeasurementStack

Return simulated detector intensities or camera counts in frame order.

ground_truth_object property

ground_truth_object: ComplexArray

Return the true high-resolution complex field.

true_model property

true_model: ImagePlaneModel

Return the optical model used to generate measurements.

reconstruction_model property

reconstruction_model: ImagePlaneModel

Return the assumed model intended for reconstruction.

ideal property

ideal: bool

Return whether camera and acquisition-error effects were absent.

missing_frames property

missing_frames: list[int]

Return zero-based frames whose simulated illumination was forced to zero.

random_seed property

random_seed: int

Return the deterministic seed used for pseudorandom effects.

simulate

simulate(
    true_model: ImagePlaneModel,
    object: ComplexArray | SyntheticObject,
    *,
    reconstruction_model: ImagePlaneModel | None = None,
    camera: CameraModel | None = None,
    illumination_errors: IlluminationAcquisitionErrors
    | None = None,
    seed: int = 0,
) -> SimulationResult

Simulate an image-plane FPM acquisition without holding the Python GIL.

Parameters:

Name	Type	Description	Default
true_model	ImagePlaneModel	Compiled physical model used by the forward simulation.	required
object	ComplexArray | SyntheticObject	Complex128 field or validated SyntheticObject matching the model's reconstruction shape.	required
reconstruction_model	ImagePlaneModel | None	Optional separately compiled assumed model. Omission reuses true_model before known linear camera response is applied.	None
camera	CameraModel | None	Optional detector pipeline producing digital counts.	None
illumination_errors	IlluminationAcquisitionErrors | None	Optional gain variation, missing frames, or source permutation.	None
seed	int	Deterministic unsigned random seed.	0

Returns:

Type	Description
SimulationResult	Measurements, true and assumed models, object truth, and realized acquisition metadata.