-
Notifications
You must be signed in to change notification settings - Fork 5
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Merge pull request #79 from n-claes/docs/devdocs
Development documentation and doc updates
- Loading branch information
Showing
56 changed files
with
1,771 additions
and
1,689 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,83 @@ | ||
| name: docs | ||
|
|
||
| on: | ||
| push: | ||
| branches: [ master, develop ] | ||
| pull_request: | ||
| branches: [ develop ] | ||
|
|
||
| jobs: | ||
| develop: | ||
| runs-on: ubuntu-latest | ||
|
|
||
| # only run on PR or push to develop, skip on master | ||
| if: ${{ contains(github.base_ref, 'develop') || contains(github.ref, 'refs/heads/develop') }} | ||
|
|
||
| steps: | ||
| - uses: actions/checkout@v2 | ||
| - name: Set up Python 3.8 | ||
| uses: actions/setup-python@v1 | ||
| with: | ||
| python-version: 3.8 | ||
|
|
||
| - name: Install dependencies | ||
| run: | | ||
| python -m pip install --upgrade pip | ||
| pip install ford graphviz | ||
| sudo apt-get install graphviz | ||
| pip install -U sphinx | ||
| pip install numpydoc sphinx-rtd-theme lazy-object-proxy==1.4 sphinx-autoapi | ||
| - name: Generate documentation | ||
| run: | | ||
| cd docs | ||
| python generate_docs.py develop | ||
| - name: Deploy | ||
| uses: peaceiris/actions-gh-pages@v3 | ||
| if: ${{ contains(github.ref, 'refs/heads/develop') }} | ||
| with: | ||
| deploy_key: ${{ secrets.ACTIONS_DEPLOY_KEY }} | ||
| external_repository: n-claes/legolas.science-dev | ||
| publish_branch: main | ||
| publish_dir: ./docs | ||
| cname: dev.legolas.science | ||
| enable_jekyll: true | ||
| full_commit_message: 'dev: deploy n-claes/legolas@${{ github.sha }}' | ||
|
|
||
| stable: | ||
| runs-on: ubuntu-latest | ||
|
|
||
| # only run on push to master, skip for develop | ||
| if: ${{ contains(github.ref, 'refs/heads/master') }} | ||
|
|
||
| steps: | ||
| - uses: actions/checkout@v2 | ||
| - name: Set up Python 3.8 | ||
| uses: actions/setup-python@v1 | ||
| with: | ||
| python-version: 3.8 | ||
|
|
||
| - name: Install dependencies | ||
| run: | | ||
| python -m pip install --upgrade pip | ||
| pip install ford graphviz | ||
| sudo apt-get install graphviz | ||
| pip install -U sphinx | ||
| pip install numpydoc sphinx-rtd-theme lazy-object-proxy==1.4 sphinx-autoapi | ||
| - name: Generate documentation | ||
| run: | | ||
| cd docs | ||
| python generate_docs.py stable | ||
| - name: Deploy | ||
| uses: peaceiris/actions-gh-pages@v3 | ||
| with: | ||
| deploy_key: ${{ secrets.ACTIONS_DEPLOY_KEY_STABLE }} | ||
| external_repository: n-claes/legolas.science-stable | ||
| publish_branch: main | ||
| publish_dir: ./docs | ||
| cname: legolas.science | ||
| enable_jekyll: true | ||
| full_commit_message: 'stable: deploy n-claes/legolas@${{ github.sha }}' |
This file was deleted.
Oops, something went wrong.
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,79 +1,33 @@ | ||
|
|
||
|  | ||
|  | ||
|
|
||
| **L**arge **E**igensystem **G**enerator for **O**ne-dimensional p**LAS**mas | ||
|
|
||
| [](https://github.com/n-claes/legolas/actions/workflows/legolas.yml) [](https://github.com/n-claes/legolas/actions/workflows/pylbo.yml) [](https://github.com/n-claes/legolas/actions/workflows/docs.yml) [](https://codecov.io/gh/n-claes/legolas) [](https://github.com/n-claes/legolas/releases) [](https://join.slack.com/t/the-legolas-code/shared_invite/zt-tsb5yaht-LtLWHzVu8Zux~Yt3PBx32Q) | ||
|
|
||
| ### Table of contents | ||
| 1. [CI status](#ci-status) | ||
| 2. [Using Legolas](#using-legolas) | ||
| 3. [Obtaining Legolas](#obtaining-legolas) | ||
| 4. [Requirements](#requirements) | ||
| 5. [Compilation](#compilation) | ||
| 6. [Contents](#directory-contents) | ||
| 1. [About](#about-legolas) | ||
| 2. [Documentation](#documentation) | ||
| 3. [Versions](#stable-and-develop-versions) | ||
| 4. [Using Legolas](#using-legolas) | ||
|
|
||
| ## CI status | ||
| - Branch `master` <br> | ||
| [](https://github.com/n-claes/legolas/actions?query=workflow%3Aregression+branch%3Amaster) | ||
| [](https://github.com/n-claes/legolas/actions?query=workflow%3Alegolas-core+branch%3Amaster) | ||
| [](https://github.com/n-claes/legolas/actions?query=workflow%3Apylbo-core+branch%3Amaster) | ||
| - Branch `develop` <br> | ||
| [](https://github.com/n-claes/legolas/actions?query=workflow%3Aregression+branch%3Adevelop) | ||
| [](https://github.com/n-claes/legolas/actions?query=workflow%3Alegolas-core+branch%3Adevelop) | ||
| [](https://github.com/n-claes/legolas/actions?query=workflow%3Apylbo-core+branch%3Adevelop) | ||
| ## About Legolas | ||
| The main goal of Legolas is to provide a new and modern user-friendly code while making use of the most recent developments in linear algebra and theoretical (linear) MHD, allowing for high resolution eigenspectrum studies with various physical effects included. | ||
|
|
||
| ## Using Legolas | ||
| :warning: **Please note** :warning: | ||
| Legolas is being developed and maintained at the [Centre for mathematical Plasma-Astrophysics](https://wis.kuleuven.be/CmPA), KU Leuven, Belgium. | ||
|
|
||
| Legolas is the result of months and months of developing, testing, fixing issues, testing again, | ||
| thinking bugs are fixed, further development, discovering that bugs weren't fixed, headscratching, testing again, etc. | ||
| In short, a typical development process of a brand new code. Since this took (and still takes) a lot of effort and time, | ||
| we therefore kindly ask that _**the first published peer-reviewed paper from applying Legolas is done in co-authorship with at least one of the original authors**_. | ||
| Since the code is brand new we would like to know how it is used and provide guidance if possible. | ||
|
|
||
| ## Obtaining Legolas | ||
| You can obtain the latest stable version of the code through | ||
| ```bash | ||
| git clone https://github.com/n-claes/legolas.git | ||
| cd legolas | ||
| git checkout master | ||
| ``` | ||
| We ensure that the `master` branch always contains a stable release. If you would | ||
| like to check out the latest development goodies of the code, you can checkout the `develop` branch instead | ||
| and build from that one. Our typical workflow is branching off of `develop`, extend or create a feature and merge it back | ||
| into `develop` when the automated tests are passing. Every now and then we merge `develop` into `master` and bump the | ||
| release version. We hence (try to) ensure that `develop` is stable, but beware that this may not always be the case. | ||
| ## Documentation | ||
| We have a dedicated website on [legolas.science](https://legolas.science) which contains a detailed guide on how to install, compile and use the code. There you can also find the source code documentation of both Legolas and the post-processing framework Pylbo, which is rendered straight from the `master` (or `develop`) branch and updated on every commit. | ||
|
|
||
| Also note that due to this development workflow there will be multiple branches present in the repository at any | ||
| given time. Feel free to check these out, but note that we will frequently rebase those so know that merge conflicts may | ||
| be common when pulling updates from those branches. | ||
| ## Stable and develop versions | ||
| The `master` branch of this repository should contain the latest stable release of the code, the main website is built from this branch. If you would like to check out the latest development goodies instead you can take a look at the `develop` branch. As there may be some time between major releases it is possible that the development branch can be quite different from the stable branch. However, the development version has its own dedicated website at [dev.legolas.science](https://dev.legolas.science), for those who want to use the bleeding-edge version of the code. | ||
|
|
||
| ## Requirements | ||
| We make extensive use of submodules (Fortran 2008) and object-oriented features (Fortran 2003), | ||
| meaning that Legolas requires relatively recent compilers. We build using [CMake](https://cmake.org). | ||
| To make use of the post-processing framework [Pylbo](post_processing) (which is highly recommended since we | ||
| use a dedicated file format to store information) you need Python 3.6 or higher. | ||
| The list below gives an indication of what is needed, note that lower versions _may_ work (but we haven't tested that). | ||
| - gfortran v8.x+ | ||
| - CMake v3.12+ | ||
| - Python v3.6+ | ||
| - make | ||
| - BLAS and LAPACK v3.5+ | ||
| Note that while everything on the `develop` branch _should_ be stable, it is possible that some features there are still under development and/or not yet entirely tested or documented. | ||
|
|
||
| For more information see the website. | ||
|
|
||
| ## Compilation | ||
| For compilation instructions we refer to the website. | ||
| ## Using Legolas | ||
| :warning: **Please note** | ||
|
|
||
| ## Directory contents | ||
| Below is an overview of what's in the directory: | ||
| - `.github/workflows`: all `.yml` files used for automatic testing. | ||
| - `docs`: everything related to documentation, contains the Jekyll/Sphinx/Ford configuration files. The website is built from this folder. | ||
| - `post-processing`: contains the Python package Pylbo. | ||
| - `setup_tools`: scripts related to Legolas setup, also contains the `findBLAS` and `findLAPACK` CMake files. | ||
| - `src`: all legolas source files and subdirectories. | ||
| - `tests`: everything related to testing | ||
| - `core_tests`: tests for the Legolas core subroutines, uses [pFUnit](https://github.com/Goddard-Fortran-Ecosystem/pFUnit). | ||
| - `pylbo_tests`: tests for the Pylbo framework, does checks on internal Pylbo routines + Legolas interface for multiruns. | ||
| - `regression_tests`: tests for Legolas output, compares results from newly compiled code to expected (stored) output. | ||
| - `CMakeLists.txt`: used for build configuration | ||
| - `legolas_config.par`: example parameter file for legolas configuration. | ||
| - `pylbo_wrapper.py`: wrapper script to interface with Pylbo. | ||
| Legolas has taken (and still takes up) a lot of effort and time to test, develop and maintain. | ||
| Since the code is relatively new we would like to know how it is used and provide guidance if possible. | ||
| To that end, we kindly ask that the _**the first published peer-reviewed paper from applying Legolas is done in co-authorship with at least one of the original authors**_. The BibTex citation to our ApJS method paper can be found [here](https://ui.adsabs.harvard.edu/abs/2020arXiv201014148C/exportcitation). |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,48 @@ | ||
| --- | ||
| title: About Legolas | ||
| layout: single | ||
| classes: wide | ||
| sidebar: | ||
| nav: "leftcontents" | ||
| last_modified_at: 2021-07-28 | ||
| --- | ||
|
|
||
| ## Origins | ||
| The development of Legolas started due to the need of a new and flexible numerical tool to solve the full system of linearised | ||
| MHD equations with various physical effects included. Calculating all eigenvalues for such setups is relatively | ||
| straightforward for homogeneous cases since this boils down to calculating the algebraic system of linearised equations, | ||
| writing down the matrices and plugging them into your favourite eigenvalue problem solver. | ||
| However, this becomes extremely difficult (or even impossible) to do for more general cases with inhomogeneous equilibria, | ||
| unless some rather special conditions are applied to the system to make it analytically tractable. | ||
|
|
||
| Legolas actually builds on the heritage of early numerical codes, most notably LEDA (Kerner, 1985), meant for studies of ideal and resistive MHD spectra. | ||
| The original LEDA code has had several extensions over the past decades, such as LEDA2 (Van Der Linden, 1992) for non-adiabatic spectra and LEDAFLOW (Nijboer, 1997) for non-static spectra. | ||
| These codes were not mergeable however, such that a combination of for example non-adiabatic effects, flow and resistivity was not possible without a major undertaking. | ||
| This prompted us to start from scratch on a brand new, modern MHD spectral code which we named Legolas, | ||
| short for "**<u>L</u>**arge **<u>E</u>**igensystem **<u>G</u>**enerator for **<u>O</u>**ne-dimensional p**<u>las</u>**mas". | ||
|
|
||
| Development on Legolas started late 2019 by Niels Claes as part of his PhD studies. He was joined in mid 2020 by Jordi De Jonghe, and both of them are currently | ||
| maintaining and developing the code even further in close collaboration. | ||
| <img src="/assets/images/erc_logo.png" alt="ERC logo" align="right" width="100" height="100"> | ||
| This is all done under the supervision of Rony Keppens at the [Centre for | ||
| mathematical Plasma-Astrophysics](https://wis.kuleuven.be/CmPA) at the KU Leuven, Belgium, as part of the [ERC PROMINENT](https://erc-prominent.github.io) project. | ||
|
|
||
| ## Aims | ||
| The main goal of Legolas is to provide a new and modern user-friendly code, making use of the most recent developments in linear algebra and | ||
| theoretical (linear) MHD. This allows for detailed, high-resolution studies of the full (M)HD linear spectrum through fully realistic setups | ||
| and parametric studies, including a myriad of physical effects. | ||
|
|
||
| ## Features | ||
| Legolas is written in modern Fortran and is highly modularised. This allows for easy maintenance and makes the code ready | ||
| to be extended with additional physics and modern algorithmic requirements. At the time of writing, Legolas currently supports | ||
| both 3D Cartesian or cylindrical geometries with 1D variation. | ||
| Various physical effects are implemented: | ||
| - background flows, allowing for non-static equilibrium conditions | ||
| - external gravity | ||
| - resistivity, either constant values or realistic temperature-dependent profiles | ||
| - optically thin radiative losses, based on modern cooling curves | ||
| - anisotropic thermal conduction, with fully customisable parallel/perpendicular effects with respect to the magnetic field | ||
| - viscosity | ||
| - Hall MHD | ||
|
|
||
| Note that Legolas can calculate spectra in either full MHD or in hydrodynamics (no magnetic field). |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Binary file not shown.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file not shown.
Binary file not shown.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file not shown.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file not shown.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
File renamed without changes
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file was deleted.
Oops, something went wrong.
Oops, something went wrong.