rc-qlc 0.3.24__cp310-cp310-win_amd64.whl

qlc/doc/USAGE.md

@@ -0,0 +1,58 @@
+# QLC Usage Guide
+
+## Installed CLI Tools
+
+Once installed, QLC provides the following command-line entry points:
+
+### `qlc`
+Runs the full shell-based QLC pipeline (retrieval, processing, plotting).
+
+### `qlc-py`
+Runs the standalone Python-based observation–model comparison.
+
+### `sqlc`
+Submits a QLC run as a batch job (e.g., SLURM, LSF).
+
+---
+
+## PyPI Installation
+
+To install `rc-qlc` from PyPI and set up the local environment, use the following two-step command.
+
+### CAMS Mode
+For users connected to the CAMS data infrastructure.
+```bash
+pip install rc-qlc && qlc-install --cams
+```
+
+### Test Mode
+For a standalone test using the bundled example data.
+```bash
+pip install rc-qlc && qlc-install --test
+```
+
+---
+
+## Local Wheel Installation
+
+If you have a wheel file (`.whl`), you can install it directly.
+
+```bash
+# Example for a local wheel file
+pip install ./path/to/your/rc-qlc-0.3.21-....whl
+qlc-install --test
+```
+
+---
+
+## Running QLC in Test Mode
+
+After installing in test mode, you can immediately run the main drivers:
+```bash
+# Run the full shell pipeline with example data
+qlc
+
+# Run only the Python processing part
+qlc-py
+```
+

qlc/examples/cams_case_1/config/json/qlc_config.json

@@ -0,0 +1,41 @@
+[
+  {
+    "name": "CAMS2_35",
+    "logdir": "./log",
+    "workdir": "./run",
+    "output_base_name": "$HOME/qlc/output/GMD",
+    "station_file": "$HOME/qlc/obs/data/ebas_station-locations.csv",
+    "obs_path": "$HOME/qlc/obs/data/ver0d",
+    "obs_dataset_type": "ebas_daily",
+    "start_date": "2018-01-01",
+    "end_date": "2018-12-31",
+    "variable": "SO2,SO4,HNO3,NO3,NH3,NH4",
+    "station_radius_deg": 10.0,
+    "plot_type": "",
+    "plot_region": "EU",
+    "time_average": "daily, weekly, monthly",
+    "station_plot_group_size": 5,
+    "show_stations": false,
+    "show_min_max": true,
+    "log_y_axis": false,
+    "fix_y_axis": true,
+    "show_station_map": true,
+    "load_station_timeseries_obs": true,
+    "show_station_timeseries_obs": true,
+    "show_station_timeseries_mod": false,
+    "show_station_timeseries_com": false,
+    "save_plot_format": "pdf",
+    "save_data_format": "nc",
+    "multiprocessing": true,
+    "n_threads": "20",
+    "debug": false,
+
+    "global_attributes": {
+      "title": "Air pollutants over Europe, SO2,SO4,HNO3,NO3,NH3,NH4",
+      "summary": "Custom summary for netCDF output: Ebas daily observations for selected EU stations.",
+      "author": "Plain & Simple, plain.simple@example.com",
+      "history": "Processed for CAMS (test 1.1)",
+      "Conventions": "CF-1.8"
+    }
+  }
+]

qlc/examples/cams_case_1/config/nml/mars_A3_sfc.nml

@@ -0,0 +1,19 @@
+# adopt to your needs, except for EXP, SDATE, EDATE, MYPATH, MYFILE, which will be auto-replaced
+# add your param_, ncvar_ and myvar_ to your $HOME/qlc/config/qlc.conf file
+# param_A3-sfc=("203.210")
+# ncvar_A3-sfc=("go3")
+# myvar_A3-sfc=("O3")
+# surface level
+RETRIEVE,
+CLASS      = XCLASS,
+TYPE       = fc, 
+STREAM     = oper,
+EXPVER     = EXP,
+PARAM      = 203.210,
+LEVTYPE    = sfc,
+GRID       = 1.0/1.0,
+TIME       = 00:00:00,
+STEP       = 0/6/12/18,
+LEVELIST   = 137,
+DATE       = SDATE/to/EDATE,
+target     = "MYPATH/MYFILE_A3_sfc.grb"

