diff --git a/reference_data/inputs/CaCrP2O7_mvc-11955_symmetrized.json b/reference_data/inputs/CaCrP2O7_mvc-11955_symmetrized.json
index 9e4b457f4..2e223541d 100644
--- a/reference_data/inputs/CaCrP2O7_mvc-11955_symmetrized.json
+++ b/reference_data/inputs/CaCrP2O7_mvc-11955_symmetrized.json
@@ -158,5 +158,7 @@
     true
   ]
 },
+"user":"musil",
+"comment":"comes from materials project id: mvc-11955",
 "ids": [1],
 "nextid": 2}
\ No newline at end of file
diff --git a/reference_data/inputs/alanine-X-examples.json b/reference_data/inputs/alanine-X-examples.json
index ba998cc50..e7fe680de 100644
--- a/reference_data/inputs/alanine-X-examples.json
+++ b/reference_data/inputs/alanine-X-examples.json
@@ -1,11 +1,13 @@
 {"1": {
- "cell": [[8.1, 0.0, 0.0], [0.0, 8.62, 0.0], [0.0, 0.0, 7.21]],
- "ctime": 19.792880012677248,
- "mtime": 19.792880012677248,
- "numbers": [6, 6, 6, 6, 6, 6, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 8, 8, 7, 7],
- "pbc": [false, false, false],
- "positions": [[3.889491085, 4.97062762, 1.86077437], [3.891927665, 3.94516009, 3.0053970299999997], [2.7073416949999998, 5.93709525, 1.9835621499999998], [4.211128895, 3.6536609899999997, 5.42796568], [4.210000545, 4.67960304, 6.57156473], [5.391698695, 2.6857677099999995, 5.55687028], [3.5920354549999995, 3.2140371400000003, 0.7843498599999998], [4.828550695, 5.54957842, 1.8723012799999998], [1.758181365, 5.382449869999999, 1.9948462500000002], [2.776300025, 6.5301968, 2.90611802], [2.708255285, 6.626161099999999, 1.12917427], [4.508119535, 5.40924319, 4.35202838], [3.271190615, 3.0762157199999995, 5.4429136399999996], [6.341818634999999, 3.2387308599999995, 5.57095967], [5.318730025, 2.09561691, 6.4812020100000005], [5.392829694999999, 1.9938388999999996, 4.7049904], [3.547668225, 2.7783416499999998, 2.8106070699999997], [4.555853324999999, 5.84639344, 6.37902407], [3.839338715, 4.1980903199999995, 0.63843527], [4.261876395, 4.42509162, 4.2045273199999995]],
- "unique_id": "1b5bf47287ddedc63232cd0b58101302",
- "user": "markus"},
-"ids": [1],
-"nextid": 2}
+    "cell": [[8.1, 0.0, 0.0], [0.0, 8.62, 0.0], [0.0, 0.0, 7.21]],
+    "ctime": 19.792880012677248,
+    "mtime": 19.792880012677248,
+    "numbers": [6, 6, 6, 6, 6, 6, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 8, 8, 7, 7],
+    "pbc": [false, false, false],
+    "positions": [[3.889491085, 4.97062762, 1.86077437], [3.891927665, 3.94516009, 3.0053970299999997], [2.7073416949999998, 5.93709525, 1.9835621499999998], [4.211128895, 3.6536609899999997, 5.42796568], [4.210000545, 4.67960304, 6.57156473], [5.391698695, 2.6857677099999995, 5.55687028], [3.5920354549999995, 3.2140371400000003, 0.7843498599999998], [4.828550695, 5.54957842, 1.8723012799999998], [1.758181365, 5.382449869999999, 1.9948462500000002], [2.776300025, 6.5301968, 2.90611802], [2.708255285, 6.626161099999999, 1.12917427], [4.508119535, 5.40924319, 4.35202838], [3.271190615, 3.0762157199999995, 5.4429136399999996], [6.341818634999999, 3.2387308599999995, 5.57095967], [5.318730025, 2.09561691, 6.4812020100000005], [5.392829694999999, 1.9938388999999996, 4.7049904], [3.547668225, 2.7783416499999998, 2.8106070699999997], [4.555853324999999, 5.84639344, 6.37902407], [3.839338715, 4.1980903199999995, 0.63843527], [4.261876395, 4.42509162, 4.2045273199999995]],
+    "unique_id": "1b5bf47287ddedc63232cd0b58101302",
+    "user": "markus",
+    "comment": "alanine unit cell specifically for the examples section"},
+ "ids": [1],
+ "nextid": 2
+}
diff --git a/reference_data/inputs/alanine-X.json b/reference_data/inputs/alanine-X.json
index 72079b586..0031c288f 100644
--- a/reference_data/inputs/alanine-X.json
+++ b/reference_data/inputs/alanine-X.json
@@ -1,11 +1,13 @@
 {"1": {
- "cell": [[8.1, 0.0, 0.0], [0.0, 8.62, 0.0], [0.0, 0.0, 7.21]],
- "ctime": 18.407640453530774,
- "mtime": 18.407640453530774,
- "numbers": [6, 6, 6, 6, 6, 6, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 8, 8, 7, 7],
- "pbc": [false, false, false],
- "positions": [[-0.1613651, 0.65906786, -1.97824041], [-0.15892852, -0.36639967, -0.83361775], [-1.34351449, 1.62553549, -1.85545263], [0.16027271, -0.65789877, 1.5889509], [0.15914436, 0.36804328, 2.73254995], [1.34084251, -1.62579205, 1.7178555], [-0.45882073, -1.09752262, -3.05466492], [0.77769451, 1.23801866, -1.9667135], [-2.29267482, 1.07089011, -1.84416853], [-1.27455616, 2.21863704, -0.93289676], [-1.3426009, 2.31460134, -2.70984051], [0.45726335, 1.09768343, 0.5130136], [-0.77966557, -1.23534404, 1.60389886], [2.29096245, -1.0728289, 1.73194489], [1.26787384, -2.21594285, 2.64218723], [1.34197351, -2.31772086, 0.86597562], [-0.50318796, -1.53321811, -1.02840771], [0.50499714, 1.53483368, 2.54000929], [-0.21151747, -0.11346944, -3.20057951], [0.21102021, 0.11353186, 0.36551254]],
- "unique_id": "e3fc0a6b5a2f88b7e05a78a383f1ed40",
- "user": "markus"},
-"ids": [1],
-"nextid": 2}
\ No newline at end of file
+    "cell": [[8.1, 0.0, 0.0], [0.0, 8.62, 0.0], [0.0, 0.0, 7.21]],
+    "ctime": 18.407640453530774,
+    "mtime": 18.407640453530774,
+    "numbers": [6, 6, 6, 6, 6, 6, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 8, 8, 7, 7],
+    "pbc": [false, false, false],
+    "positions": [[-0.1613651, 0.65906786, -1.97824041], [-0.15892852, -0.36639967, -0.83361775], [-1.34351449, 1.62553549, -1.85545263], [0.16027271, -0.65789877, 1.5889509], [0.15914436, 0.36804328, 2.73254995], [1.34084251, -1.62579205, 1.7178555], [-0.45882073, -1.09752262, -3.05466492], [0.77769451, 1.23801866, -1.9667135], [-2.29267482, 1.07089011, -1.84416853], [-1.27455616, 2.21863704, -0.93289676], [-1.3426009, 2.31460134, -2.70984051], [0.45726335, 1.09768343, 0.5130136], [-0.77966557, -1.23534404, 1.60389886], [2.29096245, -1.0728289, 1.73194489], [1.26787384, -2.21594285, 2.64218723], [1.34197351, -2.31772086, 0.86597562], [-0.50318796, -1.53321811, -1.02840771], [0.50499714, 1.53483368, 2.54000929], [-0.21151747, -0.11346944, -3.20057951], [0.21102021, 0.11353186, 0.36551254]],
+    "unique_id": "e3fc0a6b5a2f88b7e05a78a383f1ed40",
+    "user": "markus",
+    "comment": "generic polyalanine geometry for testing different elements"},
+ "ids": [1],
+ "nextid": 2
+}
diff --git a/reference_data/inputs/alanine-center-select.json b/reference_data/inputs/alanine-center-select.json
index 073411f47..92eb8e324 100644
--- a/reference_data/inputs/alanine-center-select.json
+++ b/reference_data/inputs/alanine-center-select.json
@@ -1,14 +1,16 @@
 {"1": {
- "cell": [[8.1, 0.0, 0.0], [0.0, 8.62, 0.0], [0.0, 0.0, 7.21]],
- "ctime": 19.792880012677248,
- "mtime": 19.792880012677248,
- "numbers": [6, 6, 6, 6, 6, 6, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 8, 8, 7, 7],
- "center_atoms_mask": [true, true, true, true, true, true, false, false, false,
-                       false, false, false, false, false, false, false, true,
-                       true, true, true],
- "pbc": [false, false, false],
- "positions": [[3.889491085, 4.97062762, 1.86077437], [3.891927665, 3.94516009, 3.0053970299999997], [2.7073416949999998, 5.93709525, 1.9835621499999998], [4.211128895, 3.6536609899999997, 5.42796568], [4.210000545, 4.67960304, 6.57156473], [5.391698695, 2.6857677099999995, 5.55687028], [3.5920354549999995, 3.2140371400000003, 0.7843498599999998], [4.828550695, 5.54957842, 1.8723012799999998], [1.758181365, 5.382449869999999, 1.9948462500000002], [2.776300025, 6.5301968, 2.90611802], [2.708255285, 6.626161099999999, 1.12917427], [4.508119535, 5.40924319, 4.35202838], [3.271190615, 3.0762157199999995, 5.4429136399999996], [6.341818634999999, 3.2387308599999995, 5.57095967], [5.318730025, 2.09561691, 6.4812020100000005], [5.392829694999999, 1.9938388999999996, 4.7049904], [3.547668225, 2.7783416499999998, 2.8106070699999997], [4.555853324999999, 5.84639344, 6.37902407], [3.839338715, 4.1980903199999995, 0.63843527], [4.261876395, 4.42509162, 4.2045273199999995]],
- "unique_id": "1b5bf47287ddedc63232cd0b58101302",
- "user": "markus"},
-"ids": [1],
-"nextid": 2}
+    "cell": [[8.1, 0.0, 0.0], [0.0, 8.62, 0.0], [0.0, 0.0, 7.21]],
+    "ctime": 19.792880012677248,
+    "mtime": 19.792880012677248,
+    "numbers": [6, 6, 6, 6, 6, 6, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 8, 8, 7, 7],
+    "center_atoms_mask": [true, true, true, true, true, true, false, false, false,
+                          false, false, false, false, false, false, false, true,
+                          true, true, true],
+    "pbc": [false, false, false],
+    "positions": [[3.889491085, 4.97062762, 1.86077437], [3.891927665, 3.94516009, 3.0053970299999997], [2.7073416949999998, 5.93709525, 1.9835621499999998], [4.211128895, 3.6536609899999997, 5.42796568], [4.210000545, 4.67960304, 6.57156473], [5.391698695, 2.6857677099999995, 5.55687028], [3.5920354549999995, 3.2140371400000003, 0.7843498599999998], [4.828550695, 5.54957842, 1.8723012799999998], [1.758181365, 5.382449869999999, 1.9948462500000002], [2.776300025, 6.5301968, 2.90611802], [2.708255285, 6.626161099999999, 1.12917427], [4.508119535, 5.40924319, 4.35202838], [3.271190615, 3.0762157199999995, 5.4429136399999996], [6.341818634999999, 3.2387308599999995, 5.57095967], [5.318730025, 2.09561691, 6.4812020100000005], [5.392829694999999, 1.9938388999999996, 4.7049904], [3.547668225, 2.7783416499999998, 2.8106070699999997], [4.555853324999999, 5.84639344, 6.37902407], [3.839338715, 4.1980903199999995, 0.63843527], [4.261876395, 4.42509162, 4.2045273199999995]],
+    "unique_id": "1b5bf47287ddedc63232cd0b58101302",
+    "user": "markus",
+    "comment": "example molecule for dihedral angles including a mask for center atoms for testing"},
+ "ids": [1],
+ "nextid": 2
+}
diff --git a/reference_data/inputs/crystal_structure.json b/reference_data/inputs/crystal_structure.json
index 9d563a370..00066077d 100644
--- a/reference_data/inputs/crystal_structure.json
+++ b/reference_data/inputs/crystal_structure.json
@@ -46,6 +46,8 @@
      [8.69635908, -22.91214366, 47.04070713],
      [3.47854363, -24.48756343, 49.71844700]],
     "unique_id": "a0ias0d",
