added solution docstrings

Author: bobmyhill

burnman/data/input_raw_endmember_datasets/hpx_eos_to_burnman.py

@@ -179,9 +179,11 @@ def replace_numbers(match):
     n_data = len(data)
 
     noods = []
+    names = []
     for ind in start_indices:
         i = ind
         name = data[i][0]
+        names.append(name)
         n_mbrs = int(data[i][1])
         logging.debug(f"Solution: {name}")
         logging.debug(f"Number of endmembers: {n_mbrs}")
@@ -380,8 +382,24 @@ def replace_numbers(match):
 
             mbr_initializations.append(f'[{mbr}, "{site_formula}"]')
 
+        # Create docstring
+        doc = '        """\n'
+        doc += f"        Initialisation for a {name} solution object.\n"
+
+        doc += "        Contains the following endmembers with associated site occupancies :\n"
+
+        for mbr_initialization in mbr_initializations:
+            doc += f"        * {mbr_initialization}\n"
+
+        if formulation == "asf":
+            doc += f"\n        This is implemented as an asymmetric solution.\n"
+        else:
+            doc += f"\n        This is implemented as a symmetric solution.\n"
+        doc += '        """\n'
+
         out_ss += f"class {name}(Solution):\n"
         out_ss += "    def __init__(self, molar_fractions=None):\n"
+        out_ss += doc
         out_ss += f'        self.name = "{name}"\n'
         if formulation == "asf":
             out_ss += "        self.solution_model = AsymmetricRegularSolution(\n"
@@ -427,9 +445,15 @@ def replace_numbers(match):
         f"{underline}\n"
         "\n"
         "HPx-eos solutions using endmembers from\n"
