VolFe 0.4.2__tar.gz → 1.0__tar.gz

{volfe-0.4.2 → volfe-1.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: VolFe
-Version: 0.4.2
+Version: 1.0
 Summary: VolFe
 Author: Pip Liggins, Penny Wieser
 Author-email: Ery Hughes <ery.c.hughes@gmail.com>
@@ -38,7 +38,7 @@ Welcome to VolFe! an open-source framework for calculating melt-vapour equilibri
 [![Documentation Status](https://readthedocs.org/projects/VolFe/badge/?version=latest)](https://VolFe.readthedocs.io/en/latest/?badge=latest)
 
 Read more about the python package in the Earth ArXiv pre-print (and please cite if you use the package!):
-Hughes, E.C., Liggins, P., Wieser, P. and Stolper, E.M., 2024. VolFe: an open-source tool for calculating melt-vapor equilibria including silicate melt, carbon, hydrogen, sulfur, and noble gases. https://doi.org/10.31223/X52X3G
+Hughes, E.C., Liggins, P., Wieser, P. and Stolper, E.M., 2024. VolFe: an open-source Python package for calculating melt-vapor equilibria including silicate melt, carbon, hydrogen, sulfur, and noble gases. https://doi.org/10.31223/X52X3G
 
 For more information and worked examples, see the ReadTheDocs page:
 https://volfe.readthedocs.io/en/latest/

{volfe-0.4.2 → volfe-1.0}/README.md

@@ -8,7 +8,7 @@ Welcome to VolFe! an open-source framework for calculating melt-vapour equilibri
 [![Documentation Status](https://readthedocs.org/projects/VolFe/badge/?version=latest)](https://VolFe.readthedocs.io/en/latest/?badge=latest)
 
 Read more about the python package in the Earth ArXiv pre-print (and please cite if you use the package!):
-Hughes, E.C., Liggins, P., Wieser, P. and Stolper, E.M., 2024. VolFe: an open-source tool for calculating melt-vapor equilibria including silicate melt, carbon, hydrogen, sulfur, and noble gases. https://doi.org/10.31223/X52X3G
+Hughes, E.C., Liggins, P., Wieser, P. and Stolper, E.M., 2024. VolFe: an open-source Python package for calculating melt-vapor equilibria including silicate melt, carbon, hydrogen, sulfur, and noble gases. https://doi.org/10.31223/X52X3G
 
 For more information and worked examples, see the ReadTheDocs page:
 https://volfe.readthedocs.io/en/latest/
@@ -30,4 +30,4 @@ Check VolFe runs on your machine, and that any edits you make haven't broken exi
 ```
 python -m pytest tests
 ```
-or you can use the testing frameworks that come with your IDE (e.g. [VSCode](https://code.visualstudio.com/docs/python/testing), [PyCharm](https://www.jetbrains.com/help/pycharm/testing-your-first-python-application.html)).
+or you can use the testing frameworks that come with your IDE (e.g. [VSCode](https://code.visualstudio.com/docs/python/testing), [PyCharm](https://www.jetbrains.com/help/pycharm/testing-your-first-python-application.html)).

{volfe-0.4.2 → volfe-1.0}/src/VolFe/__init__.py

@@ -1,5 +1,5 @@
 __author__ = "Ery Hughes, Pip Liggins, Penny Wieser"
-__version__ = "0.4.2"
+__version__ = "1.0"
 
 # functions for calculating properties of the melt and gas
 from .melt_gas import *  # noqa F401 F403

{volfe-0.4.2 → volfe-1.0}/src/VolFe/batch_calculations.py

@@ -3276,6 +3276,14 @@ def calc_comp_error_function(
 
 # outputting model options used in the calculation
 def results_isotopes_model_options(models):
+    """Outputs headers and values for model options related to isotopic fractionation.
+
+    Args:
+        models (pandas.DataFrame): Model options.
+
+    Returns:
+        tuple(pandas.DataFrame,pandas.DataFrame): Headers. Values.
+    """
     results_headers = pd.DataFrame(
         [
             [
@@ -3322,6 +3330,16 @@ def results_isotopes_model_options(models):
 
 
 def results_isotopes_gas_melt(comp, run):
+    """Outputs headers and values for melt and vapor composition for isotope
+    fractionation calculations.
+
+    Args:
+        comp (pandas.DataFrame): Composition of the melt and vapor by species, including weight fraction of vapor.
+        run (float): Index of interest.
+
+    Returns:
+        tuple(pandas.DataFrame,pandas.DataFrame): Headers. Values.
+    """
     results_headers = pd.DataFrame(
         [
             [
@@ -3393,6 +3411,21 @@ def results_isotopes_gas_melt(comp, run):
 def results_table_isotopes(
     PT, R_all_species_S, R_m_g_S, R_all_species_C, R_m_g_C, R_all_species_H, R_m_g_H
 ):
+    """Outputs headers and values for isotope ratios for all species and melt and vapor
+    for all elements.
+
+    Args:
+        PT (dict): Pressure (bars) as "P" and temperature ('C) as "T".
+        R_all_species_S (dict): S isotope ratios of all S-bearing species.
+        R_m_g_S (dict): S isotope ratio of melt and vapor.
+        R_all_species_C (dict): C isotope ratios of all C-bearing species.
+        R_m_g_C (dict): C isotope ratio of melt and vapor.
+        R_all_species_H (dict): H isotope ratios of all H-bearing species.
+        R_m_g_H (dict): H isotope ratio of melt and vapor.
+
+    Returns:
+        tuple(pandas.DataFrame,pandas.DataFrame): Headers. Values.
+    """
     results_headers = pd.DataFrame(
         [
             [
@@ -3473,6 +3506,20 @@ def results_table_isotopes(
 def results_table_isotopes_d(
     R_all_species_S, R_m_g_S, R_all_species_C, R_m_g_C, R_all_species_H, R_m_g_H
 ):
+    """Outputs headers and values for isotope ratios for all species and melt and vapor
+    for all elements as delta-values.
+
+    Args:
+        R_all_species_S (dict): S isotope ratios of all S-bearing species.
+        R_m_g_S (dict): S isotope ratio of melt and vapor.
+        R_all_species_C (dict): C isotope ratios of all C-bearing species.
+        R_m_g_C (dict): C isotope ratio of melt and vapor.
+        R_all_species_H (dict): H isotope ratios of all H-bearing species.
+        R_m_g_H (dict): H isotope ratio of melt and vapor.
+
+    Returns:
+        tuple(pandas.DataFrame,pandas.DataFrame): Headers. Values.
+    """
     results_headers = pd.DataFrame(
         [
             [
@@ -3555,6 +3602,21 @@ def calc_isotopes_gassing(
     nr_tol=1.0e-9,
     models=mdv.default_models,
 ):
+    """Calculates the isotopic ratio and delta value of all species and melt and vapor
+    during degassing.
+
+    Args:
+        setup (pandas.DataFrame): Output from a degassing calculation.
+        R_i_d (dict): Bulk isotope ratios as delta values.
+        first_row (int, optional): First row in setup to run. Defaults to 0.
+        last_row (_type_, optional): Last run in setup to run. Defaults to None.
+        nr_step (float, optional): Step-size for Newton-Raphson solver. Defaults to 1.0.
+        nr_tol (float, optional): Tolerance for Newton-Raphson solver. Defaults to 1.0e-9.
+        models (pandas.DataFrame, optional): Model options. Defaults to mdv.default_models.
+
+    Returns:
+        pandas.DataFrame: Results of isotopic fractionation during degassing.
+    """
     if last_row is None:
         last_row = len(setup)
 

{volfe-0.4.2 → volfe-1.0}/src/VolFe/calculations.py

@@ -1184,8 +1184,21 @@ def mf_S_species_old(melt_wf, gas_mf):
     return mf_S
 
 
-# WORK IN PROGRESS
 def mf_S_species(comp):
+    """
+    Calculates weight fraction of S in each sulfur-bearing species in the melt and vapor wrt to
+    total sulfur in the system.
+
+    Parameters
+    ----------
+    comp: pandas.DataFrame
+        Weight fraction by species in the melt and mole fraction in vapor including the wt% of vapor
+
+    Returns
+    -------
+    dict
+        weight fraction (equivalent to mole fraction) of S in each species relative to total S
+    """
     # weight of S in each sulfur-bearing species
     wtg = (float(comp["wt_g_wtpc"].iloc[0])) / 100.0
     wtm = 1.0 - wtg
@@ -1232,8 +1245,21 @@ def mf_S_species(comp):
     return mf
 
 
-# WORK IN PROGRESS
 def mf_C_species(comp):
+    """
+    Calculates weight fraction of C in each carbon-bearing species in the melt and vapor wrt to
+    total carbon in the system.
+
+    Parameters
+    ----------
+    comp: pandas.DataFrame
+        Weight fraction by species in the melt and mole fraction in vapor including the wt% of vapor
+
+    Returns
+    -------
+    dict
+        weight fraction (equivalent to mole fraction) of C in each species relative to total C
+    """
     # weight of C in each carbon-bearing species
     wtg = (float(comp["wt_g_wtpc"].iloc[0])) / 100.0
     wtm = 1.0 - wtg
@@ -1292,42 +1318,22 @@ def mf_C_species(comp):
     return mf
 
 
-(
-    "xgO2_mf",
-    "xgH2_mf",
-    "xgH2O_mf",
-    "xgS2_mf",
-    "xgSO2_mf",
-    "xgH2S_mf",
-    "xgCO2_mf",
-)
-(
-    "xgCO_mf",
-    "xgCH4_mf",
-    "xgOCS_mf",
-    "xgX_mf",
-    "xgC_S_mf",
-)
-(
-    "H2OT_wtpc",
-    "OH_wtpc",
-    "H2Omol_wtpc",
-    "H2_ppmw",
-    "CH4_ppmw",
-    "CO2T_ppmw",
-)
-(
-    "CO2mol_ppmw",
-    "CO32-_ppmw",
-    "CO_ppmw",
-    "S2-_ppmw",
-    "S6+_ppmw",
-    "H2S_ppmw",
-)
-
-
 # WORK IN PROGRESS
 def mf_H_species(comp):
+    """
+    Calculates weight fraction of H in each hydrogen-bearing species in the melt and vapor wrt to
+    total hydrogen in the system.
+
+    Parameters
+    ----------
+    comp: pandas.DataFrame
+        Weight fraction by species in the melt and mole fraction in vapor including the wt% of vapor
+
+    Returns
+    -------
+    dict
+        weight fraction (equivalent to mole fraction) of H in each species relative to total H
+    """
     # weight of H in each hydrogen-bearing species
     wtg = (float(comp["wt_g_wtpc"].iloc[0])) / 100.0
     wtm = 1.0 - wtg
@@ -1751,8 +1757,22 @@ def calc_pure_solubility(PT, melt_wf, models):
     return results
 
 
-# WORK IN PROGRESS
 def calc_isotopes(PT, comp, R, models, nr_step, nr_tol, run=0.0):
+    """Calculates the isotope ratio for all species and melt and vapor for H, S, and C
+    for a single melt-vapor composition.
+
+    Args:
+        PT (dict): Pressure in bars as "P" and temperature in 'C as "T"
+        comp (pandas.DataFrame): Composition of the melt and vapor by species, including weight fraction of vapor.
+        R (dict): Bulk isotope ratio of the system.
+        models (pandas.DataFrame): Model options
+        nr_step (float): Step-size for Newton-Raphson solver.
+        nr_tol (float): Tolerance for Newton-Raphson solver.
+        run (float, optional): Row number in file to run. Defaults to 0.0.
+
+    Returns:
+        tuple(dict,dict,dict,dict,dict,dict): Isotope ratios for all species in S, C, and H. Isotope ratios for melt and vapor in S, C, and H.
+    """
     comp_ = comp[run : run + 1]  # noqa
     R_all_species_C, R_m_g_C = iso.i2s9("C", PT, comp_, R, models, nr_step, nr_tol)
     R_all_species_S, R_m_g_S = iso.i2s9("S", PT, comp_, R, models, nr_step, nr_tol)

{volfe-0.4.2 → volfe-1.0}/src/VolFe/isotopes.py

@@ -17,10 +17,33 @@ import VolFe.model_dependent_variables as mdv
 
 
 def delta_standard(standard, isotope, element):
+    """
+    Get the isotopic ratio reference value for a standard for an element.
+
+
+    Parameters
+    ----------
+    standard: str
+        Standard material of interest: VCDT for S, VPDB for C, and VSMOW for H.
+
+    isotope: float
+        Minor isotope if interest: 34 for S, 13 for C, and 2 for H
+
+    element: str
+        Element of interest: S, C, or H.
+
+    Returns
+    -------
+    float
+        isotope ratio for reference material
+
+    """
     if element == "S":
         if standard == "VCDT":
             if isotope == 34:
-                reference = 1 / 22.6436  # 34S/32S Ding et al. (2001)
+                reference = (
+                    1 / 22.6436
+                )  # 34S/32S Ding et al. (2001) GCA 65(15):2433–2437 https://doi.org/10.1016/S0016-7037(01)00611-1
     elif element == "C":
         if standard == "VPDB":
             if isotope == 13:
@@ -30,11 +53,37 @@ def delta_standard(standard, isotope, element):
     elif element == "H":
         if standard == "VSMOW":
             if isotope == 2:
-                reference = 155.76 / 1.0e6  # 2H/1H Hagemann et al. (1970)
+                reference = (
+                    155.76 / 1.0e6
+                )  # 2H/1H Hagemann et al. (1970) Tellus 22(6):712–715 https://doi.org/10.1111/J.2153-3490.1970.TB00540.X
     return reference
 
 
 def ratio2delta(standard, isotope, element, ratio):
+    """
+    Convert isotope ratio to delta value.
+
+
+    Parameters
+    ----------
+    standard: str
+        Standard material of interest: VCDT for S, VPDB for C, and VSMOW for H.
+
+    isotope: float
+        Minor isotope if interest: 34 for S, 13 for C, and 2 for H
+
+    element: str
+        Element of interest: S, C, or H.
+
+    ratio: float
+        Value of isotope ratio.
+
+    Returns
+    -------
+    float
+        delta-value of isotope ratio
+
+    """
     reference = delta_standard(standard, isotope, element)
     if ratio == "":
         d = ""
@@ -44,12 +93,52 @@ def ratio2delta(standard, isotope, element, ratio):
 
 
 def delta2ratio(standard, isotope, element, d):
+    """
+    Convert delta value to isotope ratio.
+
+
+    Parameters
+    ----------
+    standard: str
+        Standard material of interest: VCDT for S, VPDB for C, and VSMOW for H.
+
+    isotope: float
+        Minor isotope if interest: 34 for S, 13 for C, and 2 for H
+
+    element: str
+        Element of interest: S, C, or H.
+
+    d: float
+        delta-value.
+
+    Returns
+    -------
+    float
+        isotope ratio of delta-value.
+
+    """
     reference = delta_standard(standard, isotope, element)
     ratio = ((d / 1000.0) * reference) + reference
     return ratio
 
 
 def alpha2Delta(a):
+    """
+    Convert alpha fractionation factor to cap-delta fractionation factor.
+
+
+    Parameters
+    ----------
+    isotope: float
+        alpha fractionation factor
+
+
+    Returns
+    -------
+    float
+        cap-delta fractionation factor
+
+    """
     D = 1000.0 * (1.0 - a)
     return D
 
@@ -60,6 +149,33 @@ def alpha2Delta(a):
 
 
 def alpha_gas_using_beta(element, A, B, PT, models):  # using beta values
+    """
+    Calculate alpha fractionation factor from beta-factors.
+
+
+    Parameters
+    ----------
+    element: str
+        Element of interest: S, C, or H.
+
+    A: str
+        Nominator species.
+
+    B: str
+        Denominator species.
+
+    PT: dict
+        Pressure (bars) as "P" and temperature ('C) as "T".
+
+    models: pandas.DataFrame
+        Models options.
+
+    Returns
+    -------
+    float
+        alpha fractionation factor for A-B
+
+    """
     beta_A = mdv.beta_gas(PT, element, A, models)  # gas species A
     beta_B = mdv.beta_gas(PT, element, B, models)  # gas species B
     result = beta_A / beta_B
@@ -72,6 +188,30 @@ def alpha_gas_using_beta(element, A, B, PT, models):  # using beta values
 
 
 def alphas_C(PT, comp, models):
+    """
+    Calculate consistant alpha fractionation factors for C-bearing species (i.e., all
+    relative to the same species). If vapor is present, the species is CO2(v), otherwise
+    it is CO2mol(m) or CO32-(m).
+
+
+    Parameters
+    ----------
+    PT: dict
+        Pressure (bars) as "P" and temperature ('C) as "T".
+
+    comp: pandas.DataFrame
+        Composition of the melt and vapor by species, including weight fraction of
+        vapor.
+
+    models: pandas.DataFrame
+        Models options.
+
+    Returns
+    -------
+    dict
+        alpha fractionation factor for all C-bearing species relative to one species
+
+    """
     if float(comp["wt_g_wtpc"].iloc[0]) > 0.0:  # all alphas against CO2 in the vapor
         A = alpha_gas_using_beta("C", "CO", "CO2", PT, models)  # CO(v)-CO2(v)
         B = alpha_gas_using_beta("C", "CH4", "CO2", PT, models)  # CH4(v)-CO2(v)
@@ -123,6 +263,30 @@ def alphas_C(PT, comp, models):
 
 
 def alphas_H(PT, comp, models):
+    """
+    Calculate consistant alpha fractionation factors for H-bearing species (i.e., all
+    relative to the same species). If vapor is present, the species is H2O(v), otherwise
+    it is H2Omol(m) or OH-(m).
+
+
+    Parameters
+    ----------
+    PT: dict
+        Pressure (bars) as "P" and temperature ('C) as "T".
+
+    comp: pandas.DataFrame
+        Composition of the melt and vapor by species, including weight fraction of
+        vapor.
+
+    models: pandas.DataFrame
+        Models options.
+
+    Returns
+    -------
+    dict
+        alpha fractionation factor for all H-bearing species relative to one species
+
+    """
     if float(comp["wt_g_wtpc"].iloc[0]) > 0.0:  # all alphas against H2O in the vapor
         A = alpha_gas_using_beta("H", "H2", "H2O", PT, models)  # H2(v)
         B = alpha_gas_using_beta("H", "CH4", "H2O", PT, models)  # CH4(v)
@@ -153,9 +317,9 @@ def alphas_H(PT, comp, models):
             A = mdv.alpha_H_H2Ov_H2Om(PT, comp, models)  # H2Omol(m)
             B = c / mdv.alpha_H_H2Ov_OHmm(PT, comp, models)  # OH-(m)
             H_species1, H_species2 = "OH-", "H2Omol"
-        else:  # all alphas against CO2mol in the melt
-            A = mdv.alpha_C_CO2v_CO2m(PT, comp, models)  # OH-(m)
-            B = c / mdv.alpha_H_H2Ov_OHmm(PT, comp, models)  # H2Omol(m)
+        else:  # all alphas against OH- in the melt
+            A = mdv.alpha_H_H2Ov_OHmm(PT, comp, models)  # OH-(m)
+            B = c / mdv.alpha_H_H2Ov_H2Om(PT, comp, models)  # H2Omol(m)
             H_species1, H_species2 = "H2Omol", "OH-"
         C = (a * A) / mdv.alpha_H_H2v_H2m(PT, comp, models)  # H2mol(m)
         D = (b * A) / mdv.alpha_H_CH4v_CH4m(PT, comp, models)  # CH4mol(m)
@@ -179,6 +343,29 @@ def alphas_H(PT, comp, models):
 
 
 def alphas_S(PT, comp, models):  # all alphas against S2-(m)
+    """
+    Calculate consistant alpha fractionation factors for S-bearing species (i.e., all
+    relative to the same species) against *S2-(m).
+
+
+    Parameters
+    ----------
+    PT: dict
+        Pressure (bars) as "P" and temperature ('C) as "T".
+
+    comp: pandas.DataFrame
+        Composition of the melt and vapor by species, including weight fraction of
+        vapor.
+
+    models: pandas.DataFrame
+        Models options.
+
+    Returns
+    -------
+    dict
+        alpha fractionation factor for all S-bearing species relative to *S2-
+
+    """
     C = mdv.alpha_S_H2Sv_S2mm(PT, comp, models)  # H2S(v)
     A = C * alpha_gas_using_beta("S", "S2", "H2S", PT, models)  # S2(v)
     B = C * alpha_gas_using_beta("S", "OCS", "H2S", PT, models)  # OCS(v)
@@ -211,14 +398,16 @@ def simple_isotope_fractionation(D, db):
     Parameters
     ----------
     D: float
-        Float of cap-delta Fractionation factor between vapor and melt in per mil.
+        Cap-delta Fractionation factor between vapor and melt in per mil.
 
     db: float
-        Float initial little-delta isotope value of bulk system in per mil.
+        Initial little-delta isotope value of bulk system in per mil.
+
 
     Returns
     -------
-    Dataframe.
+    pandas.DataFrame
+        Isotopic composition of melt and vapor during closed- and open-system degassing
 
     """
     for n in range(0, 1000, 1):
@@ -252,6 +441,21 @@ def simple_isotope_fractionation(D, db):
 
 
 def newton_raphson(x0, constants, e1, step, eqs, deriv, maxiter=100):
+    """Newton-Raphson solver.
+
+    Args:
+        x0 (float): Initial guess
+        constants (list): Constants required to evaluate equations
+        e1 (float): Tolerance for solver
+        step (float): Step-size for solver
+        eqs (func): Equations to solve
+        deriv (func): Differentials of equations to solve
+        maxiter (int, optional): Maximum number of iterations to try. Defaults to 100.
+
+    Returns:
+        float: Solution
+    """
+
     def dx(x, eqs):
         f_ = eqs(x, constants)
         result = abs(0 - f_)
@@ -291,6 +495,18 @@ def newton_raphson(x0, constants, e1, step, eqs, deriv, maxiter=100):
 
 
 def allocate_species(element, comp, alphas, species_distribution):
+    """Specifies species order for subsequent calculations.
+
+    Args:
+        element (str): Element of interest: H, S, or C.
+        comp (pandas.DataFrame): Composition of the melt and vapor by species, including weight fraction of vapor.
+        alphas (dict): Consistent alpha fractionation factors.
+        species_distribution (dict): Fraction of element in each species.
+
+    Returns:
+        tuple(dict,dict): Dictionary of alphas and species distribution in correct
+        order.
+    """
     if element == "S":
         species = "S2-"
         T_a = species_distribution[species]
@@ -402,6 +618,16 @@ def allocate_species(element, comp, alphas, species_distribution):
 
 
 def rename_output(element, input, comp):
+    """Renames generic output with species names.
+
+    Args:
+        element (str): Element of interest: H, S, or C.
+        input (dict): Dictionary of interest with generic names.
+        comp (pandas.DataFrame): Composition of the melt and vapor by species, including weight fraction of vapor.
+
+    Returns:
+        dict: Species names instead of generic names.
+    """
     output = {}
     if element == "S":
         output["m_S2-"] = input["A"]
@@ -455,6 +681,21 @@ def rename_output(element, input, comp):
 
 
 def i2s9(element, PT, comp, R, models, nr_step, nr_tol):
+    """Calculate the isotope ratios of up to nine species with two isotopes.
+
+    Args:
+        element (str): Element of interest: H, S, or C.
+        PT (dict): Pressure (bars) as "P" and temperature ('C) as "T".
+        comp (pandas.DataFrame): Composition of the melt and vapor by species, including weight fraction of vapor.
+        R (dict): Bulk isotope ratio of the system.
+        models (dict): Model options.
+        nr_step (float): Step-size for Newton-Raphson solver.
+        nr_tol (float): Tolerance for Newton-Raphson solver.
+
+    Returns:
+        tuple(dict,dict): Isotope ratio of each species. Average isotope ratio of melt
+        and vapor.
+    """
     comp.reset_index(drop=True, inplace=True)
     if element == "S":
         if comp.loc[0, "ST_ppmw"] == 0.0:
@@ -673,6 +914,16 @@ def i2s9(element, PT, comp, R, models, nr_step, nr_tol):
 
 
 def av_m_g(element, ratio, constants):
+    """Melt and vapor isotope ratio based on isotope ratio of species within them.
+
+    Args:
+        element (str): Element of interest: H, C, or S.
+        ratio (dict): Isotope ratios of all species
+        constants (tuple(dict,dict,float)): Consistent alpha fractionation factors. Fraction of element in each species. Bulk isotope ratio.
+
+    Returns:
+        dict: Melt and vapor isotope ratio.
+    """
     alphas, species_distribution, R_i = constants
 
     # heavy/total isotope ratio
@@ -769,6 +1020,16 @@ def av_m_g(element, ratio, constants):
 
 
 def iso_initial_guesses(element, R, comp):
+    """Initial guess for Newton-Raphson solver.
+
+    Args:
+        element (str): Element of interest: S, C, or H.
+        R (dict): Isotope ratio of bulk system.
+        comp (pandas.DataFrame): Composition of the melt and vapor by species, including weight fraction of vapor.
+
+    Returns:
+        float: Initial guess for Newton-Raphson solver.
+    """
     if element == "S":
         species_distribution = c.mf_S_species(comp)
         R_i = R["S"]

{volfe-0.4.2 → volfe-1.0}/src/VolFe/model_dependent_variables.py

@@ -111,9 +111,9 @@ default_models = [
     ["alpha_H_H2Sv_H2Sm", "no fractionation"],
     ["alpha_C_CH4v_CH4m", "no fractionation"],
     ["alpha_C_COv_COm", "no fractionation"],
-    ["alpha_C_CO2v_CO2T", "LeePP"],
+    ["alpha_C_CO2v_CO2T", "Lee24"],
     ["alpha_C_CO2v_CO2m", "Blank93"],
-    ["alpha_C_CO2v_CO32mm", "LeePP"],
+    ["alpha_C_CO2v_CO32mm", "Lee24"],
     ["alpha_S_H2Sv_H2Sm", "no fractionation"],
     ["alpha_SO2_SO4", "Fiege15"],
     ["alpha_H2S_S", "Fiege15"],
@@ -5778,7 +5778,37 @@ species = species.set_index("species")
 
 
 def beta_gas(PT, element, species, models):  # beta factors
-    # from Richet et al. (1977)fitted to quadratic equation for 600 < T'C < 1300
+    """
+    Beta isotopic fractionation factors between vapor species containing 32S/34S, 13C/12C, and D/H.
+
+
+    Parameters
+    ----------
+    PT: dict
+        Pressure (bars) as "P" and temperature ('C) as "T".
+
+    element: str
+        Element of interest (H, C, or S).
+
+    species: str
+        Vapor species of interest (H2O, H2, CH4, H2S, CO2, CO, OCS, SO2, S2).
+
+    models: pandas.DataFrame
+        Minimum requirement is index of "beta_factors" and column label of "option".
+
+    Returns
+    -------
+    float
+        Beta factor for element in species of interest
+
+
+    Model options for 'beta_factors'
+    -------------
+    - 'Richet77' [default] Quadratic fits to data in Tables 9, 10, and 13 between 600 < T'C < 1300 of Richet et al. (1977) Ann. Rev. Earth Planet. Sci. 5:65-110 as detailed in Saper et al. (in prep).
+    Only one option available currently, included for future development.
+
+    """
+    # from Richet et al. (1977) fitted to quadratic equation for 600 < T'C < 1300
     if models.loc["beta_factors", "option"] == "Richet77":
         t = 1.0 / (PT["T"] + 273.15)
         if element == "S":
@@ -5818,6 +5848,35 @@ def beta_gas(PT, element, species, models):  # beta factors
 
 
 def alpha_S_H2Sv_S2mm(PT, comp, models):  # alpha for 32/34S between H2S(v) and S2-(m)
+    """
+    Alpha fractionation factor for 32S/34S (R) between H2S(v) and *S2-(m): a = R[H2S(m)]/R[S2-(m)].
+
+
+    Parameters
+    ----------
+    PT: dict
+        Pressure (bars) as "P" and temperature ('C) as "T".
+
+    comp: dict
+        Melt composition (SiO2, TiO2, etc.), not normally used unless model option
+        requires melt composition.
+
+    models: pandas.DataFrame
+        Minimum requirement is index of "alpha_H2S_S" and column label of "option".
+
+    Returns
+    -------
+    float
+        alpha fractionation factor
+
+
+    Model options for "alpha_H2S_S"
+    -------------
+    - 'Fiege15' [default] Eq. (8) from Fiege et al. (2015) Chem. Geol. 393:36-54 https://doi.org/10.1016/j.chemgeo.2014.11.012
+    - 'no fractionation' Treat as no isotopic fractionation between these species
+
+    """
+
     model = models.loc["alpha_H2S_S", "option"]
     if model == "Fiege15":  # Fiege et al. (2015) Chemical Geology eq. 8
         T_K = PT["T"] + 273.15
@@ -5832,6 +5891,35 @@ def alpha_S_H2Sv_S2mm(PT, comp, models):  # alpha for 32/34S between H2S(v) and
 
 
 def alpha_S_SO2v_S6pm(PT, comp, models):  # alpha for 32/34S between SO2(v) and S6+(m)
+    """
+    Alpha fractionation factor for 32S/34S (R) between SO2(v) and S6+(m): a = R[SO2(v)]/R[S6+(m)].
+
+
+    Parameters
+    ----------
+    PT: dict
+        Pressure (bars) as "P" and temperature ('C) as "T".
+
+    comp: dict
+        Melt composition (SiO2, TiO2, etc.), not normally used unless model option
+        requires melt composition.
+
+    models: pandas.DataFrame
+        Minimum requirement is index of "alpha_SO2_SO4" and column label of "option".
+
+    Returns
+    -------
+    float
+        alpha fractionation factor
+
+
+    Model options for "alpha_SO2_SO4"
+    -------------
+    - 'Fiege15' [default] Eq. (9) from Fiege et al. (2015) Chem. Geol. 393:36-54 https://doi.org/10.1016/j.chemgeo.2014.11.012
+    - 'no fractionation' Treat as no isotopic fractionation between these species
+
+    """
+
     model = models.loc["alpha_SO2_SO4", "option"]
     if model == "Fiege15":  # Fiege et al. (2015) Chemical Geology eq. 9
         T_K = PT["T"] + 273.15
@@ -5851,6 +5939,35 @@ def alpha_S_SO2v_S6pm(PT, comp, models):  # alpha for 32/34S between SO2(v) and
 
 
 def alpha_S_H2Sv_H2Sm(PT, comp, models):  # alpha for 32/34S between H2S(v) and H2S(m)
+    """
+    Alpha fractionation factor for 32S/34S (R) between H2S(v) and H2S(m): a = R[H2S(v)]/R[H2S(m)].
+
+
+    Parameters
+    ----------
+    PT: dict
+        Pressure (bars) as "P" and temperature ('C) as "T".
+
+    comp: dict
+        Melt composition (SiO2, TiO2, etc.), not normally used unless model option
+        requires melt composition.
+
+    models: pandas.DataFrame
+        Minimum requirement is index of "alpha_S_H2Sv_H2Sm" and column label of "option".
+
+    Returns
+    -------
+    float
+        alpha fractionation factor
+
+
+    Model options for "alpha_S_H2Sv_H2Sm"
+    -------------
+    - 'no fractionation' Treat as no isotopic fractionation between these species
+    Only one option available currently, included for future development.
+
+    """
+
     model = models.loc["alpha_S_H2Sv_H2Sm", "option"]
     if model == "no fractionation":  #
         a = 1.0
@@ -5865,8 +5982,37 @@ def alpha_S_H2Sv_H2Sm(PT, comp, models):  # alpha for 32/34S between H2S(v) and
 def alpha_C_CO2v_CO32mm(
     PT, comp, models
 ):  # alpha for 13/12C between CO2(v) and CO32-(m)
+    """
+    Alpha fractionation factor for 13C/12C (R) between CO2(v) and CO32-(m): a = R[CO2(v)]/R[CO32-(m)].
+
+
+    Parameters
+    ----------
+    PT: dict
+        Pressure (bars) as "P" and temperature ('C) as "T".
+
+    comp: dict
+        Melt composition (SiO2, TiO2, etc.), not normally used unless model option
+        requires melt composition.
+
+    models: pandas.DataFrame
+        Minimum requirement is index of "alpha_C_CO2v_CO32mm" and column label of "option".
+
+    Returns
+    -------
+    float
+        alpha fractionation factor
+
+
+    Model options for "alpha_C_CO2v_CO32mm"
+    -------------
+    - 'Lee24' [default] Lee et al. (2024) GCA 380:208-219 https://doi.org/10.1016/j.gca.2024.07.015
+    - 'no fractionation' Treat as no isotopic fractionation between these species
+
+    """
+
     model = models.loc["alpha_C_CO2v_CO32mm", "option"]
-    if model == "LeePP":
+    if model == "Lee24":
         a = math.exp(2.9 / 1000.0)
     elif model == "no fractionation":
         a = 1.0
@@ -5876,6 +6022,35 @@ def alpha_C_CO2v_CO32mm(
 def alpha_C_CO2v_CO2m(
     PT, comp, models
 ):  # alpha for 13/12C between CO2(v) and CO2mol(m)
+    """
+    Alpha fractionation factor for 13C/12C (R) between CO2(v) and CO2(m): a = R[CO2(v)]/R[CO2(m)].
+
+
+    Parameters
+    ----------
+    PT: dict
+        Pressure (bars) as "P" and temperature ('C) as "T".
+
+    comp: dict
+        Melt composition (SiO2, TiO2, etc.), not normally used unless model option
+        requires melt composition.
+
+    models: pandas.DataFrame
+        Minimum requirement is index of "alpha_C_CO2v_CO2m" and column label of "option".
+
+    Returns
+    -------
+    float
+        alpha fractionation factor
+
+
+    Model options for "alpha_C_CO2v_CO2m"
+    -------------
+    - 'Blank93' [default] Blank & Stolper (1993) EOS Trans Am Geophys Union 74:347-8
+    - 'no fractionation' Treat as no isotopic fractionation between these species
+
+    """
+
     model = models.loc["alpha_C_CO2v_CO2m", "option"]
     if model == "Blank93":
         a = 1.0
@@ -5884,6 +6059,7 @@ def alpha_C_CO2v_CO2m(
     return a
 
 
+# WORK IN PROGRESS
 def alpha_C_CO2v_CO2Tm(PT, comp, models):  # alpha for 13/12C between CO2(v) and CO2T(m)
     model = models.loc["alpha_C_CO2v_CO2T", "option"]
     if model == "LeePP":
@@ -5894,6 +6070,35 @@ def alpha_C_CO2v_CO2Tm(PT, comp, models):  # alpha for 13/12C between CO2(v) and
 
 
 def alpha_C_COv_COm(PT, comp, models):  # alpha for 13/12C between CO(v) and COmol(m)
+    """
+    Alpha fractionation factor for 13C/12C (R) between CO(v) and COmol(m): a = R[CO(v)]/R[COmol(m)].
+
+
+    Parameters
+    ----------
+    PT: dict
+        Pressure (bars) as "P" and temperature ('C) as "T".
+
+    comp: dict
+        Melt composition (SiO2, TiO2, etc.), not normally used unless model option
+        requires melt composition.
+
+    models: pandas.DataFrame
+        Minimum requirement is index of "alpha_C_COv_COm" and column label of "option".
+
+    Returns
+    -------
+    float
+        alpha fractionation factor
+
+
+    Model options for "alpha_C_COv_COm"
+    -------------
+    - 'no fractionation' Treat as no isotopic fractionation between these species
+    Only one option available currently, included for future development.
+
+    """
+
     model = models.loc["alpha_C_COv_COm", "option"]
     if model == "no fractionation":
         a = 1.0
@@ -5903,6 +6108,35 @@ def alpha_C_COv_COm(PT, comp, models):  # alpha for 13/12C between CO(v) and COm
 def alpha_C_CH4v_CH4m(
     PT, comp, models
 ):  # alpha for 13/12C between CH4(v) and CH4mol(m)
+    """
+    Alpha fractionation factor for 13C/12C (R) between CH4(v) and CH4mol(m): a = R[CH4(v)]/R[CH4mol(m)].
+
+
+    Parameters
+    ----------
+    PT: dict
+        Pressure (bars) as "P" and temperature ('C) as "T".
+
+    comp: dict
+        Melt composition (SiO2, TiO2, etc.), not normally used unless model option
+        requires melt composition.
+
+    models: pandas.DataFrame
+        Minimum requirement is index of "alpha_C_CH4v_CH4m" and column label of "option".
+
+    Returns
+    -------
+    float
+        alpha fractionation factor
+
+
+    Model options for "alpha_C_CH4v_CH4m"
+    -------------
+    - 'no fractionation' Treat as no isotopic fractionation between these species
+    Only one option available currently, included for future development.
+
+    """
+
     model = models.loc["alpha_C_CH4v_CH4m", "option"]
     if model == "no fractionation":
         a = 1.0
@@ -5915,6 +6149,35 @@ def alpha_C_CH4v_CH4m(
 
 
 def alpha_H_H2Ov_H2Om(PT, comp, models):
+    """
+    Alpha fractionation factor for D/H (R) between H2O(v) and H2Omol(m): a = R[H2O(v)]/R[H2Omol(m)].
+
+
+    Parameters
+    ----------
+    PT: dict
+        Pressure (bars) as "P" and temperature ('C) as "T".
+
+    comp: dict
+        Melt composition (SiO2, TiO2, etc.), not normally used unless model option
+        requires melt composition.
+
+    models: pandas.DataFrame
+        Minimum requirement is index of "alpha_H_H2Ov_H2Om" and column label of "option".
+
+    Returns
+    -------
+    float
+        alpha fractionation factor
+
+
+    Model options for "alpha_H_H2Ov_H2Om"
+    -------------
+    - 'Rust04' [default] Rust et al. (2004) Geology 32(4) 349-352 https://doi.org/10.1130/G20388.2
+    - 'no fractionation' Treat as no isotopic fractionation between these species
+
+    """
+
     model = models.loc["alpha_H_H2Ov_H2Om", "option"]
     if model == "no fractionation":
         a = 1.0
@@ -5924,6 +6187,35 @@ def alpha_H_H2Ov_H2Om(PT, comp, models):
 
 
 def alpha_H_H2Ov_OHmm(PT, comp, models):
+    """
+    Alpha fractionation factor for D/H (R) between H2O(v) and OH-(m): a = R[H2O(v)]/R[OH-(m)].
+
+
+    Parameters
+    ----------
+    PT: dict
+        Pressure (bars) as "P" and temperature ('C) as "T".
+
+    comp: dict
+        Melt composition (SiO2, TiO2, etc.), not normally used unless model option
+        requires melt composition.
+
+    models: pandas.DataFrame
+        Minimum requirement is index of "alpha_H_H2Ov_OHmm" and column label of "option".
+
+    Returns
+    -------
+    float
+        alpha fractionation factor
+
+
+    Model options for "alpha_H_H2Ov_OHmm"
+    -------------
+    - 'Rust04' [default] Rust et al. (2004) Geology 32(4) 349-352 https://doi.org/10.1130/G20388.2
+    - 'no fractionation' Treat as no isotopic fractionation between these species
+
+    """
+
     model = models.loc["alpha_H_H2Ov_OHmm", "option"]
     if model == "no fractionation":
         a = 1.0
@@ -5933,6 +6225,35 @@ def alpha_H_H2Ov_OHmm(PT, comp, models):
 
 
 def alpha_H_H2v_H2m(PT, comp, models):  # alpha for D/H between H2(v) and H2(m)
+    """
+    Alpha fractionation factor for 13C/12C (R) between H2(v) and H2mol(m): a = R[H2(v)]/R[H2mol(m)].
+
+
+    Parameters
+    ----------
+    PT: dict
+        Pressure (bars) as "P" and temperature ('C) as "T".
+
+    comp: dict
+        Melt composition (SiO2, TiO2, etc.), not normally used unless model option
+        requires melt composition.
+
+    models: pandas.DataFrame
+        Minimum requirement is index of "alpha_H_H2v_H2m" and column label of "option".
+
+    Returns
+    -------
+    float
+        alpha fractionation factor
+
+
+    Model options for "alpha_H_H2v_H2m"
+    -------------
+    - 'no fractionation' Treat as no isotopic fractionation between these species
+    Only one option available currently, included for future development.
+
+    """
+
     model = models.loc["alpha_H_H2v_H2m", "option"]
     if model == "no fractionation":
         a = 1.0
@@ -5940,6 +6261,35 @@ def alpha_H_H2v_H2m(PT, comp, models):  # alpha for D/H between H2(v) and H2(m)
 
 
 def alpha_H_CH4v_CH4m(PT, comp, models):  # alpha for D/H between CH4(v) and CH4(m)
+    """
+    Alpha fractionation factor for 13C/12C (R) between CH4(v) and CH4mol(m): a = R[CH4(v)]/R[CH4mol(m)].
+
+
+    Parameters
+    ----------
+    PT: dict
+        Pressure (bars) as "P" and temperature ('C) as "T".
+
+    comp: dict
+        Melt composition (SiO2, TiO2, etc.), not normally used unless model option
+        requires melt composition.
+
+    models: pandas.DataFrame
+        Minimum requirement is index of "alpha_H_CH4v_CH4m" and column label of "option".
+
+    Returns
+    -------
+    float
+        alpha fractionation factor
+
+
+    Model options for "alpha_H_CH4v_CH4m"
+    -------------
+    - 'no fractionation' Treat as no isotopic fractionation between these species
+    Only one option available currently, included for future development.
+
+    """
+
     model = models.loc["alpha_H_CH4v_CH4m", "option"]
     if model == "no fractionation":
         a = 1.0
@@ -5947,6 +6297,34 @@ def alpha_H_CH4v_CH4m(PT, comp, models):  # alpha for D/H between CH4(v) and CH4
 
 
 def alpha_H_H2Sv_H2Sm(PT, comp, models):  # alpha for D/H between H2S(v) and H2S(m)
+    """
+    Alpha fractionation factor for 13C/12C (R) between H2S(v) and H2Smol(m): a = R[H2S(v)]/R[H2Smol(m)].
+
+
+    Parameters
+    ----------
+    PT: dict
+        Pressure (bars) as "P" and temperature ('C) as "T".
+
+    comp: dict
+        Melt composition (SiO2, TiO2, etc.), not normally used unless model option
+        requires melt composition.
+
+    models: pandas.DataFrame
+        Minimum requirement is index of "alpha_H_H2Sv_H2Sm" and column label of "option".
+
+    Returns
+    -------
+    float
+        alpha fractionation factor
+
+
+    Model options for "alpha_H_H2Sv_H2Sm"
+    -------------
+    - 'no fractionation' Treat as no isotopic fractionation between these species
+    Only one option available currently, included for future development.
+
+    """
     model = models.loc["alpha_H_H2Sv_H2Sm", "option"]
     if model == "no fractionation":  #
         a = 1.0

{volfe-0.4.2 → volfe-1.0}/src/VolFe.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: VolFe
-Version: 0.4.2
+Version: 1.0
 Summary: VolFe
 Author: Pip Liggins, Penny Wieser
 Author-email: Ery Hughes <ery.c.hughes@gmail.com>
@@ -38,7 +38,7 @@ Welcome to VolFe! an open-source framework for calculating melt-vapour equilibri
 [![Documentation Status](https://readthedocs.org/projects/VolFe/badge/?version=latest)](https://VolFe.readthedocs.io/en/latest/?badge=latest)
 
 Read more about the python package in the Earth ArXiv pre-print (and please cite if you use the package!):
-Hughes, E.C., Liggins, P., Wieser, P. and Stolper, E.M., 2024. VolFe: an open-source tool for calculating melt-vapor equilibria including silicate melt, carbon, hydrogen, sulfur, and noble gases. https://doi.org/10.31223/X52X3G
+Hughes, E.C., Liggins, P., Wieser, P. and Stolper, E.M., 2024. VolFe: an open-source Python package for calculating melt-vapor equilibria including silicate melt, carbon, hydrogen, sulfur, and noble gases. https://doi.org/10.31223/X52X3G
 
 For more information and worked examples, see the ReadTheDocs page:
 https://volfe.readthedocs.io/en/latest/