VESIcal Code Documentation

Modules

VESIcal

Model()

class VESIcal.model_classes.Model[source]

The model object implements a volatile solubility model. It is composed of the methods needed to evaluate VESIcal.calculate_dissolved_volatiles(), VESIcal.calculate_equilibrium_fluid_comp(), and calculate_saturation_pressure(). The fugacity and activity models for the volatiles species must be specified, defaulting to ideal.

check_calibration_range(parameters, report_nonexistance=True)[source]

Checks whether the given parameters are within the ranges defined by the CalibrationRange objects for the model and its fugacity and activity models. An empty string will be returned if all parameters are within the calibration range. If a parameter is not within the calibration range, a description of the problem will be returned in the string.

Parameters:

parameters dict – Dictionary keys are the names of the parameters to be checked, e.g., pressure temperature, SiO2, etc. Values are the values of each parameter. A complete set need not be given.

Returns:

String description of any parameters falling outside of the calibration range.

Return type:

str

get_calibration_range()[source]

Returns a string describing the calibration ranges defined by the CalibrationRange objects for each model, and its associated fugacity and activity models.

Returns:

String description of the calibration range objects.

Return type:

str

get_calibration_values(variable_names)[source]

Returns the values stored as the calibration range for the given variable(s). However, for checks where there is a single value- i.e. cr_GreaterThan or crf_LessThan, the logical operation will remain a mystery until someone figures out an elegant way of communicating it.

Parameters:

variable_names str or list – The name(s) of the variables you want the calibration ranges for.

Returns:

A list of values or tuples for the calibration ranges in the order given.

Return type:

list

FugacityModel()

class VESIcal.fugacity_models.FugacityModel[source]

The fugacity model object is for implementations of fugacity models for individual volatile species, though it may depend on the mole fraction of other volatile species. It contains all the methods required to calculate the fugacity at a given pressure and mole fraction.

abstract fugacity(pressure, **kwargs)[source]

activity_model()

class VESIcal.activity_models.activity_model[source]

The activity model object is for implementing activity models for volatile species in melts. It contains all the methods required to evaluate the activity.

abstract activity(X, **kwargs)[source]

Calculate()

class VESIcal.calculate_classes.Calculate(sample, model='MagmaSat', silence_warnings=False, **kwargs)[source]

The Calculate object is a template for implementing user-friendly methods for running calculations using the volatile solubility models. All Calculate methods have a common workflow- sample is read in, preprocessed, the calculation is performed, the calibration range is checked, and the results stored.

calculate_dissolved_volatiles(Calculate)
class VESIcal.calculate_classes.calculate_dissolved_volatiles(sample, model='MagmaSat', silence_warnings=False, **kwargs)[source]

Calculates the dissolved volatile concentration using a chosen model (default is MagmaSat). Using this interface will preprocess the sample, run the calculation, and then check the calibration ranges. All parameters required by the chosen model must be passed.

Parameters:
  • sample (Sample class) – The rock composition as a Sample object.

  • pressure (float) – Total pressure in bars.

  • model (string or Model object) – Model to be used. If using one of the default models, this can be the string corresponding to the model in the default_models dict.

  • silence_warnings bool – If set to True, no warnings will be raised automatically when calibration checks fail.

  • preprocess_sample bool – If True (default), the sample will be preprocessed according to the preprocessing operations within the models. If you obtain unexpected results, try setting to False.

Returns:

Calculate object, access results by fetching the result property. Dissolved volatile concentrations (in wt%), in order (CO2, H2O, if using a mixed fluid default model).

Return type:

Calculate object

return_default_units(sample, calc_result, **kwargs)[source]

Checkes the default units set for the sample_class.Sample object and returns the result of a calculation in those units.

Parameters:
  • sample (Sample class) – The rock composition as a Sample object.

  • calc_result (dict or float) – Result of a calculate_dissolved_volatiles() calculation on a sample.

calculate_equilibrium_fluid_comp(Calculate)
class VESIcal.calculate_classes.calculate_equilibrium_fluid_comp(sample, model='MagmaSat', silence_warnings=False, **kwargs)[source]

Calculates the equilibrium fluid composition using a chosen model (default is MagmaSat). Using this interface will preprocess the sample, run the calculation, and then check the calibration ranges. All parameters required by the chosen model must be passed.

Parameters:
  • sample (Sample class) – The rock composition as a Sample object.

  • pressure (float or None) – Total pressure in bars. If None, the saturation pressure will be used.

  • model (string or Model object) – Model to be used. If using one of the default models, this can be the string corresponding to the model in the default_models dict.

  • silence_warnings bool – If set to True, no warnings will be raised automatically when calibration checks fail.

  • preprocess_sample bool – If True (default), the sample will be preprocessed according to the preprocessing operations within the models. If you obtain unexpected results, try setting to False.

Returns:

Calculate object, access result by fetching the result property. Mole fractions of each volatile species, in order (CO2, then H2O, if using a mixed-fluid default model).

Return type:

Calculate object

calculate_saturation_pressure(Calculate)
class VESIcal.calculate_classes.calculate_saturation_pressure(sample, model='MagmaSat', silence_warnings=False, **kwargs)[source]

Calculates the pressure at which a fluid will be saturated, given the dissolved volatile concentrations. Using this interface will preprocess the sample, run the calculation, and then check the calibration ranges. All parameters required by the chosen model must be passed.

Parameters:
  • sample (Sample class) – The rock composition as a Sample object.

  • model (string or Model object) – Model to be used. If using one of the default models, this can be the string corresponding to the model in the default_models dict.

  • silence_warnings bool – If set to True, no warnings will be raised automatically when calibration checks fail.

  • preprocess_sample bool – If True (default), the sample will be preprocessed according to the preprocessing operations within the models. If you obtain unexpected results, try setting to False.

Returns:

Calculate object, access results by fetching the result property. The saturation pressure in bars as a float.

Return type:

Calculate object

calculate_isobars_and_isopleths(Calculate)
class VESIcal.calculate_classes.calculate_isobars_and_isopleths(sample, model='MagmaSat', silence_warnings=False, **kwargs)[source]

Calculates isobars and isopleths using a chosen model (default is MagmaSat). Using this interface will preprocess the sample, run the calculation, and then check the calibration ranges. All parameters required by the chosen model must be passed.

Parameters:
  • sample (Sample class) – The rock composition as a Sample object.

  • pressure_list (list) – List of all pressure values at which to calculate isobars, in bars.

  • isopleth_list (list) – OPTIONAL: Default value is None, in which case only isobars will be calculated. List of all fluid compositions in mole fraction (of the first species in self.volatile_species) at which to calcualte isopleths. Values can range from 0 to 1.

  • points (int) – The number of points in each isobar and isopleth. Default value is 101.

  • model (string or Model object) – Model to be used. If using one of the default models, this can be the string corresponding to the model in the default_models dict.

  • silence_warnings bool – If set to True, no warnings will be raised automatically when calibration checks fail.

  • preprocess_sample bool – If True (default), the sample will be preprocessed according to the preprocessing operations within the models. If you obtain unexpected results, try setting to False.

Returns:

Calculate object, access results by fetching the result property. If isopleth_list is not None, two objects will be returned, one with the isobars and the second with the isopleths. If return_dfs is True, two pandas DataFrames will be returned with column names ‘Pressure’ or ‘XH2O_fl’, ‘H2O_liq’, and ‘CO2_liq’. If return_dfs is False, two lists of numpy arrays will be returned. Each array is an individual isobar or isopleth, in the order passed via pressure_list or isopleth_list. The arrays are the concentrations of H2O and CO2 in the liquid, in the order of the species in self.volatile_species.

Return type:

Calculate object

calculate_degassing_path(Calculate)
class VESIcal.calculate_classes.calculate_degassing_path(sample, model='MagmaSat', silence_warnings=False, **kwargs)[source]

Calculates the dissolved volatiles in a progressively degassing sample.

Parameters:
  • sample (Sample class) – The rock composition as a Sample object.

  • pressure string, float, int, list, or numpy array – Defaults to ‘saturation’, the calculation will begin at the saturation pressure. If a number is passed as either a float or int, this will be the starting pressure. If a list of numpy array is passed, the pressure values in the list or array will define the degassing path, i.e. final_pressure and steps variables will be ignored. Units are bars.

  • fractionate_vapor float – What proportion of vapor should be removed at each step. If 0.0 (default), the degassing path will correspond to closed-system degassing. If 1.0, the degassing path will correspond to open-system degassing.

  • final_pressure float – The final pressure on the degassing path, in bars. Ignored if a list or numpy array is passed as the pressure variable. Default is 1 bar.

  • steps int – The number of steps in the degassing path. Ignored if a list or numpy array are passed as the pressure variable.

  • model (string or Model object) – Model to be used. If using one of the default models, this can be the string corresponding to the model in the default_models dict.

  • silence_warnings bool – If set to True, no warnings will be raised automatically when calibration checks fail.

  • preprocess_sample bool – If True (default), the sample will be preprocessed according to the preprocessing operations within the models. If you obtain unexpected results, try setting to False.

Returns:

Calculate object, access results by fetching the result property. A DataFrame with columns ‘Pressure’, ‘H2O_liq’, ‘CO2_liq’, ‘H2O_fl’, ‘CO2_fl’, and ‘FluidProportion_wt’, is returned. Dissolved volatiles are in wt%, the proportions of volatiles in the fluid are in mole fraction.

Return type:

Calculate object

calculate_liquid_density(Calculate)
class VESIcal.thermo.thermo_calculate_classes.calculate_liquid_density(sample, silence_warnings=False, **kwargs)[source]

Calculates the density of the liquid using the DensityX model. Using this interface will preprocess the sample, run the calculation, and then check the calibration ranges. All parameters required by the chosen model must be passed.

Parameters:
  • sample (Sample class) – The rock composition as a Sample object.

  • pressure (float) – Total pressure in bars.

  • temperature (float) – Temperature in degrees C.

  • silence_warnings bool – If set to True, no warnings will be raised automatically when calibration checks fail.

  • preprocess_sample bool – If True (default), the sample will be preprocessed according to the preprocessing operations within the models. If you obtain unexpected results, try setting to False.

Returns:

Calculate object, access results by fetching the result property. Density in g/L.

Return type:

Calculate object

calculate_liquid_viscosity(Calculate)
class VESIcal.thermo.thermo_calculate_classes.calculate_liquid_viscosity(sample, silence_warnings=False, **kwargs)[source]

Calculates the density of the liquid using the Giordano et al. (2008) model. Using this interface will preprocess the sample, run the calculation, and then check the calibration ranges. All parameters required by the chosen model must be passed.

Parameters:
  • sample (Sample class) – The rock composition as a Sample object.

  • temperature (float) – Temperature in degrees C.

  • silence_warnings bool – If set to True, no warnings will be raised automatically when calibration checks fail.

  • preprocess_sample bool – If True (default), the sample will be preprocessed according to the preprocessing operations within the models. If you obtain unexpected results, try setting to False.

Returns:

Calculate object, access results by fetching the result property. Log viscosity in Pa*s.

Return type:

Calculate object

batchfile module

Functions defined in VESIcal.batchfile

BatchFile()

class VESIcal.batchfile.BatchFile(filename, sheet_name=0, file_type='excel', units='wtpt_oxides', label='Label', default_normalization='none', default_units='wtpt_oxides', dataframe=None, **kwargs)[source]

A batch file with sample names and oxide compositions