-    "user": "markus stricker"},
-    "ids": [1],
-    "nextid": 2}
+    "user": "markus stricker",
+    "comment": "hcp Magnesium structure from a stacking fault calculation"},
+ "ids": [1],
+ "nextid": 2
+}
diff --git a/reference_data/inputs/dummy_structure.json b/reference_data/inputs/dummy_structure.json
index d0b3a47b9..9d96a6a3b 100644
--- a/reference_data/inputs/dummy_structure.json
+++ b/reference_data/inputs/dummy_structure.json
@@ -7,5 +7,6 @@
  "positions": [[6.03082510917271, -2.913100950849861, -1.4110821617697935], [7.030973863685865, -3.9442545913417115, 7.975299746380401], [7.510589457284684, -1.0048832736406603, 0.6507593684212125], [8.606901396586432, -0.8040071549228305, 9.304703596048965], [-2.914845713471, -1.1230526607765916, -0.5388356363489741], [3.6769411844653135, 8.932319785127099, 2.0360098626537777], [-3.2790995230230258, 6.9653701020480305, -2.1893609120406996], [-4.981994061617974, -3.9631171819320636, 2.9671084697147574], [5.550149395141625, 8.179110963564593, 1.8162513380958059], [7.301136575640884, 9.119717390418975, 0.15305376319016695]],
  "unique_id": "74caf9bd73247664c6d32acf24402306",
  "user": "musil"},