-        f"dataset {mbr_dataset}.\n"
-        "The values in this document are all in S.I. units,\n"
-        "unlike those in the original THERMOCALC file.\n"
+        f"dataset {mbr_dataset}.\n\n"
+        "Contains the following solutions:\n"
+    )
+    for name in names:
+        preamble += f"* {name}\n"
+
+    preamble += (
+        "\nThe values in this document are all in S.I. units,\n"
+        "unlike those in the original THERMOCALC file.\n\n"
         "This file is autogenerated using hpx_eos_to_burnman.py\n"
         '"""\n\n'
         f"import numpy as np\n"

burnman/minerals/ig50NCKFMASHTOCr.py

@@ -9,8 +9,28 @@
 
 HPx-eos solutions using endmembers from
 dataset HGP_2018_ds633.
+
+Contains the following solutions:
+* pl4tr
+* k4tr
+* pli
+* plc
+* ol
+* ksp
+* mu
+* bi
+* g
+* ep
+* cd
+* opx
+* cpx
+* spn
+* hb
+* ilm
+
 The values in this document are all in S.I. units,
 unlike those in the original THERMOCALC file.
+
 This file is autogenerated using hpx_eos_to_burnman.py
 """
 
@@ -432,6 +452,15 @@
 
 class pl4tr(Solution):
     def __init__(self, molar_fractions=None):
+        """
+        Initialisation for a pl4tr solution object.
+        Contains the following endmembers with associated site occupancies :
+        * [HGP_2018_ds633.ab(), "[Naa][Altb1/4Sitb3/4]"]
+        * [HGP_2018_ds633.an(), "[Caa][Altb1/2Sitb1/2]"]
+        * [HGP_2018_ds633.san(), "[Ka][Altb1/4Sitb3/4]"]
+
+        This is implemented as an asymmetric solution.
+        """
         self.name = "pl4tr"
         self.solution_model = AsymmetricRegularSolution(
             endmembers=[
@@ -452,6 +481,15 @@ def __init__(self, molar_fractions=None):
 
 class k4tr(Solution):
     def __init__(self, molar_fractions=None):
+        """
+        Initialisation for a k4tr solution object.
+        Contains the following endmembers with associated site occupancies :
+        * [HGP_2018_ds633.ab(), "[Naa][Altb1/4Sitb3/4]"]
+        * [HGP_2018_ds633.an(), "[Caa][Altb1/2Sitb1/2]"]
+        * [HGP_2018_ds633.san(), "[Ka][Altb1/4Sitb3/4]"]
+
+        This is implemented as an asymmetric solution.
+        """
         self.name = "k4tr"
         self.solution_model = AsymmetricRegularSolution(
             endmembers=[
@@ -472,6 +510,15 @@ def __init__(self, molar_fractions=None):
 
 class pli(Solution):
     def __init__(self, molar_fractions=None):
+        """
+        Initialisation for a pli solution object.
+        Contains the following endmembers with associated site occupancies :
+        * [abhI, "[Na]"]
+        * [HGP_2018_ds633.an(), "[Ca]"]
+        * [HGP_2018_ds633.san(), "[K]"]
+
+        This is implemented as an asymmetric solution.
+        """
         self.name = "pli"
         self.solution_model = AsymmetricRegularSolution(
             endmembers=[
@@ -489,6 +536,15 @@ def __init__(self, molar_fractions=None):
 
 class plc(Solution):
     def __init__(self, molar_fractions=None):
+        """
+        Initialisation for a plc solution object.
+        Contains the following endmembers with associated site occupancies :
+        * [HGP_2018_ds633.abh(), "[Na]"]
+        * [anC, "[Ca]"]
+        * [HGP_2018_ds633.san(), "[K]"]
+
+        This is implemented as an asymmetric solution.
+        """
         self.name = "plc"
         self.solution_model = AsymmetricRegularSolution(
             endmembers=[
@@ -506,6 +562,16 @@ def __init__(self, molar_fractions=None):
 
 class ol(Solution):
     def __init__(self, molar_fractions=None):
+        """
+        Initialisation for a ol solution object.
+        Contains the following endmembers with associated site occupancies :
+        * [HGP_2018_ds633.mont(), "[Mgmone][Camtwo]"]
+        * [HGP_2018_ds633.fa(), "[Femone][Femtwo]"]
+        * [HGP_2018_ds633.fo(), "[Mgmone][Mgmtwo]"]
+        * [cfm, "[Mgmone][Femtwo]"]
+
+        This is implemented as a symmetric solution.
+        """
         self.name = "ol"
         self.solution_model = SymmetricRegularSolution(
             endmembers=[
@@ -525,6 +591,15 @@ def __init__(self, molar_fractions=None):
 
 class ksp(Solution):
     def __init__(self, molar_fractions=None):
+        """
+        Initialisation for a ksp solution object.
+        Contains the following endmembers with associated site occupancies :
+        * [HGP_2018_ds633.san(), "[K]"]
+        * [HGP_2018_ds633.abh(), "[Na]"]
+        * [anC, "[Ca]"]
+
+        This is implemented as an asymmetric solution.
+        """
         self.name = "ksp"
         self.solution_model = AsymmetricRegularSolution(
             endmembers=[
@@ -542,6 +617,18 @@ def __init__(self, molar_fractions=None):
 
 class mu(Solution):
     def __init__(self, molar_fractions=None):
+        """
+        Initialisation for a mu solution object.
+        Contains the following endmembers with associated site occupancies :
+        * [HGP_2018_ds633.mu(), "[Ka][Almtwoa][Almtwob][Sitone1/2Altone1/2]2"]
+        * [HGP_2018_ds633.cel(), "[Ka][Mgmtwoa][Almtwob][Sitone]2"]
+        * [HGP_2018_ds633.fcel(), "[Ka][Femtwoa][Almtwob][Sitone]2"]
+        * [HGP_2018_ds633.pa(), "[Naa][Almtwoa][Almtwob][Sitone1/2Altone1/2]2"]
+        * [mam, "[Caa][Almtwoa][Almtwob][Altone]2"]
+        * [fmu, "[Ka][Almtwoa][Fethreemtwob][Sitone1/2Altone1/2]2"]
+
+        This is implemented as an asymmetric solution.
+        """
         self.name = "mu"
         self.solution_model = AsymmetricRegularSolution(
             endmembers=[
@@ -580,6 +667,18 @@ def __init__(self, molar_fractions=None):
 
 class bi(Solution):
     def __init__(self, molar_fractions=None):
+        """
+        Initialisation for a bi solution object.
+        Contains the following endmembers with associated site occupancies :
+        * [HGP_2018_ds633.phl(), "[Mgmthree][Mgmonetwo]2[Sit1/2Alt1/2]2[Ohv]2"]
+        * [annm, "[Femthree][Femonetwo]2[Sit1/2Alt1/2]2[Ohv]2"]
+        * [obi, "[Femthree][Mgmonetwo]2[Sit1/2Alt1/2]2[Ohv]2"]
+        * [HGP_2018_ds633.east(), "[Almthree][Mgmonetwo]2[Alt]2[Ohv]2"]
+        * [tbi, "[Timthree][Mgmonetwo]2[Sit1/2Alt1/2]2[Ov]2"]
+        * [fbi, "[Fethreemthree][Mgmonetwo]2[Alt]2[Ohv]2"]
+
+        This is implemented as a symmetric solution.
+        """
         self.name = "bi"
         self.solution_model = SymmetricRegularSolution(
             endmembers=[
@@ -603,6 +702,18 @@ def __init__(self, molar_fractions=None):
 
 class g(Solution):
     def __init__(self, molar_fractions=None):
+        """
+        Initialisation for a g solution object.
+        Contains the following endmembers with associated site occupancies :
+        * [HGP_2018_ds633.py(), "[Mgmone]3[Almtwo]2"]
+        * [HGP_2018_ds633.alm(), "[Femone]3[Almtwo]2"]
+        * [HGP_2018_ds633.gr(), "[Camone]3[Almtwo]2"]
+        * [HGP_2018_ds633.andr(), "[Camone]3[Fethreemtwo]2"]
+        * [knom, "[Mgmone]3[Crmtwo]2"]
+        * [tig, "[Mgmone]3[Almtwo1/2Mgmtwo1/4Timtwo1/4]2"]
+
+        This is implemented as an asymmetric solution.
+        """
         self.name = "g"
         self.solution_model = AsymmetricRegularSolution(
             endmembers=[
@@ -641,6 +752,15 @@ def __init__(self, molar_fractions=None):
 
 class ep(Solution):
     def __init__(self, molar_fractions=None):
+        """
+        Initialisation for a ep solution object.
+        Contains the following endmembers with associated site occupancies :
+        * [HGP_2018_ds633.cz(), "[Almone][Almthree]"]
+        * [HGP_2018_ds633.ep(), "[Almone][Femthree]"]
+        * [HGP_2018_ds633.fep(), "[Femone][Femthree]"]
+
+        This is implemented as a symmetric solution.
+        """
         self.name = "ep"
         self.solution_model = SymmetricRegularSolution(
             endmembers=[
@@ -655,6 +775,15 @@ def __init__(self, molar_fractions=None):
 
 class cd(Solution):
     def __init__(self, molar_fractions=None):
+        """
+        Initialisation for a cd solution object.
+        Contains the following endmembers with associated site occupancies :
+        * [HGP_2018_ds633.crd(), "[Mgx]2[Vh]"]
+        * [HGP_2018_ds633.fcrd(), "[Fex]2[Vh]"]
+        * [HGP_2018_ds633.hcrd(), "[Mgx]2[Htwooh]"]
+
+        This is implemented as a symmetric solution.
+        """
         self.name = "cd"
         self.solution_model = SymmetricRegularSolution(
             endmembers=[
@@ -669,6 +798,21 @@ def __init__(self, molar_fractions=None):
 
 class opx(Solution):
     def __init__(self, molar_fractions=None):
+        """
+        Initialisation for a opx solution object.
+        Contains the following endmembers with associated site occupancies :
+        * [HGP_2018_ds633.en(), "[Mgmone][Mgmtwo][Sit]1/2"]
+        * [HGP_2018_ds633.fs(), "[Femone][Femtwo][Sit]1/2"]
+        * [fm, "[Mgmone][Femtwo][Sit]1/2"]
+        * [odi, "[Mgmone][Camtwo][Sit]1/2"]
+        * [HGP_2018_ds633.mgts(), "[Almone][Mgmtwo][Sit1/2Alt1/2]1/2"]
+        * [cren, "[Crmone][Mgmtwo][Sit1/2Alt1/2]1/2"]
+        * [obuf, "[Mgmone1/2Timone1/2][Mgmtwo][Sit1/2Alt1/2]1/2"]
+        * [mess, "[Fethreemone][Mgmtwo][Sit1/2Alt1/2]1/2"]
+        * [ojd, "[Almone][Namtwo][Sit]1/2"]
+
+        This is implemented as an asymmetric solution.
+        """
         self.name = "opx"
         self.solution_model = AsymmetricRegularSolution(
             endmembers=[
@@ -709,6 +853,22 @@ def __init__(self, molar_fractions=None):
 
 class cpx(Solution):
     def __init__(self, molar_fractions=None):
+        """
+        Initialisation for a cpx solution object.
+        Contains the following endmembers with associated site occupancies :
+        * [HGP_2018_ds633.di(), "[Mgmone][Camtwo][Sit]1/2"]
+        * [cfs, "[Femone][Femtwo][Sit]1/2"]
+        * [HGP_2018_ds633.cats(), "[Almone][Camtwo][Sit1/2Alt1/2]1/2"]
+        * [crdi, "[Crmone][Camtwo][Sit1/2Alt1/2]1/2"]
+        * [cess, "[Fethreemone][Camtwo][Sit1/2Alt1/2]1/2"]
+        * [cbuf, "[Mgmone1/2Timone1/2][Camtwo][Sit1/2Alt1/2]1/2"]
+        * [HGP_2018_ds633.jd(), "[Almone][Namtwo][Sit]1/2"]
+        * [cen, "[Mgmone][Mgmtwo][Sit]1/2"]
+        * [cfm, "[Mgmone][Femtwo][Sit]1/2"]
+        * [kjd, "[Almone][Kmtwo][Sit]1/2"]
+
+        This is implemented as an asymmetric solution.
+        """
         self.name = "cpx"
         self.solution_model = AsymmetricRegularSolution(
             endmembers=[
@@ -762,6 +922,20 @@ def __init__(self, molar_fractions=None):
 
 class spn(Solution):
     def __init__(self, molar_fractions=None):
+        """
+        Initialisation for a spn solution object.
+        Contains the following endmembers with associated site occupancies :
+        * [nsp, "[Mgt][Alm]"]
+        * [isp, "[Alt][Mgm1/2Alm1/2]"]
+        * [nhc, "[Fet][Alm]"]
+        * [ihc, "[Alt][Fem1/2Alm1/2]"]
+        * [nmt, "[Fet][Fethreem]"]
+        * [imt, "[Fethreet][Fem1/2Fethreem1/2]"]
+        * [pcr, "[Mgt][Crm]"]
+        * [qndm, "[Mgt][Mgm1/2Tim1/2]"]
+
+        This is implemented as a symmetric solution.
+        """
         self.name = "spn"
         self.solution_model = SymmetricRegularSolution(
             endmembers=[
@@ -789,6 +963,23 @@ def __init__(self, molar_fractions=None):
 
 class hb(Solution):
     def __init__(self, molar_fractions=None):
+        """
+        Initialisation for a hb solution object.
+        Contains the following endmembers with associated site occupancies :
+        * [HGP_2018_ds633.tr(), "[Va][Mgmonethree]3[Mgmtwo]2[Camfour]2[Sitone][Ohv]2"]
+        * [tsm, "[Va][Mgmonethree]3[Almtwo]2[Camfour]2[Sitone1/2Altone1/2][Ohv]2"]
+        * [prgm, "[Naa][Mgmonethree]3[Mgmtwo1/2Almtwo1/2]2[Camfour]2[Sitone1/2Altone1/2][Ohv]2"]
+        * [glm, "[Va][Mgmonethree]3[Almtwo]2[Namfour]2[Sitone][Ohv]2"]
+        * [HGP_2018_ds633.cumm(), "[Va][Mgmonethree]3[Mgmtwo]2[Mgmfour]2[Sitone][Ohv]2"]
+        * [grnm, "[Va][Femonethree]3[Femtwo]2[Femfour]2[Sitone][Ohv]2"]
+        * [a, "[Va][Mgmonethree]3[Femtwo]2[Femfour]2[Sitone][Ohv]2"]
+        * [b, "[Va][Femonethree]3[Mgmtwo]2[Femfour]2[Sitone][Ohv]2"]
+        * [mrb, "[Va][Mgmonethree]3[Fethreemtwo]2[Namfour]2[Sitone][Ohv]2"]
+        * [kprg, "[Ka][Mgmonethree]3[Mgmtwo1/2Almtwo1/2]2[Camfour]2[Sitone1/2Altone1/2][Ohv]2"]
+        * [tts, "[Va][Mgmonethree]3[Timtwo]2[Camfour]2[Sitone1/2Altone1/2][Ov]2"]
+
+        This is implemented as an asymmetric solution.
+        """
         self.name = "hb"
         self.solution_model = AsymmetricRegularSolution(
             endmembers=[
@@ -868,6 +1059,15 @@ def __init__(self, molar_fractions=None):
 
 class ilm(Solution):
     def __init__(self, molar_fractions=None):
+        """
+        Initialisation for a ilm solution object.
+        Contains the following endmembers with associated site occupancies :
+        * [oilm, "[Fetwoa][Tib]"]
+        * [dilm, "[Fetwoa1/2Tia1/2][Fetwob1/2Tib1/2]"]
+        * [dhem, "[Fethreea][Fethreeb]"]
+
+        This is implemented as a symmetric solution.
+        """
         self.name = "ilm"
         self.solution_model = SymmetricRegularSolution(
             endmembers=[