Apply suggestions from code review

python/chemiscope/input.py

@@ -198,16 +198,16 @@ def create_input(
         global_parameters.update(structure_j).update(atom_k)
 
     If given, the `structure` parameters list should contain one entry per structure, and
-    the `atom` parameters list should be a flat list with one entry per atom and structure.
+    the `atom` parameters list should be a flat list corresponding to the atoms of each consecutive structure.
     All shapes accept a few general parameters, and some specific ones
 
     .. code-block:: python
 
-        # general prameters
+        # general parameters
         {
             "position" : [float, float, float], # centering (defaults to origin for structure, atom position for atom)
             "scale" : float,  # scaling of the size of the shape
-            "orientation" [float, float, float, float], # optional, given as quaternion
+            "orientation" [float, float, float, float], # optional, given as quaternion in (x, y, z, w) format
             "color" : string | hex code # e.g. 0xFF0000
         }
 
@@ -235,15 +235,12 @@ def create_input(
                 [float, float, float],
                 ...
             ],
-            "simplices": [  # mesh triangulation - will be done automatically if omitted
+            "simplices": [  # mesh triangulation (optional); computed via convex triangulation where omitted
                 [int, int, int],  # indices refer to the list of vertices
                 ...
             ],
         }
 
-    ``orientation`` is provided as a quaternion in ``x, y, z, w`` format.
-    For ``custom`` shapes, ``simplices``, refer to the *indices* of the vertices. If omitted, the mesh will be
-    determined by convex.
 
     .. _`ase.Atoms`: https://wiki.fysik.dtu.dk/ase/ase/atoms.html
     """
@@ -304,7 +301,6 @@ def create_input(
     if shapes is not None:
         # TODO check and sanitize
         data["shapes"] = shapes
-        # _add_shapes(data["structures"], shapes)
 
     data["properties"] = {}
     if properties is not None:

python/chemiscope/structures/_ase.py

@@ -336,7 +336,7 @@ def _extract_key_from_ase(frame, key, target=None):
     return values, target
 
 
-def extract_vectors_from_ase(frames, key="forces", target=None, **kwargs):
+def ase_vectors_to_arrows(frames, key="forces", target=None, **kwargs):
     """
     Extract a vectorial atom property from a list of ase.Atoms
     objects, and returns a list of arrow shapes. Besides the specific
@@ -382,7 +382,7 @@ def extract_vectors_from_ase(frames, key="forces", target=None, **kwargs):
         return {"kind": "arrow", "parameters": {"global": globs, "structure": vectors}}
 
 
-def extract_tensors_from_ase(frames, key="tensor", target=None, **kwargs):
+def ase_tensors_to_arrows(frames, key="tensor", target=None, **kwargs):
     """
     Extract a 3-tensor atom property from a list of ase.Atoms
     objects, and returns a list of arrow shapes. Besides the specific

python/examples/shapes.py

@@ -186,7 +186,7 @@
     ),
 )
 
-dipoles_auto = chemiscope.extract_vectors_from_ase(frames, "dipole_ccsd", scale=0.5)
+dipoles_auto = chemiscope.ase_vectors_to_arrows(frames, "dipole_ccsd", scale=0.5)
 # one can always update the defaults created by these automatic functions
 dipoles_auto["parameters"]["global"] = {
     "base_radius": 0.2,
@@ -207,7 +207,7 @@
         # (molecular) electric dipole
         "dipole": dipoles_auto,
         # atomic decomposition of the polarizability as ellipsoids. use utility to extract from the ASE frames
-        "alpha": chemiscope.extract_tensors_from_ase(
+        "alpha": chemiscope.ase_tensors_to_arrows(
             frames, "alpha", force_positive=True, scale=0.2
         ),
         # shapes with a bit of flair

python/examples/trajectory.py

@@ -46,7 +46,7 @@
     properties=properties,
     # visualize forces as vectors
     shapes={
-        "forces": chemiscope.extract_vectors_from_ase(
+        "forces": chemiscope.ase_vectors_to_arrows(
             frames, "forces", scale=1, radius=0.15
         )
     },