From 597d7acc01ebffaa3603ffad2f3f6f72e4a0f42d Mon Sep 17 00:00:00 2001 From: Simon Wilkinson Date: Fri, 30 Jan 2026 13:29:36 +0000 Subject: [PATCH] Fix typos and spelling in the docs --- doc/sphinx/src/building.rst | 6 +- doc/sphinx/src/contributing.rst | 32 ++++---- doc/sphinx/src/models.rst | 36 ++++----- doc/sphinx/src/modifiers.rst | 6 +- doc/sphinx/src/philosophy.rst | 4 +- doc/sphinx/src/using-closures.rst | 124 +++++++++++++++--------------- doc/sphinx/src/using-eos.rst | 14 ++-- doc/sphinx/src/using-kpt.rst | 14 ++-- 8 files changed, 118 insertions(+), 118 deletions(-) diff --git a/doc/sphinx/src/building.rst b/doc/sphinx/src/building.rst index 977adfc9763..b6e75aac34b 100644 --- a/doc/sphinx/src/building.rst +++ b/doc/sphinx/src/building.rst @@ -163,7 +163,7 @@ preconditions: ============================================== ================================================================================= =========================================== When installing ``singularity-eos``, data files are also installed. The -follwing options control where the data files are installed: +following options control where the data files are installed: ====================================== ======= =========================================== Option Default Comment @@ -395,7 +395,7 @@ To start using Spack, we use the provided activation script $> source ~/spack/share/spack/setup-env.sh You will always need to *activate* spack for each new shell. You may -find it convienant to invoke this Spack setup in your login script, +find it convenient to invoke this Spack setup in your login script, though be aware that Spack will prepend paths to your environment which may cause conflicts with other package tools and software. @@ -422,7 +422,7 @@ However, Spack has put in a lot of effort to be able to automatically discover the available tools and software on any given system. While not perfect, we can get a fairly robust starting point. -Assume we are on an HPC system that has Envionrmental Modules that +Assume we are on an HPC system that has Environmental Modules that provides compilers, MPI implementations, and sundry other common tools. To help Spack find these, let's load a specific configuration into the active shell environment. diff --git a/doc/sphinx/src/contributing.rst b/doc/sphinx/src/contributing.rst index 145e3432652..75e5e8d7b50 100644 --- a/doc/sphinx/src/contributing.rst +++ b/doc/sphinx/src/contributing.rst @@ -12,7 +12,7 @@ repository, or submit a pull request! Pull request protocol ---------------------- -There is a pull reuqest template that will be auto-populated when you +There is a pull request template that will be auto-populated when you submit a pull request. A pull request should have a summary of changes. You should also add tests for bugs fixed or new features you add. @@ -36,7 +36,7 @@ useful output. For example: CFM=clang-format-12 VERBOSE=1 ./util/scripts/format.sh Several sets of tests are triggered on a pull request: a static format -check, a docs buld, and unit tests of analytic models and the stellar +check, a docs build, and unit tests of analytic models and the stellar collapse model. These are run through GitHub's CPU infrastructure. We have a second set of tests run on a wider set of architectures that also access the Sesame library, which we are not able to make public. @@ -72,7 +72,7 @@ be requested to split your pull request into two or more separate contributions. You may also receive many "nitpicky" comments about code style or structure. These comments help keep a broad codebase, with many contributors uniform in style and maintainable with -consistent expectations accross the code base. While there is no +consistent expectations across the code base. While there is no formal style guide for now, the regular contributors have a sense for the broad style of the project. You should take these stylistic and "nitpicky" suggestions seriously, but you should also feel free to @@ -81,7 +81,7 @@ push back. As with any creative endeavor, we put a lot of ourselves into our code. It can be painful to receive criticism on your contribution and easy to take it personally. While you should resist the urge to take -offense, it is also partly code reviewer's responsiblity to create a +offense, it is also partly code reviewer's responsibility to create a constructive environment, as discussed below. Expectations of code reviewers @@ -100,7 +100,7 @@ congenial: want to try this other pattern." * Avoid language that can be misconstrued, even if it's common - notation in the commnunity. For example, avoid phrases like "code + notation in the community. For example, avoid phrases like "code smell." * Explain why you make a suggestion. In addition to saying "try X @@ -117,7 +117,7 @@ congenial: General principle for everyone ``````````````````````````````` -It's hard to convey tone in text correspondance. Try to read what +It's hard to convey tone in text correspondence. Try to read what others write favorably and try to write in such a way that your tone can't be mis-interpreted as malicious. @@ -147,7 +147,7 @@ The basic process for adding a new EOS can be summarized as #. Create a Fortran interface to initialize your EOS into an array of EOS In addition to these main steps, there are a couple more that are required if -you would like your EOS to work with our fortran interface, which will be +you would like your EOS to work with our Fortran interface, which will be discussed below. Step 1: Create a new header file for your EOS @@ -156,7 +156,7 @@ Step 1: Create a new header file for your EOS In general, the best practice is to simply copy an existing EOS file and modify it for the new EOS. However, there are some subtleties here that are important. -- Parameters for the EOS can be initialzed via an initializer list, and +- Parameters for the EOS can be initialized via an initializer list, and additional parameter checking can be done in the constructor. - Any EOS must have a set of member functions that conform to the general :ref:`EOS API`. In essence, these functions are @@ -291,7 +291,7 @@ At this point your new EOS should be usable to any host code written in C++. To allow the EOS to work with Fortran, an initializer wrapper function needs to be defined and interfaced with Fortran. -First, the C++ intialization function needs to be named soas to avoid namespace +First, the C++ initialization function needs to be named so as to avoid namespace conflicts. We typically name the initialization functions ``init_sg_``. For example, the function for initialing an ideal gas looks like @@ -329,7 +329,7 @@ We also overload the initialization function to make the ``enabled`` and return init_sg_IdealGas(matindex, eos, gm1, Cv, def_en, def_v); } -Finally the fortran side, we then define a fortran interface to the C++ +Finally the Fortran side, we then define a Fortran interface to the C++ initialization function, .. code-block:: fortran @@ -347,7 +347,7 @@ initialization function, end function init_sg_IdealGas end interface -and a fortran wrapper function to call the C++ function: +and a Fortran wrapper function to call the C++ function: .. code-block:: fortran @@ -370,13 +370,13 @@ A Note on the EOS Builder ````````````````````````` The :ref:`EOS Builder ` is a tool that eliminates the need -for chaining together an EOS with a series of modifiers by instead specifing +for chaining together an EOS with a series of modifiers by instead specifying the parameters and modifications in one function. This convenience comes at the cost of added development complexity though, and so we do not require a new EOS to be available for the EOS Builder. At a basic level though, the EOS needs to be declared in the ``EOSType`` enum -and logic needs to be added to initialze the EOS parameters. More effort may be +and logic needs to be added to initialize the EOS parameters. More effort may be needed to make the EOS compatible with modifiers and we point the interested contributor to the existing EOS as examples. @@ -408,7 +408,7 @@ Some notes on style and code architecture * A major influence on code style and architecture is the `ten rules for developing safety-critical code`_, by Gerard Holzmann. Safety critical code is code that exists in a context where failure - implies serious harm. A flight controler on an airplane or + implies serious harm. A flight controller on an airplane or spacecraft or the microcontroller in a car are examples of safety-critical contexts. ``singularity-eos`` is not safety-critical but many of the coding habits advocated for by Holzmann produce @@ -469,7 +469,7 @@ style. Here we briefly discuss a few things one should be aware of. ``PORTABLE_INLINE_FUNCTION``, ``PORTABLE_FORCEINLINE_FUNCTION``. These macros are imported from the `ports-of-call`_ library and resolve to the appropriate - decorations for a given device-side backend such as cuda so the code + decorations for a given device-side backend such as Cuda so the code compiles correctly. Code that doesn't need to run on device, such as EOS class constructors, does not need these decorations. @@ -500,7 +500,7 @@ style. Here we briefly discuss a few things one should be aware of. "reference-semantics." This means that if you copy an EOS object, it should always be a shallow copy, not a deep copy, unless a deep copy is explicitly requested. This is for performance reasons and also to - simplify the managment of data on device. + simplify the management of data on device. * **Real:** The ``Real`` datatype is either a single precision or double precision floating point number, depending on how diff --git a/doc/sphinx/src/models.rst b/doc/sphinx/src/models.rst index 1a130da584b..948abc1fd05 100644 --- a/doc/sphinx/src/models.rst +++ b/doc/sphinx/src/models.rst @@ -34,7 +34,7 @@ EOS Theory An equation of state (EOS) is a constituitive model that generally relates thermodynamic quantities such as pressure, temperature, density, internal -energy, free energy, and entropy consistent with the constraints of equillibrium +energy, free energy, and entropy consistent with the constraints of equilibrium thermodynamics. ``singularity-eos`` contains a number of equations of state that are most useful @@ -75,7 +75,7 @@ To some degree it is the complexity of the reference state and the heat capacity that will determine an EOS's ability to capture the complex behavior of a material. At the simplest level, the ideal gas EOS uses a reference state at zero pressure and energy, while more complex equations of state such as the -Davis EOS use the material's isentrope. In ths way, the reference curve +Davis EOS use the material's isentrope. In this way, the reference curve indicates the conditions under which you can expect the EOS to represent the intended behavior. @@ -106,7 +106,7 @@ where all potentials are specific. Here :math:`e` is again the internal energy, is the Gibbs free energy. While equations of state formulated using the Helmholtz free energy can be particularly attractive (such as the sesame tables), finding a convenient form can be difficult. As such, it becomes -imperitive to extend the Mie-Gruneisen form so that it can form a complete +imperative to extend the Mie-Gruneisen form so that it can form a complete EOS. The heat capacity is defined as @@ -222,7 +222,7 @@ the electron equation of state or ion equation of state. The tabulated models may also support loading tables specifically for electron or ion equations of state. In these cases, an ``enum class`` -specifies which component of the material is being requst: +specifies which component of the material is being requested: .. code-block:: cpp @@ -232,7 +232,7 @@ where here ``ElectronOnly`` is the free electrons of the material, corresponding to Sesame 304 tables, ``IonCold`` is the ions plus cold curve (i.e., the ions if you don't know what a cold curve is), corresponding to the Sesame 303 tables, and ``Total`` is the sum of -free electrons and ions, correspodning to the Sesame 301 tables. +free electrons and ions, corresponding to the Sesame 301 tables. .. note:: @@ -355,7 +355,7 @@ Nomenclature Disambiguation The Gruneisen Parameter ''''''''''''''''''''''' In this description of the EOS models, we use :math:`\Gamma` to represent the -Gruneisen coeficient since this is the most commonly-used symbol in the +Gruneisen coefficient since this is the most commonly-used symbol in the context of Mie-Gruneisen equations of state. The definition of the Gruneisen parameter is @@ -870,7 +870,7 @@ Gruneisen EOS One of the most commonly-used EOS to represent solids is the Steinberg variation of the Mie-Gruneisen EOS, often just shortened to "Gruneisen" EOS. This EOS -uses the Hugoniot as the reference curve and thus is extremly powerful because +uses the Hugoniot as the reference curve and thus is extremely powerful because the basic shock response of a material can be modeled using minimal parameters. The pressure follows the traditional Mie-Gruneisen form, @@ -896,7 +896,7 @@ The user should note that this implies that :math:`e=0` at the reference temperature, :math:`T_0`. Given this simple relationship, the user should treat the temperature from this EOS as only a rough estimate. -Given the inconsisetency in the temperature, we have made the choice **not** to +Given the inconsistency in the temperature, we have made the choice **not** to expose the entropy for this EOS. **Requesting an entropy value will result in an error.** @@ -927,7 +927,7 @@ When the unitless user parameter :math:`b=0`, the Gruneisen parameter is of a form where :math:`\rho\Gamma =` constant in compression, i.e. when :math:`\eta > 0`. If the unitless user parameter :math:`b=\Gamma_0`, the Gruneisen parameter is of a -form where :math:`\Gamma_0 =` constant in compression. These two limitig cases are +form where :math:`\Gamma_0 =` constant in compression. These two limiting cases are shown in the figure below. .. image:: ../SteinbergGammarho.png @@ -946,7 +946,7 @@ The reference pressure along the Hugoniot is determined by \end{cases} where :math:`P_0` is the reference pressure and :math:`c_0`, :math:`s_1`, -:math:`s_2`, and :math:`s_3` are fitting paramters to the +:math:`s_2`, and :math:`s_3` are fitting parameters to the :math:`U_s`-:math:`u_p` curve such that .. math:: @@ -1002,7 +1002,7 @@ There is an overload of the ``Gruneisen`` class which computes Both constructors also optionally accept `MeanAtomicProperties` for the atomic mass and number as a final optional parameter. -Extendended Vinet EOS +Extended Vinet EOS ````````````````````` The extended Vinet EOS is a full EOS, extended in both temperature and density @@ -1172,7 +1172,7 @@ Solving the jump equations above gives that the reference pressure along the Hug Note the singularity at :math:`s \eta = 1` which limits this model's validity to compressions :math:`\eta << 1/s`. If your problem can be expected to have compressions of this order, you should use the PowerMG -EOS that is explicitely constructed for large compressions. +EOS that is explicitly constructed for large compressions. The assumption of linear :math:`U_s`- :math:`u_p` relation is simply not valid at large compressions. The energy along the Hugoniot is given by @@ -1181,7 +1181,7 @@ The energy along the Hugoniot is given by E_H(\rho) = \frac{P_H \eta }{2 \rho_0} + E_0 . -The temperature on the Hugoniot is hard to derive explicitely but with the help of Mathematica +The temperature on the Hugoniot is hard to derive explicitly but with the help of Mathematica we can solve .. math:: @@ -1239,7 +1239,7 @@ the atomic mass and number as a final optional parameter. Mie-Gruneisen power expansion EOS ````````````````````````````````` As we noted above, the assumption of a linear :math:`U_s`- :math:`u_p` relation is simply not valid at large compressions. At -Sandia National Laboratories Z-pinch machine, the compression is routinely so large that a new Mie-Gruneisen EOS was developped, +Sandia National Laboratories Z-pinch machine, the compression is routinely so large that a new Mie-Gruneisen EOS was developed, by `Robinson `_, that could handle these large compressions. The overall structure and motivation for approximations are as described above; in compression it is only the formula for :math:`P_H`, and by extension :math:`T_H`, that differ. This EOS is however modified in expansion to follow an isentrope instead of the invalid-in-expansion Hugoniot. @@ -1453,7 +1453,7 @@ Using the fact that the heat capacity can be expressed as C_V = T\left( \frac{\partial S}{\partial T} \right)_V, -the temperature off of the reference isoentrope can be integrated from this +the temperature off of the reference isentrope can be integrated from this identity to yield .. math:: @@ -1469,7 +1469,7 @@ expressed as a function of temperature and density such that S(\rho, T) = \frac{C_{V,0}}{\alpha} \left( \frac{T}{T_{S,0}(\rho)} \right)^\alpha. The :math:`e(\rho, P)` formulation can now be more-conveniently cast in terms of -termperature such that +temperature such that .. math:: @@ -1496,7 +1496,7 @@ Finally, the pressure and energy along the isentrope are given by where :math:`A`, :math:`B`, :math:`C`, :math:`y`, and :math:`Z` are all -user-settable parameters and again quantities with a subcript of :math:`0` +user-settable parameters and again quantities with a subscript of :math:`0` refer to the reference state. The variable :math:`\bar{\rho}` is simply an integration variable. The parameter :math:`C` is especially useful for ensuring that the high-pressure portion of the shock Hugoniot does not cross that of the @@ -1531,7 +1531,7 @@ Davis Products EOS The Davis products EOS is created from the reference isentrope passing through the CJ state of the high explosive along with a constant heat capacity. The -constant heat capacity leads to the energy being a simple funciton of the +constant heat capacity leads to the energy being a simple function of the temperature deviation from the reference isentrope such that .. math:: diff --git a/doc/sphinx/src/modifiers.rst b/doc/sphinx/src/modifiers.rst index c81a9e330af..d3281be3ce7 100644 --- a/doc/sphinx/src/modifiers.rst +++ b/doc/sphinx/src/modifiers.rst @@ -11,7 +11,7 @@ given EOS model by shifting all energies up or down. Modifiers can be used to, for example, production-harden a model. Only certain combinations of ``EOS`` and ``modifier`` are permitted by -the defualt ``Variant``. For example, only ``IdealGas``, +the default ``Variant``. For example, only ``IdealGas``, ``SpinerEOS``, and ``StellarCollapse`` support the ``RelativisticEOS`` and ``UnitSystem`` modifiers. All models support the ``ShiftedEOS`` and ``ScaledEOS`` modifiers. However, note that modifiers do not @@ -59,7 +59,7 @@ To understand the scaled EOS, consider the pressure for an ideal gas: P = \Gamma \rho \varepsilon -where here :math:`\Gamma` is the Gruneien parameter, :math:`\rho` is +where here :math:`\Gamma` is the Gruneisen parameter, :math:`\rho` is the density, and :math:`\varepsilon` is the specific internal energy. The pressure is unchanged under the operation @@ -99,7 +99,7 @@ this scaling to the definition of the Helmholtz free energy yields F_\mathrm{eos} = e_\mathrm{eos} - TS_\mathrm{eos} = \frac{1}{R} F_\mathrm{in} = \frac{1}{R}e_\mathrm{in} - T\left(\frac{1}{R}S_\mathrm{in}\right), -where the implicaiton is that this inverse the scaling ratio should also be +where the implication is that this inverse the scaling ratio should also be applied to energy. The inverse scaling ratio must be applied to the entropy here in order to ensure that all other thermodynamic potentials (energy, entropy, and the Gibbs free energy) scale similarly. diff --git a/doc/sphinx/src/philosophy.rst b/doc/sphinx/src/philosophy.rst index 7207dc612ad..35167b204b0 100644 --- a/doc/sphinx/src/philosophy.rst +++ b/doc/sphinx/src/philosophy.rst @@ -44,7 +44,7 @@ This also motivates the hot-swappable modifiers for equation of state models. Capturing real-world material, or production-hardening an equation of state can be challenging and imperfect. The modifiers allow the user to ensure an EOS meets their needs, in a way that is -reproducible and comparable accross host codes. +reproducible and comparable across host codes. No Compromise on Performance Portability ------------------------------------------ @@ -56,6 +56,6 @@ Performance, Flexibility, Usability, and Extendability -------------------------------------------------------- We recognize that performance, runtime usability and flexibility, and -extendability are all imporant, and do our best to navigate this +extendability are all important, and do our best to navigate this trade-space. We write our code in as modular a way as possible, but we recognize that sometimes abstraction gets in the way. diff --git a/doc/sphinx/src/using-closures.rst b/doc/sphinx/src/using-closures.rst index c8ffd9c2a4f..dbe8bd399ce 100644 --- a/doc/sphinx/src/using-closures.rst +++ b/doc/sphinx/src/using-closures.rst @@ -9,7 +9,7 @@ When transitioning to a multi-material approach, a single velocity is typically used and the Euler equations are solved with respect to the bulk fluid motion. In this case, the pressure contribution to momentum isn't well-defined and in principle each material could have its own pressure contribution to material -motion. Furthermore, the paritioning of volume and energy between the materials +motion. Furthermore, the partitioning of volume and energy between the materials in the flow is not well-defined either. As a result, a multi-material closure rule is needed to determine both how to @@ -67,7 +67,7 @@ where :math:`\rho_i` is the physical density (i.e. material mass per *material* volume). It is important to note here that while the densities, :math:`\rho_i`, and the volume fractions, :math:`f_i`, will vary as the closure model is applied, the average densities, -:math:`\overline{\rho}_i`, will all remain constant, motiviating their +:math:`\overline{\rho}_i`, will all remain constant, motivating their internal use in the closure solvers. The total density (mass of *participating* materials per total volume) is then @@ -91,11 +91,11 @@ that = \sum_{i = 0}^{N - 1} u_i where :math:`u` is the total internal energy density (internal energy per unit -volume). Similarly, :math:`u_i` is analagous to :math:`\overline{\rho}_i` in +volume). Similarly, :math:`u_i` is analogous to :math:`\overline{\rho}_i` in that it is the internal energy for a material averaged over the entire control volume. -Internally, the closer models in ``singularity-eos`` operate on :math:`f_i`, +Internally, the closure models in ``singularity-eos`` operate on :math:`f_i`, :math:`\overline{\rho}_i`, and :math:`u_i` as well as their total counterparts. This is different than the forms stated at the beginning of this section so that in essence the PTE solver has the form @@ -256,10 +256,10 @@ equilibrium state described by :math:`f_i^*(x_i, y_i)` and + \sum\limits_{i=0}^{N-1} (y_i^* - y_i) \left(\frac{\partial u_i}{\partial y_i}\right)_{x_i}, -providing a means to update the guess for the equilbrium state. Minor +providing a means to update the guess for the equilibrium state. Minor manipulations are needed to recast the derivatives in terms of accessible thermodynamic derivatives, and then these equations can be written in matrix -form to solve for the unknown distance away from the equilibrum state. At each +form to solve for the unknown distance away from the equilibrium state. At each iteration of the Newton-Raphson solver, the derivatives are recomputed and a new update is found until some tolerance is reached. When a good initial guess is used (such as a previous PTE state), some algorithms may converge in @@ -271,7 +271,7 @@ specify the system. For example, if pressure, :math:`P`, and temperature, :math:`T`, are chosen, then the subscripts are eliminated since we seek a solution where all materials have the same temperature and pressure. (See :ref:`pressure-temperature-formulation`.) In this -formulation, there are two equations and two unkowns, and one such +formulation, there are two equations and two unknowns, and one such solver is described below. Most of the current PTE solvers in ``singularity-eos`` are cast in terms @@ -298,7 +298,7 @@ that - (y^*_j - y_j) \left(\frac{\partial P_j}{\partial y_j}\right)_{f_j}, where the equations are typically written such that :math:`j = i + 1`. Since the -equlibrium pressure is the same for both materials, the term cancels out and +equilibrium pressure is the same for both materials, the term cancels out and the material pressures are left. @@ -311,7 +311,7 @@ terms of just the volume fractions: f_\mathrm{tot} - \sum\limits_{i=0}^{N-1} f_i = \sum\limits_{i=0}^{N-1} (f_i^* - f_i). -The EOS only returns derivatives in terms of density though, so a the density +The EOS only returns derivatives in terms of density though, so the density derivatives must be transformed to volume fraction derivatives via .. math:: @@ -319,8 +319,8 @@ derivatives must be transformed to volume fraction derivatives via \left(\frac{\partial Q}{\partial f_i}\right)_X = - \frac{\rho_i^2}{\rho}\left(\frac{\partial Q}{\partial \rho_i}\right)_X, -were :math:`Q` and :math:`X` are arbitrary thermodynamic variables. At this -point, there are :math:`N + 1` equations and unknowns in the PTE sover. The +where :math:`Q` and :math:`X` are arbitrary thermodynamic variables. At this +point, there are :math:`N + 1` equations and unknowns in the PTE solver. The choice of the second independent variable is discussed below and has implications for both the number of additional unknowns and the stability of the method. @@ -331,9 +331,9 @@ The Pressure-Temperature Formulation An obvious choice is to treat the independent variables as pressure and temperature. Then one has only two equations and two unknowns. The -residual contains only the volume fraction and energy summmation rules +residual contains only the volume fraction and energy summation rules described above. Taylor expanding these residuals about fixed -temeprature and pressure points leads to two residual equations of the +temperature and pressure points leads to two residual equations of the form .. math:: @@ -391,7 +391,7 @@ equations of the form T_i(\rho_i, \epsilon_i) - T_j(\rho_j, \epsilon_j) = 0. -Again Taylor expanding about the equilibirum state, this results in a set of +Again Taylor expanding about the equilibrium state, this results in a set of equations of the form .. math:: @@ -413,7 +413,7 @@ state by iterating on temperature; there may also be a loss of accuracy in the derivatives depending on how they are calculated. In general, the density-temperature formulation of the PTE solver seems to be -more stable and performant and is usually preferrred to this formulation. +more stable and performant and is usually preferred to this formulation. In the code this is referred to as the ``PTESolverRhoU``. @@ -493,7 +493,7 @@ equivalent sized :math:`N+1` system) that in the 2-material case the Jacobian is a 2x2 matrix, similar to the ``PTESolverPT``. In many cases the number of materials participating in a mixed cell will be small, and the difference between :math:`N` equations and :math:`N+1` -equuations may be be significant from a performance +equations may be be significant from a performance perspective. However, special care must be taken (and has been taken in our implementation) to ensure that all volume fractions remain within their regime of validity as the solver iterates. @@ -529,7 +529,7 @@ Fixed temperature When the temperature and total density are known, the equilibrium pressure and the component densities are unknown. This requires a total of :math:`N` equations and unknowns. Since the total energy is unknown, it can be dropped -from the contraints leaving just the :math:`N - 1` pressure equality equations +from the constraints leaving just the :math:`N - 1` pressure equality equations and the volume fraction sum constraint. The pressure residuals can then be simplified to be @@ -573,7 +573,7 @@ entirely header only. There are several moving parts. First, one must allocate scratch space used by the solver. There are helper routines for providing the needed -scratch space, wich will tell you how many bytes per mixed cell are +scratch space, which will tell you how many bytes per mixed cell are required. For example: .. cpp:function:: int PTESolverRhoTRequiredScratch(const size_t nmat); @@ -584,7 +584,7 @@ and provide the number of real numbers (i.e., either ``float`` or ``double``) required for a single cell given a number of materials in -equilibriun for either the ``RhoT`` or ``RhoU`` solver. +equilibrium for either the ``RhoT`` or ``RhoU`` solver. The equivalent functions @@ -625,7 +625,7 @@ materials. The PTE solvers **require** that all input densities and volume fractions are non-zero. As a result, ``nmat`` refers to the number of *participating* materials. The user is encouraged to wrap their data arrays using an - ``Indexer`` concept where, for example, three paricipating PTE materials + ``Indexer`` concept where, for example, three participating PTE materials might be indexed as 5, 7, 20 in the material arrays. This requires overloading the square bracket operator to map from PTE idex to material index. @@ -663,44 +663,44 @@ contains the following member fields, with default values: .. code-block:: cpp -struct MixParams { - bool verbose = false; - bool iterate_t_guess = true; - Real derivative_eps = 3.0e-6; - Real pte_rel_tolerance_p = 1.0e-6; - Real pte_rel_tolerance_t = 1.0e-4; - Real pte_rel_tolerance_e = 1.0e-6; - Real pte_rel_tolerance_v = 1.0e-6; - Real pte_abs_tolerance_p = 1.0e-6; - Real pte_abs_tolerance_t = 1.0e-4; - - Real pte_slow_convergence_thresh = 0.99; - Real pte_rel_tolerance_p_sufficient = 1.e2 * pte_rel_tolerance_p; - Real pte_rel_tolerance_t_sufficient = 10 * pte_rel_tolerance_t; - Real pte_rel_tolerance_e_sufficient = 1.e2 * pte_rel_tolerance_e; - Real pte_rel_tolerance_v_sufficient = 1.e2 * pte_rel_tolerance_v; - Real pte_abs_tolerance_p_sufficient = 1.e2 * pte_abs_tolerance_p; - Real pte_abs_tolerance_t_sufficient = 10 * pte_abs_tolerance_t; - - std::size_t pte_max_iter_per_mat = 128; - Real line_search_alpha = 1.e-2; - std::size_t line_search_max_iter = 6; - Real line_search_fac = 0.5; - Real vfrac_safety_fac = 0.95; - Real temperature_limit = 1.0e15; - Real default_tguess = 300.; - Real min_dtde = 1.0e-16; - std::size_t pte_small_step_tries = 2; - Real pte_small_step_thresh = 1e-16; - Real pte_max_dpdv = -1e-8; - - // choose index with largest volume fraction - std::int64_t pte_reduced_system_exclude_idx = -1; -}; + struct MixParams { + bool verbose = false; + bool iterate_t_guess = true; + Real derivative_eps = 3.0e-6; + Real pte_rel_tolerance_p = 1.0e-6; + Real pte_rel_tolerance_t = 1.0e-4; + Real pte_rel_tolerance_e = 1.0e-6; + Real pte_rel_tolerance_v = 1.0e-6; + Real pte_abs_tolerance_p = 1.0e-6; + Real pte_abs_tolerance_t = 1.0e-4; + + Real pte_slow_convergence_thresh = 0.99; + Real pte_rel_tolerance_p_sufficient = 1.e2 * pte_rel_tolerance_p; + Real pte_rel_tolerance_t_sufficient = 10 * pte_rel_tolerance_t; + Real pte_rel_tolerance_e_sufficient = 1.e2 * pte_rel_tolerance_e; + Real pte_rel_tolerance_v_sufficient = 1.e2 * pte_rel_tolerance_v; + Real pte_abs_tolerance_p_sufficient = 1.e2 * pte_abs_tolerance_p; + Real pte_abs_tolerance_t_sufficient = 10 * pte_abs_tolerance_t; + + std::size_t pte_max_iter_per_mat = 128; + Real line_search_alpha = 1.e-2; + std::size_t line_search_max_iter = 6; + Real line_search_fac = 0.5; + Real vfrac_safety_fac = 0.95; + Real temperature_limit = 1.0e15; + Real default_tguess = 300.; + Real min_dtde = 1.0e-16; + std::size_t pte_small_step_tries = 2; + Real pte_small_step_thresh = 1e-16; + Real pte_max_dpdv = -1e-8; + + // choose index with largest volume fraction + std::int64_t pte_reduced_system_exclude_idx = -1; + }; where here ``verbose`` enables verbose output in the PTE solve is, ``derivative_eps`` is the spacing used for finite differences -evaluations of equations of state when building a jacobian. The +evaluations of equations of state when building a Jacobian. The ``pte_rel_tolerance_p``, ``pte_rel_tolerance_e``, and ``pte_rel_tolerance_t`` variables are relative tolerances for the error in the pressure, energy, temperature respectively. The @@ -720,7 +720,7 @@ variables. If between two iterations the residual does not decrease to ``pte_slow_convergence_thresh`` times its previous value or smaller, **and** the errors in the relevant variables are within the ``_sufficient`` tolerances, the solver will consider that "good -enough" and report succesful convergence. In general these should be +enough" and report successful convergence. In general these should be set to an order of magnitude or two less strict than the desired tolerance. @@ -737,12 +737,12 @@ materials used. ``line_search_alpha`` is used as a safety factor in the line search. ``line_search_max_iter`` is the maximum number of iterations the solver is allowed to take in the line search. ``line_search_fac`` is the step size in the line -search. ``vfrac_safety_fac`` limites the relative amount the volume +search. ``vfrac_safety_fac`` limits the relative amount the volume fraction can take in a given iteration. ``temperature_limit`` is the maximum temperature allowed by the solver. ``default_tguess`` is used as an initial guess for temperature if a better guess is not passed in -or cannot be inferred. ``min_dtde`` is the minmum that temperature is -allowed to change with respect to energy when computing Jacobians. +or cannot be inferred. ``min_dtde`` is the minimum allowed change to +temperature with respect to energy when computing Jacobians. The parameters ``pte_small_step_tries`` and ``pte_small_step_thresh`` guard against the PTE solver taking tiny steps forever and not @@ -786,9 +786,9 @@ The constructor for the ``PTESolverRhoU`` has the same structure: Real_t &&temp, Real_t &&press, Lambda_t &&lambda, Real *scratch, const Real Tnorm = 0, const MixParams ¶ms = MixParams()); -Both constructors are callable on host or device. In gerneral, +Both constructors are callable on host or device. In general, densities and internal energies are the required inputs. However, all -indexer quantities are asusmed to be input/output, as the PTE solver +indexer quantities are assumed to be input/output, as the PTE solver may use unknowns, such as pressure and temperature, as initial guesses and may reset input quantities, such as material densities, to be thermodynamically consistent with the equilibrium solution. @@ -826,7 +826,7 @@ Initial Guesses for PTE Solvers As is always the case when solving systems of nonlinear equations, good initial guesses are important to ensure rapid convergence to the solution. For the PTE -solvers, this means providing intial guesses for the material densities and the +solvers, this means providing initial guesses for the material densities and the equilibrium temperature. For material densities, a good initial guess is often the previous value obtained from a prior call to the solver. ``singularity-eos`` does not provide any mechanism to cache these values from call to call, so it is diff --git a/doc/sphinx/src/using-eos.rst b/doc/sphinx/src/using-eos.rst index fe34a72c500..7105f884852 100644 --- a/doc/sphinx/src/using-eos.rst +++ b/doc/sphinx/src/using-eos.rst @@ -857,7 +857,7 @@ provides some internal transformation on inputs and outputs. For example the ``ShiftedEOS`` modifier changes the reference energy of a given EOS model by shifting all energies up or down. Modifiers can be used to, for example, production-harden a model. Only certain -combinations of ``EOS`` and ``modifier`` are permitted by the defualt +combinations of ``EOS`` and ``modifier`` are permitted by the default ``Variant``. For example, only ``IdealGas``, ``SpinerEOS``, and ``StellarCollapse`` support the ``RelativisticEOS`` and ``UnitSystem`` modifiers. All models support the ``ShiftedEOS`` and ``ScaledEOS`` @@ -910,7 +910,7 @@ unmodified EOS model, call The return value here will be either the type of the ``EOS`` variant type or the unmodified model (for example ``IdealGas``), depending -on whether this method was callled within a variant or on a standalone +on whether this method was called within a variant or on a standalone model outside a variant. If you have chained modifiers, e.g., @@ -934,7 +934,7 @@ required by the modifier is appended to the end of the lambda indexer. For example, the ``StellarCollapse`` EOS model requires ``nlambda=2``. The ``ZSplitI`` modifier rquires ``nlambda=1``. Together, ``ZSplitI`` requires a -lambda indexer of length 3, an the ordering is two parameters for +lambda indexer of length 3, and the ordering is two parameters for ``StellarCollapse`` first, and then the parameter required by ``ZSplitI``. @@ -1155,7 +1155,7 @@ Note that for relativistic models, c_s^2 = \frac{B_S}{w} -where :math:`w = \rho h` for specific entalpy :math:`h` is the +where :math:`w = \rho h` for specific enthalpy :math:`h` is the enthalpy by volume. The sound speed may also differ for, e.g., porous models, where the pressure is less directly correlated with the density. @@ -1346,19 +1346,19 @@ The function const unsigned long output, Indexer_t &&lambda = nullptr) const; -is a a bit of a special case. ``output`` is a bitfield represented as +is a bit of a special case. ``output`` is a bitfield represented as an unsigned 64 bit number. Quantities such ``pressure`` and ``specific_internal_energy`` can be represented in the ``output`` field by flipping the appropriate bits. There is one bit per quantity. ``FillEos`` sets all parameters (passed in by reference) -requested in the ``output`` field utilizing all paramters not +requested in the ``output`` field utilizing all parameters not requested in the ``output`` flag, which are assumed to be input. The ``output`` variable uses the same ``thermalqs`` flags as the ``PreferredInput`` method. If an insufficient number of variables are passed in as input, or if the input is not a combination supported by a given model, the function is expected to raise an error. The exact -combinations of inputs and ouptuts supported is model +combinations of inputs and outputs supported is model dependent. However, the user will always be able to use density and temperature or internal energy as inputs and get all other quantities as outputs. diff --git a/doc/sphinx/src/using-kpt.rst b/doc/sphinx/src/using-kpt.rst index acd8025da35..31eed336c68 100644 --- a/doc/sphinx/src/using-kpt.rst +++ b/doc/sphinx/src/using-kpt.rst @@ -8,7 +8,7 @@ Kinetic Phase Transition Framework ================================== A step in adapting to more realistic calculations is to -get away from that phase transitions are instantanious and the +get away from the idea that phase transitions are instantaneous and the system is in, at least, local thermal equilibrium (LTE) all the time. Allowing for superheated (the material is hotter than the equilibrium state) and supercooled (the material is cooler than the equilibrium state) materials is @@ -22,7 +22,7 @@ Gibbs free energy. If the material is heated or cooled from this equilibrium sta phase emerges to have a lower Gibbs free energy, a phase transition occurs and the system eventually transform to this new phase. However, all phase transitions need some type of *nucleation event* to get started. For the liquid raindrop cooling down while falling to the ground through very cold air, the hit against the -asphalt is the nucleation event, and the supercooled liquid in the drop instantaniously transform to the equilibrium ice phase. +asphalt is the nucleation event, and the supercooled liquid in the drop instantaneously transform to the equilibrium ice phase. For the very hot coffee, the spoon insertion is the "nucleation" event when the very hot liquid coffee instantaneously transforms into its equilibrium phase, gas. @@ -201,10 +201,10 @@ that ``gibbs[gibbsorder[0]]`` is the highest Gibbs free energy and ``gibbs[gibbs The time step ''''''''''''' -If a timestep would be truely infinitesimal, :math:`R_{ij} dt \leq 1` would always hold, since however big the +If a timestep were truely infinitesimal, :math:`R_{ij} dt \leq 1` would always hold, since however big the rate :math:`R_{ij}` is, :math:`dt < \frac{1}{R_{ij}}`. This means that the new mass fractions would always obey :math:`0 \leq \mu_i \leq 1`. However, with a discretized time step, :math:`R_{ij} \Delta t` can become larger than :math:`1`, and it can be that even -if the master equation holds, it results in some phase mass fractions becomming negative and some being above :math:`1`, which is unphysical. +if the master equation holds, it results in some phase mass fractions becoming negative and some being above :math:`1`, which is unphysical. One way of dealing with this is to use a time step, :math:`\Delta t`, that is smaller than the inverse of the largest rate from an active phase. A routine suggesting a maximum timestep is available in ``singularity-eos``: @@ -250,8 +250,8 @@ the phase transition indices :math:`jk` is as can be verified by hand in the figure above. -Note that this method depleats phases in order of mass transfer to the lowest Gibbs free energy first, then the next lowest, and so on (see figure above), -but stops once the originating phase is depleated. If this is reflecting the physical reality, is up to the user to decide. The size of the time step -problem is taken care of by never transfering more that the existing mass in a phase to any other phase. +Note that this method depletes phases in order of mass transfer to the lowest Gibbs free energy first, then the next lowest, and so on (see figure above), +but stops once the originating phase is depleted. If this is reflecting the physical reality, is up to the user to decide. The size of the time step +problem is taken care of by never transferring more that the existing mass in a phase to any other phase.