added documentation for range based reactors

documentation/source/users/rmg/input.rst

@@ -257,6 +257,61 @@ 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 use reactors at fixed points, reaction conditions are sampled from a range of conditions.  
+Conditions are chosen using a weighted stochastic grid sampling algorithm.  An objective function measuring 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 values are then normalized to one and a grid point is selected such that
+each the probability a given grid point is chosen is equal to its normalized objective function value.  Then a random
+step of maximum length half 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.  
+These variable condition reactors terminate after a defined number of iterations (``nSimsTerm``). In theory use of 
+these reactors should 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 ``nSimsTerm`` reaction conditions. Theoretically if ``nSimsTerm`` is set high enough the RMG model converges over the 
+entire interval.  Even convergence for smaller ``nSimsTerm`` (values near the number of individual reactors you would 
+use to span the system) is usually superior to the convergence achieved (over the whole interval) using individual
+reactors.  If there is a particular reaction condition you expect to converge more slowly than the rest of the range 
+and are worried might be missed in theory there is virually no cost to using a single condition reactor at that 
+condition along with the range based reactor.  Interval convergence on most of the interval can usually be
+ achieved by using the number of individual reactors you would typically use to span the space and adding one or two. 
+This is not a particularly accurate rule of thumb, (sometimes you can get by with significantly fewer). This number of
+reactors will usually give you significantly better convergence than using individual reactors. How different this 
+result is from individual reactors and full interval convergence is incredibly system dependent not just on the 
+intervals choosen but the chemistry occuring.  
+
+If normalization of the ranged conditions is undesirable 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
+a mole fraction of one.  This ensures that all species except the ``balanceSpecies`` have mole fractions within the range
+specified.  
+
 .. _simulatortolerances:
 
 Simulator Tolerances