Package: qgs
Quasi-Geostrophic Spectral model (qgs)General Informationqgs is a Python implementation of an atmospheric model for midlatitudes.  It models the dynamics of
a 2-layerquasi-geostrophicchannel
atmosphere on abeta-plane, coupled to a simple land orshallow-waterocean component.About(c) 2020-2023 qgs Developers and ContributorsPart of the code originates from the PythonMAOOAMimplementation by Maxime Tondeur and Jonathan Demaeyer.SeeLICENSE.txtfor license information.Please cite the code description article if you use (a part of) this software for a publication:Demaeyer J., De Cruz, L. and Vannitsem, S. , (2020). qgs: A flexible Python framework of reduced-order multiscale climate models.Journal of Open Source Software,5(56), 2597,https://doi.org/10.21105/joss.02597.Please consult the qgscode repositoryfor updates.InstallationWith pipThe easiest way to install and run qgs is to usepippip install qgsand you are set!Additionally, you can clone the repositorygit clone https://github.com/Climdyn/qgs.gitand perform a test by running the scriptpython qgs/qgs_rp.pyto see if everything runs smoothly (this should take less than a minute).With AnacondaThe easiest way to install and run qgs is to use an appropriate environment created throughAnaconda.First install Anaconda and clone the repository:git clone https://github.com/Climdyn/qgs.gitThen install and activate the Python3 Anaconda environment:conda env create -f environment.yml
conda activate qgsYou can then perform a test by running the scriptpython qgs_rp.pyto see if everything runs smoothly (this should take less than a minute).Note for Windows and MacOS usersPresently, qgs is compatible with Windows and MacOS but users wanting to use qgs inside their Python scripts must guard the main script with aif __name__ == "__main__":clause and add the following lines belowfrom multiprocessing import freeze_support
  freeze_support()About this usage, see for example the main scriptsqgs_rp.pyandqgs_maooam.pyin the root folder.
Note that the Jupyter notebooks are not concerned by this recommendation and work perfectly well on both operating systems.Why?These lines are required to make the multiprocessing library works with these operating systems. Seeherefor more details,
and in particularthis section.Activating DifferentialEquations.jl optional supportIn addition to the qgs builtin Runge-Kutta integrator, the qgs model can alternatively be integrated with a package calledDifferentialEquations.jlwritten inJulia, and available through thediffeqpypython package.
The diffeqpy package first installation step is done by Anaconda in the qgs environment but then you mustinstall Juliaand follow the final manual installation instruction found in thediffeqpy README.These can be summed up as opening a terminal and doing:conda activate qgs
pythonand then inside the Python command line interface do:>>> import diffeqpy
>>> diffeqpy.install()which will then finalize the installation. An example of a notebook using this package is available in the documentation and onreadthedocs.DocumentationTo build the documentation, please run (with the conda environment activated):cd documentation
make htmlYou may need to installmakeif it is not already present on your system.
Once built, the documentation is availablehere.The documentation is also available online on read the docs:https://qgs.readthedocs.io/Usageqgs can be used by editing and running the scriptqgs_rp.pyandqgs_maooam.pyfound in the main folder.For more advanced usages, please read theUser Guides.ExamplesAnother nice way to run the model is through the use of Jupyter notebooks.
Simple examples can be found in thenotebooks folder.
For instance, runningconda activate qgs
cd notebooks
jupyter-notebookwill lead you to your favorite browser where you can load and run the examples.Dependenciesqgs needs mainly:Numpyfor numeric supportsparsefor sparse multidimensional arrays supportNumbafor code accelerationSympyfor symbolic manipulation of inner productsCheck the yaml fileenvironment.ymlfor the dependencies.Forthcoming developmentsScientific development (short-to-mid-term developments)Non-autonomous equation (seasonality, etc...)Energy diagnosticsTechnical mid-term developmentsDimensionally robust Parameter class operationVectorization of the tensor computationLong-term development trackActive advectionTrue quasi-geostrophic ocean when using ocean model versionSalinity in the oceanSymbolic PDE equation specificationNumerical basis of functionContributing to qgsIf you want to contribute actively to the roadmap detailed above, please contact the main authors.In addition, if you have made changes that you think will be useful to others, please feel free to suggest these as a pull request on theqgs Github repository.More information and guidance about how to do a pull request for qgs can be found in the documentationhere.Other atmospheric models in PythonNon-exhaustive list:Q-GCM: A mid-latitude grid based ocean-atmosphere model like MAOOAM. Code in Fortran,
interface is in Python.pyqg: A pseudo-spectral python solver for quasi-geostrophic systems.Isca: Research GCM written in Fortran and largely
configured with Python scripts, with internal coding changes required for non-standard cases.