scikit-complexity 0.2.0__py3-none-any.whl

skcomplex/models/physics/fluids/_kinetic_equations.py

@@ -0,0 +1,327 @@
+"""Kinetic equations of gases and plasmas over position and velocity, on the phase spaces of the core."""
+
+# Author: Georgios Douzas <gdouzas@icloud.com>
+# License: MIT
+
+import math
+from types import SimpleNamespace
+
+import numpy as np
+import numpy.typing as npt
+from sage.all__sagemath_symbolics import Expression
+
+from ....core.elements import DensityElement, FieldElement
+from ....core.interactions import AdvectionInteraction, EncounterInteraction
+from ....core.laws.utils import coordinate, gradient, inverse_laplacian, moment
+from ....core.spaces import LatticeSpace, PhaseSpace
+from ....core.system import System
+from ....engine.solvers import RK4Solver, SemiLagrangianSolver, SSPRKSolver, StrangSplittingSolver
+from ....errors import ValidationError
+from ....specs import AxisSpec, VisualSpec
+from ..._catalog import register_model
+from ._bhatnagar_gross_krook import BhatnagarGrossKrookInteraction
+
+SETUPS = ('landau', 'two-stream')
+SHOCK_TUBE = 'sod'
+VELOCITY_AXES = ('vx', 'vy')
+VLASOV_VISUAL = VisualSpec('image', {'moments': (0,)})
+
+
+def _get_maxwellian(
+    density: npt.NDArray[np.float64],
+    mean: npt.NDArray[np.float64],
+    temperature: npt.NDArray[np.float64],
+    speeds: npt.NDArray[np.floating],
+) -> npt.NDArray[np.float64]:
+    """Return the Maxwellian of densities, mean velocities, and temperatures over one velocity axis, one row each."""
+    rows = (speeds[None, :] - mean[:, None]) ** 2 / (2 * temperature[:, None])
+    return density[:, None] * np.exp(-rows) / np.sqrt(2 * np.pi * temperature[:, None])
+
+
+def _get_streaming(_: SimpleNamespace) -> list[Expression]:
+    """Return the drift of free streaming over one position and one velocity axis."""
+    return [coordinate('v'), 0]
+
+
+def _get_plane_streaming(_: SimpleNamespace) -> list[Expression]:
+    """Return the drift of free streaming over one position and two velocity axes."""
+    return [coordinate('vx'), 0, 0]
+
+
+def _get_poisson_drift(s: SimpleNamespace) -> list[Expression]:
+    """Return the velocity along position and the force of the potential of the density along velocity."""
+    density = moment(s.target.f, 0, axes=('v',))
+    return [coordinate('v'), -gradient(inverse_laplacian(1 - density), 1)[0]]
+
+
+def _get_uniform_gas(positions: int, velocities: int, knudsen: float, half_width: float) -> tuple[FieldElement, float]:
+    """Return a gas over one position and two velocity axes, with a density wave, and its collision frequency."""
+    length = 2 * math.pi
+    axes = [AxisSpec(name, velocities, -half_width, half_width) for name in VELOCITY_AXES]
+    space = PhaseSpace(LatticeSpace((positions,), spacing=length / positions), axes).check().prepare()
+    vx, vy = np.meshgrid(space.coordinates_['vx'], space.coordinates_['vy'], indexing='ij')
+    x = np.arange(positions) * length / positions
+    profile = np.exp(-(vx**2 + vy**2) / 2) / (2 * np.pi)
+    values = np.multiply.outer(1.0 + 0.2 * np.sin(x), profile)
+    gas = FieldElement('gas', element=DensityElement, space=space, values={'f': values}, discretization='finite-volume')
+    return gas, 1.0 / knudsen
+
+
+def _get_maxwell_molecules(_speed: object, _cosine: object) -> float:
+    """Return the cross-section of Maxwell molecules in two velocity dimensions."""
+    return 1 / (2 * math.pi)
+
+
+@register_model(
+    field='physics/fluids',
+    tags=('field', 'kinetic', 'phase space', 'collisions', 'pde'),
+    references=('Bellomo et al. 2017', 'Mouhot and Pareschi 2006'),
+    defaults={
+        'until': 0.5,
+        'dt': 0.1,
+        'solver': StrangSplittingSolver(SemiLagrangianSolver(0.1), RK4Solver(0.05), 0.1),
+    },
+)
+def boltzmann_equation(
+    positions: int = 8,
+    velocities: int = 12,
+    *,
+    knudsen: float = 1.0,
+    half_width: float = 6.0,
+) -> System:
+    """Return the Boltzmann equation of Maxwell molecules over one position and two velocity axes.
+
+    Free streaming moves a density wave along the periodic position axis, and binary collisions redistribute the density
+    over the velocities at every position, by the fast spectral method.
+
+    Args:
+        positions:
+            The number of positions.
+
+        velocities:
+            The number of points of each velocity axis.
+
+        knudsen:
+            The Knudsen number, the inverse of the collision frequency.
+
+        half_width:
+            The half-width of each velocity axis.
+
+    Returns:
+        system:
+            The model, with the density `gas.f`.
+
+    Examples:
+        >>> from skcomplex.models.physics.fluids import boltzmann_equation
+        >>> boltzmann_equation(4, 8).elements[0].check().prepare().size_
+        256
+    """
+    gas, frequency = _get_uniform_gas(positions, velocities, knudsen, half_width)
+    stream = AdvectionInteraction('stream', target='gas', state='f', drift=_get_plane_streaming)
+    collide = EncounterInteraction(
+        'collide',
+        candidate='gas',
+        cross_section=_get_maxwell_molecules,
+        factor=lambda _: frequency,
+    )
+    return System(elements=[gas], interactions=[stream, collide])
+
+
+@register_model(
+    field='physics/fluids',
+    tags=('field', 'kinetic', 'phase space', 'collisions', 'pde'),
+    references=('Bellomo et al. 2017', 'Enskog 1922'),
+    defaults={
+        'until': 0.5,
+        'dt': 0.1,
+        'solver': StrangSplittingSolver(SemiLagrangianSolver(0.1), RK4Solver(0.05), 0.1),
+    },
+)
+def enskog(
+    positions: int = 8,
+    velocities: int = 12,
+    *,
+    knudsen: float = 1.0,
+    diameter: float = 0.2,
+    half_width: float = 6.0,
+) -> System:
+    """Return the local Enskog equation, the Boltzmann equation with the contact value of the pair correlation of disks.
+
+    The collision frequency is multiplied at every position by Henderson's contact value `(1 - 7 c / 16) / (1 - c)^2` of
+    the area fraction `c = pi n d^2 / 4`, with `n` the density moment and `d` the diameter of the disks. The collision
+    partners sit at one position, so the shift of one diameter of the full Enskog collision is left out.
+
+    Args:
+        positions:
+            The number of positions.
+
+        velocities:
+            The number of points of each velocity axis.
+
+        knudsen:
+            The Knudsen number, the inverse of the collision frequency of the dilute gas.
+
+        diameter:
+            The diameter of the disks.
+
+        half_width:
+            The half-width of each velocity axis.
+
+    Returns:
+        system:
+            The model, with the density `gas.f`.
+
+    Examples:
+        >>> from skcomplex.models.physics.fluids import enskog
+        >>> enskog(4, 8).elements[0].check().prepare().size_
+        256
+    """
+    gas, frequency = _get_uniform_gas(positions, velocities, knudsen, half_width)
+    area = math.pi * diameter**2 / 4
+
+    def contact(s: SimpleNamespace) -> Expression:
+        fraction = area * moment(s.candidate.f, 0, axes=VELOCITY_AXES)
+        return frequency * (1 - 7 * fraction / 16) / (1 - fraction) ** 2
+
+    stream = AdvectionInteraction('stream', target='gas', state='f', drift=_get_plane_streaming)
+    collide = EncounterInteraction('collide', candidate='gas', cross_section=_get_maxwell_molecules, factor=contact)
+    return System(elements=[gas], interactions=[stream, collide])
+
+
+@register_model(
+    field='physics/fluids',
+    tags=('field', 'kinetic', 'phase space', 'shocks', 'pde'),
+    references=('Bhatnagar, Gross, and Krook 1954', 'Mieussens 2000', 'Sod 1978'),
+    defaults={'until': 0.2, 'dt': 0.05, 'solver': StrangSplittingSolver(SSPRKSolver(), RK4Solver(0.005), 0.005)},
+)
+def bgk_equation(
+    positions: int = 100,
+    velocities: int = 32,
+    *,
+    knudsen: float = 1e-2,
+    half_width: float = 6.0,
+) -> System:
+    """Return the BGK equation of the Sod shock tube over one position and one velocity axis.
+
+    The density relaxes at every position towards the maximum-entropy density with its density, momentum, and energy,
+    and the gas starts from the two states of the shock tube of Sod on either side of the middle of a unit interval. As
+    the Knudsen number falls the density moment tends to the Euler solution with the adiabatic index 3 of one velocity
+    dimension.
+
+    Args:
+        positions:
+            The number of positions.
+
+        velocities:
+            The number of points of the velocity axis.
+
+        knudsen:
+            The Knudsen number, the relaxation time.
+
+        half_width:
+            The half-width of the velocity axis.
+
+    Returns:
+        system:
+            The model, with the density `gas.f`.
+
+    Examples:
+        >>> from skcomplex.models.physics.fluids import bgk_equation
+        >>> bgk_equation(8, 16).elements[0].check().prepare().size_
+        128
+    """
+    position = LatticeSpace((positions,), spacing=1.0 / positions, boundary='reflecting')
+    space = PhaseSpace(position, [AxisSpec('v', velocities, -half_width, half_width)]).check().prepare()
+    left = np.arange(positions) < positions // 2
+    density = np.where(left, 1.0, 0.125)
+    temperature = np.where(left, 1.0, 0.8)
+    values = _get_maxwellian(density, np.zeros(positions), temperature, space.coordinates_['v'])
+    gas = FieldElement(
+        'gas',
+        element=DensityElement,
+        space=space,
+        values={'f': values},
+        discretization='finite-volume',
+        visual=VLASOV_VISUAL,
+    )
+    stream = AdvectionInteraction('stream', target='gas', state='f', drift=_get_streaming)
+    relax = BhatnagarGrossKrookInteraction('relax', target='gas', axes=('v',), time=knudsen)
+    return System(elements=[gas], interactions=[stream, relax])
+
+
+@register_model(
+    field='physics/fluids',
+    tags=('field', 'kinetic', 'phase space', 'plasma', 'pde'),
+    references=('Bellomo et al. 2017', 'Cheng and Knorr 1976'),
+    defaults={'until': 30.0, 'dt': 0.25, 'solver': SemiLagrangianSolver(0.25)},
+)
+def vlasov_equation(
+    positions: int = 32,
+    velocities: int = 64,
+    *,
+    setup: str = 'landau',
+    amplitude: float = 0.01,
+    half_width: float = 6.0,
+) -> System:
+    """Return the Vlasov-Poisson equation of electrons over a neutralizing background, on a periodic position axis.
+
+    The electric field is solved from the density moment at every step. The set-up `'landau'` starts from a Maxwellian
+    with a density wave of wave number 0.5, whose electric energy decays at twice the Landau damping rate 0.1533. The
+    set-up `'two-stream'` starts from two beams of temperature 0.25 at the velocities -1.5 and 1.5, which are unstable
+    at the wave number 0.5.
+
+    Args:
+        positions:
+            The number of positions.
+
+        velocities:
+            The number of points of the velocity axis.
+
+        setup:
+            `'landau'` or `'two-stream'`.
+
+        amplitude:
+            The relative amplitude of the initial density wave.
+
+        half_width:
+            The half-width of the velocity axis.
+
+    Returns:
+        system:
+            The model, with the density `gas.f`.
+
+    Raises:
+        ValidationError:
+            The set-up is unknown.
+
+    Examples:
+        >>> from skcomplex.models.physics.fluids import vlasov_equation
+        >>> vlasov_equation(8, 16).elements[0].check().prepare().size_
+        128
+    """
+    if setup not in SETUPS:
+        error_msg = f'Unknown set-up {setup!r} of the Vlasov equation. Use one of {", ".join(SETUPS)}.'
+        raise ValidationError(error_msg)
+    length = 4 * math.pi
+    space = PhaseSpace(
+        LatticeSpace((positions,), spacing=length / positions),
+        [AxisSpec('v', velocities, -half_width, half_width)],
+    )
+    space.check().prepare()
+    x = np.arange(positions) * length / positions
+    v = space.coordinates_['v']
+    profile = np.exp(-(v**2) / 2) / np.sqrt(2 * np.pi)
+    if setup == 'two-stream':
+        profile = (np.exp(-2 * (v - 1.5) ** 2) + np.exp(-2 * (v + 1.5) ** 2)) * np.sqrt(2 / np.pi) / 2
+    gas = FieldElement(
+        'gas',
+        element=DensityElement,
+        space=space,
+        values={'f': np.outer(1.0 + amplitude * np.cos(0.5 * x), profile)},
+        discretization='finite-volume',
+        visual=VLASOV_VISUAL,
+    )
+    return System(
+        elements=[gas],
+        interactions=[AdvectionInteraction('vlasov', target='gas', state='f', drift=_get_poisson_drift)],
+    )

