pathsim-fusion 0.1.0__py3-none-any.whl

pathsim_fusion/__init__.py

@@ -0,0 +1,29 @@
+"""
+PathSim-Fusion: Fusion fuel cycle and balance-of-plant blocks for PathSim
+
+Specialized simulation blocks for the PathSim framework. All blocks follow
+the standard PathSim block interface and can be connected into simulation
+diagrams.
+"""
+
+try:
+    from ._version import version as __version__
+except ImportError:
+    __version__ = "unknown"
+
+# Pure-Python blocks — eager.
+from .tritium import GLC, Bubbler4, IonisationChamber
+
+__all__ = ["GLC", "Bubbler4", "IonisationChamber", "__version__"]
+
+# If you add blocks that depend on a native package (e.g. pybamm, jsbsim,
+# casadi, …) put them in their own submodule and re-export them defensively
+# here so the toolbox still imports when the heavy dependency is missing
+# (e.g. in Pyodide). Pair this with a PEP 508 environment marker in
+# pyproject.toml — see the comment there for an example.
+#
+# try:
+#     from .native_block import HeavyBlock
+#     __all__ += ["HeavyBlock"]
+# except ImportError:
+#     pass

pathsim_fusion/_version.py

@@ -0,0 +1,24 @@
+# file generated by vcs-versioning
+# don't change, don't track in version control
+from __future__ import annotations
+
+__all__ = [
+    "__version__",
+    "__version_tuple__",
+    "version",
+    "version_tuple",
+    "__commit_id__",
+    "commit_id",
+]
+
+version: str
+__version__: str
+__version_tuple__: tuple[int | str, ...]
+version_tuple: tuple[int | str, ...]
+commit_id: str | None
+__commit_id__: str | None
+
+__version__ = version = '0.1.0'
+__version_tuple__ = version_tuple = (0, 1, 0)
+
+__commit_id__ = commit_id = None

pathsim_fusion/tritium/__init__.py

@@ -0,0 +1,5 @@
+from .bubbler import Bubbler4
+from .glc import GLC
+from .ionisation_chamber import IonisationChamber
+
+__all__ = ["GLC", "Bubbler4", "IonisationChamber"]

pathsim_fusion/tritium/bubbler.py

