Add cross-referentiable bibliography

Author: patnr

docs/bib/bib2md.py

@@ -0,0 +1,42 @@
+"""Render bibtex file as markdown with keys as headings that can be cross-referenced."""
+
+from pathlib import Path
+
+import pybtex.backends.markdown as fmt
+from pybtex.database import parse_string
+from pybtex.richtext import Tag, Text
+from pybtex.style.formatting.unsrt import Style as UnsrtStyle
+from pybtex.style.formatting.unsrt import field, sentence
+
+fmt.SPECIAL_CHARS.remove("[")
+fmt.SPECIAL_CHARS.remove("]")
+fmt.SPECIAL_CHARS.remove("(")
+fmt.SPECIAL_CHARS.remove(")")
+fmt.SPECIAL_CHARS.remove("-")
+
+HERE = Path(__file__).parent
+
+
+class MyStyle(UnsrtStyle):
+    # default_sorting_style = "author_year_title"
+    def format_title(self, e, which_field, as_sentence=True):
+        formatted_title = field(
+            which_field,
+            apply_func=lambda text: Tag("tt", Text('"', text.capitalize(), '"')),
+        )
+        if as_sentence:
+            return sentence[formatted_title]
+        else:
+            return formatted_title
+
+
+bib = parse_string((HERE / "refs.bib").read_text(), "bibtex")
+
+formatted = MyStyle().format_entries(bib.entries.values())
+
+md = ""
+for entry in formatted:
+    md += f"### `{entry.key}`\n\n"
+    md += entry.text.render_as("markdown") + "\n\n"
+
+(HERE.parent / "references.md").write_text(md)

docs/bib/refs.bib

@@ -0,0 +1,89 @@
+@article{emerick2016a,
+    title={Analysis of the performance of ensemble-based assimilation of production and seismic data},
+    author={Emerick, Alexandre A.},
+    journal={Journal of Petroleum Science and Engineering},
+    volume={139},
+    pages={219--239},
+    year={2016},
+    publisher={Elsevier}
+}
+
+@book{evensen2009a,
+    title={Data Assimilation},
+    author={Evensen, Geir},
+    year={2009},
+    edition={2},
+    pages={307},
+    publisher={Springer}
+}
+
+@article{emerick2013a,
+    title={Ensemble smoother with multiple data assimilation},
+    author={Emerick, Alexandre A. and Reynolds, Albert C.},
+    journal={Computers \& Geosciences},
+    volume={55},
+    pages={3--15},
+    year={2013},
+    publisher={Elsevier}
+}
+
+@article{rafiee2017,
+  title={Theoretical and efficient practical procedures for the generation of inflation factors for ES-MDA},
+  author={Rafiee, Javad and Reynolds, Albert C},
+  journal={Inverse Problems},
+  volume={33},
+  number={11},
+  pages={115003},
+  year={2017},
+  publisher={IOP Publishing}
+}
+
+@article{chen2013,
+    title={Levenberg--{M}arquardt forms of the iterative ensemble smoother for efficient history matching and uncertainty quantification},
+    author={Chen, Yan and Oliver, Dean S.},
+    journal={Computational Geosciences},
+    volume={17},
+    number={4},
+    pages={689--703},
+    year={2013},
+    publisher={Springer}
+}
+
+@article{raanes2019,
+    title={Revising the stochastic iterative ensemble smoother},
+    author={Raanes, Patrick Nima and Stordal, Andreas St{\o}rksen and Evensen, Geir},
+    doi={10.5194/npg-26-325-2019},
+    journal={Nonlinear Processes in Geophysics},
+    volume={26},
+    number={3},
+    pages={325--338},
+    year={2019},
+    publisher={Copernicus GmbH}
+}
+
+@article{evensen2019,
+    title={Efficient implementation of an iterative ensemble smoother for data assimilation and reservoir history matching},
+    author={Evensen, Geir and Raanes, Patrick N. and Stordal, Andreas S. and Hove, Joakim},
+    doi={10.3389/fams.2019.00047},
+    journal={Frontiers in Applied Mathematics and Statistics},
+    volume={5},
+    pages={47},
+    year={2019},
+    publisher={Frontiers}
+}
+
+@article{kingma2014,
+  title={Adam: A method for stochastic optimization},
+  author={Kingma, Diederik P},
+  journal={arXiv preprint arXiv:1412.6980},
+  year={2014}
+}
+
+@article{hansen2006,
+  title={The {CMA} evolution strategy: a comparing review},
+  author={Hansen, Nikolaus},
+  journal={Towards a new evolutionary computation: Advances in the estimation of distribution algorithms},
+  pages={75--102},
+  year={2006},
+  publisher={Springer}
+}

