{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Warmup\n",
    "\n",
    "\n",
    "Fisrt of all, we need to install Docker/Docker Desktop.\n",
    "\n",
    "- [How to install Docker on Linux?](https://envdes.github.io/clmu-app/container/install_docker.html)\n",
    "\n",
    "- [How to install Docker Desktop](https://www.docker.com/products/docker-desktop/)\n",
    "  \n",
    "Platform: arm64/amd64\n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## workflow\n",
    "\n",
    "![workflow](./figs/wp.png)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### 1 Initailize"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Before initialization, we need to pull the docker image.\n",
    "\n",
    "**for Linux and MacOS** : use `docker pull envdes/clmu-app:1.1` in command line or `usp.docker(\"pull\")` in Python\n",
    "\n",
    "**for Windows**: pull the image `envdes/clmu-app:1.1` manually from Docker Desktop"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 1,
   "metadata": {},
   "outputs": [],
   "source": [
    "from pyclmuapp import usp_clmu\n",
    "\n",
    "# initialize\n",
    "usp = usp_clmu() # will create a temporary working directory workdir\n",
    "# can use pwd to specify the working directory \n",
    "#, e.g. usp_clmu(pwd=\"/path/to/working/directory\"), default is the current working directory"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Using `ups_clmu()` will initiate the usp_clmu class. The class will take the following parameters:\n",
    "\n",
    "- The inputfolder, outputfolder, logfolder, and scriptfolder will be checked in the current working directory.\n",
    "- If the folder does not exist, it will be created.\n",
    "- User can specify the folders by using the inputfolder, outputfolder, logfolder, and scriptfolder parameters.\n",
    "- Inputfolder, outputfolder, logfolder, and scriptfolder parameters are optional."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### 2 Run a simulation"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "usp_res = usp.run(\n",
    "            case_name = \"usp_spinup\", \n",
    "            SURF=\"surfdata.nc\",\n",
    "            FORCING=\"forcing.nc\",\n",
    "            RUN_STARTDATE = \"2002-01-01\", # the start date of the simulation, must include in the forcing file time range\n",
    "            STOP_OPTION = \"nyears\", # can be 'ndays', 'nmonths', 'nyears', 'nsteps'; nsteps means 1800s\n",
    "            STOP_N = \"10\", # run for 10 years\n",
    "            #RUN_TYPE= \"coldstart\", # coldstart is the default option\n",
    "        )\n",
    "usp_res"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "parameters of `usp.run`\n",
    "\n",
    "- output_prefix (str) – The output file name. The default is “_clm.nc”. if the output_prefix is none, the output file name will not be changed.\n",
    "\n",
    "- case_name (str) – The case name. The default is “usp_case”.\n",
    "\n",
    "- RUN_STARTDATE (str) – The start date of the run. The default is “2012-08-08”.\n",
    "\n",
    "- START_TOD (str) – The start time of the day. The default is “00000”.\n",
    "\n",
    "- STOP_OPTION (str) – The stop option. The default is “ndays”.\n",
    "\n",
    "- STOP_N (str) – The number of days to run. The default is “10”.\n",
    "\n",
    "- ATM_DOM (str) – The path to the domain data file. Will use the domain data provided by the user. The default is None.\n",
    "\n",
    "- SURF (str) – The path to the surface data file. Will use the surface data provided by the user. The default is None.\n",
    "\n",
    "- FORCING (str) – The path to the forcing data file. Will use the forcing data provided by the user. The default is None.\n",
    "\n",
    "- RUN_TYPE (str) – The type of the run. The default is “coldstart”. The other option is “branch”.\n",
    "\n",
    "- RUN_REFCASE (str) – The reference case. The default is “None”. Need to be provided when the RUN_TYPE is “branch”.\n",
    "\n",
    "- RUN_REFDATE (str) – The reference date. The default is “None”. Need to be provided when the RUN_TYPE is “branch”.\n",
    "\n",
    "- RUN_REFTOD (str) – The reference time of the day. The default is “00000”. Need to be provided when the RUN_TYPE is “branch”.\n",
    "\n",
    "- password (str) – The password for the docker. The default is “None”. Need to be provided when server is needed.\n",
    "\n",
    "- iflog (bool) – The flag to log the output. The default is True.\n",
    "\n",
    "- logfile (str) – The log file name. The default is pwd+”log.log”.\n",
    "\n",
    "- urban_hac (str) – The flag to turn on the urban HAC. The default is “ON_WASTEHEAT”. valid_values=”OFF”,”ON”,”ON_WASTEHEAT”.\n",
    "\n",
    "- run_tyep (str) – The type of the run. The default is “usp”. or use “usp-execp” to run when container is started."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### 3 How to get your own input files?\n",
    "\n",
    "For surface data: [Make your own surface data](https://junjieyu-uom.github.io/pyclmuapp/notebooks/own/prepare_urbansurf_10evlurb.html).\n",
    "\n",
    "For forcing data: [Make your own forcing data from ERA5](https://junjieyu-uom.github.io/pyclmuapp/notebooks/own/prepare_forcing_from_era5.html).publish_display_data"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### 3 How to change the surface and forcing data?\n",
    "\n",
    "- If we have run a simulation using the `usp` object, \n",
    "the forcing data path is stored in the `usp.usr_forcing_file` attribute, \n",
    "the surface data path is stored in the `usp.surfdata` attribute, \n",
    "we can modify the forcing data by calling the `usp.modify_forcing` method and modify the surface data by calling the `usp.modify_surf` method,\n",
    "and run the simulation again using the `usp.run` method. \n",
    "\n",
    "- If there is no forcing data path provided or have not run a simulation using the `usp` object, check the forcing, by calling `usp.check_forcing(usr_forcing=\"forcing.nc\")` method\n",
    "- If there is no surface data path provided or have not run a simulation using the `usp` object, check the surface, by calling `usp.check_surf(usr_surf=\"sufdata.nc\")` method\n",
    "\n",
    "For example,\n",
    "\n",
    "```python\n",
    "# for modifying the surface data with adding 0.2 to ALB_ROOF_DIR \n",
    "usp.modify_surf(action={\"ALB_ROOF_DIR\":0.2}, surfata_name=\"surface_modfied.nc\", mode=\"add\")\n",
    "\n",
    "# for modifying the forcing data with adding 1.0 to Tair\n",
    "usp.modify_forcing(action={\"Tair\": 1}, mode=\"add\", forcing_name=\"forcing_replaced.nc\")\n",
    "```"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "**Variables of surface data can be directly modified by `usp.modify_surf()`**\n",
    "\n",
    "| Variables      | Long name      | Type      | Unit      |\n",
    "|:---------|:--------|:---------|:---------|\n",
    "| CANYON_HWR | Canyon height to width ratio | Morphological | Unitless |\n",
    "| HT_ROOF | Height of roof | Morphological | Meters |\n",
    "| THICK_ROOF | Thickness of roof | Morphological | Meters |\n",
    "| THICK_WALL | Thickness of wall | Morphological | Meters |\n",
    "| WTLUNIT_ROOF | Fraction of roof | Morphological | Unitless |\n",
    "| WTROAD_PERV | Fraction of pervious road | Morphological | Unitless |\n",
    "| WALL_TO_PLAN_AREA_RATIO | Ratio of wall area to plan area | Morphological | Unitless |\n",
    "| WIND_HGT_CANYON | Height of wind in canyon | Morphological | Meters |\n",
    "| NLEV_IMPROAD | Number of impervious road layers | Morphological | Unitless |\n",
    "| TK_ROOF | Thermal conductivity of roof | Thermal | W/m*k |\n",
    "| TK_WALL | Thermal conductivity of wall | Thermal | W/m*k |\n",
    "| TK_IMPROAD | Thermal conductivity of impervious road | Thermal | W/m*k |\n",
    "| CV_ROOF | Volumetric heat capacity of roof | Thermal | J/m^3*k |\n",
    "| CV_WALL | Volumetric heat capacity of wall | Thermal | J/m^3*k |\n",
    "| CV_IMPROAD | Volumetric heat capacity of impervious road | Thermal | J/m^3*k |\n",
    "| EM_IMPROAD | Emissivity of impervious road | Radiative | Unitless |\n",
    "| EM_PERROAD | Emissivity of pervious road | Radiative | Unitless |\n",
    "| EM_ROOF | Emissivity of roof | Radiative | Unitless |\n",
    "| EM_WALL | Emissivity of wall | Radiative | Unitless |\n",
    "| ALB_IMPROAD_DIR | Direct albedo of impervious road | Radiative | Unitless |\n",
    "| ALB_IMPROAD_DIF | Diffuse albedo of impervious road | Radiative | Unitless |\n",
    "| ALB_PERROAD_DIR | Direct albedo of pervious road | Radiative | Unitless |\n",
    "| ALB_PERROAD_DIF | Diffuse albedo of pervious road | Radiative | Unitless |\n",
    "| ALB_ROOF_DIR | Direct albedo of roof | Radiative | Unitless |\n",
    "| ALB_ROOF_DIF | Diffuse albedo of roof | Radiative | Unitless |\n",
    "| ALB_WALL_DIR | Direct albedo of wall | Radiative | Unitless |\n",
    "| ALB_WALL_DIF | Diffuse albedo of wall | Radiative | Unitless |\n",
    "| T_BUILDING_MIN | Minimum interior building temperature | Indoor | K |\n",
    "\n",
    "**Variables of forcing data can be directly modified by `usp.modify_ forcing()`**\n",
    "\n",
    "| Variable   | Long name                                      | Unit        |\n",
    "|------------|--------------------------------------------------|-------------|\n",
    "| Zbot       | Measurement height above ground                 | Meters           |\n",
    "| Prectmms   | Precipitation rate                              | kg/m²/s     |\n",
    "| Wind       | Wind speed                                      | m/s         |\n",
    "| LWdown     | Downward longwave radiation at measurement height | W/m²       |\n",
    "| PSurf      | Air pressure at measurement height              | Pa          |\n",
    "| Qair       | Specific humidity at measurement height         | kg/kg       |\n",
    "| Tair       | Air temperature at measurement height           | K           |\n",
    "| SWdown     | Downward shortwave radiation at measurement height | W/m²     |"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Optional input method"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "%%time\n",
    "# check surface\n",
    "usp.check_surf(usr_surf=\"sufdata.nc\") # use the default surface data of London\n",
    "# check the domain\n",
    "usp.check_domain()\n",
    "# check the forcing\n",
    "# this forcing derived from urban-plumber forcing data\n",
    "usp.check_forcing(usr_forcing=\"forcing.nc\")\n",
    "usp_res = usp.run(\n",
    "            case_name = \"usp_spinup\", \n",
    "            RUN_STARTDATE = \"2002-01-01\",\n",
    "            STOP_OPTION = \"nyears\", \n",
    "            STOP_N = \"10\",\n",
    "            #RUN_TYPE= \"coldstart\", # coldstart is the default option\n",
    "        )\n",
    "usp_res"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Optional run way"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "from pyclmuapp import usp_clmu\n",
    "\n",
    "# initialize\n",
    "usp = usp_clmu()\n",
    "\n",
    "# run the docker image\n",
    "usp.docker(\"run\")\n",
    "\n",
    "usp_res = usp.run(\n",
    "            case_name = \"usp_spinup\", \n",
    "            SURF=\"surfdata.nc\",\n",
    "            FORCING=\"forcing.nc\",\n",
    "            RUN_STARTDATE = \"2002-01-01\",\n",
    "            STOP_OPTION = \"nyears\", \n",
    "            STOP_N = \"10\",\n",
    "            #RUN_TYPE= \"coldstart\", # coldstart is the default option\n",
    "            crun_type=\"usp-exec\" # this is to run the container when the docker image is used\n",
    "        )\n",
    "\n",
    "# stop the docker image and remove it\n",
    "usp.docker(\"stop\")\n",
    "usp.docker(\"rm\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "---\n",
    "\n",
    "**additonal information**"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "\n",
    "`usp.check_surf()` will show what is available in the surfdata_dict.\n",
    "\n",
    "to see what care mainly contained in surfdata.\n",
    "\n",
    "```python\n",
    "surf = usp.check_surf()\n",
    "print(surf)\n",
    "```\n",
    "\n",
    "Args:\n",
    "\n",
    "- usr_surfdata (str): The path to the user-defined surface data file. The default is None.\n",
    "\n",
    "- surfata_name (str): The name of the surface data file. The default is \"surfdata.nc\".\n",
    "\n",
    "\n",
    "Please check below output to see:\n",
    "\n",
    "1. what kind of urban parameter will need to run the single point model\n",
    "\n",
    "2. The values list indicates different paramter in different level\n",
    "\n",
    "   - list of albedo indicate the albedo of visable and invisable solar bands (VIS,NIR)\n",
    "  \n",
    "   - list of thermal paramters indicates the layer"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "---\n",
    "\n",
    "`usp.check_domain()`\n",
    "\n",
    "if you have your domain file, use `usp.check_domain(usr_domain=your-filepath)`\n",
    "\n",
    "other parameters:\n",
    "\n",
    "- usr_domain (str): The path to the user-defined domain data file. The default is None,which - means using the default domain data (UK-Kin site).\n",
    "\n",
    "- lat (float): The latitude of the domain. The default is None. Provide it to change to your interest point.\n",
    "\n",
    "- lon (float): The longitude of the domain. The default is None. Provide it to change to your interest point."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "---\n",
    "\n",
    "**check the forcing file**\n",
    "\n",
    "`usp.check_forcing`\n",
    "\n",
    "we need to provdie our own forcing data\n",
    "\n",
    "if the forcing file is not in inputfolder/usp, then it will be copied to the inputfolder/usp\n",
    "\n",
    "Args:\n",
    "\n",
    "- usr_forcing (str): The path to the user-defined forcing data file. The default is None.\n",
    "\n",
    "- action (dict): The dictionary of the revised forcing data for the urban surface parameters. The default is None, which means no action.\n",
    "\n",
    "- mode (str): The mode for the revision. The default is \"add\".\n",
    "\n",
    "- forcing_name (str): The name of the revised forcing data file. The default is \"forcing.nc\".\n",
    "\n",
    "the forcing should be included:\n",
    "\n",
    "1.  Zbot : Measurement height above ground m\n",
    "2.  Prectmms : Precip_rate kg/m2/s\n",
    "3.  Wind : Wind m/s\n",
    "4.  LWdown : Downward longwave radiation at measurement height W/m2\n",
    "5.  PSurf : Air pressure at measurement height Pa\n",
    "6.  Qair : Specific humidity at measurement height, Kg/Kg\n",
    "7.  Tair : Air temperature at measurement height K\n",
    "8.  SWdown : Downward shortwave radiation at measurement height W/m2\n",
    "\n",
    "Note: \n",
    "\n",
    "- Wind=sqrt(Wind_N^2 + Wind_E^2 )\n",
    "\n",
    "- Prectmms=Snow+Rain\n",
    "\n",
    "Make sure the forcing file is same as the protocols of CLM"
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "pymet",
   "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.11.8"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 2
}