@@ -0,0 +1,240 @@
+#########################################################################################
+##
+##                                      Bubbler Block
+##
+#########################################################################################
+
+# IMPORTS ===============================================================================
+
+import numbers
+from typing import ClassVar
+
+import numpy as np
+from pathsim.blocks.dynsys import DynamicalSystem
+from pathsim.events.schedule import ScheduleList
+
+# BLOCK DEFINITIONS =====================================================================
+
+
+class Bubbler4(DynamicalSystem):
+    """Tritium bubbling system with sequential vial collection stages.
+
+    This block models a tritium collection system used in fusion reactor blanket
+    purge gas processing. The system bubbles tritium-containing gas through a series
+    of liquid-filled vials to capture and concentrate tritium for measurement and
+    inventory tracking.
+
+
+    Physical Description
+    --------------------
+    The bubbler consists of two parallel processing chains:
+
+    **Soluble Chain (Vials 1-2):**
+    Tritium already in soluble forms (HTO, HT) flows sequentially through
+    vials 1 and 2. Each vial has a collection efficiency :math:`\\eta_{vial}`,
+    representing the fraction of tritium that dissolves into the liquid phase
+    and is retained.
+
+    **Insoluble Chain (Vials 3-4):**
+    Tritium in insoluble forms (T₂, organically bound) first undergoes catalytic
+    conversion to soluble forms with efficiency :math:`\\alpha_{conv}`. The
+    converted tritium, along with uncaptured soluble tritium from the first chain,
+    then flows through vials 3 and 4 with the same collection efficiency.
+
+
+    Mathematical Formulation
+    -------------------------
+    The system is governed by the following differential equations for the
+    vial inventories :math:`x_i`:
+
+    .. math::
+
+        \\begin{align}
+            \\frac{dx_1}{dt} &= \\eta_{vial} \\cdot u_{sol} \\\\
+            \\frac{dx_2}{dt} &= \\eta_{vial} \\cdot (1-\\eta_{vial}) \\cdot u_{sol} \\\\
+            \\frac{dx_3}{dt} &= \\eta_{vial} \\cdot [\\alpha_{conv} \\cdot u_{insol} + (1-\\eta_{vial})^2 \\cdot u_{sol}] \\\\
+            \\frac{dx_4}{dt} &= \\eta_{vial} \\cdot (1-\\eta_{vial}) \\cdot [\\alpha_{conv} \\cdot u_{insol} + (1-\\eta_{vial})^2 \\cdot u_{sol}]
+        \\end{align}
+
+
+    The sample output represents uncaptured tritium exiting the system:
+
+    .. math::
+
+        y_{sample} = (1-\\alpha_{conv}) \\cdot u_{insol} + (1-\\eta_{vial})^2 \\cdot [\\alpha_{conv} \\cdot u_{insol} + (1-\\eta_{vial})^2 \\cdot u_{sol}]
+
+
+    Where:
+        - :math:`u_{sol}` = soluble tritium input flow rate
+        - :math:`u_{insol}` = insoluble tritium input flow rate
+        - :math:`\\eta_{vial}` = vial collection efficiency
+        - :math:`\\alpha_{conv}` = conversion efficiency from insoluble to soluble
+        - :math:`x_i` = tritium inventory in vial i
+
+    Parameters
+    ----------
+    conversion_efficiency : float
+       Conversion efficiency from insoluble to soluble forms (:math:`\\alpha_{conv}`),
+       between 0 and 1.
+    vial_efficiency : float
+       Collection efficiency of each vial (:math:`\\eta_{vial}`), between 0 and 1.
+    replacement_times : float | list[float] | list[list[float]] | None
+        Times at which each vial is replaced with a fresh one. If None, no
+        replacement events are created. If a single value is provided, it is
+        used for all vials. If a single list of floats is provided, it will be
+        used for all vials. If a list of four lists is provided, each sublist
+        corresponds to the replacement times for each vial.
+
+    Inputs
+    ------
+    sample_in_soluble (0) : soluble tritium flow rate into the bubbler
+    sample_in_insoluble (1) : insoluble tritium flow rate into the bubbler
+
+    Outputs
+    -------
+    vial1 (0) : tritium inventory in vial 1
+    vial2 (1) : tritium inventory in vial 2
+    vial3 (2) : tritium inventory in vial 3
+    vial4 (3) : tritium inventory in vial 4
+    sample_out (4) : uncaptured tritium flow rate leaving the bubbler
+
+    Note
+    ----
+    Vial replacement is modeled as instantaneous reset events that set the
+    corresponding vial inventory to zero, simulating the physical replacement
+    of a full vial with an empty one.
+    """
+
+    input_port_labels: ClassVar[dict[str, int]] = {
+        "sample_in_soluble": 0,
+        "sample_in_insoluble": 1,
+    }
+    output_port_labels: ClassVar[dict[str, int]] = {
+        "vial1": 0,
+        "vial2": 1,
+        "vial3": 2,
+        "vial4": 3,
+        "sample_out": 4,
+    }
+
+    def __init__(
+        self,
+        conversion_efficiency=0.9,
+        vial_efficiency=0.9,
+        replacement_times=None,
+    ):
+
+        # input validation
+        if not 0 <= conversion_efficiency <= 1:
+            raise ValueError(
+                "'conversion_efficiency' must be between 0 and 1 "
+                f"but is {conversion_efficiency}"
+            )
+        if not 0 <= vial_efficiency <= 1:
+            raise ValueError(
+                f"'vial_efficiency' must be between 0 and 1 but is {vial_efficiency}"
+            )
+
+        # bubbler parameters
+        self.replacement_times = replacement_times
+        self.vial_efficiency = vial_efficiency
+        self.conversion_efficiency = conversion_efficiency
+
+        # dynamical component, ode rhs
+        def _fn_d(x, u, t):
+
+            # short
+            ve = self.vial_efficiency
+            ce = self.conversion_efficiency
+
+            # unpack inputs
+            sol, ins = u
+
+            # compute vial content change rates
+            dv1 = ve * sol
+            dv2 = dv1 * (1 - ve)
+            dv3 = ve * (ce * ins + (1 - ve) ** 2 * sol)
+            dv4 = dv3 * (1 - ve)
+
+            return np.array([dv1, dv2, dv3, dv4])
+
+        # algebraic output component
+        def _fn_a(x, u, t):
+
+            # short
+            ve = self.vial_efficiency
+            ce = self.conversion_efficiency
+
+            # unpack inputs
+            sol, ins = u
+
+            sample_out = (1 - ce) * ins + (1 - ve) ** 2 * (
+                ce * ins + (1 - ve) ** 2 * sol
+            )
+
+            return np.hstack([x, sample_out])
+
+        # initialization just like `DynamicalSystem` block
+        super().__init__(
+            func_dyn=_fn_d,
+            func_alg=_fn_a,
+            initial_value=np.zeros(4),
+        )
+
+        # create internal vial reset events
+        self._create_reset_events()
+
+    def _create_reset_event_vial(self, i, reset_times):
+        """Define event action function and return a `ScheduleList` event
+        per vial `i` that triggers at predefined `reset_times`.
+        """
+
+        def reset_vial_i(_):
+            # get the full engine state
+            x = self.engine.get()
+            # set index 'i' to zero
+            x[i] = 0.0
+            # set the full engine state
+            self.engine.set(x)
+
+        return ScheduleList(times_evt=reset_times, func_act=reset_vial_i)
+
+    def _create_reset_events(self):
+        """Create reset events for all vials based on the replacement times.
+
+        Raises
+        ------
+        ValueError : If reset_times is not valid.
+        """
+
+        replacement_times = self.replacement_times
+        self.events = []
+
+        # no replacement
+        if replacement_times is None:
+            return
+
+        # a single time is used for all vials (numbers.Real also covers numpy scalars)
+        if isinstance(replacement_times, numbers.Real):
+            replacement_times = [[replacement_times]] * 4
+
+        # a flat list of times is used for all vials
+        elif isinstance(replacement_times, (list, tuple)) and all(
+            isinstance(t, numbers.Real) for t in replacement_times
+        ):
+            replacement_times = [list(replacement_times)] * 4
+
+        elif isinstance(replacement_times, np.ndarray) and replacement_times.ndim == 1:
+            replacement_times = [replacement_times.tolist()] * 4
+
+        # otherwise one list of times per vial
+        elif len(replacement_times) != 4:
+            raise ValueError(
+                "replacement_times must be a single value or a list with the same length as the number of vials"
+            )
+
+        # create the internal events
+        self.events = [
+            self._create_reset_event_vial(i, ts)
+            for i, ts in enumerate(replacement_times)
+        ]

