tud_lbm.operators.differential
==============================

.. py:module:: tud_lbm.operators.differential

.. autoapi-nested-parse::

   Differential operators — composite builder and primitives.

   Public API: build_diff_ops()

   Implementation modules are internal; use the factory to access.

   .. rubric:: Example

   from operators.differential import build_diff_ops

   gradient_standard, gradient, laplacian = build_diff_ops(config, mp_params, lattice)



Functions
---------

.. autoapisummary::

   tud_lbm.operators.differential.build_differential_fn
   tud_lbm.operators.differential.build_diff_ops


Package Contents
----------------

.. py:function:: build_differential_fn(scheme: str) -> tud_lbm.operators.protocols.DifferentialOperator

   Return a differential operator satisfying DifferentialOperator protocol.

   :param scheme: Differential operator name.

   :returns: A callable satisfying the DifferentialOperator protocol.

   :raises ValueError: If scheme is not registered.


.. py:function:: build_diff_ops(config: tud_lbm.config.simulation_config.SimulationConfig, mp_params: tud_lbm.operators.macroscopic.MultiphaseParams | None, lattice: tud_lbm.lattice.lattice.Lattice) -> tuple[collections.abc.Callable, collections.abc.Callable, collections.abc.Callable, collections.abc.Callable | None, collections.abc.Callable | None]

   Build gradient/laplacian closures, wetting-aware if applicable.

   Ensures boundary-condition modules are imported so that their
   ``@boundary_condition`` decorators have fired before we query
   pad-edge-mode metadata.

   Returns five items:

   * **gradient_standard**: ``(grid) → result``. Standard gradient ∇μ.
   * **gradient_density**: Density gradient ∇ρ, used in source terms.
   * **laplacian_density**: Laplacian ∇²ρ, used in chemical potential.
   * **gradient_density_wetting**: Parametric density gradient ``(grid, phi_l, phi_r, d_rho_l, d_rho_r) → result``.
     ``None`` unless hysteresis is configured.
   * **laplacian_density_wetting**: Parametric Laplacian ``(grid, phi_l, phi_r, d_rho_l, d_rho_r) → result``.
     ``None`` unless hysteresis is configured.

   Design:

   * **Non-wetting**: All returned closures accept only ``(grid)``.
     ``gradient_density_wetting`` and ``laplacian_density_wetting`` are ``None``.
   * **Fixed wetting** (wetting config but no hysteresis): Same behavior as non-wetting.
     ``gradient_density`` and ``laplacian_density`` close over static wetting parameters.
     ``gradient_density_wetting`` and ``laplacian_density_wetting`` are ``None``.
   * **Hysteresis**: ``gradient_density`` and ``laplacian_density`` are initial closures
     seeded with wetting parameters (explicit or neutral defaults).
     ``gradient_density_wetting`` and ``laplacian_density_wetting`` are the parametric factories
     used by the hysteresis optimizer to build trial-step operators.

   :param config: Validated simulation configuration.
   :param mp_params: Multiphase parameters (``None`` for single-phase).
   :param lattice: The simulation :class:`Lattice` (weights, velocities).

   :returns: ``(gradient_standard,
             gradient_density, laplacian_density,
             gradient_density_wetting, laplacian_density_wetting)``