From dd1dfef43f5deb5e56e7fdd98da5f89ca1fea667 Mon Sep 17 00:00:00 2001 From: Michael Zingale Date: Wed, 26 Feb 2025 14:22:21 -0500 Subject: [PATCH] Document the build system (#1760) Co-authored-by: Alexander Smith <72695548+aisclark91@users.noreply.github.com> Co-authored-by: Brendan Boyd <42776109+biboyd@users.noreply.github.com> --- Docs/source/build_system.rst | 220 +++++++++++++++++++++++++++++++++++ Docs/source/index.rst | 1 + Docs/source/networks.rst | 4 + Docs/source/screening.rst | 2 + Docs/source/sdc.rst | 4 + 5 files changed, 231 insertions(+) create mode 100644 Docs/source/build_system.rst diff --git a/Docs/source/build_system.rst b/Docs/source/build_system.rst new file mode 100644 index 000000000..3b957c3ab --- /dev/null +++ b/Docs/source/build_system.rst @@ -0,0 +1,220 @@ +************ +Build System +************ + +Microphysics leverages the AMReX build system. GNU make is the +primary build system, but CMake is partially supported. Here we focus +on the GNU make build system. + +.. tip:: + + All of the build variables supported by the AMReX build system can + be used with Microphysics, for example: + + * ``COMP`` : the compiler system to use + * ``USE_CUDA`` : build for NVIDIA GPUs with CUDA + * ``USE_HIP`` : build for AMD GPUs with HIP/ROCm + + See the `AMReX GNU Make Docs + `_ + +There are two main makefile stubs: + +.. index:: Make.Microphysics, Make.Microphysics_extern + +* ``Make.Microphysics`` : this is used by the unit tests within Microphysics and it + defines the variables needed by the AMReX build system, including specifying the + location of the files. It also defines the rules for some files that are created + at build time. + +* ``Make.Microphysics_extern`` : this is the core makefile stub for Microphysics + that interprets the build variables that enable / disable different functionality. + This is meant to be included into any application code's build system. + +additionally directories have their own ``Make.package`` files that specify +the files needed for the build and some rules for making intermediary files. + + +Environment variables +===================== + +The build system relies on some environment variables to find the source: + +.. index:: AMREX_HOME, MICROPHYSICS_HOME + +* ``AMREX_HOME`` : this should point to the top-level ``amrex/`` directory + +* ``MICROPHYSICS_HOME`` : this is needed by application codes, and + should point to the top level ``Microphysics/`` directory. For + building unit tests within the ``Microphysics/`` directory itself, + this does not need to be explicitly set. + + +Automatically generated files +============================= + +There are a few source files that are created automatically at +compile-time. These are placed in the +``tmp_build_dir/microphysics_sources/`` sub-directory under the +directory you run ``make`` (if building through an application code, +the sub-directory may have a different name). + +.. index:: network_properties.H, extern_parameters.H, AMReX_buildInfo.cpp + +The main files are: + +* ``network_properties.H`` : this defines the properties of the composition that + make up the network (and therefore, used by the equation of state and other + physics). + +* ``extern_parameters.H`` : this defines all of the runtime parameters that are + part of the build. At the moment, they are treated as global variables + (using managed memory on GPUs), but a ``struct`` that carries their values + is also available through ``extern_type.H``. + +* ``AMReX_buildInfo.cpp`` : this defines functions that return the git hashes, + compilers, compiler flags, and more meta-data about the build. This file + is automatically deleted once it is built to insure it is always up-to-date. + The functions it defines are used when writing the ``job_info`` file + in the plotfiles that some unit tests produce. + +Controlling choice of physics +============================= + +The choice of physics to include in an application is done at build time, and is +controlled by a number of make variables. + +.. tip:: + + You can query the value of any variable in the Microphysics build system by doing + `make print-` where `` is the name of the variable. + + For example, + + .. code:: bash + + make print-EOS_DIR + + will tell you what EOS is being used. + + +The following control whether certain physics modules are included in +the build process. Note: an EOS and network are always required. +These can be set to ``TRUE`` to enable and ``FALSE`` to disable specific features. + +* ``USE_CONDUCTIVITY`` : determines whether a conductivity routine + should be included in the list of build packages. If enabled, this + also defines the ``CONDUCTIVITY`` preprocessor variable. Default: + ``FALSE``. + +* ``USE_NEUTRINOS`` : determines whether a neutrino cooling term + should be applied in the reaction network energy generation + equation. See :ref:`neutrino_loss`. The default is set by each + individual network. + +* ``USE_NET_NET`` : determines whether the self-consistent NSE + infrastructure is included in the build. See + :ref:`self_consistent_nse`. No default is set. + +* ``USE_NSE_TABLE`` : determines whether the tabular NSE + infrastructure is included in the build. See :ref:`tabulated_nse`. + No default is set. + +* ``USE_RATES`` : for templated reaction networks (see + :ref:`sec:templated_rhs`) determines whether we include the + ``rates/`` set of reaction rates in the build system. Also defines + the ``RATES`` preprocessor variable. The default is set by each of + the templated networks separately. + +* ``USE_REACT`` : determines whether we need to include any of the + source related to reaction networks or integrators and sets the + ``REACTIONS`` preprocessor variable. Note: even if this is set to + ``TRUE``, the ``network_properties.H`` file is still generated. No + default is set. + +* ``USE_SCREENING`` : determines whether the screening routines are + included in the list of build packages. If enabled, this also + defines the ``SCREENING`` preprocessor variable which is used in + some networks to disable screening completely. Note: it is also + possible to set the screening routine to ``null`` which would have + the same effect (see :ref:`sec:screening`). The default is set by + each individual network. + + +The following control the choice of implementation for the different physics modules: + + +* ``CONDUCTIVITY_DIR`` : the name of the conductivity implementation to use, + relative to ``Microphysics/conductivity/``. + +* ``EOS_DIR`` : the name of the EOS to use, relative to ``Microphysics/EOS/``. + +* ``INTEGRATOR_DIR`` : the name of the integrator to use, relative to + ``Microphysics/integration/``. + +* ``NETWORK_DIR`` : the name of the network to use, relative to ``Microphysics/networks/``. + If ``general_null`` is chosen, then the inputs file is determined by + either ``GENERAL_NET_INPUTS`` or ``NETWORK_INPUTS`` (see :ref:`sec:networks:general_null`). + +* ``OPACITY_DIR`` : the name of the opacity implementation to use, relative + to ``Microphysics/opacity/``. + +* ``SCREEN_METHOD`` : the name of the screening implementation to use. The choices + are listed in :ref:`sec:screening`. + + +The following control the time-integration method used by the reaction +network integration: + +* ``USE_SIMPLIFIED_SDC`` : enable the simplified-SDC coupling of hydro and reactions. + See :ref:`sec:simplified_sdc`. + +* ``USE_TRUE_SDC`` : enable the true-SDC coupling of hydro and reactions. + See :ref:`sec:true_sdc`. + +.. note:: + + If neither of these are set to ``TRUE``, then Strang-splitting coupling + will be used. + + +Targets +======= + +For the unit tests, simply doing + +.. code:: bash + + make + +in the test directory will build the test. There are a few other targets defined. The most important +is ``clean``. Doing: + +.. code:: bash + + make clean + +will remove all the build temporary files (including the ``tmp_build_dir/``). + +.. important:: + + If you want to use a different EOS or reaction network (or any other physics), then you + should always do ``make clean`` first in the build directory. + +Some other targets include: + +* ``nettables`` : create the symlinks for any weak reaction rate tables that are part of the + network. + +* ``table`` : create a symlink for the ``helm_table.dat`` EOS table if the ``helmholtz`` EOS is used. + +* ``nsetable`` : create a symlink for the NSE table if ``USE_NSE_TABLE=TRUE`` is set. + +* ``build_status`` : report the current git versions of Microphysics and AMReX + +* ``test_extern_params`` : this will simply parse the runtime parameters and execute the + ``write_probin.py`` script that generates the headers and C++ files necessary to use + the parameters. These will be generated under ``tmp_build_dir/microphysics_sources/``. + +* ``net_prop_debug`` : this will simply create the ``network_properties.H`` file for the + current network and output it into ``tmp_build_dir/microphysics_sources/``. diff --git a/Docs/source/index.rst b/Docs/source/index.rst index 7589e79e7..6306f9a70 100644 --- a/Docs/source/index.rst +++ b/Docs/source/index.rst @@ -46,6 +46,7 @@ system. getting_started design data_structures + build_system rp_intro .. toctree:: diff --git a/Docs/source/networks.rst b/Docs/source/networks.rst index 5f680befb..e31455005 100644 --- a/Docs/source/networks.rst +++ b/Docs/source/networks.rst @@ -1,3 +1,5 @@ +.. _sec:networks: + *************************** Available Reaction Networks *************************** @@ -25,6 +27,8 @@ Microphysics knows the properties of the fluid. `_ :cite:`pynucastro, pynucastro2` using the ``AmrexAstroCxxNetwork`` class. +.. _sec:networks:general_null: + ``general_null`` ================ diff --git a/Docs/source/screening.rst b/Docs/source/screening.rst index 5223bbbac..3dfa86bad 100644 --- a/Docs/source/screening.rst +++ b/Docs/source/screening.rst @@ -1,3 +1,5 @@ +.. _sec:screening: + *************************** Screening of Reaction Rates *************************** diff --git a/Docs/source/sdc.rst b/Docs/source/sdc.rst index 2eed54cce..0dae1af31 100644 --- a/Docs/source/sdc.rst +++ b/Docs/source/sdc.rst @@ -44,6 +44,8 @@ is the reaction source term. are supported by the same integrators, and both of these options will set the ``SDC`` preprocessor flag. +.. _sec:true_sdc: + "True" SDC ---------- @@ -86,6 +88,8 @@ This can be cast as an ODE system as: \frac{d\Uc}{dt} \approx \frac{\Uc^{m+1} - \Uc^m}{\delta t_m} = \Rbs{\Uc} + {\bf C} +.. _sec:simplified_sdc: + Simplified SDC --------------