pathsim_fusion/tritium/glc.py

@@ -0,0 +1,537 @@
+"""
+Bubble column gas-liquid contactor model solver.
+
+This module solves the coupled, non-linear, second-order ordinary differential
+equations that describe tritium transport in a counter-current bubble column,
+based on the model by C. Malara (1995). The boundary value problem is solved
+with the native :class:`~pathsim.blocks.BVP1D` block, which warm-starts the
+mesh between evaluations and skips the re-solve when the boundary data is
+unchanged.
+"""
+
+from typing import ClassVar
+
+import numpy as np
+import scipy.constants as const
+from pathsim.blocks import BVP1D
+from scipy.optimize import root_scalar
+
+# --- Physical Constants ---
+g = const.g  # m/s^2, Gravitational acceleration
+R = const.R  # J/(mol·K), Universal gas constant
+N_A = const.N_A  # 1/mol, Avogadro's number
+M_LiPb = 2.875e-25  # Kg/molecule, Lipb molecular mass
+
+
+def _calculate_properties(params):
+    """
+    Calculate temperature-dependent and geometry-dependent physical properties.
+
+    This function computes fluid properties, flow characteristics,
+    dimensionless numbers, and hydrodynamic parameters based on the input
+    geometry and operating conditions.
+
+    Args:
+        params (dict): Dictionary of input parameters including T, D, Flow_l,
+                       Flow_g, and P_0.
+
+    Returns:
+        dict: A dictionary containing the calculated physical properties.
+    """
+    T = params["T"]
+    D = params["D"]
+    flow_l = params["flow_l"]
+    flow_g = params["flow_g"]
+    P_in = params["P_in"]
+
+    # --- Fluid Properties (Temperature Dependent) ---
+    # TODO add references
+    rho_l = 10.45e3 * (1 - 1.61e-4 * T)  # kg/m^3, Liquid (LiPb) density
+    sigma_l = 0.52 - 0.11e-3 * T  # N/m, Surface tension, liquid-gas interface
+    mu_l = 1.87e-4 * np.exp(11640 / (R * T))  # Pa.s, Dynamic viscosity of liquid
+    nu_l = mu_l / rho_l  # m^2/s, Kinematic viscosity of liquid
+    D_T = 2.5e-7 * np.exp(-27000 / (R * T))  # m^2/s, Tritium diffusion coeff
+    K_s_at = 2.32e-8 * np.exp(-1350 / (R * T))  # atfrac*Pa^0.5, Sievert's const
+    K_s = K_s_at * (rho_l / (M_LiPb * N_A))  # mol/(m^3·Pa^0.5)
+
+    # --- Flow Properties ---
+    A = np.pi * (D / 2) ** 2  # m^2, Cross-sectional area
+    Q_l = flow_l / rho_l  # m^3/s, Volumetric liquid flow rate
+    Q_g = (flow_g * R * T) / P_in  # m^3/s, Volumetric gas flow rate at inlet
+    u_l = Q_l / A  # m/s, Superficial liquid velocity
+    u_g0 = Q_g / A  # m/s, Superficial gas velocity at inlet
+
+    # --- Dimensionless Numbers for Correlations ---
+    Bn = (g * D**2 * rho_l) / sigma_l  # Bond number
+    Ga = (g * D**3) / nu_l**2  # Galilei number
+    Sc = nu_l / D_T  # Schmidt number
+    Fr = u_g0 / (g * D) ** 0.5  # Froude number
+
+    # --- Hydrodynamic and Mass Transfer Parameters ---
+    # Gas hold-up (ε_g) from correlation: C = ε_g / (1 - ε_g)^4
+    C = 0.2 * (Bn ** (1 / 8)) * (Ga ** (1 / 12)) * Fr
+
+    def _f_holdup(e, C_val):
+        return e / (1 - e) ** 4 - C_val
+
+    try:
+        sol = root_scalar(_f_holdup, args=(C,), bracket=[1e-12, 1 - 1e-12])
+        epsilon_g = sol.root
+    except Exception as exc:
+        raise RuntimeError("Failed to solve for gas hold-up ε_g") from exc
+
+    epsilon_l = 1 - epsilon_g  # Liquid phase fraction
+
+    # Dispersion coefficients
+    E_l = (D * u_g0) / ((13 * Fr) / (1 + 6.5 * (Fr**0.8)))
+    E_g = (0.2 * D**2) * u_g0
+
+    # Interfacial area and mass transfer coefficients
+    d_b = (26 * (Bn**-0.5) * (Ga**-0.12) * (Fr**-0.12)) * D
+    a = 6 * epsilon_g / d_b
+    h_l_a = D_T * (0.6 * Sc**0.5 * Bn**0.62 * Ga**0.31 * epsilon_g**1.1) / (D**2)
+    h_l = h_l_a / a  # Mass transfer coefficient
+
+    return {
+        "rho_l": rho_l,
+        "sigma_l": sigma_l,
+        "mu_l": mu_l,
+        "nu_l": nu_l,
+        "K_s": K_s,
+        "Q_l": Q_l,
+        "Q_g": Q_g,
+        "u_l": u_l,
+        "u_g0": u_g0,
+        "epsilon_g": epsilon_g,
+        "epsilon_l": epsilon_l,
+        "E_l": E_l,
+        "E_g": E_g,
+        "a": a,
+        "h_l": h_l,
+    }
+
+
+def _calculate_dimensionless_groups(params, phys_props):
+    """
+    Calculate the dimensionless groups for the ODE system.
+
+    Args:
+        params (dict): Dictionary of input parameters including L, T, P_in,
+                       and c_T_inlet.
+        phys_props (dict): Dictionary of physical properties calculated by
+                           _calculate_properties.
+
+    Returns:
+        dict: A dictionary containing the dimensionless groups (Bo_l, phi_l,
+              Bo_g, phi_g, psi, nu).
+    """
+    # Unpack parameters
+    L, T, P_in, c_T_in = (
+        params["L"],
+        params["T"],
+        params["P_in"],
+        params["c_T_in"],
+    )
+
+    # Unpack physical properties
+    rho_l, K_s, u_l, u_g0, epsilon_g, epsilon_l, E_l, E_g, a, h_l = (
+        phys_props["rho_l"],
+        phys_props["K_s"],
+        phys_props["u_l"],
+        phys_props["u_g0"],
+        phys_props["epsilon_g"],
+        phys_props["epsilon_l"],
+        phys_props["E_l"],
+        phys_props["E_g"],
+        phys_props["a"],
+        phys_props["h_l"],
+    )
+
+    # Calculate dimensionless groups
+    psi = (rho_l * g * epsilon_l * L) / P_in  # Hydrostatic pressure ratio
+    nu = ((c_T_in / K_s) ** 2) / P_in  # Equilibrium ratio
+    Bo_l = u_l * L / (epsilon_l * E_l)  # Bodenstein number, liquid
+    phi_l = a * h_l * L / u_l  # Transfer units, liquid
+    Bo_g = u_g0 * L / (epsilon_g * E_g)  # Bodenstein number, gas
+    phi_g = 0.5 * (R * T * c_T_in / P_in) * (a * h_l * L / u_g0)
+
+    return {
+        "Bo_l": Bo_l,
+        "phi_l": phi_l,
+        "Bo_g": Bo_g,
+        "phi_g": phi_g,
+        "psi": psi,
+        "nu": nu,
+    }
+
+
+def _ode_system(xi, S, dim):
+    """First-order ODE system (4 equations) of the dimensionless GLC model.
+
+    The state is ``S = [x_T, dx_T/d(xi), y_T2, dy_T2/d(xi)]``. The signature
+    matches what the native :class:`~pathsim.blocks.BVP1D` block expects, with
+    the spatial mesh ``xi`` of shape ``(m,)`` and the state ``S`` of shape
+    ``(4, m)``.
+
+    Args:
+        xi (numpy.ndarray): Dimensionless axial coordinate, shape ``(m,)``.
+        S (numpy.ndarray): State, shape ``(4, m)``.
+        dim (dict): Dimensionless groups (Bo_l, phi_l, Bo_g, phi_g, psi, nu).
+
+    Returns:
+        numpy.ndarray: Derivatives ``dS/d(xi)``, shape ``(4, m)``.
+    """
+    Bo_l, phi_l, Bo_g, phi_g, psi, nu = (
+        dim["Bo_l"],
+        dim["phi_l"],
+        dim["Bo_g"],
+        dim["phi_g"],
+        dim["psi"],
+        dim["nu"],
+    )
+
+    x_T, dx_T_dxi, y_T2, dy_T2_dxi = S
+    theta = x_T - np.sqrt(np.maximum(0, (1 - psi * xi) * y_T2 / nu))
+
+    dS0_dxi = dx_T_dxi  # d(x_T)/d(xi)
+    dS1_dxi = Bo_l * (phi_l * theta - dx_T_dxi)  # d^2(x_T)/d(xi)^2
+    dS2_dxi = dy_T2_dxi  # d(y_T2)/d(xi)
+    term1 = (1 + 2 * psi / Bo_g) * dy_T2_dxi
+    term2 = phi_g * theta
+    dS3_dxi = (Bo_g / (1 - psi * xi)) * (term1 - term2)  # d^2(y_T2)/d(xi)^2
+
+    return np.vstack((dS0_dxi, dS1_dxi, dS2_dxi, dS3_dxi))
+
+
+def _boundary_conditions(Sa, Sb, dim, y_T2_in, BCs):
+    """Boundary-condition residuals at xi=0 (Sa) and xi=1 (Sb).
+
+    Args:
+        Sa (numpy.ndarray): State at xi=0 (liquid outlet).
+        Sb (numpy.ndarray): State at xi=1 (liquid inlet).
+        dim (dict): Dimensionless groups (uses Bo_l, Bo_g).
+        y_T2_in (float): Inlet mole fraction of T2 in the gas phase.
+        BCs (str): Boundary-condition type, ``"C-C"`` or ``"O-C"``.
+
+    Returns:
+        numpy.ndarray: The four boundary-condition residuals.
+
+    Raises:
+        ValueError: If ``BCs`` is not a recognised type.
+    """
+    Bo_l, Bo_g = dim["Bo_l"], dim["Bo_g"]
+
+    if BCs == "C-C":  # Closed-Closed
+        res1 = Sa[1]  # dx_T/d(xi) = 0 at xi=0
+        res2 = Sb[0] - (1 - (1 / Bo_l) * Sb[1])  # x_T(1) = 1 - ...
+        res3 = Sa[2] - y_T2_in - (1 / Bo_g) * Sa[3]  # y_T2(0) = y_T2_in + ...
+        res4 = Sb[3]  # dy_T2/d(xi) = 0 at xi=1
+    elif BCs == "O-C":  # Open-Closed
+        res1 = Sa[1]  # dx_T/d(xi) = 0 at xi=0
+        res2 = Sb[0] - 1.0  # x_T(1) = 1
+        res3 = Sa[2] - y_T2_in  # y_T2(0) = y_T2_in
+        res4 = Sb[3]  # dy_T2/d(xi) = 0 at xi=1
+    else:
+        raise ValueError(f"Unknown boundary condition type: {BCs!r}")
+
+    return np.array([res1, res2, res3, res4])
+
+
+def _process_results(S_ends, params, phys_props, dim_params):
+    """
+    Process the BVP solution to produce dimensional results.
+
+    This function converts the dimensionless solution of the BVP back into
+    dimensional quantities, calculates the extraction efficiency, performs a
+    mass balance check, and aggregates all results.
+
+    Args:
+        S_ends (numpy.ndarray): Solution sampled at the domain endpoints,
+            shape ``(4, 2)`` with column 0 at xi=0 (liquid outlet) and column 1
+            at xi=1 (liquid inlet).
+        params (dict): The original input parameters.
+        phys_props (dict): The calculated physical properties.
+        dim_params (dict): The calculated dimensionless groups.
+
+    Returns:
+        dict: The dimensional results dictionary.
+    """
+
+    # Unpack parameters
+    c_T_in, P_in, T = params["c_T_in"], params["P_in"], params["T"]
+    y_T2_in = params["y_T2_in"]
+
+    # Dimensionless results (xi=0 -> column 0, xi=1 -> column 1)
+    x_T_outlet_dimless = S_ends[0, 0]
+    Q_l, Q_g = phys_props["Q_l"], phys_props["Q_g"]
+    y_T2_out = S_ends[2, 1]
+    efficiency = 1 - x_T_outlet_dimless
+
+    # Dimensional results
+    c_T_out = x_T_outlet_dimless * c_T_in
+    P_out = P_in * (1 - dim_params["psi"])
+    P_T2_out = y_T2_out * P_out
+    P_T2_in = y_T2_in * P_in
+
+    # Tritium molar flows from the converged solution (mol/s). Each T2 molecule
+    # carries two tritium atoms.
+    n_T_in_liquid = c_T_in * Q_l
+    n_T_in_gas = 2 * P_T2_in * Q_g / (R * T)
+    n_T_out_liquid = c_T_out * Q_l
+    Q_g_out = Q_g * (P_in / P_out)  # m3/s
+    n_T_out_gas = 2 * P_T2_out * Q_g_out / (R * T)
+
+    n_T_in = n_T_in_liquid + n_T_in_gas
+    n_T_out = n_T_out_liquid + n_T_out_gas
+
+    # Mass-balance residual reported as a diagnostic. For closed-closed (C-C)
+    # boundary conditions it is at numerical-noise level; for open-closed (O-C)
+    # it reflects the dispersive flux neglected by the open inlet condition.
+    return {
+        "c_T_outlet [mol/m^3]": c_T_out,
+        "y_T2_outlet_gas": y_T2_out,
+        "extraction_efficiency [fraction]": efficiency,
+        "total_gas_P_outlet [Pa]": P_out,
+        "liquid_vol_flow [m^3/s]": Q_l,
+        "gas_vol_flow_outlet [m^3/s]": Q_g_out,
+        "tritium_out_liquid [mol/s]": n_T_out_liquid,
+        "tritium_out_gas [mol/s]": n_T_out_gas,
+        "Total tritium in [mol/s]": n_T_in,
+        "Total tritium out [mol/s]": n_T_out,
+        "mass_balance_residual [mol/s]": n_T_in - n_T_out,
+    }
+
+
+class GLC(BVP1D):
+    r"""Counter-current bubble column gas-liquid contactor (GLC) for tritium extraction.
+
+    Solves the coupled, non-linear, second-order boundary value problem that
+    describes tritium transport between a liquid metal (LiPb) stream and a
+    purge gas in a counter-current bubble column. The model is based on
+    C. Malara (1995) and accounts for axial dispersion, interfacial mass
+    transfer via Sieverts' law, and hydrostatic pressure variation along
+    the column.
+
+    The block is a specialisation of the native :class:`~pathsim.blocks.BVP1D`
+    block: the constructor seeds the parent with the Malara right-hand side and
+    boundary conditions, and the four block inputs supply the per-evaluation
+    boundary data. The hydrodynamic correlations and dimensionless groups are
+    computed from the current input inside the collocation callbacks. As for any
+    ``BVP1D``, the solve is warm-started from the previous mesh and skipped
+    entirely when the input is unchanged. After each solve the dimensionless
+    endpoint solution is post-processed into the dimensional output ports.
+
+    Use :meth:`results` to retrieve the full dimensional result dictionary,
+    which additionally contains partial pressures, physical properties and the
+    dimensionless groups.
+
+    Reference: https://doi.org/10.13182/FST95-A30485
+
+    **Input ports:**
+    ``c_T_in`` -- dissolved tritium concentration in liquid inlet [mol/m³],
+    ``flow_l`` -- liquid mass flow rate [kg/s],
+    ``y_T2_inlet`` -- T₂ mole fraction in inlet gas [-],
+    ``flow_g`` -- gas mass flow rate [kg/s].
+
+    **Output ports:**
+    ``c_T_out`` -- dissolved tritium concentration in liquid outlet [mol/m³],
+    ``y_T2_out`` -- T₂ mole fraction in outlet gas [-],
+    ``eff`` -- extraction efficiency [-],
+    ``P_out`` -- total gas outlet pressure [Pa],
+    ``Q_l`` -- liquid volumetric flow rate [m³/s],
+    ``Q_g_out`` -- gas volumetric flow rate at outlet [m³/s],
+    ``n_T_out_liquid`` -- tritium molar flow in liquid outlet [mol/s],
+    ``n_T_out_gas`` -- tritium molar flow in gas outlet [mol/s].
+
+    Parameters
+    ----------
+    P_in : float
+        Inlet operating pressure [Pa].
+    L : float
+        Column height [m].
+    D : float
+        Column diameter [m].
+    T : float
+        Operating temperature [K]. Used to compute temperature-dependent
+        LiPb properties (density, viscosity, Sieverts' constant, etc.).
+    BCs : str
+        Boundary condition type for the BVP: ``"C-C"`` (closed-closed) or
+        ``"O-C"`` (open-closed).
+    g : float, optional
+        Gravitational acceleration [m/s²]. Default: ``scipy.constants.g``.
+    initial_nb_of_elements : int, optional
+        Number of mesh elements for the initial BVP grid. Default: 20.
+    tol : float, optional
+        Solver tolerance for the BVP. Default: 1e-5.
+    max_nodes : int, optional
+        Maximum number of mesh nodes allowed during BVP refinement. Default:
+        10000.
+    """
+
+    input_port_labels: ClassVar[dict[str, int]] = {
+        "c_T_in": 0,
+        "flow_l": 1,
+        "y_T2_inlet": 2,
+        "flow_g": 3,
+    }
+    output_port_labels: ClassVar[dict[str, int]] = {
+        "c_T_out": 0,
+        "y_T2_out": 1,
+        "eff": 2,
+        "P_out": 3,
+        "Q_l": 4,
+        "Q_g_out": 5,
+        "n_T_out_liquid": 6,
+        "n_T_out_gas": 7,
+    }
+
+    def __init__(
+        self,
+        P_in,
+        L,
+        D,
+        T,
+        BCs,
+        g=const.g,
+        initial_nb_of_elements=20,
+        tol=1e-5,
+        max_nodes=10000,
+    ):
+        # fixed operating point and geometry; the four block inputs supply the
+        # per-evaluation boundary data (c_T_in, flow_l, y_T2_inlet, flow_g)
+        self.params = {
+            "P_in": P_in,
+            "L": L,
+            "g": g,
+            "D": D,
+            "T": T,
+            "elements": initial_nb_of_elements,
+            "BCs": BCs,
+        }
+        self.BCs = BCs
+
+        # cache of (physical properties, dimensionless groups) keyed on the input
+        # so the hydrodynamic correlations run once per operating point instead of
+        # on every collocation mesh point
+        self._u_cache = None
+        self._phys = None
+        self._dim = None
+
+        # seed the native BVP block with the Malara model physics; sample the two
+        # domain endpoints so the dimensionless outlet/inlet states are available
+        super().__init__(
+            fun=self._ode,
+            bc=self._bc,
+            n=4,
+            domain=(0.0, 1.0),
+            n_nodes=initial_nb_of_elements + 1,
+            x_eval=np.array([0.0, 1.0]),
+            tol=tol,
+            max_nodes=max_nodes,
+        )
+
+    def _physics(self, u):
+        """Physical properties and dimensionless groups for the input `u`.
+
+        Cached on `u` so the hydrodynamic correlations (and the gas hold-up
+        root solve) run once per operating point rather than on every mesh
+        point of the collocation solve.
+        """
+        if self._u_cache is not None and np.array_equal(u, self._u_cache):
+            return self._phys, self._dim
+
+        c_T_in, flow_l, y_T2_inlet, flow_g = u
+        p = dict(self.params)
+        p["c_T_in"] = c_T_in
+        p["flow_l"] = flow_l
+        p["flow_g"] = flow_g
+        p["y_T2_in"] = y_T2_inlet
+
+        phys = _calculate_properties(p)
+
+        # guard against a non-physical (non-positive) gas outlet pressure
+        P_out = p["P_in"] - phys["rho_l"] * (1 - phys["epsilon_g"]) * g * p["L"]
+        if P_out <= 0:
+            raise ValueError(
+                f"Calculated gas outlet pressure is non-positive ({P_out:.2e} Pa). "
+                "Check input parameters P_in, L, etc."
+            )
+
+        dim = _calculate_dimensionless_groups(p, phys)
+
+        self._u_cache = np.array(u, dtype=float)
+        self._phys, self._dim = phys, dim
+        return phys, dim
+
+    def _ode(self, xi, S, p, u):
+        """Malara right-hand side, with dimensionless groups derived from `u`."""
+        _, dim = self._physics(u)
+        return _ode_system(xi, S, dim)
+
+    def _bc(self, Sa, Sb, p, u):
+        """Malara boundary conditions, with groups derived from `u`."""
+        _, dim = self._physics(u)
+        y_T2_in = max(u[2], 1e-20)
+        return _boundary_conditions(Sa, Sb, dim, y_T2_in, self.BCs)
+
+    def update(self, t):
+        """Solve the BVP and expose the dimensional results at the output ports.
+
+        Delegates the solve to :class:`~pathsim.blocks.BVP1D` (warm-started, and
+        skipped when the input is unchanged), then post-processes the
+        dimensionless endpoint solution into the eight dimensional output ports.
+
+        Parameters
+        ----------
+        t : float
+            evaluation time
+
+        Raises
+        ------
+        RuntimeError
+            if the BVP solve did not converge
+        """
+        super().update(t)
+        if not self.success:
+            raise RuntimeError("BVP solver failed to converge.")
+
+        res = self.results()
+        self.outputs.update_from_array(
+            np.array(
+                [
+                    res["c_T_outlet [mol/m^3]"],
+                    res["y_T2_outlet_gas"],
+                    res["extraction_efficiency [fraction]"],
+                    res["total_gas_P_outlet [Pa]"],
+                    res["liquid_vol_flow [m^3/s]"],
+                    res["gas_vol_flow_outlet [m^3/s]"],
+                    res["tritium_out_liquid [mol/s]"],
+                    res["tritium_out_gas [mol/s]"],
+                ]
+            )
+        )
+
+    def results(self):
+        """Post-process the current BVP solution into dimensional results.
+
+        Returns
+        -------
+        dict, None
+            Dimensional results (outlet concentration, extraction efficiency,
+            outlet pressure, volumetric flows, tritium molar flows and the mass
+            balance) for the most recent input, or ``None`` if no successful
+            solve has happened yet.
+        """
+        if not self.success:
+            return None
+
+        u = self.inputs.to_array()
+        c_T_in, flow_l, y_T2_inlet, flow_g = u
+        p = dict(self.params)
+        p["c_T_in"] = c_T_in
+        p["flow_l"] = flow_l
+        p["flow_g"] = flow_g
+        p["y_T2_in"] = y_T2_inlet
+
+        phys, dim = self._physics(u)
+        return _process_results(self.solution(), p, phys, dim)

