Merge pull request #53 from VERITAS-Observatory/towncrier

Typos fixes; addition of towncrier for changelogs.

Author: GernotMaier

.github/workflows/CI.yml

@@ -0,0 +1,41 @@
+---
+name: CI
+
+on:
+  workflow_dispatch:
+  pull_request:
+    types: [opened, synchronize]
+  schedule:
+    - cron: "0 0 * * *"
+
+jobs:
+
+  linting:
+    runs-on: ubuntu-latest
+    defaults:
+      run:
+        shell: bash -leo pipefail {0}
+
+    permissions:
+      contents: read
+      packages: read
+      statuses: write
+
+    steps:
+      - name: checkout
+        uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+
+      - name: Check whether the citation metadata from CITATION.cff is valid
+        uses: citation-file-format/cffconvert-github-action@2.0.0
+        with:
+          args: "--validate"
+
+      - name: Pre-commit
+        run: |
+          pip install pre-commit
+          pre-commit run --all-files

.pre-commit-config.yaml

@@ -1,18 +1,18 @@
 repos:
   # https://pycqa.github.io/isort/docs/configuration/black_compatibility.html#integration-with-pre-commit
   - repo: https://github.com/pycqa/isort
-    rev: 5.13.2
+    rev: 6.0.1
     hooks:
       - id: isort
         args: ["--profile", "black", "--filter-files"]
   - repo: https://github.com/psf/black
-    rev: 24.10.0
+    rev: 25.1.0
     hooks:
       - id: black
         args: ["--line-length=100"]
   # https://black.readthedocs.io/en/stable/guides/using_black_with_other_tools.html?highlight=other%20tools#flake8
   - repo: https://github.com/PyCQA/flake8
-    rev: 7.1.1
+    rev: 7.2.0
     hooks:
       - id: flake8
         args: ["--max-line-length=100"]
@@ -24,7 +24,7 @@ repos:
       - id: end-of-file-fixer
   # codespell
   - repo: https://github.com/codespell-project/codespell
-    rev: v2.3.0
+    rev: v2.4.1
     hooks:
       - id: codespell
-        args: ["--ignore-words-list=Gaus,highE",]
+        args: ["--ignore-words-list=Gaus,highE,MIROR,ARRANG",]

CHANGELOG.md

