dynamodels 0.3.2__tar.gz → 0.3.3__tar.gz

{dynamodels-0.3.2/dynamodels.egg-info → dynamodels-0.3.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: dynamodels
-Version: 0.3.2
+Version: 0.3.3
 Summary: Dynamical-system models with history tracking and pluggable integrators (Lorenz, Van der Pol, Rijke, annular combustor, KS)
 Author-email: Andrea Nóvoa <a.novoa@imperial.ac.uk>
 License-Expression: MIT

{dynamodels-0.3.2 → dynamodels-0.3.3}/dynamodels/__init__.py

@@ -17,7 +17,7 @@ from .history import HistoryTracker
 from .integrator import ConstantIntegrator, DiscreteIntegrator, Integrator, IVPIntegrator
 from .model import Model
 
-__version__ = "0.3.2"
+__version__ = "0.3.3"
 
 __all__ = [
     "Model",

{dynamodels-0.3.2 → dynamodels-0.3.3}/dynamodels/physical/kuramoto_sivashinsky.py

@@ -20,9 +20,8 @@ class KS(Model):
     u_t + u_{xx} + \nu\, u_{xxxx} + u\,u_x = 0, \qquad x \in (0, L],
     $$
 
-    with periodic boundary conditions $u(t, 0) = u(t, L)$, $u_x(t, 0) = u_x(t, L)$,
-    and $\nu = (2\pi/L)^2$. Solved with the ETDRK4 scheme in Fourier space, where the
-    Fourier transform pair is
+    with periodic boundary conditions $u(t, 0) = u(t, L)$, $u_x(t, 0) = u_x(t, L)$.
+    Solved with the ETDRK4 scheme in Fourier space, where the Fourier transform pair is
 
     $$
     \hat{u}(k) = \mathcal{F}[u(x)] = \frac{1}{L}\int_0^L u(x)\,e^{-ikx}\,\mathrm{d}x,
@@ -30,8 +29,27 @@ class KS(Model):
     u(x) = \mathcal{F}^{-1}[\hat{u}(k)] = \sum_k \hat{u}(k)\,e^{ikx}.
     $$
 
-    The nonlinear term $u\,u_x$ is computed in physical space and transformed back to
-    Fourier space at every stage.
+    On the $N_x$-point grid the wavenumbers are $\alpha_j = 2\pi j / L$, so the
+    (diagonal) linear operator is $\alpha_j^2 - \nu\,\alpha_j^4$ and the nonlinear
+    term $u\,u_x$ is computed in physical space and transformed back to Fourier
+    space at every stage.
+
+    **Parametrization ($\nu$, $L$).** The pair is independent: whichever of the two
+    is given fixes that side of the operator.
+
+    - `nu` only (the default): the domain follows the standard nondimensionalization
+      $L = 2\pi/\sqrt{\nu}$, and the equation is then integrated in its $\nu = 1$
+      form on that domain -- so `self.nu` is **1** afterwards and the stored
+      $(N_x, \nu, L)$ always describes the operator that was actually integrated
+      (this is what makes `ntsa.respawn`, which rebuilds from `fixed_params`,
+      bit-faithful).
+    - `L` only: $\nu = 1$ on the given domain.
+    - **both**: both are honoured as given, i.e. the genuine two-parameter system
+      $u_t + u_{xx} + \nu u_{xxxx} + u u_x = 0$ on $(0, L]$.
+
+    The one- and two-parameter forms are related by $v(x', t') = \sqrt{\nu}\,u(x, t)$
+    with $x = \sqrt{\nu}\,x'$ and $t = \nu\,t'$: `KS(Nx, L=Lx, nu=visc, dt=dt)` and
+    `KS(Nx, L=Lx/sqrt(visc), dt=dt/visc)` describe the same physical system.
     """
 
     # name: str = 'KS'
@@ -42,6 +60,7 @@ class KS(Model):
     Nx = 256             # Spatial discretization
     nu = 0.08            # 'Viscosity' parameter of the KS equation.
     L = -1         # Domain length (0, L] NB. Will be set to 2*pi/sqrt(nu) if not specified.
+    # (nu, L) resolution rules: see the class docstring. Passing BOTH keeps both.
 
     initial_amplitude = 0.01
 
@@ -63,6 +82,9 @@ class KS(Model):
 
             - ``Nx`` : int, number of spatial grid points (must be even).
             - ``nu`` : float, viscosity parameter.
+            - ``L`` : float, domain length, domain is (0, L].
+              ``nu`` and ``L`` are independent -- see the class docstring for the
+              resolution rules when only one of them is given.
             - ``dt`` : float, time step size.
             - ``initial_amplitude`` : float, amplitude of the initial condition.
             - ``Nq`` : int, number of sensors.
@@ -72,6 +94,10 @@ class KS(Model):
         """
 
 
+        # 'nu' has a non-sentinel class default, so an EXPLICIT nu is what marks the
+        # two-parameter form; 'L' uses its non-positive class default as the sentinel.
+        nu_given = model_dict.get('nu') is not None
+
         for key in list(model_dict.keys()):
             if key in vars(KS):
                 setattr(self, key, model_dict.pop(key))
@@ -80,17 +106,24 @@ class KS(Model):
         if self.Nx % 2 != 0:
             raise ValueError("Nx must be even.")
 
-        if self.L is None or self.L <= 0 and self.nu is None:
+        L_given = self.L is not None and self.L > 0
+
+        if not L_given and not nu_given and self.nu is None:
             raise ValueError("Either L or nu must be specified.")
-        elif self.L is None or self.L <= 0:
+        elif not L_given:
+            # nu alone: standard nondimensionalization. The domain absorbs nu and the
+            # equation is integrated in its nu = 1 form, so (Nx, nu, L) stays a faithful
+            # description of the operator (respawn / filename keying).
             self.L = 2 * np.pi / np.sqrt(self.nu)
-        else:
             self.nu = 1.
+        elif not nu_given:
+            self.nu = 1.
+        # else: both given -- honour both (general two-parameter form).
 
         assert self.L is not None and self.L > 0, "L must be positive."
         assert self.nu is not None and self.nu > 0, "nu must be positive."
 
-        # Define Fourier wavenumbers k on the nondimensional domain
+        # Fourier wavenumbers alpha_j = 2 pi j / L on the domain (0, L]
         self.k = 2 * np.pi * np.fft.rfftfreq(self.Nx, d=self.L / self.Nx)
 
         dt_requested = model_dict.pop('dt', 0.25)
@@ -238,10 +271,10 @@ class KS(Model):
 
     @property
     def __linear_operator(self):
-        # ÷ Fourier multipliers for linear term
-        # return (self.k**2 - self.nu * self.k**4)[:, None]
-        # else:
-        return (self.k**2 - self.k**4)[:, None]
+        # Fourier multipliers of the linear term: alpha^2 - nu alpha^4, with
+        # alpha = self.k = 2 pi j / L. The single-parameter forms resolve nu to 1
+        # in __init__, so this reduces to alpha^2 - alpha^4 for them.
+        return (self.k**2 - self.nu * self.k**4)[:, None]
 
 
     @property

{dynamodels-0.3.2 → dynamodels-0.3.3/dynamodels.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: dynamodels
-Version: 0.3.2
+Version: 0.3.3
 Summary: Dynamical-system models with history tracking and pluggable integrators (Lorenz, Van der Pol, Rijke, annular combustor, KS)
 Author-email: Andrea Nóvoa <a.novoa@imperial.ac.uk>
 License-Expression: MIT

{dynamodels-0.3.2 → dynamodels-0.3.3}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "dynamodels"
-version = "0.3.2"
+version = "0.3.3"
 description = "Dynamical-system models with history tracking and pluggable integrators (Lorenz, Van der Pol, Rijke, annular combustor, KS)"
 readme = "README.md"
 requires-python = ">=3.10"

{dynamodels-0.3.2 → dynamodels-0.3.3}/tests/test_physical.py

@@ -2,6 +2,7 @@
 import sys
 
 import numpy as np
+import pytest
 
 import dynamodels
 from dynamodels.physical import KS, KS2D, Annular, Lorenz63, Lorenz96, Rijke, VdP
@@ -134,9 +135,65 @@ def test_ks_dt_honored_and_param_roundtrip():
     assert m.dt == 0.1
     _, t = m.time_integrate(Nt=5)
     assert np.isclose(t[1] - t[0], 0.1)
-    # (Nx, nu, L) are fixed_params so a respawn-style rebuild is bit-faithful,
-    # including the L-given branch that normalizes nu to 1
+    # nu alone nondimensionalizes: the domain absorbs nu and the stored operator
+    # is the nu = 1 one, so (Nx, nu, L) keeps describing what was integrated.
+    assert m.nu == 1.0 and m.L == pytest.approx(2 * np.pi / np.sqrt(0.08))
+    # (Nx, nu, L) are fixed_params so a respawn-style rebuild is bit-faithful
     m2 = KS(Nx=64, dt=0.1, nu=m.nu, L=m.L, psi0=m.psi0.copy())
     pa, _ = m.time_step(Nt=50)
     pb, _ = m2.time_step(Nt=50)
     assert np.allclose(pa, pb)
+
+
+def test_ks_two_parameter_form_honors_both_nu_and_L():
+    # Regression: nu used to be silently forced to 1 whenever L was given, so an
+    # independent (visc, Lx) pair was inexpressible. Both must now survive, and the
+    # linear operator must be the general alpha^2 - nu alpha^4.
+    Nx, Lx, visc, dt = 64, 20 * np.pi, 0.37, 0.01
+    m = KS(Nx=Nx, dt=dt, L=Lx, nu=visc)
+    assert m.nu == visc and m.L == Lx
+
+    alpha = 2 * np.pi * np.arange(Nx // 2 + 1) / Lx
+    np.testing.assert_allclose(m.k, alpha, rtol=0, atol=1e-12)
+    # E = exp(dt * Lhat) is the exact exponential of the linear operator, so it
+    # exposes the operator the ETDRK4 coefficients were rebuilt from.
+    expected = np.exp(dt * (alpha**2 - visc * alpha**4))[:, None]
+    np.testing.assert_allclose(m.ETDRK4_f_terms['E'], expected, rtol=1e-14, atol=0)
+
+    # The single-parameter defaults keep their nu = 1 operator
+    m_L = KS(Nx=Nx, dt=dt, L=Lx)
+    assert m_L.nu == 1.0
+    np.testing.assert_allclose(m_L.ETDRK4_f_terms['E'],
+                               np.exp(dt * (alpha**2 - alpha**4))[:, None], rtol=1e-14, atol=0)
+
+
+def test_ks_two_parameter_form_matches_rescaled_construction():
+    # (visc, Lx) and the old nu = 1 rescaling describe the SAME physical system:
+    #   v(x', t') = sqrt(visc) u(x, t),  x = sqrt(visc) x',  t = visc t'
+    # so KS(Nx, L=Lx, nu=visc, dt=dt) and KS(Nx, L=Lx/sqrt(visc), dt=dt/visc) must
+    # agree after u = v / sqrt(visc) (and t = visc t').
+    # The qlROM ks1d quasi-periodic parameters. dt is finer than the case's own 0.1
+    # on purpose: the two constructions differ only by floating-point roundoff, and
+    # this system amplifies a 1e-15 perturbation to O(1) within t ~ 30 (verified with
+    # a perturbed IC on a SINGLE construction), so the comparison horizon has to stay
+    # inside the roundoff-dominated regime for the equivalence itself to be visible.
+    Nx, Lx, visc, dt, Nt = 128, 2 * np.pi, 16 / 71, 0.02, 300
+    s = np.sqrt(visc)
+    u0 = np.cos(Lx * np.arange(Nx) / Nx)
+
+    direct = KS(Nx=Nx, dt=dt, L=Lx, nu=visc, psi0=np.fft.rfft(u0)[:, None])
+    rescaled = KS(Nx=Nx, dt=dt / visc, L=Lx / s, psi0=np.fft.rfft(s * u0)[:, None])
+
+    assert direct.dt == dt and rescaled.dt == dt / visc
+
+    pa, ta = direct.time_step(Nt=Nt)
+    pb, tb = rescaled.time_step(Nt=Nt)
+
+    ua = KS.fourier_to_physical(pa)[:, :, 0]
+    ub = KS.fourier_to_physical(pb)[:, :, 0] / s
+    err = np.max(np.abs(ua - ub)) / np.max(np.abs(ua))
+    assert err < 1e-10, f'rescaling equivalence broken: rel err {err:.2e}'
+    # time also maps: t = visc * t' (the stamps themselves are rounded to
+    # precision_t by Model, so compare the exact steps they are built from)
+    assert visc * rescaled.dt == pytest.approx(direct.dt, rel=1e-14)
+    assert len(ta) == len(tb) == Nt + 1