psdm 0.1.0__py3-none-any.whl

psdm/__init__.py

@@ -0,0 +1,31 @@
+"""Pore and Surface Diffusion Model (PSDM) for fixed-bed adsorbers."""
+
+from . import fullscale
+from .capacity import CapacityEstimate, estimate_capacity
+from .fitting import DsFitResult, FitResult, fit_freundlich, fit_surface_diffusivity, sum_of_squares
+from .isotherms import IsothermFit, fit_isotherm
+from .model import Column, Compound
+from .solver import Result, simulate
+from .uncertainty import Uncertainty, model_uncertainty
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "CapacityEstimate",
+    "Column",
+    "Compound",
+    "DsFitResult",
+    "FitResult",
+    "IsothermFit",
+    "Result",
+    "Uncertainty",
+    "__version__",
+    "estimate_capacity",
+    "fit_freundlich",
+    "fit_isotherm",
+    "fit_surface_diffusivity",
+    "fullscale",
+    "model_uncertainty",
+    "simulate",
+    "sum_of_squares",
+]

psdm/capacity.py

@@ -0,0 +1,279 @@
+"""Adsorbent capacity from column breakthrough data when ``K`` is unknown.
+
+The loading at breakthrough follows from a mass balance over the column,
+
+.. math::
+
+    q = \\frac{Q}{M} \\int_0^{t_b} \\left(C_{in}(t) - C_{out}(t)\\right) dt,
+
+and a Freundlich ``K`` for an assumed ``1/n`` from :math:`K = q / \\bar C^{1/n}` with
+:math:`\\bar C` the mean influent concentration up to breakthrough :math:`t_b`. When the
+effluent has not yet reached the influent concentration, :math:`t_b` is extrapolated with a
+logistic curve or a straight line, as in ``PSDM.__calculate_capacity`` of the US EPA code.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+import numpy as np
+import pandas as pd
+from scipy.optimize import curve_fit
+from scipy.stats import linregress
+
+from . import units
+from .model import Column
+
+MAX_BREAKTHROUGH_DAYS = 2000.0
+"""Extrapolated breakthrough times are capped at this many days."""
+
+MIN_LOADING = 1e-6
+"""Smallest loading (ug/g) returned when a breakthrough was found."""
+
+METHODS = (
+    "breakthrough",
+    "exceeds mean influent",
+    "logistic",
+    "linear, single point",
+    "linear regression",
+    "minimum",
+)
+"""Possible values of :attr:`CapacityEstimate.method`.
+
+``breakthrough``
+    The effluent reached the influent concentration in the data.
+``exceeds mean influent``
+    The effluent reached the mean influent concentration in the data.
+``logistic``
+    Breakthrough extrapolated with :func:`logistic` (99 % of the plateau).
+``linear, single point`` and ``linear regression``
+    Breakthrough extrapolated with a straight line through the last effluent points.
+``minimum``
+    Too few non-zero effluent values; the whole data period is used, so ``q`` and ``K``
+    are lower bounds.
+"""
+
+
+@dataclass(frozen=True)
+class CapacityEstimate:
+    """Output of :func:`estimate_capacity`.
+
+    Attributes
+    ----------
+    k
+        Freundlich ``K`` for :attr:`n_inv`, (ug/g)(L/ug)^(1/n).
+    n_inv
+        The assumed ``1/n``.
+    q
+        Adsorbent loading at breakthrough, ug/g.
+    mean_influent
+        Mean influent concentration up to breakthrough, in the data's concentration unit.
+    breakthrough_time
+        Time of (possibly extrapolated) breakthrough, in the data's time unit.
+    method
+        How the breakthrough time was found, one of :data:`METHODS`.
+    """
+
+    k: float
+    n_inv: float
+    q: float
+    mean_influent: float
+    breakthrough_time: float
+    method: str
+    _mean_influent_ug: float
+
+    def k_for(self, n_inv):
+        """Freundlich ``K`` that gives the same loading :attr:`q` for another ``1/n``."""
+        return self.q / self._mean_influent_ug ** np.asarray(n_inv, dtype=float)
+
+
+def logistic(t, c0: float, a: float, b: float):
+    """Logistic breakthrough curve ``c0 / (1 + exp(a - b t))``."""
+    return c0 / (1.0 + np.exp(a - b * np.asarray(t, dtype=float)))
+
+
+def _interp(t, xp, fp):
+    """Linear interpolation with linear extrapolation beyond both ends."""
+    t = np.asarray(t, dtype=float)
+    y = np.interp(t, xp, fp)
+    if len(xp) > 1:
+        lo, hi = t < xp[0], t > xp[-1]
+        y[lo] = fp[0] + (t[lo] - xp[0]) * (fp[1] - fp[0]) / (xp[1] - xp[0])
+        y[hi] = fp[-1] + (t[hi] - xp[-1]) * (fp[-1] - fp[-2]) / (xp[-1] - xp[-2])
+    return y
+
+
+def _with_point(t, c, t_new, c_new):
+    """Insert (or replace) the point ``(t_new, c_new)`` keeping ``t`` sorted."""
+    keep = t != t_new
+    t, c = np.append(t[keep], t_new), np.append(c[keep], c_new)
+    order = np.argsort(t, kind="stable")
+    return t[order], c[order]
+
+
+def _integral(t_end, t, c):
+    """Integral of the piecewise-linear (extrapolated) curve ``(t, c)`` from 0 to ``t_end``."""
+    knots = np.unique(np.concatenate([[0.0, t_end], t[(t > 0) & (t < t_end)]]))
+    y = _interp(knots, t, c)
+    return float(np.sum(0.5 * (y[1:] + y[:-1]) * np.diff(knots)))
+
+
+def _last_time(t, below=np.inf):
+    """Last positive, finite data time smaller than ``below`` (``0`` if there is none)."""
+    ok = t[np.isfinite(t) & (t > 0) & (t < below)]
+    return float(ok[-1]) if len(ok) else 0.0
+
+
+def _breakthrough(t, c_in, c_out, mean_in, grid, cap):
+    """Find or extrapolate the breakthrough time (days).
+
+    Returns ``(time, method, t_in, c_in, t_out, c_out)``; the curves may gain an extra
+    extrapolated point at the breakthrough time.
+    """
+    duration = t[-1]
+    t_in, t_out = t.copy(), t.copy()
+
+    nonzero = np.count_nonzero(c_out)
+    if nonzero == 0:
+        return duration, "minimum", t_in, c_in, t_out, c_out
+    if nonzero == 1 and not (c_out[-1] > 0 and c_out[-1] / mean_in >= 0.25):
+        # a single non-zero value that is not a high last point cannot be extrapolated
+        return duration, "minimum", t_in, c_in, t_out, c_out
+
+    if c_out.max() >= c_in.min():
+        f_in, f_out = _interp(grid, t, c_in), _interp(grid, t, c_out)
+        checks = ((f_out >= f_in, "breakthrough"), (f_out >= mean_in, "exceeds mean influent"))
+        for crossed, method in checks:
+            if crossed.any():
+                time = max(grid[np.argmax(crossed)] - (grid[1] - grid[0]), 0.0)  # last before
+                return time, method, t_in, c_in, t_out, c_out
+
+    try:
+        lo, hi = min(0.99 * mean_in, c_out[0]), max(mean_in, c_out[0])
+        params, _ = curve_fit(
+            logistic,
+            t,
+            c_out,
+            p0=(mean_in, 5.0, 0.1),
+            bounds=((lo, 0.0, 0.0), (hi, 1e3, 1.0)),
+            maxfev=10000,
+        )
+    except (RuntimeError, ValueError):
+        params = None
+    if params is not None:
+        time = float(np.round((params[1] + np.log(99.0)) / params[2]))
+        if time >= duration:
+            t_in, c_in = _with_point(t_in, c_in, time, mean_in)
+            t_out, c_out = _with_point(t_out, c_out, time, logistic(time, *params))
+            return (duration if time > cap else time), "logistic", t_in, c_in, t_out, c_out
+        if time > 0.25 * duration:
+            return time, "logistic", t_in, c_in, t_out, c_out
+
+    if c_out[-1] > 0 and c_out[-1] / mean_in >= 0.25 and len(t) > 1:
+        method = "linear, single point"
+        slope = c_out[-1] / (t[-1] - t[-2])
+        intercept = -c_out[-1] * t[-2] / (t[-1] - t[-2])
+    else:
+        method = "linear regression"
+        n = np.count_nonzero(c_out)
+        if n < len(c_out) and c_out[-(n + 1)] != 0:
+            n += 1
+        slope, intercept = linregress(t[-(n + 1) :], c_out[-(n + 1) :])[:2]
+    with np.errstate(divide="ignore", invalid="ignore"):
+        time = float(np.round((mean_in - intercept) / slope))
+    if not np.isfinite(time):
+        return _last_time(t), method, t_in, c_in, t_out, c_out
+    if time <= 0:
+        time = _last_time(t)
+    t_in, c_in = _with_point(t_in, c_in, time, mean_in)
+    t_out, c_out = _with_point(t_out, c_out, time, mean_in)
+    return time, method, t_in, c_in, t_out, c_out
+
+
+def estimate_capacity(
+    column: Column,
+    influent: pd.Series,
+    effluent: pd.Series,
+    *,
+    n_inv: float = 0.45,
+    time_unit: str = "days",
+    conc_unit: str = "ug/L",
+    resolution: float = 1.0,
+) -> CapacityEstimate:
+    """Estimate Freundlich ``K`` from a breakthrough curve for an assumed ``1/n``.
+
+    The breakthrough time is the last time before the effluent reaches the influent (or
+    mean influent) concentration. If the effluent never gets there, a logistic curve
+    ``C0 / (1 + exp(a - b t))`` (``t`` in days) is fitted to the effluent and breakthrough is
+    taken at 99 % of ``C0``; if that fails or predicts breakthrough in the first quarter of
+    the data, a straight line through the last effluent points is extrapolated to the mean
+    influent concentration. Extrapolated breakthrough beyond :data:`MAX_BREAKTHROUGH_DAYS`
+    falls back to the end of the data. The loading ``q`` is the integral of influent minus
+    effluent (linearly interpolated, with the extrapolated point appended) up to
+    breakthrough, times flow rate over adsorbent mass.
+
+    This is ``PSDM.__calculate_capacity`` of the US EPA code with ``break_type='calc'``.
+
+    Parameters
+    ----------
+    column
+        The adsorber; only ``flow_rate`` and ``mass`` are used.
+    influent, effluent
+        Concentrations of one compound indexed by time (sharing the same time points, e.g.
+        :attr:`psdm.io.Dataset.influent` and ``effluent`` columns).
+    n_inv
+        Assumed Freundlich ``1/n``; use :meth:`CapacityEstimate.k_for` for other values.
+    time_unit, conc_unit
+        Units of the index and values of ``influent`` and ``effluent``.
+    resolution
+        Time step, in days, of the search for the breakthrough time.
+
+    Returns
+    -------
+    CapacityEstimate
+    """
+    if not resolution > 0:
+        raise ValueError("resolution must be positive")
+    infl = influent.astype(float).sort_index()
+    effl = effluent.astype(float).sort_index()
+    if not infl.index.equals(effl.index):
+        effl = effl.reindex(infl.index).interpolate(method="index", limit_direction="both")
+    if len(infl) < 2:
+        raise ValueError("influent and effluent need at least two time points")
+    if infl.isna().any() or effl.isna().any():
+        raise ValueError("influent and effluent must not contain missing values")
+    c_in = infl.to_numpy().copy()
+    c_out = effl.to_numpy().copy()
+    if c_in.sum() <= 0:
+        raise ValueError("the influent contains no mass")
+    c_in[c_in == 0] = 1e-3  # as upstream; avoids a zero mean concentration
+
+    t_mult = units.factor("time", time_unit)  # -> minutes
+    c_mult = units.factor("concentration", conc_unit)  # -> ug/L
+    t = infl.index.to_numpy(dtype=float) * t_mult / units.MIN_PER_DAY  # days
+    mean_in = float(c_in.mean())
+    grid = np.arange(0.0, t[-1] + resolution, resolution)
+
+    time, method, t_in, c_in, t_out, c_out = _breakthrough(
+        t, c_in, c_out, mean_in, grid, MAX_BREAKTHROUGH_DAYS
+    )
+    if time > MAX_BREAKTHROUGH_DAYS:
+        time = _last_time(t, MAX_BREAKTHROUGH_DAYS)
+    elif time == 0:
+        time = resolution  # breakthrough cannot be immediate
+
+    # loading in ug/g: (conc · day) · (ug/L per conc) · (L/day) / g
+    flow_l_per_day = column.flow_rate / 1e3 * units.MIN_PER_DAY
+    q = (_integral(time, t_in, c_in) - _integral(time, t_out, c_out)) * c_mult
+    q = max(q * flow_l_per_day / column.mass, MIN_LOADING)
+    mean = float(np.mean(_interp(grid[grid <= time], t_in, c_in)))
+    mean_ug = mean * c_mult
+    return CapacityEstimate(
+        k=float(q / mean_ug**n_inv),
+        n_inv=float(n_inv),
+        q=float(q),
+        mean_influent=mean,
+        breakthrough_time=time * units.MIN_PER_DAY / t_mult,
+        method=method,
+        _mean_influent_ug=mean_ug,
+    )

psdm/collocation.py

@@ -0,0 +1,144 @@
+"""Orthogonal collocation operators for the particle (radial) and bed (axial) coordinates."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+import numpy as np
+from scipy import sparse, special
+
+
+@dataclass(frozen=True)
+class Collocation:
+    """Discretisation operators.
+
+    Attributes
+    ----------
+    nr
+        Radial collocation points, including the particle surface.
+    nz
+        Axial points in the whole bed (``ne * nz_element - (ne - 1)``).
+    wr
+        Radial quadrature weights, shape ``(nr,)``.
+    br
+        Radial Laplacian operator for a sphere, shape ``(nr, nr)``.
+    az
+        Axial first-derivative operator, shape ``(nz, nz)``.
+    """
+
+    nr: int
+    nz: int
+    wr: np.ndarray
+    br: np.ndarray
+    az: np.ndarray
+
+
+def _radial(nr: int) -> tuple[np.ndarray, np.ndarray]:
+    """Symmetric (sphere) polynomials in ``r**2`` at Jacobi roots plus the surface."""
+    a = 3  # spherical geometry
+    rr = 0.5 * (special.roots_jacobi(nr - 1, 1.0, 0.5)[0] + 1.0)
+    r = np.sqrt(np.append(rr, 1.0))
+
+    powers = np.arange(nr)
+    q = r[:, None] ** (2 * powers)
+    d = np.zeros((nr, nr))
+    for i in range(1, nr):
+        d[:, i] = (2 * i) * (2 * i - 2 + a) * r ** (2 * i - 2)
+    f = 1.0 / (2.0 * powers + a)
+    qinv = np.linalg.inv(q)
+    return f @ qinv, d @ qinv
+
+
+def _lagrange_derivative(x: np.ndarray) -> np.ndarray:
+    """First-derivative collocation matrix on points ``x`` via the monomial basis."""
+    n = len(x)
+    powers = np.arange(n)
+    q = x[:, None] ** powers
+    c = np.zeros((n, n))
+    c[:, 1:] = powers[1:] * x[:, None] ** (powers[1:] - 1)
+    return c @ np.linalg.inv(q)
+
+
+def _axial_single(nz: int) -> np.ndarray:
+    z = np.concatenate([[0.0], special.roots_sh_legendre(nz - 2)[0], [1.0]])
+    # monomials in (2z - 1) are better conditioned than in z; the operator is identical
+    s = 2.0 * z - 1.0
+    return 2.0 * _lagrange_derivative(s)
+
+
+def _axial_elements(ne: int, nz: int) -> np.ndarray:
+    """Orthogonal collocation on ``ne`` finite elements, continuity at shared nodes."""
+    a = _lagrange_derivative(np.concatenate([[0.0], special.roots_sh_legendre(nz - 2)[0], [1.0]]))
+    z = ne * a
+    n_total = ne * nz - (ne - 1)
+    op = np.zeros((n_total, n_total))
+    for k in range(ne):
+        lo = k * (nz - 1)
+        op[lo : lo + nz, lo : lo + nz] = z
+    # rows where elements meet: enforce continuity of the first derivative
+    q = a[-1, -1] - a[0, 0]
+    for k in range(ne - 1):
+        start = k * (nz - 1)
+        shared = (k + 1) * (nz - 1)
+        op[shared, :] = 0.0
+        op[shared, start:shared] = z[-1, :-1] - z[-1, -1] / q * a[-1, :-1]
+        op[shared, shared + 1 : shared + nz] = z[-1, -1] / q * a[0, 1:]
+    op[0, :] = 0.0  # constant inlet boundary
+    return op
+
+
+def build(nr: int, nz: int, ne: int = 1) -> Collocation:
+    """Build collocation operators.
+
+    Parameters
+    ----------
+    nr
+        Number of radial collocation points (including the surface).
+    nz
+        Number of axial collocation points per element (including both ends).
+    ne
+        Number of axial finite elements.
+    """
+    if nr < 2 or nz < 3 or ne < 1:
+        raise ValueError("need nr >= 2, nz >= 3 and ne >= 1")
+    wr, br = _radial(nr)
+    az = _axial_single(nz) if ne == 1 else _axial_elements(ne, nz)
+    return Collocation(nr=nr, nz=az.shape[0], wr=wr, br=br, az=az)
+
+
+def jacobian_sparsity(n_comp: int, nr: int, nz: int) -> sparse.csr_matrix:
+    """Sparsity pattern of the PSDM right-hand side.
+
+    The state is ordered ``(compound, radial node + bulk, axial node)``; ``nz`` is the total
+    number of axial nodes. Particle nodes couple to every particle node of every compound at
+    the same axial position (competitive equilibrium) and to their own bulk concentration;
+    bulk nodes couple to the bulk along the axis and to the particle surface.
+    """
+    shape = (n_comp, nr + 1, nz)
+    index = np.arange(np.prod(shape)).reshape(shape)
+    rows, cols = [], []
+
+    def connect(r, c):
+        r, c = np.broadcast_arrays(r, c)
+        rows.append(r.ravel())
+        cols.append(c.ravel())
+
+    particle = index[:, :nr, :]  # (n_comp, nr, nz)
+    bulk = index[:, nr, :]  # (n_comp, nz)
+    # particle <-> all particle nodes (all compounds) at the same z
+    for z in range(nz):
+        p = particle[:, :, z].ravel()
+        connect(p[:, None], p[None, :])
+    # surface <-> own bulk
+    connect(particle[:, nr - 1, 1:], bulk[:, 1:])
+    # bulk <-> bulk along the axis, own compound
+    for c in range(n_comp):
+        connect(bulk[c, 1:, None], bulk[c, None, 1:])
+    # bulk <-> surface of every compound at the same z
+    for z in range(1, nz):
+        connect(bulk[:, z, None], particle[:, nr - 1, z][None, :])
+
+    n = index.size
+    data = np.ones(sum(len(r) for r in rows), dtype=bool)
+    mat = sparse.coo_matrix((data, (np.concatenate(rows), np.concatenate(cols))), shape=(n, n))
+    return mat.tocsr()

