pipliggins · pipliggins · Nov 16, 2022 · Nov 21, 2022 · Nov 23, 2022 · Dec 4, 2022
diff --git a/docs/Makefile b/docs/Makefile
@@ -0,0 +1,20 @@
+# Minimal makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line, and also
+# from the environment for the first two.
+SPHINXOPTS    ?=
+SPHINXBUILD   ?= sphinx-build
+SOURCEDIR     = .
+BUILDDIR      = _build
+
+# Put it first so that "make" without argument is like "make help".
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+.PHONY: help Makefile
+
+# Catch-all target: route all unknown targets to Sphinx using the new
+# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
+%: Makefile
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
diff --git a/docs/_static/custom.css b/docs/_static/custom.css
@@ -0,0 +1,6 @@
+.math {
+    text-align: left;
+}
+.eqno {
+    float: right;
+}
diff --git a/docs/conf.py b/docs/conf.py
@@ -0,0 +1,32 @@
+# Configuration file for the Sphinx documentation builder.
+#
+# For the full list of built-in configuration values, see the documentation:
+# https://www.sphinx-doc.org/en/master/usage/configuration.html
+
+# -- Project information -----------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
+
+project = 'evo-outgas'
+copyright = '2022, Philippa Liggins'
+author = 'Philippa Liggins'
+release = '1.0.1'
+
+# -- General configuration ---------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
+
+extensions = ['sphinx.ext.todo', 'sphinx.ext.viewcode', 'sphinx.ext.autodoc', 'sphinx.ext.napoleon', 'sphinx.ext.mathjax']
+
+templates_path = ['_templates']
+exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']
+
+numfig = True
+
+
+# -- Options for HTML output -------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
+
+html_theme = 'sphinx_rtd_theme'
+html_static_path = ['_static']
+
+def setup(app):
+    app.add_css_file('custom.css')
diff --git a/docs/evo_doc.rst b/docs/evo_doc.rst
diff --git a/docs/images/SOH_evodc_fugacities.png b/docs/images/SOH_evodc_fugacities.png
diff --git a/docs/images/SOH_evodc_melt.png b/docs/images/SOH_evodc_melt.png
diff --git a/docs/images/c_system.png b/docs/images/c_system.png
diff --git a/docs/images/coh_satp.png b/docs/images/coh_satp.png
diff --git a/docs/images/dc_2evo_comp.png b/docs/images/dc_2evo_comp.png
diff --git a/docs/images/decompression.png b/docs/images/decompression.png
diff --git a/docs/images/eqb_constants.png b/docs/images/eqb_constants.png
diff --git a/docs/images/ery_sulfur_b.png b/docs/images/ery_sulfur_b.png
diff --git a/docs/images/evo_overview.png b/docs/images/evo_overview.png
diff --git a/docs/images/h_with_fo2.pdf b/docs/images/h_with_fo2.pdf
diff --git a/docs/images/model_schematic.pdf b/docs/images/model_schematic.pdf
diff --git a/docs/images/s_curve.pdf b/docs/images/s_curve.pdf
diff --git a/docs/images/table1.png b/docs/images/table1.png
diff --git a/docs/images/table2.png b/docs/images/table2.png
diff --git a/docs/index.rst b/docs/index.rst
@@ -0,0 +1,58 @@
+Welcome to EVo's documentation!
+=======================================
+
+EVo is a volcanic outgassing model for COHSN elements.
+
+The current implementation has been developed in Python 3 and tested on Windows, Linux and macOS.
+
+Installation/Usage:
+*******************
+
+EVo can be used through local installation, either through a CLI or a webapp.
+
+To install locally, EVo must be downloaded from GitHub using
+::
+
+   git clone git@github.com:pipliggins/EVo.git
+
+into the project directory where you wish to use EVo. EVo must then be locally pip-installed:
+::
+
+   cd EVO
+   python -m pip install ".[streamlit]"
+
+From this point, EVo can either be imported into your python scripts as a regular module using
+::
+
+   install evo
+
+and run using
+::
+
+   evo.main('chem_file', 'env_file', 'output_options_file')
+
+Or EVo can be run directly from the terminal from inside the `evo` directory:
+::
+
+   cd EVO/evo
+   python dgs.py input/chem.yaml input/env.yaml --output input/output.yaml
+
+Alternatively you can interact with EVo using the webapp interface, by running:
+::
+
+   cd EVO/webapp
+   streamlit run streamlit-app.py
+
+
+.. toctree::
+   :maxdepth: 2
+   :caption: Contents:
+
+   evo_doc
+
+Indices and tables
+==================
+
+* :ref:`genindex`
+* :ref:`modindex`
+* :ref:`search`
diff --git a/docs/make.bat b/docs/make.bat
@@ -0,0 +1,35 @@
+@ECHO OFF
+
+pushd %~dp0
+
+REM Command file for Sphinx documentation
+
+if "%SPHINXBUILD%" == "" (
+	set SPHINXBUILD=sphinx-build
+)
+set SOURCEDIR=.
+set BUILDDIR=_build
+
+%SPHINXBUILD% >NUL 2>NUL
+if errorlevel 9009 (
+	echo.
+	echo.The 'sphinx-build' command was not found. Make sure you have Sphinx
+	echo.installed, then set the SPHINXBUILD environment variable to point
+	echo.to the full path of the 'sphinx-build' executable. Alternatively you
+	echo.may add the Sphinx directory to PATH.
+	echo.
+	echo.If you don't have Sphinx installed, grab it from
+	echo.https://www.sphinx-doc.org/
+	exit /b 1
+)
+
+if "%1" == "" goto help
+
+%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
+goto end
+
+:help
+%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
+
+:end
+popd
diff --git a/docs/requirements.txt b/docs/requirements.txt
@@ -0,0 +1,2 @@
+sphinx==5.3.0
+sphinx_rtd_theme
diff --git a/pyproject.toml b/pyproject.toml
@@ -26,12 +26,13 @@ dependencies = ["numpy>=1.21.0",
   "scipy>=1.7.0",
   "matplotlib>=3.4.2",
   "mpmath>=1.2.1",
-  "pyyaml",
   "ruamel.yaml",
   "pandas>=2.1.0",]
 
 [project.optional-dependencies]
 dev = ["ruff", "pre-commit"]