qlc/examples/cams_case_1/config/nml/mars_B1_pl.nml

@@ -0,0 +1,19 @@
+# adopt to your needs, except for EXP, SDATE, EDATE, MYPATH, MYFILE, which will be auto-replaced
+# add your param_, ncvar_ and myvar_ to your $HOME/qlc/qlc.conf file
+# param_B=("19.217"  "6.217"   "122.210" "203.210")
+# ncvar_B=("var19"   "var6"    "var122"  "var203")
+# myvar_B=("NH3"     "HNO3"    "SO2"     "O3")
+# pressure levels
+RETRIEVE,
+CLASS      = XCLASS,
+TYPE       = fc, 
+STREAM     = oper,
+EXPVER     = EXP,
+PARAM      = 19.217,
+LEVTYPE    = pl,
+GRID       = 1.0/1.0,
+TIME       = 00:00:00,
+STEP       = 0/6/12/18,
+LEVELIST   = 10/20/30/50/70/100/150/200/250/300/400/500/700/850/925/1000,
+DATE       = SDATE/to/EDATE,
+target     = "MYPATH/MYFILE_B1_pl.grb"

qlc/examples/cams_case_1/config/nml/mars_C1_pl.nml

@@ -0,0 +1,19 @@
+# adopt to your needs, except for EXP, SDATE, EDATE, MYPATH, MYFILE, which will be auto-replaced
+# add your param_, ncvar_ and myvar_ to your $HOME/qlc/qlc.conf file
+# param_C2=("36.212" "35.212" "2.212" "1.212")
+# ncvar_C2=("var36"  "var35"  "var2"  "var1" )
+# myvar_C2=("NO3_as" "NH4_as" "SO4_as" "N_as")
+# model levels
+RETRIEVE,
+CLASS      = XCLASS,
+TYPE       = fc, 
+STREAM     = oper,
+EXPVER     = EXP,
+PARAM      = 35.212,
+LEVTYPE    = pl,
+GRID       = 1.0/1.0,
+TIME       = 00:00:00,
+STEP       = 0/6/12/18,
+LEVELIST   = 10/20/30/50/70/100/150/200/250/300/400/500/700/850/925/1000,
+DATE       = SDATE/to/EDATE,
+target     = "MYPATH/MYFILE_C1_pl.grb"

qlc/examples/cams_case_1/config/qlc_cams.conf