Variables:
  • filename (str) – Path to the batch file, e.g., “my_file.xlsx”. This always needs to be passed, even if the user is passing a pandas DataFrame rather than an batch file. If passing a DataFrame, filename should be set to None. File can be excel file (.xlsx) or .csv.

  • sheet_name (str) –

    OPTIONAL. For Excel files. Default value is 0 which gets the first sheet in the batch spreadsheet file. This implements the pandas. read_excel() sheet_name parameter. But functionality to read in more than one sheet at a time (e.g., pandas.read_excel(sheet_name=None)) is not yet imlpemented in VESIcal. From the pandas 1.0.4 documentation:

    Available cases: - Defaults to 0: 1st sheet as a DataFrame - 1: 2nd sheet as a DataFrame - “Sheet1”: Load sheet with name “Sheet1”

  • file_type (str) – OPTIONAL. Default is ‘excel’, which denotes that passed file has extension .xlsx. Other option is ‘csv’, which denotes that the passed file has extension .csv.

  • units (str) – OPTIONAL. Default is ‘wtpt_oxides’. String defining whether the oxide composition is given in wt percent (“wtpt_oxides”, which is the default), mole oxides (mol_oxides) or mole cations (mol_cations).

  • default_normalization (None or str) –

    The type of normalization to apply to the data by default. One of: - None (no normalization) - ‘standard’ (default): Normalizes an input composition to 100%. - ‘fixedvolatiles’: Normalizes major element oxides to 100 wt%,

    including volatiles. The volatile wt% will remain fixed, whilst the other major element oxides are reduced proportionally so that the total is 100 wt%.

    • ’additionalvolatiles’: Normalises major element oxide wt% to 100%, assuming it is volatile-free. If H2O or CO2 are passed to the function, their un-normalized values will be retained in addition to the normalized non-volatile oxides, summing to >100%.

  • str (default_units) – The type of composition to return by default, one of: - wtpt_oxides (default) - mol_oxides - mol_cations

  • label (str) – OPTIONAL. Default is ‘Label’. Name of the column within the passed file referring to sample names.

  • dataframe (pandas DataFrame) – OPTIONAL. Default is None in which case this argument is ignored. This argument is used when the user wishes to turn a pandas DataFrame into an BatchFile object, for example when user data is already in python rather than being imported from a file. In this case set dataframe equal to the dataframe object being passed in. If using this option, pass None to filename.

get_composition(species=None, normalization=None, units=None, exclude_volatiles=False, asBatchFile=False)[source]

Returns a pandas DataFrame containing the compositional information for all samples in the BatchFile object

Parameters:
  • species (NoneType or str) – The name of the oxide or cation to return the concentration of. If NoneType (default) the whole composition of each sample will be returned. If an oxide is passed, the value in wtpt will be returned unless units is set to ‘mol_oxides’, even if the default units for the sample object are mol_oxides. If an element is passed, the concentration will be returned as mol_cations, unless ‘mol_singleO’ is specified as units, even if the default units for the sample object are mol_singleO. Unless normalization is specified in the method call, none will be applied.

  • normalization (NoneType or str) – The type of normalization to apply to the data. One of: - ‘none’ (no normalization) - ‘standard’ (default): Normalizes an input composition to 100%. - ‘fixedvolatiles’: Normalizes major element oxides to 100 wt%,

    including volatiles. The volatile wt% will remain fixed, whilst the other major element oxides are reduced proportionally so that the total is 100 wt%.

    • ‘additionalvolatiles’: Normalises major element oxide wt% to 100%, assuming it is volatile-free. If H2O or CO2 are passed to the function, their un-normalized values will be retained in addition to the normalized non-volatile oxides, summing to >100%.

    If NoneType is passed the default normalization option will be used (self.default_normalization).

  • units (NoneType or str) – The units of composition to return, one of: - wtpt_oxides (default) - mol_oxides - mol_cations - mol_singleO If NoneType is passed the default units option will be used (self.default_type).

  • exclude_volatiles bool – If True, volatiles will be excluded from the returned composition, prior to normalization and conversion.

  • asBatchFile (bool) – If True, returns a BatchFile object. If False, returns a pandas.DataFrame object.

Returns:

All sample information.

Return type:

pandas.DataFrame or BatchFile object

get_data(normalization=None, units=None, asBatchFile=False)[source]

Returns all data stored in a BatchFile object (both compositional and other data). To return only the compositional data, use get_composition().

Parameters:
  • normalization (NoneType or str) – The type of normalization to apply to the data. One of: - ‘none’ (no normalization) - ‘standard’ (default): Normalizes an input composition to 100%. - ‘fixedvolatiles’: Normalizes major element oxides to 100 wt%,

    including volatiles. The volatile wt% will remain fixed, whilst the other major element oxides are reduced proportionally so that the total is 100 wt%.

    • ‘additionalvolatiles’: Normalises major element oxide wt% to 100%, assuming it is volatile-free. If H2O or CO2 are passed to the function, their un-normalized values will be retained in addition to the normalized non-volatile oxides, summing to >100%.

    If NoneType is passed the default normalization option will be used (self.default_normalization).

  • units (NoneType or str) – The units of composition to return, one of: - wtpt_oxides (default) - mol_oxides - mol_cations - mol_singleO

    If NoneType is passed the default units option will be used (self.default_type).

  • asBatchFile (bool) – If True, returns a BatchFile object. If False, returns a pandas.DataFrame object.

Returns:

All sample information.

Return type:

pandas.DataFrame or BatchFile object

get_sample_composition(samplename, species=None, normalization=None, units=None, asSampleClass=False)[source]

Returns oxide composition of a single sample from a user-imported file as a dictionary

Parameters:
  • samplename (string) – Name of the desired sample

  • normalization (NoneType or str) – The type of normalization to apply to the data. One of: - ‘none’ (no normalization) - ‘standard’ (default): Normalizes an input composition to 100%. - ‘fixedvolatiles’: Normalizes major element oxides to 100 wt%,

    including volatiles. The volatile wt% will remain fixed, whilst the other major element oxides are reduced proportionally so that the total is 100 wt%.

    • ‘additionalvolatiles’: Normalises major element oxide wt% to 100%, assuming it is volatile-free. If H2O or CO2 are passed to the function, their un-normalized values will be retained in addition to the normalized non-volatile oxides, summing to >100%.

    If NoneType is passed the default normalization option will be used (self.default_normalization).

  • units (NoneType or str) – The units of composition to return, one of: - wtpt_oxides (default) - mol_oxides - mol_cations - mol_singleO If NoneType is passed the default units option will be used (self.default_type).

  • asSampleClass (bool) – If True, the sample composition will be returned as a sample class, with default options. In this case any normalization instructions will be ignored.

Returns:

Composition of the sample as oxides

Return type:

dictionary, float, or sample_class.Sample object

save_csv(filenames, calculations, **kwargs)[source]

Saves data calculated by the user in batch processing mode to a comma-separated values (csv) file. Mirros the pandas.to_csv() method. Any argument that can be passed to pandas.csv() can be passed here. One csv file will be saved for each calculation passed.

Parameters:
  • filenames (string or list of strings) – Name of the file. Extension (.csv) should be passed along with the name itself, all in quotes (e.g., ‘myfile.csv’). The number of calculations passed must match the number of filenames passed. If passing more than one, should be passed as a list.

  • calculations (pandas DataFrame or list of pandas DataFrames) – A single variable or list of variables containing calculated outputs from any of the core BatchFile functions: calculate_dissolved_volatiles, calculate_equilibrium_fluid_comp, and calculate_saturation_pressure.

Returns:

  • Creates and saves a CSV file or files with data from each

  • calculation saved to its own file.

save_excel(filename, calculations, sheet_names=None)[source]

Saves data calculated by the user in batch processing mode (using the BatchFile class methods) to an organized Excel file, with the original user data plus any calculated data.

Parameters:
  • filename (string) – Name of the file. Extension (.xlsx) should be passed along with the name itself, all in quotes (e.g., ‘myfile.xlsx’).

  • calculations (pandas DataFrame or list of pandas DataFrames) – A single DataFrame or list of DataFrames (e.g., calculated outputs from any of the core BatchFile functions: calculate_dissolved_volatiles, calculate_equilibrium_fluid_comp, and calculate_saturation_pressure). If None, only the original user data will be saved.

  • sheet_names (None, string, or list) – OPTIONAL. Default value is None. Allows user to set the name of the sheet or sheets written to the Excel file.

Returns:

  • Creates and saves an Excel file with data from each calculation

  • saved to its own sheet.

set_default_normalization(default_normalization)[source]

Set the default type of normalization to use with the get_composition() method.

Parameters:

default_normalization (str) – The type of normalization to apply to the data. One of: - ‘none’ (no normalization) - ‘standard’ (default): Normalizes an input composition to 100%. - ‘fixedvolatiles’: Normalizes major element oxides to 100 wt%,

including volatiles. The volatile wt% will remain fixed, whilst the other major element oxides are reduced proportionally so that the total is 100 wt%.

  • ‘additionalvolatiles’: Normalises major element oxide wt% to 100%, assuming it is volatile-free. If H2O or CO2 are passed to the function, their un-normalized values will be retained in addition to the normalized non-volatile oxides, summing to >100%.

set_default_units(default_units)[source]

Set the default units of composition to return when using the get_composition() method.

Parameters:

default_units str – The type of composition to return, one of: - wtpt_oxides (default) - mol_oxides - mol_cations

try_set_index(dataframe, label)[source]

Method to handle setting the index column in an BatchFile object. If no column is passed that matches the default index name, then this method will attempt to choose the ‘best’ column that the user might want to serve as an index column.

Parameters:
  • dataframe (pandas DataFrame)

  • label (str) – Name of the column within the passed Excel file referring to sample names.

status_bar()

VESIcal.batchfile.status_bar()[source]

Various styles of status bars that display the progress of a calculation within a loop

BatchFile_from_DataFrame()

class VESIcal.batchmodel.BatchFile_from_DataFrame(dataframe, units='wtpt_oxides', label=None)[source]

Transforms any pandas DataFrame object into a VESIcal BatchFile object.

Parameters:

Same as batchfile.BatchFile_from_DataFrame()

Return type:

VESIcal.BatchFile object

Sample

Functions defined in VESIcal.sample_class

Sample()

class VESIcal.sample_class.Sample(composition, units='wtpt_oxides', default_normalization='none', default_units='wtpt_oxides')[source]

The sample class stores compositional information for samples, and contains methods for normalization and other compositional calculations.

change_composition(new_composition, units='wtpt_oxides', inplace=True)[source]

Change the concentration of some component of the composition.

If the units are moles, they are read as moles relative to the present composition, i.e. if you wish to double the moles of MgO, if the present content is 0.1 moles, you should provide {‘MgO’:0.2}. The composition will then be re-normalized. If the original composition was provided in un-normalized wt%, the unnormalized total will be lost.

Parameters:
  • new_composition (dict or pandas.Series) – The components to be updated.

  • units (str) – The units of new_composition. Should be one of: - wtpt_oxides (default) - mol_oxides - mol_cations

  • inplace (bool) – If True the object will be modified in place. If False, a copy of the Sample object will be created, modified, and then returned.

Returns:

Modified Sample class.

Return type:

Sample class

check_cation(cation)[source]

Check whether the sample composition contains the given cation.

Parameters:

cation (str) – The element name to check the composition for.

Returns:

Whether the composition contains the given element, or not.

Return type:

bool

check_oxide(oxide)[source]

Check whether the sample composition contains the given oxide.

Parameters:

oxide (str) – Oxide name to check composition for.

Returns:

Whether the composition contains the given oxide, or not.

Return type:

bool

delete_oxide(oxide, inplace=True)[source]

Allows user to remove a given oxide from the Sample composition