+"comment": "hand made structure for testing",
 "ids": [1],
 "nextid": 2}
diff --git a/reference_data/inputs/dummy_structure_wrapped.json b/reference_data/inputs/dummy_structure_wrapped.json
index 1a4e0c8f1..37ba6e9a8 100644
--- a/reference_data/inputs/dummy_structure_wrapped.json
+++ b/reference_data/inputs/dummy_structure_wrapped.json
@@ -7,5 +7,6 @@
  "positions": [[0.030825109172710086, 0.5510006642878933, 0.5889178382302064], [-0.9690261363141339, 1.2518978313649192, 1.9752997463804005], [-0.4894105427153157, 0.7271675339282166, 0.6507593684212125], [-1.393098603413569, 0.9280436526460467, 1.3047035960489655], [-0.9148457134710007, 0.6089981467922854, 1.461164363651026], [-0.32305881553468885, 0.2720657472827135, 0.03600986265377782], [0.7209004769769732, 0.03716687177252341, 1.8106390879593006], [-0.9819940616179721, 1.2330352407745677, 0.9671084697147575], [-2.449850604858379, 1.2509077332890859, 1.8162513380958059], [-0.6988634243591202, 0.4594633525745903, 0.15305376319016695]],
  "unique_id": "d3185d2d5a94a8bee9f48b38eb058871",
  "user": "musil"},