psdm/correlations.py

@@ -0,0 +1,70 @@
+"""Film mass-transfer correlations.
+
+Each correlation returns the Sherwood number ``Sh = kf * d_p / D_l``; :func:`film_transfer`
+turns it into the film transfer coefficient ``kf`` (cm/s). Correlations are collected from
+Xu et al. (2013), *J. Zhejiang Univ. Sci. A* 14(3):155–176.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+
+import numpy as np
+
+
+def _ohashi(re, sc, ebed):
+    re = np.asarray(re, dtype=float)
+    regimes = [re < 5.8, re < 500]
+    coef = np.select(regimes, [1.58, 1.21], 0.59)
+    exponent = np.select(regimes, [0.4, 0.5], 0.6)
+    return 2.0 + coef * re**exponent * sc ** (1 / 3)
+
+
+def _gnielinski(re, sc, ebed):
+    sh_lam = 0.644 * re**0.5 * sc ** (1 / 3)
+    sh_turb = 0.037 * re**0.8 * sc / (1.0 + 2.443 * re**-0.1 * (sc ** (2 / 3) - 1.0))
+    return (2.0 + np.sqrt(sh_lam**2 + sh_turb**2)) * (1.0 + 1.5 * (1.0 - ebed))
+
+
+SHERWOOD: dict[str, Callable] = {
+    # Chern & Chien (2002), modified Gnielinski -- the PSDM/AdDesignS default
+    "Chern and Chien": lambda re, sc, eb: (
+        (1 + 1.5 * (1 - eb)) * (2 + 0.644 * re**0.5 * sc ** (1 / 3))
+    ),
+    "Gnielinski": _gnielinski,
+    "Tan et al": lambda re, sc, eb: 1.1 / eb * (re * sc) ** (1 / 3),
+    "Wilson and Geankoplis": lambda re, sc, eb: 1.09 / eb * (re * sc) ** (1 / 3),
+    "Ohashi et al": _ohashi,
+    "Williamson et al": lambda re, sc, eb: 2.4 * eb * re**0.3 * sc**0.42,
+    "Ko et al": lambda re, sc, eb: 0.325 / (eb * re**0.36 * sc ** (1 / 3)),
+    "Wakao and Funazkri": lambda re, sc, eb: 2 + 1.1 * re**0.6 * sc ** (1 / 3),
+    "Kataoka et al": lambda re, sc, eb: 1.85 * ((1 - eb) / eb) ** (1 / 3) * (re * sc) ** (1 / 3),
+}
+"""Available Sherwood-number correlations, keyed by name."""
+
+
+def film_transfer(
+    diffusivity, radius: float, re: float, sc, ebed: float, correlation: str = "Chern and Chien"
+):
+    """Film transfer coefficient ``kf`` (cm/s).
+
+    Parameters
+    ----------
+    diffusivity
+        Liquid diffusivity, cm²/s.
+    radius
+        Adsorbent particle radius, cm.
+    re, sc
+        Particle Reynolds and Schmidt numbers.
+    ebed
+        Bed void fraction.
+    correlation
+        Key of :data:`SHERWOOD`.
+    """
+    try:
+        sherwood = SHERWOOD[correlation]
+    except KeyError:
+        raise ValueError(
+            f"unknown correlation {correlation!r}; expected one of {sorted(SHERWOOD)}"
+        ) from None
+    return diffusivity / (2.0 * radius) * sherwood(re, sc, ebed)