Merge pull request #2 from scientificcomputing/dokken/suggestions

Various improvements

Author: finsberg

LICENSE

@@ -1,4 +1,4 @@
-Copyright 2022 Simula Reaseach Laboratory
+Copyright 2022 Simula Research Laboratory
 
 Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
 

code/postprocess.py

@@ -1,12 +1,24 @@
-"""Script for converting file """
+"""
+Script for converting file
+
+SPDX-License-Identifier:    MIT
+"""
 import json
+import logging
+import sys
 import typing
 from pathlib import Path
 
 import config
 import dolfin
-from cardiac_geometries.geometry import Geometry
-from cardiac_geometries.geometry import load_microstructure
+import numpy as np
+from cardiac_geometries.geometry import Geometry, load_microstructure
+
+logger = logging.Logger(__name__, logging.INFO)
+ch = logging.StreamHandler(sys.stdout)
+FORMAT = '%(levelname)-5s [%(filename)s:%(lineno)d] %(message)s'
+ch.setFormatter(logging.Formatter(FORMAT))
+logger.addHandler(ch)
 
 
 def generate_fiber_xdmf_file(
@@ -17,17 +29,17 @@ def generate_fiber_xdmf_file(
 
     geo = Geometry.from_file(outfile, schema_path=outfile.with_suffix(".json"))
 
-    f0, s0, n0 = load_microstructure(
+    f0, _, _ = load_microstructure(
         mesh=geo.mesh,
         microstructure_path=microstructure_path,
     )
 
-    # Save fibers to a file that can be visualized in paraview
+    # Save fibers to a file that can be visualized in Paraview
 
     with dolfin.XDMFFile(fiber_path.as_posix()) as f:
         f.write(f0)
 
-    print(f"Saved fibers to {fiber_path}")
+    logger.info(f"Saved fibers to {fiber_path}")
     # Compute some features. This could be some results presented in the paper
 
     return {
@@ -39,11 +51,28 @@ def generate_fiber_xdmf_file(
     }
 
 
-def check_results(features_path: Path, features):
-    expected_feautres = json.loads(features_path.read_text())
-    print("Checking reproducibility")
-    assert expected_feautres == features
-    print("Results are reproducible!")
+def check_results(features_path: Path, features: dict):
+    """
+    Check if data from input file `features_path` matches input features
+
+    Args:
+        features_path (Path): Path to reference results
+        features (dict): Results generated from current simulation
+    """
+    expected_features = json.loads(features_path.read_text())
+    logger.info("Checking reproducibility")
+    reproducible = True
+    # Check each (key, value) pair in the features and check they are
+    # within machine precision
+    for key in expected_features.keys():
+        if not np.isclose(expected_features[key], features[key]):
+            logger.error(f"{key}: {expected_features[key]}!={features[key]}")
+            reproducible = False
+
+    if reproducible:
+        logger.info("Results are reproducible")
+    else:
+        raise RuntimeError("Results are not reproducible")
 
 
 def main() -> int:

code/pre_processing.py

@@ -1,17 +1,26 @@
 """
-Script for converting gmsh files to dolfin format
+Script for converting GMSH files to Dolfin format
 using cardiac geometries
 
 https://computationalphysiology.github.io/cardiac_geometries/
 
+SPDX-License-Identifier:    MIT
 """
 import typing
 from pathlib import Path
-
+import logging
 import cardiac_geometries
 import config
 from cardiac_geometries.geometry import Geometry
 from cardiac_geometries.geometry import H5Path
+import sys
+
+# We set default log level to be info
+logger = logging.Logger(__name__, logging.INFO)
+ch = logging.StreamHandler(sys.stdout)
+FORMAT = '%(levelname)-5s [%(filename)s:%(lineno)d] %(message)s'
+ch.setFormatter(logging.Formatter(FORMAT))
+logger.addHandler(ch)
 
 schema = {
     "mesh": H5Path(
@@ -35,10 +44,15 @@ def convert_mesh(
     msh_file: typing.Union[Path, str],
     outfile: typing.Union[Path, str],
 ) -> None:
+    """
+    Convert an .msh file to DOLFIN h5 format
 
-    print("Converting 'msh' file to dolfin xdmf format")
+    Args:
+        msh_file (typing.Union[Path, str]): Path to input mesh (.msh extension)
+        outfile (typing.Union[Path, str]): Path to outfile (.h5 extension)
+    """
     geometry = cardiac_geometries.gmsh2dolfin(msh_file, unlink=True)
-
+    logger.info(f"Converting {msh_file}")
     geo = Geometry(
         mesh=geometry.mesh,
         markers=geometry.markers,
@@ -47,10 +61,16 @@ def convert_mesh(
     )
 
     geo.save(outfile)
-    print(f"Saved to {outfile}")
+    logger.info(f"Saved to {outfile}")
 
 
 def main() -> int:
+    """
+    Convert meshes from `../data/mesh/heart0*.msh` to `../data/heart_0*.h5`
+
+    Returns:
+        int: 0 if code runs as expected
+    """
     for heart_nr in [1, 2]:
         msh_file = config.get_msh_path(heart_nr=heart_nr)
         outfile = config.get_h5_path(heart_nr=heart_nr)

code/run_fiber_generation.py

@@ -3,14 +3,24 @@
 algorithm
 
 https://finsberg.github.io/ldrb/
+
+SPDX-License-Identifier:    MIT
 """
+import logging
+import sys
 from pathlib import Path
 
 import config
 import dolfin
 import ldrb
 from cardiac_geometries.geometry import Geometry
 
+logger = logging.Logger(__name__, logging.INFO)
+ch = logging.StreamHandler(sys.stdout)
+FORMAT = '%(levelname)-5s [%(filename)s:%(lineno)d] %(message)s'
+ch.setFormatter(logging.Formatter(FORMAT))
+logger.addHandler(ch)
+
 
 def generate_fibers(outfile: Path, microstructure_path: Path) -> None:
 
@@ -46,7 +56,7 @@ def generate_fibers(outfile: Path, microstructure_path: Path) -> None:
         h5file.write(s0, "s0")
         h5file.write(n0, "n0")
 
-    print(f"Microstructure saved to {microstructure_path}")
+    logger.info(f"Microstructure saved to {microstructure_path}")
 
 
 def main() -> int:

docs/_config.yml

@@ -35,6 +35,7 @@ parse:
 sphinx:
   config:
     bibtex_bibfiles: ["refs.bib"]
+    suppress_warnings: ["bibtex.duplicate_citation"] # If the same paper is cited in multiple files
 
   extra_extensions:
   - 'sphinx.ext.autodoc'

docs/abstract.md

@@ -5,7 +5,7 @@ Here you can write a little abstract for the paper or some text explaining what
 
 You could also add citation that you can add to the `refs.bib` in the `docs` folder. You can read more about adding citations [here](https://jupyterbook.org/en/stable/content/citations.html).
 
-In this example we use the LDRB algorithm {cite}`bayer2012novel` to data from {cite}`martinez2019repository`
+In this example we use the LDRB algorithm {cite}`bayer2012novel` to data from {cite}`martinez2019repository`.
 
 
 ## References

docs/docker.md

@@ -1,4 +1,4 @@
-## Running in Docker
+# Running in Docker
 
 We have created a docker image containing all the dependencies as well as the source code in the repository. To get the most recent version of the docker image, make sure to pull the latest image first
 ```bash

docs/refs.bib

@@ -6,12 +6,14 @@ @article{bayer2012novel
   number={10},
   pages={2243--2254},
   year={2012},
-  publisher={Springer}
+  publisher={Springer},
+  doi={10.1007/s10439-012-0593-5}
 }
 
 @misc{martinez2019repository,
   title={Repository for modelling acute myocardial ischemia: simulation scripts and torso-heart mesh},
   author={Martinez-Navarro, Hector and Rodriguez, Blanca and Bueno-Orovio, Alfonso and Minchole, Ana},
   year={2019},
-  publisher={University of Oxford}
+  publisher={University of Oxford},
+  doi={10.5287/bodleian:9RxJPo9po}
 }

docs/reproducing.md

@@ -3,7 +3,7 @@
 
 ## Data
 
-Data is available in a dropbox folder. Use the script `download_data.sh` in the data folder to download the data, i.e
+Data is available in a Dropbox folder. Use the script `download_data.sh` in the data folder to download the data, i.e
 ```bash
 cd data
 bash download_data.sh
@@ -18,9 +18,9 @@ The data folder should have the following structure after the data is downloaded
     ├── heart01.msh
     └── heart02.msh
 ```
-These meshes are originally taken from <https://ora.ox.ac.uk/objects/uuid:951b086c-c4ba-41ef-b967-c2106d87ee06>, but since the original data is about 26GB we decided to make a smaller dataset for this example.
+These meshes are originally taken from {cite}`martinez2019repository`, but since the original data is about 26GB we decided to make a smaller dataset for this example.
 
-Eventually when you publish a paper you could put this data on e.g [Zenodo](https://zenodo.org). That will make sure the data gets it's own DOI.
+Eventually when you publish a paper you could put this data on e.g [Zenodo](https://zenodo.org). That will make sure the data gets it's own [Digital Object Identifier](https://www.doi.org/) (DOI).
 
 
 ## Scripts
@@ -31,7 +31,7 @@ In order to reproduce the results you need to first run the pre-processing scrip
 ```
 python3 pre_processing.py
 ```
-This will convert the meshes from Gmsh to a dolfin format.
+This will convert the meshes from Gmsh to a Dolfin format.
 
 ### Fiber generation
 The next step is to run the fiber generation. You can do this by running the script
@@ -46,3 +46,7 @@ The final step is to postprocess the results by running the script
 python3 postprocess.py
 ```
 This will generate a file for visualizing the fibers in the Paraview (inside `code/results` called  `fiber_<heart_nr>.xdmf`). This script will also compare some features computed from the fibers with the results published in the (artificial) paper. If the results differ, then the program will raise an error.
+
+```{bibliography}
+:filter: docname in docnames
+```