+ "comment": "hand made structure for testing",
 "ids": [1],
 "nextid": 2}
diff --git a/reference_data/inputs/molecular_crystal.json b/reference_data/inputs/molecular_crystal.json
index 9a5fb17bf..54612487f 100644
--- a/reference_data/inputs/molecular_crystal.json
+++ b/reference_data/inputs/molecular_crystal.json
@@ -1179,6 +1179,8 @@
       true
     ]
   },
+  "user": "musil",
+  "comment": "first structure of the CSD 500 molecular crystals dataset",
   "nextid": 2,
   "ids": [
     0
diff --git a/reference_data/inputs/polyalanine.json b/reference_data/inputs/polyalanine.json
index 35e126ddf..6fd4ec64a 100644
--- a/reference_data/inputs/polyalanine.json
+++ b/reference_data/inputs/polyalanine.json
@@ -1,9 +1,9 @@
 {"1": {
- "cell": [[8.1, 0.0, 0.0], [0.0, 8.62, 0.0], [0.0, 0.0, 7.21]],
- "ctime": 18.407640453530774,
- "mtime": 18.407640453530774,
- "numbers": [6, 6, 6, 6, 6, 6, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 8, 8, 7, 7],
- "pbc": [false, false, false],
+    "cell": [[8.1, 0.0, 0.0], [0.0, 8.62, 0.0], [0.0, 0.0, 7.21]],
+    "ctime": 18.407640453530774,
+    "mtime": 18.407640453530774,
+    "numbers": [6, 6, 6, 6, 6, 6, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 8, 8, 7, 7],
+    "pbc": [false, false, false],
     "positions": [[-0.1613651, 0.65906786, -1.97824041],
                   [-0.15892852, -0.36639967, -0.83361775],
                   [-1.34351449, 1.62553549, -1.85545263],
@@ -24,7 +24,9 @@
                   [0.50499714, 1.53483368, 2.54000929],
                   [-0.21151747, -0.11346944, -3.20057951],
                   [0.21102021, 0.11353186, 0.36551254]],
- "unique_id": "e3fc0a6b5a2f88b7e05a78a383f1ed40",
- "user": "markus stricker"},
-"ids": [1],
-"nextid": 2}
+    "unique_id": "e3fc0a6b5a2f88b7e05a78a383f1ed40",
+    "user": "markus stricker",
+    "comment": "example molecule for dihedral angles testing"},
+ "ids": [1],
+ "nextid": 2
+}
diff --git a/reference_data/inputs/simple_cubic_8.json b/reference_data/inputs/simple_cubic_8.json
index c2c8fbc3d..19a1afe1e 100644
--- a/reference_data/inputs/simple_cubic_8.json
+++ b/reference_data/inputs/simple_cubic_8.json
@@ -13,7 +13,9 @@
         [1.5, 0.5, 1.5],
         [0.5, 1.5, 1.5],
         [1.5, 1.5, 1.8]
