dynamodels 0.3.2__tar.gz → 0.4.1__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: dynamodels
-Version: 0.3.2
+Version: 0.4.1
 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.4.1}/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.4.1"
 
 __all__ = [
     "Model",

{dynamodels-0.3.2 → dynamodels-0.4.1}/dynamodels/model.py

@@ -278,7 +278,7 @@ class Model:
 
 
     @property
-    def hist(self):
+    def hist(self) -> np.ndarray:
         """Returns only the valid (non-empty) portion of the history buffer."""
         return self.history.hist
 
@@ -1066,10 +1066,60 @@ class Model:
                 ax[1].set(xlabel=t_lbl, xlim=[t[-t_zoom], t[-1]])
 
 
-    def visualize_spatiotemporal_hist(self, reference_y=1.0, reference_t: float = 1.0, **kwargs):
-        """No-op hook for subclasses to plot spatiotemporal (e.g. field)
-        histories. Called by `visualize_history`."""
-        pass
+    def visualize_spatiotemporal_hist(self, y_hist=None, t=None, nrows=None, averaged=False,
+                                      reference_y=1.0, reference_t: float = 1.0, **kwargs):
+        """Space-time diagram of the state history: state index vs time.
+
+        Generic default plotting ``hist[:, :Nphi]`` directly — one panel per
+        ensemble member (up to ``nrows``), or the ensemble mean and standard
+        deviation with ``averaged=True``. Called by `visualize_history`. Same
+        signature as the physical-space overrides in `KS`, `Rijke` and
+        `Lorenz96`, which rewrite this when the raw state history is not the
+        physical field.
+        """
+        if y_hist is None:
+            y_hist = self.hist[:, :self.Nphi]
+        if t is None:
+            t = self.hist_t
+
+        (t,), t_lbl = normalized_time(reference_t, t)
+        assert t is not None
+        if reference_y != 1.0:
+            y_hist = y_hist / reference_y
+
+        N = y_hist.shape[1]
+        extent = [t[0], t[-1], -0.5, N - 0.5]
+
+        if not averaged:
+            if nrows is None:
+                nrows = min(10, y_hist.shape[-1])
+            fig = plt.figure(figsize=(8, 1.5 * nrows + 1), layout='constrained')
+            axs = np.atleast_1d(fig.subplots(nrows=nrows, sharex=True, sharey=True))
+            lim = np.max(abs(y_hist))
+            for mi, ax in enumerate(axs):
+                im = ax.imshow(y_hist[:, :, mi].T, aspect='auto', origin='lower',
+                               cmap='RdBu_r', vmin=-lim, vmax=lim, extent=extent)
+            axs[0].set(title=f'{self.name} state space-time evolution')
+            fig.colorbar(im, ax=axs, shrink=1 / nrows)
+        else:
+            fig, axs = plt.subplots(nrows=2, figsize=(8, 6), sharex=True, layout='constrained')
+            y_mean = np.mean(y_hist, axis=-1)
+            lim = np.max(abs(y_mean))
+            im0 = axs[0].imshow(y_mean.T, aspect='auto', origin='lower',
+                                cmap='RdBu_r', vmin=-lim, vmax=lim, extent=extent)
+            axs[0].set(title=f'{self.name} state space-time evolution (mean and std)')
+            fig.colorbar(im0, ax=axs[0])
+            y_std = np.std(y_hist, axis=-1, ddof=1)
+            im1 = axs[1].imshow(y_std.T, aspect='auto', origin='lower',
+                                cmap='magma', vmin=0, extent=extent)
+            fig.colorbar(im1, ax=axs[1])
+
+        axs[-1].set(xlabel=t_lbl)
+        for ax in axs:
+            if N <= 10:
+                ax.set(yticks=np.arange(N), yticklabels=self.state_labels[:N])
+            else:
+                ax.set(ylabel='state index')
 
 
 

{dynamodels-0.3.2 → dynamodels-0.4.1}/dynamodels/physical/__init__.py

@@ -1,6 +1,7 @@
 from .annular import Annular
 from .kuramoto_sivashinsky import KS
 from .kuramoto_sivashinsky_2d import KS2D
+from .kuznetsov import Kuznetsov
 from .lorenz63 import Lorenz63
 from .lorenz96 import Lorenz96
 from .rijke import Rijke
@@ -10,6 +11,7 @@ __all__ = [
     "Annular",
     "KS",
     "KS2D",
+    "Kuznetsov",
     "Lorenz63",
     "Lorenz96",
     "Rijke",

{dynamodels-0.3.2 → dynamodels-0.4.1}/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.4.1}/dynamodels/physical/kuramoto_sivashinsky_2d.py

@@ -4,6 +4,17 @@ import numpy as np
 from ..integrator import DiscreteIntegrator
 from ..model import Model
 
+# Known regimes on the default l = pi domain (see the qlROM-DA study).
+# Values not listed fall back to the class defaults (32x32 grid, dt = 0.01).
+CASES = {
+    'periodic': {'nu1': 0.5, 'nu2': 0.2, 'dt': 0.01},
+    'travelling': {'nu1': 0.5, 'nu2': 0.35},
+    'quasi-periodic': {'nu1': 0.5, 'nu2': 0.1},
+    'chaotic': {'nu1': 0.1, 'nu2': 0.1, 'Nx': 64, 'Ny': 64,
+                't_transient': 40., 't_CR': 4.},
+    'chaotic_B': {'nu1': 0.3, 'nu2': 0.1, 'Nx': 64, 'Ny': 64},
+}
+
 
 class KS2D(Model):
 
@@ -28,33 +39,37 @@ class KS2D(Model):
 
     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).
