[cig-commits] [commit] master: Manual Copy Editting (6a07d4e)
cig_noreply at geodynamics.org
cig_noreply at geodynamics.org
Tue Dec 9 21:56:51 PST 2014
Repository : https://github.com/geodynamics/burnman
On branch : master
Link : https://github.com/geodynamics/burnman/compare/5e4f39cd2f0083b2ce1af9190304e7f1451739f4...96a37e8bbbe737b38fba242d3e2f77955d11c99a
>---------------------------------------------------------------
commit 6a07d4e0817ca72d7d472834d5aa0f63c1ac9b80
Author: Cayman Unterborn <kmanunterborn at gmail.com>
Date: Tue Dec 9 19:58:01 2014 -0800
Manual Copy Editting
Fixed citations, added units to classes that were missing
>---------------------------------------------------------------
6a07d4e0817ca72d7d472834d5aa0f63c1ac9b80
burnman/__init__.py | 4 ++--
burnman/averaging_schemes.py | 7 +++++--
burnman/birch_murnaghan.py | 19 ++++++++++++++++---
burnman/geotherm.py | 6 +++---
burnman/material.py | 14 +++++++-------
burnman/mineral.py | 6 +++---
burnman/mineral_helpers.py | 2 +-
burnman/seismic.py | 2 +-
sphinx/averaging.rst | 2 +-
sphinx/background.rst | 39 ++++++++++++++++++++-------------------
sphinx/examples.rst | 2 +-
11 files changed, 60 insertions(+), 43 deletions(-)
diff --git a/burnman/__init__.py b/burnman/__init__.py
index 5a566e6..7bd3517 100644
--- a/burnman/__init__.py
+++ b/burnman/__init__.py
@@ -5,8 +5,8 @@
"""BurnMan
=======
-BurnMan is an open source mineral physics toolbox written in Python to
-determine seismic velocities for the lower mantle. BurnMan calculates the
+BurnMan is an open source mineral physics toolbox written in Python which
+determines seismic velocities for the lower mantle. BurnMan calculates the
isotropic thermoelastic moduli by solving the equations-of-state for a
mixture of minerals defined by the user. The user may select from a list of
minerals applicable to the lower mantle included or easily define one of
diff --git a/burnman/averaging_schemes.py b/burnman/averaging_schemes.py
index ef07f49..b61f05f 100644
--- a/burnman/averaging_schemes.py
+++ b/burnman/averaging_schemes.py
@@ -100,14 +100,15 @@ class AveragingScheme:
return np.sum(np.array(alphas)*np.array(volumes)) / total_vol
def average_heat_capacity_v(self, fractions, c_v):
+ #TODO: double-check that the formula we use is appropriate here.
"""
Averages the heat capacities at constant volume C_V by molar fractions
as in eqn. (16) in Ita'92.
- TODO: double-check that the formula we use is appropriate here.
Parameters
----------
+
fractions : list of floats
List of molar fractions of each phase in the composite (should sum to 1.0).
c_v : list of floats
@@ -115,16 +116,18 @@ class AveragingScheme:
Returns
-------
+
C_v : float
heat capacity at constant volume of the bulk [J/K/mol]
"""
return np.sum(np.array(fractions)*np.array(c_v))
def average_heat_capacity_p(self, fractions, c_p):
+ #TODO: double-check that the formula we use is correct.
"""
Averages the heat capacities at constant pressure C_P by molar fractions.
- TODO: double-check that the formula we use is correct.
+
Parameters
----------
diff --git a/burnman/birch_murnaghan.py b/burnman/birch_murnaghan.py
index 29789ce..d4705bc 100644
--- a/burnman/birch_murnaghan.py
+++ b/burnman/birch_murnaghan.py
@@ -78,15 +78,28 @@ class BirchMurnaghanBase(eos.EquationOfState):
function, so if this is the case, you should use that. For more see :class:`burnman.birch_murnaghan.BM2` and :class:`burnman.birch_murnaghan.BM3`.
"""
def volume(self,pressure, temperature, params):
+ """
+ Returns volume [m^3] as a function of pressure [Pa]
+ """
return volume(pressure,params)
def isothermal_bulk_modulus(self,pressure,temperature, volume, params):
+ """
+ Returns adiabatic bulk modulus [Pa] as a function of pressure [Pa]
+ and volume [m^3].
+ """
return bulk_modulus(volume, params)
def adiabatic_bulk_modulus(self,pressure, temperature, volume, params):
+ """
+ Returns adiabatic bulk modulus of the mineral [Pa]
+ """
return bulk_modulus(volume,params)
def shear_modulus(self,pressure, temperature, volume, params):
+ """
+ Returns shear modulus of the mineral [Pa]
+ """
if(self.order == 2):
return shear_modulus_second_order(volume,params)
elif(self.order == 3):
@@ -94,19 +107,19 @@ class BirchMurnaghanBase(eos.EquationOfState):
def heat_capacity_v(self,pressure, temperature, volume, params):
"""
- Since this equation of state does not have temperature effects, simply return a very large number.
+ Since this equation of state does not have temperature effects, simply return a very large number. [J/K/mol]
"""
return 1.e99
def heat_capacity_p(self,pressure, temperature, volume, params):
"""
- Since this equation of state does not have temperature effects, simply return a very large number.
+ Since this equation of state does not have temperature effects, simply return a very large number. [J/K/mol]
"""
return 1.e99
def thermal_expansivity(self,pressure, temperature, volume, params):
"""
- Since this equation of state does not have temperature effects, simply return zero.
+ Since this equation of state does not have temperature effects, simply return zero. [1/K]
"""
return 0.
diff --git a/burnman/geotherm.py b/burnman/geotherm.py
index 206e647..e057701 100644
--- a/burnman/geotherm.py
+++ b/burnman/geotherm.py
@@ -71,7 +71,7 @@ def adiabatic(pressures, T0, rock):
T0 : float
An anchor temperature, corresponding to the temperature of the first
- pressure in the list.
+ pressure in the list. [K]
rock : :class:`burnman.composite`
Material for which we compute the adiabat. From this material we
@@ -105,10 +105,10 @@ def dTdP(temperature, pressure, rock):
----------
pressure : float
- The pressure at which to evaluate dT/dP.
+ The pressure at which to evaluate dT/dP. [Pa]
temperature : float
- The temperature at which to evaluate dT/dP.
+ The temperature at which to evaluate dT/dP. [K]
rock : :class:`burnman.composite`
Material for which we compute dT/dP
diff --git a/burnman/material.py b/burnman/material.py
index dd4391d..bf3ceb0 100644
--- a/burnman/material.py
+++ b/burnman/material.py
@@ -15,9 +15,9 @@ class Material:
Attributes
----------
pressure : float
- The current pressure as set by :func:`~burnman.Material.set_state`.
+ The current pressure as set by :func:`~burnman.Material.set_state`. [Pa]
temperature : float
- The current temperature as set by :func:`~burnman.Material.set_state`.
+ The current temperature as set by :func:`~burnman.Material.set_state`. [K]
"""
def __init__(self):
@@ -54,7 +54,7 @@ class Material:
def print_minerals_of_current_state(self):
"""
- Print a human-readable representation of this Material at the current p, T as a list of minerals.
+ Print a human-readable representation of this Material at the current P, T as a list of minerals.
This requires set_state() has been called before.
"""
(frs,mins) = self.unroll()
@@ -72,9 +72,9 @@ class Material:
Parameters
----------
pressure : float
- The desired pressure in Pa.
+ The desired pressure in [Pa].
temperature : float
- The desired temperature in K.
+ The desired temperature in [K].
"""
self.pressure = pressure
self.temperature = temperature
@@ -102,7 +102,7 @@ class Material:
def density(self):
"""
Returns the density of this material. Note that the return value of this function may depend on the current
- state (temperature, pressure).
+ state (temperature, pressure). [kg/m^3]
Notes
-----
@@ -111,7 +111,7 @@ class Material:
Returns
-------
density : float
- The density of this material in kg/m^3
+ The density of this material in [kg/m^3]
"""
raise NotImplementedError("need to implement density() in derived class!")
diff --git a/burnman/mineral.py b/burnman/mineral.py
index e641665..d23a383 100644
--- a/burnman/mineral.py
+++ b/burnman/mineral.py
@@ -33,9 +33,9 @@ class Mineral(Material):
reference volume should be in m^3/(mol molecule) and not in unit cell
volume and 'n' should be the number of atoms per molecule. Frequently in
the literature the reference volume is given in Angstrom^3 per unit cell.
- To convert this to m^3/(mol molecule) you should multiply by 10^(-30) *
- N_a / Z, where N_a is Avogadro's number and Z is the number of atoms per
- unit cell. You can look up Z in many places, including www.mindat.org
+ To convert this to m^3/(mol of molecule) you should multiply by 10^(-30) *
+ N_a / Z, where N_a is Avogadro's number and Z is the number of formula units per
+ unit cell. You can look up Z in many places, including www.mindat.org
"""
def __init__(self):
diff --git a/burnman/mineral_helpers.py b/burnman/mineral_helpers.py
index 7e3eab4..ac5f400 100644
--- a/burnman/mineral_helpers.py
+++ b/burnman/mineral_helpers.py
@@ -123,7 +123,7 @@ class HelperFeDependent(Material):
"""
Helper to implement a rock that does iron exchange (two minerals with
- changing iron content based on p,T).
+ changing iron content based on P,T).
Classes deriving from this helper need to implement
create_inner_material() and provide a function in __init__ that computes
diff --git a/burnman/seismic.py b/burnman/seismic.py
index 0fe0a44..227628e 100644
--- a/burnman/seismic.py
+++ b/burnman/seismic.py
@@ -178,7 +178,7 @@ class Seismic1DModel:
Parameters
----------
depth : float or array of floats
- Depth[s] [m] to evaluate gravity at.
+ Depth(s) [m] to evaluate gravity at.
Returns
-------
diff --git a/sphinx/averaging.rst b/sphinx/averaging.rst
index 496713b..5aca3cc 100644
--- a/sphinx/averaging.rst
+++ b/sphinx/averaging.rst
@@ -6,7 +6,7 @@ However, as soon as we have a composite material (e.g., a rock), the determinati
The bulk and shear modulus of a rock are dependent on the specific geometry of the grains in the rock, so there is no general
formula for its averaged elastic properties. Instead, we must choose from a number of averaging schemes if we want a single value,
or use bounding methods to get a range of possible values. The module :mod:`burnman.averaging_schemes` provides a number of different
-averages and bounds for a composite.
+average and bounding schemes for determining a composite rock's physical parameters.
Base class
-----------
diff --git a/sphinx/background.rst b/sphinx/background.rst
index 2f768af..07af973 100644
--- a/sphinx/background.rst
+++ b/sphinx/background.rst
@@ -41,7 +41,7 @@ where :math:`V` is the volume at a given pressure and :math:`V_0` is the
volume at a reference state (:math:`P = 10^5` Pa , :math:`T` = 300 K). The
pressure and elastic moduli are derived from a third order Taylor expansion of
Helmholtz free energy in :math:`f` and evaluating the appropriate volume and
-strain derivatives (see, e.g., :cite:`poirier1991`). For an isotropic
+strain derivatives (see, e.g., :cite:`Poirier1991`). For an isotropic
material one obtains for the pressure, isothermal bulk modulus, and shear
modulus:
@@ -135,7 +135,7 @@ where :math:`\alpha` is the coefficient of thermal expansion
There is no difference between the isothermal and adiabatic shear moduli for
an isotropic solid. All together this makes an eleven parameter EoS model,
which is summarized in the Table below. For more details on the
-EoS, we refer readers to :cite:`stixrude2005`.
+EoS, we refer readers to :cite:`Stixrude2005`.
.. _table-parameters:
@@ -232,7 +232,7 @@ where :math:`\rho_i` is the density and :math:`\mu_i` is the molar mass of the :
Unlike density and volume, there is no straightforward way to average the bulk and shear moduli of a multiphase rock, as it depends on the specific distribution and orientation of the constituent minerals.
-BurnMan allows several schemes for averaging the elastic moduli: the Voigt and Reuss bounds, the Hashin-Shtrikman bounds, the Voigt-Reuss-Hill average, and the Hashin-Shtrikman average :cite:`watt1976`.
+BurnMan allows several schemes for averaging the elastic moduli: the Voigt and Reuss bounds, the Hashin-Shtrikman bounds, the Voigt-Reuss-Hill average, and the Hashin-Shtrikman average :cite:`Watt1976`.
The Voigt average, assuming constant strain across all phases, is defined as
@@ -254,7 +254,7 @@ The Voigt-Reuss-Hill average is the arithmetic mean of Voigt and Reuss bounds:
X_{VRH} = \frac{1}{2} \left( X_V + X_R \right).
:label: vrh
-The Hashin-Shtrikman bounds make an additional assumption that the distribution of the phases is statistically isotropic, and are usually much narrower than the Voigt and Reuss bounds :cite:`{watt1976}`.
+The Hashin-Shtrikman bounds make an additional assumption that the distribution of the phases is statistically isotropic, and are usually much narrower than the Voigt and Reuss bounds :cite:`Watt1976`.
This may be a poor assumption in regions of Earth with high anisotropy, such as the lowermost mantle, though they are rather more physically motivated than the commonly-used Voigt-Reuss-Hill average.
In most instances, the Voigt-Reuss-Hill average and the arithmetic mean of the Hashin-Shtrikman bounds are quite close to each other with the pure arithmetic mean (linear averaging) being well outside of both Hashin-Shtrikman and Voigt-Reuss-Hill.
@@ -284,12 +284,12 @@ In BurnMan one can correct the calculated acoustic velocity values to those for
.. math::
V_{S/P}=V_{S/P}^{\mathrm{uncorr.}}\left(1-\frac{1}{2}\cot(\frac{\beta\pi}{2})\frac{1}{Q_{S/P}}(\omega)\right).
-Similar to :cite:`matas2007`, we use a :math:`\beta` value of 0.3, which falls in the range of values of :math:`0.2` to :math:`0.4` proposed for the lower mantle (e.g. :cite:`karato1990`).
+Similar to :cite:`Matas2007`, we use a :math:`\beta` value of 0.3, which falls in the range of values of :math:`0.2` to :math:`0.4` proposed for the lower mantle (e.g. :cite:`Karato1990`).
The correction is implemented for Q values of PREM for the lower mantle.
As :math:`Q_S` is smaller than :math:`Q_P`, the correction is more significant for S waves.
In both cases, though, the correction is minor compared to, for example, uncertainties in the temperature (corrections) and mineral physical parameters.
-More involved models of relaxation mechanisms can be implemented, but lead to the inclusion of more poorly constrained parameters, :cite:`matas2007a`.
-While attenuation can be ignored in many applications :cite:`trampert2001`, it might play a significant role in explaining strong variations in seismic velocities in the lowermost mantle :cite:`davies2012`.
+More involved models of relaxation mechanisms can be implemented, but lead to the inclusion of more poorly constrained parameters, :cite:`Matas2007a`.
+While attenuation can be ignored in many applications :cite:`Trampert2001`, it might play a significant role in explaining strong variations in seismic velocities in the lowermost mantle :cite:`Davies2012`.
.. _ref-methods-user-input:
@@ -303,16 +303,17 @@ Mineralogical composition
^^^^^^^^^^^^^^^^^^^^^^^^^
A number of pre-defined minerals are included in the mineral library and users can create their own.
-The library includes wrapper functions to include a transition from the high-spin mineral to the low-spin mineral :cite:`lin2013` or to combine minerals for a given iron number.
+The library includes wrapper functions to include a transition from the high-spin mineral to the low-spin mineral :cite:`Lin2013` or to combine minerals for a given iron number.
-*Standard minerals* -- The 'standard' mineral format includes a list of parameters given in Table :tab:`param`.
+*Standard minerals* -- The 'standard' mineral format includes a list of parameters given in the above table.
Each mineral includes a suggested EoS with which the mineral parameters are derived.
For some minerals the parameters for the thermal corrections are not yet measured or calculated, and therefore the corrections can not be applied.
An occasional mineral will not have a measured or calculated shear moduli, and therefore can only be used to compute densities and bulk sound velocities.
The mineral library is subdivided by citation.
BurnMan includes the option to produce a \LaTeX\; table of the mineral parameters used.
BurnMan can be easily setup to incorporate uncertainties for these parameters.
+
*Minerals with a spin transition* -- A standard mineral for the high spin and low spin must be defined separately.
These minerals are "wrapped," so as to switch from the high spin to high spin mineral at a give pressure.
While not realistic, for the sake of simplicity, the spin transitions are considered to be sharp at a given pressure.
@@ -327,14 +328,14 @@ Alternatively one can calculate the iron mol fraction from the distribution coef
:label: KD
-We adopt the formalism of :cite:`nakajima2012` choosing a reference distribution coefficient :math:`K_{D0}` and standard state volume change (:math:`\Delta \upsilon^{0}`) for the Fe-Mg exchange between perovskite and ferropericlase
+We adopt the formalism of :cite:`Nakajima2012` choosing a reference distribution coefficient :math:`K_{D0}` and standard state volume change (:math:`\Delta \upsilon^{0}`) for the Fe-Mg exchange between perovskite and ferropericlase
.. math::
K_{D}={K_D}_0 \:\exp\left(\frac{(P_0-P)\Delta \upsilon^{0}}{RT}\right),
:label: KD2
where :math:`R` is the gas constant and :math:`P_0` the reference pressure.
-As a default, we adopt the average :math:`\Delta \upsilon^{0}` of :cite:`{nakajima2012}` of :math:`2\cdot10^{-7}` :math:`^3 mol^{-1}` and suggest using their :math:`{K_D}_0` value of :math:`0.5`.
+As a default, we adopt the average :math:`\Delta \upsilon^{0}` of :cite:`Nakajima2012` of :math:`2\cdot10^{-7}` :math:`m^3 mol^{-1}` and suggest using their :math:`{K_D}_0` value of :math:`0.5`.
The multiphase mixture of these minerals can be built by the user in three ways:
@@ -361,7 +362,7 @@ As elsewhere, BurnMan provides a number of built-in geotherms, as well as the ab
A geotherm in BurnMan is an object that returns temperature as a function of pressure.
Alternatively, the user could ignore the geothermal and compute elastic velocities for a range of temperatures at any give pressure.
-Currently, we include geotherms published by :cite:`brown1981` and :cite:`anderson1982earth`.
+Currently, we include geotherms published by :cite:`Brown1981` and :cite:`anderson1982earth`.
Alternatively one can use an adiabatic gradient defined by the thermoelastic properties of a given mineralogical model.
For a homogeneous material, the adiabatic temperature profile is given by integrating the ordinary differential equation (ODE)
@@ -392,21 +393,21 @@ Quantitative misfits between two profiles include an L2-norm and a chi-squared m
A seismic model in BurnMan is
an object that provides pressure, density, and seismic velocities (:math:`V_P, V_\Phi, V_S`) as a function of depth.
-To compare to seismically constrained profiles, BurnMan provides the 1D seismic velocity model PREM :cite:`{dziewonski1981}`.
+To compare to seismically constrained profiles, BurnMan provides the 1D seismic velocity model PREM :cite:`Dziewonski1981`.
One can choose to evaluate :math:`V_P, V_\Phi, V_S, \rho, K_S` and/or :math:`G`.
-The user can input their own seismic profile, an example of which is included for AK135 :cite:`kennett1995`.
+The user can input their own seismic profile, an example of which is included using AK135 :cite:`Kennett1995`.
Besides standardized 1D radial profiles, one can also compare to regionalized average profiles for the lower mantle.
This option accommodates the observation that the lowermost mantle can be clustered into two regions, a 'slow' region, which represents the so-called Large Low Shear Velocity Provinces, and 'fast' region, the continuous surrounding region where slabs might subduct :cite:`lekic2012`.
-This clustering as well as the averaging of the 1D model occurs over five tomographic S wave velocity models (SAW24B16: :cite:`megnin2000`; HMSL-S: :cite:`houser2008`; S362ANI: :cite:`kustowski2008`; GyPSuM: :cite:`simmons2010`; S40RTS: :cite:`ritsema2011`).
+This clustering as well as the averaging of the 1D model occurs over five tomographic S wave velocity models (SAW24B16: :cite:`megnin2000`; HMSL-S: :cite:`houser2008`; S362ANI: :cite:`Kustowski2008`; GyPSuM: :cite:`Simmons2010`; S40RTS: :cite:`Ritsema2011`).
The strongest deviations from PREM occur in the lowermost 1000 km.
-Using the 'fast' and 'slow' S wave velocity profiles is therefore most important when interpreting the lowermost mantle. Suggestion of compositional variation between these regions comes from seismology :cite:`to2005,he2012` as well as geochemistry :cite:`deschamps2012,jackson2010`.
-Based on thermo-chemical convection models, :cite:`styles2011` also show that averaging profiles in thermal boundary layers may cause problems for seismic interpretation.
+Using the 'fast' and 'slow' S wave velocity profiles is therefore most important when interpreting the lowermost mantle. Suggestion of compositional variation between these regions comes from seismology :cite:`to2005,He2012` as well as geochemistry :cite:`Deschamps2012,jackson2010`.
+Based on thermo-chemical convection models, :cite:`Styles2011` also show that averaging profiles in thermal boundary layers may cause problems for seismic interpretation.
-We additionally apply cluster analysis to and provide models for P wave velocity based on two tomographic models (MIT-P08: :cite:`li2008`; GyPSuM: :cite:`simmons2012`).
+We additionally apply cluster analysis to and provide models for P wave velocity based on two tomographic models (MIT-P08: :cite:`Li2008`; GyPSuM: :cite:`Simmons2012`).
The clustering results correlate well with the fast and slow regions for S wave velocities; this could well be due to the fact that the initial model for the P wave velocity models is scaled from S wave tomographic velocity models.
Additionally, the variations in P wave velocities are a lot smaller than for S waves.
For this reason using these adapted models is most important when comparing the S wave velocities.
-While interpreting lateral variations of seismic velocity in terms of composition and temperature is a major goal :cite:`trampert2004,mosca2012`, to determine the bulk composition the current challenge appears to be concurrently fitting absolute P and S wave velocities and incorporate the significant uncertainties in mineral physical parameters).
+While interpreting lateral variations of seismic velocity in terms of composition and temperature is a major goal :cite:`Trampert2004,Mosca2012`, to determine the bulk composition the current challenge appears to be concurrently fitting absolute P and S wave velocities and incorporate the significant uncertainties in mineral physical parameters).
diff --git a/sphinx/examples.rst b/sphinx/examples.rst
index 526856e..96e1b99 100644
--- a/sphinx/examples.rst
+++ b/sphinx/examples.rst
@@ -52,7 +52,7 @@ link to source code: `tutorial/step_2.py <../../../tutorial/step_2.py>`_
.. automodule:: tutorial.step_3
-After changing the standard deviations for :math:`K\prime` and :math:`G\prime` to 0.2, the following figure of velocities for 1000 realizations is produced:
+After changing the standard deviations for :math:`K'` and :math:`G'` to 0.2, the following figure of velocities for 1000 realizations is produced:
.. image:: figures/tut-step3.png
More information about the CIG-COMMITS
mailing list