From c158c4df21a34c6c02f88f54214c387659adbcfd Mon Sep 17 00:00:00 2001 From: Timothy Nunn Date: Wed, 16 Aug 2023 14:36:35 +0100 Subject: [PATCH 1/5] Update README links to GitHub --- README.md | 17 ++++++++--------- 1 file changed, 8 insertions(+), 9 deletions(-) diff --git a/README.md b/README.md index 8fb7ebdf..ce4fb453 100644 --- a/README.md +++ b/README.md @@ -1,27 +1,26 @@ # PROCESS -PROCESS is the reactor systems code at [CCFE](www.ccfe.ac.uk). More information on PROCESS -can be found on the PROCESS [webpage](https://ccfe.ukaea.uk/resources/process/). +PROCESS is the reactor systems code at the [UK Atomic Energy Authority](https://ccfe.ukaea.uk/). More information on PROCESS can be found on the PROCESS [webpage](https://ccfe.ukaea.uk/resources/process/). -PROCESS was originally a Fortran code, but is now Python-wrapped Fortran. In order to use PROCESS, the Fortran must be compiled and a Python-Fortran interface generated for the Python to import. Once built, it can be installed and run as a Python package. +PROCESS was originally a Fortran code, but is currently a mixture of Python and Python-wrapped Fortran; the eventual aim is to have an entirely Python code base. In order to use PROCESS, the Fortran must be compiled and a Python-Fortran interface generated for the Python to import. Once built, it can be installed and run as a Python package. ## Getting Started -Please see the [installation guide](http://process.gitpages.ccfe.ac.uk/process/installation) and the [usage guide](http://process.gitpages.ccfe.ac.uk/process/usage). Once installed, the `examples` directory provides Jupyter notebooks for interactively demonstrating usage of PROCESS, which is a good place to start. The `examples/README.md` provides more help. +Please see the [installation guide](https://ukaea.github.io/PROCESS/installation/introduction/) and the [usage guide](https://ukaea.github.io/PROCESS/usage/running-process/). Once installed, the `examples` directory provides Jupyter notebooks for interactively demonstrating usage of PROCESS, which is a good place to start. The `examples/README.md` provides more help. ## Documentation -To read about how the code works and the modules in it see the [documentation](http://process.gitpages.ccfe.ac.uk/process), which is hosted on Gitlab Pages. +To read about how the code works and the modules in it see the [documentation](https://ukaea.github.io/PROCESS/). ## Tracking and Testing Process uses a mixture of tracking and testing to ensure code reliability. Tests are run on each branch and ensure the output of keys functions are correct. Tracking, on the other hand, shows graphs of a variables changes over time, and what commit caused the change. -Our tracker can be found here: http://process.gitpages.ccfe.ac.uk/process/tracking.html -Documentation on testing can be found here: http://process.gitpages.ccfe.ac.uk/process/development/testing/ +* Our tracker can be found here: https://ukaea.github.io/PROCESS/tracking.html +* Documentation on testing can be found here: https://ukaea.github.io/PROCESS/development/testing/ ## Development -Please see the CONTRIBUTING.md for guidance on how to contribute to PROCESS. Further information is found in the development section of the [documentation](http://process.gitpages.ccfe.ac.uk/process). +Please see the CONTRIBUTING.md for guidance on how to contribute to PROCESS. Further information is found in the development section of the [documentation](https://ukaea.github.io/PROCESS/). ## Publications -A list of publications using PROCESS is given [here](http://process.gitpages.ccfe.ac.uk/process/publications), including two papers outlining the physics and engineering models in PROCESS. +A list of publications using PROCESS is given [here](https://ukaea.github.io/PROCESS/publications), including two papers outlining the physics and engineering models in PROCESS. ## Contacts [James Morris](james.morris2@ukaea.uk) From be53d215aa6b0c7691d32c96ae6dac2f5ff773e0 Mon Sep 17 00:00:00 2001 From: Timothy Nunn Date: Wed, 16 Aug 2023 15:49:52 +0100 Subject: [PATCH 2/5] Update link locations in documentation --- .../proc-pages/installation/installation-docker.md | 12 +++--------- .../installation/installation-singularity.md | 12 ++++++------ .../proc-pages/installation/installation-ubuntu.md | 8 ++++---- 3 files changed, 13 insertions(+), 19 deletions(-) diff --git a/documentation/proc-pages/installation/installation-docker.md b/documentation/proc-pages/installation/installation-docker.md index 00c92b9e..3a9e9661 100644 --- a/documentation/proc-pages/installation/installation-docker.md +++ b/documentation/proc-pages/installation/installation-docker.md @@ -1,7 +1,7 @@ # Installation using Docker !!! Note "Note" - This section is for users of a privileged machine of the wrong OS e.g MacOS. If you are a using a shared resource e.g. computing cluster, please go [here](#singularity-container).* + This section is for users of a privileged machine of the wrong OS e.g MacOS. If you are a using a shared resource e.g. computing cluster, please go [here](https://ukaea.github.io/PROCESS/installation/installation-singularity/).* PROCESS can be run on Mac or in other environments inside a Docker container. The PROCESS repository, including source and build directories, remain in the host filesystem, but the @@ -22,23 +22,17 @@ using `homebrew`: brew --cask install docker ``` -Then login to the Gitlab container registry: - -``` -docker login git.ccfe.ac.uk:4567 -``` - Then download the Docker image from the Process Gitlab container registry: ``` -docker pull git.ccfe.ac.uk:4567/process/process/dev +docker pull ghcr.io/ukaea/process-ci:latest ``` Running `docker image ls` should show the image in your local Docker image repository. Optionally, you can change the image name to something more manageable: ``` -docker tag git.ccfe.ac.uk:4567/process/process/dev process-dev +docker tag ghcr.io/ukaea/process-ci:latest process-dev ``` to rename the image to "process-dev" with the "latest" tag: "process:latest". diff --git a/documentation/proc-pages/installation/installation-singularity.md b/documentation/proc-pages/installation/installation-singularity.md index 1f59c747..b90b4b2c 100644 --- a/documentation/proc-pages/installation/installation-singularity.md +++ b/documentation/proc-pages/installation/installation-singularity.md @@ -1,6 +1,6 @@ -# Installation using Singularity container +# Installation using Singularity/Apptainer container Singularity is a container environment similar to Docker. This means a user can run PROCESS with all required dependencies installed. Singularity, however, is designed to work with user-level @@ -11,7 +11,7 @@ Singularity can convert OCI compliant containers into the Singularity Image Form the Docker container above. Download, and convert the Docker container by running: ```bash -singularity pull --docker-login process.sif docker://git.ccfe.ac.uk:4567/process/process/dev:latest +apptainer pull process.sif docker://ghcr.io/ukaea/process-ci:latest ``` Singularity will then ask for a username and password, your CCFE GitLab short username and @@ -20,7 +20,7 @@ copied like any file. Running the following command will load a Singularity shel dependencies for PROCESS installed: ```bash -singularity shell process.sif +apptainer shell process.sif ``` Singularity will automatically mount your home (`$HOME`) directory into the container. Therefore, @@ -45,13 +45,13 @@ module load singularity/3.7.1 Pull the Singularity image and enter your git username and password when prompted: ```bash -singularity pull --docker-login process.sif docker://git.ccfe.ac.uk:4567/process/process/dev:latest +apptainer pull process.sif docker://ghcr.io/ukaea/process-ci:latest ``` Make sure you have created [ssh keys](https://docs.gitlab.com/ee/ssh/) and open the Singularity shell: ```bash -singularity shell process.sif +apptainer shell process.sif ``` Singularity is an environment which allows you to use dependencies not available on Freia, like @@ -68,4 +68,4 @@ cmake --build build ``` Now you can run commands within the shell like `process -i tests/regression/scenarios/large-tokamak/IN.DAT` -to verify installation and create [batch jobs](http://process.gitpages.ccfe.ac.uk/process/io/utilities-guide/). +to verify installation and create [batch jobs](https://ukaea.github.io/PROCESS/io/utilities/). diff --git a/documentation/proc-pages/installation/installation-ubuntu.md b/documentation/proc-pages/installation/installation-ubuntu.md index 20146979..ea648d8c 100644 --- a/documentation/proc-pages/installation/installation-ubuntu.md +++ b/documentation/proc-pages/installation/installation-ubuntu.md @@ -8,8 +8,8 @@ and the advantages of use. !!! Info "OS" This section is for users on a Windows system, if you are a MacOS or privileged machine user - please go [here](#docker-container), or if you are a using a shared resource, please - go [here](#singularity-container). + please go [here](https://ukaea.github.io/PROCESS/installation/installation-docker/), or if you are a using a shared resource, please + go [here](https://ukaea.github.io/PROCESS/installation/installation-singularity/). To install Windows Subsystem for Linux (WSL) follow the 'Manual Installation Steps' [here](https://docs.microsoft.com/en-us/windows/wsl/install-win10). Choose WSL 2 and Ubuntu 20 (if @@ -109,12 +109,12 @@ pytest which runs unit, integration, and regression tests. -A more in-depth discussion of testing can be found [here](http://process.gitpages.ccfe.ac.uk/process/development/testing/). +A more in-depth discussion of testing can be found [here](https://ukaea.github.io/PROCESS/development/testing/). If everything passes, this indicates a successful installation. If anything fails, this indicates that your environment produces different results to what is expected. You might consider creating an issue in GitHub, or trying out the -[Docker container](http://process.gitpages.ccfe.ac.uk/process/installation/installation-docker) instead. +[Docker container](https://ukaea.github.io/PROCESS/installation/installation-docker/) instead. !!! Question "Installation troubleshooting" From d5d483aeea582728c5b7b8e89c54fcfc3b44447e Mon Sep 17 00:00:00 2001 From: Timothy Nunn Date: Wed, 16 Aug 2023 17:00:21 +0100 Subject: [PATCH 3/5] Style vardes tables --- .../proc-pages/stylesheets/vardes.css | 38 +++++++++++-------- 1 file changed, 22 insertions(+), 16 deletions(-) diff --git a/documentation/proc-pages/stylesheets/vardes.css b/documentation/proc-pages/stylesheets/vardes.css index 7cca97ec..39787d98 100644 --- a/documentation/proc-pages/stylesheets/vardes.css +++ b/documentation/proc-pages/stylesheets/vardes.css @@ -6,19 +6,25 @@ table { table.vardes { table-layout: fixed; width: 100%; - overflow-wrap: anywhere; border-collapse: collapse; + border: 1px solid; } -th, td { +th { + font-weight: bold; +} + +th, +td { padding: 10px; + border: 1px solid; } html { font-size: 1.3rem; } -.md-typeset h1{ +.md-typeset h1 { font-weight: bold; color: var(--md-default-fg-color) !important; } @@ -63,22 +69,22 @@ html { /*-------------------- IMAGES --------------------*/ .logo { - width:200px; + width: 200px; } @media only screen and (max-width: 767px) { .logo { - width:35%; + width: 35%; } - } +} - .image { - width:75%; +.image { + width: 75%; } @media only screen and (max-width: 767px) { .image { - width:100%; + width: 100%; } } @@ -89,46 +95,46 @@ div.doc-contents:not(.first) { margin-bottom: 60px; } -div.doc-class > .doc-heading { +div.doc-class>.doc-heading { background-color: #e7f2fa; border-top: 3px solid #e0301c; padding: 10px; } -div.doc-class > .doc-heading::before { +div.doc-class>.doc-heading::before { content: "class"; color: dimgray; font-style: italic; font-size: 1rem; } -div.doc-method > h4::before { +div.doc-method>h4::before { content: "method"; color: dimgray; font-style: italic; font-size: 0.8rem; } -div.doc-function > .doc-heading { +div.doc-function>.doc-heading { background-color: #e7f2fa; border-top: 3px solid #e0301c; padding: 10px; } -div.doc-function > .doc-heading::before { +div.doc-function>.doc-heading::before { content: "function"; color: dimgray; font-style: italic; font-size: 1rem; } -div.doc-module > .doc-heading { +div.doc-module>.doc-heading { background-color: #e7f2fa; border-top: 6px solid #e0301c; padding: 10px; } -div.doc-module > .doc-heading::before { +div.doc-module>.doc-heading::before { content: "module"; color: dimgray; font-style: italic; From 75ff72fe57e015034e8a06e84002165186ee6ed6 Mon Sep 17 00:00:00 2001 From: Timothy Nunn Date: Wed, 16 Aug 2023 17:01:26 +0100 Subject: [PATCH 4/5] Various documentation QOL changes --- .../installation/installation-ubuntu.md | 39 ++++++++----------- mkdocs.yml | 4 +- 2 files changed, 18 insertions(+), 25 deletions(-) diff --git a/documentation/proc-pages/installation/installation-ubuntu.md b/documentation/proc-pages/installation/installation-ubuntu.md index ea648d8c..7fccc8c9 100644 --- a/documentation/proc-pages/installation/installation-ubuntu.md +++ b/documentation/proc-pages/installation/installation-ubuntu.md @@ -1,27 +1,26 @@ -# Installation on Ubuntu/WSL +# Installation on Ubuntu/Windows +PROCESS is developed and testing using Ubuntu 20. We cannot guarantee any other operating system will be able to compile PROCESS or reproduce results. We do unofficially support MacOS however PROCESS is **not** currently tested on this OS by the CI system. +!!! Info "Windows User" + Windows users should run PROCESS using WSL. -Using the Windows Subsystem for Linux (on Windows) or a containerised environment is the recommended -way to build, test, and run PROCESS on any OS other than Ubuntu 20. Documentation on Ubuntu for WSL -can be found [here](https://ubuntu.com/wsl) for a deeper description of how they function together -and the advantages of use. + To install Windows Subsystem for Linux (WSL) follow the 'Manual Installation Steps' + [here](https://docs.microsoft.com/en-us/windows/wsl/install-win10). Choose WSL 2 and Ubuntu 20 (if + installing from the Microsoft store then Ubuntu 20 is installed by default). -!!! Info "OS" - This section is for users on a Windows system, if you are a MacOS or privileged machine user - please go [here](https://ukaea.github.io/PROCESS/installation/installation-docker/), or if you are a using a shared resource, please - go [here](https://ukaea.github.io/PROCESS/installation/installation-singularity/). + The following command is used to install WSL (**you need admin privileges to perform this command**): -To install Windows Subsystem for Linux (WSL) follow the 'Manual Installation Steps' -[here](https://docs.microsoft.com/en-us/windows/wsl/install-win10). Choose WSL 2 and Ubuntu 20 (if -installing from the Microsoft store then Ubuntu 20 is installed by default). + ```bash + wsl --install + ``` -The following command is used to install WSL (**you need admin privileges to perform this command**): + If the above procedure fails to work, there is a [Microsoft help page](https://learn.microsoft.com/en-us/windows/wsl/install). -```bash -wsl --install -``` +!!! Info "Users on unsupported OS'" + Other users may find benefit in our [Docker installation guide](https://ukaea.github.io/PROCESS/installation/installation-docker/) if they are on a machine which they have admin privledges. + + Users of shared resources should see our [Singularity/Apptainer installation guide](https://ukaea.github.io/PROCESS/installation/installation-singularity/). -If the above procedure fails to work, there is a [Microsoft help page](https://learn.microsoft.com/en-us/windows/wsl/install). GFortran version 9 or above is needed for successful installation and execution of PROCESS. Versions below GFortran-9 will be rejected by CMake by default since, while PROCESS might compile @@ -67,12 +66,6 @@ source env/bin/activate we recommend installing one so your other projects don't influence the dependencies of PROCESS and visa versa. -!!! Warning "Python version" - Only Python3.8 versions are supported in PROCESS. If you have installed a recent version of - Ubuntu such as v22, Python 3.10 may have been installed. If this is the case it is recommended - that you install Ubuntu20.04 which will have Python3.8 as its default. If not, this may lead - to build issues down the line. - Now compile the Fortran and create the Python interface. This is done using `cmake` to configure the build and then `make` to build it. Finally start the build process: diff --git a/mkdocs.yml b/mkdocs.yml index 182062db..9ec196ad 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -2,11 +2,11 @@ site_name: PROCESS docs_dir: documentation/proc-pages/ nav: - - Home: + - Getting Started: - About: index.md - Installation: - Introduction: installation/introduction.md - - Installation on Ubuntu/WSL: installation/installation-ubuntu.md + - Installation on Ubuntu/Windows: installation/installation-ubuntu.md - Installation using Docker: installation/installation-docker.md - Installation using Singularity: installation/installation-singularity.md - Visual Studio Code: installation/vs-code.md From 3cae9f86751cdc74c32e4358ba66326e9e4e0f10 Mon Sep 17 00:00:00 2001 From: Timothy Nunn Date: Wed, 16 Aug 2023 17:27:12 +0100 Subject: [PATCH 5/5] Add description of Actions jobs --- documentation/proc-pages/development/ci-guide.md | 16 ++++++++++++++-- 1 file changed, 14 insertions(+), 2 deletions(-) diff --git a/documentation/proc-pages/development/ci-guide.md b/documentation/proc-pages/development/ci-guide.md index 41ead6b8..8bd5aea3 100644 --- a/documentation/proc-pages/development/ci-guide.md +++ b/documentation/proc-pages/development/ci-guide.md @@ -1,6 +1,18 @@ # GitHub Actions -{==To be updated once migrated to GitHub.==} +Our GitHub actions Continuous Integration (CI) pipeline serves to ensure each branch and pull request conforms to our testing and style requirements. Due to the requirement of all stages on the built PROCESS artefacts and Docker image, all of our CI can currently be found in one workflow file: `process.yml`. A summary of each job within this workflow can be found below: -Provide table of actions and what they attempt to accomplish. \ No newline at end of file +| Name | Functionality | +| ---- | ------------- | +| docker | Checks if the `process-ci` Docker container is up-to-date and builds it if not. Only runs on the **main** branch. | +| make-py38 | Builds and archives the PROCESS build artefacts | +| unit-py38 | Installs PROCESS and runs the unit tests. The job will fail if any of the unit tests fail. | +| integration-py38 | Installs PROCESS and runs the integration tests. The job will fail if any of the integration tests fail. | +| regression-py38 | Installs PROCESS and runs the regression tests with a 0% tolerance. The job will fail if any of the regression tests fail. | +| regression-5-percent-py38 | Installs PROCESS and runs the regression tests with a 5% tolerance. The job will fail if any of the regression tests fail. | +| large-tokamak-py38 | Installs PROCESS and runs the `large-tokamak` input file, archiving the output MFILE. Only runs on the **main** branch. | +| flake8 | Runs the flake8 Python linter and fails if any lint errors occur. | +| black | Runs the black Python formatter and fails if any formatting issues are detected. | +| tracking | Collects MFILEs for input files of interest and creates a dashboard of changes in key values over time (one datapoint for each commit on main). | +| docs | Builds and deploys the documentation onto GitHub pages. | \ No newline at end of file