Merge pull request #249 from ReactionMechanismGenerator/debugging_docs

Improve Documentation

Author: mjohnson541

docs/make.jl

@@ -9,6 +9,7 @@ makedocs(
     modules = [ReactionMechanismSimulator],
     pages = [
         "Home" => "index.md",
+        "Installation.md",
         "Input.md",
         "Simulating.md",
         "Analysis.md",

docs/src/Analysis.md

@@ -80,6 +80,13 @@ Transitory sensitivity values can be computed using several different algorithms
 Please let us know on our Github issues page if we're missing any important
 property calculators.  
 
+## Crash Analysis
+
+When thermodynamics and kinetics are poorly assigned mechanisms can become too stiff to simulate causing the solver to crash. In these
+ cases it is very important to be able to efficiently identify potential offending thermochemistry and/or kinetics. Our crash analysis tool analyzes 
+ the reaction and species fluxes to identify NaN quantities and quantities that are unusually large. A crash report can be generated from the associated `Simulation` or `SystemSimulation` object with `printcrashanalysis(analyzecrash(sim;tol=tol))`. In general, the correct `tol` depends on how much faster the offending chemistry is than the real chemistry. Rather than use the default tolerance one should adjust `tol` to achieve a reasonable amount of possible offending thermochemistry and kinetics, adjusting up to reduce the amount identified while decreasing `tol` will cause
+the amount identified to increase. 
+
 ## Plotting
 
 ### Plotting Mole Fractions

docs/src/Installation.md

@@ -0,0 +1,45 @@
+# Install Julia
+RMS is written in Juila language. So before stepping any further, Julia needs to be installed. The download links can be found at [download Julia](https://julialang.org/downloads/). More instructions can be found from the [instruction page](https://julialang.org/downloads/platform/).
+
+## Standard Installation
+With julia RMS can be installed with:  
+
+```
+using Pkg
+Pkg.add("ReactionMechanismSimulator")
+Pkg.build("ReactionMechanismSimulator")
+```
+
+## Developer Installation
+Clone RMS to your machine in an appropriate location we will refer to as `RMS_PATH``:  
+```
+git clone https://github.com/ReactionMechanismGenerator/ReactionMechanismSimulator.jl.git
+```
+then you can install with 
+```
+import Pkg
+Pkg.develop(Pkg.PackageSpec(path=RMS_PATH)) 
+Pkg.build("ReactionMechanismSimulator")
+```
+
+## Testing RMS
+Unit and functional tests for RMS can be run with: 
+```
+import Pkg
+Pkg.test("ReactionMechanismSimulator")
+```
+
+## pyrms
+We also provide a python wrapper for RMS, [pyrms](https://github.com/ReactionMechanismGenerator/pyrms). Installation instructions are available on its github page. 
+
+## Julia-Python Linking
+The above instructions will automatically handle Julia-Python linking. However, in some cases it can be useful to use python from a specific conda environment. For these cases we provide instructions to relink Julia to a different Anaconda Python environment where `PATH_TO_YOUR_ENV` is the path to the Anaconda environment and `PATH_TO_PYTHON` is the path to the associated Python executable: 
+
+```
+import Pkg
+Pkg.add("PyCall")                              
+ENV["CONDA_JL_HOME"] = PATH_TO_YOUR_ENV        
+Pkg.build("Conda")                             
+ENV["PYTHON"] = PATH_TO_PYTHON                 
+Pkg.build("PyCall")                            
+```

docs/src/Simulating.md

@@ -109,6 +109,36 @@ sol = solve(react.ode,CVODE_BDF(),abstol=1e-20,reltol=1e-12;forwardsensitivities
 
 In general CVODE_BDF tends to work well on these problems.  
 
+## Saving a Solution Object
+
+The user may wish to save useful objects from above:
+
+```
+bsol = Simulation(sol, domain)
+```
+
+Saving the data to a Julia data structure ([JLD2](https://github.com/JuliaIO/JLD2.jl)) seems to work well. Once the `JLD2` package has been downloaded, data can be saved using the following commands:
+
+```
+using JLD2, FileIO
+save("<file_name>.jld2", "bsol_saved", bsol)
+```
+
+The data can be read back into Julia as a dictionary, and the desired data can be accessed using its corresponding key:
+
+```
+d = load("<file_name>.jld2")
+bsol_loaded = d["bsol_saved"]
+```
+
+Since the data is saved in HDF5 format, it can also be read into Python as follows:
+
+```
+import h5py
+f = h5py.File("<file_name", "r")
+```
+
+
 ## Threaded Sensitivity Analysis
 Instead of solving all of the sensitivity equations at once as is done in raw Forward sensitivity analysis we can
 first solve the equations without sensitivity analysis alone. With an interpolatable solution to the original equations the sensitivities associated with each parameter are decoupled from the sensitivities of every other parameter and can be solved independently. Solving these groups of equations sequentially is often significantly faster than solving the equations together. However, by parallelizing the solution of these equations using multithreading it is possible to achieve dramatic speed ups. This approach is not always competitive with adjoint sensitivities as the adjoint approach requires solution of a much smaller system of equations, however, in practice this approach is often more robust especially for large systems.