docs/gen_ref_pages.py

@@ -29,7 +29,7 @@
         # Generate index.md
         parts = parts[:-1] # name of parent dir
         path_md = path_md.with_name("index.md")
-    elif parts[-1] == str(Path(__file__).with_suffix("").name):
+    elif parts[0] == "docs":
         continue
 
     # PS: Uncomment (replace `mkdocs_gen_files.open`) to view actual .md files

docs/references.md

@@ -0,0 +1,56 @@
+### `emerick2016a`
+
+Alexandre A\. Emerick\.
+`"Analysis of the performance of ensemble-based assimilation of production and seismic data"`\.
+*Journal of Petroleum Science and Engineering*, 139:219–239, 2016\.
+
+### `evensen2009a`
+
+Geir Evensen\.
+*Data Assimilation*\.
+Springer, 2 edition, 2009\.
+
+### `emerick2013a`
+
+Alexandre A\. Emerick and Albert C\. Reynolds\.
+`"Ensemble smoother with multiple data assimilation"`\.
+*Computers & Geosciences*, 55:3–15, 2013\.
+
+### `rafiee2017`
+
+Javad Rafiee and Albert C Reynolds\.
+`"Theoretical and efficient practical procedures for the generation of inflation factors for es-mda"`\.
+*Inverse Problems*, 33(11):115003, 2017\.
+
+### `chen2013`
+
+Yan Chen and Dean S\. Oliver\.
+`"Levenberg–Marquardt forms of the iterative ensemble smoother for efficient history matching and uncertainty quantification"`\.
+*Computational Geosciences*, 17(4):689–703, 2013\.
+
+### `raanes2019`
+
+Patrick Nima Raanes, Andreas Størksen Stordal, and Geir Evensen\.
+`"Revising the stochastic iterative ensemble smoother"`\.
+*Nonlinear Processes in Geophysics*, 26(3):325–338, 2019\.
+[doi:10\.5194/npg-26-325-2019](https://doi.org/10.5194/npg-26-325-2019)\.
+
+### `evensen2019`
+
+Geir Evensen, Patrick N\. Raanes, Andreas S\. Stordal, and Joakim Hove\.
+`"Efficient implementation of an iterative ensemble smoother for data assimilation and reservoir history matching"`\.
+*Frontiers in Applied Mathematics and Statistics*, 5:47, 2019\.
+[doi:10\.3389/fams\.2019\.00047](https://doi.org/10.3389/fams.2019.00047)\.
+
+### `kingma2014`
+
+Diederik P Kingma\.
+`"Adam: a method for stochastic optimization"`\.
+*arXiv preprint arXiv:1412\.6980*, 2014\.
+
+### `hansen2006`
+
+Nikolaus Hansen\.
+`"The CMA evolution strategy: a comparing review"`\.
+*Towards a new evolutionary computation: Advances in the estimation of distribution algorithms*, pages 75–102, 2006\.
+

docs/tutorials/pipt/tutorial_pipt.ipynb

@@ -303,12 +303,7 @@
       "\n",
       "        keys_en : dict\n",
       "\n",
-      "        sim : callable\n",
-      "\n",
-      "        References\n",
-      "        ----------\n",
-      "        [1] A. Emerick & A. Reynods, Computers & Geosciences, 55, p. 3-15, 2013\n",
-      "        \n"
+      "        sim : callable\n"
      ]
     },
     {

mkdocs.yml

@@ -11,7 +11,7 @@ nav:
   - Home: index.md
   - Reference: reference/
   - Tutorials: tutorials/
-  # - Bibliography: references.md
+  - Bibliography: references.md
   - dev_guide.md
 
 validation:

pipt/misc_tools/analysis_tools.py

@@ -21,7 +21,7 @@
 def parallel_upd(list_state, prior_info, states_dict, X, local_mask_info, obs_data, pred_data, parallel, actnum=None,
                  field_dim=None, act_data_list=None, scale_data=None, num_states=1, emp_d_cov=False):
     """
-    Script to initialize and control a parallel update of the ensemble state following [1].
+    Script to initialize and control a parallel update of the ensemble state following [`emerick2016a`][].
 
     Parameters
     ----------
@@ -57,11 +57,6 @@ def parallel_upd(list_state, prior_info, states_dict, X, local_mask_info, obs_da
     Notes
     -----
     Since the localization matrix is to large for evaluation, we instead calculate it row for row.
-
-    References
-    ----------
-    [1] Emerick, Alexandre A. 2016. “Analysis of the Performance of Ensemble-Based Assimilation of Production and
-    Seismic Data.” Journal of Petroleum Science and Engineering 139. Elsevier: 219-39. doi:10.1016/j.petrol.2016.01.029
     """
     if scale_data is None:
         scale_data = np.ones(obs_data.shape[0])
@@ -1060,7 +1055,7 @@ def calc_kalmangain(cov_cross, cov_auto, cov_data, opt=None):
 def calc_subspace_kalmangain(cov_cross, data_pert, cov_data, energy):
     """
     Compute the Kalman gain in a efficient subspace determined by how much energy (i.e. percentage of singluar values)
-    to retain. For more info regarding the implementation, see Chapter 14 in [1].
+    to retain. For more info regarding the implementation, see Chapter 14 in [`evensen2009a`][].
 
     Parameters
     cov_cross : ndarray
@@ -1074,10 +1069,6 @@ def calc_subspace_kalmangain(cov_cross, data_pert, cov_data, energy):
     -------
     k_g : ndarray
         Subspace Kalman gain
-
-    References
-    ----------
-    [1] G. Evensen (2009). Data Assimilation: The Ensemble Kalman Filter, Springer.
     """
     # No. ensemble members
     ne = data_pert.shape[1]

pipt/update_schemes/enrml.py

@@ -645,7 +645,7 @@ class gnenrml_margis(gnenrmlMixIn, margIS_update):
 
 class co_lm_enrml(lmenrmlMixIn, approx_update):
     """
-    This is the implementation of the approximative LM-EnRML algorithm as described in [1].
+    This is the implementation of the approximative LM-EnRML algorithm as described in [`chen2013`][].
 
     This algorithm is quite similar to the lm_enrml as provided above, and will therefore inherit most of its methods.
     We only change the calc_analysis part...
@@ -657,11 +657,6 @@ def __init__(self, keys_da):
         """
         The class is initialized by passing the PIPT init. file upwards in the hierarchy to be read and parsed in
         `pipt.input_output.pipt_init.ReadInitFile`.
-
-        References
-        ----------
-        [1] Chen Y. & Oliver D.S. 2013, Levenberg-Marquardt Forms of the Iterative Ensemble Smoother for Efficient
-        History Matching and Uncertainty Quantification. Comput. Geosci., 17 (4): 689-703
         """
         # Call __init__ in parent class
         super().__init__(keys_da)
@@ -679,11 +674,6 @@ def calc_analysis(self):
         -------
         success : bool
             True if data mismatch is decreasing, False if increasing
-
-        References
-        ----------  
-        [1] Chen Y. & Oliver D.S. 2013, Levenberg-Marquardt Forms of the Iterative Ensemble Smoother for Efficient
-        History Matching and Uncertainty Quantification. Comput. Geosci., 17 (4): 689-703
         """
         # Get assimilation order as a list
         self.assim_index = [self.keys_da['obsname'], self.keys_da['assimindex'][0]]
@@ -795,8 +785,10 @@ def calc_analysis(self):
 
 class gn_enrml(lmenrmlMixIn):
     """
-    This is the implementation of the stochastig IES as  described in [1]. More information about the method is found in
-    [2]. This implementation is the Gauss-Newton version.
+    This is the implementation of the stochastig IES as  described in [`raanes2019`][].
+
+    More information about the method is found in [`evensen2019`][].
+    This implementation is the Gauss-Newton version.
 
     This algorithm is quite similar to the `lm_enrml` as provided above, and will therefore inherit most of its methods.
     We only change the calc_analysis part...
@@ -806,14 +798,6 @@ def __init__(self, keys_da):
         """
         The class is initialized by passing the PIPT init. file upwards in the hierarchy to be read and parsed in
         `pipt.input_output.pipt_init.ReadInitFile`.
-
-        References
-        ----------
-        [1] Raanes, P. N., Stordal, A. S., & Evensen, G. (2019). Revising the stochastic iterative ensemble smoother.
-        Nonlinear Processes in Geophysics, 26(3), 325-338. https://doi.org/10.5194/npg-26-325-2019 <br>
-        [2] Evensen, G., Raanes, P. N., Stordal, A. S., & Hove, J. (2019). Efficient Implementation of an Iterative
-        Ensemble Smoother for Data Assimilation and Reservoir History Matching. Frontiers in Applied Mathematics and
-        Statistics, 5(October), 114. https://doi.org/10.3389/fams.2019.00047
         """
         # Call __init__ in parent class
         super().__init__(keys_da)

pipt/update_schemes/esmda.py

@@ -20,7 +20,8 @@
 
 class esmdaMixIn(Ensemble):
     """
-    This is the implementation of the ES-MDA algorithm given in [1]. This algorithm have been implemented mostly to
+    This is the implementation of the ES-MDA algorithm given in [`emerick2013a`][].
+    This algorithm have been implemented mostly to
     illustrate how a algorithm using the Mda loop can be implemented.
     """
 
@@ -37,10 +38,6 @@ def __init__(self, keys_da, keys_en, sim):
         keys_en : dict
 
         sim : callable
-
-        References
-        ----------
-        [1] A. Emerick & A. Reynods, Computers & Geosciences, 55, p. 3-15, 2013
         """
         # Pass the init_file upwards in the hierarchy
         super().__init__(keys_da, keys_en, sim)
@@ -330,17 +327,13 @@ class esmda_geo(esmda_approx):
     """
     This is the implementation of the ES-MDA-GEO algorithm from [1]. The main analysis step in this algorithm is the
     same as the standard ES-MDA algorithm (implemented in the `es_mda` class). The difference between this and the
-    standard algorithm is the calculation of the inflation factor.
+    standard algorithm is the calculation of the inflation factor. Also see [`rafiee2017`][].
     """
 
     def __init__(self, keys_da):
         """
         The class is initialized by passing the PIPT init. file upwards in the hierarchy to be read and parsed in
         `pipt.input_output.pipt_init.ReadInitFile`.
-
-        References
-        ----------
-        [1] J. Rafiee & A. Reynolds, Inverse Problems 33 (11), 2017
         """
         # Pass the init_file upwards in the hierarchy
         super().__init__(keys_da)

popt/update_schemes/cma.py

@@ -6,7 +6,7 @@ class CMA:
 
     def __init__(self, ne, dim, alpha_mu=None, n_mu=None, alpha_1=None, alpha_c=None, corr_update=False, equal_weights=True):
         '''
-        This is a rather simple simple CMA class
+        This is a rather simple simple CMA class [`hansen2006`][].
 
         Parameters
         ----------------------------------------------------------------------------------------------------------
@@ -37,12 +37,6 @@ def __init__(self, ne, dim, alpha_mu=None, n_mu=None, alpha_1=None, alpha_c=None
             If True, all n_mu members are assign equal weighting, `w_i = 1/n_mu`.
             If False, the weighting scheme proposed in [1], where `w_i = log(n_mu + 1)-log(i)`,
             and normalized such that they sum to one. Defualt is True.
-
-        References
-        ----------------------------------------------------------------------------------------------------------
-        [1] Hansen, N. (2006). The CMA evolution strategy: a comparing review. 
-            In J. Lozano, P. Larranaga, I. Inza & E. Bengoetxea (ed.), Towards a new evolutionary computation. 
-            Advances on estimation of distribution algorithms (pp. 75--102) . Springer .     
         '''
         self.alpha_mu       = alpha_mu
         self.n_mu           = n_mu