Parameters:
  • oxide (str or list) – Name or names of the oxide(s) to remove.

  • inplace (bool) – If True the object will be modified in place. If False, a copy of the Sample object will be created, modified, and then returned.

Returns:

Modified Sample class.

Return type:

Sample class

get_composition(species=None, normalization=None, units=None, exclude_volatiles=False, asSampleClass=False, oxide_masses={})[source]

Returns the composition in the format requested, normalized as requested.

Parameters:
  • species (NoneType or str) – The name of the oxide or cation to return the concentration of. If NoneType (default) the whole composition will be returned as a pandas.Series. If an oxide is passed, the value in wtpt will be returned unless units is set to ‘mol_oxides’, even if the default units for the sample object are mol_oxides. If an element is passed, the concentration will be returned as mol_cations, unless ‘mol_singleO’ is specified as units, even if the default units for the sample object are mol_singleO. Unless normalization is specified in the method call, none will be applied.

  • normalization (NoneType or str) – The type of normalization to apply to the data. One of: - ‘none’ (no normalization) - ‘standard’ (default): Normalizes an input composition to 100%. - ‘fixedvolatiles’: Normalizes major element oxides to 100 wt%, including volatiles.

    The volatile wt% will remain fixed, whilst the other major element oxides are reduced proportionally so that the total is 100 wt%.

    • ‘additionalvolatiles’: Normalises major element oxide wt% to 100%, assuming it is volatile-free. If H2O or CO2 are passed to the function, their un-normalized values will be retained in addition to the normalized non-volatile oxides, summing to >100%.

    If NoneType is passed the default normalization option will be used (self.default_normalization).

  • units (NoneType or str) – The units of composition to return, one of: - wtpt_oxides (default) - mol_oxides - mol_cations - mol_singleO If NoneType is passed the default units option will be used (self.default_type).

  • exclude_volatiles bool – If True, volatiles will be excluded from the returned composition, prior to normalization and conversion.

  • asSampleClass (bool) – If True, the sample composition will be returned as a sample class, with default options. In this case any normalization instructions will be ignored.

  • oxide_masses (dict) – Specify here any oxide masses that should be changed from the VESIcal default. This might be useful for recreating other implementations of models that use slightly different molecular masses. The default values in VESIcal are given to 3 dp.

Returns:

The sample composition, as specified.

Return type:

pandas.Series, float, or Sample class

get_formulaweight(exclude_volatiles=False)[source]

Converts major element oxides in wt% to the formula weight (on a 1 oxygen basis).

Parameters:

exclude_volatiles bool – If True the formula weight will be calculated without volatiles

Returns:

The formula weight of the composition, on a one oxygen basis.

Return type:

float

set_default_normalization(default_normalization)[source]

Set the default type of normalization to use with the get_composition() method.

Parameters:

default_normalization (str) – The type of normalization to apply to the data. One of: - ‘none’ (no normalization) - ‘standard’ (default): Normalizes an input composition to 100%. - ‘fixedvolatiles’: Normalizes major element oxides to 100 wt%, including volatiles.

The volatile wt% will remain fixed, whilst the other major element oxides are reduced proportionally so that the total is 100 wt%.

  • ‘additionalvolatiles’: Normalises major element oxide wt% to 100%, assuming it is volatile-free. If H2O or CO2 are passed to the function, their un-normalized values will be retained in addition to the normalized non-volatile oxides, summing to >100%.

set_default_units(default_units)[source]

Set the default units of composition to return when using the get_composition() method.

Parameters:

default_units str – The type of composition to return, one of: - wtpt_oxides (default) - mol_oxides - mol_cations - mol_singleO

Fugacity Models

fugacity_idealgas(FugacityModel)

class VESIcal.fugacity_models.fugacity_idealgas[source]

An instance of FugacityModel for an ideal gas.

fugacity(pressure, X_fluid=1.0, **kwargs)[source]

Returns the fugacity of an ideal gas, i.e., the partial pressure.

Parameters:
  • pressure float – Total pressure of the system, in bars.

  • X_fluid float – The mole fraction of the species in the vapour phase.

Returns:

Fugacity (partial pressure) in bars

Return type:

float

fugacity_KJ81_co2(FugacityModel)

class VESIcal.fugacity_models.fugacity_KJ81_co2[source]

Implementation of the Kerrick and Jacobs (1981) EOS for mixed fluids. This class will return the properties of the CO2 component of the mixed fluid.

fugacity(pressure, temperature, X_fluid, **kwargs)[source]

Calculates the fugacity of CO2 in a mixed CO2-H2O fluid. Above 1050C, it assumes H2O and CO2 do not interact, as the equations are not defined beyond this point.

Parameters:
  • pressure float – Total pressure of the system in bars.

  • temperature float – Temperature in degC

  • X_fluid float – Mole fraction of CO2 in the fluid.

Returns:

fugacity of CO2 in bars

Return type:

float

lnPhi_mix(P, T, X_fluid)[source]

Calculates the natural log of the fugacity coefficient for CO2 in a mixed CO2-H2O fluid. Uses Eq (27) of Kerrick and Jacobs (1981).

Parameters:
  • P float – Total pressure in bars.

  • T float – Temperature in degC

  • X_fluid float – The mole fraction of CO2 in the fluid.

Returns:

The natural log of the fugacity coefficient for CO2 in a mixed fluid.

Return type:

float

root_volume(v, P, T, X_fluid)[source]

Returns the difference between the lhs and rhs of Eq (28) of Kerrick and Jacobs (1981). For use with a root finder to obtain the volume of the mixed fluid.

Parameters:
  • v float – Guess for the volume

  • P float – Total system pressure in bars.

  • T float – Temperature in degC

  • X_fluid float – Mole fraction of CO2 in the fluid.

Returns:

Difference between lhs and rhs of Eq (28) of Kerrick and Jacobs (1981), in bars.

Return type:

float

root_volume_h(v, P, T)[source]

Returns the difference between the lhs and rhs of Eq (14) of Kerrick and Jacobs (1981). For use with a root solver to identify the volume of a pure H2O fluid.

Parameters:
  • v float – Guess for the volume

  • P float – Total pressure in bars.

  • T float – Temperature in degC.

Returns:

The difference between the lhs and rhs of Eq (14) of Kerrick and Jacobs (1981), in bars.

Return type:

float

volume(P, T, X_fluid)[source]

Calculates the volume of the mixed fluid, by solving Eq (28) of Kerrick and Jacobs (1981) using scipy.root_scalar.

Parameters:
  • P float – Total pressure of the system, in bars.

  • T float – Temperature in degC

  • X_fluid float – Mole fraction of CO2 in the fluid

Returns:

Volume of the mixed fluid.

Return type:

float

volume_h(P, T)[source]

Calculates the volume of a pure H2O fluid, by solving Eq (14) of Kerrick and Jacobs (1981).

Parameters:
  • P float – Total pressure in bars.

  • T float – Temperature in degC.

Return type:

Difference between lhs and rhs of Eq (14) of Kerrick and Jacobs (1981), in bars.

fugacity_KJ81_h2o(FugacityModel)

class VESIcal.fugacity_models.fugacity_KJ81_h2o[source]

Implementation of the Kerrick and Jacobs (1981) EOS for mixed fluids. This class will return the properties of the H2O component of the mixed fluid.

fugacity(pressure, temperature, X_fluid, **kwargs)[source]

Calculates the fugacity of H2O in a mixed CO2-H2O fluid. Above 1050C, it assumes H2O and CO2 do not interact, as the equations are not defined beyond this point.

Parameters:
  • pressure float – Total pressure of the system in bars.

  • temperature float – Temperature in degC

  • X_fluid float – Mole fraction of H2O in the fluid.

Returns:

fugacity of H2O in bars

Return type:

float

lnPhi_mix(P, T, X_fluid)[source]

Calculates the natural log of the fugacity coefficient for H2O in a mixed CO2-H2O fluid. Uses Eq (27) of Kerrick and Jacobs (1981).

Parameters:
  • P float – Total pressure in bars.

  • T float – Temperature in degC

  • X_fluid float – The mole fraction of H2O in the fluid.

Returns:

The natural log of the fugacity coefficient for H2O in a mixed fluid.

Return type:

float

root_volume(v, P, T, X_fluid)[source]

Returns the difference between the lhs and rhs of Eq (28) of Kerrick and Jacobs (1981). For use with a root finder to obtain the volume of the mixed fluid.

Parameters:
  • v float – Guess for the volume

  • P float – Total system pressure in bars.

  • T float – Temperature in degC

  • X_fluid float – Mole fraction of H2O in the fluid.

Returns:

Difference between lhs and rhs of Eq (28) of Kerrick and Jacobs (1981), in bars.

Return type:

float

root_volume_c(v, P, T)[source]

Returns the difference between the lhs and rhs of Eq (14) of Kerrick and Jacobs (1981). For use with a root solver to identify the volume of a pure H2O fluid.

Parameters:
  • v float – Guess for the volume

  • P float – Total pressure in bars.

  • T float – Temperature in degC.

Returns:

The difference between the lhs and rhs of Eq (14) of Kerrick and Jacobs (1981), in bars.

Return type:

float

volume(P, T, X_fluid)[source]

Calculates the volume of the mixed fluid, by solving Eq (28) of Kerrick and Jacobs (1981) using scipy.root_scalar.

Parameters:
  • P float – Total pressure of the system, in bars.

  • T float – Temperature in degC

  • X_fluid float – Mole fraction of H2O in the fluid

Returns:

Volume of the mixed fluid.

Return type:

float

volume_c(P, T)[source]

Calculates the volume of a pure CO2 fluid, by solving Eq (14) of Kerrick and Jacobs (1981).

Parameters:
  • P float – Total pressure in bars.

  • T float – Temperature in degC.

Return type:

Difference between lhs and rhs of Eq (14) of Kerrick and Jacobs (1981), in bars.

fugacity_ZD09_co2(FugacityModel)

class VESIcal.fugacity_models.fugacity_ZD09_co2[source]

Implementation of the Zhang and Duan (2009) fugacity model for pure CO2 fluids.

Vm(Vm, P, T)[source]

Function to use for solving for the parameter Vm, defined by eqn (8) of Zhang and Duan (2009). Called by scipy.fsolve in the fugacity method.

Parameters:
  • Vm float – Guessed value of Vm

  • P float – Pressure in MPa

  • T float – Temperature in K

Returns:

Difference between (rearranged) LHS and RHS of eqn (8) of Zhang and Duan (2009).

Return type:

float

fugacity(pressure, temperature, X_fluid=1.0, **kwargs)[source]

Calculates the fugacity of a pure CO2 fluid, or a mixed fluid assuming ideal mixing. Implements eqn (14) of Zhang and Duan (2009).

Parameters:
  • pressure float – Pressure in bars

  • temperature float – Temperature in degC

  • X_fluid float – Mole fraction of CO2 in the fluid. Default is 1.0.

Returns:

Fugacity of CO2, standard state 1 bar.

Return type:

float

fugacity_RedlichKwong(FugacityModel)

class VESIcal.fugacity_models.fugacity_RedlichKwong[source]

Implementation of the Redlich Kwong EoS Code derived from http://people.ds.cam.ac.uk/pjb10/thermo/pure.html - Patrick J. Barrie 30 October 2003.

fugacity(pressure, temperature, X_fluid=1.0, species='H2O', **kwargs)[source]

Calculates the fugacity of H2O in a mixed H2O-CO2 fluid using the universal relationships: P_i = f_i/gamma_i = (fpure_i * Xfluid_i) / gamma_i See Iacovino (2015) EPSL for further explanation.

