method.incl

.. par:parameter:: Method:list

   :Summary: :s:`Sequence of numerical methods to apply.`
   :Type:    :par:typefmt:`list ( string )`
   :Default: :d:`none`
   :Scope:     :c:`Cello`

   :e:`This parameter specifies the list of numerical methods to use, and
   is analagous to "EvolveLevel" routine in ENZO.  Each method in the
   list is applied in the order specified.  Possible methods include:`

     * :t:`"comoving_expansion"` :e:`adds comoving expansion terms to the
       physical variables.`
     * :t:`"cosmology"` :e:`for writing redshift to monitor output.`
     * :t:`"flux_correct"` :e:`for performing flux corrections when using AMR.`
     * :t:`"grackle"` :e:`for heating and cooling methods in the Enzo
       Grackle library`
     * :t:`"gravity"` :e:`solves for the gravitational potential given gas
       and particle density fields.`
     * :t:`"heat"` :e:`for the forward-Euler heat-equation solver, which
       is used primarily for demonstrating how new Methods are
       implemented in Enzo-E`
     * :t:`"pm_deposit"` :e:`deposits "dark" particle density into
       "density_particle" field using CIC for "gravity" method.`
     * :t:`"pm_update"` :e:`moves cosmological "dark" particles based on
       positions, velocities, and accelerations.`  **This will be phased out
       in favor of a more general "move_particles" method.**
     * :t:`"ppm"` :e:`for Enzo-E's PPM hydrodynamics method.`  *This may be
       phased out in favor of using a more general "hydro" method
       instead, with a specific hydro solver specified.*
     * :t:`"ppml"` :e:`for the PPML ideal MHD solver.`  *This may be phased
       out in favor of using a more general "mhd" method instead, with a
       specific mhd solver specified.*
     * :t:`"ppml_it"` :e:`alternate name for "ppml".`
     * :t:`"ppml_ig"` :e:`for the adiabatic version of PPML.`   *This may be phased
       out in favor of using a more general "mhd" method instead, with a
       specific mhd solver specified.*
     * :t:`"mhd_vlct"` :e:`for the VL + CT (van Leer + Constrained Transport) MHD
       solver.`
     * :t:`"trace"` :e:`for moving tracer particles.`  **This will be phased
       out in favor of a more general "move_particles" method.**
     * :t:`"turbulence"` :e:`computes random forcing for turbulence
       simulations.`
     * :t:`"turbulence_ou"` :e:`implements Ornstein-Uhlenbeck driven turbulence.`

   :e:`Parameters specific to individual methods are specified in subgroups, e.g.`::

        Method {
           list = ["ppm"];
           ppm {
              diffusion   = true;
              flattening  = 3;
              steepening  = true;
              dual_energy = false;
           }
        }

   :e:`There are a subset of parameters that can be specified for all
   methods.  For example, a` :ref:`schedule_param` :e:`subgroup can
   be defined for any method object (to dictate when the method is
   executed).`

   :e:`For more detailed documentation on Methods, see` :ref:`using-methods`

----

.. par:parameter:: Method:courant

   :Summary: :s:`Global Courant safety factor`
   :Type:    :par:typefmt:`float`
   :Default: :d:`1.0`
   :Scope:     :c:`Cello`

   :e:`The global Courant safety factor is a multiplication factor for
   the time step applied on top of any Field or Particle specific Courant
   safety factors.`

accretion
---------

.. par:parameter:: Method:accretion:accretion_radius_cells

   :Summary:    :s:`The radius of the spherical accretion zone around each sink particle, in
                    units of the minimum cell width.`
   :Type:       :par:typefmt:`float`
   :Default:    :d:`4.0`
   :Scope:     :z:`Enzo`

   :e:`The accretion radius (i.e., the radius of the spherical accretion zone) in units of the minimum cell width (i.e., if the cell width along all the x, y, and z-axes are hx, hy, and hz, then the minimum cell width is the minimum of hx, hy, and hz),, at the highest refinement level. Its value must be less than one fewer than the minimum ghost depth  for "flux" accretion, and less than the minimum ghost depth for other flavors of accretion. The ghost depth is 4 (along all axes) by default.`