+    | regime         | nu1 | nu2  | grid  | dt   | t_transient | t_CR |
+    |----------------|-----|------|-------|------|-------------|------|
+    | periodic       | 0.5 | 0.2  | 32x32 | 0.01 | 100.        | 10.  |
+    | travelling     | 0.5 | 0.35 | 32x32 | 0.1  | 100.        | 10.  |
+    | quasi-periodic | 0.5 | 0.1  | 32x32 | 0.01 | 100.        | 10.  |
+    | chaotic        | 0.1 | 0.1  | 64x64 | 0.01 | 40.        | 4.  |
+    | chaotic_B      | 0.3 | 0.1  | 64x64 | 0.01 | 100.        | 10.  |
+
+    The class defaults are the 'periodic' regime; pass ``case='chaotic'`` etc.
+    (see `CASES`) to select another. Explicit kwargs win over the case values,
+    e.g. ``KS2D(case='chaotic', Nx=128, Ny=128)``.
     """
 
     t_transient = 100.
     t_CR = 10.
 
+    case = None  # default case; can be overridden in __init__ or by kwargs
     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)
+    Nx = 32                # Grid points in x
+    Ny = 32                # Grid points in y
+    nu1 = 0.5              # Fourth-order 'viscosity' parameter
+    nu2 = 0.2              # 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']
+    # nu1/nu2 are estimable (per-member ETDRK4 coefficients are rebuilt when a
+    # DA analysis moves them); the grid and domain stay structural
+    params = ['nu1', 'nu2']
+    fixed_params = ['Nx', 'Ny', 'l']
     extra_print_params = ['Nx', 'Ny', 'nu1', 'nu2']
     sensor_placement_method = 'grid'
 
@@ -66,6 +81,8 @@ class KS2D(Model):
         **model_dict
             Model parameters; supported keys are:
 
+            - ``case`` : str, a named regime from `CASES`; its values are
+              defaults that any explicit kwarg below overrides.
             - ``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.
@@ -76,6 +93,13 @@ class KS2D(Model):
             - ``psi0`` : ndarray, initial PHYSICAL field, shape (Nx*Ny,) or
               (Nx*Ny, m) (optional; defaults to sin(X+Y) + sin(X) + sin(Y)).
         """
+        self.case = model_dict.pop('case', None)
+        if self.case is not None:
+            if self.case not in CASES:
+                raise ValueError(f"Unknown case '{self.case}'. Must be one of {list(CASES)}.")
+            for key, val in CASES[self.case].items():
+                model_dict.setdefault(key, val)  # explicit kwargs win over the case
+
         for key in list(model_dict.keys()):
             if key in vars(KS2D):
                 setattr(self, key, model_dict.pop(key))
