rc-qlc 0.3.24__cp311-cp311-macosx_11_0_arm64.whl

qlc/config/json/qlc_config_example_4c_eu-coll.json

@@ -0,0 +1,45 @@
+[
+  {
+    "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",
+    "mod_path": "$HOME/qlc/mod/",
+    "model": "ifs",
+    "experiments": "hylm,i3bw,i3ad",
+    "exp_labels": "CY48R1,CY49R1_NOE4C,CY49R1",
+    "start_date": "2018-12-01",
+    "end_date": "2018-12-31",
+    "variable": "SO2,SO4,HNO3,NO3,NH3,NH4",
+    "station_radius_deg": 0.5,
+    "plot_type": "",
+    "plot_region": "EU",
+    "time_average": "daily,weekly",
+    "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": false,
+    "show_station_timeseries_obs": false,
+    "show_station_timeseries_mod": false,
+    "show_station_timeseries_com": true,
+    "save_plot_format": "pdf",
+    "save_data_format": "nc",
+    "multiprocessing": true,
+    "n_threads": "4",
+    "debug": false,
+
+    "global_attributes": {
+      "title": "Air pollutants over Europe, SO2,SO4,HNO3,NO3,NH4,NH3",
+      "summary": "EBAS daily observations for selected EU stations.",
+      "author": "Swen Metzger, sm@researchconcepts.io",
+      "history": "Processed for CAMS2_35bis (dev 1.2)",
+      "Conventions": "CF-1.8"
+    }
+  }
+]

qlc/config/nml/mars_A1_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/qlc.conf file
+# param_A=("207.210" "72.210"  "73.210"  "74.210")
+# ncvar_A=("var207"  "var72"   "var73"   "var74")
+# myvar_A=("AOD"     "PM1"     "PM2.5"   "PM10")
+# surface level
+RETRIEVE,
+CLASS      = XCLASS,
+TYPE       = fc, 
+STREAM     = oper,
+EXPVER     = EXP,
+PARAM      = 73.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_A1_sfc.grb"

qlc/config/nml/mars_A2_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/qlc.conf file
+# param_A=("207.210" "72.210"  "73.210"  "74.210")
+# ncvar_A=("var207"  "var72"   "var73"   "var74")
+# myvar_A=("AOD"     "PM1"     "PM2.5"   "PM10")
+# surface level
+RETRIEVE,
+CLASS      = XCLASS,
+TYPE       = fc, 
+STREAM     = oper,
+EXPVER     = EXP,
+PARAM      = 207.210/72.210/73.210/74.210,
+LEVTYPE    = sfc,
+GRID       = 0.5/0.5,
+TIME       = 00:00:00,
+STEP       = 0/to/21/by/3,
+LEVELIST   = 137,
+DATE       = SDATE/to/EDATE,
+target     = "MYPATH/MYFILE_A2_sfc.grb"

qlc/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/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/config/nml/mars_B2_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/6.217/122.210/203.210,
+LEVTYPE    = pl,
+GRID       = 0.5/0.5,
+TIME       = 00:00:00,
+STEP       = 0/to/21/by/3,
+LEVELIST   = 1/2/3/5/7/10/20/30/50/70/100/150/200/250/300/400/500/700/850/925/1000,
+DATE       = SDATE/to/EDATE,
+target     = "MYPATH/MYFILE_B2_pl.grb"

qlc/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/config/nml/mars_C2_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      = 36.212/35.212/2.212/1.212,
+LEVTYPE    = pl,
+GRID       = 0.5/0.5,
+TIME       = 00:00:00,
+STEP       = 0/to/21/by/3,
+LEVELIST   = 1/2/3/5/7/10/20/30/50/70/100/150/200/250/300/400/500/700/850/925/1000,
+DATE       = SDATE/to/EDATE,
+target     = "MYPATH/MYFILE_C2_pl.grb"

