driftlet 0.1.0

package/types/types.d.ts

@@ -0,0 +1,574 @@
+export type SpeciesDef = {
+    name: string;
+    /**
+     * charge number (integer; 0 for neutral species)
+     */
+    z: number;
+    /**
+     * default reference concentration, mol/m³
+     */
+    cRef?: number;
+};
+export type MaterialSpeciesDef = {
+    /**
+     * coefficient in N = −(D c/RT)∇μ̄, m²/s
+     */
+    D: number;
+    /**
+     * standard chemical potential, J/mol
+     */
+    mu0: number;
+    /**
+     * concentration that mu0 refers to, mol/m³
+     */
+    cRef?: number;
+};
+/**
+ * Statistics model: how the listed species' concentrations follow from their reduced
+ * potentials ζ = (μ̄ − zFφ − μ°)/RT. Species not in any model are ideal, c = c_ref e^ζ.
+ */
+export type StatisticsDef = ({
+    type: "fermi-dirac";
+    species: string[];
+    order?: 0.5 | 0;
+} | {
+    type: "lattice";
+    species: string[];
+    cMax: number;
+} | {
+    type: "redlich-kister";
+    species: [string];
+    cMax: number;
+    A?: number[];
+} | {
+    type: "debye-huckel";
+    species: string[];
+    epsr?: number;
+    a?: number;
+} | {
+    type: "insertion";
+    species: [string, string];
+    cMax: number;
+    A?: number[];
+    ocv?: {
+        x: number[];
+        E: number[];
+        muRef: number;
+    };
+} | {
+    type: "custom";
+    species: string[];
+    evaluate: (zeta: number[]) => {
+        c: number[];
+        dcdzeta: number[][];
+    };
+});
+/**
+ * A material: either ordinary (epsr, species, optional statistics) or a conductor.
+ */
+export type MaterialDef = {
+    /**
+     * relative permittivity; 0 makes the material strictly neutral
+     */
+    epsr?: number;
+    /**
+     * species present in this material
+     */
+    species?: Record<string, MaterialSpeciesDef>;
+    /**
+     * non-ideal statistics (default: all ideal)
+     */
+    statistics?: StatisticsDef[];
+    /**
+     * a metal or fast ion
+     * conductor: its one carrier and conductivity (S/m); its only level is the carrier's (a metal's
+     * Fermi level), and φ is undefined inside
+     */
+    conductor?: {
+        species: string;
+        conductivity: number;
+    };
+};
+export type GridOptions = {
+    /**
+     * cell size at region ends, m
+     */
+    hmin?: number;
+    /**
+     * largest cell size, m
+     */
+    hmax?: number;
+    /**
+     * geometric growth ratio (default 1.2)
+     */
+    ratio?: number;
+    /**
+     * minimum cells per region (default 8)
+     */
+    minCells?: number;
+    /**
+     * left-end cell size, overriding hmin
+     */
+    hLeft?: number;
+    /**
+     * right-end cell size, overriding hmin
+     */
+    hRight?: number;
+};
+export type RegionDef = {
+    /**
+     * material name
+     */
+    material: string;
+    /**
+     * m
+     */
+    length: number;
+    name?: string;
+    /**
+     * immobile charge density, C/m³
+     */
+    fixedCharge?: number;
+    /**
+     * initial concentrations, mol/m³ (required for species
+     * not connected to a contact: it fixes the amount they conserve)
+     */
+    c0?: Record<string, number>;
+    /**
+     * imposed flow toward +x, m/s, carrying every mobile species
+     */
+    velocity?: number;
+    /**
+     * eddy (turbulent) mixing diffusivity, m²/s; current-free
+     */
+    mixing?: number;
+    grid?: GridOptions;
+};
+export type InterfacePhiLaw = "pinned" | "neutral" | {
+    type: "capacitive";
+    C: number;
+};
+export type InterfaceSpeciesLink = "equilibrium" | "blocked" | {
+    type: "conductance";
+    G: number;
+};
+/**
+ * A reaction at a face: participants on each side with signed stoichiometric coefficients
+ * (ν < 0 consumed by the forward reaction), Butler–Volmer kinetics.
+ */
+export type FaceReactionDef = {
+    /**
+     * the reaction as an equation, e.g. 'Ag+ + e- = Ag(s)', each
+     * participant on the side that holds it ('Li+(left)' where both do); or give left and right
+     */
+    equation?: string;
+    /**
+     * participants on the left side (species present there, or fixed neutrals)
+     */
+    left?: Record<string, number>;
+    /**
+     * participants on the right side
+     */
+    right?: Record<string, number>;
+    /**
+     * μ (J/mol) of fixed-activity participants that aren't species
+     */
+    fixed?: Record<string, number>;
+    /**
+     * standard rate constant, mol/(m²·s)
+     */
+    k0: number;
+    /**
+     * transfer coefficient, 0…1 (default 0.5)
+     */
+    alpha?: number;
+};
+/**
+ * One face between consecutive regions. For different materials under a 'pinned' or
+ * 'capacitive' law, exactly one alignment (step or dipole) is required.
+ */
+export type InterfaceDef = {
+    /**
+     * standard-level step right − left, J/mol
+     */
+    step?: {
+        species: string;
+        value: number;
+    };
+    /**
+     * φ jump right − left, V
+     */
+    dipole?: number;
+    /**
+     * beside a conductor region: V_F − φ_edge at zero charge, V
+     */
+    zeroCharge?: number;
+    /**
+     * electrostatic law (default 'pinned'; 'neutral' between ε = 0 materials)
+     */
+    phi?: InterfacePhiLaw;
+    /**
+     * C/m²
+     */
+    sheetCharge?: number;
+    /**
+     * per-species laws (default equilibrium
+     * where present on both sides and not reacting at the face)
+     */
+    species?: Record<string, InterfaceSpeciesLink>;
+    /**
+     * reactions at the face
+     */
+    reactions?: FaceReactionDef[];
+};
+export type BulkReactionDef = {
+    /**
+     * signed stoichiometric coefficients (ν < 0 consumed)
+     */
+    nu?: Record<string, number>;
+    /**
+     * the reaction as an equation, e.g. 'e- + h+ = 0' (instead of nu)
+     */
+    equation?: string;
+    /**
+     * μ (J/mol) of fixed-activity participants that aren't species
+     */
+    fixed?: Record<string, number>;
+    /**
+     * forward rate constant per material name
+     */
+    kf: Record<string, number>;
+};
+/**
+ * Contacts use the same laws as internal faces; the outside is a phase with known levels
+ * V_i = V + offset_i (a rigid ladder that the circuit slides by V).
+ */
+export type ContactSpeciesLink = "blocked" | "equilibrium" | {
+    type: "equilibrium";
+    offset?: number;
+    mu?: number;
+} | {
+    type: "conductance";
+    G: number;
+    offset?: number;
+} | {
+    type: "exchange";
+    k: number;
+    mu: number;
+};
+/**
+ * 'bulk': the end node is plain bulk (locally neutral, no double layer); 'neutral': no charge at
+ * the face (D = 0); capacitive: Stern layer or gate; 'pinned': φ_edge = V − zeroCharge. The last
+ * two take the contact's zeroCharge.
+ */
+export type ContactPhiLink = "bulk" | "neutral" | "pinned" | {
+    type: "capacitive";
+    C: number;
+};
+export type ContactDef = {
+    /**
+     * held terminal voltage, V (default 0, if no I)
+     */
+    V?: Source;
+    /**
+     * or: the current driven into the device, A/m² (the voltage floats)
+     */
+    I?: Source;
+    /**
+     * with V: a series resistance, Ω·m² (a source behind a resistor)
+     */
+    R?: number;
+    /**
+     * species whose voltage V is
+     */
+    terminal?: string;
+    /**
+     * per-species links (default blocked)
+     */
+    species?: Record<string, ContactSpeciesLink>;
+    /**
+     * a neutral
+     * composition held at the contact, anchored through a charged reference species
+     */
+    bath?: {
+        c: Record<string, number>;
+        reference: string;
+        offset?: number;
+    };
+    /**
+     * required when any species connects (default 'neutral')
+     */
+    phi?: ContactPhiLink;
+    /**
+     * for a capacitive or pinned law: V − φ_edge at zero charge, V
+     */
+    zeroCharge?: number;
+};
+/**
+ * A terminal's source: a constant, or a piecewise-linear waveform through (t, value), constant
+ * beyond the points, or periodic with period t_last − t_0 if repeat is true.
+ */
+export type Source = number | {
+    t: number[];
+    values: number[];
+    repeat?: boolean;
+};
+/**
+ * An internal port: an outside phase exchanging with a window of one region's nodes. On a
+ * conductor region it attaches to the whole conductor (no window), and a conductance G is per area
+ * (S/m²) instead of per volume (S/m³).
+ */
+export type PortDef = {
+    name?: string;
+    /**
+     * region name or index
+     */
+    region: string | number;
+    /**
+     * window start, m from the region's left end (default 0)
+     */
+    from?: number;
+    /**
+     * window end, m (default: the region's length)
+     */
+    to?: number;
+    /**
+     * held terminal voltage, V (default 0, if no I)
+     */
+    V?: Source;
+    /**
+     * or: the current driven into the device, A/m² (e.g. 0 for a reference electrode)
+     */
+    I?: Source;
+    /**
+     * with V: a series resistance, Ω·m²
+     */
+    R?: number;
+    /**
+     * species whose offset defaults to 0
+     */
+    terminal?: string;
+    species: Record<string, "blocked" | "equilibrium" | {
+        type: "equilibrium";
+        offset?: number;
+        mu?: number;
+    } | {
+        type: "conductance";
+        G: number;
+        offset?: number;
+    } | {
+        type: "exchange";
+        k: number;
+        mu: number;
+    }>;
+};
+/**
+ * A device definition: plain, serialisable data.
+ */
+export type DeviceDefinition = {
+    /**
+     * temperature, K (default 298.15)
+     */
+    T?: number;
+    species: SpeciesDef[];
+    materials: Record<string, MaterialDef>;
+    /**
+     * left to right
+     */
+    regions: RegionDef[];
+    /**
+     * one per face, interfaces[f] between regions f and f+1
+     */
+    interfaces?: (InterfaceDef | null | undefined)[];
+    bulkReactions?: BulkReactionDef[];
+    contacts?: {
+        left?: ContactDef;
+        right?: ContactDef;
+    };
+    /**
+     * internal ports
+     */
+    ports?: PortDef[];
+    grid?: GridOptions;
+};
+export type ContactResult = {
+    /**
+     * terminal voltage, V
+     */
+    V: number;
+    /**
+     * particle flux toward +x through this contact, mol/(m²·s)
+     */
+    flux: Record<string, number>;
+    /**
+     * displacement toward +x at this contact, C/m²
+     */
+    D: number;
+    /**
+     * total current toward +x, A/m²
+     */
+    current: number;
+};
+export type Solution = {
+    /**
+     * node positions, m (interface positions appear twice)
+     */
+    x: Float64Array;
+    /**
+     * region index per node
+     */
+    region: Int32Array;
+    /**
+     * the species, in order, with their charge numbers
+     */
+    species: {
+        name: string;
+        z: number;
+    }[];
+    /**
+     * each region's name, material and extent, m
+     */
+    regions: {
+        name: string;
+        material: string;
+        x0: number;
+        x1: number;
+    }[];
+    /**
+     * bookkeeping φ, V (NaN where undefined)
+     */
+    phi: Float64Array;
+    /**
+     * concentrations, mol/m³ (NaN where absent)
+     */
+    c: Record<string, Float64Array>;
+    /**
+     * electrochemical potentials μ̄, J/mol
+     */
+    mu: Record<string, Float64Array>;
+    /**
+     * standard levels μ° + zFφ, J/mol
+     */
+    muStd: Record<string, Float64Array>;
+    /**
+     * species voltages μ̄/(zF), V (charged species)
+     */
+    V: Record<string, Float64Array>;
+    /**
+     * standard levels as voltages, V
+     */
+    Vstd: Record<string, Float64Array>;
+    /**
+     * current toward +x through the device, A/m²
+     */
+    current: number;
+    /**
+     * V_right − V_left, V
+     */
+    terminalVoltage: number;
+    /**
+     * each terminal (left, right,
+     * then the ports by name): its voltage, and its current into the device (A/m²)
+     */
+    terminals: Record<string, {
+        V: number;
+        current: number;
+    }>;
+    contacts: {
+        left: ContactResult;
+        right: ContactResult;
+    };
+    gates: {
+        left?: {
+            V: number;
+            D: number;
+            charge: number;
+        };
+        right?: {
+            V: number;
+            D: number;
+            charge: number;
+        };
+    };
+    /**
+     * what each
+     * internal port brings into the device
+     */
+    ports: {
+        name: string;
+        V: number;
+        flux: Record<string, number>;
+        current: number;
+    }[];
+    interfaces: {
+        dipole: number;
+        sheetCharge: number;
+        D: number;
+        N: Record<string, number>;
+        rates: number[];
+    }[];
+    /**
+     * total charge in the device, C/m²
+     */
+    charge: number;
+    conservation: {
+        species: string;
+        regions: number[];
+        spectator: boolean;
+        connected: boolean;
+        reactive: boolean;
+        amount: number;
+        reference: number;
+        intake: number;
+        drift: number;
+    }[];
+    warnings: string[];
+    converged: boolean;
+    iterations: number;
+    /**
+     * s
+     */
+    time: number;
+    /**
+     * advance(): whether tEnd was reached (false if the frame budget ran out)
+     */
+    done?: boolean;
+    /**
+     * advance(): steps rejected by error control or Newton failure
+     */
+    rejected?: number;
+    /**
+     * advance(): terminal
+     * current (A/m², toward +x) and voltage after each accepted step
+     */
+    trace?: {
+        t: number[];
+        current: number[];
+        voltage: number[];
+    };
+};
+export type ImpedanceResult = {
+    /**
+     * frequencies, Hz
+     */
+    f: Float64Array;
+    /**
+     * impedance −δV/δI, Ω·m²
+     */
+    Z: {
+        re: Float64Array;
+        im: Float64Array;
+    };
+    /**
+     * per frequency, per unit excitation (volt, or A/m² in current mode)
+     */
+    profiles?: {
+        phi: ComplexProfile;
+        mu: Record<string, ComplexProfile>;
+        c: Record<string, ComplexProfile>;
+    }[];
+};
+export type ComplexProfile = {
+    re: Float64Array;
+    im: Float64Array;
+};