pathsim_fusion/tritium/ionisation_chamber.py

@@ -0,0 +1,96 @@
+#########################################################################################
+##
+##                            Ionisation Chamber Block
+##
+#########################################################################################
+
+# IMPORTS ===============================================================================
+
+from typing import ClassVar
+
+from pathsim.blocks.function import Function
+
+# BLOCKS ================================================================================
+
+
+class IonisationChamber(Function):
+    """Ionisation chamber for tritium detection.
+
+    Algebraic block that models a flow-through ionisation chamber. The sample
+    passes through unchanged while the chamber produces a signal proportional
+    to the tritium concentration, scaled by a detection efficiency.
+
+    Mathematical Formulation
+    -------------------------
+    The chamber receives a tritium flux and flow rate, computes the
+    concentration, and applies the detection efficiency:
+
+    .. math::
+
+        c = \\frac{\\Phi_{in}}{\\dot{V}}
+
+    .. math::
+
+        \\text{signal} = \\varepsilon(c) \\cdot c
+
+    .. math::
+
+        \\Phi_{out} = \\Phi_{in}
+
+    where :math:`\\varepsilon` is the detection efficiency (constant or
+    concentration-dependent).
+
+    Parameters
+    ----------
+    detection_efficiency : float or callable, optional
+        Constant efficiency factor or a function ``f(c) -> float`` that
+        returns the efficiency for a given concentration. Mutually
+        exclusive with *detection_threshold*.
+    detection_threshold : float, optional
+        If provided, the efficiency is a step function: 1 above the
+        threshold, 0 below. Mutually exclusive with *detection_efficiency*.
+    """
+
+    input_port_labels: ClassVar[dict[str, int]] = {
+        "flux_in": 0,
+        "flow_rate": 1,
+    }
+
+    output_port_labels: ClassVar[dict[str, int]] = {
+        "flux_out": 0,
+        "signal": 1,
+    }
+
+    def __init__(self, detection_efficiency=None, detection_threshold=None):
+
+        # input validation
+        if detection_efficiency is not None and detection_threshold is not None:
+            raise ValueError(
+                "Specify either 'detection_efficiency' or 'detection_threshold', not both"
+            )
+        if detection_efficiency is None and detection_threshold is None:
+            raise ValueError(
+                "One of 'detection_efficiency' or 'detection_threshold' must be provided"
+            )
+
+        if detection_threshold is not None:
+            self.detection_efficiency = lambda c: (
+                1.0 if c >= detection_threshold else 0.0
+            )
+        else:
+            self.detection_efficiency = detection_efficiency
+
+        self.detection_threshold = detection_threshold
+
+        super().__init__(func=self._eval)
+
+    def _eval(self, flux_in, flow_rate):
+        concentration = flux_in / flow_rate if flow_rate > 0 else 0.0
+
+        eff = self.detection_efficiency
+        epsilon = eff(concentration) if callable(eff) else eff
+
+        signal = epsilon * concentration
+        flux_out = flux_in
+
+        return (flux_out, signal)