qlc/config/nml/mars_C3_ml.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_C3-ml=("247.210" "248.210" "249.210" "11.210")
+# ncvar_C3-ml=("var247"  "var248"  "var249"  "var11" )
+# myvar_C3-ml=("NO3a"    "NO3b"    "NH4"     "SO4")
+# model levels
+RETRIEVE,
+CLASS      = XCLASS,
+TYPE       = fc, 
+STREAM     = oper,
+EXPVER     = EXP,
+PARAM      = 247.210/248.210/249.210/11.210,
+LEVTYPE    = ml,
+GRID       = 0.5/0.5,
+TIME       = 00:00:00,
+STEP       = 0/to/21/by/3,
+LEVELIST   = 1/to/137,
+DATE       = SDATE/to/EDATE,
+target     = "MYPATH/MYFILE_C3_ml.grb"

qlc/config/nml/mars_D.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_D=("51.212"  "52.212")
+# ncvar_D=("var51"   "var52")
+# myvar_D=("pHcloud" "pHrain")
+# model levels
+RETRIEVE,
+CLASS      = XCLASS,
+TYPE       = fc, 
+STREAM     = oper,
+EXPVER     = EXP,
+PARAM      = 51.212/52.212,
+LEVTYPE    = ml,
+GRID       = 0.5/0.5,
+TIME       = 00:00:00,
+STEP       = 0/to/21/by/3,
+LEVELIST   = 100/to/137,
+DATE       = SDATE/to/EDATE,
+target     = "MYPATH/MYFILE_D.grb"

qlc/config/nml/mars_E.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_E=("210025")
+# ncvar_E=("aergn10")
+# myvar_E=("EQdiag")
+# model level 1:80: 1-30 GF/ 31-60 AW speciated + 61-80 diag fields
+RETRIEVE,
+CLASS      = XCLASS,
+TYPE       = fc, 
+STREAM     = oper,
+EXPVER     = EXP,
+PARAM      = 210025,
+LEVTYPE    = ml,
+GRID       = 0.5/0.5,
+TIME       = 00:00:00,
+STEP       = 0/to/21/by/3,
+LEVELIST   = 1/to/71,
+DATE       = SDATE/to/EDATE,
+target     = "MYPATH/MYFILE_E.grb"

qlc/config/nml/mars_F.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_F=("22.210")
+# ncvar_F=("aergn07")
+# myvar_F=("pHaer")
+# model level 12: aerosol pH
+RETRIEVE,
+CLASS      = XCLASS,
+TYPE       = fc, 
+STREAM     = oper,
+EXPVER     = EXP,
+PARAM      = 22.210,
+LEVTYPE    = ml,
+GRID       = 0.5/0.5,
+TIME       = 00:00:00,
+STEP       = 0/to/21/by/3,
+LEVELIST   = 12,
+DATE       = SDATE/to/EDATE,
+target     = "MYPATH/MYFILE_F.grb"

qlc/config/nml/mars_G.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_G=("22.210")
+# ncvar_G=("aergn07")
+# myvar_G=("AW")
+# model level 15: aerosol water
+RETRIEVE,
+CLASS      = XCLASS,
+TYPE       = fc, 
+STREAM     = oper,
+EXPVER     = EXP,
+PARAM      = 22.210,
+LEVTYPE    = ml,
+GRID       = 0.5/0.5,
+TIME       = 00:00:00,
+STEP       = 0/to/21/by/3,
+LEVELIST   = 15,
+DATE       = SDATE/to/EDATE,
+target     = "MYPATH/MYFILE_G.grb"

qlc/config/qlc_cams.conf

@@ -0,0 +1,26 @@
+#----------------------------------------------------------------------
+#----------------------- QLC version to be used -------------------
+QLC_VERSION="VERSION"
+#----------------------- Path definitions -------------------------
+QLC_HOME="$HOME/qlc"
+QLC_DIRECTORY="${QLC_HOME}_v${QLC_VERSION}/cams"
+SCRIPTS_PATH="${QLC_DIRECTORY}/bin"
+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"
+#----------------------------------------------------------------------
+# User specific configuration file
+CONFIG_DIR="$HOME/qlc/config"
+CONFIG_TEX="$CONFIG_DIR/qlc_tex.conf"
+#----------------------------------------------------------------------
+# Source the tex script configuration file to load the settings
+. "$CONFIG_TEX"
+#----------------------------------------------------------------------
+#----------------------------------------------------------------------

