Merge branch 'main' into add_individual_intensities

docs/Changing_Parameters/Changing_Param_Example.yml

@@ -0,0 +1,17 @@
+stardis_config_version: 1.0
+atom_data: kurucz_cd23_chianti_H_He.h5
+model:
+    type: marcs
+    fname: ../quickstart/sun.mod
+    final_atomic_number: 30
+opacity:
+    file: {}
+    bf:
+        H_I: {}
+    ff:
+        H_I: {}
+    disable_electron_scattering: False
+    line:
+        disable: False
+        broadening: [radiation, linear_stark, quadratic_stark, van_der_waals]
+no_of_thetas: 10

docs/Custom_Star_Model_with_Marcs/Custom_Star_Model_with_Marcs.ipynb

@@ -0,0 +1,130 @@
+{
+ "cells": [
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "\n",
+    "<span style=\"font-size: 24px;\">In the quickstart notebook you saw STARDIS using the file 'sun.mod' to create spectra based on the sun. Here we will show how to obtain and use a .mod file for a star of your chosen parameters.</span>"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "### Using MARCS to get .mod files\n",
+    "\n",
+    "STARDIS uses files from the [MARCS site](https://marcs.oreme.org/), which \"contains about 52,000 stellar atmospheric models of spectral types F, G and K\". Here we will only be discussing the aspects of MARCS needed for STARDIS. To get started, [go to the 'Search Marcs' tab of the MARCS site](https://marcs.oreme.org/data/)"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "\n",
+    "<span style=\"font-size: 26px;\">https://marcs.oreme.org/data/</span>"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "<div>\n",
+    "<img src=\"search_marcs.png\" width=\"700\"/>\n",
+    "</div>\n",
+    "\n",
+    "*picture of the Search Marcs page*"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "Getting an atmosphere model is as easy as entering a range of parameters of your choosing. For more information on what each of these qualities are, you can click the question marks next to each option or refer to [the MARCS documentation](https://marcs.oreme.org/documents/)."
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "In the below example, we have entered some arbitrary values into MARCS, and on the right are now all files that qualify. Note how the names of the files show the exact parameters of each file and how there are several pages of files you can look through.\n",
+    "\n",
+    "<div>\n",
+    "<img src=\"search_results.png\" width=\"700\"/>\n",
+    "</div>"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "MARCS uses a 'shopping cart' style system for selecting models, called your 'basket'. Once you have selected your chosen models, proceed to the 'Basket' tab to download them. **Make sure you only have '.mod' files selected, as that is the format used by STARDIS.**"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "Below is an example of a yaml file using the 'sun.mod' file. Note that you can provide either the relative or absolute path to your new model data.\n",
+    "\n"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "``` yaml\n",
+    "stardis_config_version: 1.0\n",
+    "atom_data: kurucz_cd23_chianti_H_He.h5\n",
+    "model:\n",
+    "    type: marcs\n",
+    "    fname: sun.mod # <----- this is where the .mod file is specified\n",
+    "    final_atomic_number: 30\n",
+    "opacity:\n",
+    "...\n",
+    "```"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "#### One last thing: gzipped files\n",
+    "\n",
+    "when you download a mod file from MARCS, it will be gzipped (shown by the file ending with '.mod.gz'). By default STARDIS will assume you have extracted the file, however you can add a line to the yaml file 'gzipped: True' as shown below and STARDIS will take care of this for you.\n",
+    "\n",
+    "``` yaml\n",
+    "...\n",
+    "model:\n",
+    "    type: marcs\n",
+    "    fname: sun.mod\n",
+    "    gzipped: True # <----- use this if the file is gzipped\n",
+    "    final_atomic_number: 30\n",
+    "...\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
+}

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
+}

docs/index.rst

@@ -10,6 +10,11 @@ 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>
+   Changing Parameters <Changing_Parameters/Changing_Parameters>
    Example Notebooks <example_notebooks/rotation_broadening>
    Contributing <contributing>
    Bibliography <bibliography>