diff --git a/doc/RTD/source/HydroSchemes/index.rst b/doc/RTD/source/HydroSchemes/index.rst index 3b511e03c0d0e92c6b663050d4c85df87860316f..d77649ee608bc17796339d2019e1b9e391f7eecf 100644 --- a/doc/RTD/source/HydroSchemes/index.rst +++ b/doc/RTD/source/HydroSchemes/index.rst @@ -2,7 +2,7 @@ Josh Borrow 4th April 2018 .. _hydro: - + Hydrodynamics Schemes ===================== @@ -39,8 +39,8 @@ In case the case of a 2 loop scheme, SWIFT removes the gradient loop and the ext sphenix_sph gasoline_sph phantom_sph + remix_sph adaptive_softening gizmo shadowswift adding_your_own - diff --git a/doc/RTD/source/HydroSchemes/remix_sph.rst b/doc/RTD/source/HydroSchemes/remix_sph.rst new file mode 100644 index 0000000000000000000000000000000000000000..e1a05fc8e21c98837d62690cbb42ebdf0880fcba --- /dev/null +++ b/doc/RTD/source/HydroSchemes/remix_sph.rst @@ -0,0 +1,94 @@ +.. REMIX SPH + Thomas Sandnes, 13th May 2025 + +.. _remix_sph: + +REMIX SPH +============================================== + +.. toctree:: + :maxdepth: 2 + :hidden: + :caption: Contents: + +REMIX is an SPH scheme designed to alleviate effects that typically suppress +mixing and instability growth at density discontinuities in SPH simulations +(Sandnes et al. 2025). REMIX addresses this problem by directly targeting sources +of kernel smoothing error and discretisation error, resulting in a generalised, +material-independent formulation that improves the treatment both of +discontinuities within a single material, for example in an ideal gas, and of +interfaces between dissimilar materials. The scheme combines: + ++ An evolved density estimate to avoid the kernel smoothing error in the + standard SPH integral density estimate; ++ Thermodynamically consistent, conservative equations of motion, with + free functions chosen to limit zeroth-order error; ++ Linear-order reproducing kernels with grad-h terms and a vacuum interface + treatment; ++ A "kernel normalising term" to avoid potential accumulation of error in + the evolved density estimate, such that densities would be no longer + representative of the distribution of particle masses in the simulation volume; ++ Advanced artificial viscosity and diffusion schemes with linear reconstruction + of quantities to particle midpoints, and a set of novel improvements to + effectively switch between treatments for shock-capturing under compression and + noise-smoothing in shearing regions. + +To configure with this scheme, use + +.. code-block:: bash + + ./configure --with-hydro=remix --with-equation-of-state=planetary + + +This scheme allows multiple materials, +meaning that different SPH particles can be assigned different +`equations of state <equations_of_state.html>`_ (EoS). +Every SPH particle then requires and carries the additional ``MaterialID`` flag +from the initial conditions file. This flag indicates the particle's material +and which EoS it should use. Note that configuring with +``--with-equation-of-state=planetary`` is required for this scheme, although +for simulations that use a single, ideal gas EoS, setting all MaterialIDs to +``0`` and including + +.. code-block:: yaml + + EoS: + planetary_use_idg_def: 1 + +in the parameter file are the only EoS-related additions needed compared with +other non-Planetary hydro schemes. Note also that since densities are evolved in +time, initial particle densities are required in initial conditions. + +We additionally recommend configuring with ``--with-kernel=wendland-C2`` and with + +.. code-block:: yaml + + SPH: + resolution_eta: 1.487 + +in the parameter file for improved hydrodynamic behaviour and since this is the +configuration used for the validation simulations of Sandnes et al. (2025). + + +The current implementation of the REMIX hydro scheme has been validated for +planetary applications and in hydrodynamic test cases and does not include all +necessary functionality for e.g. cosmological simulations. + +Default parameters used in the artificial viscosity and diffusion schemes and the +normalising term are: + +.. code-block:: c + + #define const_remix_visc_alpha 1.5f + #define const_remix_visc_beta 3.f + #define const_remix_visc_epsilon 0.1f + #define const_remix_visc_a 2.0f / 3.0f + #define const_remix_visc_b 1.0f / 3.0f + #define const_remix_difn_a_u 0.05f + #define const_remix_difn_b_u 0.95f + #define const_remix_difn_a_rho 0.05f + #define const_remix_difn_b_rho 0.95f + #define const_remix_norm_alpha 1.0f + #define const_remix_slope_limiter_exp_denom 0.04f + +These can be changed in ``src/hydro/REMIX/hydro_parameters.h``. diff --git a/doc/RTD/source/Planetary/hydro_scheme.rst b/doc/RTD/source/Planetary/hydro_scheme.rst index f0c787dce100142ecbe9b650fbee4d2110f34676..50d86e11944edbdb6828c64eb0a841b78b8c028b 100644 --- a/doc/RTD/source/Planetary/hydro_scheme.rst +++ b/doc/RTD/source/Planetary/hydro_scheme.rst @@ -16,5 +16,15 @@ and which EoS it should use. The Balsara viscosity switch is used by default, but can be disabled by compiling SWIFT with ``make CFLAGS=-DPLANETARY_SPH_NO_BALSARA``. -Note: the boundary-improvement methods presented in Ruiz-Bonilla+2022 are -in the process of being improved for release with better documentation etc soon. +Note: the boundary-improvement method presented in Ruiz-Bonilla+2022 can be +accessed on the ``planetary_imbalance_RB22`` git branch. + +.. _planetary_remix_hydro: + +REMIX SPH +====================== + +REMIX is an SPH scheme designed to alleviate effects that typically suppress +mixing and instability growth at density discontinuities in SPH simulations +(Sandnes et al. 2025). For more information on what is included in the REMIX +scheme and how to configure SWIFT to use REMIX, see: :ref:`remix_sph`. diff --git a/doc/RTD/source/Planetary/index.rst b/doc/RTD/source/Planetary/index.rst index 15e2daedd9d53e22ac645b2e56b29f555b6af7cf..23997d67d67095837edaf2ac00311368316b8f15 100644 --- a/doc/RTD/source/Planetary/index.rst +++ b/doc/RTD/source/Planetary/index.rst @@ -22,11 +22,19 @@ and ``DemoImpact/``. Check out their `README.md` files for more info. The tabulated equation of state files can be downloaded there using ``EoSTables/get_eos_tables.sh``. -To run planetary or similar simulations, SWIFT should be configured to use -the planetary hydrodynamics scheme and equations of state: -``--with-hydro=planetary`` and ``--with-equation-of-state=planetary``. -These allow for multiple materials to be used, -chosen from the several available equations of state. +To run planetary or similar simulations with a traditional SPH formulation, +SWIFT should be configured to use the planetary hydrodynamics scheme and +equations of state: ``--with-hydro=planetary`` and +``--with-equation-of-state=planetary``. These allow for multiple materials to be +used, chosen from the several available equations of state. Planetary +simulations can also be carried out using the more advanced :ref:`remix_sph` scheme, +which improves the treatment of mixing and material interfaces +(Sandnes et al. 2025). To configure within REMIX, use ``--with-hydro=remix`` and +``--with-equation-of-state=planetary``. Note that REMIX simulations require +initial particle densities in the initial conditions. We also recommend +configuring with ``--with-kernel=wendland-C2`` and with ``resolution_eta: 1.487`` +in the parameter file for improved hydrodynamic behaviour and since this is the +configuration used for the validation simulations of Sandnes et al. (2025). .. toctree:: :maxdepth: 1