Documentation for using/getting a new CARSUS atom_data file for STARD…

…IS (#226) * Documentation for using/getting a new CARSUS atom_data file for STARDIS * edited the doc, forgot to save before first commit :/ * added part on using vald_linelist: * Typo, format, and clarification edits * directory managment and added to index.rst * heading format fix (hopefully) --------- Co-authored-by: Joshua Shields <[email protected]>
tardis-sn · Dec 2, 2024 · 4279f55 · 4279f55
1 parent fd1b669
commit 4279f55
Show file tree

Hide file tree

Showing 2 changed files with 102 additions and 0 deletions.
diff --git a/docs/Custom_atomic_data/Custom_atomic_data.ipynb b/docs/Custom_atomic_data/Custom_atomic_data.ipynb
@@ -0,0 +1,101 @@
+{
+ "cells": [
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## Using Your Own Atomic Data\n",
+    " To run a simulation, STARDIS requires an atomic data file that has information on the properties of atoms and molecules needed by STARDIS. While [\"kurucz_cd23_chianti_H_He.h5\"](https://dev.azure.com/tardis-sn/TARDIS/_apis/git/repositories/tardis-refdata/items?path=atom_data/kurucz_cd23_chianti_H_He.h5&resolveLfs=true) is the default atomic data used by STARDIS, you can create and use other atomic data files by using [CARSUS](https://tardis-sn.github.io/carsus/). For more information on using CARSUS you can access the [CARSUS documentation](https://tardis-sn.github.io/carsus/index.html)."
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "### Relevant CARSUS Data to Collect\n",
+    "While CARSUS accumulates all sorts of data when compiling the atomic data files, not everything it can include is necessary or relevant for running STARDIS. Here is a list of what data/readers you should make sure to include when running CARSUS:\n",
+    "- [atomic weights & ionization energy from NIST](https://tardis-sn.github.io/carsus/io/nist.html)\n",
+    "- [Robert Kurucz’s Atomic Linelist (GFALL)](https://tardis-sn.github.io/carsus/io/gfall.html)\n",
+    "- [atomic and molecular transitions from VALD](https://tardis-sn.github.io/carsus/io/vald.html)\n",
+    "- [Molecular formation from Barklem & Collet 2016](https://tardis-sn.github.io/carsus/io/barklem2016.html)\n"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "<span style=\"font-size: 24px;\">Use CARSUS and follow their documentation to get a data file:</span>\n",
+    "\n",
+    "<span style=\"font-size: 24px;\">[https://tardis-sn.github.io/carsus/](https://tardis-sn.github.io/carsus/)</span>"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "To use new atomic data file in a simulation,  add/edit the line in your yaml file `atom_data: <path/to/atomic_data>`. This path can be *either* the relative or absolute path. Your atomic data file should have the file extension '.h5'."
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "The file 'kurucz_cd23_chianti_H_He.h5' referenced below is the default atomic_data used by STARDIS.\n",
+    "``` yaml\n",
+    "stardis_config_version: 1.0\n",
+    "atom_data: kurucz_cd23_chianti_H_He.h5 # <----- put the relative or absolute path here\n",
+    "model:\n",
+    "...\n",
+    "```"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "### Using VALD linelists\n",
+    "\n",
+    "Possibly one of the most important reasons you would want to use a custom atomic data file would be to take advantage of a tailored VALD linelist. You can refer to [VALD's documentation](https://www.astro.uu.se/valdwiki) for information on these lists if you are unfamiliar. To create a detailed and accurate stellar spectrum, we highly recommend looking into using a VALD linelist bundled into your atomic data."
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "If you have included a VALD linelist in your atom_data file, then you **must** make the following change to your Yaml file for the linelist to be used:\n",
+    "``` yaml\n",
+    "...\n",
+    "line:\n",
+    "        disable: False\n",
+    "        broadening: [radiation, linear_stark, quadratic_stark, van_der_waals]\n",
+    "        vald_linelist:  #<-----\n",
+    "            use_linelist: True #<----- will default to false, so must set to True\n",
+    "            shortlist: <boolean> #<----- VALD can output lists in 'long' form or 'short' form; set accordingly\n",
+    "no_of_thetas: 20\n",
+    "...\n",
+    "```"
+   ]
+  }
+ ],
+ "metadata": {
+  "kernelspec": {
+   "display_name": "stardis",
+   "language": "python",
+   "name": "python3"
+  },
+  "language_info": {
+   "codemirror_mode": {
+    "name": "ipython",
+    "version": 3
+   },
+   "file_extension": ".py",
+   "mimetype": "text/x-python",
+   "name": "python",
+   "nbconvert_exporter": "python",
+   "pygments_lexer": "ipython3",
+   "version": "3.12.4"
+  }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 2
+}
diff --git a/docs/index.rst b/docs/index.rst
@@ -10,6 +10,7 @@ This is the documentation for STARDIS.
    Quickstart <quickstart/quickstart>
    Downloading and Installation <installation>
    Physics of STARDIS <physics/physics_of_stardis>
+   Custom Atomic Data <Custom_atomic_data/Custom_atomic_data>
    Possible STARDIS Outputs <possible_stardis_outputs/possible_stardis_outputs>
    Custom Star Model <Custom_Star_Model_with_Marcs/Custom_Star_Model_with_Marcs>
    Using STARDIS in Parallel <using_stardis_in_parallel/stardis_in_parallel>