gamma(pressure, temperature, species)[source]

Calculates fugacity coefficients.

Parameters:
  • temperature (fload) – Temperature in degrees C.

  • pressure (float) – Pressure in bars.

  • species (str) – Choose which species to calculate. Options are ‘H2O’ and ‘CO2’.

Returns:

Fugacity coefficient for passed species.

Return type:

float

fugacity_HollowayBlank(FugacityModel)

class VESIcal.fugacity_models.fugacity_HollowayBlank[source]

Implementation of the Modified Redlich Kwong presented in Holloway and Blank (1994) Reviews in Mineralogy and Geochemistry vol. 30. Originally written in Quickbasic. CO2 calculations translated to Matlab by Chelsea Allison and translated to python by K. Iacovino for VESIcal. H2O calculations translated to VisualBasic by Gordon M. Moore and translated to python by K. Iacovino for VESIcal.

REDKW(BP, A2B)[source]

The RK routine. A routine to calculate compressibility factor and fugacity coefficient with the Redlich-Kwong equation following Edmister (1968). This solution for supercritical fluid.

Parameters:
  • BP (float) – B parameter sum from RKCALC

  • A2B (float) – A parameter sum from RKCALC

Returns:

XLNFP (fugacity coefficient?)

Return type:

float

RKCALC(temperature, pressure, species)[source]

Calculation of pure gas MRK properties following Holloway 1981, 1987

Parameters:
  • temperature (float) – Temperature in degrees K.

  • pressure (float) – Pressure in atmospheres.

Returns:

Natural log of the fugacity of a pure gas.

Return type:

float

Saxena(TK, pb)[source]

High pressure corresponding states routines from Saxena and Fei (1987) GCA vol. 51, 783-791.

Parameters:
  • TK (float) – Temperature in K.

  • pb (float) – Pressure in bars.

Returns:

XLNF, Natural log of the ratio F(P)/F(4000 bar)

Return type:

float

fugacity(pressure, temperature, species, **kwargs)[source]

Calculates fugacity.

Parameters:
  • temperature (float) – Temperature in degrees C.

  • pressure (float) – Pressure in bars.

  • species (str) – Choose which species to calculate. Options are ‘H2O’ and ‘CO2’.

Returns:

Fugacity coefficient for passed species

Return type:

float

fugacity_HB_co2(FugacityModel)

class VESIcal.fugacity_models.fugacity_HB_co2[source]

Implementation of the Holloway and Blank (1994) Modified Redlich Kwong EoS for CO2.

fugacity(pressure, temperature, X_fluid=1.0, **kwargs)[source]

fugacity_HB_h2o(FugacityModel)

class VESIcal.fugacity_models.fugacity_HB_h2o[source]

Implementation of the Holloway and Blank (1994) Modified Redlich Kwong EoS for H2O.

fugacity(pressure, temperature, X_fluid=1.0, **kwargs)[source]

Activity Models

activity_idealsolution(activity_model)

class VESIcal.activity_models.activity_idealsolution[source]

Implements an ideal solution activity model, i.e. it will always return the mole fraction.

activity(X)[source]

The activity of the component in an ideal solution, i.e., it will return the mole fraction.

Parameters:

X float – The mole fraction of the species in the solution.

Returns:

The activity of the species in the solution, i.e., the mole fraction.

Return type:

float

Pure Fluid Models

ShishkinaCarbon(Model)

class VESIcal.models.shishkina.carbon[source]

Implementation of the Shishkina et al. (2014) carbon solubility model, as a Model class.

PiStar(sample)[source]

Shishkina et al. (2014) Eq (11)

Calculates the Pi* parameter for use in calculating CO2 solubility.

Parameters:

sample (Sample class) – The magma composition stored in a Sample class.

Returns:

The value of the Pi* compositional parameter.

Return type:

float

calculate_dissolved_volatiles(pressure, sample, X_fluid=1, **kwargs)[source]

Calculates the dissolved CO2 concentration in wt%, using equation (13) of Shishkina et al. (2014).

Parameters:
  • pressure (float) – (Total) pressure in bars.

  • sample (Sample class) – Magma composition.

  • X_fluid (float) – The mol-fraction of the fluid that is CO2. Default is 1, i.e. a pure CO2 fluid.

Returns:

The dissolved CO2 concentration in wt%.

Return type:

float

calculate_equilibrium_fluid_comp(pressure, sample, **kwargs)[source]

Returns 1.0 if a pure CO2 fluid is saturated. Returns 0.0 if a pure CO2 fluid is undersaturated.

Parameters:
  • pressure float – The total pressure of the system in bars.

  • sample Sample class – Magma major element composition.

Returns:

1.0 if CO2-fluid saturated, 0.0 otherwise.

Return type:

float

calculate_saturation_pressure(sample, **kwargs)[source]

Calculates the pressure at which a pure CO2 fluid is saturated, for the given sample composition and CO2 concentration. Calls the scipy.root_scalar routine, which makes repeated calls to the calculate_dissolved_volatiles method.

Parameters:

sample Sample class – Magma major element composition.

Returns:

Saturation pressure in bar

Return type:

float

root_saturation_pressure(pressure, sample, kwargs)[source]

Function called by scipy.root_scalar when finding the saturation pressure using calculate_saturation_pressure.

Parameters:
  • pressure float – Pressure guess in bars

  • sample Sample class – Magma major element composition.

  • kwargs dictionary – Additional keyword arguments supplied to calculate_saturation_pressure. Might be required for the fugacity or activity models.

Returns:

The differece between the dissolved CO2 at the pressure guessed, and the CO2 concentration passed in the sample variable.

Return type:

float

ShishkinaWater(Model)

class VESIcal.models.shishkina.water[source]

Implementation of the Shishkina et al. (2014) H2O solubility model as a Model class.

calculate_dissolved_volatiles(pressure, sample, X_fluid=1.0, **kwargs)[source]

Calculates the dissolved H2O concentration using Eqn (9) of Shishkina et al. (2014).

Parameters:
  • pressure float – Total pressure in bars

  • sample Sample class – Magma major element composition.

  • X_fluid float – The mol fraction of H2O in the fluid

Returns:

The H2O concentration in wt%

Return type:

float

calculate_equilibrium_fluid_comp(pressure, sample, **kwargs)[source]

Returns 1.0 if a pure H2O fluid is saturated. Returns 0.0 if a pure H2O fluid is undersaturated.

Parameters:
  • pressure float – The total pressure of the system in bars.

  • sample Sample class – Magma major element composition (including H2O).

Returns:

1.0 if H2O-fluid saturated, 0.0 otherwise.

Return type:

float

calculate_saturation_pressure(sample, **kwargs)[source]

Calculates the pressure at which a pure H2O fluid is saturated, for the given sample composition and H2O concentration. Calls the scipy.root_scalar routine, which makes repeated calls to the calculate_dissolved_volatiles method.

Parameters:

sample Sample class – Magma major element composition (including H2O).

Returns:

Saturation pressure in bar

Return type:

float

root_saturation_pressure(pressure, sample, kwargs)[source]

Function called by scipy.root_scalar when finding the saturation pressure using calculate_saturation_pressure.

Parameters:
  • pressure float – Pressure guess in bars

  • sample Sample class – Magma major element composition (including H2O).

  • kwargs dictionary – Additional keyword arguments supplied to calculate_saturation_pressure. Might be required for the fugacity or activity models.

Returns:

The differece between the dissolved H2O at the pressure guessed, and the H2O concentration passed in the sample variable.

Return type:

float

DixonCarbon(Model)

class VESIcal.models.dixon.carbon[source]

Implementation of the Dixon (1997) carbon solubility model, as a Model class.

XCO3_Std(sample)[source]

Calculates the mole fraction of CO3(2-) dissolved when in equilibrium with pure CO2 vapour at 1200C and 1 bar, using Eq (8) of Dixon (1997).

Parameters:

sample Sample class – Magma major element chemistry.

Returns:

Mole fraction of CO3(2-) dissolved at 1 bar and 1200C.

Return type:

float

calculate_dissolved_volatiles(pressure, sample, X_fluid=1.0, **kwargs)[source]

Calculates the dissolved CO2 concentration using Eqn (3) of Dixon (1997).

Parameters:
  • pressure float – Total pressure in bars.

  • sample Sample class – Magma major element composition.

  • X_fluid float – The mol fraction of CO2 in the fluid.

Returns:

The CO2 concentration in wt%.

Return type:

float

calculate_equilibrium_fluid_comp(pressure, sample, **kwargs)[source]

Returns 1.0 if a pure H2O fluid is saturated. Returns 0.0 if a pure H2O fluid is undersaturated.

Parameters:
  • pressure float – The total pressure of the system in bars.

  • sample Sample class – Magma major element composition.

Returns:

1.0 if CO2-fluid saturated, 0.0 otherwise.

Return type:

float

calculate_saturation_pressure(sample, X_fluid=1.0, **kwargs)[source]

Calculates the pressure at which a pure CO2 fluid is saturated, for the given sample composition and CO2 concentration. Calls the scipy.root_scalar routine, which makes repeated called to the calculate_dissolved_volatiles method.

Parameters:
  • sample Sample class – Magma major element composition (including CO2).

  • X_fluid float – The mole fraction of CO2 in the fluid. Default is 1.0.

Returns:

Calculated saturation pressure in bars.

Return type:

float

molfrac_molecular(pressure, sample, X_fluid=1.0, **kwargs)[source]

Calculates the mole fraction of CO3(-2) dissolved when in equilibrium with a pure CO2 fluid at 1200C, using Eqn (1) of Dixon (1997).

Parameters:
  • pressure float – Total pressure in bars.

  • sample Sample class – Magma major element composition.

  • X_fluid float – Mole fraction of CO2 in the fluid.

Returns:

Mole fraction of CO3(2-) dissolved.

Return type:

float

root_saturation_pressure(pressure, sample, kwargs)[source]

The function called by scipy.root_scalar when finding the saturation pressure using calculate_saturation_pressure.

Parameters:
  • pressure float – Total pressure in bars.

  • sample Sample class – Magma major element composition.

Returns:

The difference between the dissolved CO2 the pressure guessed, and the CO2 concentration passed in the sample variable.

Return type:

float

DixonWater(Model)

class VESIcal.models.dixon.water[source]

Implementation of the Dixon (1997) water solubility model, as a Model class.

XH2O_Std(sample)[source]

Calculates the mole fraction of molecular H2O dissolved when in equilibrium with pure H2O vapour at 1200C and 1 bar, using Eq (9) of Dixon (1997).

Parameters:

sample Sample class – Magma major element composition.

Returns:

Mole fraction of molecular water dissolved at 1 bar and 1200C.

Return type:

float

XOH(pressure, sample, X_fluid=1.0, **kwargs)[source]

Calculates the mole fraction of hydroxyl groups dissolved by solving Eq (4) of Dixon (1997). Calls scipy.root_scalar to find the root of the XOH_root method.

Parameters:
  • pressure float – Total pressure in bars.

  • sample pandas Series or dict – Major element oxides in wt%.

  • X_fluid float – Mole fraction of H2O in the fluid.

Returns:

Mole fraction of hydroxyl groups dissolved.

Return type:

float

XOH_root(XOH, XH2O)[source]

Method called by scipy.root_scalar when finding the saturation pressure using the calculate_saturation_pressure method. Implements Eq (4) of Dixon (1997).

Parameters:
  • XOH float – Guess for the mole fraction of hydroxyl groups dissolved in melt.

  • XH2O float – Mole fraction of molecular water dissolved in melt.

Returns:

The difference between the RHS and LHS of Eq (4) of Dixon (1997) for the guessed value of XOH.

Return type:

float

calculate_dissolved_volatiles(pressure, sample, X_fluid=1.0, **kwargs)[source]

Calculates the dissolved H2O concentration using Eqns (5) and (6) of Dixon (1997).

Parameters:
  • pressure float – Total pressure in bars.

  • sample Sample class – Magma major element composition.

  • X_fluid float – The mol fraction of H2O in the fluid.

Returns:

The H2O concentration in wt%.

Return type:

float

calculate_equilibrium_fluid_comp(pressure, sample, **kwargs)[source]

Returns 1.0 if a pure H2O fluid is saturated. Returns 0.0 if a pure H2O fluid is undersaturated.

Parameters:
  • pressure float – The total pressure of the system in bars.

  • sample Sample class – Magma major element composition (including H2O).

Returns:

1.0 if H2O-fluid saturated, 0.0 otherwise.

Return type:

float

calculate_saturation_pressure(sample, X_fluid=1.0, **kwargs)[source]

Calculates the pressure at which a pure H2O fluid is saturated, for the given sample composition and H2O concentration. Calls the scipy.root_scalar routine, which makes repeated called to the calculate_dissolved_volatiles method.

Parameters:
  • sample Sample class – Magma major element composition (including H2O).

  • X_fluid float – The mole fraction of H2O in the fluid. Default is 1.0.

Returns:

Calculated saturation pressure in bars.

Return type:

float

molfrac_molecular(pressure, sample, X_fluid=1.0, **kwargs)[source]

Calculates the mole fraction of molecular H2O dissolved when in equilibrium with a pure H2O fluid at 1200C, using Eqn (2) of Dixon (1997).

Parameters:
  • pressure float – Total pressure in bars.

  • sample Sample class – Magma major element composition.

  • X_fluid float – Mole fraction of H2O in the fluid.

Returns:

Mole fraction of molecular H2O dissolved.

Return type:

float

root_saturation_pressure(pressure, sample, kwargs)[source]

Function called by scipy.root_scalar when finding the saturation pressure using calculate_saturation_pressure.

Parameters:
  • pressure float – Pressure guess in bars

  • sample pandas Series or dict – Major elements in wt% (normalized to 100%), including H2O.

  • kwargs dictionary – Additional keyword arguments supplied to calculate_saturation_pressure. Might be required for the fugacity or activity models.

Returns:

The differece between the dissolved H2O at the pressure guessed, and the H2O concentration passed in the sample variable.

Return type:

float

IaconoMarzianoCarbon(Model)

class VESIcal.models.iaconomarziano.carbon[source]

Implementation of the Iacono-Marziano et al. (2012) carbon solubility model, as a Model class.

NBO_O(sample, coeffs='webapp')[source]

Calculates NBO/O according to Appendix A.1. of Iacono-Marziano et al. (2012). NBO/O is calculated on either a hydrous or anhyrous basis, as set when initialising the Model class.

Parameters:
  • sample pandas Series or dict – Major element oxides in wt% (including H2O if using the hydrous parameterization).

  • coeffs str – One of: - ‘webapp’ or ‘manuscript’ to include H2O in NBO/O - ‘anhydrous’ to exclude H2O from NBO/O

Returns:

NBO/O.

Return type:

float

calculate_dissolved_volatiles(pressure, temperature, sample, X_fluid=1, coeffs='webapp', **kwargs)[source]

Calculates the dissolved CO2 concentration, using Eq (12) of Iacono-Marziano et al. (2012). If using the hydrous parameterization, it will use the scipy.root_scalar routine to find the root of the root_dissolved_volatiles method.

Parameters:
  • pressure float – Total pressure in bars.

  • temperature float – Temperature in C

  • sample Sample class – Magma major element composition.

  • X_fluid float – Mole fraction of H2O in the fluid. Default is 1.0.

  • coeffs str – Which set of coefficients should be used for H2O calculations: - ‘webapp’ (default) for the hydrous NBO/O parameterisation coefficients used in the

    Iacono-Marziano webapp.

    • ‘manuscript’ for the hydrous NBO/O parameterisation coefficients given in the Iacono-Marziano et al. (2012) manuscript.

    • ‘anhydrous’ for the anhydrous NBO/O parameterisation coefficients given in the Iacono-Marziano et al. (2012) manuscript.

Returns:

Dissolved H2O concentration in wt%.

Return type:

float

calculate_equilibrium_fluid_comp(pressure, temperature, sample, **kwargs)[source]

Returns 1.0 if a pure CO2 fluid is saturated. Returns 0.0 if a pure CO2 fluid is undersaturated.

Parameters:
  • pressure float – The total pressure of the system in bars.

  • temperature float – The temperature of the system in C.

  • sample Sample class – Magma major element composition (including H2O).

Returns:

1.0 if CO2-fluid saturated, 0.0 otherwise.

Return type:

float

calculate_saturation_pressure(temperature, sample, **kwargs)[source]

Calculates the pressure at which a pure CO2 fluid is saturated, for the given sample composition and CO2 concentration. Calls the scipy.root_scalar routine, which makes repeated called to the calculate_dissolved_volatiles method.

Parameters:
  • temperature float – The temperature of the system in C.

  • sample Sample class – Magma major element composition (including CO2).

Returns:

Calculated saturation pressure in bars.

Return type:

float

root_saturation_pressure(pressure, temperature, sample, kwargs)[source]

Function called by scipy.root_scalar when finding the saturation pressure using calculate_saturation_pressure.

Parameters:
  • pressure float – Pressure guess in bars

  • temperature float – The temperature of the system in C.

  • sample Sample class – Magma major element composition, including CO2.

  • kwargs dictionary – Additional keyword arguments supplied to calculate_saturation_pressure. Might be required for the fugacity or activity models.

Returns:

The differece between the dissolved CO2 at the pressure guessed, and the CO2 concentration passed in the sample variable.

Return type:

float

IaconoMarzianoWater(Model)

class VESIcal.models.iaconomarziano.water[source]

Implementation of the Iacono-Marziano et al. (2012) water solubility model, as a Model class. Three calibrations are provided- the one incorporating the H2O content as a parameter (hydrous), and the one that does not (anhydrous), in addition to the coefficient values given incorrect and do not align with the web versions of the model. Which model should be used is specified when the methods are called. The default choice is the hydrous model.

NBO_O(sample, coeffs='webapp')[source]

Calculates NBO/O according to Appendix A.1. of Iacono-Marziano et al. (2012). NBO/O is calculated on either a hydrous or anhyrous basis, as set when initialising the Model class.

Parameters:
  • sample pandas Series or dict – Major element oxides in wt% (including H2O if using the hydrous parameterization).

  • coeffs str – One of: - ‘webapp’ or ‘manuscript’ to include H2O in NBO/O - ‘anhydrous’ to exclude H2O from NBO/O

Returns:

NBO/O.

Return type:

float

calculate_dissolved_volatiles(pressure, temperature, sample, X_fluid=1.0, coeffs='webapp', **kwargs)[source]

Calculates the dissolved H2O concentration, using Eq (13) of Iacono-Marziano et al. (2012). If using the hydrous parameterization, it will use the scipy.root_scalar routine to find the root of the root_dissolved_volatiles method.

Parameters:
  • pressure float – Total pressure in bars.

  • temperature float – Temperature in C

  • sample pandas Series or dict – Major element oxides in wt%.

  • X_fluid float – Mole fraction of H2O in the fluid. Default is 1.0.

  • coeffs str – Which set of coefficients should be used in the calculations: - ‘webapp’ (default) for the hydrous NBO/O parameterisation coefficients used in

    the Iacono-Marziano webapp.

    • ‘manuscript’ for the hydrous NBO/O parameterisation coefficients given in the Iacono-Marziano et al. (2012) manuscript, but were incorrect (pers.comm.).

    • ‘anhydrous’ for the anhydrous NBO/O parameterisation coefficients given in the Iacono-Marziano et al. (2012) manuscript.

Returns:

Dissolved H2O concentration in wt%.

Return type:

float

calculate_equilibrium_fluid_comp(pressure, temperature, sample, **kwargs)[source]

Returns 1.0 if a pure H2O fluid is saturated. Returns 0.0 if a pure H2O fluid is undersaturated.

Parameters:
  • pressure float – The total pressure of the system in bars.

  • temperature float – The temperature of the system in C.

  • sample pandas Series or dict – Major element oxides in wt% (including H2O).

Returns:

1.0 if H2O-fluid saturated, 0.0 otherwise.

Return type:

float

calculate_saturation_pressure(temperature, sample, **kwargs)[source]

Calculates the pressure at which a pure H2O fluid is saturated, for the given sample composition and H2O concentration. Calls the scipy.root_scalar routine, which makes repeated called to the calculate_dissolved_volatiles method.

Parameters:
  • temperature float – The temperature of the system in C.

  • sample pandas Series or dict – Major element oxides in wt% (including H2O).

  • X_fluid float – The mole fraction of H2O in the fluid. Default is 1.0.

Returns:

Calculated saturation pressure in bars.

Return type:

float

root_dissolved_volatiles(h2o, pressure, temperature, sample, X_fluid, coeffs, kwargs)[source]

Function called by calculate_dissolved_volatiles method when the hydrous parameterization is being used.

Parameters:
  • h2o float – Guess for the H2O concentration in wt%.

  • pressure float – Total pressure in bars.

  • temperature float – Temperature in K.

  • sample pandas Series or dict – Major element oxides in wt%.

  • X_fluid float – Mole fraction of H2O in the fluid.

  • coeffs str – One of ‘webapp’,’manuscript’,’anhydrous’.

  • kwargs dictionary – Keyword arguments

Returns:

Difference between H2O guessed and the H2O calculated.

Return type:

float

root_saturation_pressure(pressure, temperature, sample, kwargs)[source]

Function called by scipy.root_scalar when finding the saturation pressure using calculate_saturation_pressure.

Parameters:
  • pressure float – Pressure guess in bars

  • temperature float – The temperature of the system in C.

  • sample pandas Series or dict – Major elements in wt% (normalized to 100%), including H2O.

  • kwargs dictionary – Additional keyword arguments supplied to calculate_saturation_pressure. Might be required for the fugacity or activity models.

Returns:

The differece between the dissolved H2O at the pressure guessed, and the H2O concentration passed in the sample variable.

Return type:

float

LiuWater(Model)

class VESIcal.models.liu.water[source]

Implementation of the Liu et al. (2005) H2O solubility model for metaluminous high-silica rhyolitic melts.

calculate_dissolved_volatiles(sample, pressure, temperature, X_fluid=1.0, **kwargs)[source]
Parameters:
  • sample (Sample class) – Magma major element composition.

  • pressure float – Pressure in bars.

  • temperature float – Temperature in degrees C.

  • X_fluid float – OPTIONAL. Default is 1.0. Mole fraction of H2O in the H2O-CO2 fluid.

Returns:

Calculated dissolved H2O concentration in wt%.

Return type:

float

calculate_equilibrium_fluid_comp(sample, pressure, temperature, **kwargs)[source]
Parameters:
  • sample (Sample class) – Magma major element composition.

  • pressure float – Pressure in bars.

  • temperature float – Temperature in degrees C.

Returns:

Calculated equilibrium fluid concentration in XH2Ofluid mole fraction.

Return type:

float

calculate_saturation_pressure(temperature, sample, X_fluid=1.0, **kwargs)[source]

Calculates the pressure at which a an H2O-bearing fluid is saturated. Calls the scipy.root_scalar routine, which makes repeated called to the calculate_dissolved_volatiles method.