skcomplex/models/physics/fluids/_kinetics.py

@@ -0,0 +1,147 @@
+"""Kinetic and wave transport models: wave-number conservation with breaking, and discrete-velocity gases."""
+
+# Author: Georgios Douzas <gdouzas@icloud.com>
+# License: MIT
+
+import math
+from types import SimpleNamespace
+
+import numpy as np
+from sage.all__sagemath_symbolics import Expression, sqrt
+
+from ....core.elements import FieldElement
+from ....core.interactions import ConservationInteraction
+from ....core.spaces import LatticeSpace
+from ....core.system import System
+from ....engine.solvers import SSPRKSolver
+from ..._catalog import register_model
+from ._carleman_gas import CarlemanGasElement
+from ._wave_number import WaveNumberElement
+
+
+def _get_collisions(s: SimpleNamespace) -> Expression:
+    """Return the net rate `kappa (f_minus^2 - f_plus^2)` at which collisions turn left movers into right movers."""
+    return s.target.kappa * (s.target.f_minus**2 - s.target.f_plus**2)
+
+
+@register_model(
+    field='physics/fluids',
+    tags=('field', 'waves', 'breaking', 'conservation law', 'finite volume', 'pde'),
+    references=('Whitham 1974', 'Forrest 2018'),
+    defaults={'until': 20.0, 'dt': 0.5, 'solver': SSPRKSolver()},
+)
+def wave_breaking(n: int = 200, *, k0: float = 1.0, amplitude: float = 0.5, g: float = 1.0) -> System:
+    """Return the kinematic wave equation of deep-water wave trains on a periodic interval of length 2 pi.
+
+    The wave number starts as `k0 (1 + amplitude sin x)` and steepens into a jump, a break of the wavelength, at the
+    time `1 / max(-C'(k0(x)) k0'(x))` of the first crossing of characteristics. Finite volumes conserve the total
+    number of waves.
+
+    Args:
+        n:
+            The number of cells.
+
+        k0:
+            The mean initial wave number.
+
+        amplitude:
+            The relative amplitude of the initial modulation, below 1.
+
+        g:
+            The gravitational acceleration.
+
+    Returns:
+        system:
+            The model, with the wave number `train.k`.
+
+    Examples:
+        >>> from skcomplex.models.physics.fluids import wave_breaking
+        >>> wave_breaking(16).elements[0].check().prepare().size_
+        16
+    """
+    spacing = 2 * math.pi / n
+    centers = (np.arange(n) + 0.5) * spacing
+    values = {'k': k0 * (1 + amplitude * np.sin(centers)), 'g': g}
+    space = LatticeSpace(n, spacing=spacing)
+    return System(
+        elements=[
+            FieldElement(
+                'train',
+                element=WaveNumberElement,
+                space=space,
+                values=values,
+                discretization='finite-volume',
+            ),
+        ],
+        interactions=[
+            ConservationInteraction('action', target='train', state='k', flux=lambda s: sqrt(s.target.g * s.target.k)),
+        ],
+    )
+
+
+@register_model(
+    field='physics/fluids',
+    tags=('field', 'kinetic theory', 'discrete velocities', 'finite volume', 'pde'),
+    references=('Carleman 1957', 'Gatignol 1975', 'Bellomo et al. 2017'),
+    defaults={'until': 5.0, 'dt': 0.1, 'solver': SSPRKSolver()},
+)
+def discrete_velocity_boltzmann(
+    n: int = 200,
+    *,
+    c: float = 1.0,
+    kappa: float = 1.0,
+    length: float = 10.0,
+) -> System:
+    """Return the Carleman discrete-velocity Boltzmann equation on a periodic line, from a pulse of right movers.
+
+    A pulse of right-moving particles on a uniform background splits into two moving pulses while collisions relax
+    every site towards equal densities, and the total mass stays constant.
+
+    Args:
+        n:
+            The number of cells.
+
+        c:
+            The particle speed.
+
+        kappa:
+            The collision rate.
+
+        length:
+            The length of the line.
+
+    Returns:
+        system:
+            The model, with the densities `gas.f_plus` and `gas.f_minus`.
+
+    Examples:
+        >>> from skcomplex.models.physics.fluids import discrete_velocity_boltzmann
+        >>> discrete_velocity_boltzmann(16).elements[0].check().prepare().size_
+        16
+    """
+    spacing = length / n
+    centers = (np.arange(n) + 0.5) * spacing
+    pulse = np.exp(-((centers - length / 2) ** 2))
+    values = {'f_plus': 0.5 + pulse, 'f_minus': np.full(n, 0.5), 'c': c, 'kappa': kappa}
+    space = LatticeSpace(n, spacing=spacing)
+    return System(
+        elements=[
+            FieldElement('gas', element=CarlemanGasElement, space=space, values=values, discretization='finite-volume'),
+        ],
+        interactions=[
+            ConservationInteraction(
+                'right_movers',
+                target='gas',
+                state='f_plus',
+                flux=lambda s: s.target.c * s.target.f_plus,
+                source=_get_collisions,
+            ),
+            ConservationInteraction(
+                'left_movers',
+                target='gas',
+                state='f_minus',
+                flux=lambda s: -s.target.c * s.target.f_minus,
+                source=lambda s: -_get_collisions(s),
+            ),
+        ],
+    )

