doc/src/fix_rx.txt

   1 "LAMMPS WWW Site"_lws - "LAMMPS Documentation"_ld - "LAMMPS Commands"_lc :c
   2
   3 :link(lws,http://lammps.sandia.gov)
   4 :link(ld,Manual.html)
   5 :link(lc,Section_commands.html#comm)
   6
   7 :line
   8
   9 fix rx command :h3
  10
  11 [Syntax:]
  12
  13 fix ID group-ID rx file localTemp matrix solver minSteps ... :pre
  14
  15 ID, group-ID are documented in "fix"_fix.html command
  16 rx = style name of this fix command
  17 file = filename containing the reaction kinetic equations and Arrhenius parameters
  18 localTemp = {none,lucy} = no local temperature averaging or local temperature defined through Lucy weighting function
  19 matrix = {sparse, dense} format for the stoichiometric matrix
  20 solver = {lammps_rk4,rkf45} = rk4 is an explicit 4th order Runge-Kutta method; rkf45 is an adaptive 4th-order Runge-Kutta-Fehlberg method
  21 minSteps = # of steps for rk4 solver or minimum # of steps for rkf45 (rk4 or rkf45)
  22 maxSteps = maximum number of steps for the rkf45 solver (rkf45 only)
  23 relTol = relative tolerance for the rkf45 solver (rkf45 only)
  24 absTol = absolute tolernace for the rkf45 solver (rkf45 only)
  25 diag   = Diagnostics frequency for the rkf45 solver (optional, rkf45 only) :ul
  26
  27 [Examples:]
  28
  29 fix 1 all rx kinetics.rx none dense lammps_rk4
  30 fix 1 all rx kinetics.rx none sparse lammps_rk4 1
  31 fix 1 all rx kinetics.rx lucy sparse lammps_rk4 10
  32 fix 1 all rx kinetics.rx none dense rkf45 1 100 1e-6 1e-8
  33 fix 1 all rx kinetics.rx none dense rkf45 1 100 1e-6 1e-8 -1 :pre
  34
  35 [Description:]
  36
  37 Fix {rx} solves the reaction kinetic ODEs for a given reaction set that is
  38 defined within the file associated with this command.
  39
  40 For a general reaction such that
  41
  42 :c,image(Eqs/fix_rx_reaction.jpg)
  43
  44 the reaction rate equation is defined to be of the form
  45
  46 :c,image(Eqs/fix_rx_reactionRate.jpg)
  47
  48 In the current implementation, the exponents are defined to be equal
  49 to the stoichiometric coefficients.  A given reaction set consisting
  50 of {n} reaction equations will contain a total of {m} species.  A set
  51 of {m} ordinary differential equations (ODEs) that describe the change
  52 in concentration of a given species as a function of time are then
  53 constructed based on the {n} reaction rate equations.
  54
  55 The ODE systems are solved over the full DPD timestep {dt} using either a 4th
  56 order Runge-Kutta {rk4} method with a fixed step-size {h}, specified
  57 by the {lammps_rk4} keyword, or a 4th order Runge-Kutta-Fehlberg (rkf45) method
  58 with an adaptive step-size for {h}. The number of ODE steps per DPD timestep
  59 for the rk4 method is optionally specified immediately after the rk4
  60 keyword. The ODE step-size is set as {dt/num_steps}. Smaller
  61 step-sizes tend to yield more accurate results but there is not
  62 control on the error. For error control, use the rkf45 ODE solver.
  63
  64 The rkf45 method adjusts the step-size so that the local truncation error is held
  65 within the specified absolute and relative tolerances. The initial step-size {h0}
  66 can be specified by the user or estimated internally. It is recommeded that the user
  67 specify {h0} since this will generally reduced the number of ODE integration steps
  68 required. {h0} is defined as {dt / min_steps} if min_steps >= 1. If min_steps == 0,
  69 {h0} is estimated such that an explicit Euler method would likely produce
  70 an acceptable solution. This is generally overly conservative for the 4th-order
  71 method and users are advised to specify {h0} as some fraction of the DPD timestep.
  72 For small DPD timesteps, only one step may be necessary depending upon the tolerances.
  73 Note that more than min_steps ODE steps may be taken depending upon the ODE stiffness
  74 but no more than max_steps will be taken. If max_steps is reached, an error warning
  75 is printed and the simulation is stopped.
  76
  77 After each ODE step, the solution error {e} is tested and weighted using the absTol
  78 and relTol values. The error vector is weighted as {e} / (relTol * |{u}| + absTol)
  79 where {u} is the solution vector. If the norm of the error is <= 1, the solution is
  80 accepted, {h} is increased by a proportional amount, and the next ODE step is begun.
  81 Otherwise, {h} is shrunk and the ODE step is repeated.
  82
  83 Run-time diagnostics are available for the rkf45 ODE solver. The frequency
  84 (in time-steps) that diagnostics are reported is controlled by the last (optional)
  85 12th argument. A negative frequency means that diagnostics are reported once at the
  86 end of each run. A positive value N means that the diagnostics are reported once
  87 per N time-steps.
  88
  89 The diagnostics report the average # of integrator steps and RHS function evaluations
  90 and run-time per ODE as well as the average/RMS/min/max per process. If the
  91 reporting frequency is 1, the RMS/min/max per ODE are also reported. The per ODE
  92 statistics can be used to adjust the tolerance and min/max step parameters. The
  93 statistics per MPI process can be useful to examine any load imbalance caused by the
  94 adaptive ODE solver. (Some DPD particles can take longer to solve than others. This
  95 can lead to an imbalance across the MPI processes.)
  96
  97 :line
  98
  99 The filename specifies a file that contains the entire set of reaction
 100 kinetic equations and corresponding Arrhenius parameters.  The format of
 101 this file is described below.
 102
 103 There is no restriction on the total number or reaction equations that
 104 are specified.  The species names are arbitrary string names that are
 105 associated with the species concentrations.  Each species in a given
 106 reaction must be preceded by it's stoichiometric coefficient.  The
 107 only delimiters that are recognized between the species are either a
 108 {+} or {=} character.  The {=} character corresponds to an
 109 irreversible reaction.  After specifying the reaction, the reaction
 110 rate constant is determined through the temperature dependent
 111 Arrhenius equation:
 112
 113 :c,image(Eqs/fix_rx.jpg)
 114
 115 where {A} is the Arrhenius factor in time units or concentration/time
 116 units, {n} is the unitless exponent of the temperature dependence, and
 117 {E_a} is the activation energy in energy units.  The temperature
 118 dependence can be removed by specifying the exponent as zero.
 119
 120 The internal temperature of the coarse-grained particles can be used
 121 in constructing the reaction rate constants at every DPD timestep by
 122 specifying the keyword {none}.  Alternatively, the keyword {lucy} can
 123 be specified to compute a local-average particle internal temperature
 124 for use in the reaction rate constant expressions.  The local-average
 125 particle internal temperature is defined as:
 126
 127 :c,image(Eqs/fix_rx_localTemp.jpg)
 128
 129 where the Lucy function is expressed as:
 130
 131 :c,image(Eqs/fix_rx_localTemp2.jpg)
 132
 133 The self-particle interaction is included in the above equation.
 134
 135 The stoichiometric coefficients for the reaction mechanism are stored
 136 in either a sparse or dense matrix format. The dense matrix should only be
 137 used for small reaction mechanisms. The sparse matrix should be used when there
 138 are many reactions (e.g., more than 5). This allows the number of reactions and
 139 species to grow while keeping the computational cost tractable. The matrix
 140 format can be specified as using either the {sparse} or {dense} keywords.
 141 If all stoichiometric coefficients for a reaction are small integers (whole
 142 numbers <= 3), a fast exponential function is used. This can save significant
 143 computational time so users are encouraged to use integer coefficients
 144 where possible.
 145
 146 :line
 147
 148 The format of a tabulated file is as follows (without the
 149 parenthesized comments):
 150
 151 # Rxn equations and parameters                                               (one or more comment or blank lines) :pre
 152 1.0 hcn + 1.0 no2 = 1.0  no + 0.5 n2  + 0.5 h2 + 1.0 co   2.49E+01 0.0 1.34  (rxn equation, A, n, Ea)
 153 1.0 hcn + 1.0  no = 1.0  co + 1.0 n2  + 0.5 h2            2.16E+00 0.0 1.52
 154 ...
 155 1.0  no + 1.0  co = 0.5  n2 + 1.0 co2                     1.66E+06 0.0 0.69  :pre
 156
 157 A section begins with a non-blank line whose 1st character is not a
 158 "#"; blank lines or lines starting with "#" can be used as comments
 159 between sections.
 160
 161 Following a blank line, the next N lines list the N reaction
 162 equations.  Each species within the reaction equation is specified
 163 through its stoichiometric coefficient and a species tag.  Reactant
 164 species are specified on the left-hand side of the equation and
 165 product species are specified on the right-hand side of the equation.
 166 After specifying the reactant and product species, the final three
 167 arguments of each line represent the Arrhenius parameter {A}, the
 168 temperature exponent {n}, and the activation energy {Ea}.
 169
 170 Note that the species tags that are defined in the reaction equations
 171 are used by the "fix eos/table/rx"_fix_eos_table_rx.html command to
 172 define the thermodynamic properties of each species.  Furthermore, the
 173 number of species molecules (i.e., concentration) can be specified
 174 either with the "set"_set.html command using the "d_" prefix or by
 175 reading directly the concentrations from a data file.  For the latter
 176 case, the "read_data"_read_data.html command with the fix keyword
 177 should be specified, where the fix-ID will be the "fix rx" ID with a
 178 "_SPECIES" suffix, e.g.
 179
 180 fix          foo all rx reaction.file ...
 181 read_data    data.dpd fix foo_SPECIES NULL Species
 182
 183 :line
 184
 185 [Restrictions:]
 186
 187 This command is part of the USER-DPD package.  It is only enabled if
 188 LAMMPS was built with that package.  See the "Making
 189 LAMMPS"_Section_start.html#start_3 section for more info.
 190
 191 This command also requires use of the "atom_style dpd"_atom_style.html
 192 command.
 193
 194 This command can only be used with a constant energy or constant
 195 enthalpy DPD simulation.
 196
 197 [Related commands:]
 198
 199 "fix eos/table/rx"_fix_eos_table_rx.html,
 200 "fix shardlow"_fix_shardlow.html,
 201 "pair dpd/fdt/energy"_pair_dpd_fdt.html
 202
 203 [Default:] none