@photivra/engine 1.5.0 → 2.0.0

package/dist/sensor/raw-readout.d.ts

@@ -1,25 +1,29 @@
 /**
- * Module boundary and integration notes.
- * Validate an untrusted declaration and return the normalized typed contract. Unknown enum values,
- * missing required fields and incompatible scientific data fail at this boundary. Signal ordering is
- * expected charge → independent seeded photo/dark draws → signed electronic read noise → upper pre-ADC
- * threshold → black pedestal → nearest-half-up ADC quantization → unsigned code limits. Signed
- * below-black values survive until the final code clamp. Physical storage saturation, pre-ADC clipping
- * and digital clipping have distinct diagnostics; ISO never invents a conversion regime.
- * Validate an untrusted declaration and return the normalized typed contract. Unknown enum values,
- * missing required fields and incompatible scientific data fail at this boundary. Signal ordering is
- * expected charge → independent seeded photo/dark draws → signed electronic read noise → upper pre-ADC
- * threshold → black pedestal → nearest-half-up ADC quantization → unsigned code limits. Signed
- * below-black values survive until the final code clamp. Physical storage saturation, pre-ADC clipping
- * and digital clipping have distinct diagnostics; ISO never invents a conversion regime.
+ * RAW readout: turns the expected charge in a sensor site into a RAW code, with shot noise, read
+ * noise and the ADC (analogue-to-digital converter).
+ *
+ * The steps, in order:
+ * 1. expected charge;
+ * 2. separately seeded random photo and dark draws (Poisson shot noise);
+ * 3. signed electronic read noise;
+ * 4. the upper pre-ADC clipping threshold;
+ * 5. the black pedestal (offset);
+ * 6. ADC quantization, rounding to nearest with ties up;
+ * 7. limits on the unsigned code.
+ *
+ * Values below black stay signed until the final code clamp. Physical storage saturation, pre-ADC
+ * clipping and digital clipping are reported separately. The ISO setting never invents a conversion
+ * regime; regimes are declared.
  * @see docs/SENSOR_RAW_PRODUCER.md for equations, coordinate/unit conventions, blockers and support
  * limits.
  */
 import { type CalculationResult } from "../core/calculation-result.js";
 import { type EvidenceBackedFact, type EvidenceProvenance } from "../core/evidence-provenance.js";
+import { type DeterministicUniformStream } from "./stochastic-seed.js";
 import type { SensorPhotoAccumulatedChargeComposition as SensorAccumulatedChargeComposition } from "./accumulated-charge.js";
 import type { SensorPhysicalChargeCapacityAssessment } from "./physical-charge-capacity.js";
 import type { SensorSpectralResponseScientificStatus } from "./spectral-response.js";
+import { type SensorFixedPatternNoiseProfile } from "./fixed-pattern-noise.js";
 export declare const SENSOR_CHARGE_SAMPLING_PROFILE_SCHEMA_VERSION: "0.1.0";
 export declare const SENSOR_READOUT_CONVERSION_PROFILE_SCHEMA_VERSION: "0.1.0";
 export type SensorAdditionalChargeSamplingModel = "poisson" | "deterministic-expected-electron-equivalent";