@@ -0,0 +1,10 @@
+# CHANGELOG
+
+All notable changes to the VTS-SimPipe project will be documented in this file.
+Changes for upcoming releases can be found in the [docs/changes](docs/changes) directory.
+Note that changes before release v2.2.0 are not documented here, but can be found in the
+[GitHub repository](https://github.com/VERITAS-Observatory/VTS-SimPipe/releases).
+
+This changelog is generated using [Towncrier](https://towncrier.readthedocs.io/).
+
+<!-- towncrier release notes start -->

CITATION.cff

@@ -4,9 +4,9 @@ cff-version: 1.2.0
 message: If you use this software, please cite it using these metadata.
 title: "VTS-SimPipe: simulation tools for the VERITAS observatory"
 doi: 10.5281/zenodo.10541349
-version: 2.0.0
+version: 2.1.1
 type: software
-date-released: 2024-03-12
+date-released: 2024-10-17
 keywords:
 - "gamma-ray astronomy"
 - "astronomy software"

LICENSE

@@ -1,6 +1,6 @@
 BSD 3-Clause License
 
-Copyright (c) 2024, Gernot Maier, VERITAS Collaboration
+Copyright (c) 2024, 2025 Gernot Maier, VERITAS Collaboration
 
 Redistribution and use in source and binary forms, with or without
 modification, are permitted provided that the following conditions are met:

README.md

@@ -34,13 +34,13 @@ No compilation of any of the package is required.
 # clone repository
 git clone https://github.com/VERITAS-Observatory/VTS-SimPipe.git
 cd VTS-SimPipe
-# prepare log files and directories
+# configure environment variables
 cp env_setup_template.sh env_setup.sh
-# edit env_setup.sh to your needs
-# pull all container images from the registry
+# edit env_setup.sh to specify local paths and container runtime (docker/apptainer)
+# download pre-built container images from registry
 cd scripts && ./pull.sh
-# prepare your configuration (e.g. zenith angle, number of events, etc.)
-# see example in config/config_ATM61_template.dat
+# configure simulation parameters (zenith angle, primary particle type, energy range, etc.)
+# see template configuration in config/config_ATM61_template.dat
 # prepare production
 cd scripts
 ./prepare_all_production_steps.sh ../config/config_ATM61_template.dat
@@ -58,7 +58,7 @@ cd scripts
 
 ## Software packages
 
-Following software packages are used by the simulation pipeline and installed in the docker images:
+Following software packages are integrated into the simulation chain via containerized environments:
 
 - [CORSIKA](https://web.ikp.kit.edu/corsika/) for air shower and Cherenkov photon generation
 - [corsikaIOreader](https://github.com/GernotMaier/corsikaIOreader/) for file format conversion and Cherenkov photon absorption and scattering.
@@ -82,7 +82,9 @@ Note that the CI on github will build three different containers for CORSIKA:
 
 1. [vts-simpipe-corsika](https://github.com/VERITAS-Observatory/VTS-SimPipe/pkgs/container/vtsimpipe-corsika) based on [docker/Dockerfile-corsika](docker/Dockerfile-corsika) with the standard CORSIKA software (as used in VERITAS for productions in the past); configuration and compilation using the `coconut` tools.
 2. [vts-simpipe-corsika-noopt](https://github.com/VERITAS-Observatory/VTS-SimPipe/pkgs/container/vtsimpipe-corsika-noopt) based on [docker/Dockerfile-corsika-noopt](docker/Dockerfile-corsika-noopt) using CORSIKA 7.7500 used compile coptions as outlined in the Docker file (in contrast to 1., uses the `O3` flags, but it does not use the vectorization code of 3.)
-3. [vts-simpipe-corsika-ax2](https://github.com/VERITAS-Observatory/VTS-SimPipe/pkgs/container/vtsimpipe-corsika-ax2) based on [docker/Dockerfile-corsika-ax2](docker/Dockerfile-corsika-ax2) using CORSIKA 7.7500 with minor updates to the Bernlohr package (this is the package used for the generation and propagation of Cherenkov photons). A patch is applied to the Cherenkov photon code to allow to use vector instructions and improve runtime performance, see discussions in L. Arrabito et al, *Optimizing Cherenkov photons generation and propagation in CORSIKA for CTA Monte-Carlo simulations*, [arXiv.2006.14927](https://arxiv.org/abs/2006.14927)
+3. [vts-simpipe-corsika-ax2](https://github.com/VERITAS-Observatory/VTS-SimPipe/pkgs/container/vtsimpipe-corsika-ax2) based on [docker/Dockerfile-corsika-ax2](docker/Dockerfile-corsika-ax2) using CORSIKA 7.7500 with minor updates to the Bernlohr package (this is the package used for the generation and propagation of Cherenkov photons). A patch is applied to the Cherenkov photon code to allow to use vector instructions and improve runtime performance, see discussions in L. Arrabito et al, *Optimizing Cherenkov photons generation and propagation in CORSIKA for CTAO Monte-Carlo simulations*, [arXiv.2006.14927](https://arxiv.org/abs/2006.14927)
+
+The use of optimized CORISKA containers requires access to x86_64 architecture with SSE4/AVX2/AVX512 support.
 
 To build the CORSIKA container (similar for all):
 
@@ -298,17 +300,17 @@ SLANT 1
 
 ## Optimization of CORSIKA
 
-The CTA simulation pipeline uses vector-optimization of the Cherenkov photon generation and propagation code in CORSIKA with notable performance improvements, see the discussion in L. Arrabito et al, *Optimizing Cherenkov photons generation and propagation in CORSIKA for CTA Monte-Carlo simulations*, [arXiv.2006.14927](https://arxiv.org/abs/2006.14927).
+The CTAO simulation pipeline uses vector-optimization of the Cherenkov photon generation and propagation code in CORSIKA with notable performance improvements, see the discussion in L. Arrabito et al, *Optimizing Cherenkov photons generation and propagation in CORSIKA for CTAO Monte-Carlo simulations*, [arXiv.2006.14927](https://arxiv.org/abs/2006.14927).
 
-VTS-SimPipe is able to use the same optimized CORSIKA, thanks to for Luisa Arrabito for providing it. Below a comparison of the runtime of the optimized and non-optimized CORSIKA for the same simulation setup:
+VTS-SimPipe is able to use the same optimized CORSIKA, thanks to for L. Arrabito for providing it. Below a comparison of the runtime of the optimized and non-optimized CORSIKA for the same simulation setup:
 
 | Type | CORSIKA version | IACT/ATMO version | Remarks | Run Time [s] / event | Ratio to VTS-SimPipe |
 | -------- | -------- | -------- | -------- | -------- | -------- |
 | VTS-SimPipe | 7.7500 | 1.66 (2023-02-03) | default coconut build (see remarks below); [container](https://github.com/VERITAS-Observatory/VTS-SimPipe/pkgs/container/vtsimpipe-corsika/177291090?tag=1.1.0), [docker](https://github.com/VERITAS-Observatory/VTS-SimPipe/blob/main/docker/Dockerfile-corsika); SLANT option; no VIEWCONE | 33.6 | 1. |
 | VTS-noopt | 7.7500 | 1.66 (2023-02-03) | no specific optimization (O3; see remarks below); [container](https://github.com/VERITAS-Observatory/VTS-SimPipe/pkgs/container/vtsimpipe-corsika-noopt/182679178?tag=20240223-115829) [docker (noopt arg)](https://github.com/VERITAS-Observatory/VTS-SimPipe/blob/main/docker/Dockerfile-corsika-optimized) | 17.2 | 2.0 |
 | VTS-avx2 | 7.7500 | 1.66 (2023-02-03) | avx2 [container](https://github.com/VERITAS-Observatory/VTS-SimPipe/pkgs/container/vtsimpipe-corsika-avx2/182679269?tag=20240223-115831), [docker (avx2 arg)](https://github.com/VERITAS-Observatory/VTS-SimPipe/blob/main/docker/Dockerfile-corsika-optimized) | 13.42 | 2.5 |
 | VTS-sse4 | 7.7500 | 1.66 (2023-02-03) | sse4 [container](https://github.com/VERITAS-Observatory/VTS-SimPipe/pkgs/container/vtsimpipe-corsika-sse4/182679278?tag=20240223-115831), [docker (sse4 arg)](https://github.com/VERITAS-Observatory/VTS-SimPipe/blob/main/docker/Dockerfile-corsika-optimized) | 12.5 | 2.7 |
-| VTS-avx512f | 7.7500 | 1.66 (2023-02-03) | avx51f [container](https://github.com/VERITAS-Observatory/VTS-SimPipe/pkgs/container/vtsimpipe-corsika-avx512/182679206?tag=20240223-115833), [docker (avx512 arg)](https://github.com/VERITAS-Observatory/VTS-SimPipe/blob/main/docker/Dockerfile-corsika-optimized) | 13.7 | 2.4 |
+| VTS-avx512f | 7.7500 | 1.66 (2023-02-03) | avx512f [container](https://github.com/VERITAS-Observatory/VTS-SimPipe/pkgs/container/vtsimpipe-corsika-avx512/182679206?tag=20240223-115833), [docker (avx512 arg)](https://github.com/VERITAS-Observatory/VTS-SimPipe/blob/main/docker/Dockerfile-corsika-optimized) | 13.7 | 2.4 |
 
 ### Remarks
 

config/GROPTICS/Upgrade_20120827_v420_3.cfg

@@ -217,7 +217,7 @@ v) set low gain multiplier according to low gain analysis results from 200712 (n
 
 vi) set CFD threshold to 50 mV
 
-vii) new mirror reflectivities according to measurments on 2007/11/26 (VBC elog 4395)
+vii) new mirror reflectivities according to measurements on 2007/11/26 (VBC elog 4395)
 
 ====================================================================================================
 
@@ -279,14 +279,14 @@ v)   G.Maier and J.Holder, Simulation of T1, VERITAS internal note (see T1 ELOG
 
 * VERSN 4.2.0
 
-Numbre of telescope (NBRTL)
+Number of telescope (NBRTL)
 * NBRTL 4
 
 Telescope location in the field (TLLOC) the parameters are:
    -the telescope identification number
-   -the X (oriented towrd east) location cordinate in meters.
-   -the Y (oriented toward north)location cordinate in meters.
-   -the Z (oriented toward up) location cordinate in meters.
+   -the X (oriented toward east) location coordinate in meters.
+   -the Y (oriented toward north)location coordinate in meters.
+   -the Z (oriented toward up) location coordinate in meters.
    -the telescope rotation offset in meters.
 	The telescope rotation offset is the distance below the focal point
         of the mirror along the optical axis about which the telescope
@@ -309,7 +309,7 @@ The simulation parameter record SIMUL contains
 	for the simulation calculation to be carried with.)
    -the number of samples over which the simulation produces the signals
    -the number of samples over which the noise database is produced
-(GM) should be 20000, but noise calculation currently extremly slow
+(GM) should be 20000, but noise calculation currently extremely slow
 * SIMUL 2.0 100 4000
 
 
@@ -330,7 +330,7 @@ Mirror design (MIROR). The parameters are
 Mirror reflectivity curve (RFCRV). The flag is followed by
    -the the reflectivity curve identification index
    -the number of points given on the quantum efficiency spectral curve.
-This is followed by a serie of
+This is followed by a series of
    -wave length(in nano-meter)
    -reflectivity(fraction of unity)
 
@@ -413,7 +413,7 @@ Mirror element (MIREL) characterisation. For each we have
    -the curvature radius
    -the x position of the element on the dish (in meters)
    -the y position of the element on the dish (in meters)
-   -the maximum mis-alignement in degrees
+   -the maximum misalignment in degrees
    -the maximum blure radius in degrees
    -the degradation factor (1.0=perfect 0.0=missing)
    -the reflectivity curve identifier

docker/Dockerfile-corsika-optimized

@@ -36,7 +36,7 @@ RUN make clean && rm -f */*.a lib/*/*.a && \
         F77="${GCC_PATH}/gfortran -L/lib64/" \
         CFLAGS="-DCERENKOPT -DVLIBM -std=c99 -O3 -m${AVX_FLAG} -DVECTOR_SIZE=8 -DVECTOR_LENGTH=8" \
         CXXFLAGS="-DCERENKOPT -DVLIBM -std=c99 -O3 -m${AVX_FLAG} -DVECTOR_SIZE=8 -DVECTOR_LENGTH=8" \
-        # Note: different to CTA - no change in avx options for Fortran
+        # Note: different to CTAO - no change in avx options for Fortran
         # FFLAGS="-ffixed-line-length-132 -fno-automatic -frecord-marker=4 -std=legacy -DCERENKOPT -DVLIBM -std=c99 -O3 -m${AVX_FLAG} -DVECTOR_SIZE=8 -DVECTOR_LENGTH=8" \
         FFLAGS="-ffixed-line-length-132 -fno-automatic -frecord-marker=4 -std=legacy -std=c99 -O3 -mavx2" \
         install; \