Parameters:
  • sample (Sample class) – Magma major element composition.

  • temperature float – Temperature in degrees C.

  • X_fluid float – OPTIONAL. Default is 1.0. Mole fraction of H2O in the H2O-CO2 fluid.

Returns:

Calculated saturation pressure in bars.

Return type:

float

root_saturation_pressure(pressure, temperature, sample, X_fluid, kwargs)[source]

Function called by scipy.root_scalar when finding the saturation pressure using calculate_saturation_pressure.

Parameters:
  • pressure float – Pressure guess in bars

  • temperature float – The temperature of the system in C.

  • sample (Sample class) – Magma major element composition, including H2O.

  • kwargs dictionary – Additional keyword arguments supplied to calculate_saturation_pressure. Might be required for the fugacity or activity models.

Returns:

The differece between the dissolved H2O at the pressure guessed, and the H2O concentration passed in the sample variable.

Return type:

float

LiuCarbon(Model)

class VESIcal.models.liu.carbon[source]

Implementation of the Liu et al. (2005) H2O-CO2 solubility model for metaluminous high-silica rhyolitic melts.

calculate_dissolved_volatiles(sample, pressure, temperature, X_fluid=1, **kwargs)[source]
Parameters:
  • sample (Sample class) – Magma major element composition.

  • pressure float – Pressure in bars.

  • temperature float – Temperature in degrees C.

  • X_fluid float – OPTIONAL. Default is 1. Mole fraction of CO2 in the H2O-CO2 fluid.

Returns:

Calculated dissolved CO2 concentration in wt%.

Return type:

float

calculate_equilibrium_fluid_comp(sample, pressure, temperature, **kwargs)[source]
Parameters:
  • sample (Sample class) – Magma major element composition.

  • pressure float – Pressure in bars.

  • temperature float – Temperature in degrees C.

Returns:

Calculated equilibrium fluid concentration in XCO2fluid mole fraction.

Return type:

float

calculate_saturation_pressure(temperature, sample, X_fluid=1.0, **kwargs)[source]

Calculates the pressure at which a an CO2-bearing fluid is saturated. Calls the scipy.root_scalar routine, which makes repeated called to the calculate_dissolved_volatiles method.

Parameters:
  • sample (Sample class) – Magma major element composition.

  • temperature float – Temperature in degrees C.

  • X_fluid float – OPTIONAL. Default is 0. Mole fraction of CO2 in the H2O-CO2 fluid.

Returns:

Calculated saturation pressure in bars.

Return type:

float

root_saturation_pressure(pressure, temperature, sample, X_fluid, kwargs)[source]

Function called by scipy.root_scalar when finding the saturation pressure using calculate_saturation_pressure.

Parameters:
  • pressure float – Pressure guess in bars

  • temperature float – The temperature of the system in C.

  • sample (Sample class) – Magma major element composition, including H2O.

  • kwargs dictionary – Additional keyword arguments supplied to calculate_saturation_pressure. Might be required for the fugacity or activity models.

Returns:

The differece between the dissolved H2O at the pressure guessed, and the H2O concentration passed in the sample variable.

Return type:

float

MooreWater(Model)

class VESIcal.models.moore.water[source]

Implementation of the Moore et al. (1998) H2O solubility model for magmas up to 3,000 bars.

calculate_dissolved_volatiles(sample, pressure, temperature, X_fluid=1.0, **kwargs)[source]
Parameters:
  • sample (Sample class) – Magma major element chemistry.

  • pressure float – Pressure in bars.

  • temperature float – Temperature in degrees C.

  • X_fluid float – OPTIONAL. Default is 1.0. Mole fraction of H2O in the H2O-CO2 fluid.

Returns:

Calculated dissolved H2O concentration in wt%.

Return type:

float

calculate_equilibrium_fluid_comp(sample, pressure, temperature, **kwargs)[source]
Parameters:
  • sample (Sample class) – Magma major element composition.

  • pressure float – Pressure in bars.

  • temperature float – Temperature in degrees C.

Returns:

Calculated equilibrium fluid concentration in XH2Ofluid mole fraction.

Return type:

float

calculate_saturation_pressure(temperature, sample, X_fluid=1.0, **kwargs)[source]

Calculates the pressure at which a an H2O-bearing fluid is saturated. Calls the scipy.root_scalar routine, which makes repeated called to the calculate_dissolved_volatiles method.

Parameters:
  • sample (Sample class) – Magma major element composition.

  • temperature float – Temperature in degrees C.

  • X_fluid float – OPTIONAL. Default is 1.0. Mole fraction of H2O in the H2O-CO2 fluid.

Returns:

Calculated saturation pressure in bars.

Return type:

float

root_saturation_pressure(pressure, temperature, sample, X_fluid, kwargs)[source]

Function called by scipy.root_scalar when finding the saturation pressure using calculate_saturation_pressure.

Parameters:
  • pressure float – Pressure guess in bars

  • temperature float – The temperature of the system in C.

  • sample Sample class – Magma major element composition.

  • kwargs dictionary – Additional keyword arguments supplied to calculate_saturation_pressure. Might be required for the fugacity or activity models.

Returns:

The differece between the dissolved H2O at the pressure guessed, and the H2O concentration passed in the sample variable.

Return type:

float

AllisonCarbon(Model)

class VESIcal.models.allison.carbon(model_loc='sunset', model_fit='thermodynamic')[source]

Implementation of the Allison et al. (2019) CO2 solubility model. Which type of fit, and which composition must be selected when the Model is initialized. The fit may be either thermodynamic or power-law. The composition may be chosen from sunset, sfvf, erebus, vesuvius, etna, or stromboli. Default is the power-law fit to sunset.

calculate_dissolved_volatiles(pressure, temperature=1200, sample=None, X_fluid=1.0, **kwargs)[source]

Calclates the dissolved CO2 concentration using (Eqns) 2-7 or 10-11 from Allison et al. (2019).

Parameters:
  • pressure float – Pressure in bars.

  • temperature float – Temperature in C.

  • sample NoneType or Sample class – Magma major element composition. Not required for this model, therefore None may be passed.

  • X_fluid float – The mole fraction of CO2 in the fluid. Default is 1.0.

Returns:

Dissolved CO2 concentration in wt%.

Return type:

float

calculate_equilibrium_fluid_comp(pressure, sample, temperature=1200, **kwargs)[source]

Returns 1.0 if a pure CO2 fluid is saturated. Returns 0.0 if a pure CO2 fluid is undersaturated.

Parameters:
  • pressure float – The total pressure of the system in bars.

  • temperature float – The temperature of the system in C.

  • sample (Sample class) – Magma major element composition (including H2O).

Returns:

1.0 if CO2-fluid saturated, 0.0 otherwise.

Return type:

float

calculate_saturation_pressure(sample, temperature=1200, X_fluid=1.0, **kwargs)[source]

Calculates the pressure at which a pure CO2 fluid is saturated, for the given sample composition and CO2 concentration. Calls the scipy.root_scalar routine, which makes repeated called to the calculate_dissolved_volatiles method.

Parameters:
  • temperature float – The temperature of the system in C.

  • sample (Sample class) – Magma major element composition (including CO2).

  • X_fluid float – The mole fraction of H2O in the fluid. Default is 1.0.

Returns:

Calculated saturation pressure in bars.

Return type:

float

root_saturation_pressure(pressure, temperature, sample, X_fluid, kwargs)[source]

Function called by scipy.root_scalar when finding the saturation pressure using calculate_saturation_pressure.

Parameters:
  • pressure float – Pressure guess in bars

  • temperature float – The temperature of the system in C.

  • sample (Sample class) – Magma major element composition, including CO2.

  • kwargs dictionary – Additional keyword arguments supplied to calculate_saturation_pressure. Might be required for the fugacity or activity models.

Returns:

The differece between the dissolved CO2 at the pressure guessed, and the CO2 concentration passed in the sample variable.

Return type:

float

Mixed Fluid Models

MixedFluid(Model)

class VESIcal.model_classes.MixedFluid(models)[source]

Implements the generic framework for mixed fluid solubility. Any set of pure fluid solubility models may be specified.

calculate_degassing_path(sample, pressure='saturation', fractionate_vapor=0.0, final_pressure=100.0, steps=101, return_dfs=True, round_to_zero=True, **kwargs)[source]

Calculates the dissolved volatiles in a progressively degassing sample.

Parameters:
  • sample Sample class – Magma major element composition (including volatiles).

  • pressure string, float, int, list, or numpy array – Defaults to ‘saturation’, the calculation will begin at the saturation pressure. If a number is passed as either a float or int, this will be the starting pressure. If a list of numpy array is passed, the pressure values in the list or array will define the degassing path, i.e. final_pressure and steps variables will be ignored. Units are bars.

  • fractionate_vapor float – What proportion of vapor should be removed at each step. If 0.0 (default), the degassing path will correspond to closed-system degassing. If 1.0, the degassing path will correspond to open-system degassing.

  • final_pressure float – The final pressure on the degassing path, in bars. Ignored if a list or numpy array is passed as the pressure variable. Default is 1 bar.

  • steps int – The number of steps in the degassing path. Ignored if a list or numpy array are passed as the pressure variable.

  • return_dfs bool – If True, the results will be returned in a pandas DataFrame, if False, two numpy arrays will be returned.

  • round_to_zero bool – If True, the first entry of FluidProportion_wt will be rounded to zero, rather than being a value within numerical error of zero. Default is True.

Returns:

If return_dfs is True (default), a DataFrame with columns ‘Pressure_bars’, ‘H2O_liq’, ‘CO2_liq’, ‘H2O_fl’, ‘CO2_fl’, and ‘FluidProportion_wt’, is returned. Dissolved volatiles are in wt%, the proportions of volatiles in the fluid are in mole fraction. Otherwise a numpy array containing the dissolved volatile concentrations, and a numpy array containing the mole fractions of volatiles in the fluid is returned. The columns are in the order of the volatiles in self.volatile_species.

Return type:

pandas DataFrame or numpy arrays

calculate_dissolved_volatiles(pressure, X_fluid, returndict=False, **kwargs)[source]

Calculates the dissolved volatile concentrations in wt%, using each model’s calculate_dissolved_volatiles method. At present the volatile concentrations are not propagated through.

Parameters:
  • pressure float – The total pressure in bars.

  • X_fluid float, numpy.ndarry, dict, pandas Series – The mole fraction of each species in the fluid. If the mixed fluid model contains only two species (e.g. CO2 and H2O), the value of the first species in self.volatile_species may be passed on its own as a float.

  • returndict bool – If True, the results will be returned in a dict, otherwise they will be returned as a tuple.

Returns:

Dissolved volatile concentrations of each species in the model, in the order set by self.volatile_species.

Return type:

tuple

calculate_equilibrium_fluid_comp(pressure, sample, return_dict=True, **kwargs)[source]

Calculates the composition of the fluid in equilibrium with the dissolved volatile concentrations passed. If a fluid phase is undersaturated at the chosen pressure (0,0) will be returned. Note, this currently assumes the given H2O and CO2 concentrations are the system total, not the total dissolved. If one of the volatile species has a zero or negative concentration, the pure fluid model for the other volatile species will be used.

Parameters:
  • pressure float – The total pressure in bars.

  • sample Sample class – Magma major element composition.

  • return_dict bool – Set the return type, if true a dict will be returned, if False two floats will be returned. Default is True.

Returns:

Mole fractions of the volatile species in the fluid, in the order given by self.volatile_species if floats.

Return type:

dict or floats

calculate_isobars_and_isopleths(pressure_list, isopleth_list=[0, 1], points=51, return_dfs=True, extend_to_zero=True, **kwargs)[source]

