dynamodels 0.2.1__tar.gz → 0.3.3__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: dynamodels
-Version: 0.2.1
+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.2.1 → 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.2.0"
+__version__ = "0.3.3"
 
 __all__ = [
     "Model",

{dynamodels-0.2.1 → dynamodels-0.3.3}/dynamodels/physical/__init__.py

@@ -1,5 +1,6 @@
 from .annular import Annular
 from .kuramoto_sivashinsky import KS
+from .kuramoto_sivashinsky_2d import KS2D
 from .lorenz63 import Lorenz63
 from .lorenz96 import Lorenz96
 from .rijke import Rijke
@@ -8,6 +9,7 @@ from .van_der_pol import VdP
 __all__ = [
     "Annular",
     "KS",
+    "KS2D",
     "Lorenz63",
     "Lorenz96",
     "Rijke",

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

@@ -3,8 +3,6 @@
 # %%
 
 
-import warnings
-
 import matplotlib.pyplot as plt
 import numpy as np
 from matplotlib import cm as cm
@@ -22,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,
@@ -32,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'
@@ -44,9 +60,12 @@ 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
 
+    # structural constructor params: carried by ntsa.respawn and encoded in filename
+    fixed_params = ['Nx', 'nu', 'L']
     extra_print_params = ['Nx']
     sensor_placement_method = 'grid'
 
@@ -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,20 +106,28 @@ 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)
 
-        self.dt = model_dict.pop('dt', 0.25)
+        dt_requested = model_dict.pop('dt', 0.25)
+        self.dt = dt_requested
 
 
         self.ETDRK4_f_terms = None  # This simply trigers the setter method.
@@ -112,7 +146,6 @@ class KS(Model):
 
 
         #   Init Model  #
-        dt = model_dict.pop('dt', 0.25)
         psi0 = model_dict.pop('psi0', None)
         if psi0 is None:
             # Initialize state in physical space and transform to spectral space
@@ -122,7 +155,14 @@ class KS(Model):
             psi0 = np.array(u_hat)
 
 
-        super().__init__(psi0=psi0, dt=dt, integrator_class=DiscreteIntegrator, **model_dict)
+        super().__init__(psi0=psi0, dt=self.dt, integrator_class=DiscreteIntegrator, **model_dict)
+
+        # Model's dt setter rounds to precision_t decimals, which silently perturbs
+        # timesteps with more significant digits (e.g. dt = 0.1 * 71 / 16). Keep the
+        # exact requested value for stepping (precision_t still governs time stamps)
+        # and rebuild the ETDRK4 coefficients with it.
+        self._dt = float(dt_requested)
+        self.ETDRK4_f_terms = None
 
 
     # _______________ Modified Model methods ________________ #
@@ -231,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
@@ -245,93 +285,74 @@ class KS(Model):
 
     @ETDRK4_f_terms.setter
     def ETDRK4_f_terms(self, _):
-        # Avoid division by zero for k=0 mode
+        """Kassam-Trefethen ETDRK4 coefficients (E, E2, Q, f1, f2, f3) per Fourier mode.
+
+        The exponentials are exact; the phi-function coefficients Q/f1/f2/f3 are
+        evaluated with the resolvent contour integral on the half circle |z| = 15
+        (M = 32 points, real-part symmetrization) around the origin -- the same
+        quadrature rule used for the dense-operator ETDRK4 coefficients in the
+        qlROM stack, so a Galerkin projection of this discretization reproduces
+        this model's discrete map. Note: for modes with |dt*L| > 15 (far outside
+        the contour) the quadrature returns ~0 instead of the tiny exact value;
+        those modes are overdamped (E ~ exp(dt*L) ~ 0) and their nonlinear-response
+        error is negligible, matching the established dense-operator behavior.
+        """
         L = self.__linear_operator
 
-        # Initialize coefficient arrays
-        terms = dict(
-            f1 = np.zeros((self.Nk, 1), dtype=complex),
-            f2 = np.zeros((self.Nk, 1), dtype=complex),
-            f3 = np.zeros((self.Nk, 1), dtype=complex),
-            E = np.exp(self.dt * L),
-            E2 = np.exp(self.dt * L / 2),
-            nonlinear_operator = self.__nonlinear_operator
+        M = 32          # contour quadrature points
+        R = 15.0        # contour radius
+        z = R * np.exp(1j * np.pi * (np.arange(1, M + 1) - 0.5) / M)   # (M,)
+        ez, ez2 = np.exp(z), np.exp(z / 2)
+
+        # resolvent 1/(z - dt*L) per (mode, contour point)
+        res = 1.0 / (z[np.newaxis, :] - self.dt * L)                    # (Nk, 1) -> (Nk, M)
+
+        hQ = ez2 - 1.0
+        hf1 = (-4.0 - z + ez * (4.0 - 3.0 * z + z**2)) / z**2
+        hf2 = (2.0 + z + ez * (z - 2.0)) / z**2
+        hf3 = (-4.0 - 3.0 * z - z**2 + ez * (4.0 - z)) / z**2
+
+        def _coef(h):
+            return self.dt * np.real(np.mean(h[np.newaxis, :] * res, axis=-1))[:, None]
+
+        self._ETDRK4_f_terms = dict(
+            E=np.exp(self.dt * L),
+            E2=np.exp(self.dt * L / 2),
+            Q=_coef(hQ),
+            f1=_coef(hf1),
+            f2=_coef(hf2),
+            f3=_coef(hf3),
+            nonlinear_operator=self.__nonlinear_operator,
         )
 
-        # Use vectorized computation with error handling
-        with np.errstate(divide='ignore', invalid='ignore', over='ignore'):
-
-            # Use Taylor series for small arguments to avoid numerical issues
-            M = 16  # Number of points for contour integral approximation
-            r = np.exp(1j * np.pi * (np.arange(1, M+1) - 0.5) / M)
-
-            LR = self.dt * L + r[np.newaxis, :]
 
-            f1 = (-4 - LR + np.exp(LR) * (4 - 3*LR + LR**2)) / LR**3
-            f2 = (2 + LR + np.exp(LR) * (-2 + LR)) / LR**3
-            f3 = (-4 - 3*LR - LR**2 + np.exp(LR) * (4 - LR)) / LR**3
 
+    @staticmethod
+    def ETDRK4_step(u_hat, nonlinear_operator, E, E2, Q, f1, f2, f3):
+        """
+        Standard Kassam-Trefethen ETDRK4 step:
 
-        # # Check for NaNs or Infs and replace with Taylor limits if needed
-        zero_mask = (L[:,0] <= 1e-10)
-        for key, val in zip(['f1', 'f2', 'f3'], [f1, f2, f3]):
-            val.astype(complex)
-
-            if key in ['f1', 'f2']:
-                terms[key][zero_mask] = self.dt * 0.5  # For intermediate steps
-            elif key == 'f3':
-                terms[key][zero_mask] = self.dt * (1/6) # For intermediate steps
-
-            for kk in range(self.Nk):
-                f = val[kk]
-                valid_mask = np.isfinite(f)
-                if np.any(valid_mask):
-                    terms[key][kk] = self.dt * np.real(np.mean(f))
-                else:
-                    warnings.warn(f"NaN or Inf detected in ETDRK4 coefficient {key}, replacing with Taylor limits")
-                    terms[key][kk] = self.dt / 6
-
-        # Store coefficients in the object
-        self._ETDRK4_f_terms = terms.copy()
-
+        a_n = exp(L h / 2) u_n + Q N(u_n)
+        b_n = exp(L h / 2) u_n + Q N(a_n)
+        c_n = exp(L h / 2) a_n + Q (2 N(b_n) - N(u_n))
 
+        u_{n+1} = exp(L h) u_n + f1 N(u_n) + 2 f2 (N(a_n) + N(b_n)) + f3 N(c_n)
 
-    @staticmethod
-    def ETDRK4_step(u_hat, nonlinear_operator, E, E2, f1, f2, f3):
-        """
-        ETDRK4 time-stepping scheme:
-
-        a_n = exp(L * dt/2) * u_n + L^{-1} * (exp(L * dt/2) - I) * N(u_n)
-        b_n = exp(L * dt/2) * u_n + L^{-1} * (exp(L * dt/2) - I) * N(a_n)
-        c_n = exp(L * dt/2) * a_n + L^{-1} * (exp(L * dt/2) - I) * (2 * N(b_n) - N(u_n))
-
-        u_{n+1} = exp(L * dt) * u_n
-                + dt^{-2} * L^{-3} * [
-                    (-4 - L h + exp(L h) * (4 - 3 L h + (L h)^2)) * N(u_n)
-                    + 2 * (2 + L h + exp(L h) * (-2 + L h)) * (N(a_n) + N(b_n))
-                    + (-4 - 3 L h - (L h)^2 + exp(L h) * (4 - L h)) * N(c_n)
-                    ]
-
-        Where:
-        - u_n: solution at timestep n
-        - h: timestep size
-        - L: linear operator (diagonalized in Fourier space)
-        - N(u): nonlinear operator
-        - I: identity operator
-        - a_n, b_n, c_n: intermediate Runge-Kutta stages
-
-        This scheme integrates the linear part exactly using exponentials and uses RK4 for nonlinear terms.
+        where h is the timestep, L the (diagonal) linear operator, N the
+        nonlinear operator, and Q, f1, f2, f3 the contour-integrated
+        phi-function coefficients (see ETDRK4_f_terms). The linear part is
+        integrated exactly; the nonlinear terms with fourth-order accuracy.
         """
 
         N1 = nonlinear_operator(u_hat)
-        a = E2 * u_hat + f1 * N1
+        a = E2 * u_hat + Q * N1
         N2 = nonlinear_operator(a)
-        b = E2 * u_hat + f2 * N2
+        b = E2 * u_hat + Q * N2
         N3 = nonlinear_operator(b)
-        c = E * u_hat + f3 * N3
+        c = E2 * a + Q * (2 * N3 - N1)
         N4 = nonlinear_operator(c)
 
-        return E * u_hat + (f1 * N1 + 2 * f2 * (N2 + N3) + f3 * N4) / 6.
+        return E * u_hat + f1 * N1 + 2 * f2 * (N2 + N3) + f3 * N4
 
 
 

dynamodels-0.3.3/dynamodels/physical/kuramoto_sivashinsky_2d.py

@@ -0,0 +1,297 @@
+import matplotlib.pyplot as plt
+import numpy as np
+
+from ..integrator import DiscreteIntegrator
+from ..model import Model
+
+
+class KS2D(Model):
+
+    r"""Anisotropic two-dimensional Kuramoto-Sivashinsky equation.
+
+    $$
+    u_t + \left(u_{xx} + \alpha\, u_{yy}\right)
+        + \nu_1 \left(\partial_x^2 + \alpha\, \partial_y^2\right)^2 u
+        + \tfrac{1}{2}\left(u_x^2 + \alpha\, u_y^2\right) = 0,
+    \qquad (x, y) \in (0, 2\ell]^2,
+    $$
+
+    doubly periodic, with anisotropy ratio $\alpha = \nu_2/\nu_1$. Solved
+    pseudo-spectrally (full 2-D FFT) with the ETDRK4 scheme; the exponential
+    coefficients are evaluated by the Kassam-Trefethen contour integral. The
+    zero mode is projected out at every step (the equation only defines $u$ up
+    to a constant), so the field stays zero-mean.
+
+    The state is the PHYSICAL field flattened to shape (Nx*Ny, m) -- real
+    valued, so observables are plain state rows and ensemble filters need no
+    complex-state handling.
+
+    Known regimes on the default $\ell = \pi$ domain (see the qlROM-DA study):
+
+    | regime         | nu1 | nu2  | grid  | dt   |
+    |----------------|-----|------|-------|------|
+    | periodic       | 0.5 | 0.2  | 32x32 | 0.01 |
+    | travelling     | 0.5 | 0.35 | 32x32 | 0.1  |
+    | quasi-periodic | 0.5 | 0.1  | 32x32 | 0.01 |
+    | chaotic        | 0.1 | 0.1  | 64x64 | 0.01 |
+    | chaotic_B      | 0.3 | 0.1  | 64x64 | 0.01 |
+
+    The default parameters are the 'chaotic' regime (leading Lyapunov exponent
+    approximately 1.8).
+    """
+
+    t_transient = 100.
+    t_CR = 10.
+
+    Nq = 4                 # Number of sensors
+    Nx = 64                # Grid points in x
+    Ny = 64                # Grid points in y
+    nu1 = 0.1              # Fourth-order 'viscosity' parameter
+    nu2 = 0.1              # Anisotropic counterpart (alpha = nu2 / nu1)
+    l = float(np.pi)       # noqa: E741 -- domain half-length (0, 2l]^2, matches the ks2d study notation
+
+    Mcontour = 32          # Contour-integral points for the ETDRK4 coefficients
+    Rcontour = 15.0        # Contour radius
+
+    # structural parameters: carried by ntsa.respawn and encoded in Model.filename
+    fixed_params = ['Nx', 'Ny', 'nu1', 'nu2', 'l']
+    extra_print_params = ['Nx', 'Ny', 'nu1', 'nu2']
+    sensor_placement_method = 'grid'
+
+    def __init__(self, **model_dict):
+        """Initialize the 2D KS model.
+
+        Parameters
+        ----------
+        **model_dict
+            Model parameters; supported keys are:
+
+            - ``Nx``, ``Ny`` : int, grid points per direction (must be even).
+            - ``nu1``, ``nu2`` : float, viscosity parameters (alpha = nu2/nu1).
+            - ``l`` : float, domain half-length, domain is (0, 2l]^2.
+            - ``dt`` : float, time step size.
+            - ``Nq`` : int, number of sensors.
+            - ``sensor_placement_method`` : str, ``'grid'`` or ``'random'``.
+            - ``seed`` : int, random seed for sensor placement.
+            - ``psi0`` : ndarray, initial PHYSICAL field, shape (Nx*Ny,) or
+              (Nx*Ny, m) (optional; defaults to sin(X+Y) + sin(X) + sin(Y)).
+        """
+        for key in list(model_dict.keys()):
+            if key in vars(KS2D):
+                setattr(self, key, model_dict.pop(key))
+
+        if self.Nx % 2 != 0 or self.Ny % 2 != 0:
+            raise ValueError("Nx and Ny must be even.")
+        if self.nu1 <= 0 or self.nu2 <= 0:
+            raise ValueError("nu1 and nu2 must be positive.")
+
+        # Physical grid on (0, 2l]^2
+        self.dx = 2.0 * self.l / self.Nx
+        self.dy = 2.0 * self.l / self.Ny
+        self.X, self.Y = np.meshgrid(self.x, self.y, indexing='ij')
+
+        # Full FFT wavenumbers (positive Nyquist convention)
+        dk = np.pi / self.l
+        kx = np.concatenate((np.arange(0, self.Nx // 2 + 1),
+                             np.arange(-self.Nx // 2 + 1, 0))) * dk
+        ky = np.concatenate((np.arange(0, self.Ny // 2 + 1),
+                             np.arange(-self.Ny // 2 + 1, 0))) * dk
+        self.kX, self.kY = np.meshgrid(kx, ky, indexing='ij')
+
+        self.aniso = self.nu2 / self.nu1     # alpha in the equation; Model reserves .alpha
+        self.Lhat = (self.kX**2 + self.aniso * self.kY**2
+                     - self.nu1 * (self.kX**4
+                                   + 2.0 * self.aniso * self.kX**2 * self.kY**2
+                                   + self.aniso**2 * self.kY**4))
+
+        self._etdrk4_cache = None
+
+        #  Select sensors ___________________________ #
+        if self.sensor_placement_method == 'grid':
+            self.sensor_locations = np.linspace(0, self.Nx * self.Ny - 1, self.Nq,
+                                                endpoint=True, dtype=int)
+        elif self.sensor_placement_method == 'random':
+            self.sensor_locations = self.rng.integers(0, self.Nx * self.Ny - 1, self.Nq)
+        else:
+            raise NotImplementedError(f"sensor_placement_method "
+                                      f"'{self.sensor_placement_method}' not recognized.")
+
+        #   Init Model  #
+        dt = model_dict.pop('dt', 0.01)
+        psi0 = model_dict.pop('psi0', None)
+        if psi0 is None:
+            u0 = np.sin(self.X + self.Y) + np.sin(self.X) + np.sin(self.Y)
+            u0 -= np.mean(u0)
+            psi0 = u0.reshape(-1, 1)
+
+        super().__init__(psi0=psi0, dt=dt, integrator_class=DiscreteIntegrator, **model_dict)
+
+    # _______________ Modified Model methods ________________ #
+
+    @property
+    def obs_labels(self):
+        return [f"$u(\\mathbf{{x}}_{{{j+1}}})$" for j in np.arange(self.Nq)]
+
+    @property
+    def state_labels(self):
+        return [f"$u_{{{j+1}}}$" for j in np.arange(self.Nphi)]
+
+    def get_observables(self, Nt=1, loc=None, **kwargs):
+        """Observable state at the sensor locations (the state is already the
+        physical field, so observables are plain rows of the flattened state).
+
+        Parameters
+        ----------
+        Nt : int
+            Number of time steps to retrieve. Default is 1.
+        loc : array-like or str, optional
+            Flattened-grid sensor indices; 'all' returns the whole field;
+            None (default) uses the model's sensor locations.
+        """
+        if loc is None:
+            loc = self.sensor_locations
+        elif isinstance(loc, str) and loc.lower() == 'all':
+            loc = np.arange(self.Nx * self.Ny)
+
+        if Nt == 1:
+            return self.hist[-1, loc]
+        else:
+            return self.hist[-Nt:, loc]
+
+    # _______________ KS2D specific properties and methods ________________ #
+
+    @property
+    def x(self):
+        return np.arange(self.Nx) * self.dx
+
+    @property
+    def y(self):
+        return np.arange(self.Ny) * self.dy
+
+    @property
+    def ETDRK4_f_terms(self):
+        """ETDRK4 coefficient arrays (Nx, Ny), recomputed if dt changed."""
+        if self._etdrk4_cache is None or self._etdrk4_cache[0] != self.dt:
+            self._etdrk4_cache = (self.dt, self._compute_etdrk4_terms())
+        return self._etdrk4_cache[1]
+
+    def _compute_etdrk4_terms(self):
+        """Kassam-Trefethen contour-integral evaluation of the ETDRK4
+        coefficients for the diagonal spectral operator Lhat."""
+        mm = np.arange(1, self.Mcontour + 1)
+        r = self.Rcontour * np.exp(1j * np.pi * (mm - 0.5) / self.Mcontour)
+        LR = self.dt * self.Lhat[:, :, None] + r[None, None, :]
+
+        with np.errstate(divide='ignore', invalid='ignore', over='ignore'):
+            terms = dict(
+                E=np.exp(self.dt * self.Lhat),
+                E2=np.exp(0.5 * self.dt * self.Lhat),
+                Q=self.dt * np.real(np.mean((np.exp(LR / 2.0) - 1.0) / LR, axis=2)),
+                f1=self.dt * np.real(np.mean(
+                    (-4.0 - LR + np.exp(LR) * (4.0 - 3.0 * LR + LR**2)) / LR**3, axis=2)),
+                f2=self.dt * np.real(np.mean(
+                    (2.0 + LR + np.exp(LR) * (-2.0 + LR)) / LR**3, axis=2)),
+                f3=self.dt * np.real(np.mean(
+                    (-4.0 - 3.0 * LR - LR**2 + np.exp(LR) * (4.0 - LR)) / LR**3, axis=2)),
+            )
+        return terms
+
+    def _nonlinear_hat(self, vhat):
+        """N(u) = -1/2 F[u_x^2 + alpha u_y^2] for spectral fields (Nx, Ny, m)."""
+        vx = np.fft.ifft2(1j * self.kX[:, :, None] * vhat, axes=(0, 1)).real
+        vy = np.fft.ifft2(1j * self.kY[:, :, None] * vhat, axes=(0, 1)).real
+        return -0.5 * np.fft.fft2(vx * vx + self.aniso * vy * vy, axes=(0, 1))
+
+    def ETDRK4_step(self, u):
+        """One ETDRK4 step of physical fields u with shape (Nx, Ny, m)."""
+        c = self.ETDRK4_f_terms
+        E, E2, Q = c['E'][:, :, None], c['E2'][:, :, None], c['Q'][:, :, None]
+        f1, f2, f3 = c['f1'][:, :, None], c['f2'][:, :, None], c['f3'][:, :, None]
+
+        u = u - np.mean(u, axis=(0, 1), keepdims=True)
+        vhat = np.fft.fft2(u, axes=(0, 1))
+
+        Nv = self._nonlinear_hat(vhat)
+        a = E2 * vhat + Q * Nv
+        Na = self._nonlinear_hat(a)
+        b = E2 * vhat + Q * Na
+        Nb = self._nonlinear_hat(b)
+        cstage = E2 * a + Q * (2.0 * Nb - Nv)
+        Nc = self._nonlinear_hat(cstage)
+
+        vhat_next = E * vhat + f1 * Nv + 2.0 * f2 * (Na + Nb) + f3 * Nc
+        u_next = np.fft.ifft2(vhat_next, axes=(0, 1)).real
+        return u_next - np.mean(u_next, axis=(0, 1), keepdims=True)
+
+    def time_step(self, Nt=10, averaged=False, alpha=None):
+        """Advance all m members Nt ETDRK4 steps.
+
+        Returns
+        -------
+        psi : np.ndarray
+            Trajectory of shape (Nt + 1, Nx*Ny, m), including the current state.
+        t : np.ndarray
+            Time points, shape (Nt + 1,).
+        """
+        u0 = self.current_state
+        if u0.ndim == 1:
+            u0 = u0[:, None]
+        m = u0.shape[1]
+
+        t = np.round(self.current_time + np.arange(Nt + 1) * self.dt, self.precision_t)
+
+        if averaged and m > 1:
+            u_mean = np.mean(u0, axis=1, keepdims=True)
+            deviation = u0 - u_mean
+            u = u_mean.reshape(self.Nx, self.Ny, 1)
+            frames = [u]
+            for _ in range(Nt):
+                frames.append(self.ETDRK4_step(frames[-1]))
+            psi = np.stack([f.reshape(-1, 1) + deviation for f in frames], axis=0)
+        else:
+            u = u0.reshape(self.Nx, self.Ny, m)
+            frames = [u]
+            for _ in range(Nt):
+                frames.append(self.ETDRK4_step(frames[-1]))
+            psi = np.stack([f.reshape(-1, m) for f in frames], axis=0)
+
+        return psi, t
+
+    def get_energy(self, Nt=0, u=None):
+        """Spatially averaged L2 energy, E = mean(u^2), shape (Nt, m)."""
+        if u is None:
+            u = self.get_observable_hist(Nt=Nt, loc='all')
+        if u.ndim == 2:
+            u = u[np.newaxis, :]
+        assert u.shape[1] == self.Nx * self.Ny
+        return np.mean(u**2, axis=1)
+
+    def get_enstrophy(self, Nt=0, u=None):
+        """Spatially averaged enstrophy, mean(u_x^2 + alpha u_y^2), shape (Nt, m)."""
+        if u is None:
+            u = self.get_observable_hist(Nt=Nt, loc='all')
+        if u.ndim == 2:
+            u = u[np.newaxis, :]
+        Nt_, _, m = u.shape
+        vhat = np.fft.fft2(u.reshape(Nt_, self.Nx, self.Ny, m), axes=(1, 2))
+        ux = np.fft.ifft2(1j * self.kX[None, :, :, None] * vhat, axes=(1, 2)).real
+        uy = np.fft.ifft2(1j * self.kY[None, :, :, None] * vhat, axes=(1, 2)).real
+        return np.mean((ux**2 + self.aniso * uy**2).reshape(Nt_, -1, m), axis=1)
+
+    def visualize_spatiotemporal_hist(self, nframes=6, member=0, **kwargs):
+        """Snapshot strip of the physical field u(x, y) for one ensemble member."""
+        u_hist = self.get_observable_hist(loc='all')
+        idx = np.linspace(0, u_hist.shape[0] - 1, nframes, dtype=int)
+        lim = np.max(np.abs(u_hist[idx, :, member]))
+
+        fig, axs = plt.subplots(ncols=nframes, figsize=(2.2 * nframes, 2.4),
+                                sharey=True, constrained_layout=True)
+        for ax, ii in zip(np.atleast_1d(axs), idx):
+            im = ax.imshow(u_hist[ii, :, member].reshape(self.Nx, self.Ny).T,
+                           origin='lower', cmap='RdBu_r', vmin=-lim, vmax=lim,
+                           extent=[0, 2 * self.l, 0, 2 * self.l])
+            ax.set(title=f"$t={self.hist_t[ii]:.2f}$", xlabel="$x$")
+        np.atleast_1d(axs)[0].set(ylabel="$y$")
+        fig.colorbar(im, ax=axs, shrink=0.8)
+        fig.suptitle(rf"2D KS, $\nu_1={self.nu1}$, $\nu_2={self.nu2}$, "
+                     rf"${self.Nx}\times{self.Ny}$")

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: dynamodels
-Version: 0.2.1
+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.2.1 → dynamodels-0.3.3}/dynamodels.egg-info/SOURCES.txt

@@ -15,6 +15,7 @@ dynamodels.egg-info/top_level.txt
 dynamodels/physical/__init__.py
 dynamodels/physical/annular.py
 dynamodels/physical/kuramoto_sivashinsky.py
+dynamodels/physical/kuramoto_sivashinsky_2d.py
 dynamodels/physical/lorenz63.py
 dynamodels/physical/lorenz96.py
 dynamodels/physical/rijke.py

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

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "dynamodels"
-version = "0.2.1"
+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.3/tests/test_physical.py

@@ -0,0 +1,199 @@
+"""Smoke tests for the physical models + the package's torch-free guarantee."""
+import sys
+
+import numpy as np
+import pytest
+
+import dynamodels
+from dynamodels.physical import KS, KS2D, Annular, Lorenz63, Lorenz96, Rijke, VdP
+
+
+def test_torch_free_import():
+    # the whole point of the split: importing the modelling core must not drag
+    # in any ML stack
+    assert 'torch' not in sys.modules, 'importing dynamodels pulled in torch'
+    assert 'skopt' not in sys.modules, 'importing dynamodels pulled in scikit-optimize'
+    assert dynamodels.__version__
+
+
+def test_models_integrate_smoke():
+    for cls, kwargs in [(Lorenz63, {}), (Lorenz96, dict(Nx=10)), (VdP, {}),
+                        (Rijke, {}), (Annular, {}), (KS, {}),
+                        (KS2D, dict(Nx=32, Ny=32, nu1=0.5, nu2=0.35, dt=0.1))]:
+        model = cls(**kwargs)
+        psi, t = model.time_integrate(Nt=10)
+        assert psi.shape[0] == len(t) and np.all(np.isfinite(psi)), f'{cls.__name__} integration failed'
+        model.update_history(psi, t)
+        y = model.get_observable_hist()
+        assert y.shape[1] == model.Nq, f'{cls.__name__} observables wrong shape'
+        assert len(model.obs_labels) == model.Nq
+        model.close()
+
+
+def test_t_lyap_tables():
+    # measured-lambda1 tables in the physical model files: instances get
+    # t_lyap = 1/lambda1(sweep param) inside the chaotic range, class constants
+    # and off-table configurations are untouched
+    assert np.isclose(Lorenz63.t_lyap, 0.9056 ** -1), 'class access must stay the constant'
+    ms = [Lorenz63(), Lorenz63(rho=10.),
+          Lorenz96(Nx=10, F=8.), Lorenz96(Nx=10, F=4.8), Lorenz96(Nx=10, F=2.),
+          Lorenz96(Nx=40, F=8.), Rijke(beta=12.), Rijke(beta=4.)]
+    expect = [1 / 0.917, 0.9056 ** -1,
+              1 / 1.184, None, 1.67 ** -1,
+              1.67 ** -1, 1 / 161.0, 0.02]
+    for m, e in zip(ms, expect):
+        if e is None:  # F=4.8: log-interpolated between the F=4.6 and F=5 entries
+            assert 1 / 0.058 < m.t_lyap < 1 / 0.0391, f'{m.name} t_lyap = {m.t_lyap}'
+        else:
+            assert np.isclose(m.t_lyap, e), f'{type(m).__name__} t_lyap = {m.t_lyap}, expected {e}'
+        m.close()
+
+
+def test_pickle_drops_live_pool():
+    # pickling a mid-run model must not require close(): __getstate__ drops the
+    # (unpicklable) live pool and the copy lazily re-creates one when needed
+    import pickle
+    import threading
+
+    m = Lorenz63()
+    psi, t = m.time_integrate(Nt=5)
+    m.update_history(psi, t)
+    m.integrator._pool = threading.Lock()  # stand-in for an unpicklable live pool
+    m2 = pickle.loads(pickle.dumps(m))
+    assert m2.integrator._pool is None
+    assert np.allclose(m2.current_state, m.current_state)
+    m.integrator._pool = None
+    m.close()
+    m2.close()
+
+
+def test_create_dataset(tmp_path):
+    from dynamodels.utils import create_dataset
+    data, path = create_dataset(Lorenz63, str(tmp_path), num_lyap_times=2, seed=1)
+    assert data['clean_data'].shape == data['noisy_data'].shape
+    assert data['clean_data'].shape[1] == 3
+    assert len(data['t']) == len(data['clean_data'])
+    assert not np.allclose(data['clean_data'], data['noisy_data'])
+    # second call must hit the .mat cache, not re-integrate
+    cached, path2 = create_dataset(Lorenz63, str(tmp_path), num_lyap_times=2, seed=1)
+    assert path2 == path
+    assert np.allclose(cached['clean_data'], data['clean_data'])
+    # Nx must key the cache: a different structural size gets its own file
+    d10, p10 = create_dataset(Lorenz96, str(tmp_path), num_lyap_times=2, Nx=10)
+    assert p10 != path and d10['clean_data'].shape[1] == 10
+
+
+def test_ks_etdrk4_matches_reference_integration():
+    # regression for the pre-0.3.2 stepper, which used f-coefficients in the RK
+    # stages and divided the final combination by 6 -- first-order consistent
+    # with u_t = L u + N(u)/6 (a 6x-amplitude rescale of KS), 7% off a reference
+    # integration by t = 0.5. The standard Kassam-Trefethen scheme must track an
+    # integrating-factor RK4 reference at fine step to high accuracy.
+    # keep |dt * L_hat| < 15 for every mode so the contour quadrature is exact
+    # for all of them (far-outside modes deliberately match the dense-operator
+    # stack's behavior instead -- see ETDRK4_f_terms)
+    dt, L, Nx, Nt = 0.005, 22.0, 48, 100
+    m = KS(Nx=Nx, dt=dt, L=L, seed=0, initial_amplitude=1.0)
+    k = m.k
+    Lhat = (k**2 - k**4)[:, None]
+
+    def Nrhs(u_hat):
+        u = np.fft.irfft(u_hat, axis=0)
+        return -0.5 * (1j * k[:, None]) * np.fft.rfft(u**2, axis=0)
+
+    psi, _ = m.time_integrate(Nt=Nt)
+    u_dm = psi[-1]
+
+    sub = 100
+    h = dt / sub
+    E1, Eh = np.exp(h * Lhat), np.exp(h / 2 * Lhat)
+    u = m.psi0.copy()
+    for _ in range(Nt * sub):
+        k1 = Nrhs(u)
+        k2 = Nrhs(Eh * (u + h / 2 * k1))
+        k3 = Nrhs(Eh * u + h / 2 * k2)
+        k4 = Nrhs(E1 * u + h * Eh * k3)
+        u = E1 * u + h / 6 * (E1 * k1 + 2 * Eh * (k2 + k3) + k4)
+
+    rel = np.linalg.norm(u_dm - u) / np.linalg.norm(u)
+    # ~5e-5 is the scheme's genuine truncation error at this dt with an O(1)
+    # rough IC; the pre-0.3.2 scheme sat at ~7e-2 regardless of dt.
+    assert rel < 1e-3, f'KS ETDRK4 deviates from reference integration: rel err {rel:.2e}'
+
+
+def test_ks_exact_dt_preserved():
+    # Model.dt rounds to precision_t decimals; KS must keep the exact requested
+    # step (dt = 0.1 * 71 / 16 arises from the visc rescaling of the qlROM cases)
+    dt = 0.1 / (16 / 71)
+    m = KS(Nx=32, dt=dt, L=10.0)
+    assert m.dt == dt
+
+
+def test_ks_dt_honored_and_param_roundtrip():
+    # dt used to be silently replaced by the 0.25 default at the Model level
+    m = KS(Nx=64, dt=0.1, nu=0.08)
+    assert m.dt == 0.1
+    _, t = m.time_integrate(Nt=5)
+    assert np.isclose(t[1] - t[0], 0.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

dynamodels-0.2.1/tests/test_physical.py

@@ -1,81 +0,0 @@
-"""Smoke tests for the physical models + the package's torch-free guarantee."""
-import sys
-
-import numpy as np
-
-import dynamodels
-from dynamodels.physical import KS, Annular, Lorenz63, Lorenz96, Rijke, VdP
-
-
-def test_torch_free_import():
-    # the whole point of the split: importing the modelling core must not drag
-    # in any ML stack
-    assert 'torch' not in sys.modules, 'importing dynamodels pulled in torch'
-    assert 'skopt' not in sys.modules, 'importing dynamodels pulled in scikit-optimize'
-    assert dynamodels.__version__
-
-
-def test_models_integrate_smoke():
-    for cls, kwargs in [(Lorenz63, {}), (Lorenz96, dict(Nx=10)), (VdP, {}),
-                        (Rijke, {}), (Annular, {}), (KS, {})]:
-        model = cls(**kwargs)
-        psi, t = model.time_integrate(Nt=10)
-        assert psi.shape[0] == len(t) and np.all(np.isfinite(psi)), f'{cls.__name__} integration failed'
-        model.update_history(psi, t)
-        y = model.get_observable_hist()
-        assert y.shape[1] == model.Nq, f'{cls.__name__} observables wrong shape'
-        assert len(model.obs_labels) == model.Nq
-        model.close()
-
-
-def test_t_lyap_tables():
-    # measured-lambda1 tables in the physical model files: instances get
-    # t_lyap = 1/lambda1(sweep param) inside the chaotic range, class constants
-    # and off-table configurations are untouched
-    assert np.isclose(Lorenz63.t_lyap, 0.9056 ** -1), 'class access must stay the constant'
-    ms = [Lorenz63(), Lorenz63(rho=10.),
-          Lorenz96(Nx=10, F=8.), Lorenz96(Nx=10, F=4.8), Lorenz96(Nx=10, F=2.),
-          Lorenz96(Nx=40, F=8.), Rijke(beta=12.), Rijke(beta=4.)]
-    expect = [1 / 0.917, 0.9056 ** -1,
-              1 / 1.184, None, 1.67 ** -1,
-              1.67 ** -1, 1 / 161.0, 0.02]
-    for m, e in zip(ms, expect):
-        if e is None:  # F=4.8: log-interpolated between the F=4.6 and F=5 entries
-            assert 1 / 0.058 < m.t_lyap < 1 / 0.0391, f'{m.name} t_lyap = {m.t_lyap}'
-        else:
-            assert np.isclose(m.t_lyap, e), f'{type(m).__name__} t_lyap = {m.t_lyap}, expected {e}'
-        m.close()
-
-
-def test_pickle_drops_live_pool():
-    # pickling a mid-run model must not require close(): __getstate__ drops the
-    # (unpicklable) live pool and the copy lazily re-creates one when needed
-    import pickle
-    import threading
-
-    m = Lorenz63()
-    psi, t = m.time_integrate(Nt=5)
-    m.update_history(psi, t)
-    m.integrator._pool = threading.Lock()  # stand-in for an unpicklable live pool
-    m2 = pickle.loads(pickle.dumps(m))
-    assert m2.integrator._pool is None
-    assert np.allclose(m2.current_state, m.current_state)
-    m.integrator._pool = None
-    m.close()
-    m2.close()
-
-
-def test_create_dataset(tmp_path):
-    from dynamodels.utils import create_dataset
-    data, path = create_dataset(Lorenz63, str(tmp_path), num_lyap_times=2, seed=1)
-    assert data['clean_data'].shape == data['noisy_data'].shape
-    assert data['clean_data'].shape[1] == 3
-    assert len(data['t']) == len(data['clean_data'])
-    assert not np.allclose(data['clean_data'], data['noisy_data'])
-    # second call must hit the .mat cache, not re-integrate
-    cached, path2 = create_dataset(Lorenz63, str(tmp_path), num_lyap_times=2, seed=1)
-    assert path2 == path
-    assert np.allclose(cached['clean_data'], data['clean_data'])
-    # Nx must key the cache: a different structural size gets its own file
-    d10, p10 = create_dataset(Lorenz96, str(tmp_path), num_lyap_times=2, Nx=10)
-    assert p10 != path and d10['clean_data'].shape[1] == 10