{
 "cells": [
  {
   "cell_type": "markdown",
   "id": "11aa9891",
   "metadata": {},
   "source": [
    "# Advanced Settings with GeneralSettings\n",
    "\n",
    "This notebook demonstrates how to use the `advanced.GeneralSettings` class to modify UCLCHEM parameters instead of using parameter dictionaries. This provides a more object-oriented interface with better autocomplete, type checking, and state management."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 1,
   "id": "a876b589",
   "metadata": {
    "execution": {
     "iopub.execute_input": "2026-01-27T12:55:41.955048Z",
     "iopub.status.busy": "2026-01-27T12:55:41.954834Z",
     "iopub.status.idle": "2026-01-27T12:55:43.297102Z",
     "shell.execute_reply": "2026-01-27T12:55:43.296400Z"
    }
   },
   "outputs": [],
   "source": [
    "import uclchem\n",
    "from uclchem import advanced\n",
    "import os\n",
    "\n",
    "# Ensure output directory exists\n",
    "if not os.path.exists(\"output_6\"):\n",
    "    os.makedirs(\"output_6\")"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "891293f2",
   "metadata": {},
   "source": [
    "## Using GeneralSettings Instead of param_dict\n",
    "\n",
    "The traditional way to configure UCLCHEM models is with parameter dictionaries that are passed when running the UCLCHEM model. The `GeneralSettings` class provides an alternative that directly modifies the Fortran module state before running a model. This has the benefit that you can change things globally, and access things that are not exposted through parameter dictionaries.\n",
    "\n",
    "**Key differences:**\n",
    "- Direct access to Fortran variables with autocomplete support\n",
    "- Tracks which settings have been modified\n",
    "- Provides context managers for temporary changes\n",
    "- Settings persist across model runs (not reset automatically)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 2,
   "id": "b379aa8e",
   "metadata": {
    "execution": {
     "iopub.execute_input": "2026-01-27T12:55:43.299467Z",
     "iopub.status.busy": "2026-01-27T12:55:43.299132Z",
     "iopub.status.idle": "2026-01-27T12:55:43.305066Z",
     "shell.execute_reply": "2026-01-27T12:55:43.304081Z"
    }
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Current initial density: 100.0\n",
      "Current initial temperature: 10.0\n"
     ]
    }
   ],
   "source": [
    "# Create settings interface\n",
    "settings = advanced.GeneralSettings()\n",
    "\n",
    "# View current value\n",
    "print(f\"Current initial density: {settings.defaultparameters.initialdens.get()}\")\n",
    "print(f\"Current initial temperature: {settings.defaultparameters.initialtemp.get()}\")"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "f8365c99",
   "metadata": {},
   "source": [
    "## Setting Parameters Directly\n",
    "\n",
    "Instead of creating a `param_dict`, we can set parameters directly:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 3,
   "id": "81f17d02",
   "metadata": {
    "execution": {
     "iopub.execute_input": "2026-01-27T12:55:43.306664Z",
     "iopub.status.busy": "2026-01-27T12:55:43.306492Z",
     "iopub.status.idle": "2026-01-27T12:55:43.309903Z",
     "shell.execute_reply": "2026-01-27T12:55:43.309336Z"
    }
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "New initial density: 10000.0\n"
     ]
    }
   ],
   "source": [
    "# Set model parameters\n",
    "settings.defaultparameters.initialdens = 1e4\n",
    "settings.defaultparameters.initialtemp = 10.0\n",
    "settings.defaultparameters.finaltime = 1.0e6\n",
    "settings.defaultparameters.rout = 0.1\n",
    "settings.defaultparameters.baseav = 1.0\n",
    "settings.defaultparameters.freefall = False\n",
    "settings.defaultparameters.endatfinaldensity = False\n",
    "\n",
    "# Verify changes\n",
    "print(f\"New initial density: {settings.defaultparameters.initialdens.get()}\")"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "b4ba255b",
   "metadata": {},
   "source": [
    "## Running a Model with GeneralSettings\n",
    "\n",
    "When using `GeneralSettings`, the Fortran code uses the values we've set directly. However, **file paths (outputFile, abundSaveFile) should still be set via `param_dict`** since these are handled specially by the model wrapper and file parsers."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 4,
   "id": "0b401960",
   "metadata": {
    "execution": {
     "iopub.execute_input": "2026-01-27T12:55:43.311879Z",
     "iopub.status.busy": "2026-01-27T12:55:43.311614Z",
     "iopub.status.idle": "2026-01-27T12:55:50.989628Z",
     "shell.execute_reply": "2026-01-27T12:55:50.988686Z"
    }
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Model completed successfully\n"
     ]
    }
   ],
   "source": [
    "# Ensure output directory exists\n",
    "if not os.path.exists(\"output_6\"):\n",
    "    os.makedirs(\"output_6\")\n",
    "\n",
    "# Note: Output file paths should be set via param_dict, not GeneralSettings\n",
    "# This is because file paths are handled specially by the model wrapper\n",
    "param_dict = {\n",
    "    \"outputFile\": \"output_6/baseline.dat\",\n",
    "}\n",
    "\n",
    "# Run model with param_dict for file I/O, but using GeneralSettings for other parameters\n",
    "out_species = [\"SO\", \"CO\"]\n",
    "cloud = uclchem.model.Cloud(param_dict=param_dict, out_species=out_species)\n",
    "print(f\"Model completed successfully\")"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "c375afc1",
   "metadata": {},
   "source": [
    "## Viewing Modified Settings\n",
    "\n",
    "You can check which settings have been changed from their defaults:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 5,
   "id": "77a20662",
   "metadata": {
    "execution": {
     "iopub.execute_input": "2026-01-27T12:55:50.991245Z",
     "iopub.status.busy": "2026-01-27T12:55:50.991082Z",
     "iopub.status.idle": "2026-01-27T12:55:50.994924Z",
     "shell.execute_reply": "2026-01-27T12:55:50.993889Z"
    }
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "\n",
      "======================================================================\n",
      "Modified Settings\n",
      "======================================================================\n",
      "\n",
      "\n",
      "defaultparameters:\n",
      "  baseav                              2.0 → 1.0\n",
      "  finaltime                           5000000.0 → 1000000.0\n",
      "  initialdens                         100.0 → 10000.0\n",
      "  rout                                0.05000000074505806 → 0.1\n",
      "\n"
     ]
    }
   ],
   "source": [
    "# Show all modified settings\n",
    "settings.print_all_edited()"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "530bbbc1",
   "metadata": {},
   "source": [
    "## Using Context Managers for Temporary Changes\n",
    "\n",
    "The `temporary_changes()` context manager is useful for running models with temporary parameter modifications without affecting the global state:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 6,
   "id": "2c7646d8",
   "metadata": {
    "execution": {
     "iopub.execute_input": "2026-01-27T12:55:50.996710Z",
     "iopub.status.busy": "2026-01-27T12:55:50.996559Z",
     "iopub.status.idle": "2026-01-27T12:55:58.768672Z",
     "shell.execute_reply": "2026-01-27T12:55:58.767712Z"
    }
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Baseline density: 10000.0\n",
      "Inside context: 100000.0\n"
     ]
    },
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "High density model completed successfully\n",
      "After context: 100.0\n"
     ]
    },
    {
     "name": "stderr",
     "output_type": "stream",
     "text": [
      "/tmp/ipykernel_4059/1116252038.py:18: UserWarning: defaultparameters.initialdens has been modified outside of GeneralSettings (cache out of sync)\n",
      "  print(f\"After context: {settings.defaultparameters.initialdens.get()}\")\n"
     ]
    }
   ],
   "source": [
    "# Set a baseline density\n",
    "settings.defaultparameters.initialdens = 1e4\n",
    "print(f\"Baseline density: {settings.defaultparameters.initialdens.get()}\")\n",
    "\n",
    "# Run model with temporary higher density\n",
    "with settings.temporary_changes():\n",
    "    settings.defaultparameters.initialdens = 1e5\n",
    "    print(f\"Inside context: {settings.defaultparameters.initialdens.get()}\")\n",
    "\n",
    "    # Use param_dict for file paths\n",
    "    param_dict_high = {\"outputFile\": \"output_6/high_density.dat\"}\n",
    "    cloud_high = uclchem.model.Cloud(\n",
    "        param_dict=param_dict_high, out_species=out_species\n",
    "    )\n",
    "    print(f\"High density model completed successfully\")\n",
    "\n",
    "# Settings automatically restored\n",
    "print(f\"After context: {settings.defaultparameters.initialdens.get()}\")"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "5d63fe44",
   "metadata": {},
   "source": [
    "## Comparing Results\n",
    "\n",
    "Let's load and compare the two model runs:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 7,
   "id": "753a4d95",
   "metadata": {
    "execution": {
     "iopub.execute_input": "2026-01-27T12:55:58.770308Z",
     "iopub.status.busy": "2026-01-27T12:55:58.770140Z",
     "iopub.status.idle": "2026-01-27T12:55:58.795543Z",
     "shell.execute_reply": "2026-01-27T12:55:58.794798Z"
    }
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Baseline final CO abundance: 1.53e-04\n",
      "High density final CO abundance: 1.53e-04\n"
     ]
    }
   ],
   "source": [
    "result_baseline = uclchem.analysis.read_output_file(\"output_6/baseline.dat\")\n",
    "result_high_dens = uclchem.analysis.read_output_file(\"output_6/high_density.dat\")\n",
    "\n",
    "print(f\"Baseline final CO abundance: {result_baseline['CO'].iloc[-1]:.2e}\")\n",
    "print(f\"High density final CO abundance: {result_high_dens['CO'].iloc[-1]:.2e}\")"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "11fa1d8f",
   "metadata": {},
   "source": [
    "## Resetting Settings\n",
    "\n",
    "You can reset individual settings or all settings to defaults:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 8,
   "id": "bb5015f8",
   "metadata": {
    "execution": {
     "iopub.execute_input": "2026-01-27T12:55:58.797307Z",
     "iopub.status.busy": "2026-01-27T12:55:58.797128Z",
     "iopub.status.idle": "2026-01-27T12:55:58.800206Z",
     "shell.execute_reply": "2026-01-27T12:55:58.799560Z"
    }
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Before reset: 100.0\n",
      "After reset: 100.0\n"
     ]
    }
   ],
   "source": [
    "# Reset a single setting\n",
    "print(f\"Before reset: {settings.defaultparameters.initialdens.get()}\")\n",
    "settings.defaultparameters.initialdens.reset()\n",
    "print(f\"After reset: {settings.defaultparameters.initialdens.get()}\")"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "ae45254c",
   "metadata": {},
   "source": [
    "## Searching for Settings\n",
    "\n",
    "You can search across all modules for settings matching a pattern:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 9,
   "id": "0c387d99",
   "metadata": {
    "execution": {
     "iopub.execute_input": "2026-01-27T12:55:58.801970Z",
     "iopub.status.busy": "2026-01-27T12:55:58.801813Z",
     "iopub.status.idle": "2026-01-27T12:55:58.805151Z",
     "shell.execute_reply": "2026-01-27T12:55:58.804598Z"
    }
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Found 17 settings related to 'temp':\n",
      "  defaultparameters.initialtemp: 10.0\n",
      "  heating.max_line_solve_attempts: 5\n",
      "  cshock_mod.maxtemp: 0.0\n",
      "  cshock_mod.minimumpostshocktemp: 0.0\n",
      "  jshock_mod.maxtemp: 0.0\n"
     ]
    }
   ],
   "source": [
    "# Search for settings related to \"temp\"\n",
    "temp_settings = settings.search(\"temp\")\n",
    "print(f\"Found {len(temp_settings)} settings related to 'temp':\")\n",
    "for name, setting in list(temp_settings.items())[:5]:\n",
    "    print(f\"  {name}: {setting.get()}\")"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "eab84d10",
   "metadata": {},
   "source": [
    "## Best Practices\n",
    "\n",
    "**When to use GeneralSettings:**\n",
    "- You want to run multiple models with the same base configuration\n",
    "- You need to modify settings that aren't easily accessible via `param_dict`\n",
    "- You want autocomplete support in your IDE\n",
    "- You're building a GUI or interactive application\n",
    "\n",
    "**When to use param_dict:**\n",
    "- One-off model runs\n",
    "- Grid computations where each run has different parameters\n",
    "- **File paths (outputFile, abundSaveFile)** - always use param_dict for these\n",
    "- You want parameters explicitly documented in the function call\n",
    "\n",
    "**Important Notes:**\n",
    "- ⚠️ Settings are **global** and persist across model runs\n",
    "- ⚠️ **Not thread-safe** - don't use with multiprocessing\n",
    "- ⚠️ **File I/O paths** should always be set via `param_dict`, not GeneralSettings\n",
    "- Always reset or use context managers when running multiple models"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "a80a0ed4",
   "metadata": {},
   "source": [
    "## Summary\n",
    "\n",
    "The `GeneralSettings` class provides a powerful alternative to parameter dictionaries for configuring UCLCHEM models. Key features:\n",
    "\n",
    "- Direct access to all Fortran module variables\n",
    "- Edit tracking and reset capabilities\n",
    "- Context managers for temporary changes  \n",
    "- Search functionality across all settings\n",
    "- Better IDE autocomplete support\n",
    "\n",
    "See the documentation for more details on the `advanced` module."
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python 3",
   "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.13.11"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 5
}