MMA-EoS is a computational framework for mineralogical thermodynamics. You can use it to calculate compositional, thermodynamic and mechanical properties of polycrystalline aggregates for use in geosciences.
MMA-EoS implements equations of state for solids, comes with sets of ready-to-use model parameters and can either be controlled through command line programs or linked to your own applications as a library.
Installation
Most of the code for MMA-EoS is written in F# with some performance critical parts and system interfaces in C. This means that the code will run on many platforms that have a .NET environment, but some machine specific parts need to be present for certain functionality.
If you unpacked a binary distribution
archive of MMA-EoS, you should be able to run the launcher program
eos (for unixoid systems) or eos.exe (for windows-like systems)
directly. You can verify the authenticity of the distribution archives
using Minisign:
minisign -Vm EoS-... -P RWQqcIdQLuG/Iiw3rcwD9D3Wu8UojK49fBSLibuda44tqkEcZV+xTfYC
Alternatively, you can run MMA-EoS using
Docker. Images are provided in the repository
chust/eos. Where you would run
eos, you can instead type docker run --rm chust/eos. Where you would
use mpiexec -n N eos for parallel execution, you can instead use
docker run --env=NPROC=N --rm chust/eos.
If you want to compile MMA-EoS yourself, you will need an F# 6.0
compiler, and a C compiler. You'll also need MPI libraries for your
platform if you want parallel execution support. You should install the
.NET Core SDK, then run the
BuildAndTest.ps1 script. In case no recent version of
PowerShell is present on
your system, you can simply install it as a tool for the .NET Core SDK
using dotnet tool install -g powershell. If you need fine grained
control over the build process, you can manually build EoS.sln using
dotnet build, and the LPSolve and MPIGlue directories using GNU
make.
To create a distribution directory or archive after building MMA-EoS,
use the BundleAndZip.ps1 script, the EoS.iss installer script for
Windows, or one of the *.dockerfiles to build an image containing the
command line tools.
Command Line Use
The launcher program allows you to invoke a number of command line tools for common tasks. Simply running
eos
will list the available subcommand. Running a subcommand with the
-help flag should list its command line options, for example:
eos prop -help
The tools all have similar options. Perhaps the most important one
-db=... which selects a file with model parameters to use in the
calculations. You can write, for example, -db=SLB11 to select the
file SLB11.xml from the MMA-EoS library directory or
-db=path/to/some.xml to specify an explicit path. Additional
non-option arguments often allow to narrow the selection of phases
from the database.
To see what's in a phase collection, open the XML database file in a text editor or try something like this:
eos pidx -db=SLB11
The pidx tool also accepts the option -r to recursively list
members of collections; and it can offset the indices it reports
(-o=N), which can be handy if you want to determine column numbers
in a file that contains composition vectors along with other data
fields.
The prop tool can compute state variables for phases and collections
of phases. For example, you could output the volume (-o=V) of
forsterite (fo) with model parameters from Stixrude and
Lithgow-Bertelloni 2011 (-db=SBL11) at a pressure of 10 GPa
(-P=10e9Pa) and a temperature of 1000 K (-T=1000K) with this
command:
eos prop -db=SLB11 fo -P=10e9Pa -T=1000K -o=V
If pressures and temperatures are specified in other units than pascal and kelvin, they are passed to unit conversion functions that require the UDUNITS library to be installed.
Instead of passing pressure and temperature options to the program, you can also convey that information through standard input. If you want to obtain properties for a solid solution or collection of phases, MMA-EoS also needs a composition vector. For example one could obtain the density of olivine with 90% forsterite and 10% fayalite at 1 bar and 300 K with this command:
echo '1e5 300 0.9 0.1' | eos prop -db=SLB11 ol -o=rho
The -o=... option supports a variety of output variables:
| Variable | Unit | Description |
|---|---|---|
p |
Pa | Pressure |
T |
K | Temperature |
x |
1 | Composition vector |
atoms |
1 | Number of atoms per formula unit |
V |
m^3/mol | Molar volume |
rho |
kg/m^3 | Density |
beta |
1/Pa | Isothermal compressibility |
alpha |
1/K | Thermal expansivity |
kappa&mu |
Pa | Adiabatic compression modulus and shear modulus |
vp&vs |
m/s | P- and S-wave velocities |
G |
J/mol | Molar Gibbs energy |
S |
J/mol/K | Molar entropy |
Cp |
J/mol/K | Isobaric molar heat capacity |
Cv |
J/mol/K | Isochoric molar heat capacity |
gamma |
1 | Grüneisen parameter |
Finally, you can tell the tool to loop over a range of pressures
and/or temperatures using a combination of the -P=..., -toP=...,
-nP=..., -T=..., -toT=... and -nT=... options. For example,
the following command would display a graphical representation of
forsterite volume as a function of pressure using
GMT plotting tools and
ImageMagick:
eos prop -db=SLB11 fo -P=0 -toP=25e9Pa -nP=251 -T=300K -o=p,V \
| psxy -JX15c -R0/25e9/3.5e-5/4.5e-5 -B'5e9:p/Pa:/0.5e-5:m@+3@+/mol:' \
| display -
The opti and bmpv tools can be used to produce phase
diagrams. opti takes a phase collection, pressure, temperature and
bulk composition as input and computes a stable phase
assemblage. bmpv is an interactive graphical viewer for such
data. The following command, for example, produces a coarsely resolved
diagram of stable phases with the bulk composition Mg2SiO4:
cfg=(-db=SLB11 -P=0 -toP=25e9Pa -nP=26 -T=300K -toT=2300 -nT=21)
mpiexec -n $(nproc) eos opti ${cfg[@]} -bulk=Mg2SiO4 -o=p,T,phases \
| eos bmpv ${cfg[@]}
Both the prop and opti tools can run computations in parallel when
invoked in an MPI environment, provided the support library for MPI is
available for the host platform. Note that the output of the tools
will not necessarily be in the same sequence as their input in this
case; it is advisable to echo the input parameters through suitable
settings with the -o=... option.
As with the prop tool, the output of the opti tool can be
controlled using different arguments to the -o=... command line
option:
| Variable | Unit | Description |
|---|---|---|
p |
Pa | Pressure |
T |
K | Temperature |
bulk |
formula | Chemical bulk composition formula |
xbulk |
1 | Bulk composition interval position mapped to [0, 1] |
x |
1 | Composition vector of stable phase assemblage |
xtree |
string | Textual representation of stable phase assemblage |
phases |
bitmap | Bit field with bits set for each phase present |
endmembers |
bitmap | Bit field with bits set for each endmember present |
When output from opti is generated with the -o=p,T,x option (which
is the default), the result can not only be piped into prop, but
also loaded by that tool as a composition grid:
mpiexec -n $(nproc) eos opti -db=SLB11 \
-P=0 -toP=25e9Pa -nP=26 -T=1000K -toT=2000 -nT=11 \
-bulk='(Mg0.9Fe0.1)2SiO4' -o=p,T,x >grid.txt
mpiexec -n $(nproc) eos prop -db=SLB11 -x=grid.txt \
-P=10e9Pa -T=300K -toT=1300K -nT=11 -o=p,T,rho
prop maps every requested pressure, temperature point to the nearest
grid point to determine the associated composition vector.
Note that MMA-EoS prints some progress messages on standard error
while data and comments describing the data go to standard output. If
you redirect output, make sure not to mix the two streams (for example
use nohup with two redirections like this >output.txt 2>error.log
to prevent random interleaving of output).
MMA-EoS deals with compositions as chemical formulas. The form
tool can convert between the molar format and mass or atomic
fractions, for example the bulk composition Mg2SiO4 can be converted
to a list of mass fractions like this:
eos form -to=mass -flat -table Mg2SiO4
Of course the other direction works as well:
eos form -from=mass 0.454874 O 0.345504 Mg Si
The fraction of the last chemical component passed on the command line can be omitted and is assumed to be one minus the sum of the other fractions.
As an alternative to specifying the composition manually, MMA-EoS
also comes with a small database of abbreviations for common bulk
compositions; for example -bulk=pyrolite/fms is equivalent to
-bulk=(MgO)1.3424(FeO)0.1662(SiO2).
Library Use
MMA-EoS is highly modular. The command line tools that come with it by default are nothing but thin wrapper scripts for a set of F# assemblies:
EoS.Core.dllcontains the infrastructure concerning chemical formulas, physical units and thermoelastic phases.EoS.CommandLine.dllcontains code for parsing command line arguments and interfacing with MPI.EoS.Optimization.dllprovides Gibbs energy minimization facilities; it depends on the LPSolve library to handle linear optimization problems efficiently.EoS.DebyeModel.dllimplements an equation of state for solids based on the Birch-Murnaghan elastic energy approximation and the Mie-Debye-Grüneisen model of lattice vibrations.EoS.PolynomialModel.dllimplements equations of state of solids based on the Birch-Murnaghan elastic energy approximation and polynomial representations of heat capacity, thermal expansivity and elastic parameters.
Depending on what you want to do, you will have to link against one or
more of these libraries. XML documentation comes with the
assemblies. Building MMA-EoS from source will also render a simple
HTML representation of the documentation comments in
the source. A good starting point to explore the API is the EoS.Phases
namespace.
The following example will output the volume of a phase as specified by command line options:
#r "EoS.Core"
#r "EoS.CommandLine"
open System
open FSharp.Data.UnitSystems.SI.UnitSymbols
open EoS.Phases
open EoS.CommandLine
let db = Flag.DatabaseOpt "db" "Model parameter database"
let p = Flag.PressureOpt "P" 1.0e5<Pa> "Pressure"
let T = Flag.TemperatureOpt "T" 300.0<K> "Temperature"
let main (args : string[]) =
let pname = if args.Length > 0 then args[0] else "fo"
let phase = db.Value.TryGetObject<IPhase>(pname).Value
let p, T = p.Value, T.Value
printfn "V(p = %g Pa, T = %g K) = %g m^3/mol" <|
p / 1.0<Pa> <| T / 1.0<K> <|
phase.Volume(p, T) / 1.0<m^3/mol>
0
Flag.WithCommandLineArgs main
Background Information
Detailed information about the physical models and implementation strategy behind MMA-EoS as well as a couple of application examples can be found in this article:
T. C. Chust, G. Steinle‐Neumann, D. Dolejs, B. S. Schuberth, and H. P. Bunge. MMA‐EoS: A computational framework for mineralogical thermodynamics. Journal of Geophysical Research: Solid Earth, 122:9881-9920, 2017. doi:10.1002/2017JB014501
Community Support
A user support forum for MMA-EoS is available in the form of a Slack workspace. You are welcome to use the open invitation and join the discussion!