@@ -0,0 +1,122 @@
+#----------------------------------------------------------------------
+#----------------------- QLC version to be used -------------------
+QLC_VERSION="v03"
+#----------------------- Path definitions -------------------------
+SCRIPTS_PATH="$HOME/../cysm/bin_public/qlc_src_$QLC_VERSION" 
+QLC_HOME="$HOME/qlc"
+QLC_DIRECTORY="${QLC_HOME}_$QLC_VERSION"
+WORKING_DIRECTORY="$SCRATCH/qlc"
+MARS_RETRIEVAL_DIRECTORY="$SCRATCH/qlc/Results"
+ANALYSIS_DIRECTORY="$HPCPERM/qlc/Analysis"
+PLOTS_DIRECTORY="$PERM/qlc/Plots"
+TEX_DIRECTORY="$PERM/qlc/Presentations"
+#----------------------- PDF presentation and info  -------------
+TEAM_PREFIX="CAMS2_35"
+EVALUATION_PREFIX="EVAL"
+MODEL_RESOLUTION="T255L137"
+TIME_RESOLUTION="03hh"
+#PLOTEXTENSION="pdf"
+PLOTEXTENSION="png"
+#----------------------- Run-time definitions -------------------------
+#- 1. Definition of QLC complexity through selection of subscripts
+#----------------------------------------------------------------------
+#- (a) QLC unified data analysis and plotting (entries optional) 
+#----------------------------------------------------------------------
+#SUBSCRIPT_NAMES=("A1" "B1" "B2" "C1" "D1" "E1" "F1" "G1" "Z1")
+#SUBSCRIPT_NAMES=("C5" "Z1")
+SUBSCRIPT_NAMES=("A1" "B1a" "B2" "C5" "Z1")
+#----------------------------------------------------------------------
+#- (b) QLC unified mars data retrieval (SUBSCRIPT_NAME, A1, A2, A3, ...) 
+#- Mars retrievals for namelist : nml/mars_A2.nml, nml/mars_B2.nml, ...)
+#----------------------------------------------------------------------
+#- MARS_RETRIEVALS=("A2_sfc" "B2_pl" "C2_pl" "C3_ml" "D"  "E"  "F" "I")
+#- O3, NH3 and NH4_as
+MARS_RETRIEVALS=("A3_sfc" "B1_pl" "C1_pl")
+#----------------------------------------------------------------------
+#- un/comment MARS_RETRIEVALS (choose one or combine contents into one)
+#- The MARS_RETRIEVALS mapping is required for subscript processing (a)
+#----------------------------------------------------------------------
+#- Key variables (AOD, PM + gases and aerosols)
+# MARS_RETRIEVALS=("A2_sfc" "B2_pl" "C2_pl")
+#- pH variables (rain, cloud, aerosol pH and water)
+# MARS_RETRIEVALS=("D" "F" "G")
+#- Extended aerosol diagnostics (requires E4C and active 4D output)
+# MARS_RETRIEVALS=("E")
+#- PSC frequency (requires E4C output)
+# MARS_RETRIEVALS=("H")
+#- Meteo output (e.g., T, SH, RH)
+# MARS_RETRIEVALS=("I")
+#----------------------------------------------------------------------
+#----------------------------------------------------------------------
+#- 2. Variable mapping and definition (to be processed by subscripts) 
+#- (number of array elements need to match mars retrieval, if active)
+#----------------------------------------------------------------------
+#- e.g., surface variables (sfc)
+#----------------------------------------------------------------------
+param_A1_sfc=("73.210")
+ncvar_A1_sfc=("var73")
+myvar_A1_sfc=("PM25")
+#----------------------------------------------------------------------
+param_A2_sfc=("207.210" "72.210"  "73.210"  "74.210")
+ncvar_A2_sfc=("var207"  "var72"   "var73"   "var74")
+myvar_A2_sfc=("AOD"     "PM1"     "PM25"   "PM10")
+#----------------------------------------------------------------------
+param_A3_sfc=("203.210")
+ncvar_A3_sfc=("go3")
+myvar_A3_sfc=("O3")
+#----------------------------------------------------------------------
+#- e.g., gases (pressure levels, pl)
+#----------------------------------------------------------------------
+param_B1_pl=("19.217")
+ncvar_B1_pl=("var19")
+myvar_B1_pl=("NH3")
+#----------------------------------------------------------------------
+param_B2_pl=("19.217"  "6.217"   "122.210" "203.210")
+ncvar_B2_pl=("var19"   "var6"    "var122"  "var203")
+myvar_B2_pl=("NH3"     "HNO3"    "SO2"     "O3")
+#----------------------------------------------------------------------
+#- e.g., aerosols (pressure levels, pl)
+#----------------------------------------------------------------------
+param_C1_pl=("35.212")
+ncvar_C1_pl=("var35")
+myvar_C1_pl=("NH4_as")
+#----------------------------------------------------------------------
+param_C2_pl=("36.212" "35.212" "2.212" "1.212")
+ncvar_C2_pl=("var36"  "var35"  "var2"  "var1" )
+myvar_C2_pl=("NO3_as" "NH4_as" "SO4_as" "N_as")
+#----------------------------------------------------------------------
+param_C3_ml=("247.210" "248.210" "249.210" "11.210")
+ncvar_C3_ml=("var247"  "var248"  "var249"  "var11" )
+myvar_C3_ml=("NO3a"    "NO3b"    "NH4"     "SO4")
+#----------------------------------------------------------------------
+#- e.g., aerosol diagnostics
+#----------------------------------------------------------------------
+param_D=("51.212"  "52.212")
+ncvar_D=("var51"   "var52")
+myvar_D=("pHcloud" "pHrain")
+#----------------------------------------------------------------------
+param_E=("210025")
+ncvar_E=("aergn10")
+myvar_E=("EQdiag")
+#----------------------------------------------------------------------
+param_F=("22.210")
+ncvar_F=("aergn07")
+myvar_F=("pHaer")
+#----------------------------------------------------------------------
+param_G=("22.210")
+ncvar_G=("aergn07")
+myvar_G=("AW")
+#----------------------------------------------------------------------
+#- e.g., stratospheric diagnostics
+#----------------------------------------------------------------------
+param_H=("25.210")
+ncvar_H=("aergn10")
+myvar_H=("PSCfreq")
+#----------------------------------------------------------------------
+#- e.g., meteo fields
+#----------------------------------------------------------------------
+param_I=("130"     "133"      "157")
+ncvar_I=("var130"  "var133"   "var157")
+myvar_I=("T"       "SH"       "RH")
+#----------------------------------------------------------------------
+#----------------------------------------------------------------------

