Adds docs for various similar level columns (#407)

* Adds docs for various similar level columns Also moved notation to a more accessible spot. * Further docs on levels * Resolve comments
tardis-sn · Dec 2, 2024 · c250524 · c250524
1 parent 4f16b9e
commit c250524
Show file tree

Hide file tree

Showing 4 changed files with 42 additions and 9 deletions.
diff --git a/docs/index.rst b/docs/index.rst
@@ -11,6 +11,7 @@ Carsus is a package to manage atomic datasets. It can read data from a variety o
     installation.rst
     quickstart
     development/compare_atomic_files
+    reference/notation.rst
 
 .. toctree::
     :maxdepth: 2
@@ -26,13 +27,21 @@ Carsus is a package to manage atomic datasets. It can read data from a variety o
     io/vald
     io/barklem2016
 
+.. toctree::
+    :maxdepth: 2
+    :caption: Reference
+    :hidden:
+
+    reference/notation.rst
+    reference/level_index_id_number.rst
+
 .. toctree::
     :maxdepth: 2
     :caption: Research with Carsus
     :hidden:
 
     research/publications.rst
-    research/references.rst
+    research/bibliography.rst
 
 
 .. toctree::
@@ -50,13 +59,6 @@ Carsus is a package to manage atomic datasets. It can read data from a variety o
 
     api/modules
 
-.. toctree::
-    :maxdepth: 2
-    :caption: Legacy Code
-    :hidden:
-
-    legacy/index.rst
-
 
 .. seealso::
     Need help? Contact us `on Gitter <https://gitter.im/tardis-sn/carsus/>`_.
diff --git a/docs/reference/level_index_id_number.rst b/docs/reference/level_index_id_number.rst
@@ -0,0 +1,31 @@
+***************
+Differences between level_index, level_id and level_number
+***************
+
+=============
+level_index
+=============
+
+DataFrame index for each electronic energy level. Different for each ion. 
+Third index for energy levels after atomic number and ion charge. Used in GFALL,
+Chianti and CMFGEN levels DataFrames.
+
+For photoionization cross-sections, this is used to determine the lower and upper
+levels of cross-sections.
+
+=============
+level_id
+=============
+
+Global unique `level_id` across all species used to assign unique IDs even for the cut level and line data.
+Computed from level index. Typically has an upper and lower form to connect levels
+together.
+
+=============
+level_number
+=============
+
+Index in the order of the level energies within each species. 
+For example, species Si II has level_number 0 to n. 
+Often used in a multi-index with atomic_number, ion_number.
+Connects upper and lower energy levels.
diff --git a/docs/development/notation.rst → docs/reference/notation.rst b/docs/development/notation.rst → docs/reference/notation.rst
diff --git a/docs/research/references.rst → docs/research/bibliography.rst b/docs/research/references.rst → docs/research/bibliography.rst
@@ -1,5 +1,5 @@
 **********
-References
+Bibliography
 **********
 
 .. bibliography:: ../references.bib