----

.. par:parameter:: Method:accretion:flavor

   :Summary:    :s:`The flavor of accretion used.`
   :Type:       :par:typefmt:`string`
   :Default:    :d:`""`
   :Scope:     :z:`Enzo`

   :e:`The flavor of accretion used, which can be either "threshold", "bondi_hoyle", "flux", or "dummy". If this parameter is not set in the parameter file, or if some other string is provided, then Enzo-E will exit with an error message.`

----

.. par:parameter:: Method:accretion:physical_density_threshold_cgs

   :Summary:    :s:`The value of the accretion (physical) density threshold in cgs units.`
   :Type:       :par:typefmt:`float`
   :Default:    :d:`1.0e-24`
   :Scope:     :z:`Enzo`

   :e:`The value of the (physical) density threshold in cgs units. The density in each cell in the accretion zone cannot go below this value during the accretion process. The value of this parameter in code density units must be greater than or equal to the value of the density floor imposed by the hydro method (either "ppm" or "mhd_vlct". In cosmological simulations, the density unit is the
   mean matter density of the universe which decreases with time, which means that the value of a density quantity expressed in these units will increase with time, while the density floor is fixed
   in comoving units. The consequence is that is is sufficient for the density threshold to be above
   the density floor at the start of the simulation to guarantee that it will be above the floor
   at all subsequent times.`

----


.. par:parameter:: Method:accretion:max_mass_fraction

   :Summary:    :s:`The maximum fraction of mass which can be accreted from a cell in one timestep.`
   :Type:       :par:typefmt:`float`
   :Default:    :d:`0.25`
   :Scope:     :z:`Enzo`

   :e:`This parameter specifies the maximum fraction of mass which can be accreted from a cell in one timestep. This value of this parameter must be between 0 and 1.`


check
-----

.. include:: method_check.incl

feedback
--------

.. include:: method_feedback.incl

flux_correct
------------

.. par:parameter:: Method:flux_correct:group

   :Summary: :s:`Name of group of fields to apply flux correction to`
   :Type:    :par:typefmt:`string`
   :Default: :d:`"conserved"`
   :Scope:     :z:`Cello`

   :e:`Flux correction must be applied to conserved fields in AMR simulations to maintain conserved quantities across mesh resolution jumps.  This parameter selects the group of fields to which the "flux_correct" method will be applied.`

   :e:`Fields that store a conserved quantity divided by density`
   (e.g. ``"total_energy"``, ``"velocity_x"``) :e:`have special
   handling. Such fields must be included in both the group specified by
   this parameter AND the` ``"make_field_conservative"`` :e:`group. Flux
   corrections are applied to an element of such fields according to the
   following procedure:`

     1. :e:`The element is multiplied by the corresponding element of
        the` ``"density"`` :e:`field (before the flux corrections are
        applied to the` ``"density"`` :e:`field).`

     2. :e:`Flux corrections are applied to the product from step 1.`

     3. :e:`Finally, the element in the original field is assigned the
        value computed in step 2 divided by the corresponding element
        from the` ``"density"`` :e:`field (after flux corrections are
        applied to the` ``"density"`` :e:`field).`

   :e:`An error will be raised if these special fields are detected, and
   the` ``"density"`` :e:`field is not included in the group specified by
   this parameter.`

----

.. par:parameter:: Method:flux_correct:min_digits

   :Summary: :s:`Number of digits expected to be conserved by fields in tests`
   :Type:    :par:typefmt:`list`
   :Default: :d:`[]`
   :Scope:     :z:`Cello`

   :e:`Specifies the minimum number of digits that are expected to be conserved
   by fields. This is used for testing purposes (the simulation will
   check at each timestep whether this expectation has been met). Entries of this list should alternate between the name of fields (a string) and the expected number of conserved digits for that field (a float).`

   :e:`The example provided below indicates that the` ``"density"`` :e:`field and the product of the` ``"density"`` :e:`&` ``"velocity_x"`` :e:`fields are expected to be conserved to` ``7.1`` :e:`and` ``4.9`` :e:`digits, respectively`::

        Method {
           flux_correct {
              min_digits = ["density", 7.1,
                            "velocity_x", 4.9];
           }
        }

        Group {
           list = [ "conserved", "make_field_conservative" ];
           conserved {
              field_list = [ "density", "velocity_x"];
           }
           make_field_conservative {
              field_list = [ "velocity_x"];
           }
        }

   :e:`For the sake of backwards compatibility, this parameter can be
   assigned a single float (that is not in a list). In this case, the
   value is assumed to be the expected minimum number of digits conserved
   by the` ``"density"`` :e:`field.` *(Support for this type of parameter
   may be removed in the future)*