@@ -99,12 +123,10 @@ class KS2D(Model):
         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.Lhat = self._lhat(self.nu1, self.nu2)
 
         self._etdrk4_cache = None
+        self._member_terms = None
 
         #  Select sensors ___________________________ #
         if self.sensor_placement_method == 'grid':
@@ -126,6 +148,9 @@ class KS2D(Model):
 
         super().__init__(psi0=psi0, dt=dt, integrator_class=DiscreteIntegrator, **model_dict)
 
+        self.alpha_labels = dict(nu1='$\\nu_1$', nu2='$\\nu_2$')
+        self.alpha_lims = dict(nu1=(0.01, 1.0), nu2=(0.01, 1.0))
+
     # _______________ Modified Model methods ________________ #
 
     @property
@@ -152,6 +177,10 @@ class KS2D(Model):
             loc = self.sensor_locations
         elif isinstance(loc, str) and loc.lower() == 'all':
             loc = np.arange(self.Nx * self.Ny)
+        elif isinstance(loc, str):
+            raise ValueError("loc must be None, 'all', or array-like integer indices.")
+
+        loc = np.asarray(loc, dtype=int)
 
         if Nt == 1:
             return self.hist[-1, loc]
@@ -168,56 +197,93 @@ class KS2D(Model):
     def y(self):
         return np.arange(self.Ny) * self.dy
 
+    def _lhat(self, nu1, nu2):
+        """Diagonal spectral operator for given nu values. Scalars give the
+        shared (Nx, Ny) operator; per-member arrays of length m give a
+        (Nx, Ny, m) stack."""
+        nu1, nu2 = np.asarray(nu1, dtype=float), np.asarray(nu2, dtype=float)
+        kX, kY = (self.kX, self.kY) if nu1.ndim == 0 else (self.kX[:, :, None], self.kY[:, :, None])
+        a = nu2 / nu1
+        return (kX**2 + a * kY**2
+                - nu1 * (kX**4 + 2.0 * a * kX**2 * kY**2 + a**2 * kY**4))
+
     @property
     def ETDRK4_f_terms(self):
-        """ETDRK4 coefficient arrays (Nx, Ny), recomputed if dt changed."""
+        """ETDRK4 coefficient arrays (Nx, Ny) for the constructed (nu1, nu2),
+        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):
+    def _compute_etdrk4_terms(self, Lhat=None):
         """Kassam-Trefethen contour-integral evaluation of the ETDRK4
-        coefficients for the diagonal spectral operator Lhat."""
+        coefficients for the diagonal spectral operator `Lhat` (defaults to
+        the constructed one; a (Nx, Ny, m) stack gives per-member terms)."""
+        if Lhat is None:
+            Lhat = self.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, :]
+        LR = self.dt * Lhat[..., None] + r
 
         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)),