-    ]
-},
-"ids": [1],
-"nextid": 2}
+    ],
+    "user": "markus",
+    "comment": "custom structure with simple geometry for testing neighbourlists"},
+ "ids": [1],
+ "nextid": 2
+}
diff --git a/reference_data/inputs/simple_cubic_9.json b/reference_data/inputs/simple_cubic_9.json
index 49b496b8b..b61924844 100644
--- a/reference_data/inputs/simple_cubic_9.json
+++ b/reference_data/inputs/simple_cubic_9.json
@@ -16,7 +16,8 @@
         [1.5, 1.5, 1.8]
     ],
     "unique_id": "abcdef",
-    "user": "markus"},
+    "user": "markus",
+    "comment": "custom structure with 9 atoms and simple geometry for testing neighbourlists"},
  "ids": [1],
  "nextid": 2
 }
diff --git a/reference_data/inputs/small_molecule.json b/reference_data/inputs/small_molecule.json
index 3e4a40eac..74ba14c2b 100644
--- a/reference_data/inputs/small_molecule.json
+++ b/reference_data/inputs/small_molecule.json
@@ -96,5 +96,7 @@
   "ids": [
     0
   ],
+  "user": "musil",
+  "comment": "molecule taken from the QM9 dataset",
   "nextid": 2
 }
\ No newline at end of file
diff --git a/reference_data/inputs/small_molecule_no_cell.json b/reference_data/inputs/small_molecule_no_cell.json
index 402e39d7b..a3df9f57f 100644
--- a/reference_data/inputs/small_molecule_no_cell.json
+++ b/reference_data/inputs/small_molecule_no_cell.json
@@ -96,5 +96,7 @@
   "ids": [
     0
   ],
+  "user": "musil",
+  "comment": "molecule taken from the QM9 dataset",
   "nextid": 2
 }
\ No newline at end of file
diff --git a/reference_data/unused/behler_parinello_pair_hypers.json b/reference_data/unused/behler_parinello_pair_hypers.json
index 5a5cfed77..dc7df934c 100644
--- a/reference_data/unused/behler_parinello_pair_hypers.json
+++ b/reference_data/unused/behler_parinello_pair_hypers.json
@@ -172,5 +172,6 @@
                 "bias_weight": 16840.8752
             }
         ]
-    ]
+    ],
+    "comment": "example input file for defining the hyper parameters in a Behler-Parinello style Neural Network potential"
 }
diff --git a/reference_data/unused/simple_cubic_3.json b/reference_data/unused/simple_cubic_3.json
deleted file mode 100644
index 09499ddb9..000000000
--- a/reference_data/unused/simple_cubic_3.json
+++ /dev/null
@@ -1,16 +0,0 @@
-{"1": {
-    "cell": [[2.0, 0.0, 0.0], [0.0, 2.0, 0.0], [0.0, 0.0, 2.0]],
-    "ctime": 7.77,
-    "mtime": 7.77,
-    "numbers": [1, 1, 1],
-    "pbc": [false, false, false],
-    "positions": [
-        [0.5, 0.4, 0.5],
-        [0.5, 0.5, 0.5],
-        [1.5, 0.5, 0.5]
-    ],
-    "unique_id": "abcdef",
-    "user": "markus"},
- "ids": [1],
- "nextid": 2
-}