grackle
-------

"`Grackle <https://grackle.readthedocs.io/en/latest/>`_ is a chemistry and radiative cooling library for astrophysical
simulations. 
It is a generalized and updated version of the chemistry network of the Enzo simulation code."

While most of the parameters come directly from Grackle, there are a few notable exceptions.
These generally affect how Enzo-E uses Grackle and don't have direct counterparts listed on the `Grackle parameters section <https://grackle.readthedocs.io/en/latest/Parameters.html>`_ of the Grackle website.
These parameters include:

----

.. par:parameter:: Method:grackle:courant

   :Summary: :s:`Courant safety factor`
   :Type:    :par:typefmt:`float`
   :Default: :d:`1.0`
   :Scope:     :z:`Enzo`

   :e:`The method-specific courant safety factor. This is meaningless unless` :par:param:`~Method:grackle:use_cooling_timestep` :e:`has been set to` ``true``.
   :e:`In that case, the timestep associated with the Grackle method is this value mutliplied by the minimum timestep.`

----

.. par:parameter:: Method:grackle:use_cooling_timestep

   :Summary: :s:`Whether to limit the timestep by the minimum cooling time`
   :Type:    :par:typefmt:`logical`
   :Default: :d:`false`
   :Scope:   :z:`Enzo`

   :e:`By default, usage of Grackle does not limit the timestep. When this parameter is set to` ``true``, :e:`the timestep is limited by the product of the minimum cooling time and` :par:param:`Method:grackle:courant`.

----

.. par:parameter:: Method:grackle:radiation_redshift

   :Summary: :s:`redshift of the UV background in non-cosmological simulations`
   :Type:    :par:typefmt:`float`
   :Default: :d:`-1.0`
   :Scope:     :z:`Enzo`

   :e:`In non-cosmological simulations, this parameter is used to specify the redshift of the UV background.
   The default value,` ``-1.0``, :e:`is used to indicate that this parameter is unset.`

   * :e:`When this parameter has a value other than the default value in a cosmological simulation, the program will abort with an error message.`

   * :e:`When this parameter has a default value in a non-cosmological simulation, the radiation redshift is set to 0.0, internally.`

----

All of the other allowed parameters are used to directly configure the grackle parameters stored in Grackle's configuration object, which are each listed on the `Grackle parameters section <https://grackle.readthedocs.io/en/latest/Parameters.html>`_ of the Grackle website.
In general, to configure a given parameter on that page, ``<grackle-param>``, just assign your desired value to :par:param:`!Method:grackle:<grackle-param>`.
The primary exceptions to this guideline are for the following grackle parameters:

  * ``use_grackle``: when the grackle method is in use, this is always set to ``1``.
  * ``Gamma``: this grackle parameter is instead initialized by :par:param:`Physics:fluid_props:eos:gamma`
  * ``grackle_data_field``: this grackle parameter is initialized with the value of :par:param:`Method:grackle:data_file`

If you choose not to specify a value for a given grackle parameter, the default value is selected by the Grackle library.