Calculates isobars and isopleths. Isobars can be calculated for any number of pressures. Variables required by each of the pure fluid models must be passed, e.g. sample, temperature, etc.

Parameters:
  • pressure_list list or float – List of all pressure values at which to calculate isobars, in bars.

  • isopleth_list list – Default value is None, in which case only isobars will be calculated. List of all fluid compositions in mole fraction (of the first species in self.volatile_species) at which to calcualte isopleths. Values can range from 0 to 1.

  • points int – The number of points in each isobar and isopleth. Default value is 101.

  • return_dfs bool – If True, the results will be returned as two pandas DataFrames, as produced by the MagmaSat method. If False the results will be returned as lists of numpy arrays.

Returns:

If isopleth_list is not None, two objects will be returned, one with the isobars and the second withthe isopleths. If return_dfs is True, two pandas DataFrames will be returned with column names ‘Pressure’ or ‘XH2O_fl’, ‘H2O_liq’, and ‘CO2_liq’. If return_dfs is False, two lists of numpy arrays will be returned. Each array is an individual isobar or isopleth, in the order passed via pressure_list or isopleth_list. The arrays are the concentrations of H2O and CO2 in the liquid, in the order of the species in self.volatile_species.

Return type:

pandas DataFrame object(s) or list(s)

calculate_saturation_pressure(sample, **kwargs)[source]

Calculates the pressure at which a fluid will be saturated, given the dissolved volatile concentrations. If one of the volatile species has a zero or negative concentration the pure fluid model for the other species will be used. If one of the volatile species has a concentration lower than the concentration dissolved at 0 bar, the pure fluid model for the other species will be used.

Parameters:

sample Sample class – Magma major element composition (including volatiles).

Returns:

The saturation pressure in bars.

Return type:

float

check_calibration_range(parameters, report_nonexistance=True)[source]

Checks whether the given parameters are within the ranges defined by the CalibrationRange objects for each model and its fugacity and activity models. An empty string will be returned if all parameters are within the calibration range. If a parameter is not within the calibration range, a description of the problem will be returned in the string.

Parameters:

parameters dict – Dictionary keys are the names of the parameters to be checked, e.g., pressure temperature, SiO2, etc. Values are the values of each parameter. A complete set need not be given.

Returns:

String description of any parameters falling outside of the calibration range.

Return type:

str

get_calibration_range()[source]

Returns a string describing the calibration ranges defined by the CalibrationRange objects for each model, and its associated fugacity and activity models.

Returns:

String description of the calibration range objects.

Return type:

str

get_calibration_values(variable_names)[source]

Placeholder method to prevent an error when this generic method is called for a MixedFluid model.

Return type:

np.nan

root_for_fluid_comp(Xv0, pressure, Xt0, Xt1, sample, kwargs)[source]

Function called by scipy.root_scalar when calculating the composition of equilibrium fluid in the calculate_equilibrium_fluid_comp method.

Parameters:
  • Xv0 float – The guessed mole fraction of the first volatile species in self.volatile_species.

  • pressure float – The total pressure in bars.

  • Xt0 float – The total mole fraction of the first volatile species in self.volatile_species.

  • Xt1 float – The total mole fraction of the second volatile species in self.volatile_species.

  • sample Sample class – Magma major element composition.

  • kwargs dictionary – A dictionary of keyword arguments that may be required by the pure fluid models.

Returns:

The differene in the LHS and RHS of the mass balance equation. Eq X in manuscript.

Return type:

float

root_saturation_pressure(x, volatile_concs, sample, kwargs)[source]

Function called by scipy.root when finding the saturation pressure using calculate_saturation_pressure.

Parameters:
  • x numpy array – The guessed value for the root. x[0] is the pressure (in bars) and x[1] is the mole fraction of the first volatile in self.volatile_species.

  • volatile_concs numpy array – The dissolved volatile concentrations, in the same order as self.volatile_species.

  • sample (Sample class) – Magma major element composition (including volatiles).

  • kwargs dictionary – Dictionary of keyword arguments, which may be required by the pure-fluid models.

Returns:

The difference in the dissolved volatile concentrations, and those predicted with the pressure and fluid composition specified by x.

Return type:

numpy array

MagmaSat(Model)

class VESIcal.models.magmasat.MagmaSat[source]

An object to instantiate a thermoengine equilibrate class

calculate_degassing_path(sample, temperature, pressure='saturation', fractionate_vapor=0.0, init_vapor=0.0, final_pressure=1.0, steps=50, **kwargs)[source]

Calculates degassing path for one sample

Parameters:
  • sample (Sample class) – Magma major element composition.

    Legacy info follows, might still be useful? If pulling from an uploaded file with data for many samples, first call get_sample_composition() to get the sample desired. Then pass the result into this function.

  • temperature (float) – Temperature at which to calculate degassing paths, in degrees C.

  • pressure (string, float, int, list, or numpy array) – OPTIONAL. The perssure at which to begin the degassing calculations. Default value is ‘saturation’, which runs the calculation with the initial pressure at the saturation pressure. If a pressure greater than the saturation pressure is input, the calculation will start at saturation, since this is the first pressure at which any degassing will occur.

  • fractionate_vapor (float) – OPTIONAL. Proportion of vapor removed at each pressure step. Default value is 0.0 (completely closed-system degassing). Specifies the type of calculation performed, either closed system (0.0) or open system (1.0) degassing. If any value between <1.0 is chosen, user can also specify the ‘init_vapor’ argument (see below). A value in between 0 and 1 will remove that proportion of vapor at each step. For example, for a value of 0.2, the calculation will remove 20% of the vapor and retain 80% of the vapor at each pressure step.

  • init_vapor (float) – OPTIONAL. Default value is 0.0. Specifies the amount of vapor (in wt%) coexisting with the melt before degassing.

  • final_pressure (float) – OPTIONAL. The final pressure on the degassing path, in bars. Ignored if a list or numpy array is passed as the pressure variable. Default is 1 bar.

  • steps (int) – OPTIONAL. Default value is 50. Specifies the number of steps in pressure space at which dissolved volatile concentrations are calculated.

Return type:

pandas DataFrame object

calculate_dissolved_volatiles(sample, temperature, pressure, X_fluid=1, H2O_guess=0.0, verbose=False, **kwargs)[source]

Calculates the amount of H2O and CO2 dissolved in a magma at saturation at the given P/T conditions and fluid composition. Fluid composition will be matched to within 0.0001 mole fraction.

Parameters:
  • sample (Sample class) – Magma major element composition.

  • temperature (float or int) – Temperature, in degrees C.

  • presure (float or int) – Pressure, in bars.

  • X_fluid (float or int) – The default value is 1. The mole fraction of H2O in the H2O-CO2 fluid. X_fluid=1 is a pure H2O fluid. X_fluid=0 is a pure CO2 fluid.

  • verbose (bool) – OPTIONAL: Default is False. If set to True, returns H2O and CO2 concentration in the melt, H2O and CO2 concentration in the fluid, mass of the fluid in grams, and proportion of fluid in the system in wt%.

Returns:

A dictionary of dissolved volatile concentrations in wt% with keys H2O and CO2.

Return type:

dict

calculate_equilibrium_fluid_comp(sample, temperature, pressure, verbose=False, **kwargs)[source]

Returns H2O and CO2 concentrations in wt% in a fluid in equilibrium with the given sample at the given P/T condition.

Parameters:
  • sample (Sample class) – Magma major element composition.

  • temperature (float or int) – Temperature, in degrees C.

  • presure (float or int) – Pressure, in bars.

  • verbose (bool) – OPTIONAL: Default is False. If set to True, returns H2O and CO2 concentration in the fluid in mole fraction, mass of the fluid in grams, and proportion of fluid in the system in wt%.

Returns:

A dictionary of fluid composition in wt% with keys ‘H2O’ and ‘CO2’ is returned.

Return type:

dict

calculate_isobars_and_isopleths(sample, temperature, pressure_list, isopleth_list=None, smooth_isobars=True, smooth_isopleths=True, print_status=True, **kwargs)[source]

Calculates isobars and isopleths at a constant temperature for a given sample. Isobars can be calculated for any number of pressures. Isobars are calculated using 5 XH2O values (0, 0.25, 0.5, 0.75, 1).

Parameters:
  • sample (Sample class) – Magma major element composition.

  • temperature (float) – Temperature in degrees C.

  • pressure_list (list or float) – List of all pressure values at which to calculate isobars, in bars. If only one value is passed it can be as float instead of list.

  • isopleth_list (list or float) – OPTIONAL: Default value is None in which case only isobars will be calculated. List of all fluid compositions in mole fraction H2O (XH2Ofluid) at which to calcualte isopleths. Values can range from 0-1. If only one value is passed it can be as float instead of list.

  • smooth_isobars (bool) – OPTIONAL. Default is True. If set to True, polynomials will be fit to the computed isobar points.

  • smooth_isopleths (bool) – OPTIONAL. Default is True. If set to True, polynomials will be fit to the computed isopleth points.

  • print_status (bool) – OPTIONAL: Default is True. If set to True, progress of the calculations will be printed to the terminal.

Returns:

Two pandas DataFrames are returned; the first has isobar data, and the second has isopleth data. Columns in the isobar dataframe are ‘Pressure’, ‘H2Omelt’, and ‘CO2melt’, correpsonding to pressure in bars and dissolved H2O and CO2 in the liquid in wt%. Columns in the isopleth dataframe are ‘Pressure’, ‘H2Ofl’, and ‘CO2fl’, corresponding to pressure in bars and H2O and CO2 concentration in the H2O-CO2 fluid, in wt%.

Return type:

pandas DataFrame objects

calculate_saturation_pressure(sample, temperature, verbose=False, **kwargs)[source]

Calculates the saturation pressure of a sample composition.

Parameters:
  • sample (Sample class) – Magma major element composition.

  • temperature (flaot or int) – Temperature of the sample in degrees C.

  • verbose (bool) – OPTIONAL: Default is False. If set to False, only the saturation pressure is returned. If set to True, the saturation pressure, mass of fluid in grams, proportion of fluid in wt%, and H2O and CO2 concentrations in the fluid in mole fraction are all returned in a dict.

Returns:

If verbose is set to False: Saturation pressure in bars. If verbose is set to True: dict of all calculated values.

Return type:

float or dict

check_calibration_range(parameters, **kwargs)[source]

Checks whether supplied parameters and calculated results are within the calibration range of the model, defined by the CalibrationRange objects. An empty string will be returned if all parameters are within the calibration range. If a parameter is not within the calibration range, a description of the problem will be returned in the string.

Parameters:

parameters dict – Dictionary keys are the names of the parameters to be checked, e.g., pressure temperature, SiO2, etc. Values are the values of each parameter. A complete set need not be given.

Returns:

String description of any parameters falling outside of the calibration range.

Return type:

str

get_XH2O_fluid(sample, temperature, pressure, H2O, CO2)[source]

An internally used function to calculate fluid composition.

Parameters:
  • sample (Sample class) – Magma major element composition.

  • temperature (float) – Temperature in degrees C.

  • pressure (float) – Pressure in bars

  • H2O (float) – wt% H2O in the system

  • CO2 (float) – wt% CO2 in the system

Returns:

Mole fraction of H2O in the H2O-CO2 fluid

Return type:

float

get_calibration_range()[source]

Returns a string describing the calibration ranges defined by the CalibrationRange objects for the model.

Returns:

String description of the calibration range objects.

Return type:

str

get_fluid_mass(sample, temperature, pressure, H2O, CO2)[source]

