cgem.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "id": "90e98304-27c9-481b-961a-feb27856f03a",
   "metadata": {
    "tags": []
   },
   "source": [
    "# CGEM the Notebook\n",
    "\n",
    "This Notebook gives an overview of looking at CGEM output with Python."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "61e1b537-9831-47bb-b7c8-492c64721deb",
   "metadata": {},
   "source": [
    "## Compile the code"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "3646d5d8-58b8-46f9-a575-a487876ab859",
   "metadata": {
    "scrolled": true,
    "tags": []
   },
   "outputs": [],
   "source": [
    "!make"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "2dcaf99f-d92d-44ee-9f26-7fe1e9a96d75",
   "metadata": {},
   "source": [
    "## Import CGEM Python functions\n",
    "Current library of functions are in **cgem.py**, absolutely devoid of commenting and error checking.  (Sorry, try back later.)\n",
    "\n",
    "Click the folder icon on the left to see the files."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "3467d56d-d77c-43d4-86bc-e4a1faa2f9da",
   "metadata": {},
   "outputs": [],
   "source": [
    "#Imports all the Python functions from cgem.nml and keep the original names\n",
    "from cgem import *"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "1248b0f0-b89a-455c-85b4-ccb770b51ee4",
   "metadata": {},
   "source": [
    "---"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "be075556-756f-4b7b-b536-db66d35a3cc1",
   "metadata": {},
   "source": [
    "## Basics of namelists\n",
    "\n",
    "CGEM reads the input parameters from namelists:\n",
    "- **grid.nml**: parameters that should come from the hydro code\n",
    "- **cgem.nml**: parameters that should (mostly) be private to the biogeochem code\n",
    "\n",
    "Use **f90nml** to read and manipulate namelists.  See:\n",
    "- https://f90nml.readthedocs.io/en/latest/index.html"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "de2613f2-5f75-4254-a934-c0065d866864",
   "metadata": {},
   "outputs": [],
   "source": [
    "#Import f90nml\n",
    "import f90nml"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "80e64cee-e056-4155-9c6b-9c2a4c359f05",
   "metadata": {},
   "source": [
    "### The grid parameters:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "6088d399-27d7-47c8-a1e7-fab48a572bc4",
   "metadata": {},
   "outputs": [],
   "source": [
    "#Read and print grid parameters\n",
    "grid = f90nml.read('grid.nml')\n",
    "print(\"Grid parameters\")\n",
    "print(grid)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "06d66e83-a199-4be1-ae2c-fbf77135154d",
   "metadata": {},
   "source": [
    "### The CGEM parameters"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "f6b7f688-df97-486d-bf9e-c81c18b9872a",
   "metadata": {},
   "outputs": [],
   "source": [
    "#Read and print cgem parameters\n",
    "cgem = f90nml.read('cgem.nml')\n",
    "print(\"CGEM parameters\")\n",
    "print(cgem)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "12c14ec5-7970-4c0e-8b3b-fdd1d16de447",
   "metadata": {},
   "source": [
    "### Get the value of a single element\n",
    "```\n",
    "value = namelist_object.get('named_list').get('parameter')\n",
    "```"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "662f13fd-f47d-4191-ae38-6aec98773139",
   "metadata": {},
   "outputs": [],
   "source": [
    "## Get the number of layers and number of phytoplankton species\n",
    "km = grid.get('hydro').get('km')\n",
    "nospA = cgem.get('nosp').get('nospa')\n",
    "print(\"There are \",km,\" layers and \",nospA,\" phytoplankton species\")"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "240af04d-c626-4e31-af99-e2280529e036",
   "metadata": {},
   "source": [
    "---"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "14dbb004-724b-40ee-9399-c50856922eb6",
   "metadata": {
    "tags": []
   },
   "source": [
    "## The CGEM Python library\n",
    "\n",
    "See **cgem.py** for the details.\n",
    "\n",
    "### Functions:\n",
    "- `cgem_plot1D(grid,var)`: make timeseries plot of state variable `var` at layer `k=1`\n",
    "- `cgem_plotks(grid,var)`: make timeseries plot of a state variable `var` at each layer `k`\n",
    "- `cgem_plotAs(grid,cgem)`: make timeseries plot of each phytoplankton group at layer `k=1`\n",
    "- `cgem_getvar(var)`: gets a state variable `var` at layer `k=1`. \n",
    "- `cgem_tstart(grid)`: gets datetime object for start of simulation\n",
    "- `cgem_tend(grid)`:  gets datetime object for end of simulation\n",
    "- `cgem_timearray(grid)`: A time array, defined by the beginning of simulation and the array length of results from a run, rather than simulation start and end times.  (This is in case the code crashed.) \n",
    "\n",
    "### To work with the output, save to a variable\n",
    "For example:\n",
    "```\n",
    "phytoplankton = cgem_getvar('A')\n",
    "```\n",
    "or\n",
    "```\n",
    "time = cgem_timearray(grid)\n",
    "```"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "bc8da401-b590-49cd-857f-0299d79a41f2",
   "metadata": {},
   "source": [
    "### Once you save the variables, you can calculate stuff or make your own plots"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "5c922aac-9ae6-4dfe-a978-7269080c5a11",
   "metadata": {},
   "outputs": [],
   "source": [
    "A = cgem_getvar(\"A\")\n",
    "print(A)\n",
    "print(\"mean, max, min of A:\",A.mean(),max(A),min(A))"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "8d2e0f68-fe21-4f0f-a1fd-52e44fdc4488",
   "metadata": {},
   "source": [
    "## Basic plots\n",
    "\n",
    "This always plots layer `k=1`.\n",
    "\n",
    "syntax:\n",
    "```\n",
    "cgem_plot1D(grid,var)\n",
    "```\n",
    "\n",
    "Options for var are:\n",
    "```\n",
    "A, Qn, Qp, Z, NO3, NH4, PO4, DIC, O2, OM1_A, OM2_A, OM1_Z, OM2_Z, OM1_R, OM2_R, CDOM, Si, Alk, Tr\n",
    "```\n",
    "\n",
    "If using more than one species, use the name and number, e.g., `A3`."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "920717cc-a0da-4add-aa90-7ccd766b7997",
   "metadata": {},
   "outputs": [],
   "source": [
    "#Plot the first phytoplankton group, use 'A' or 'A1'\n",
    "cgem_plot1D(grid,'A')"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "6e769543-2e92-40e1-bd41-d4ec22263586",
   "metadata": {},
   "source": [
    "---"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "84990ddc-81ad-406a-855b-1f9abf5555db",
   "metadata": {},
   "source": [
    "## Modifying the namelists\n",
    "You can directly edit the **.nml** files by clicking on them, editing, and saving, but it is actually more reliable to do this in Python. The Fortran code won't notice if you don't define the correct number of parameters and will crash with a segmentation fault if you do that wrong.\n",
    "\n",
    "Some notes:\n",
    "- Fortran isn't case sensitive, but Python is.  Use all lower case when using f90nml.\n",
    "- Using `force=True` with nml.write will overwrite the nml file.  The CGEM code needs those files to be named **grid.nml** and **cgem.nml**.\n",
    "- If you mess something up and want to start with the default **cgem** or **grid.nml**, do `!cp nml_save/cgem.nml .` and `!cp nml_save/grid.nml .`  \n",
    "- You can check the difference between current and default nmls by doing `!diff grid.nml nml_save/grid.nml`.  \n",
    "- In Python, you can do `![whatever the regular shell command is]`."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "329934ca-811a-4bd7-a94f-af7917e1fc92",
   "metadata": {},
   "source": [
    "### Example: Change the simulation length"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "e626e5f8-6c6c-440c-bb62-e419b05f7999",
   "metadata": {},
   "outputs": [],
   "source": [
    "#Check end of simulation month\n",
    "print(grid['hydro']['imone'])\n",
    "#Change it to March\n",
    "grid['hydro']['imone'] = 3\n",
    "# Check it\n",
    "print(grid['hydro']['imone'])\n",
    "# Write the nml file\n",
    "grid.write('grid.nml',force=True)\n",
    "#Redo the phytoplankton plot\n",
    "cgem_plot1D(grid,'A')"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "13a49778-6b35-4f83-b728-3569c96e1b32",
   "metadata": {},
   "source": [
    "### Resetting the nml file\n",
    "Use the `cp` command from the shell, then redefine the namelist object."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "18933b6d-d9e4-48e1-be88-26ec9331b2d0",
   "metadata": {},
   "outputs": [],
   "source": [
    "!cp nml_save/grid.nml .\n",
    "grid = f90nml.read('grid.nml')"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "9bf20fe0-84fe-4d30-927f-0c97590283d0",
   "metadata": {},
   "outputs": [],
   "source": [
    "#Redo the phytoplankton plot\n",
    "cgem_plot1D(grid,'A2')"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "6136b7c4-e200-4f5e-a48e-0b2405e884a6",
   "metadata": {},
   "source": [
    "---"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "8964f40c-fa61-4ccd-9915-8a03d97eb563",
   "metadata": {},
   "source": [
    "## Making custom plots\n",
    "\n",
    "So far, there is a limited selection of canned plot functions.  When making plots, define a time array if you don't want the x-axis to be 'timesteps'."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "62315b34-5fec-4598-b9f9-ba836f06951e",
   "metadata": {},
   "outputs": [],
   "source": [
    "T = cgem_timearray(grid)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "197051be-0ed1-4fc1-909d-b0e210d7490e",
   "metadata": {},
   "source": [
    "## That's all we got for now.\n",
    "To plot a bunch of variables on the same plot, or change colors and stuff, you write your own Python..."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "a93488e7-5864-43d3-baf2-833aebadda6e",
   "metadata": {},
   "outputs": [],
   "source": [
    "Z = cgem_getvar('Z')\n",
    "NO3 = cgem_getvar('NO3')\n",
    "NH4 = cgem_getvar('NH4')\n",
    "PO4 = cgem_getvar('PO4')"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "c9eb2e38-9ba1-460e-a41c-2810114f456a",
   "metadata": {},
   "outputs": [],
   "source": [
    "fig, ax = plt.subplots(figsize=(20, 5))\n",
    "ax.plot(T,NO3)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "4822430b-9ece-4784-bbb5-cce122d7fc12",
   "metadata": {},
   "outputs": [],
   "source": [
    "fig, ax = plt.subplots(figsize=(20, 5))\n",
    "ax.plot(T,Z)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "430451cb-3cea-4f66-9d58-a6f130d064f4",
   "metadata": {},
   "outputs": [],
   "source": [
    "fig, ax = plt.subplots(figsize=(20, 5))\n",
    "ax.plot(T,NO3, color='black')\n",
    "ax.plot(T,NH4, color='blue')\n",
    "ax.plot(T,PO4, color='cyan')"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "42c5d844-9d36-4391-b1f1-958e1ad119e2",
   "metadata": {},
   "outputs": [],
   "source": []
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python 3 (ipykernel)",
   "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.10.9"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 5
}