+doc = ["sphinx == 5.3.0"]
+web = ["streamlit"]
 test = ["pytest"]
 
 [project.urls]

diff --git a/src/evo/__init__.py b/src/evo/__init__.py
@@ -1,9 +1,14 @@
 """
 EVo
+
 A Python model for volcanic degassing, using the equilibrium constants and mass balance
 method.
 """
 
-from evo.dgs import run_evo as run_evo
+# ----------------- IMPORTS ----------------- #
+from evo.dgs import run_evo
+from evo.multirun import multirun
 
-__all__ = ["run_evo"]
+__version__ = "1.0.2"
+__author__ = "Philippa Liggins"
+__all__ = ["run_evo", "multirun"]
diff --git a/src/evo/multirun.py b/src/evo/multirun.py
@@ -3,10 +3,12 @@
 from shutil import copyfile
 
 import numpy as np
-import yaml
+import ruamel.yaml
 
 from evo.dgs import run_evo
 
+ryaml = ruamel.yaml.YAML()
+
 
 def amend_env(file, **kwargs):
     """
@@ -25,7 +27,7 @@ def amend_env(file, **kwargs):
     """
 
     with open(file) as f:
-        env_doc = yaml.full_load(f)
+        env_doc = ryaml.load(f)
 
     for param, val in kwargs.items():
         if isinstance(val, np.float64):
@@ -34,7 +36,7 @@ def amend_env(file, **kwargs):
             env_doc[param] = val
 
     with open("multirun.yaml", "w") as f:
-        yaml.dump(env_doc, f)
+        ryaml.dump(env_doc, f)
 
 
 def multirun(**kwargs):

diff --git a/src/evo/readin.py b/src/evo/readin.py
@@ -5,7 +5,7 @@
 # ------------------------------------------------------------------------
 
 import numpy as np
-import yaml
+import ruamel.yaml
 from numpy import exp, log10
 from numpy import log as ln
 
@@ -18,6 +18,8 @@
 # bundled scripts
 from evo.dgs_classes import Gas, Melt, Molecule, Output, RunDef, ThermoSystem
 
+ryaml = ruamel.yaml.YAML()
+
 # ------------------------------------------------------------------------
 # FUNCTION DEFINTIONS
 # ------------------------------------------------------------------------
@@ -44,7 +46,7 @@ def readin_env(f):
     """
 
     # creates a dictionary of the environment parameters from env.yaml
-    x = yaml.full_load(f)
+    x = ryaml.load(f)
 
     # setup run definitions
     run = RunDef()
@@ -115,7 +117,7 @@ def readin_chem(f, run, sys):
         The instantiated Melt class
     """
 
-    data = yaml.full_load(f)
+    data = ryaml.load(f)
 
     ele_names = []
     chems = []