+                E=np.exp(self.dt * Lhat),
+                E2=np.exp(0.5 * self.dt * Lhat),
+                Q=self.dt * np.real(np.mean((np.exp(LR / 2.0) - 1.0) / LR, axis=-1)),
                 f1=self.dt * np.real(np.mean(
-                    (-4.0 - LR + np.exp(LR) * (4.0 - 3.0 * LR + LR**2)) / LR**3, axis=2)),
+                    (-4.0 - LR + np.exp(LR) * (4.0 - 3.0 * LR + LR**2)) / LR**3, axis=-1)),
                 f2=self.dt * np.real(np.mean(
-                    (2.0 + LR + np.exp(LR) * (-2.0 + LR)) / LR**3, axis=2)),
+                    (2.0 + LR + np.exp(LR) * (-2.0 + LR)) / LR**3, axis=-1)),
                 f3=self.dt * np.real(np.mean(
-                    (-4.0 - 3.0 * LR - LR**2 + np.exp(LR) * (4.0 - LR)) / LR**3, axis=2)),
+                    (-4.0 - 3.0 * LR - LR**2 + np.exp(LR) * (4.0 - LR)) / LR**3, axis=-1)),
             )
         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)."""
+    def _terms_for(self, alpha):
+        """ETDRK4 terms (plus per-member anisotropy) for a list of per-member
+        alpha dicts; falls through to the shared terms when every member sits
+        at the constructed (nu1, nu2)."""
+        nu1 = np.array([a['nu1'] for a in alpha], dtype=float)
+        nu2 = np.array([a['nu2'] for a in alpha], dtype=float)
+        if np.all(nu1 == self.nu1) and np.all(nu2 == self.nu2):
+            return self.ETDRK4_f_terms
+        key = (self.dt, nu1.tobytes(), nu2.tobytes())
+        if self._member_terms is None or self._member_terms[0] != key:
+            # ponytail: full contour rebuild whenever the nus move -- cheap next
+            # to stepping, and only a DA analysis (or a new alpha) moves them
+            terms = self._compute_etdrk4_terms(self._lhat(nu1, nu2))
+            terms['aniso'] = nu2 / nu1
+            self._member_terms = (key, terms)
+        return self._member_terms[1]
+
+    def _nonlinear_hat(self, vhat, aniso=None):
+        """N(u) = -1/2 F[u_x^2 + alpha u_y^2] for spectral fields (Nx, Ny, m);
+        `aniso` may be scalar or per-member (m,)."""
+        if aniso is None:
+            aniso = self.aniso
         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))
+        return -0.5 * np.fft.fft2(vx * vx + 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]
+    def ETDRK4_step(self, u, terms=None):
+        """One ETDRK4 step of physical fields u with shape (Nx, Ny, m).
+        `terms` defaults to the shared coefficients; per-member (Nx, Ny, m)
+        stacks from `_terms_for` are used as-is."""
+        c = self.ETDRK4_f_terms if terms is None else terms
+        E, E2, Q, f1, f2, f3 = (c[k][:, :, None] if c[k].ndim == 2 else c[k]
+                                for k in ('E', 'E2', 'Q', 'f1', 'f2', 'f3'))
+        aniso = c.get('aniso', self.aniso)
 
         u = u - np.mean(u, axis=(0, 1), keepdims=True)
         vhat = np.fft.fft2(u, axes=(0, 1))
 
-        Nv = self._nonlinear_hat(vhat)
+        Nv = self._nonlinear_hat(vhat, aniso)
         a = E2 * vhat + Q * Nv
-        Na = self._nonlinear_hat(a)
+        Na = self._nonlinear_hat(a, aniso)
         b = E2 * vhat + Q * Na
-        Nb = self._nonlinear_hat(b)
+        Nb = self._nonlinear_hat(b, aniso)
         cstage = E2 * a + Q * (2.0 * Nb - Nv)
-        Nc = self._nonlinear_hat(cstage)
+        Nc = self._nonlinear_hat(cstage, aniso)
 
         vhat_next = E * vhat + f1 * Nv + 2.0 * f2 * (Na + Nb) + f3 * Nc
         u_next = np.fft.ifft2(vhat_next, axes=(0, 1)).real
@@ -226,35 +292,54 @@ class KS2D(Model):
     def time_step(self, Nt=10, averaged=False, alpha=None):
         """Advance all m members Nt ETDRK4 steps.
 
+        Parameters
+        ----------
+        alpha : list of dict, optional
+            Per-member parameter dicts (as from `get_alpha`); defaults to the
+            values carried in the (possibly augmented) current state. Members
+            with nus away from the constructed ones get their own ETDRK4
+            coefficients.
+
         Returns
         -------
         psi : np.ndarray
