added documentation for range based reactors

documentation/source/users/rmg/input.rst

@@ -257,6 +257,70 @@ sensitivities for dln(C_i)/dln(k_j) > sensitivityThreshold  or dlnC_i/d(G_j) > s
 Note that in the RMG job, after the model has been generated to completion, sensitivity analysis will be conducted
 in one final simulation (sensitivity is not performed in intermediate iterations of the job).
 
+Advanced Setting: Range Based Reactors
+-------------------------------------------------
+
+Under this setting rather than using reactors at fixed points, reaction conditions are sampled from a range of conditions.  
+Conditions are chosen using a weighted stochastic grid sampling algorithm.  An implemented objective function measures how
+desirable it is to sample from a point condition (T, P, concentrations) based on prior run conditions (weighted by how 
+recent they were and how many objects they returned). Each iteration this objective function is evaluated at a grid of
+points spaning the reactor range (the grid has 20^N points where N is the number of dimensions).  The grid values are then normalized to one and a grid point is chosen with probability 
+equal to its normalized objective function value.  Then a random step of maximum length sqrt(2)/2 times the distance between grid 
+points is taken from that grid point to give the chosen condition point.  The random numbers are seeded so that this does 
+not make the algorithm non-deterministic.  
+
+.. figure:: images/RangedReactorDiagram.png
+    :width: 300px
+    :align: center
+    :height: 300px
+
+These variable condition reactors terminate after a defined number of 
+consecutive successfully terminating iterations (``nSimsTerm``). Use of these reactors tends to improve treatment of reaction 
+conditions that otherwise would be between reactors and reduce the number of simulations needed by focusing on reaction 
+conditions at which the model terminates earlier.  An example with sensitivity analysis at a specified reaction condition 
+is available below::
+
+	simpleReactor(
+		temperature=[(1000,'K'),(1500,'K')],
+		pressure=[(1.0,'bar'),(10.0,'bar')],
+		nSimsTerm=12,
+		initialMoleFractions={
+		"ethane": [0.05,0.15],
+		"O2": 0.1,
+		"N2": 0.9,
+		},
+		terminationConversion={
+		'ethane': 0.1,
+		},
+		terminationTime=(1e1,'s'),
+		sensitivityTemperature = (1000,'K'),
+		sensitivityPressure = (10.0,'bar'),
+		sensitivityMoleFractions = {"ethane":0.1,"O2":0.9},
+		sensitivity=["ethane","O2"],
+		sensitivityThreshold=0.001,
+		balanceSpecies = "N2",
+		)
+
+Note that increasing ``nSimsTerm`` improves convergence over the entire range, but convergence is only guaranteed at the 
+last set of ``nSimsTerm`` reaction conditions. Theoretically if ``nSimsTerm`` is set high enough the RMG model converges over the 
+entire interval.  Except at very small values for ``nSimsTerm`` the convergence achieved is usually as good or superior to 
+that achieved using the same number of evenly spaced fixed reactors.   
+
+If there is a particular reaction condition you expect to converge more slowly than the rest of the range 
+there is virually no cost to using a single condition reactor (or a ranged reactor at a smaller range) at that condition 
+and a ranged reactor with a smaller value for nSimsTerm.  This is because the fixed reactor simulations will almost always
+be useful and keep the overall RMG job from terminating when the ranged reactor samples the faster converging conditions.   
+
+What you should actually set ``nSimsTerm`` to is very system dependent.  The value you choose should be at least 2 + N 
+where N is the number of dimensions the reactor spans (T=>N=1, T and P=>N=2, etc...).  There may be benefits to setting it as high
+as 2 + 5N.  The first should give you convergence over most of the interval that is almost always better than the same 
+number of fixed reactors.  The second should get you reasonably close to convergence over the entire range for N <= 2.  
+
+For gas phase reactors if normalization of the ranged mole fractions is undesirable (eg. perhaps a specific species mole 
+fractions needs to be kept constant) one can use a ``balanceSpecies``.  When a ``balanceSpecies`` is used instead of 
+normalizing the mole fractions the concentration of the defined ``balanceSpecies`` is adjusted to maintain an overall mole 
+fraction of one.  This ensures that all species except the ``balanceSpecies`` have mole fractions within the range specified.  
+
 .. _simulatortolerances:
 
 Simulator Tolerances