Clarify physicists' versus chemists' notation conventions

iodata/docstrings.py

@@ -39,6 +39,7 @@ def _document_load(
 ) -> Callable:
     if kwdocs is None:
         kwdocs = {}
+    notes = "" if notes is None else f"\nNotes\n-----\n\n{notes.strip()}\n"
     ifpresent = ifpresent or []
 
     def decorator(func):
@@ -82,11 +83,7 @@ def decorator(func):
 result: dict
     A dictionary with IOData attributes. The following attributes are guaranteed to be
     loaded: {guaranteed}.{ifpresent}
-
-Notes
------
 {notes}
-
 """
 
 
@@ -138,11 +135,7 @@ def document_load_one(
 result: dict
     A dictionary with IOData attributes. The following attribtues are guaranteed to be
     loaded: {guaranteed}.{ifpresent}
-
-Notes
------
 {notes}
-
 """
 
 

iodata/formats/fcidump.py

@@ -22,7 +22,7 @@
 -----
 1. This function works only for restricted wave-functions.
 2. One- and two-electron integrals are stored in chemists' notation in an FCIDUMP file,
-   while IOData internally uses Physicist's notation.
+   while IOData internally uses physicists' notation.
 3. Keep in mind that the FCIDUMP format changed in MOLPRO 2012, so files generated with
    older versions are not supported.
 
@@ -42,8 +42,16 @@
 PATTERNS = ["*FCIDUMP*"]
 
 
+LOAD_ONE_NOTES = """
+IOData stores four-index objects in physicists' notation internally and
+assumes they are stored in an FCIDUMP file in chemists' notation.
+"""
+
+
 @document_load_one(
-    "Molpro 2012 FCIDUMP", ["core_energy", "one_ints", "nelec", "spinpol", "two_ints"]
+    "Molpro 2012 FCIDUMP",
+    ["core_energy", "one_ints", "nelec", "spinpol", "two_ints"],
+    notes=LOAD_ONE_NOTES,
 )
 def load_one(lit: LineIterator) -> dict:
     """Do not edit this docstring. It will be overwritten."""
@@ -107,18 +115,19 @@ def load_one(lit: LineIterator) -> dict:
     }
 
 
-LOAD_ONE_NOTES = """
-The dictionary ``one_ints`` must contain a field ``core_mo``. Similarly, ``two_ints`` must
-contain ``two_mo``.
+DUMP_ONE_NOTES = """
+The dictionary ``one_ints`` must contain a field ``core_mo``.
+Similarly, ``two_ints`` must contain ``two_mo``.
+IOData stores four-index objects in physicists' notation internally and
+dumps them to an FCIDUMP file in chemists' notation.
 """
 
 
 @document_dump_one(
     "Molpro 2012 FCIDUMP",
     ["one_ints", "two_ints"],
     ["core_energy", "nelec", "spinpol"],
-    {},
-    LOAD_ONE_NOTES,
+    notes=DUMP_ONE_NOTES,
 )
 def dump_one(f: TextIO, data: IOData):
     """Do not edit this docstring. It will be overwritten."""

iodata/formats/gaussianlog.py

@@ -39,7 +39,13 @@
 PATTERNS = ["*.log"]
 
 
-@document_load_one("Gaussian Log", [], ["one_ints", "two_ints"])
+LOAD_ONE_NOTES = """\
+Note that Gaussian writes four-center integrals in chemists' notation.
+They will be reordered into physicists' notation when loading them with IOData.
+"""
+
+
+@document_load_one("Gaussian Log", [], ["one_ints", "two_ints"], notes=LOAD_ONE_NOTES)
 def load_one(lit: LineIterator) -> dict:
     """Do not edit this docstring. It will be overwritten."""
     # First get the line with the number of orbital basis functions
@@ -136,7 +142,7 @@ def _load_fourindex_g09(lit: LineIterator, nbasis: int) -> NDArray[float]:
         i2 = int(line[15:19]) - 1
         i3 = int(line[21:25]) - 1
         value = float(line[29:].replace("D", "E"))
-        # Gaussian uses the chemists notation for the 4-center indexes. IOdata
-        # uses the physicists notation.
+        # Gaussian uses the chemists' notation for the 4-center indexes. IOdata
+        # uses the physicists' notation.
         set_four_index_element(result, i0, i2, i1, i3, value)
     return result

iodata/iodata.py

@@ -252,7 +252,7 @@ class IOData:
     When relevant, these names must have a suffix ``_ao`` or ``_mo`` to clarify in which
     basis the integrals are computed.
     See ``one_ints`` for more details.
-    Array indexes are in physicist's notation.
+    Array indexes are in physicists' notation.
     """
 
     two_rdms: dict = attrs.field(factory=dict)
@@ -262,7 +262,7 @@ class IOData:
     When relevant, these names must have a suffix ``_ao`` or ``_mo`` to clarify in which
     basis the RDMs are computed.
     See ``one_rdms`` for more details.
-    Array indexes are in physicist's notation.
+    Array indexes are in physicists' notation.
     """
 
     def __attrs_post_init__(self):

iodata/test/test_fcidump.py

@@ -42,7 +42,7 @@ def test_load_fcidump_psi4_h2():
     two_mo = mol.two_ints["two_mo"]
     assert_allclose(two_mo.shape, (10, 10, 10, 10))
     assert_allclose(two_mo[0, 0, 0, 0], 0.6589928924251115e00)
-    # Check physicist's notation and symmetry
+    # Check physicists' notation and symmetry
     assert_allclose(two_mo[6, 1, 5, 0], 0.5335846565304321e-01)
     assert_allclose(two_mo[5, 1, 6, 0], 0.5335846565304321e-01)
     assert_allclose(two_mo[6, 0, 5, 1], 0.5335846565304321e-01)
@@ -69,7 +69,7 @@ def test_load_fcidump_molpro_h2():
     two_mo = mol.two_ints["two_mo"]
     assert_allclose(two_mo.shape, (4, 4, 4, 4))
     assert_allclose(two_mo[0, 0, 0, 0], 0.6527679278914691e00)
-    # Check physicist's notation and symmetry
+    # Check physicists' notation and symmetry
     assert_allclose(two_mo[3, 0, 2, 1], 0.7756042287284058e-01)
     assert_allclose(two_mo[2, 0, 3, 1], 0.7756042287284058e-01)
     assert_allclose(two_mo[3, 1, 2, 0], 0.7756042287284058e-01)