-            Trajectory of shape (Nt + 1, Nx*Ny, m), including the current state.
+            Trajectory of shape (Nt + 1, Nphi [+ Na], m), including the
+            current state; estimated-parameter rows are carried unchanged.
         t : np.ndarray
             Time points, shape (Nt + 1,).
         """
-        u0 = self.current_state
-        if u0.ndim == 1:
-            u0 = u0[:, None]
-        m = u0.shape[1]
+        psi0 = self.current_state
+        if psi0.ndim == 1:
+            psi0 = psi0[:, None]
+        m = psi0.shape[1]
+        Nu = self.Nx * self.Ny
+        u0, aug = psi0[:Nu], psi0[Nu:]   # estimated-parameter rows ride along unchanged
+
+        if alpha is None:
+            alpha = self.get_alpha(psi0)
 
         t = np.round(self.current_time + np.arange(Nt + 1) * self.dt, self.precision_t)
 
         if averaged and m > 1:
+            mean_alpha = [{k: float(np.mean([a[k] for a in alpha])) for k in self.params}]
+            terms = self._terms_for(mean_alpha)
             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]))
+                frames.append(self.ETDRK4_step(frames[-1], terms))
             psi = np.stack([f.reshape(-1, 1) + deviation for f in frames], axis=0)
         else:
+            terms = self._terms_for(alpha)
             u = u0.reshape(self.Nx, self.Ny, m)
             frames = [u]
             for _ in range(Nt):
-                frames.append(self.ETDRK4_step(frames[-1]))
+                frames.append(self.ETDRK4_step(frames[-1], terms))
             psi = np.stack([f.reshape(-1, m) for f in frames], axis=0)
 
+        if aug.shape[0]:
+            psi = np.concatenate([psi, np.broadcast_to(aug, (Nt + 1, *aug.shape))], axis=1)
         return psi, t
 
     def get_energy(self, Nt=0, u=None):
@@ -278,20 +363,38 @@ class KS2D(Model):
         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."""
+    def visualize_spatiotemporal_hist(self,
+                                      nframes=6, member=0, **kwargs):
+        """Snapshot strip of the physical field u(x, y) for one ensemble member,
+        plus a space-time diagram of the mid-domain slice u(x, y = l, t)."""
         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,
+        t = self.hist_t
+        u = u_hist[:, :, member].reshape(len(t), self.Nx, self.Ny)
+        idx = np.linspace(0, len(t) - 1, nframes, dtype=int)
+        lim = np.max(np.abs(u[idx]))
+
+        fig = plt.figure(figsize=(2.2 * nframes, 4.8), constrained_layout=True)
+        gs = fig.add_gridspec(2, nframes)
+        axs = [fig.add_subplot(gs[0, jj]) for jj in range(nframes)]
+        im = None
+        for ax, ii in zip(axs, idx):
+            im = ax.imshow(u[ii].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$")
+                           extent=(0, 2 * self.l, 0, 2 * self.l))
+            ax.set(title=f"$t={t[ii]:.2f}$", xlabel="$x$")
+        axs[0].set(ylabel="$y$")
+        assert im is not None
         fig.colorbar(im, ax=axs, shrink=0.8)