pathsim_fusion-0.1.0.dist-info/METADATA

@@ -0,0 +1,107 @@
+Metadata-Version: 2.4
+Name: pathsim-fusion
+Version: 0.1.0
+Summary: Fusion fuel cycle and balance-of-plant blocks for PathSim
+Author: PathSim Contributors
+License: MIT
+Project-URL: Homepage, https://pathsim.org
+Project-URL: Documentation, https://docs.pathsim.org/fusion
+Project-URL: Repository, https://github.com/pathsim/pathsim-fusion
+Project-URL: Issues, https://github.com/pathsim/pathsim-fusion/issues
+Keywords: simulation,pathsim,block diagram,fusion,tritium,fuel cycle,balance of plant
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering
+Classifier: Topic :: Scientific/Engineering :: Physics
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: pathsim>=0.23
+Requires-Dist: numpy>=1.15
+Requires-Dist: scipy>=1.2
+Provides-Extra: test
+Requires-Dist: pytest>=7.0; extra == "test"
+Requires-Dist: pytest-cov>=4.0; extra == "test"
+Provides-Extra: lint
+Requires-Dist: ruff==0.17.3; extra == "lint"
+Dynamic: license-file
+
+<p align="center">
+  <strong>Fusion fuel cycle and balance-of-plant blocks for PathSim</strong>
+</p>
+
+<p align="center">
+  <a href="https://pypi.org/project/pathsim-fusion/"><img src="https://img.shields.io/pypi/v/pathsim-fusion" alt="PyPI"></a>
+  <img src="https://img.shields.io/github/license/pathsim/pathsim-fusion" alt="License">
+</p>
+
+<p align="center">
+  <a href="https://pathsim.org">Homepage</a> &bull;
+  <a href="https://docs.pathsim.org/fusion">Documentation</a> &bull;
+  <a href="https://github.com/pathsim/pathsim-fusion">GitHub</a>
+</p>
+
+---
+
+PathSim-Fusion extends the [PathSim](https://github.com/pathsim/pathsim)
+simulation framework with specialized blocks. All blocks follow the standard
+PathSim block interface and can be connected into simulation diagrams.
+
+## Blocks
+
+| Block | Description | Key Parameters |
+|-------|-------------|----------------|
+| `IonisationChamber` | Flow-through tritium ionisation chamber (signal = ε(c)·c, flux passes through) | `detection_efficiency`, `detection_threshold` |
+| `Bubbler4` | Four-vial tritium sampling bubbler (soluble + insoluble chains, catalytic conversion, scheduled vial replacement) | `conversion_efficiency`, `vial_efficiency`, `replacement_times` |
+| `GLC` | Counter-current bubble-column gas–liquid contactor for tritium extraction from LiPb (Malara 1995, on `BVP1D`) | `P_in`, `L`, `D`, `T`, `BCs` |
+
+## Install
+
+```bash
+pip install pathsim-fusion
+```
+
+## Quick Example
+
+```python
+from pathsim import Simulation, Connection
+from pathsim.blocks import Constant, Source, Scope
+from pathsim_fusion import IonisationChamber
+
+flux = Source(lambda t: 1e-3 * float(t > 1))  # tritium flux, step at t = 1
+flow = Constant(0.5)  # carrier gas flow rate
+ic = IonisationChamber(detection_efficiency=0.9)
+sco = Scope(labels=["flux", "signal"])
+
+sim = Simulation(
+    blocks=[flux, flow, ic, sco],
+    connections=[
+        Connection(flux, ic["flux_in"], sco[0]),
+        Connection(flow, ic["flow_rate"]),
+        Connection(ic["signal"], sco[1]),
+    ],
+    dt=0.01,
+)
+sim.run(5)
+sco.plot()
+```
+
+## Development
+
+```bash
+pip install -e ".[test,lint]" mypy
+ruff check .                # lint
+ruff format .               # format
+mypy src/pathsim_fusion    # type check
+pytest tests/ -v            # run tests
+```
+
+## License
+
+MIT

pathsim_fusion-0.1.0.dist-info/RECORD

@@ -0,0 +1,11 @@
+pathsim_fusion/__init__.py,sha256=F88HTQsTCXwmZPNozrCBiANCDTPe69kO3DmAcDKb_U4,969
+pathsim_fusion/_version.py,sha256=n_5vdJsPNu7wZ57LGuRL585uvll-hiuvZUBWzdG0RQU,520
+pathsim_fusion/tritium/__init__.py,sha256=4mbaMbYeRI2EgSvMHzwauO7WYtPscnn8zDz9yHoiNGA,153
+pathsim_fusion/tritium/bubbler.py,sha256=xoaUH6szfOpizWwPZCI2q_A3RlsIWI9csgDYxBF3auw,8418
+pathsim_fusion/tritium/glc.py,sha256=4ws9fUYReNOEdSKz3cXhwlnhEa2lPy_HEOtQgnXDYec,19018
+pathsim_fusion/tritium/ionisation_chamber.py,sha256=rX46wbtd0Q6DSpPd_6gjv1MXOycfmSUtVSeeDplgeZA,3134
+pathsim_fusion-0.1.0.dist-info/licenses/LICENSE,sha256=DWjTGX2hLZpbN3i93RTs1I-Re_5M0hzlVim9eZHR-VQ,1064
+pathsim_fusion-0.1.0.dist-info/METADATA,sha256=dK6Fr__VH--LG65YL4liSFqgXCStbcSYDZmQHzGwC4A,3655
+pathsim_fusion-0.1.0.dist-info/WHEEL,sha256=mOdXR9C3wMVov7cSY8PY-XCzo3SmmWCHvGQr5csJoao,91
+pathsim_fusion-0.1.0.dist-info/top_level.txt,sha256=VfTTVYMISbz-u9KbkwKeecGlhDXjvJtMoFlu0Gtj6f8,15
+pathsim_fusion-0.1.0.dist-info/RECORD,,

pathsim_fusion-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.2.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

pathsim_fusion-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 PathSim
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

pathsim_fusion-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+pathsim_fusion