qlc/config/qlc_test.conf

@@ -0,0 +1,26 @@
+#----------------------------------------------------------------------
+#----------------------- QLC version to be used -------------------
+QLC_VERSION="VERSION"
+#----------------------- Path definitions -------------------------
+QLC_HOME="$HOME/qlc"
+QLC_DIRECTORY="${QLC_HOME}_v${QLC_VERSION}/test"
+SCRIPTS_PATH="${QLC_DIRECTORY}/bin"
+WORKING_DIRECTORY="${QLC_DIRECTORY}"
+MARS_RETRIEVAL_DIRECTORY="${QLC_HOME}/Results"
+ANALYSIS_DIRECTORY="${QLC_HOME}/Analysis"
+PLOTS_DIRECTORY="${QLC_HOME}/Plots"
+TEX_DIRECTORY="${QLC_HOME}/Presentations"
+#----------------------- PDF presentation and info  -------------
+TEAM_PREFIX="CAMS2_35"
+EVALUATION_PREFIX="EVAL"
+MODEL_RESOLUTION="T255L137"
+TIME_RESOLUTION="03hh"
+#----------------------------------------------------------------------
+# User specific configuration file
+CONFIG_DIR="$HOME/qlc/config"
+CONFIG_TEX="$CONFIG_DIR/qlc_tex.conf"
+#----------------------------------------------------------------------
+# Source the tex script configuration file to load the settings
+. "$CONFIG_TEX"
+#----------------------------------------------------------------------
+#----------------------------------------------------------------------

qlc/config/qlc_tex.conf

@@ -0,0 +1,107 @@
+#----------------------------------------------------------------------
+#----------------------- PDF presentation and info  -------------
+#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/doc/CONTRIBUTING.md