qlc/examples/cams_case_1/obs/ebas_station-locations.csv

@@ -0,0 +1,50 @@
+# Site ID, Site Name, Latitude, Longitude, Altitude (m)
+eu052801075n00,Site01,52.8,10.75,
+eu04791791n00,Site02,47.91,7.91,
+eu053161303n00,Site03,53.16,13.03,
+eu05635960n00,Site04,56.35,9.6,
+eu056711151n00,Site05,56.71,11.51,
+eu055691208n00,Site06,55.69,12.08,
+eu059772137n00,Site07,59.77,21.37,
+eu060532766n00,Site08,60.53,27.66,
+eu068002423n00,Site09,68.0,24.23,
+eu05444787n00,Site10,54.44,-7.87,
+eu05579324n00,Site11,55.79,-3.24,
+eu05114143n00,Site12,51.14,-1.43,
+eu046961958n00,Site13,46.96,19.58,
+eu046911632n00,Site14,46.91,16.32,
+eu056162117n00,Site15,56.16,21.17,
+eu05838825n00,Site16,58.38,8.25,
+eu065831391n00,Site17,65.83,13.91,
+eu06278888n00,Site18,62.78,8.88,
+eu078901188n00,Site19,78.9,11.88,
+eu060371107n00,Site20,60.37,11.07,
+eu078921192n00,Site21,78.92,11.92,
+eu054152206n00,Site22,54.15,22.06,
+eu063851533n00,Site23,63.85,15.33,
+eu057391191n00,Site24,57.39,11.91,
+eu056041314n00,Site25,56.04,13.14,
+eu060081750n00,Site26,60.08,17.5,
+eu049052226n00,Site27,49.05,22.26,
+eu05635960n00,Site28,56.35,9.6,
+eu056711151n00,Site29,56.71,11.51,
+eu055691208n00,Site30,55.69,12.08,
+eu060532766n00,Site31,60.53,27.66,
+eu05444787n00,Site32,54.44,-7.87,
+eu05579324n00,Site33,55.79,-3.24,
+eu05114143n00,Site34,51.14,-1.43,
+eu046961958n00,Site35,46.96,19.58,
+eu046911632n00,Site36,46.91,16.32,
+eu056162117n00,Site37,56.16,21.17,
+eu05838825n00,Site38,58.38,8.25,
+eu065831391n00,Site39,65.83,13.91,
+eu06278888n00,Site40,62.78,8.88,
+eu078901188n00,Site41,78.9,11.88,
+eu060371107n00,Site42,60.37,11.07,
+eu078921192n00,Site43,78.92,11.92,
+eu054152206n00,Site44,54.15,22.06,
+eu063851533n00,Site45,63.85,15.33,
+eu057391191n00,Site46,57.39,11.91,
+eu056041314n00,Site47,56.04,13.14,
+eu060081750n00,Site48,60.08,17.5,
+eu049052226n00,Site49,49.05,22.26,