@@ -42,6 +46,12 @@ export interface SimulateSensorChargeRealizationInput {
     accumulatedCharge: SensorAccumulatedChargeComposition;
     samplingProfile: SensorChargeSamplingProfile;
     seedUint32: number;
+    /**
+     * Optional fixed-pattern noise for this sensor. PRNU (photo-response non-uniformity) scales the
+     * photo Poisson mean; DSNU (dark-signal non-uniformity) and hot pixels scale the dark Poisson mean.
+     * If omitted, the result is exactly the uniform population model.
+     */
+    fixedPatternNoise?: SensorFixedPatternNoiseProfile;
 }
 export interface SensorChargeRealization {
     samplingProfileId: string;
@@ -58,6 +68,16 @@ export interface SensorChargeRealization {
     photoRealizedElectronCount: number;
     darkExpectedElectronCount: number;
     darkRealizedElectronCount: number;
+    /** Fixed-pattern profile applied to this realization, or null for the uniform population model. */
+    fixedPatternNoiseProfileId: string | null;
+    /** PRNU gain applied to the photo expectation (exactly 1 without a fixed pattern). */
+    photoResponseGainFactor: number;
+    /** DSNU/hot-pixel factor applied to the dark expectation (exactly 1 without a fixed pattern). */
+    darkCurrentFactor: number;
+    hotPixel: boolean;
+    /** Poisson means actually sampled: expectation × the site's fixed-pattern factor. */
+    photoSampledMeanElectronCount: number;
+    darkSampledMeanElectronCount: number;
     additionalComponents: readonly {
         componentId: string;
         expectedElectronCount: number;
@@ -77,17 +97,47 @@ export interface SensorChargeRealization {
     stochasticModel: "independent-poisson-photo-dark-explicit-additional-policy";
     deterministicSeededRealization: true;
 }
+/**
+ * Optional ADC integral non-linearity (INL): an offset in code units (LSB, least significant bit),
+ * piecewise linear in the ideal continuous ADC input code, added before quantization. The points must
+ * start at code 0 and end at the ADC maximum code. If omitted, the ADC is ideal and uniform.
+ */
+export interface SensorAdcIntegralNonLinearity {
+    kind: "piecewise-linear-code-offset";
+    knots: readonly {
+        code: number;
+        offsetCodes: number;
+    }[];
+    evidence: readonly EvidenceProvenance[];
+}
+/**
+ * Optional record of how one regime's ISO gain was derived (the exposure index of CIPA DC-004,
+ * relative to the base exposure index). The readout equations still use
+ * systemConversionGainElectronsPerCode (analog, before the ADC) and adc.digitalGain (after the ADC).
+ * This record must agree with them and never replaces them.
+ */
+export interface SensorReadoutExposureIndexGain {
+    exposureIndex: number;
+    baseExposureIndex: number;
+    /** Analog (pre-ADC) gain relative to the base-exposure-index regime. */
+    analogGain: number;
+    /** Post-ADC digital gain; equals adc.digitalGain (1 when omitted). */
+    digitalGain: number;
+    conversionGainMode: "single-conversion-gain" | "low-conversion-gain" | "high-conversion-gain";
+    evidence: readonly EvidenceProvenance[];
+}
 export interface SensorElectronicReadNoiseComponent {
     componentId: string;
     rmsElectrons: EvidenceBackedFact<number>;
     evidence: readonly EvidenceProvenance[];
 }
 /**
- * One explicitly selected electronic conversion regime, with sourced electrons
- * per code, upper pre-ADC electron-equivalent threshold, independent RMS-electron
- * read-noise components and unsigned ADC coding policy. Black pedestal and digital
- * saturation are code-domain quantities. The regime does not infer its hardware
- * mechanism or selection from ISO and does not replace physical storage capacity.
+ * One explicitly selected electronic conversion regime. It has a sourced number of
+ * electrons per code, an upper pre-ADC threshold in electron equivalents, separate
+ * read-noise components (RMS electrons) and an unsigned ADC coding policy. The black
+ * pedestal and digital saturation are in code units. The regime does not guess its
+ * hardware mechanism, is not chosen from ISO automatically, and does not replace
+ * physical storage capacity.
  */
 export interface SensorReadoutConversionRegime {
     regimeId: string;
@@ -100,7 +150,14 @@ export interface SensorReadoutConversionRegime {
         blackLevelCode: number;
         digitalSaturationCode: number;
         transfer: "uniform-round-half-up";
+        /**
+         * Optional post-ADC digital gain (>= 1) applied about the black level:
+         * code = roundHalfUp((adcCode - black) * digitalGain + black). Omission means 1.
+         */
+        digitalGain?: number;
+        integralNonLinearity?: SensorAdcIntegralNonLinearity;
     };
+    exposureIndexGain?: SensorReadoutExposureIndexGain;
     evidence: readonly EvidenceProvenance[];
     limitations: readonly string[];
 }
@@ -151,7 +208,12 @@ export interface SensorExpectedReadoutSignal {
     systemConversionGainElectronsPerCode: number;
     expectedCodeBeforeBlackOffset: number;
     blackLevelCode: number;
+    /** Continuous ADC input code including any declared INL offset. */
     expectedCodeBeforeQuantization: number;
+    adcIntegralNonLinearityOffsetCodes: number;
+    digitalGain: number;
+    /** Continuous code after post-ADC digital gain about black (equals the ADC input without one). */
+    expectedCodeAfterDigitalGain: number;
     adcBitDepth: number;
     adcMaximumCode: number;
     digitalSaturationCode: number;
@@ -169,6 +231,11 @@ export interface SimulateSensorRawCodeInput {
     readoutProfile: SensorReadoutConversionProfile;
     regimeId: string;
     readNoiseSeedUint32: number;
+    /**
+     * Optional fixed pattern; must be the same profile used for the charge realization. Its static
+     * row/column offsets are added with read noise before the pre-ADC threshold.
+     */
+    fixedPatternNoise?: SensorFixedPatternNoiseProfile;
 }
 export interface SensorRawCodeSample {
     readoutProfileId: string;
@@ -197,14 +264,25 @@ export interface SensorRawCodeSample {
         sampledElectrons: number;
     }[];
     totalElectronicReadNoiseElectrons: number;
+    /** Fixed-pattern profile applied at readout, or null. */
+    fixedPatternNoiseProfileId: string | null;
+    /** Static fixed-pattern row + column offset in input-referred electrons (0 without a pattern). */
+    fixedPatternReadoutOffsetElectrons: number;
     electronEquivalentAfterReadNoise: number;
     preAdcSaturationElectronEquivalent: number;
-    /** Signed electronic signal after upper saturation, before conversion/pedestal. */
+    /** Signed electronic signal after the upper (pre-ADC) clip, before conversion and the black pedestal. */
     electronEquivalentAfterPreAdcSaturation: number;
     preAdcSaturationApplied: boolean;
     systemConversionGainElectronsPerCode: number;
     blackLevelCode: number;
+    /** Continuous ADC input code including any declared integral non-linearity offset. */
     codeBeforeQuantization: number;
+    /** INL offset added before quantization (0 for an ideal ADC). */
+    adcIntegralNonLinearityOffsetCodes: number;
+    /** ADC output after quantization and the ADC code-range limit, before digital gain. */
+    adcCodeBeforeDigitalGain: number;
+    /** Post-ADC digital gain (1 when the regime declares none). */
+    digitalGain: number;
     quantizedCodeBeforeDigitalClamp: number;
     adcBitDepth: number;
     adcMaximumCode: number;
@@ -222,93 +300,105 @@ export interface SensorRawCodeSample {
     deterministicSeededRealization: true;
 }
 /**
- * Validate an untrusted declaration and return the normalized typed contract. Unknown enum values,
- * missing required fields and incompatible scientific data fail at this boundary.
+ * Validates untrusted input and returns it as a normalized, typed value. Unknown enum values,
+ * missing required fields and inconsistent scientific data are rejected.
  *
- * Signal ordering is expected charge → independent seeded photo/dark draws → signed electronic read
- * noise → upper pre-ADC threshold → black pedestal → nearest-half-up ADC quantization → unsigned code
- * limits. Signed below-black values survive until the final code clamp. Physical storage saturation,
- * pre-ADC clipping and digital clipping have distinct diagnostics; ISO never invents a conversion
- * regime.
- * @param value - unknown. Treated as untrusted data; static typing alone is not validation.
- * @returns SensorChargeSamplingProfile. Return shape and scientific status are explicit; no calibration is inferred from successful execution.
+ * The profile sets how expected charge is sampled into random photo and dark counts.
+ * @param value - Untrusted data. TypeScript types alone are not validation.
+ * @returns The result. Success does not imply calibration.
  *
- * @see docs/API_REFERENCE.md for the root export and exact type graph.
+ * @see docs/API_REFERENCE.md for the package export and its full type definitions.
  */
 export declare function parseSensorChargeSamplingProfile(value: unknown): SensorChargeSamplingProfile;
 /**
- * Validate an untrusted declaration and return the normalized typed contract. Unknown enum values,
- * missing required fields and incompatible scientific data fail at this boundary.
+ * Validates untrusted input and returns it as a normalized, typed value. Unknown enum values,
+ * missing required fields and inconsistent scientific data are rejected.
  *
- * Signal ordering is expected charge → independent seeded photo/dark draws → signed electronic read
- * noise → upper pre-ADC threshold → black pedestal → nearest-half-up ADC quantization → unsigned code
- * limits. Signed below-black values survive until the final code clamp. Physical storage saturation,
- * pre-ADC clipping and digital clipping have distinct diagnostics; ISO never invents a conversion
- * regime.
- * @param value - unknown. Treated as untrusted data; static typing alone is not validation.
- * @returns SensorReadoutConversionProfile. Return shape and scientific status are explicit; no calibration is inferred from successful execution.
+ * The profile lists the declared conversion regimes. ISO never invents a regime.
+ * @param value - Untrusted data. TypeScript types alone are not validation.
+ * @returns The result. Success does not imply calibration.
  *
- * @see docs/API_REFERENCE.md for the root export and exact type graph.
+ * @see docs/API_REFERENCE.md for the package export and its full type definitions.
  */
 export declare function parseSensorReadoutConversionProfile(value: unknown): SensorReadoutConversionProfile;
 /**
- * Select and validate a declared readout regime against exact channel/profile identity rather than
- * inferring it from ISO.
- *
- * Signal ordering is expected charge → independent seeded photo/dark draws → signed electronic read
- * noise → upper pre-ADC threshold → black pedestal → nearest-half-up ADC quantization → unsigned code
- * limits. Signed below-black values survive until the final code clamp. Physical storage saturation,
- * pre-ADC clipping and digital clipping have distinct diagnostics; ISO never invents a conversion
- * regime.
- * @param input - ResolveSensorReadoutRegimeInput. See the linked contract for coordinate, unit and profile binding semantics.
- * @returns ResolvedSensorReadoutRegime. Return shape and scientific status are explicit; no calibration is inferred from successful execution.
+ * Selects a declared readout regime and checks it against the exact channel and profile identity.
+ * The regime is never inferred from ISO.
+ * @param input - The input; see `ResolveSensorReadoutRegimeInput` for its fields, units and coordinates.
+ * @returns The result. Success does not imply calibration.
  *
- * @see docs/API_REFERENCE.md for the root export and exact type graph.
+ * @see docs/API_REFERENCE.md for the package export and its full type definitions.
  */
 export declare function resolveSensorReadoutRegime(input: ResolveSensorReadoutRegimeInput): ResolvedSensorReadoutRegime;
+type DeterministicRandom = DeterministicUniformStream;
 /**
- * Draw deterministic independently seeded photo/dark Poisson counts and explicit additional-component
- * policies from expected accumulated charge.
+ * Draws a nonnegative integer from a Poisson distribution with the given mean.
  *
- * Signal ordering is expected charge → independent seeded photo/dark draws → signed electronic read
- * noise → upper pre-ADC threshold → black pedestal → nearest-half-up ADC quantization → unsigned code
- * limits. Signed below-black values survive until the final code clamp. Physical storage saturation,
- * pre-ADC clipping and digital clipping have distinct diagnostics; ISO never invents a conversion
- * regime.
- * @param input - SimulateSensorChargeRealizationInput. See the linked contract for coordinate, unit and profile binding semantics.
- * @returns CalculationResult<SensorChargeRealization>. Return shape and scientific status are explicit; no calibration is inferred from successful execution.
+ * - Mean 0 returns exactly 0.
+ * - Mean below 30: multiply uniform random numbers until the product drops below e^(−mean).
+ * - Mean from 30 to below 1e9: Hörmann's (1993) PTRS transformed rejection, comparing log
+ *   probabilities to avoid overflow.
+ * - Mean of 1e9 and above: a continuity-corrected normal approximation, because the log terms lose
+ *   precision there.
  *
- * @see docs/API_REFERENCE.md for the root export and exact type graph.
+ * The same mean and random stream reproduce the same draw. Increasing the mean does not guarantee
+ * that each individual draw increases. Exported internally for the lean native executor, which must
+ * draw exactly as simulateSensorChargeRealization does; not exported from the package.
  */
-export declare function simulateSensorChargeRealization(input: SimulateSensorChargeRealizationInput): CalculationResult<SensorChargeRealization>;
+export declare function samplePoisson(mean: number, random: DeterministicRandom): number;
 /**
- * Map expected charge through declared gain/offset/readout limits without stochastic sampling and
- * retain separate clipping domains.
+ * Internal (not exported from the package): draws `count` Poisson samples of one mean from one seeded
+ * stream, exactly as the charge realization does. Used by the sampler's distribution tests.
+ */
+export declare function samplePoissonStreamForValidation(mean: number, seedUint32: number, count: number): number[];
+/**
+ * Internal (not exported from the package): draws `count` standard normal values from one seeded
+ * stream, exactly as the read-noise path does. Used by the sampler's distribution tests.
+ */
+export declare function sampleStandardNormalStreamForValidation(seedUint32: number, count: number): number[];
+/**
+ * Draws deterministic, separately seeded Poisson counts for photo and dark charge, and applies the
+ * declared policies for additional components, starting from the expected accumulated charge.
  *
- * Signal ordering is expected charge → independent seeded photo/dark draws → signed electronic read
- * noise → upper pre-ADC threshold → black pedestal → nearest-half-up ADC quantization → unsigned code
- * limits. Signed below-black values survive until the final code clamp. Physical storage saturation,
- * pre-ADC clipping and digital clipping have distinct diagnostics; ISO never invents a conversion
- * regime.
- * @param input - CalculateExpectedSensorReadoutInput. See the linked contract for coordinate, unit and profile binding semantics.
- * @returns CalculationResult<SensorExpectedReadoutSignal>. Return shape and scientific status are explicit; no calibration is inferred from successful execution.
+ * This is steps 1–2 of the readout order (see the module notes). Physical storage saturation is
+ * reported separately from later clipping.
+ * @param input - The input; see `SimulateSensorChargeRealizationInput` for its fields, units and coordinates.
+ * @returns The result. Success does not imply calibration.
  *
- * @see docs/API_REFERENCE.md for the root export and exact type graph.
+ * @see docs/API_REFERENCE.md for the package export and its full type definitions.
  */
-export declare function calculateExpectedSensorReadout(input: CalculateExpectedSensorReadoutInput): CalculationResult<SensorExpectedReadoutSignal>;
+export declare function simulateSensorChargeRealization(input: SimulateSensorChargeRealizationInput): CalculationResult<SensorChargeRealization>;
 /**
- * Use the declared seed/regime to preserve signed electronic noise through pedestal and quantization,
- * then return the bounded native ADC code and stage diagnostics.
+ * Maps the expected charge through the declared gain, offset and readout limits, with no random
+ * sampling. Each kind of clipping (physical storage, pre-ADC, digital) is reported separately.
+ * @param input - The input; see `CalculateExpectedSensorReadoutInput` for its fields, units and coordinates.
+ * @returns The result. Success does not imply calibration.
  *
- * Signal ordering is expected charge → independent seeded photo/dark draws → signed electronic read
- * noise → upper pre-ADC threshold → black pedestal → nearest-half-up ADC quantization → unsigned code
- * limits. Signed below-black values survive until the final code clamp. Physical storage saturation,
- * pre-ADC clipping and digital clipping have distinct diagnostics; ISO never invents a conversion
- * regime.
- * @param input - SimulateSensorRawCodeInput. See the linked contract for coordinate, unit and profile binding semantics.
- * @returns CalculationResult<SensorRawCodeSample>. Return shape and scientific status are explicit; no calibration is inferred from successful execution.
+ * @see docs/API_REFERENCE.md for the package export and its full type definitions.
+ */
+export declare function calculateExpectedSensorReadout(input: CalculateExpectedSensorReadoutInput): CalculationResult<SensorExpectedReadoutSignal>;
+/**
+ * Shared ADC transfer function: continuous input code (signal/gain + black + INL), rounded half up
+ * and limited to the ADC code range, then optional post-ADC digital gain about black, rounded again.
+ * The caller applies the final clamp to [0, digitalSaturationCode]. Exported internally for the lean
+ * native executor; not exported from the package.
+ */
+export declare function adcTransfer(regime: SensorReadoutConversionRegime, adcMaximumCode: number, electronEquivalent: number): {
+    codeBeforeQuantization: number;
+    inlOffset: number;
+    adcCode: number;
+    digitalGain: number;
+    quantized: number;
+};
+/**
+ * Simulates one RAW code from a charge realization with the declared seed and regime: steps 3–7 of
+ * the readout order (see the module notes). Signed read noise is kept through the black pedestal and
+ * quantization, and only the final code is clamped. Returns the bounded native ADC code and per-step
+ * diagnostics.
+ * @param input - The input; see `SimulateSensorRawCodeInput` for its fields, units and coordinates.
+ * @returns The result. Success does not imply calibration.
  *
- * @see docs/API_REFERENCE.md for the root export and exact type graph.
+ * @see docs/API_REFERENCE.md for the package export and its full type definitions.
  */
 export declare function simulateSensorRawCode(input: SimulateSensorRawCodeInput): CalculationResult<SensorRawCodeSample>;
-//# sourceMappingURL=raw-readout.d.ts.map
+export {};