Documentation for using MARCS to generate a .mod file for STARDIS

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/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 Star Model <Custom_Star_Model_with_Marcs/Custom_Star_Model_with_Marcs>
    Using STARDIS in Parallel <using_stardis_in_parallel/stardis_in_parallel>
    Example Notebooks <example_notebooks/rotation_broadening>
    Contributing <contributing>