skcomplex/models/physics/fluids/_kuramoto_sivashinsky.py

@@ -0,0 +1,41 @@
+"""Site of a flame front or a thin film, `du/dt = -d(u^2 / 2)/dx - laplacian(u) - laplacian(laplacian(u))`."""
+
+# Author: Georgios Douzas <gdouzas@icloud.com>
+# License: MIT
+
+from typing import Annotated
+
+from ....core.elements import Element
+from ....specs import StateSpec, VisualSpec
+
+
+class KuramotoSivashinskyElement(Element):
+    """Site of a flame front or a thin film, `du/dt = -d(u^2 / 2)/dx - laplacian(u) - laplacian(laplacian(u))`.
+
+    The conservation of the flux `u^2 / 2` and the rate of the linear operator are interactions of the model.
+
+    Args:
+        label:
+            The label of the site.
+
+        visual:
+            How the site is drawn, or `None` for none.
+
+        u:
+            The initial height of the front.
+
+    Examples:
+        >>> from skcomplex.models.physics.fluids import KuramotoSivashinskyElement
+        >>> KuramotoSivashinskyElement('site', u=0.5).u
+        0.5
+    """
+
+    def __init__(
+        self,
+        label: str,
+        visual: VisualSpec | None = None,
+        *,
+        u: Annotated[float, StateSpec()] = 0.0,
+    ) -> None:
+        super().__init__(label, visual=visual)
+        self.u = u