@@ -0,0 +1,105 @@
+# Contributing to QLC
+
+Thank you for considering contributing to QLC!
+
+This project supports structured comparisons between model and observation datasets (CAMS, surface stations, etc.). Contributions are welcome in the form of bug reports, feature proposals, configuration templates, or plugins.
+
+---
+
+## Package Layout
+
+- `qlc/`: Main package directory.
+  - `cli/`: Command-line entry point logic.
+  - `py/`: Core Python/Cython source files (compiled to binaries).
+  - `sh/`: Shell scripts for the pipeline driver.
+  - `config/`: Configuration templates and defaults.
+  - `examples/`: Sample case for testing.
+  - `doc/`: Documentation files.
+
+---
+
+## CLI Tools
+
+After installation, the following entry points are available:
+
+- `qlc` → Shell-based full pipeline
+- `qlc-py` → Python-only driver
+- `sqlc` → Batch wrapper for `qlc`
+
+---
+
+## Plugin Support
+
+Plugins may be placed in:
+
+```bash
+~/qlc/plugin/
+```
+
+These are loaded dynamically via `plugin_loader.py` if found.
+
+---
+
+## Development Setup
+
+To contribute to `qlc`, you should set up a local development environment. This allows you to edit the code and test your changes live.
+
+1.  **Clone the repository:**
+    ```bash
+    git clone https://github.com/researchConcepts/qlc.git
+    cd qlc
+    ```
+
+2.  **(Recommended) Create and activate a virtual environment:**
+    ```bash
+    python3 -m venv .venv
+    source .venv/bin/activate
+    ```
+
+3.  **Install in "editable" mode:**
+    This command installs all dependencies and links your environment to your source code. Any changes you make to the `.py` files will be reflected immediately.
+    ```bash
+    pip install -e .
+    ```
+
+---
+
+## Building Wheels for Distribution
+
+To build the platform-specific wheels for distribution on PyPI, use the provided build script. It handles the complexities of cross-platform compilation.
+
+```bash
+# Ensure you have the target Python version installed (e.g., 3.10)
+# Then run the build script, pointing to that interpreter
+python build_wheels.py --python /path/to/your/python3.10
+```
+The final wheels will be located in the `dist/` directory.
+
+---
+
+## Testing
+
+Unit tests (to be added) will be collected under `tests/`.
+
+  ```bash
+  python -m qlc.install --test
+  python -m qlc.install --cams
+  ```
+
+---
+
+## Style Guide
+
+- Follow [PEP8](https://www.python.org/dev/peps/pep-0008/)
+- Use docstrings in PEP257 format and keep things simple (KISS principle)
+- Write CLI-facing functions with clean logging
+
+---
+
+## License
+
+This project uses the MIT License. By contributing, you agree your code may be distributed under the same license.
+
+---
+
+Thanks again!

qlc/doc/README.md

@@ -0,0 +1,116 @@
+# Quick Look Content (QLC): Model–Observation Comparison Suite for Use with CAMS
+
+`qlc` is a single command-line tool for model–observation comparisons with automated figures and summaries,
+designed to support climate and air quality monitoring and specifically adapted for use with CAMS (Copernicus Atmospheric Monitoring Service) datasets.
+
+| Package | Status |
+|---------|--------|
+| [rc-qlc on PyPI](https://pypi.org/project/rc-qlc/) | ![PyPI](https://img.shields.io/pypi/v/rc-qlc?color=blue) |
+
+---
+
+## Features
+
+- Side-by-side evaluation of observational and modelled data
+- Fully scriptable and automated post-processing chain 
+- Modular structure using shell + Python + Cython
+- Generates publication-ready figures and LaTeX integration
+- Supports NetCDF and CSV time series formats
+- Pre-configured CAMS observational interface via JSON
+
+---
+
+## User Installation
+
+Use one of the following install modes:
+
+```bash
+# Option 1: CAMS (default data links + config)
+pip install rc-qlc && qlc-install --cams
+
+# Option 2: Local test mode with embedded examples
+pip install rc-qlc && qlc-install --test
+
+# Option 3: Custom interactive mode
+pip install rc-qlc && qlc-install --interactive="./path/to/qlc_user.conf"
+```
+
+---
+
+## Example Use Cases
+
+### Run the full shell pipeline (retrieval, processing, plotting):
+```bash
+qlc
+```
+
+### Run just the observation/model comparison in Python:
+```bash
+qlc-py
+```
+
+### Submit via batch system (e.g., SLURM or LSF):
+```bash
+sqlc
+```
+
+## Developer Setup
+
+To work on the `qlc` source code, clone the repository and install it in "editable" mode. This will install all dependencies and link the `qlc` command to your source tree.
+
+```bash
+# 1. Clone the repository
+git clone https://github.com/researchConcepts/qlc.git
+cd qlc
+
+# 2. (Recommended) Create and activate a virtual environment
+python3 -m venv .venv
+source .venv/bin/activate
+
+# 3. Install in editable mode
+pip install -e .
+```
+
+---
+
+## Configuration Structure
+
+The installer script creates the following structure in your home directory:
+```
+$HOME/qlc_v<version>/
+├── test/                   # Root directory for the 'test' installation mode
+│   ├── bin/                # Symlinks to shell scripts
+│   ├── doc/                # Symlinks to documentation
+│   ├── config/             # Active config files (e.g., qlc.conf)
+│   ├── examples/           # Test input and output files
+│   ├── obs/, mod/, ...     # Runtime directories
+│   └── VERSION.json        # Tracks install mode and version
+└── cams/                   # Root for 'cams' mode, etc.
+```
+A symlink `$HOME/qlc` is also created to point to the active installation. You can edit `$HOME/qlc/config/qlc.conf` to modify runtime behavior.
+
+---
+
+## Documentation
+
+- All core logic is contained in the `qlc` package.
+- Shell scripts for driving the pipeline are in `qlc/sh/`.
+- The core Python/Cython logic is in `qlc/py/*.py` and is compiled to binary modules for performance.
+
+---
+
+## Developer Notes
+
+- Python source files (`.py`) are compiled to binary modules (`.so`) using Cython at install time.
+- The package version is managed in `pyproject.toml`.
+- The `qlc-install` script sets up the runtime environment by creating directories and symlinks.
+
+---
+
+## License
+
+© ResearchConcepts io GmbH  
+Contact: [contact@researchconcepts.io](mailto:contact@researchconcepts.io)  
+MIT-compatible, source-restricted under private release until publication.
+
+---