+
+        # space-time diagram along the mid-domain slice y = l
+        u_slice = u[:, :, self.Ny // 2]
+        ax_st = fig.add_subplot(gs[1, :])
+        lim_st = np.max(np.abs(u_slice))
+        im_st = ax_st.imshow(u_slice.T, aspect='auto', origin='lower',
+                             cmap='RdBu_r', vmin=-lim_st, vmax=lim_st,
+                             extent=(t[0], t[-1], 0, 2 * self.l))
+        ax_st.set(xlabel="$t$", ylabel="$x$", title=r"$u(x, y = l, t)$")
+        fig.colorbar(im_st, ax=ax_st, shrink=0.8)
+
         fig.suptitle(rf"2D KS, $\nu_1={self.nu1}$, $\nu_2={self.nu2}$, "
                      rf"${self.Nx}\times{self.Ny}$")

dynamodels-0.4.1/dynamodels/physical/kuznetsov.py

@@ -0,0 +1,67 @@
+import numpy as np
+
+from ..integrator import IVPIntegrator
+from ..model import Model
+
+
+# %% =================================== KUZNETSOV OSCILLATOR ============================================== %% #
+class Kuznetsov(Model):
+    r"""Kuznetsov oscillator — autonomous generator of quasiperiodic oscillations.
+
+    Three-dimensional system displaying periodic, quasiperiodic and chaotic
+    behaviour as a function of the parameters $[\lambda, \omega_0, \mu]$:
+
+    $$
+    \dot{x} = y, \qquad
+    \dot{y} = y \left( \lambda + z + x^2 - \tfrac{1}{2} x^4 \right) - \omega_0^2 x, \qquad
+    \dot{z} = \mu - x^2.
+    $$
+
+    With the default parameters ($\lambda = 0$, $\omega_0 = 2\pi$, $\mu = 1$)
+    the attractor is a two-frequency quasiperiodic torus.
+
+    References
+    ----------
+    Kuznetsov, Kuznetsov & Stankevich (2010). A simple autonomous quasiperiodic
+    self-oscillator. *Commun. Nonlinear Sci. Numer. Simul.*, 15, 1676–1681.
+    [DOI: 10.1016/j.cnsns.2009.06.027](https://doi.org/10.1016/j.cnsns.2009.06.027).
+    """
+
+    t_transient = 100.   # fast period is 2 pi / omega0 = 1; slow beats need many of them
+    t_CR = 4.
+    t_lyap = t_CR        # no measured-lambda1 table yet (default case is quasiperiodic)
+
+    Nq = 3
+
+    lam = 0.             # linear growth rate 
+    omega0 = 2 * np.pi   # natural frequency [rad/s]
+    mu = 1.              # slow-variable drive
+
+    params = ['lam', 'omega0', 'mu']
+
+    # __________________________ Init method ___________________________ #
+    def __init__(self, **model_dict):
+
+        psi0 = model_dict.pop('psi0', np.array([0.1, 0., 0.]))
+        dt = model_dict.pop('dt', 0.01)
+
+        super().__init__(psi0=psi0, dt=dt, integrator_class=IVPIntegrator, **model_dict)
+
+        self.alpha_labels = dict(lam='$\\lambda$', omega0='$\\omega_0$', mu='$\\mu$')
+
+    @property
+    def state_labels(self):
+        return ['$x$', '$y$', '$z$']
+
+    # _______________ Kuznetsov specific properties and methods ________________ #
+    @property
+    def obs_labels(self):
+        return self.state_labels[:self.Nq]
+
+    @staticmethod
+    def time_derivative(t, psi, lam, omega0, mu):
+        x, y, z = psi[:3]
+        dx = y
+        dy = y * (lam + z + x ** 2 - 0.5 * x ** 4) - omega0 ** 2 * x
+        dz = mu - x ** 2
+        return (dx, dy, dz) + (0,) * (len(psi) - 3)

{dynamodels-0.3.2 → dynamodels-0.4.1}/dynamodels/utils.py

@@ -138,23 +138,18 @@ def mean_vector_to_ensemble(rng: np.random.Generator,
             perturbation = 1.0 + rng.uniform(-std, std, size=(mean_vec.size, m))
             ensemble_ = mean_vec[:, np.newaxis] * perturbation
 
-        else: # normal (using multivariate normal for state vector)
-
-            # Multiplicative uniform perturbation: mean * (1 +/- std)
-            # print(f'Creating normal ensemble with std={std} for mean_vec of shape {mean_vec.shape} and m={m}')
+        else: # normal: independent per-component perturbation, std relative to the mean
+            # The covariance is diagonal, so sample component-wise -- equivalent to
+            # multivariate_normal(mean, diag((mean*std)^2)) without its SVD of the
+            # (N, N) covariance, which dominated init_ensemble for field-sized states
+            def _normal(mu):
+                return mu[:, np.newaxis] + rng.normal(size=(mu.size, m)) * np.abs(mu * std)[:, np.newaxis]
 
             if np.iscomplexobj(mean_vec):
                 # Handle complex state by perturbing real and imaginary parts independently
-                # ensure we have a numpy array so static type checkers accept real/imag access
-                real_mu = np.real(mean_vec)
-                imag_mu = np.imag(mean_vec)
-                real_part = rng.multivariate_normal(real_mu, np.diag((real_mu * std) ** 2), size=m).T
-                imag_part = rng.multivariate_normal(imag_mu,  np.diag((imag_mu * std) ** 2), size=m).T
-                ensemble_ = real_part + 1j * imag_part
+                ensemble_ = _normal(np.real(mean_vec)) + 1j * _normal(np.imag(mean_vec))
             else:
-                # Covariance matrix is diagonal, perturbation scaled by mean and relative std
-                cov = np.diag((mean_vec * std) ** 2)
-                ensemble_ = rng.multivariate_normal(mean_vec, cov, size=m).T
+                ensemble_ = _normal(mean_vec)
 
     else:
         raise TypeError(f'Initial std must be a float or a dict, not {type(std)}')

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: dynamodels
-Version: 0.3.2
+Version: 0.4.1
 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.4.1}/dynamodels.egg-info/SOURCES.txt

@@ -16,6 +16,7 @@ dynamodels/physical/__init__.py
 dynamodels/physical/annular.py
 dynamodels/physical/kuramoto_sivashinsky.py
 dynamodels/physical/kuramoto_sivashinsky_2d.py
+dynamodels/physical/kuznetsov.py
 dynamodels/physical/lorenz63.py
 dynamodels/physical/lorenz96.py
 dynamodels/physical/rijke.py

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

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

@@ -2,9 +2,10 @@
 import sys
 
 import numpy as np
+import pytest
 
 import dynamodels
-from dynamodels.physical import KS, KS2D, Annular, Lorenz63, Lorenz96, Rijke, VdP
+from dynamodels.physical import KS, KS2D, Annular, Kuznetsov, Lorenz63, Lorenz96, Rijke, VdP
 
 
 def test_torch_free_import():
@@ -16,7 +17,7 @@ def test_torch_free_import():
 
 
 def test_models_integrate_smoke():
-    for cls, kwargs in [(Lorenz63, {}), (Lorenz96, dict(Nx=10)), (VdP, {}),
+    for cls, kwargs in [(Lorenz63, {}), (Lorenz96, dict(Nx=10)), (VdP, {}), (Kuznetsov, {}),
                         (Rijke, {}), (Annular, {}), (KS, {}),
                         (KS2D, dict(Nx=32, Ny=32, nu1=0.5, nu2=0.35, dt=0.1))]:
         model = cls(**kwargs)
@@ -29,6 +30,48 @@ def test_models_integrate_smoke():
         model.close()
 
 
+def test_ks2d_cases():
+    # defaults are the periodic regime; case= merges a named regime, and
+    # explicit kwargs win over the case values
+    m = KS2D()
+    assert (m.nu1, m.nu2, m.Nx, m.Ny, m.dt) == (0.5, 0.2, 32, 32, 0.01)
+    c = KS2D(case='chaotic')
+    assert (c.nu1, c.Nx, c.t_transient, c.t_CR) == (0.1, 64, 40., 4.)
+    assert c.Lhat.shape == (64, 64), 'case must be applied before the operator is built'
+    o = KS2D(case='chaotic', Nx=128, Ny=128)
+    assert o.Nx == 128 and o.nu1 == 0.1
+    with pytest.raises(ValueError):
+        KS2D(case='nope')
+    for mm in (m, c, o):
+        mm.close()
+
+
+def test_ks2d_estimable_nus():
+    # nu1/nu2 are estimable params with bounds; per-member alphas get their own
+    # ETDRK4 operators, matching independent single-nu runs from the same IC
+    m = KS2D()
+    assert m.alpha0 == dict(nu1=0.5, nu2=0.2)
+    assert m.alpha_lims['nu1'] == (0.01, 1.0) and m.alpha_lims['nu2'] == (0.01, 1.0)
+    u0 = m.psi0
+    two = KS2D(psi0=np.hstack([u0, u0]))
+    alphas = [dict(nu1=0.5, nu2=0.2), dict(nu1=0.5, nu2=0.35)]
+    psi, _ = two.time_step(Nt=20, alpha=alphas)
+    assert not np.allclose(psi[-1, :, 0], psi[-1, :, 1]), 'different nus must diverge'
+    for k, al in enumerate(alphas):
+        ref = KS2D(psi0=u0.copy(), **al)
+        psi_ref, _ = ref.time_step(Nt=20)
+        assert np.allclose(psi[:, :, k], psi_ref[:, :, 0]), f'member {k} deviates from its single-nu run'
+        ref.close()
+    # augmented ensemble: estimated-parameter rows ride through time_integrate
+    e = KS2D(t_transient=1.)  # keep init_ensemble's transient run short
+    e.init_ensemble(m=3, std_phi=0.1, est_alpha=['nu2'], std_alpha=0.1)
+    psi, t = e.time_integrate(Nt=5)
+    assert psi.shape[1] == e.Nphi + 1 and np.all(np.isfinite(psi))
+    assert np.allclose(psi[-1, -1], psi[0, -1]), 'estimated nu2 row must be carried unchanged'
+    for mm in (m, two, e):
+        mm.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
@@ -134,9 +177,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