For brevity (and to avoid having out-of-date documentation), we omit descriptions for the vast majority of recognized parameters that are directly used to initialize a corresponding grackle parameter.
With that said, we make exceptions for a small handful of these parameters (primarily in cases where a parameter's value may necessitate the existence of a field) and provide descriptions for them down below:

.. par:parameter:: Method:grackle:data_file

   :Summary:     :s:`Path to the data file containing the metal cooling and UV background tables.`
   :Type:        :par:typefmt:`string`
   :Default:     :d:`""`
   :Scope:     :z:`Enzo`

   :e:`Path to the data file containing the metal cooling and UV background tables. This parameter is directly used to initialize Grackle's` ``grackle_data_file`` :e:`parameter. The only reason this isn't called` :par:param:`!Method:grackle:grackle_data_file` :e:`is for the sake of maintaining backwards compatability`.

----

.. par:parameter:: Method:grackle:primordial_chemistry

   :Summary: :s:`Flag to control which primordial chemistry network is used`
   :Type:    :par:typefmt:`integer`
   :Default: :d:`0`
   :Scope:   :z:`Enzo`

   :e:`Flag to control which primordial chemistry network is used (this directly corresponds to Grackle's` ``primordial_chemistry`` :e:`parameter).`

     **0:** :e:`no chemistry network. Radiative cooling for primordial species is solved by interpolating from lookup tables calculated with Cloudy. A simplified set of functions are available (though not required) for use in this mode. For more information, see` `Pure Tabulated Mode <http://grackle.readthedocs.org/en/grackle-1.0/Integration.html#tabulated-mode>`_.

     **1:** :e:`6-species atomic H and He. Active species:` |H|, |H+|, |He|, |He+|, |++|, |e-|.

     **2:** :e:`9-species network including atomic species above and species for molecular hydrogen formation. This network includes formation from the` |H-| :e:`and` |H2+| :e:`channels, three-body formation` ( |H| + |H| + |H|  :e:`and`  |H| + |H| + |H2|), |H2| :e:`rotational transitions, chemical heating, and collision-induced emission (optional). Active species: above +` |H-|, |H2|, |H2+|.

     **3:** :e:`12-species network include all above plus HD rotation cooling. Active species: above plus D,` |D+|, :e:`HD.`

     **Note:** :e:`In order to make use of the non-equilibrium chemistry network (primordial_chemistry options 1-3), you must add and advect baryon fields for each of the species used by that particular option.`

----

.. par:parameter:: Method:grackle:metal_cooling

   :Summary:  :s:`Flag to enable metal cooling using the Cloudy tables`
   :Type:     :par:typefmt:`logical`
   :Default:  :d:`false`
   :Scope:     :z:`Enzo`

   :e:`Flag to enable metal cooling using the Cloudy tables. If enabled, the cooling table to be used must be specified within the table specified by the` ``Method:grackle:data_file`` :e:`parameter.`

   **Note:** :e:`In order to use the metal cooling, you must add and advect a metal density field.`

gravity
-------

.. par:parameter:: Method:gravity:solver

   :Summary: :s:`Name of the linear solver to use`
   :Type:    :par:typefmt:`string`
   :Default: :d:`"unknown"`
   :Scope:     :z:`Enzo`

   :e:`Identifier for the linear solver to use, which must be included in the "Solver:list" parameter.`

----

.. par:parameter:: Method:gravity:grav_const

   :Summary: :s:`Gravitational constant`
   :Type:    :par:typefmt:`float`
   :Default: :d:`6.67384e-8`
   :Scope:     :z:`Enzo`

   Gravitational constant used in place of G.  The default is G in cgs units.
   For non-cosmological simulations, if the user wants to use
   the standard value for the gravitational constant, the user must set a
   value which is consistent with their choice of units; i.e.,
   its value must be :math:`G_{cgs}\times M \times T^2 \times L^{-3}`, or equivalently,
   :math:`G_{cgs}\times D \times T^2`, where :math:`M, D, T, L` are the mass, density, time,
   and length units, and :math:`G_{cgs}` is the value of the gravitational constant in cgs units.

   In cosmological simulations, this parameter is ignored.


----

.. par:parameter:: Method:gravity:order

   :Summary: :s:`Order of accuracy discretization to use for the discrete Laplacian`
   :Type:    :par:typefmt:`integer`
   :Default: :d:`4`
   :Scope:     :z:`Enzo`

   :e:`Second, fourth, and sixth order discretizations of the Laplacian
   are available; valid values are 2, 4, or 6.`

----

.. par:parameter:: Method:gravity:accumulate

   :Summary: :s:`Whether to add one layer of ghost zones when refreshing particle density`
   :Type:    :par:typefmt:`logical`
   :Default: :d:`true`
   :Scope:     :z:`Enzo`

   :e:`This should be true for all runs with particles, since particle
   mass deposited in the "density_particle" field may bleed into the
   first layer of ghost zones.  This parameter ensures that that mass
   will be included in "density_total".`

----

.. par:parameter:: Method:gravity:dt_max

   :Summary: :s:`The maximum timestep returned by EnzoMethodGravity::timestep`
   :Type:    :par:typefmt:`float`
   :Default: :d:`1.0e10`
   :Scope:     :z:`Enzo`

   :e:`The timestep returned by EnzoMethodGravity::timestep (when called on a
   block) is calculated as follows. First, the geometric mean of the cell-widths
   in all dimensions is found, which we call the "mean cell width". Next, the
   quantity "epsilon" is calculated, as the mean cell width divided by the square
   of dt_max. Then, the maximum acceleration magnitude across all cells in the
   block is found, which we call "a_mag_max". We then calculate the
   mean cell width divided by the sum of a_mag_max and epsilon. The timestep is
   then the square root of this quantity. This means that if all the accelerations
   are zero (such as at the first time step), the timestep is equal to dt_max.
   Defining the timestep in this way also means that the value of the
   timestep is independent of how the acceleration vectors are oriented relative
   to the mesh.`


heat
----

.. par:parameter:: Method:heat:alpha

   :Summary:    :s:`Parameter for the forward euler heat equation solver`
   :Type:       :par:typefmt:`float`
   :Default:    :d:`1.0`
   :Scope:     :z:`Enzo`

   :e:`Thermal diffusivity parameter for the heat equation.`

merge_sinks
-----------

.. par:parameter:: Method:merge_sinks:merging_radius_cells

   :Summary:    :s:`The distance within which sink particles merge with
                    each other, in units of the minimum cell width`
   :Type:       :par:typefmt:`float`
   :Default:    :d:`8.0`
   :Scope:     :z:`Enzo`

   :e:`The distance within which sink particles merge with each other, in units of the minimum cell width, i.e., the minimum of the cell widths in all 3 dimensions, at the highest level of refinement.`

mhd_vlct
--------

.. include:: method_mhd_vlct.incl

m1_closure
----------

.. include:: method_m1_closure.incl

null
----

.. par:parameter:: Method:null:dt

   :Summary:    :s:`Set the time step for the "null" Method`
   :Type:       :par:typefmt:`float`
   :Default:    :d:`max (float)`
   :Scope:     :z:`Enzo`

   :e:`Sets the time step for the` :p:`null` :e:`Method.  This is typically used for testing the AMR meshing infrastructure without having to use any specific method.  It can also be used to add an additional maximal time step value for other methods.`

pm_deposit
----------

.. par:parameter:: Method:pm_deposit:alpha

   :Summary:    :s:`Compute the total gravitating density field at time t + alpha*dt`
   :Type:       :par:typefmt:`float`
   :Default:    :d:`0.5`
   :Scope:     :z:`Enzo`

   :e:`Sets the factor defining at what time to deposit mass into the
   density_total field.  The default is 0.5, meaning density_total is
   computed at t + 0.5*dt.`

ppm
---

.. include:: method_ppm.incl


ppml
----

.. include:: method_ppml.incl


sink_maker
----------

.. par:parameter:: Method:sink_maker:jeans_length_resolution_cells

   :Summary:    :s:`Determines how many cell widths are required to resolve the local Jeans length for a cell not to form a sink.`
   :Type:       :par:typefmt:`float`
   :Default:    :d:`4.0`
   :Scope:     :z:`Enzo`

   :e:`If the local Jeans length in a cell is less than this quantity multiplied by the maximum cell width, then the cell is a candidate for forming a sink. The maximum cell width is maximum value out of hx, hy, and hz, where hx, hy, and hz are the cell widths across the x-, y- and z-axes, respectively.`

----

.. par:parameter:: Method:sink_maker:physical_density_threshold_cgs

   :Summary:    :s:`The minimum physical density required for a cell to form a sink particle in cgs units.`
   :Type:       :par:typefmt:`float`
   :Default:    :d:`1.0e-24`
   :Scope:     :z:`Enzo`

   :e:`The value of the physical density threshold in cgs units. The density in a cell must be
   greater than the density threshold to be able to form a sink. The density in a cell after
   sink formation will be no less than the density threshold. The value of
   the density threshold in code units must be greater than or equal to the value of the
   density floor imposed by the hydro method.`

----

.. par:parameter:: Method:sink_maker:max_mass_fraction

   :Summary:    :s:`The maximum fraction of a cell's gas mass which can be turned into a sink particle in one timestep.`
   :Type:       :par:typefmt:`float`
   :Default:    :d:`0.25`
   :Scope:     :z:`Enzo`

   :e:`The mass of a newly-formed sink is bounded above by this parameter multiplied by the cell
   density multiplied by the cell volume. The value of this parameter must be between
   0 and 1.`

----

.. par:parameter:: Method:sink_maker:min_sink_mass_solar

   :Summary:    :s:`The minimum mass of a newly-formed sink particle, in solar mass units.`
   :Type:       :par:typefmt:`float`
   :Default:    :d:`0.0`
   :Scope:     :z:`Enzo`

   :e:`The minimum mass of a newly-formed sink particle, in solar mass units. If there is not enough
   gas mass in a cell to form a sink with at least this mass, no sink is formed.`

----

.. par:parameter:: Method:sink_maker:check_density_maximum

   :Summary:    :s:`Determines whether a cell is required to be a local density maximum in order to form a sink particle.`
   :Type:       :par:typefmt:`logical`
   :Default:    :d:`true`
   :Scope:     :z:`Enzo`

   :e:`If true, then a cell will only form a sink particle if its density is larger than the density in all 26 neighboring cells.`

----

.. par:parameter:: Method:sink_maker:max_offset_cell_fraction

   :Summary:    :s:`Controls the size of the random displacement of a sink particle's initial position relative to the center of the cell`
   :Type:       :par:typefmt:`float`
   :Default:    :d:`0.0`
   :Scope:     :z:`Enzo`

   :e:`When a cell creates a sink particle, the x/y/z coordinate of its initial position will be
   the x/y/z coordinate of the center of the cell, plus a random value generated from a
   uniform distribution on the interval [-A,A], where A is equal to
   this parameter multiplied by the cell width along the x/y/z axis.`


----

.. par:parameter:: Method:sink_maker:offset_seed_shift

   :Summary:    :s:`Seed used to generate the random displacement of a sink particle's initial position relative to the center of the cell`
   :Type:       :par:typefmt:`integer`
   :Default:    :d:`0`
   :Scope:     :z:`Enzo`

   :e:`When computing the random offset for the initial position of a sink particle, we compute
   an unsigned 64 bit integer value from the cycle number, the block index, and the cell
   index, and then add on this value to give the seed for the random number generator.`

star_maker
----------

.. include:: method_star_maker.incl


turbulence
----------

.. par:parameter:: Method:turbulence:edot

   :Summary: :s:`Initial value for edot for turbulence Method`
   :Type:    :par:typefmt:`float`
   :Default: :d:`-1.0`
   :Scope:     :z:`Enzo`
   :Todo: :o:`write`

   :e:`Prescribes kinetic energy injection rate for a forcing method based on random but constant-in-time external x-, y-, z-acceleration fields. The code would normalize the accelerations so that the resulting actual injection rate is constant during the simulation and equal to edot. For details of the method see` `Mac Low (1999) <https://ui.adsabs.harvard.edu/abs/1999ApJ...524..169M/abstract>`_  :e:`The default setting edot=-1 turns this forcing off.`

----

.. par:parameter:: Method:turbulence:mach_number

   :Summary: :s:`Value for Mach number in turbulence problem`
   :Type:    :par:typefmt:`float`
   :Default: :d:`0.0`
   :Scope:     :z:`Enzo`
   :Todo: :o:`write`

   :e:`Specifies the target sonic Mach number for a forced turbulence simulation. If` :p:`mach_number` :e:`is not zero, the energy injection rate will be calculated based on the Mach number.`

turbulence_ou
-------------

.. include:: method_turbulence_ou.incl