Merge branch 'dev' into 'main'

CI additions and README markdownify

See merge request dragon/5.1!1

4 files changed, 418 insertions, 0 deletions

diff --git a/.nea/.gitlab-ci.yml b/.nea/.gitlab-ci.yml
new file mode 100644
index 0000000..45b1787
--- /dev/null
+++ b/.nea/.gitlab-ci.yml
@@ -0,0 +1,214 @@
+variables:
+  GIT_STRATEGY: clone
+  GIT_SUBMODULE_STRATEGY: recursive
+  GET_SOURCES_ATTEMPTS: 3
+  DOCKER_BASE_REPO: docker.oecd-nea.org
+
+
+stages:
+  - build
+  - test
+  - deploy
+#  - release
+
+default:
+  tags:
+    - podman
+
+.release_rules: &RELEASE_RULES
+  rules:
+    # Run this job only when a tag is created
+    - if: '$CI_COMMIT_TAG =~ /v+\d+\.\d+\.\d+/'
+
+.apt_setup: &APT_SETUP |
+  sed -i 's|http://archive.ubuntu.com|http://debmirror.nea.fr:9999/archive.ubuntu.com|g'  /etc/apt/sources.list
+  sed -i 's|http://security.ubuntu.com|http://debmirror.nea.fr:9999/security.ubuntu.com|g' /etc/apt/sources.list
+  apt-get update -o Acquire::ForceIPv4=true
+
+.apt2_setup: &APT2_SETUP |
+  sed -i 's|http://archive.ubuntu.com|http://debmirror.nea.fr:9999/archive.ubuntu.com|g'  /etc/apt/sources.list.d/ubuntu.sources
+  sed -i 's|http://security.ubuntu.com|http://debmirror.nea.fr:9999/security.ubuntu.com|g' /etc/apt/sources.list.d/ubuntu.sources
+  apt-get update -o Acquire::ForceIPv4=true
+
+.apt_deb_setup: &APT_DEB_SETUP |
+  sed -i 's|http://deb.debian.org|http://debmirror.nea.fr:9999/deb.debian.org|g'  /etc/apt/sources.list
+  apt-get update -o Acquire::ForceIPv4=true
+
+.apt_deb2_setup: &APT_DEB2_SETUP |
+  sed -i 's|http://deb.debian.org|http://debmirror.nea.fr:9999/deb.debian.org|g'  /etc/apt/sources.list.d/debian.sources
+  apt-get update -o Acquire::ForceIPv4=true
+
+.build_with_hdf5: &BUILD_WITH_HDF5 |
+  cd Donjon
+  make hdf5=1 openmp=1
+  cd ../PyGan
+  make hdf5=1 openmp=1
+
+
+.build_linux_template:
+  stage: build
+  before_script:
+    - *APT_SETUP
+    - |
+      env DEBIAN_FRONTEND=noninteractive apt-get install -yq --no-install-recommends \
+        make gfortran python3 python3-dev python3-numpy python3-distutils libhdf5-serial-dev libomp-dev
+  after_script:
+    - mkdir 5.1
+    - mv Donjon 5.1/
+    - mv Dragon 5.1/
+    - mv Ganlib 5.1/
+    - mv PyGan 5.1/
+    - mv Trivac 5.1/
+    - mv script 5.1/
+  artifacts:
+    paths:
+    - 5.1/**/rdonjon
+    - 5.1/**/rdragon
+    - 5.1/**/rganlib
+    - 5.1/**/rpython
+    - 5.1/**/rtrivac
+    - 5.1/**/bin
+    - 5.1/**/lib
+    - 5.1/**/data
+    - 5.1/PyGan/Makefile
+    - 5.1/script
+    expire_in: 1 day
+    when: always
+
+build_ubuntu20:
+  extends: .build_linux_template
+  image: docker.oecd-nea.org/dragon/5.1/ubuntu:20.04
+  script:
+    - export HDF5_INC=/usr/include/hdf5/serial
+    - export HDF5_API=/usr/lib/x86_64-linux-gnu/hdf5/serial
+    - export FORTRANPATH=/usr/lib/gcc/x86_64-linux-gnu/9
+    - *BUILD_WITH_HDF5
+
+build_ubuntu22:
+  extends: .build_linux_template
+  image: docker.oecd-nea.org/dragon/5.1/ubuntu:22.04
+  script:
+    - export HDF5_INC=/usr/include/hdf5/serial
+    - export HDF5_API=/usr/lib/x86_64-linux-gnu/hdf5/serial
+    - export FORTRANPATH=/usr/lib/gcc/x86_64-linux-gnu/11
+    - *BUILD_WITH_HDF5
+
+# uses python 3.12
+build_ubuntu24:
+  extends: .build_linux_template
+  image: docker.oecd-nea.org/dragon/5.1/ubuntu:24.04
+  before_script:
+    - *APT2_SETUP
+    - |
+      env DEBIAN_FRONTEND=noninteractive apt-get install -yq --no-install-recommends \
+        make gfortran python3 python3-dev python3-numpy python3-setuptools libhdf5-serial-dev libomp-dev
+  script:
+    - export HDF5_INC=/usr/include/hdf5/serial
+    - export HDF5_API=/usr/lib/x86_64-linux-gnu/hdf5/serial
+    - export FORTRANPATH=/usr/lib/gcc/x86_64-linux-gnu/13
+    - *BUILD_WITH_HDF5
+
+.test_template:
+  stage: test
+  image: docker.oecd-nea.org/dragon/5.1/ubuntu:22.04
+  variables:
+    GIT_STRATEGY: none
+  needs:
+  - job: build_ubuntu22
+    artifacts: true
+  before_script:
+    - *APT_SETUP
+    # Note that the binaries require gfortran (a matching version) at runtime
+    - |
+      env DEBIAN_FRONTEND=noninteractive apt-get install -yq --no-install-recommends \
+        python3 python3-numpy python3-distutils python3-matplotlib libomp-dev \
+        make gfortran wget libhdf5-serial-dev libomp-dev
+    - export HDF5_INC=/usr/include/hdf5/serial
+    - export HDF5_API=/usr/lib/x86_64-linux-gnu/hdf5/serial
+    - export DRAGON_HOME=$CI_PROJECT_DIR/dragon
+    - export DRAGON_LIB_DIR=$DRAGON_HOME/libraries/l_endian
+    - export DRAGON_CODE_DIR=$DRAGON_HOME/5.1
+    - mkdir -p ${DRAGON_LIB_DIR}
+    - mv 5.1 ${DRAGON_HOME}/
+
+test_ganlib_ubuntu22:
+  extends: .test_template
+  script:
+    - cd ${DRAGON_CODE_DIR}/Ganlib
+    - ./rganlib -q testgan1.x2m
+    - ./rganlib -q testgan2.x2m
+    - ./rganlib -q testgan3.x2m
+    - ./rganlib -q testgan4.x2m
+
+
+test_dragon_ubuntu22:
+  extends: .test_template
+  script:
+    - cd ${DRAGON_LIB_DIR}
+    # get JEF 2.2 for testing
+    - wget --no-check-certificate https://git.oecd-nea.org/dragon/libraries/-/raw/main/l_endian/draglibJef2p2.gz
+    # get JEF 3.1.1 for OpenMP testing
+    - wget --no-check-certificate https://git.oecd-nea.org/dragon/libraries/-/raw/main/l_endian/draglibJeff3p1p1SHEM295_v5p1.gz
+    - cd ${DRAGON_CODE_DIR}/Dragon
+    - ./rdragon -q salmacro.x2m
+    - ./rdragon -q tdraglib.x2m
+    - ./rdragon -q pincell_mpo.x2m
+    - ./rdragon -q -p 8 uo2_295_kec1_openMP.x2m
+
+
+test_donjon_ubuntu22:
+  extends: .test_template
+  script:
+    - cd ${DRAGON_LIB_DIR}
+    # get JEF 2.2 for testing
+    - wget --no-check-certificate https://git.oecd-nea.org/dragon/libraries/-/raw/main/l_endian/draglibJef2p2Apolib99_v5p1.gz
+    - cd ${DRAGON_CODE_DIR}/Donjon
+    - ./rdonjon -q rep900_msap.x2m
+    - ./rdonjon -q Reflector_beavrs_DF-RT_Jef2p2Apolib99.x2m
+    - ./rdonjon -q Fessenheim.x2m
+
+
+test_pygan_ubuntu22:
+  extends: .test_template
+  script:
+    - cd ${DRAGON_LIB_DIR}
+    # get JEF 2.2 for testing
+    - wget --no-check-certificate https://git.oecd-nea.org/dragon/libraries/-/raw/main/l_endian/draglibJeff3p1p1SHEM295_v5p1.gz
+    - cd ${DRAGON_CODE_DIR}/PyGan
+    - make tests hdf5=1 openmp=1
+
+docker_ubuntu24_slim:
+  stage: deploy
+  image:
+    # recommended image for building with kaniko
+    # https://docs.gitlab.com/ee/ci/docker/using_kaniko.html#building-a-docker-image-with-kaniko
+    name: ${DOCKER_BASE_REPO}/dragon/5.1/kaniko:v1.23.0-debug
+    entrypoint: [""]
+  needs:
+  - job: test_ganlib_ubuntu22
+    artifacts: false
+  - job: test_dragon_ubuntu22
+    artifacts: false
+  - job: test_donjon_ubuntu22
+    artifacts: false
+  - job: test_pygan_ubuntu22
+    artifacts: false
+  script:
+    - |
+      cat <<EOF > /kaniko/.docker/config.json
+      {
+        "auths": {
+          "docker.oecd-nea.org": {
+            "username": "$CI_DEPLOY_USER",
+            "password": "$CI_DEPLOY_PASSWORD"
+          }
+        }
+      }
+      EOF
+    # TODO: change the hardcoded docker tag to use a git tag
+    - >
+      /kaniko/executor
+      --context "${CI_PROJECT_DIR}"
+      --dockerfile "${CI_PROJECT_DIR}/.nea/docker/Dockerfile.slim"
+      --destination "${DOCKER_BASE_REPO}/${CI_PROJECT_NAMESPACE}/${CI_PROJECT_NAME}:v5.1.0-slim"
+      --single-snapshot --cache=false
diff --git a/.nea/docker/Dockerfile.slim b/.nea/docker/Dockerfile.slim
new file mode 100644
index 0000000..ebfae15
--- /dev/null
+++ b/.nea/docker/Dockerfile.slim
@@ -0,0 +1,51 @@
+FROM docker.oecd-nea.org/dragon/5.1/ubuntu:24.04
+
+COPY ./.nea/docker/entrypoint.sh /entrypoint.sh
+
+ENV DRAGON_HOME=/dragon
+ENV DRAGON_CODE_DIR=$DRAGON_HOME/5.1
+
+ENV HDF5_INC=/usr/include/hdf5/serial
+ENV HDF5_API=/usr/lib/x86_64-linux-gnu/hdf5/serial
+ENV FORTRANPATH=/usr/lib/gcc/x86_64-linux-gnu/13
+
+RUN AG="env DEBIAN_FRONTEND=noninteractive apt-get -yq" && \
+    ln -snf /usr/share/zoneinfo/$TZ /etc/localtime && echo $TZ > /etc/timezone && \
+    # NEA special for our internal apt mirrors
+    cp /etc/apt/sources.list.d/ubuntu.sources /ubuntu.sources.original && \
+    sed -i 's|http://archive.ubuntu.com|http://debmirror.nea.fr:9999/archive.ubuntu.com|g'  /etc/apt/sources.list.d/ubuntu.sources && \
+    sed -i 's|http://security.ubuntu.com|http://debmirror.nea.fr:9999/security.ubuntu.com|g' /etc/apt/sources.list.d/ubuntu.sources && \
+    $AG update && \
+    $AG upgrade --no-install-recommends && \
+    $AG install --no-install-recommends openssl git git-lfs wget curl make gfortran python3 python3-dev python3-numpy python3-setuptools libhdf5-serial-dev libomp-dev && \
+    $AG autoremove && \
+    $AG autoclean && \
+    $AG clean && \
+    # Put the normal apt sources back after installing deps
+    mv /ubuntu.sources.original /etc/apt/sources.list.d/ubuntu.sources && \
+    openssl s_client -showcerts -connect git.oecd-nea.org:443 < /dev/null | sed -ne '/-BEGIN CERTIFICATE-/,/-END CERTIFICATE-/p' > /ca.crt && \
+    git config --global http.sslCAInfo /ca.crt && \
+    mkdir ${DRAGON_HOME} && cd ${DRAGON_HOME} && \
+    git clone https://git.oecd-nea.org/dragon/5.1 && \
+    cd ${DRAGON_CODE_DIR} && \
+    # to keep it slim we can remove the .git folder, and the data folders
+    rm -rf .git Donjon/data Dragon/data Trivac/data doc && \
+    cd ${DRAGON_CODE_DIR}/Donjon && \
+    make hdf5=1 openmp=1 && \
+    # this doesn't remove the binaries, just the *.o and the *.a and *.mod files
+    make clean && \
+    cd ../PyGan && \
+    make hdf5=1 openmp=1 && \
+    # this doesn't remove the binaries, just the *.o and the *.a and *.mod files
+    make clean && \
+    cd ../Ganlib && \
+    ./rganlib -q testgan1.x2m && \
+    ./rganlib -q testgan2.x2m && \
+    ./rganlib -q testgan3.x2m && \
+    chmod +x /entrypoint.sh
+
+# ENV DRAGON_LIB_DIR=$DRAGON_HOME/libraries/l_endian
+
+WORKDIR /dragon/5.1/
+
+ENTRYPOINT [ "/entrypoint.sh" ]
diff --git a/.nea/docker/entrypoint.sh b/.nea/docker/entrypoint.sh
new file mode 100644
index 0000000..416fac5
--- /dev/null
+++ b/.nea/docker/entrypoint.sh
@@ -0,0 +1,22 @@
+#!/bin/bash
+
+RED='\033[1;91m'
+GREEN='\033[1;92m'
+BLUE='\033[1;94m'
+NC='\033[0m'
+
+
+tryit(){
+    "$@"
+    local status=$?
+    if [ $status -ne 0 ]; then
+        echo -e "${RED}Error occurred with $1 ${NC}" >&2
+        exit $status
+    fi
+    return $status
+}
+
+
+# run donjon as the default entrypoint, as donjon can run dragon
+cd Donjon
+tryit ./rdonjon $@
diff --git a/README.md b/README.md
new file mode 100644
index 0000000..fdc2bc6
--- /dev/null
+++ b/README.md
@@ -0,0 +1,131 @@
+# Dragon v5.1
+
+This is the repository for the Dragon code.
+Version5 is a 64-bit clean distribution of the reactor physics codes developed at Polytechnique Montréal.
+
+
+## License
+
+The license is [GNU General Public License](http://www.gnu.org/licenses/lgpl.html).
+
+
+## Documentation
+
+For comprehensive documentation please refer to the [Merlin site](http://merlin.polymtl.ca/version5.htm).
+Additionally, you can build the documentation yourself using Latex, see the subdirectory [doc](./doc) for more.
+
+
+## Dependencies
+
+In order to compile and run Dragon you must have a Fortran compiler (2003 or later standard) and Python3.
+
+Optional dependencies are [OpenMP](https://www.openmp.org/resources/openmp-compilers-tools/) and [HDF5](https://www.hdfgroup.org/download-hdf5/).
+
+
+## Installation
+
+Dragon is supported on Linux and Unix machines. For Windows users we recommend using the Windows Subsystem for Linux (WSL).
+
+The installation is based on `make`, particularly `gmake` for Unix systems.
+
+Please go to the [Merlin site](http://merlin.polymtl.ca/version5.htm) for comprehensive installation instructions.
+
+
+## Run the code
+
+A minimum set of cross section files can be found on the [Merlin site](http://merlin.polymtl.ca/version5.htm), for more extensive work download the required files from the NEA data repository [here](../libraries/).
+
+**Please note that you must preserve the directory structure**. This can be achieved by doing the following:
+
+If you want all data (note the disk space ~10GB) follow these steps:
+
+```bash
+mkdir dragon
+cd dragon
+git clone https://git.oecd-nea.org/dragon/5.1
+git clone https://git.oecd-nea.org/dragon/libraries
+```
+
+For those with limited disk space, you will need to specify which data files you want.
+
+For example:
+
+```bash
+mkdir dragon
+cd dragon
+git clone https://git.oecd-nea.org/dragon/5.1
+GIT_LFS_SKIP_SMUDGE=1 git clone https://git.oecd-nea.org/dragon/libraries
+cd libraries
+# For JEFF 3.1.1 SHEM 361 use the following
+git lfs pull -I l_endian/draglibJeff3p1p1SHEM361_v5p1.gz
+```
+
+## Docker
+
+If you don't want to compile the code on your machine, we offer pre-built Docker images for you to use to bypass this, and you just require docker installed on your machine.
+
+For Windows users you can use [Docker Desktop](https://docs.docker.com/desktop/setup/install/windows-install/) (if you don't have WSL).
+
+
+### Get image
+
+To get a docker images (Ubuntu 22.04) with PHITS already setup and paths set, you may pull this image via:
+
+```bash
+docker pull docker.oecd-nea.org/dragon/5.1:v5.1.0-slim
+```
+
+### Running image
+
+A template command is provided below and you only need to change the text in the `<>` sections, specific to your installation. Note that the paths on the right hand side of the colon (:) should be to your **host** machine, the paths on the right hand side do not need to be changed and match to paths inside the docker container.
+
+
+```bash
+docker run -v <my_path_to_libs>:/dragon/libraries:ro
+           -v <my_path_to_inputs>:/dragon/5.1/Donjon/data/:ro
+           -v <my_path_to_outputs>:/dragon/5.1/Donjon/Linux_x86_64
+           docker.oecd-nea.org/dragon/5.1:v5.1.0-slim
+           "-q <my_input_file.x2m>"
+```
+
+You therefore need 4 parameters to set:
+
+1. `<my_path_to_libs>` should point to the directory containing your Dragon nuclear data library file (`*.gz`).
+
+2. `<my_path_to_inputs>` should point to a directory on your host machine containing the input data files (`*.x2m` and other related files). This should be a different directory to number 1.
+
+3. `<my_path_to_outputs>` should point to a directory on your host machine which will be used to keep the output files from each code run i.e (including the `*.result` file). This should be different to 1. and 2.
+
+4. `<my_input_file.x2m>` should be the name of the input data file which should exist in directory number 2.
+
+
+An example of this is given below:
+
+
+```bash
+docker run -v /home/user/dragon/libraries:/dragon/libraries:ro
+           -v /home/user/dragon/inputs:/dragon/5.1/Donjon/data/:ro
+           -v /home/user/dragon/outputs:/dragon/5.1/Donjon/Linux_x86_64
+           docker.oecd-nea.org/dragon/5.1:v5.1.0-slim
+           "-q VanDerGucht.x2m"
+```
+
+
+given the following directory contents:
+
+```bash
+$ls /home/user/dragon/libraries
+README.md  ascii  hdf5  l_endian  pynjoy
+```
+
+```bash
+$ls /home/user/dragon/inputs
+VanDerGucht.access  VanDerGucht.x2m  VanDerGucht_proc
+```
+
+will give me the following outputs
+
+```bash
+$ls /home/user/dragon/outputs
+VanDerGucht.result
+```
\ No newline at end of file