cesm.py API update

docs/cesm.rst

@@ -0,0 +1,7 @@
+python API
+===========
+
+.. automodule:: cesm
+   :members:
+   :undoc-members:
+   :show-inheritance:

docs/conf.py

@@ -6,7 +6,12 @@
 # -- Project information -----------------------------------------------------
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
 
-project = 'ctsmpy'
+import os
+import sys
+sys.path.insert(0, os.path.abspath('../src'))#指向src目录
+
+
+project = 'clmu-app'
 copyright = '2024, Junjie Yu'
 author = 'Junjie Yu'
 release = 'v0.0.0'
@@ -26,6 +31,8 @@
 'numpydoc', 
 'sphinx.ext.autosummary',
 'sphinx.ext.mathjax',
+'sphinx.ext.autodoc',
+'sphinx.ext.napoleon'
 ]
 
 #pip install --upgrade jinja2==3.0.3
@@ -53,3 +60,4 @@
 # relative to this directory. They are copied after the builtin static files,
 # so a file named "default.css" will overwrite the builtin "default.css".
 html_static_path = ['_static']
+

docs/container/1_intro_container.md

@@ -12,10 +12,10 @@ See more details in [CLM Technical Note](https://escomp.github.io/ctsm-docs/vers
 ![Alt text](fig/clmu.jpg "CLMU")
 <center>Urban parameterization in CMLU. <a href="https://escomp.github.io/ctsm-docs/versions/master/html/tech_note/Urban/CLM50_Tech_Note_Urban.html">(Fig sources)</a></center>
 
-### Why container for CLMU?
+### Why use a container for CLMU?
 
 Running CMLU within CLM (Community Land Model) requires a Linux operation system with certain [software requirements](https://escomp.github.io/CESM/versions/cesm2.2/html/introduction.html#cesm2-software-operating-system-prerequisites). Without professional support from technicians, it is a challenge for scientists or other potential users to port the CLM running environment by themselves. Here, we use a container to build an ENV fitting the recent version of [CTSM/CLM](https://github.com/ESCOMP/CTSM). Further, we can apply the container on cloud platforms or local computers to conduct some interesting experiments.
 
-### Python for urban climate exploration
+### [Python for urban climate exploration](5_python_API.md)
 We apply some Python codes to help run a case of CLM to explore urban climate. 
 

docs/container/2_install_docker.md

@@ -1,117 +1,116 @@
-### Install Docker and pull container
+### Install Docker and pull the container
 #### Check system info
-We need to get familiar with our computer system before the next steps.
+First of all, get familiar with our computer system before the next steps. Noted that the commands below run in Linux.  
 ```
 lsb_release -a
 
-#LSB Version:    :core-4.1-amd64:core-4.1-noarch
+#LSB Version:    core-4.1-amd64:core-4.1-noarch
 #Distributor ID: CentOS
 #Description:    CentOS Linux release 7.9.2009 (Core)
 #Release:        7.9.2009
 #Codename:       Core
 ```
 #### Install docker
 
-For CentOS, using yum to install packages.
+Use **yum** to install packages in CentOS.
 
 ```
-# 1 Make your packages upadted, if needed.
+# 1 Make your packages updated, if needed.
 sudo yum makecache fast 
 
-# 2 install docker dependences
+# 2 Install docker dependences
 sudo yum install -y yum-utils device-mapper-persistent-data lvm2
 
-# 3 add docker repo
+# 3 Add docker repo
 sudo yum-config-manager --add-repo https://download.docker.com/linux/centos/docker-ce.repo
 
-# 4 install docker
+# 4 Install docker
 sudo yum install -y docker-ce docker-ce-cli containerd.io
 
-# 5 start docker
+# 5 Start docker
 sudo systemctl start docker
 
-# 6 set Docker to boot automatically
+# 6 Set Docker to boot automatically
 sudo systemctl enable docker
 # Created symlink from /etc/systemd/system/multi-user.target.wants/docker.service to /usr/lib/systemd/system/docker.service.
 
-# 7 check docker
+# 7 Check docker
 sudo docker --version
 # Docker version 24.0.6, build ed223bc
 
-# 8 for more docker info
+# 8 Check more docker info
 docker info
 
 # 9 We can reset the Docker Root Dir (/var/lib/docker, for default)
 
-    sudo systemctl stop docker # stop docker
+sudo systemctl stop docker # stop docker
 
-    sudo mkdir -p your_loc/docker/storage # create docker dir
+sudo mkdir -p your_loc/docker/storage # create docker dir
 
-    cat /etc/docker/daemon.json # check the docker configuration
+cat /etc/docker/daemon.json # check the docker configuration
 
-    # if not exsit /etc/docker/daemon.json
-    # create a json file using vi/vim or nona
-    #{
-    #    "data-root": "/datadisk/docker/storage"
-    #}
+# if not exsit /etc/docker/daemon.json
+# create a json file using vi/vim or nona
+#{
+#    "data-root": "/datadisk/docker/storage"
+#}
 
-    sudo systemctl start docker # reopen docker
-    docker info # check docker configuration
+sudo systemctl start docker # reopen docker
+docker info # check docker configuration
 ```
-#### Pull the ctsm env image
+#### Pull the clm env image
 https://hub.docker.com/, the official sources of docker images.
 
 
 ```
-docker pull clmu-container # pull the image
+docker pull installed in clmu-app # pull the image
 ```
 
-#### Biuld container
+#### Build container (installed in clmu-app)
 
 ```
-# case and inputdata dir
-mkdir -vp p/project p/scratch/CESMDATAROOT/inputdata/ForcingData p/pyscripts
-
-# do not change the hostname
-docker run --hostname clm5-docker --name clm5.0 -it --mount type=bind,source="$(pwd)"/p,target=/p clm5docker:1
+# Do not change the hostname
+docker run --hostname clmu-app --name ContainerName -it clmu-app:1
 ```
 
-#### Install CTSM or CLM5.0
+#### Install CLM5.0 (installed in clmu-app)
 ```
-# in container
+# In the container directory
 cd /p/project
 git clone -b release-clm5.0 https://github.com/ESCOMP/CTSM.git clm5.0
 cd clm5.0
 ./manage_externals/checkout_externals
+
+# Check if all components needed are downloaded
+./manage_externals/checkout_externals -S
 ```
 
-If you need to change the config of CTSM, please refer to [key notes for seting config_manchine.xml](https://bb.cgd.ucar.edu/cesm/threads/issue-installing-on-centos-8-with-slurm-and-lmod.5884/#post-39110)
+If you want to modify model configuration, please refer to [key notes for setting config_manchine.xml](https://bb.cgd.ucar.edu/cesm/threads/issue-installing-on-centos-8-with-slurm-and-lmod.5884/#post-39110).
 
 #### Singularity
 
-Singularity is a container software ususally empoly in HPC. It provides a mechanism to run containers where containers can be used to package entire scientific workflows, software and libraries, and even data.
+Singularity is a container software usually employed in HPC. It provides a mechanism to run containers where containers can be used to package entire scientific workflows, software and libraries, and even data.
 Ref: https://ri.itservices.manchester.ac.uk/csf3/software/applications/singularity/
 
-Using Singularity from docker image
+Using Singularity from the docker image
 
 ```
-# save image as tar file
+# Save image as tar file
 docker save -o ~/docker/clm5docker.tar clm5docker:1
-# transport tar file
+# Transport tar file
 scp ~/docker/clm5docker.tar ...
-# biuld image form tar
+# Biuld image form tar
 singularity build clm5docker.sif docker-archive://clm5docker.tar
 scp /Users/user/Documents/GitHub/DRL_urban_climate_adaptation/2_CTSM_container/dockerfile/cime_config/config_machines.xml [email protected]:~/.cime
 scp /Users/user/Documents/GitHub/DRL_urban_climate_adaptation/2_CTSM_container/dockerfile/cime_config/config_compilers.xml [email protected]:~/.cime
 mkdir -vp p/project p/scratch/CESMDATAROOT/inputdata
 
-singularity run --hostname clm5-docker -B "$(pwd)"/p:/p clm5docker.sif # do not change hostname, either need to change cime.config file 
-
-singularity run --net --network=none --hostname clm5-docker -B "$(pwd)"/p:/p clm5docker.sif
+singularity run --hostname clmu-app -B "$(pwd)"/p:/p clm5docker.sif 
+# Do not change hostname, either need to change cime.config file 
 
-# then in singularity, as singularity are not same as 
-# CLM5 environment variables
+singularity run --net --network=none --hostname clmu-app -B "$(pwd)"/p:/p clm5docker.sif
 
+# Export CLM5 environment variables
 export PROJECT=/p/project
 export SCRATCH=/p/scratch
 export BUDGET_ACCOUNTS=slts
@@ -123,10 +122,10 @@ export OMPI_ALLOW_RUN_AS_ROOT=1
 ```
 
 #### Tips for docker commander
-- docker ps：check for the running container
-- docker stop <container-id>：stop the container
-- docker start <container-id>：start the container
-- docker restart <container-id>：restart the container
-- docker rm <container-id>：remove a container
-- docker logs <container-id>：check the logs
-- docker exec -it <container-id> /bin/bash：get into a running docker container with Bash shell.
+- docker ps: check for the running container
+- docker stop <container-id>: stop the container
+- docker start <container-id>: start the container
+- docker restart <container-id>: restart the container
+- docker rm <container-id>: remove a container
+- docker logs <container-id>: check the logs
+- docker exec -it <container-id> /bin/bash: get into a running docker container with Bash shell

docs/container/3_CLMU_env_details.md

@@ -1,10 +1,16 @@
 ### CLM ENV Container detail
 
-OS=`Fedora 31`
+Base:
+
+- OS=`Fedora 31`
 
 Major apps: 
-Compiler= `GCC 9.3.1`
-Mpi=`OpenMPI 4.0.2-1`, Cmake=`3.18`, pnetcdf=`1.12.3`, netcdf-c=`4.7.0-2`, netcdf-fortran=`4.5.2-3`, python=`3.7.9`, svn=`1.12` 
+- Compiler= `GCC 9.3.1`
+- Cmake=`3.18`
+- netcdf-c=`4.7.0-2`
+- netcdf-fortran=`4.5.2-3`
+- python=`3.7.9`
+- svn=`1.12` 
 
 ![Alt text](fig/ENV.png "CLMU")
 <center>CMLU container environment.</a></center>

docs/container/4_run_CLM_case.md

@@ -7,12 +7,11 @@ sudo docker start myclm
 
 docker exec -it myclm /bin/bash
 # Now we are in the Fedora 31 Bash.
-
 ```
 
-## Try to run a single piont case
+## Try to run a single-point case
 
-[How run a single point case?](https://escomp.github.io/ctsm-docs/versions/master/html/users_guide/running-single-points/index.html)
+[How to run a single-point case?](https://escomp.github.io/ctsm-docs/versions/master/html/users_guide/running-single-points/index.html)
 
 ```
 > cd scripts
@@ -31,14 +30,14 @@ docker exec -it myclm /bin/bash
 
 # Set the User namelist to set the output frequencies of the history files
 # Setting the stdurbpt use-case option create three history file streams
-# The frequencies and number of time-samples needs to be set
+# Set frequencies and numbers of time-samples for outputs
 > cat << EOF > user_nl_clm
 hist_mfilt = $NDAYS,$STOP_N,$STOP_N
 hist_nhtfrq = -1,1,1
 EOF
 
 > ./case.setup
-> ./case.biuld
+> ./case.build
 > ./case.submit
 ```
 
@@ -52,6 +51,6 @@ resubmit_num 0
 Submit job case.st_archive
 ERROR: No result from jobs [('case.run', None), ('case.st_archive', 'case.run or case.test')]
 ```
-**Congratuation**, you mostly successfully run your case.
+**Congratulations**, you mostly successfully run your case.
 
-If not, try to ask for help. [CESM FORUM](https://bb.cgd.ucar.edu/cesm/)
+If not, try to ask for help in [CESM FORUM](https://bb.cgd.ucar.edu/cesm/)

docs/container/5_python_API.md

@@ -0,0 +1,4 @@
+# Wrokflow of cesm.py: Python API for driving clmu-app single point modeling
+
+![Alt text](fig/cesmpy.jpg "cesmpy")
+<center>cesm Python API.</center>

docs/examples/Single_point_modeling.ipynb

@@ -110,7 +110,7 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "## Modify the data"
+    "## 2 Modify the data"
    ]
   },
   {

docs/examples/modify_urban.ipynb

@@ -89,7 +89,7 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "## Modify the surface data"
+    "## 2 Modify the surface data"
    ]
   },
   {

docs/index.rst

@@ -23,7 +23,7 @@ CLMU APP
 
 Using Python to drive CLMU simulations via container.
 
-Author: `Junjie Yu <https://junjieyu-uom.github.io>`_, `Dr. Zhonghua Zheng <https://zhonghuazheng.com>`_, `Yuan Sun <https://github.com/YuanSun-UoM>`_
+Author: `Junjie Yu <https://junjieyu-uom.github.io>`_, `Dr. Zhonghua Zheng <https://zhonghuazheng.com>`_, `Yuan Sun <https://github.com/YuanSun-UoM>`_, `Dr. Keith Oleson <https://staff.ucar.edu/users/oleson>`_
 
 .. toctree::
    :maxdepth: 2
@@ -33,6 +33,7 @@ Author: `Junjie Yu <https://junjieyu-uom.github.io>`_, `Dr. Zhonghua Zheng <http
    container/2_install_docker.md
    container/3_CLMU_env_details.md
    container/4_run_CLM_case.md
+   container/5_python_API.md
 
 .. toctree::
    :maxdepth: 2
@@ -41,6 +42,12 @@ Author: `Junjie Yu <https://junjieyu-uom.github.io>`_, `Dr. Zhonghua Zheng <http
    examples/Single_point_modeling.ipynb
    examples/modify_urban.ipynb
 
+.. toctree::
+   :maxdepth: 2
+   :caption: API Reference
+
+   cesm.rst
+
 Indices and tables
 ==================
 

docs/modules.rst

@@ -0,0 +1,7 @@
+scr
+===
+
+.. toctree::
+   :maxdepth: 4
+
+   cesm

requirements.txt

@@ -3,4 +3,6 @@ ipython
 nbsphinx
 sphinx_rtd_theme
 recommonmark 
-sphinx-markdown-tables
+sphinx-markdown-tables
+xarray
+numpy