Added pyschism manual

docs/getting-started/pre-processing-with-pyschism/atmos.md

@@ -0,0 +1,75 @@
+#**Atmospheric forcing**
+The sflux/ directory is required if nws=2 in *param.nml*. 
+
+There are four types of files needed:
+
+sflux_input.txt (<font color="red">required</font>): a namelist file
+
+sflux_air_1.[XXXX].nc (<font color="red">required</font>): NetCDF files that have time (in days), wind speed at 10m above MSL (u, v), air temperatue and spedific humidity at 2m above MSL, sea level pressure;
+
+sflux_prc_1.[XXXX].nc (<font color="blue">needed</font> if isconsv=1): NetCDF files that have time and precipitation rate;
+
+sflux_rad_1.[XXXX].nc (<font color="blue">needed</font> if ihconsv=1): NetCDF files that have time, downward longwave and shortwave radiation fluxes.
+
+PySCHISM supports three types of atmpsheric datasets.
+##**ECMWF ERA5**
+ERA5 provides hourly estimates of a large number of atmoshperic, land and oceanic climate variables. The data cover the Earth on a 30km grid and resolve the atmoshpere using 137 levels from the surface up to a height of 80km. The dataset covers from 1950 to present. PySCHISM downloads ERA5 data through CDS API service. To do so, you need to install CDS API package. [Here](https://cds.climate.copernicus.eu/api-how-to) is the instruction about how to install the package.
+
+The python script to generate sflux file from ERA5 is as follows:
+```python
+from datetime import datetime
+import pathlib
+
+from pyschism.mesh.hgrid import Hgrid
+from pyschism.forcing.nws.nws2.era5 import ERA5
+
+if __name__ == '__main__'
+    startdate=datetime(2022, 4, 1)
+    rnday = 10
+    hgrid=Hgrid.open('./hgrid.gr3',crs='EPSG:4326')
+    bbox = hgrid.get_bbox('EPSG:4326', output_type='bbox')
+    outdir = pathlib.Path('./')
+
+    er=ERA5()
+    er.write(outdir=outdir, start_date=startdate, rnday=rnday, air=True, rad=True, prc=True, bbox=bbox, output_interval=interval, overwrite=True)
+```
+##**GFS**
+The Global Forecast System (GFS) is weather forecast model produced by the National Centers for Environmental Prediction (NCEP). PySCHISM uses data hosted on AWS S3 bucket.
+
+The python script to generate sflux from GFS is as follows:
+```python
+from datetime import datetime
+
+from pyschism.mesh.hgrid import Hgrid
+from pyschism.forcing.nws.nws2.gfs2 import GFS
+
+if __name__ == '__main__':
+    startdate = datetime(2022, 3, 31)
+    rnday = 10
+    record = 1
+    hgrid = Hgrid.open('./hgrid.gr3', crs='epsg:4326')
+    pscr = '/sciclone/pscr/lcui01/GFS/'
+    gfs = GFS(start_date=startdate, rnday=rnday, pscr=pscr, record=record, bbox=hgrid.bbox)
+```
+Parameter *startdate* should be one day earlier than the actual startdate in the *param.nml* becasue GFS have nodata at t00, *pscr* is the pre-generated directory to save dowloaded raw data (grib2), *record* is to specify how many days in each file. For hindcast, recommend *record=1*. For forecast, the maximum is 5, because GFS has 5-day forecast.
+
+##**HRRR**
+The HRRR is a NOAA real-time 3-km resolution, hourly updated, cloud-resolving, convection-allowing atmospheric model. The AWS archived data starts from August 2014 to present.
+
+The python script to generate sflux from HRRR is as follows:
+```python
+from datetime import datetime
+
+from pyschism.mesh.hgrid import Hgrid
+from pyschism.forcing.nws.nws2.hrrr3 import HRRR
+
+if __name__ == '__main__':
+    startdate = datetime(2022, 3, 31)
+    rnday = 10
+    record = 1
+    hgrid = Hgrid.open('../../../data/hgrid.gr3', crs='epsg:4326')
+    pscr='/sciclone/pscr/lcui01/HRRR/'
+
+    hrrr = HRRR(start_date=startdate, rnday=rnday, pscr=pscr, record=record, bbox=hgrid.bbox)
+```
+Parameter *startdate*, *pscr*, and *record* are defined the same as GFS', except for forecast, the maximum of record for HRRR is 2, because HRRR only has 2-day forecast.

docs/getting-started/pre-processing-with-pyschism/boundary.md

@@ -0,0 +1,63 @@
+#**Boundary Condition**
+Please refer to [this page](https://schism-dev.github.io/schism/master/input-output/bctides.html) for detailed horizontal B.C. and nudging options supported by SCHISM.
+
+##**TPXO**
+PySCHISM uses TPXO Global Tidal Model database. You may need to register an account on the website to download the data.
+
+Generating *bctides.in*:   
+```python
+from datetime import datetime
+from pyschism.mesh import Hgrid
+from pyschism.forcing.bctides import Bctides, iettype, ifltype, isatype, itetype
+
+if __name__ == '__main__':
+    startdate = datetime(2022, 4, 1)
+    rnday = 10
+    hgrid = Hgrid.open("./hgrid.gr3", crs="epsg:4326")
+    iet3 = iettype.Iettype3(constituents='major', database='tpxo')
+    iet4 = iettype.Iettype4()
+    iet5 = iettype.Iettype5(iettype3=iet3, iettype4=iet4)
+    ifl3 = ifltype.Ifltype3(constituents='major', database='tpxo')
+    ifl4 = ifltype.Ifltype4()
+    ifl5 = ifltype.Ifltype5(ifltype3=ifl3, ifltype4=ifl4)
+    isa3 = isatype.Isatype4()
+    ite3 = itetype.Itetype4()
+    bctides = Bctides(hgrid, iettype=iet5, ifltype=ifl5, isatype=isa3, itetype=ite3)
+    bctides.write('./', startdate, rnday, bctides=True, elev2D=False, uv3D=False, tem3D=False, sal3D=False, overwrite=True)
+```
+
+##**HYCOM**
+Generating *elev.2D.th.nc*, *SAL_3D.th.nc*, *TEM_3D.th.nc*, and *uv3D.th.nc*:
+```python
+from datetime import datetime
+
+from pyschism.mesh.hgrid import Hgrid
+from pyschism.forcing.hycom.hycom2schism import OpenBoundaryInventory
+
+if __name__ == '__main__':
+    start_date = datetime(2022, 4, 1)
+    rnday = 10
+    hgrid = Hgrid.open('./hgrid.gr3', crs='epsg:4326')
+    vgrid = './vgrid.in'
+    outdir = './'
+    bnd = OpenBoundaryInventory(hgrid, vgrid)
+    bnd.fetch_data(outdir, start_date, rnday, elev2D=True, TS=True, UV=True)
+```
+Generating *SAL_nu.nc* and *TEM_nu.nc* for nudging:
+```python
+from datetime import datetime
+
+from pyschism.mesh import Hgrid
+from pyschism.forcing.hycom.hycom2schism import Nudge
+
+if __name__ == '__main__':
+    start_date = datetime(2022, 4, 1)
+    rnday = 10
+    hgrid = Hgrid.open('./hgrid.gr3', crs='epsg:4326')
+    vgrid = './vgrid.in'
+    outdir = './'
+
+    nudge=Nudge()
+    nudge.fetch_data(outdir, hgrid, vgrid, start_date, rnday)
+```
+This script also generates nudging coefficient files *SAL_nu.gr3* and *TEM_nu.gr3*.

docs/getting-started/pre-processing-with-pyschism/installation.md

@@ -0,0 +1,23 @@
+#Installation
+Setting up a conda environment is recommended to install PySCHISM. Please refer [here](https://docs.conda.io/en/latest/miniconda.html#linux-installers) for how to install Miniconda.
+
+Create conda environment:   
+```code
+conda create -n pyschism python=3.9
+```
+##From GitHub repo
+```code
+conda activate pyschism
+git clone https://github.com/schism-dev/pyschism.git
+cd pyschism
+pip install .     # install as a user
+# OR
+pip install -e .  #install as a developer
+```
+##Python package from PyPI
+Get the package with:   
+```code
+pip3 install pyschism
+```
+
+

docs/getting-started/pre-processing-with-pyschism/nwm.md

@@ -0,0 +1,35 @@
+#**National Water Model**
+NOAA NWM CONUS Retrospective Dataset is to provide streamflow when if_source=1 is defined in *param.nml*. This dataset covers from February 1979 to present, combination of different versions of NWM dataset. These four files are needed:   
+source_sink.in    
+vsource.th   
+vsink.th    
+msource.th
+
+The python script to generate these files is as follows:
+```python
+from datetime import datetime
+
+from pyschism.mesh import Hgrid
+from pyschism.forcing.source_sink.nwm import NationalWaterModel, NWMElementPairings
+
+if __name__ == '__main__':
+    startdate = datetime(2022, 4, 4)
+    rnday = 10
+    hgrid = Hgrid.open("./hgrid.gr3", crs="epsg:4326")
+    sources_pairings = pathlib.Path('./sources.json')
+    sinks_pairings = pathlib.Path('./sinks.json')
+    output_directory = pathlib.Path('./')
+
+    cache = pathlib.Path(f'./{startdate.strftime("%Y%m%d")}')
+    cache.mkdir(exist_ok=True, parents=True)
+
+    if all([sources_pairings.is_file(), sinks_pairings.is_file()]) is False:
+        pairings = NWMElementPairings(hgrid)
+        sources_pairings.parent.mkdir(exist_ok=True, parents=True)
+        pairings.save_json(sources=sources_pairings, sinks=sinks_pairings)
+    else:
+        pairings = NWMElementPairings.load_json(hgrid, sources_pairings, sinks_pairings)
+
+    nwm=NationalWaterModel(pairings=pairings, cache=cache)
+    nwm.write(output_directory, hgrid, startdate, rnday, overwrite=True)
+```

docs/getting-started/pre-processing-with-pyschism/overview.md

@@ -0,0 +1,2 @@
+PySCHISM is a python based package for preparing most inputs required of 3D baroclinic SCHISM run, driven by [TPXO](https://richdem.readthedocs.io/en/latest/using_it.html), [HYCOM](https://www.hycom.org/), [NWM](https://water.noaa.gov/about/nwm), and
+ a few pre-selected atmospheric models ([ERA5](https://www.ecmwf.int/en/forecasts/datasets/reanalysis-datasets/era5), [GFS](https://registry.opendata.aws/noaa-gfs-bdp-pds/), and [HRRR](https://registry.opendata.aws/noaa-hrrr-pds/)). PySCHISM has its own [repository](https://github.com/schism-dev/pyschism). The syntax of classes and methods in the library are subject to change in future releases, which will also significantly optimize performace and speed of some functionalities.

docs/getting-started/pre-processing.md

@@ -24,7 +24,7 @@ for other gridded data sources from other structured-grid models).
  like HYCOM. It essentially consists of 3D interpolations.
 
 ## Sflux_nc
-The matlab scripts inside Sflux_nc dir show you the structure of sflux*.nc as well as how to generate your own files.
+The matlab scripts inside Sflux_nc dir show you the structure of sflux\*.nc as well as how to generate your own files.
 
 ## METIS for offline domain decomposition
 You'll only need to do this if you invoked offline partitioning in compilation (e.g. with `NO_PARMETIS` turned ON in cmake)
@@ -46,8 +46,3 @@ Step 3: run METIS: `./gpmetis graphinfo <nproc> -ufactor=1.01 -seed=15`
 
 
    (replace `<nproc>` with actual # of cores).
-
-## Pre-processing with PySCHISM
-PySCHISM is a python based package for preparing most inputs required of 3D baroclinic SCHISM run, driven by HYCOM and
- a few pre-selected atmospheric models. PySCHISM has its own repository (in parallel to SCHISM) and you can
- find a user manual [here](https://pyschism.readthedocs.io/en/latest/index.html).

mkdocs.yml

@@ -57,6 +57,12 @@ nav:
     - Typical workflow (a cheat sheet): getting-started/typical-workflow.md
     - Grid generation: getting-started/grid-generation.md
     - Preprocessing: getting-started/pre-processing.md
+    - Preprocessing with PySCHISM:
+      - Overview: getting-started/pre-processing-with-pyschism/overview.md
+      - Installation: getting-started/pre-processing-with-pyschism/installation.md
+      - Boundary Conditions: getting-started/pre-processing-with-pyschism/boundary.md
+      - Atmospheric forcing: getting-started/pre-processing-with-pyschism/atmos.md
+      - Souce and Sink: getting-started/pre-processing-with-pyschism/nwm.md
     - Running the model: getting-started/running-model.md
     - Visualization: getting-started/visualization.md
     - Postprocessing: getting-started/post-processing.md