struphy 3.0.2__tar.gz → 3.0.3__tar.gz

{struphy-3.0.2/src/struphy.egg-info → struphy-3.0.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: struphy
-Version: 3.0.2
+Version: 3.0.3
 Summary: Multi-model plasma physics package
 Author: Max Planck Institute for Plasma Physics
 Author-email: stefan.possanner@ipp.mpg.de, max.lindqvist@ipp.mpg.de, eric.sonnendruecker@ipp.mpg.de
@@ -30,61 +30,61 @@ Classifier: Programming Language :: Python :: 3
 Requires-Python: >=3.10
 Description-Content-Type: text/markdown
 License-File: LICENSE
-Requires-Dist: numpy
-Requires-Dist: cunumpy
-Requires-Dist: pyccel>=2.1
-Requires-Dist: feectools
-Requires-Dist: scipy
-Requires-Dist: h5py
-Requires-Dist: matplotlib
-Requires-Dist: pyyaml
-Requires-Dist: vtk
-Requires-Dist: tqdm
-Requires-Dist: argcomplete
-Requires-Dist: pytest
-Requires-Dist: pytest-mpi
-Requires-Dist: pytest-testmon
-Requires-Dist: line_profiler
-Requires-Dist: scope-profiler>=0.1.7
+Requires-Dist: numpy<=2.2.6
+Requires-Dist: cunumpy<=0.1
+Requires-Dist: pyccel<=2.1.0,>=2.1
+Requires-Dist: feectools<=0.1.3
+Requires-Dist: scipy<=1.15.3
+Requires-Dist: h5py<=3.15.1
+Requires-Dist: matplotlib<=3.10.7
+Requires-Dist: pyyaml<=6.0.3
+Requires-Dist: vtk<=9.6.0
+Requires-Dist: tqdm<=4.67.3
+Requires-Dist: argcomplete<=3.6.3
+Requires-Dist: plotly<=6.4.0
+Requires-Dist: pytest<=9.0.2
+Requires-Dist: pytest-mpi<=0.6
+Requires-Dist: pytest-testmon<=2.2.0
+Requires-Dist: line_profiler<=5.0.1
+Requires-Dist: scope-profiler<=0.1.7,>=0.1.7
 Provides-Extra: phys
-Requires-Dist: gvec>=1.1.0; extra == "phys"
-Requires-Dist: desc-opt; extra == "phys"
+Requires-Dist: gvec<=1.3.1,>=1.1.0; extra == "phys"
+Requires-Dist: desc-opt<=0.16.0; extra == "phys"
 Provides-Extra: dev
 Requires-Dist: struphy[mpi]; extra == "dev"
-Requires-Dist: notebook; extra == "dev"
-Requires-Dist: autopep8; extra == "dev"
-Requires-Dist: isort; extra == "dev"
-Requires-Dist: flake8; extra == "dev"
-Requires-Dist: pylint; extra == "dev"
-Requires-Dist: ssort; extra == "dev"
-Requires-Dist: add-trailing-comma; extra == "dev"
-Requires-Dist: ruff>=0.15.0; extra == "dev"
-Requires-Dist: pre-commit; extra == "dev"
-Requires-Dist: nbstripout; extra == "dev"
-Requires-Dist: tabulate; extra == "dev"
-Requires-Dist: tomli-w; extra == "dev"
-Requires-Dist: kaleido; extra == "dev"
-Requires-Dist: pandas; extra == "dev"
-Requires-Dist: plotly; extra == "dev"
+Requires-Dist: notebook<=7.5.3; extra == "dev"
+Requires-Dist: autopep8<=2.3.2; extra == "dev"
+Requires-Dist: isort<=8.0.0; extra == "dev"
+Requires-Dist: flake8<=7.3.0; extra == "dev"
+Requires-Dist: pylint<=4.0.5; extra == "dev"
+Requires-Dist: ssort<=0.16.0; extra == "dev"
+Requires-Dist: add-trailing-comma<=4.0.0; extra == "dev"
+Requires-Dist: ruff<=0.15.2,>=0.15.0; extra == "dev"
+Requires-Dist: pre-commit<=4.5.1; extra == "dev"
+Requires-Dist: nbstripout<=0.9.1; extra == "dev"
+Requires-Dist: tabulate<=0.9.0; extra == "dev"
+Requires-Dist: tomli-w<=1.2.0; extra == "dev"
+Requires-Dist: kaleido<=1.2.0; extra == "dev"
+Requires-Dist: pandas<=3.0.1; extra == "dev"
 Provides-Extra: mpi
-Requires-Dist: mpi4py; extra == "mpi"
+Requires-Dist: mpi4py<=4.1.1; extra == "mpi"
 Provides-Extra: doc
 Requires-Dist: struphy[phys]; extra == "doc"
-Requires-Dist: jupyter; extra == "doc"
-Requires-Dist: nbconvert; extra == "doc"
-Requires-Dist: ipykernel; extra == "doc"
-Requires-Dist: sphinx; extra == "doc"
-Requires-Dist: sphinx-design; extra == "doc"
-Requires-Dist: lxml_html_clean; extra == "doc"
-Requires-Dist: sphinxcontrib-napoleon; extra == "doc"
-Requires-Dist: sphinx-copybutton; extra == "doc"
-Requires-Dist: pydata-sphinx-theme; extra == "doc"
-Requires-Dist: nbsphinx; extra == "doc"
-Requires-Dist: m2r2; extra == "doc"
-Requires-Dist: myst-parser; extra == "doc"
-Requires-Dist: mistune; extra == "doc"
-Requires-Dist: docutils; extra == "doc"
-Requires-Dist: ipyparallel; extra == "doc"
+Requires-Dist: jupyter<=1.1.1; extra == "doc"
+Requires-Dist: nbconvert<=6.5.4; extra == "doc"
+Requires-Dist: ipykernel<=7.1.0; extra == "doc"
+Requires-Dist: sphinx<=9.1.0; extra == "doc"
+Requires-Dist: sphinx-design<=0.7.0; extra == "doc"
+Requires-Dist: lxml_html_clean<=0.4.3; extra == "doc"
+Requires-Dist: sphinxcontrib-napoleon<=0.7; extra == "doc"
+Requires-Dist: sphinx-copybutton<=0.5.2; extra == "doc"
+Requires-Dist: pydata-sphinx-theme<=0.16.1; extra == "doc"
+Requires-Dist: nbsphinx<=0.9.8; extra == "doc"
+Requires-Dist: m2r2<=0.3.4; extra == "doc"
+Requires-Dist: myst-parser<=5.0.0; extra == "doc"
+Requires-Dist: mistune<=0.8.4; extra == "doc"
+Requires-Dist: docutils<=0.22.4; extra == "doc"
+Requires-Dist: ipyparallel<=9.0.2; extra == "doc"
 Provides-Extra: likwid
 Requires-Dist: struphy[dev]; extra == "likwid"
 Requires-Dist: pylikwid; extra == "likwid"

{struphy-3.0.2 → struphy-3.0.3}/pyproject.toml

@@ -6,7 +6,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "struphy"
-version = "3.0.2"
+version = "3.0.3"
 readme = "README.md"
 requires-python = ">=3.10"
 authors = [
@@ -21,24 +21,25 @@ keywords = [
 ]
 classifiers = [
     "Programming Language :: Python :: 3",
-    ]
+]
 dependencies = [
-    'numpy',
-    'cunumpy',
-    'pyccel>=2.1',
-    'feectools',
-    'scipy',
-    'h5py',
-    'matplotlib',
-    'pyyaml',
-    'vtk',
-    'tqdm',
-    'argcomplete',
-    'pytest',
-    'pytest-mpi',
-    'pytest-testmon',
-    'line_profiler',
-    'scope-profiler>=0.1.7',
+    "numpy<=2.2.6",
+    "cunumpy<=0.1",
+    "pyccel<=2.1.0, >=2.1",
+    "feectools<=0.1.3",
+    "scipy<=1.15.3",
+    "h5py<=3.15.1",
+    "matplotlib<=3.10.7",
+    "pyyaml<=6.0.3",
+    "vtk<=9.6.0",
+    "tqdm<=4.67.3",
+    "argcomplete<=3.6.3",
+    "plotly<=6.4.0",
+    "pytest<=9.0.2",
+    "pytest-mpi<=0.6",
+    "pytest-testmon<=2.2.0",
+    "line_profiler<=5.0.1",
+    "scope-profiler<=0.1.7, >=0.1.7",
 ]
 
 [project.license]
@@ -46,47 +47,46 @@ file = "LICENSE"
 
 [project.optional-dependencies]
 phys = [
-    'gvec>=1.1.0',
-    'desc-opt',
+    "gvec<=1.3.1, >=1.1.0",
+    "desc-opt<=0.16.0",
 ]
 dev = [
     "struphy[mpi]",
-    "notebook",
-    "autopep8",
-    "isort",
-    "flake8",
-    "pylint",
-    "ssort",
-    "add-trailing-comma",
-    "ruff>=0.15.0",
-    "pre-commit",
-    "nbstripout",
-    "tabulate",
-    "tomli-w",
-    "kaleido",
-    "pandas",
-    "plotly",
+    "notebook<=7.5.3",
+    "autopep8<=2.3.2",
+    "isort<=8.0.0",
+    "flake8<=7.3.0",
+    "pylint<=4.0.5",
+    "ssort<=0.16.0",
+    "add-trailing-comma<=4.0.0",
+    "ruff<=0.15.2, >=0.15.0",
+    "pre-commit<=4.5.1",
+    "nbstripout<=0.9.1",
+    "tabulate<=0.9.0",
+    "tomli-w<=1.2.0",
+    "kaleido<=1.2.0",
+    "pandas<=3.0.1",
 ]
 mpi = [
-    'mpi4py',
+    "mpi4py<=4.1.1",
 ]
 doc = [
     "struphy[phys]",
-    "jupyter",
-    "nbconvert",
-    "ipykernel",
-    "sphinx",
-    "sphinx-design",
-    "lxml_html_clean",
-    "sphinxcontrib-napoleon",
-    "sphinx-copybutton",
-    "pydata-sphinx-theme",
-    "nbsphinx",
-    "m2r2",
-    "myst-parser",
-    "mistune",
-    "docutils",
-    "ipyparallel",
+    "jupyter<=1.1.1",
+    "nbconvert<=6.5.4",
+    "ipykernel<=7.1.0",
+    "sphinx<=9.1.0",
+    "sphinx-design<=0.7.0",
+    "lxml_html_clean<=0.4.3",
+    "sphinxcontrib-napoleon<=0.7",
+    "sphinx-copybutton<=0.5.2",
+    "pydata-sphinx-theme<=0.16.1",
+    "nbsphinx<=0.9.8",
+    "m2r2<=0.3.4",
+    "myst-parser<=5.0.0",
+    "mistune<=0.8.4",
+    "docutils<=0.22.4",
+    "ipyparallel<=9.0.2",
 ]
 likwid = [
     "struphy[dev]",
@@ -137,17 +137,12 @@ ignore = [
 [tool.isort]
 profile = "black"
 line_length = 120
-# multi_line_output = 3
-# include_trailing_comma = true
-# force_grid_wrap = 0
-# combine_as_imports = true
 
 [tool.pylint]
 max-line-length = 120
 
 [tool.ruff]
 line-length = 120
-# exclude = ["__pyccel__"]
 
 [tool.ruff.lint]
 ignore = [
@@ -165,7 +160,7 @@ ignore = [
     "F405",
     "D211",
     "D213",
-    "F841", # Ignore unused variables
+    "F841",
 ]
 
 [tool.pytest.ini_options]

{struphy-3.0.2 → struphy-3.0.3}/src/struphy/__init__.py

@@ -18,6 +18,8 @@ from struphy.api.particles import (
     WeightsParameters,
 )
 from struphy.api.perturbations import perturbations
+from struphy.api.post_processing import PlottingData, PostProcessor
+from struphy.api.simulation import Simulation
 
 __all__ = [
     "domains",
@@ -36,4 +38,7 @@ __all__ = [
     "DerhamOptions",
     "FieldsBackground",
     "ButcherTableau",
+    "PostProcessor",
+    "PlottingData",
+    "Simulation",
 ]

{struphy-3.0.2 → struphy-3.0.3}/src/struphy/api/models/__init__.py

@@ -6,7 +6,6 @@ from struphy.models.deterministic_particle_diffusion import (
 from struphy.models.drift_kinetic_electrostatic_adiabatic import (
     DriftKineticElectrostaticAdiabatic,
 )
-from struphy.models.euler_sph import EulerSPH
 from struphy.models.guiding_center import GuidingCenter
 from struphy.models.hasegawa_wakatani import HasegawaWakatani
 from struphy.models.linear_extended_mh_duniform import LinearExtendedMHDuniform
@@ -49,7 +48,6 @@ __all__ = [
     "ColdPlasmaVlasov",
     "DeterministicParticleDiffusion",
     "DriftKineticElectrostaticAdiabatic",
-    "EulerSPH",
     "GuidingCenter",
     "HasegawaWakatani",
     "LinearExtendedMHDuniform",

struphy-3.0.3/src/struphy/api/post_processing/__init__.py

@@ -0,0 +1,3 @@
+from struphy.post_processing.post_processing_tools import PlottingData, PostProcessor
+
+__all__ = ["PostProcessor", "PlottingData"]

struphy-3.0.3/src/struphy/api/simulation/__init__.py

@@ -0,0 +1,3 @@
+from struphy.simulation.sim import Simulation
+
+all = ["Simulation",]

{struphy-3.0.2 → struphy-3.0.3}/src/struphy/feec/psydac_derham.py

@@ -890,7 +890,7 @@ class Derham:
         perturbations: Perturbation | list = None,
         domain: Domain = None,
         equil: FluidEquilibrium = None,
-        verbose: bool = True,
+        verbose: bool = False,
     ):
         """Creat a callable spline function.
 
@@ -1442,7 +1442,7 @@ class SplineFunction:
         perturbations: Perturbation | list = None,
         domain: Domain = None,
         equil: FluidEquilibrium = None,
-        verbose: bool = True,
+        verbose: bool = False,
     ):
         self._name = name
         self._space_id = space_id
@@ -1494,7 +1494,7 @@ class SplineFunction:
             print(f"\nAllocated SplineFuntion '{self.name}' in space '{self.space_id}'.")
 
         if self.backgrounds is not None or self.perturbations is not None:
-            self.initialize_coeffs(domain=self.domain, equil=self.equil)
+            self.initialize_coeffs(domain=self.domain, equil=self.equil, verbose=verbose)
 
     @property
     def name(self):
@@ -1675,6 +1675,7 @@ class SplineFunction:
         perturbations: Perturbation | list = None,
         domain: Domain = None,
         equil: FluidEquilibrium = None,
+        verbose: bool = False,
     ):
         """
         Set the initial conditions for self.vector.
@@ -1707,14 +1708,14 @@ class SplineFunction:
         # start from zero coeffs
         self._vector *= 0.0
 
-        if MPI.COMM_WORLD.Get_rank() == 0:
+        if verbose and MPI.COMM_WORLD.Get_rank() == 0:
             print(f"Initializing {self.name} ...")
 
         # add backgrounds to initial vector
         if self.backgrounds is not None:
             for fb in self.backgrounds:
                 assert isinstance(fb, FieldsBackground)
-                if MPI.COMM_WORLD.Get_rank() == 0:
+                if verbose and MPI.COMM_WORLD.Get_rank() == 0:
                     print(f"Adding background {fb} ...")
 
                 # special case of const
@@ -1769,7 +1770,7 @@ class SplineFunction:
         # add perturbations to coefficient vector
         if self.perturbations is not None:
             for ptb in self.perturbations:
-                if MPI.COMM_WORLD.Get_rank() == 0:
+                if verbose and MPI.COMM_WORLD.Get_rank() == 0:
                     print(f"Adding perturbation {ptb} ...")
 
                 # special case of white noise in logical space for different components

{struphy-3.0.2 → struphy-3.0.3}/src/struphy/fields_background/base.py

@@ -11,14 +11,60 @@ from struphy.geometry.base import Domain
 
 class FluidEquilibrium(metaclass=ABCMeta):
     """
-    Base class for callable fluid equilibria consisting of at least
-    u (velocity), p (pressure) and n (density).
-
-    Any child class must provide  the following callables:
-
-    * either ``u_xyz`` or override ``uv``
-    * either ``p_xyz`` or override ``p0``
-    * either ``n_xyz`` or override ``n0``
+    Abstract base class for callable fluid equilibria on arbitrary domains.
+
+    This class provides a unified interface for representing fluid equilibrium states,
+    including velocity, pressure, and number density fields. It supports coordinate
+    transformations between logical (reference) and physical domains through the Domain
+    object, enabling computations on mapped domains.
+
+    Attributes
+    ----------
+    params : dict
+        Dictionary of parameters passed to the class initialization. Automatically
+        strips 'self' and '__class__' entries.
+    domain : Domain
+        Domain object that characterizes the mapping from the logical cube [0, 1]^3
+        to the physical domain. Enables coordinate transformations and differential
+        form conversions (0-forms, 1-forms, 2-forms, 3-forms).
+
+    Implementation Requirements
+    ---------------------------
+    Child classes must provide at least one method from each of these pairs:
+
+    * Velocity: either ``u_xyz`` (Cartesian) or override ``uv`` (logical coordinates)
+    * Pressure: either ``p_xyz`` (Cartesian) or override ``p0`` (0-form on logical domain)
+    * Number Density: either ``n_xyz`` (Cartesian) or override ``n0`` (0-form on logical domain)
+
+    Derived Quantities
+    ------------------
+    The class automatically provides derived fields computed from the basic fields:
+
+    * Temperature: ``t0``, ``t3`` (from p/n)
+    * Thermal velocity: ``vth0``, ``vth3`` (from temperature)
+    * Entropy density: ``s0_monoatomic``, ``s3_monoatomic``, ``s0_diatomic``, ``s3_diatomic``
+
+    Differential Forms
+    -------------------
+    Vector fields (velocity) are available as:
+
+    * ``uv``: contravariant components on logical domain
+    * ``u1``: 1-form components
+    * ``u2``: 2-form components
+    * ``u_cart``: Cartesian components with physical coordinates
+
+    Scalar fields are available as 0-forms (point values) and 3-forms (densities):
+
+    * ``p0``, ``p3``: pressure
+    * ``n0``, ``n3``: number density
+    * ``t0``, ``t3``: temperature
+    * ``q0``, ``q3``: square root of pressure
+
+    Notes
+    -----
+    The class uses abstract methods to enforce implementation in child classes.
+    Subclasses should override coordinate-appropriate base methods (CartesianFluidEquilibrium
+    or LogicalFluidEquilibrium) to simplify implementation.
     """
 
     @property
@@ -50,6 +96,13 @@ class FluidEquilibrium(metaclass=ABCMeta):
         assert isinstance(new_domain, Domain) or new_domain is None
         self._domain = new_domain
 
+    def __repr__(self):
+        out = f"{self.__class__.__name__}"
+        for k, v in self.params.items():
+            out += f"\n    {k}:".ljust(20)
+            out += f"{v}"
+        return out
+
     ###########################
     # Vector-valued callables #
     ###########################
@@ -256,7 +309,11 @@ class FluidEquilibrium(metaclass=ABCMeta):
 
 class CartesianFluidEquilibrium(FluidEquilibrium):
     r"""
-    The callables ``u_xyz``, ``p_xyz`` and ``n_xyz`` must be provided in Cartesian coordinates.
+    Specialization for equilibria defined in Cartesian coordinates.
+
+    Child classes must implement the abstract methods ``u_xyz``, ``p_xyz``, and ``n_xyz``,
+    which return velocity, pressure, and number density in Cartesian physical space (x, y, z).
+    The base class automatically handles coordinate transformations and differential form conversions.
     """
 
     @abstractmethod
@@ -282,7 +339,12 @@ class CartesianFluidEquilibrium(FluidEquilibrium):
 
 class LogicalFluidEquilibrium(FluidEquilibrium):
     r"""
-    The callables ``uv``, ``p0`` and ``n0`` must be provided on the logical cube [0, 1]^3.
+    Specialization for equilibria defined on the logical cube [0, 1]^3.
+
+    Child classes must implement the abstract methods ``uv``, ``p0``, and ``n0``,
+    which return contravariant velocity, 0-form pressure, and 0-form number density
+    on the logical reference domain. Useful for direct implementation when physical
+    coordinates are obtained via coordinate transformation through the domain mapping.
     """
 
     @abstractmethod
@@ -309,8 +371,11 @@ class LogicalFluidEquilibrium(FluidEquilibrium):
 
 class NumericalFluidEquilibrium(LogicalFluidEquilibrium):
     r"""
-    Must provide a (numerical) mapping from the logical cube [0, 1]^3 to the physical domain.
-    Overrides base class domain.
+    Specialization for equilibria with numerically computed domain mappings.
+
+    Child classes must provide a ``numerical_domain`` property that returns a Domain object
+    representing the mapping from the logical cube [0, 1]^3 to the physical domain.
+    This class overrides the domain property to use the numerically computed mapping.
     """
 
     @property
@@ -327,12 +392,11 @@ class NumericalFluidEquilibrium(LogicalFluidEquilibrium):
 
 class FluidEquilibriumWithB(FluidEquilibrium):
     """
-    :ref:`FluidEquilibrium` with B (magnetic field) in addition.
-
-    Any child class must provide the following callables:
+    Extension of FluidEquilibrium with magnetic field and its gradient.
 
-    * either ``b_xyz`` or override ``bv``
-    * either ``gradB_xyz`` or override ``gradB1``
+    Child classes must implement either Cartesian (``b_xyz``, ``gradB_xyz``) or
+    logical (``bv``, ``gradB1``) methods for magnetic field and its gradient.
+    Provides methods for 1-form and 2-form transformations of the magnetic field.
     """
 
     @FluidEquilibrium.domain.setter
@@ -624,7 +688,10 @@ class FluidEquilibriumWithB(FluidEquilibrium):
 
 class CartesianFluidEquilibriumWithB(CartesianFluidEquilibrium):
     r"""
-    The callables ``b_xyz`` and ``gradB_xyz`` must be provided in Cartesian coordinates.
+    Specialization for fluid equilibria with magnetic field in Cartesian coordinates.
+
+    Child classes must implement the abstract methods ``b_xyz`` and ``gradB_xyz``,
+    which return magnetic field and its gradient strength in Cartesian physical space.
     """
 
     @abstractmethod
@@ -645,7 +712,10 @@ class CartesianFluidEquilibriumWithB(CartesianFluidEquilibrium):
 
 class LogicalFluidEquilibriumWithB(LogicalFluidEquilibrium):
     r"""
-    The callable ``bv`` must be provided on the logical cube [0, 1]^3.
+    Specialization for fluid equilibria with magnetic field on the logical cube [0, 1]^3.
+
+    Child classes must implement the abstract methods ``bv`` (contravariant magnetic field)
+    and ``gradB1`` (1-form gradient of magnetic field strength) on the logical domain.
     """
 
     @abstractmethod
@@ -669,8 +739,10 @@ class LogicalFluidEquilibriumWithB(LogicalFluidEquilibrium):
 
 class NumericalFluidEquilibriumWithB(LogicalFluidEquilibriumWithB):
     r"""
-    Must provide a (numerical) mapping from the logical cube [0, 1]^3 to the physical domain.
-    Overrides base class domain.
+    Specialization for fluid equilibria with magnetic field and numerically computed domain mappings.
+
+    Child classes must provide a ``numerical_domain`` property that returns a Domain object.
+    This class overrides the domain property to use the numerically computed mapping.
     """
 
     @property
@@ -687,12 +759,12 @@ class NumericalFluidEquilibriumWithB(LogicalFluidEquilibriumWithB):
 
 class MHDequilibrium(FluidEquilibriumWithB):
     """
-    :ref:`FluidEquilibriumWithB` with j (current density) in addition.
-    The mean velocity is returned as j/n (overriding the base class).
-
-    Any child class must provide  the following callables:
+    Extension of FluidEquilibriumWithB with current density field.
 
-    * either ``j_xyz`` or override ``jv``
+    Child classes must implement either Cartesian (``j_xyz``) or logical (``jv``) methods
+    for current density. The velocity field is derived from current density as j/n,
+    overriding the base FluidEquilibrium. Provides methods for 1-form and 2-form
+    transformations of the current density.
     """
 
     @FluidEquilibriumWithB.domain.setter
@@ -1221,8 +1293,10 @@ class MHDequilibrium(FluidEquilibriumWithB):
 
 class CartesianMHDequilibrium(MHDequilibrium):
     r"""
-    The callables ``b_xyz``, ``j_xyz``, ``p_xyz``, ``n_xyz`` and ``gradB_xyz``
-    must be provided in Cartesian coordinates.
+    Specialization for MHD equilibria in Cartesian coordinates.
+
+    Child classes must implement the abstract methods ``b_xyz``, ``j_xyz``, ``p_xyz``,
+    ``n_xyz``, and ``gradB_xyz`` in Cartesian physical space.
     """
 
     @abstractmethod
@@ -1395,8 +1469,10 @@ class AxisymmMHDequilibrium(CartesianMHDequilibrium):
 
 class LogicalMHDequilibrium(MHDequilibrium):
     r"""
-    The callables ``bv``, ``jv``, ``p0``, ``n0`` and ``gradB1``
-    must be provided on the logical cube [0, 1]^3.
+    Specialization for MHD equilibria on the logical cube [0, 1]^3.
+
+    Child classes must implement the abstract methods ``bv``, ``jv``, ``p0``, ``n0``,
+    and ``gradB1`` on the logical reference domain.
     """
 
     @abstractmethod
@@ -1439,8 +1515,10 @@ class LogicalMHDequilibrium(MHDequilibrium):
 
 class NumericalMHDequilibrium(LogicalMHDequilibrium):
     r"""
-    Must provide a (numerical) mapping from the logical cube [0, 1]^3 to the physical domain.
-    Overrides base class domain.
+    Specialization for MHD equilibria with numerically computed domain mappings.
+
+    Child classes must provide a ``numerical_domain`` property that returns a Domain object.
+    This class overrides the domain property to use the numerically computed mapping.
     """
 
     @property