Merge pull request #364 from tovrstra/fcidump-clarification

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)