@@ -194,7 +196,7 @@ def readin_output(f):
         The instantiated Output class
     """
 
-    x = yaml.full_load(f)
+    x = ryaml.load(f)
 
     out = Output()
     out.set_outputs(x)

diff --git a/webapp/chem.yaml b/webapp/chem.yaml
@@ -0,0 +1,10 @@
+SIO2: 47.95
+TIO2: 1.67
+AL2O3: 17.32
+FEO: 10.24
+MNO: 0.17
+MGO: 5.76
+CAO: 10.93
+NA2O: 3.45
+K2O: 1.99
+P2O5: 0.51
diff --git a/webapp/env.yaml b/webapp/env.yaml
@@ -0,0 +1,103 @@
+#run type
+COMPOSITION: basalt
+
+#RUN_TYPE: choose either closed or open
+RUN_TYPE: closed
+
+# Runs only one pressure step, the starting pressure.
+SINGLE_STEP: false
+# Search for the saturation point based on melt composition; ignores P_Start and WgT
+FIND_SATURATION: false
+# Finds saturation pressure based on volatile contents as atomic mass fractions (H, S, N, C) + fO2
+ATOMIC_MASS_SET: false
+
+GAS_SYS: oh
+FE_SYSTEM: true
+S_SAT_WARN: false
+
+# model parameters
+T_START: 1473.15
+P_START: 3000.0
+P_STOP: 1.0
+DP_MIN: 0.1
+DP_MAX: 100.0
+MASS: 100.0
+WgT: 1.0e-05
+
+# Fraction of gas phase lost at each pressure step during open system degassing
+LOSS_FRAC: 0.9999
+
+# select models
+DENSITY_MODEL: spera2000
+# Relate fo2 to Fe2/Fe3 ratio; pick from kc1991 (Kress & Carmicheal 1991), r2013 (Righter et al., 2013))
+FO2_MODEL: kc1991
+# Rock buffer definitions, options: frost1991; 
+FMQ_MODEL: frost1991
+
+# select solubility laws from options. Some options do not include OH-, CO3, CH4 species.
+# OH system models, pick from: burguisser2015 (H2O only); 
+H2O_MODEL: burguisser2015
+# H2 model, pick from: burguisser2015 (ONLY USE TO COMPARE TO DCOMPRESS; ERROR!); gaillard2003
+H2_MODEL: gaillard2003
+# C models, pick from: burguisser2015 (CO2 & CO3); eguchi2018 (CO2, CO3 & graphite)
+C_MODEL: burguisser2015
+# CO model, pick either armstrong2015, or None (preferred for higher fO2 cases above ~ IW+1)
+CO_MODEL: armstrong2015
+# CH4 model, pick either ardia2013, or None (preferred for higher fO2 cases above ~ IW+1)
+CH4_MODEL: ardia2013
+# S models, pick from: sulfide capacity: oneill2002, oneill2020;  sulfate capacity: nash2019  ; SCSS: liu2007
+SULFIDE_CAPACITY: oneill2020
+SULFATE_CAPACITY: nash2019
+SCSS: liu2007
+# N model, pick from: libourel2003 (N2 only)
+N_MODEL: libourel2003
+
+# fO2 can be set relative to a mineral buffer (NNO, FMQ or IW), as an absolute value, or through the FeO/Fe2O3 ratio in the chem.yaml file.
+# Or it can be set implicitly in the OH system by initialising using fH2 rather than fO2.
+FO2_buffer_SET: true
+FO2_buffer: FMQ
+FO2_buffer_START: 0.0
+
+# SET TOTAL VOLATILES AS ATOMIC MASS FRACTIONS (ppm)
+
+ATOMIC_H: 0.0
+ATOMIC_C: 0.0
+ATOMIC_S: 0.0
+ATOMIC_N: 0.0
+
+# VOLATILE SETTING OPTIONS:
+# OH: Either fO2 (see above) OR fH2
+# COH: Pick 2 from the fO2 (see above), fH2, fH2O or wtH2O. You cannot set up with just fO2 and fH2, or specify both fH2O and WtH2O.
+# SOH: Pick 2 from the fO2 (see above), fH2, fH2O or wtH2O. You cannot set up with just fO2 and fH2, or specify both fH2O and WtH2O
+# COHS: Pick 3 from the fO2 (see above), fH2, fH2O, wtH2O fCO2 or WtCO2. You cannot set up with just fO2 and fH2, or specify either both fH2O and WtH2O or both fCO2 and WtCO2
+# COHSN: Pick 4 from the fO2 (see above), fH2, fH2O, wtH2O fCO2 or WtCO2, plus WtN. You cannot set up with just fO2 and fH2, or specify either both fH2O and WtH2O or both fCO2 and WtCO2
+
+# To select an option, switch the boolean specified by 'set' to 'true' and provide a value in the corresponding 'start' option.
+# Switch all other volatile setting options to false to avoid triggering an error.
+
+# select initial volatile compositions, either as gas fugacities
+
+FH2_SET: false
+FH2_START: 0.0
+
+FH2O_SET: false
+FH2O_START: 0.0
+
+FCO2_SET: false
+FCO2_START: 0.0
+
+# or melt wt fractions -  a wt FRACTION still dissolved in the melt at the starting pressure (NOT WHEN EVERYTHING IS DISSOLVED), so 0.1 wt% = 0.001
+WTH2O_SET: false
+WTH2O_START: 0.0
+
+WTCO2_SET: false
+WTCO2_START: 0.0
+
+SULFUR_SET: false
+SULFUR_START: 0.0
+
+NITROGEN_SET: false
+NITROGEN_START: 0.0
+
+GRAPHITE_SATURATED: false
+GRAPHITE_START: 0.0
diff --git a/webapp/evo_logo.png b/webapp/evo_logo.png
diff --git a/webapp/output.yaml b/webapp/output.yaml
@@ -0,0 +1,7 @@
+# Graphical output selection
+
+Plt_melt_species: True
+Plt_gas_species_wt: False
+Plt_gas_species_mol: True
+Plt_gas_fraction: True
+Plt_fo2_dFMQ: False