An internally used function to calculate fluid mass.

Parameters:
  • sample (Sample class) – Magma major element composition.

  • temperature (float) – Temperature in degrees C.

  • pressure (float) – Pressure in bars

  • H2O (float) – wt% H2O in the system

  • CO2 (float) – wt% CO2 in the system

Returns:

mass of the fluid in grams

Return type:

float

preprocess_sample(sample)[source]

Returns sample with 0.0 values for any oxides not passed.

Parameters:

sample (Sample class) – Magma major element composition.

Return type:

Sample class object

VESIcal Plotting Functions

Functions defined in VESIcal.vplot

VESIcal.vplot.plot(isobars=None, isopleths=None, degassing_paths=None, custom_H2O=None, custom_CO2=None, isobar_labels=None, isopleth_labels=None, degassing_path_labels=None, custom_labels=None, custom_colors='VESIcal', custom_symbols=None, markersize=10, figsize=(12, 8), save_fig=False, extend_isobars_to_zero=True, smooth_isobars=False, smooth_isopleths=False, **kwargs)[source]

Custom automatic plotting of model calculations in VESIcal. Isobars, isopleths, and degassing paths can be plotted. Labels can be specified for each. Any combination of isobars, isopleths, and degassing paths can be plotted.

Parameters:
  • isobars (pandas DataFrame or list) – OPTIONAL. DataFrame object containing isobar information as calculated by calculate_isobars_and_isopleths. Or a list of DataFrame objects.

  • isopleths (pandas DataFrame or list) – OPTIONAL. DataFrame object containing isopleth information as calculated by calculate_isobars_and_isopleths. Or a list of DataFrame objects.

  • degassing_paths (list) – OPTIONAL. List of DataFrames with degassing information as generated by calculate_degassing_path().

  • custom_H2O (list) – OPTIONAL. List of groups of H2O values to plot as points. For example myfile.data[‘H2O’] is one group of H2O values. Must be passed with custom_CO2 and must be same length as custom_CO2.

  • custom_CO2 (list) – OPTIONAL. List of groups of CO2 values to plot as points.For example myfile.data[‘CO2’] is one group of CO2 values. Must be passed with custom_H2O and must be same length as custom_H2O.

  • isobar_labels (list) – OPTIONAL. Labels for the plot legend. Default is None, in which case each plotted line will be given the generic legend name of “Isobars n”, with n referring to the nth isobars passed. Isobar pressure is given in parentheses. The user can pass their own labels as a list of strings. If more than one set of isobars is passed, the labels should refer to each set of isobars, not each pressure.

  • isopleth_labels (list) – OPTIONAL. Labels for the plot legend. Default is None, in which case each plotted isopleth will be given the generic legend name of “Isopleth n”, with n referring to the nth isopleths passed. Isopleth XH2O values are given in parentheses. The user can pass their own labels as a list of strings. If more than one set of isopleths is passed, the labels should refer to each set of isopleths, not each XH2O value.

  • degassing_path_labels (list) – OPTIONAL. Labels for the plot legend. Default is None, in which case each plotted line will be given the generic legend name of “Pathn”, with n referring to the nth degassing path passed. The user can pass their own labels as a list of strings.

  • custom_labels (list) – OPTIONAL. Labels for the plot legend. Default is None, in which case each group of custom points will be given the generic legend name of “Customn”, with n referring to the nth degassing path passed. The user can pass their own labels as a list of strings.

  • custom_colors (list) – OPTIONAL. Default value is “VESIcal”, which uses VESIcal’s color ramp. A list of color values readable by matplotlib can be passed here if custom symbol colors are desired. The length of this list must match that of custom_H2O and custom_CO2.

  • custom_symbols (list) – OPTIONAL. Default value is None, in which case data are plotted as filled circles.. A list of symbol tyles readable by matplotlib can be passed here if custom symbol types are desired. The length of this list must match that of custom_H2O and custom_CO2.

  • markersize (int) – OPTIONAL. Default value is 10. Same as markersize kwarg in matplotlib. Any numeric value passed here will set the marker size for (custom_H2O, custom_CO2) points.

  • figsize (tuple) – OPTIONAL. Default value is (12,8). Sets the matplotlib.pyplot figsize value as (x_dimension, y_dimension)

  • save_fig (False or str) – OPTIONAL. Default value is False, in which case the figure will not be saved. If a string is passed, the figure will be saved with the string as the filename. The string must include the file extension.

  • extend_isobars_to_zero (bool) – OPTIONAL. If True (default), isobars will be extended to zero, even if there is a finite solubility at zero partial pressure.

  • smooth_isobars (bool) – OPTIONAL. Default is False. If set to True, isobar data will be fit to a polynomial and plotted. If False, the raw input data will be plotted.

  • smooth_isopleths (bool) – OPTIONAL. Default is False. If set to True, isopleth data will be fit to a polynomial and plotted. If False, the raw input data will be plotted.

Returns:

fig and axes matploblib objects defining a plot with x-axis as H2O wt% in the melt and y-axis as CO2 wt%in the melt. Isobars, or lines of constant pressure at which the sample magma composition is saturated, and isopleths, or lines of constant fluid composition at which the sample magma composition is saturated, are plotted if passed. Degassing paths, or the concentration of dissolved H2O and CO2 in a melt equilibrated along a path of decreasing pressure, is plotted if passed.

Return type:

fig, axes Matplotlib objects

VESIcal.vplot.scatterplot(custom_x, custom_y, xlabel=None, ylabel=None, **kwargs)[source]

Custom x-y plotting using VESIcal’s built-in plot() function, built Matplotlib’s plot and scatter functions.

Parameters:
  • custom_x (list) – List of groups of x-values to plot as points or lines

  • custom_y (list) – List of groups of y-values to plot as points or lines

  • xlabel (str) – OPTIONAL. What to display along the x-axis.

  • ylabel (str) – OPTIONAL. What to display along the y-axis.

  • kwargs – Can take in any key word agruments that can be passed to plot().

Returns:

X-y plot with custom x and y axis values and labels.

Return type:

fig, ax matplotlib objects

VESIcal.vplot.smooth_isobars_and_isopleths(isobars=None, isopleths=None)[source]

Takes in a dataframe with calculated isobar and isopleth information (e.g., output from calculate_isobars_and_isopleths) and smooths the data for plotting.

Parameters:
  • isobars (pandas DataFrame) – OPTIONAL. DataFrame object containing isobar information as calculated by calculate_isobars_and_isopleths.

  • isopleths (pandas DataFrame) – OPTIONAL. DataFrame object containing isopleth information as calculated by calculate_isobars_and_isopleths.

Returns:

DataFrame with x and y values for all isobars and all isopleths. Useful if a user wishes to do custom plotting with isobar and isopleth data rather than using the built-in plot_isobars_and_isopleths() function.

Return type:

pandas DataFrame

VESIcal.vplot.calib_plot(user_data=None, model='all', plot_type='TAS', zoom=None, figsize=(17, 8), legend=True, save_fig=False, **kwargs)[source]

Plots user data and calibration set of any or all models on any x-y plot or a total alkalis vs silica (TAS) diagram. TAS diagram boundaries provided by tasplot python module, copyright John A Stevenson.

Parameters:
  • user_data (BatchFile object, Sample object, pandas DataFrame, pandas Series,) – or dict. OPTIONAL. Default value is None, in which case only the model calibration set is plotted. User provided sample data describing the oxide composition of one or more samples. Multiple samples can be passed as an BatchFile object or pandas DataFrame. A single sample can be passed as a pandas Series.

  • model (str or list) – OPTIONAL. Default value is ‘all’, in which case all model calibration datasets will be plotted. ‘Mixed’ can be used to plot all mixed fluid models. String of the name of the model calibration dataset to plot (e.g., ‘Shishkina’). Multiple models can be plotted by passing them as strings within a list (e.g., [‘Shishkina’, ‘Dixon’]).

  • plot_type (str) – OPTIONAL. Default value is ‘TAS’, which returns a total alkali vs silica (TAS) diagram. Any two oxides can be plotted as an x-y plot by setting plot_type=’xy’ and specifying x- and y-axis oxides, e.g., x=’SiO2’, y=’Al2O3’.

  • zoom (str or list) – OPTIONAL. Default value is None in which case axes will be set to the default of 35<x<100 wt% and 0<y<25 wt% for TAS type plots and the best values to show the data for xy type plots. Can pass “user_data” to plot the figure where the x and y axes are scaled down to zoom in and only show the region surrounding the user_data. A list of tuples may be passed to manually specify x and y limits. Pass in data as [(x_min, x_max), (y_min, y_max)]. For example, the default limits here would be passed in as [(35,100), (0,25)].

  • figsize (tuple) – OPTIONAL. Default value is (17,8). Sets the matplotlib.pyplot figsize value as (x_dimension, y_dimension).

  • legend (bool) – OPTIONAL. Default value is True. Can be set to False in which case the legend will not be displayed.

  • save_fig (False or str) – OPTIONAL. Default value is False, in which case the figure will not be saved. If a string is passed, the figure will be saved with the string as the filename. The string must include the file extension.

Return type:

matplotlib object

Data Transformation Functions

VESIcal.fluid_molfrac_to_wt(data, H2O_colname='XH2O_fl_VESIcal', CO2_colname='XCO2_fl_VESIcal')[source]

Takes in a pandas dataframe object and converts only the fluid composition from mole fraction to wt%, leaving the melt composition in tact. The user must specify the names of the XH2O_fl and XCO2_fl columns.

Parameters:
  • data (pandas DataFrame) – Sample composition(s) containing columns for H2O and CO2 concentrations in the fluid.

  • H2O_colname (str) – OPTIONAL. The default value is ‘XH2O_fl’, which is what is returned by BatchFile() core calculations. String containing the name of the column corresponding to the H2O concentration in the fluid, in mol fraction.

  • CO2_colname (str) – OPTIONAL. The default value is ‘XCO2_fl’, which is what is returned by BatchFile() core calculations. String containing the name of the column corresponding to the CO2 concentration in the fluid, in mol fraction.

Returns:

Original data passed plus newly calculated values are returned.

Return type:

pandas DataFrame

VESIcal.fluid_wt_to_molfrac(data, H2O_colname='H2O_fl_wt', CO2_colname='CO2_fl_wt')[source]

Takes in a pandas dataframe object and converts only the fluid composition from wt% to mole fraction, leaving the melt composition in tact. The user must specify the names of the H2O_fl_wt and CO2_fl_wt columns.

Parameters:
  • data (pandas DataFrame) – DataFrame containing columns for H2O and CO2 concentrations in the fluid.

  • H2O_colname (str) – OPTIONAL. The default value is ‘H2O_fl_wt’, which is what is returned by BatchFile() core calculations. String containing the name of the column corresponding to the H2O concentration in the fluid, in wt%.

  • CO2_colname (str) – OPTIONAL. The default value is ‘CO2_fl_wt’, which is what is returned by BatchFile() core calculations. String containing the name of the column corresponding to the CO2 concentration in the fluid, in wt%.

Returns:

Original data passed plus newly calculated values are returned.

Return type:

pandas DataFrame

VESIcal.get_oxides(sample)[source]

Returns a sample composition with only compositional oxide data, removing any extranneous data. Useful when passing a self-defined sample (e.g. dict or pandas Series) to a some VESIcal function.

Parameters:
  • sample (pandas Series or dictionary)

  • A sample composition plus other sample information

Returns:

  • Same type as passed sample (pandas Series or dictionary)

  • Sample composition with extranneous information removed.

Universal Informative Functions

VESIcal.get_model_names(model='all')[source]