{
 "cells": [
  {
   "cell_type": "markdown",
   "id": "VSC-40870560",
   "metadata": {
    "language": "markdown"
   },
   "source": [
    "# Parameter Files\n",
    "\n",
    "So far every model has been assembled by hand in Python. That is great for exploration, but science workflows benefit from reproducibility: being able to re-run or share an exact configuration without distributing a notebook. TauREx `.par` files are the answer — a simple INI-style format where each section corresponds to one Python component.\n",
    "\n",
    "The mapping is direct and transparent:\n",
    "- `[Temperature]` → temperature profile\n",
    "- `[Pressure]` → pressure grid\n",
    "- `[Chemistry]` → gas mixture\n",
    "- `[Model]` → forward-model geometry and contributions\n",
    "\n",
    "The same model we built manually in [Transmission spectrum basics](https://escience-taurex.github.io/taurex3/examples/03_transmission_basics.html), [Emission spectrum basics](https://escience-taurex.github.io/taurex3/examples/04_emission_basics.html), and [Cloud models](https://escience-taurex.github.io/taurex3/examples/05_clouds.html) can be expressed in a dozen lines of text. More information about the full parameter-file syntax is [here](../user/taurex/inputfile.rst), and global settings (data paths, log level) are [here](../user/taurex/global.rst)."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "d707bfd5",
   "metadata": {},
   "source": [
    "## Data Note\n",
    "\n",
    "This notebook uses the opacity and CIA files set up in [Setup and opacity data](https://escience-taurex.github.io/taurex3/examples/01_setup_and_data.html). TauREx provides the software to work with these datasets; the files themselves are third-party products from [ExoMol](https://www.exomol.com) and [HITRAN](https://hitran.org/)."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 1,
   "id": "VSC-165713bc",
   "metadata": {
    "language": "python"
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Opacity data located and ready.\n",
      "Parameter file will be written to: ../../examples/tmp/input.par\n"
     ]
    }
   ],
   "source": [
    "from pathlib import Path\n",
    "import os\n",
    "import sys\n",
    "\n",
    "for candidate in (Path.cwd(), *Path.cwd().parents):\n",
    "    if (candidate / '_shared.py').exists():\n",
    "        sys.path.insert(0, str(candidate))\n",
    "        break\n",
    "    nested = candidate / 'examples' / 'notebooks'\n",
    "    if (nested / '_shared.py').exists():\n",
    "        sys.path.insert(0, str(nested))\n",
    "        break\n",
    "\n",
    "from _shared import CIA_DIR, TMP_DIR, XSEC_DIR, ensure_opacity_data\n",
    "\n",
    "ensure_opacity_data(download=False)\n",
    "output_path = Path(os.path.relpath(TMP_DIR / 'input.par', Path.cwd()))\n",
    "xsec_path = os.path.relpath(XSEC_DIR, Path.cwd())\n",
    "cia_path = os.path.relpath(CIA_DIR, Path.cwd())\n",
    "\n",
    "print('Opacity data located and ready.')\n",
    "print(f'Parameter file will be written to: {output_path}')"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 2,
   "id": "VSC-5bbb1366",
   "metadata": {
    "language": "python"
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "[Global]\n",
      "xsec_path = ../../examples/tmp/xsec\n",
      "cia_path = ../../examples/tmp/cia\n",
      "\n",
      "[Chemistry]\n",
      "chemistry_type = taurex\n",
      "fill_gases = H2,He\n",
      "ratio = 0.1741\n",
      "\n",
      "    [[H2O]]\n",
      "    gas_type = constant\n",
      "    mix_ratio = 1e-3\n",
      "\n",
      "[Temperature]\n",
      "profile_type = isothermal\n",
      "T = 2000\n",
      "\n",
      "[Pressure]\n",
      "profile_type = Simple\n",
      "atm_min_pressure = 1e-5\n",
      "atm_max_pressure = 1e5\n",
      "nlayers = 100\n",
      "\n",
      "[Planet]\n",
      "planet_type = Simple\n",
      "planet_mass = 0.74\n",
      "planet_radius = 1.38\n",
      "\n",
      "[Star]\n",
      "star_type = blackbody\n",
      "temperature = 6117\n",
      "radius = 1.16\n",
      "\n",
      "[Model]\n",
      "model_type = transmission\n",
      "\n",
      "    [[Absorption]]\n",
      "\n"
     ]
    }
   ],
   "source": [
    "input_par = f'''[Global]\n",
    "xsec_path = {xsec_path}\n",
    "cia_path = {cia_path}\n",
    "\n",
    "[Chemistry]\n",
    "chemistry_type = taurex\n",
    "fill_gases = H2,He\n",
    "ratio = 0.1741\n",
    "\n",
    "    [[H2O]]\n",
    "    gas_type = constant\n",
    "    mix_ratio = 1e-3\n",
    "\n",
    "[Temperature]\n",
    "profile_type = isothermal\n",
    "T = 2000\n",
    "\n",
    "[Pressure]\n",
    "profile_type = Simple\n",
    "atm_min_pressure = 1e-5\n",
    "atm_max_pressure = 1e5\n",
    "nlayers = 100\n",
    "\n",
    "[Planet]\n",
    "planet_type = Simple\n",
    "planet_mass = 0.74\n",
    "planet_radius = 1.38\n",
    "\n",
    "[Star]\n",
    "star_type = blackbody\n",
    "temperature = 6117\n",
    "radius = 1.16\n",
    "\n",
    "[Model]\n",
    "model_type = transmission\n",
    "\n",
    "    [[Absorption]]\n",
    "'''\n",
    "\n",
    "output_path.parent.mkdir(parents=True, exist_ok=True)\n",
    "output_path.write_text(input_par)\n",
    "print(input_par)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "VSC-cd0fe61c",
   "metadata": {
    "language": "markdown"
   },
   "source": [
    "## Loading the Parameter File\n",
    "\n",
    "`ParameterParser` reads a `.par` file and reconstructs the full model hierarchy — exactly the same objects that would be created by hand in Python. This round-trip confirms that the declarative and programmatic approaches are equivalent.\n",
    "\n",
    "Full syntax details, dynamic-header behaviour, and required section names are documented [here](../user/taurex/inputfile.rst)."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "14c124b4",
   "metadata": {},
   "source": [
    "### Parameter files for multimodel runs\n",
    "\n",
    "Parameter files are also the entry point for TauREx composite forward models. Set `model_type = multi_transit`, `multi_eclipse`, or `multi_directimage` in the main file, then list the regional files in `parfiles`. Each regional file can carry its own temperature, chemistry, pressure, and contribution blocks, while `fractions` in the main file controls the area weighting."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 3,
   "id": "VSC-82697bed",
   "metadata": {
    "language": "python"
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "TransmissionModel\n",
      "Contributions: ['Absorption']\n"
     ]
    }
   ],
   "source": [
    "from taurex.parameter import ParameterParser\n",
    "\n",
    "parser = ParameterParser()\n",
    "parser.read(str(output_path))\n",
    "parser.setup_globals()\n",
    "model = parser.generate_appropriate_model()\n",
    "\n",
    "print(type(model).__name__)\n",
    "print('Contributions:', [c.name for c in model.contribution_list])"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 4,
   "id": "VSC-81f9c637",
   "metadata": {
    "language": "python"
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Temperature object: Isothermal\n",
      "Chemistry object: TaurexChemistry\n",
      "Pressure object: SimplePressureProfile\n"
     ]
    }
   ],
   "source": [
    "print('Temperature object:', type(model.temperature).__name__)\n",
    "print('Chemistry object:', type(model.chemistry).__name__)\n",
    "print('Pressure object:', type(model.pressure).__name__)"
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": ".venv",
   "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.3"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 5
}