From 2d55cce5900efed08afc47d14b0f42915c394f91 Mon Sep 17 00:00:00 2001 From: Luke Polson Date: Mon, 13 Nov 2023 15:52:59 -0800 Subject: [PATCH] Initial commit --- .clang-format | 37 +++++ .devcontainer/Dockerfile | 98 +++++++++++++ .devcontainer/devcontainer.bashrc | 11 ++ .devcontainer/devcontainer.json | 126 ++++++++++++++++ .gitattributes | 4 + .github/PULL_REQUEST_TEMPLATE.md | 23 +++ .../actions/configure-environment/action.yml | 16 ++ .github/workflows/ci.yml | 58 ++++++++ .gitignore | 7 + .gitmodules | 3 + CONTRIBUTING.md | 137 ++++++++++++++++++ LICENSE.txt | 53 +++++++ NOTICE.txt | 11 ++ PETSIRD | 1 + README.md | 50 +++++++ SUPPORT.md | 13 ++ cpp/CMakeLists.txt | 17 +++ cpp/README.md | 15 ++ environment.yml | 20 +++ python/README.md | 6 + python/start.py | 5 + 21 files changed, 711 insertions(+) create mode 100644 .clang-format create mode 100644 .devcontainer/Dockerfile create mode 100644 .devcontainer/devcontainer.bashrc create mode 100644 .devcontainer/devcontainer.json create mode 100644 .gitattributes create mode 100644 .github/PULL_REQUEST_TEMPLATE.md create mode 100644 .github/actions/configure-environment/action.yml create mode 100644 .github/workflows/ci.yml create mode 100644 .gitignore create mode 100644 .gitmodules create mode 100644 CONTRIBUTING.md create mode 100644 LICENSE.txt create mode 100644 NOTICE.txt create mode 160000 PETSIRD create mode 100644 README.md create mode 100644 SUPPORT.md create mode 100644 cpp/CMakeLists.txt create mode 100644 cpp/README.md create mode 100644 environment.yml create mode 100644 python/README.md create mode 100644 python/start.py diff --git a/.clang-format b/.clang-format new file mode 100644 index 0000000..d2e3998 --- /dev/null +++ b/.clang-format @@ -0,0 +1,37 @@ +--- +BasedOnStyle : GNU +--- +Language : Cpp +FixNamespaceComments: true +AlwaysBreakAfterReturnType: TopLevelDefinitions +AlwaysBreakTemplateDeclarations: true +# Set BraceWrapping. Most of these are GNU but not all. +# Sadly, apparently we need to give all of them though, as when using BreakBeforeBraces=GNU, +# customisations get ignored. +BreakBeforeBraces: Custom +BraceWrapping: + AfterClass: true + AfterControlStatement: true + AfterEnum: true + AfterFunction: true + AfterNamespace: true + AfterObjCDeclaration: true + AfterStruct: true + AfterUnion: true + AfterExternBlock: true + BeforeCatch: true + BeforeElse: true + IndentBraces: true + SplitEmptyFunction: false + SplitEmptyRecord: true + SplitEmptyNamespace: true + # non-standard GNU + SplitEmptyFunction: false +ColumnLimit: 130 +IndentPPDirectives: AfterHash +PointerAlignment: Left +SortIncludes: false +SortUsingDeclarations: false +SpaceBeforeParens: ControlStatements +Standard: Cpp11 +... diff --git a/.devcontainer/Dockerfile b/.devcontainer/Dockerfile new file mode 100644 index 0000000..4e0fbee --- /dev/null +++ b/.devcontainer/Dockerfile @@ -0,0 +1,98 @@ +ARG DEVCONTAINER_BASE=mcr.microsoft.com/devcontainers/base:1.0.9-ubuntu-22.04 + +######################################################### +# file-normalizer stage +# In order to use BuildKit remote caching, input files must have +# not only the right content hash, but also the right permissions. +# Git only tracks whether the owner can execute a file. +# Here we bring in all files that are going to be used in the +# subsequent stage and normalize the permissions. +######################################################### + +FROM --platform=linux/amd64 ${DEVCONTAINER_BASE} as file-normalizer + +COPY environment.yml \ + .devcontainer/devcontainer.bashrc \ + /data/ + +RUN chmod -R 555 /data/ + +######################################################### +# devcontainer stage +# Installs all dependencies and tooling for development. +######################################################### + +FROM --platform=linux/amd64 ${DEVCONTAINER_BASE} AS devcontainer + +# Install needed packages and setup non-root user. +ARG USERNAME="vscode" +ARG USER_UID=1000 +ARG USER_GID=$USER_UID +ARG CONDA_GID=900 +ARG CONDA_ENVIRONMENT_NAME=prd +ARG VSCODE_DEV_CONTAINERS_SCRIPT_LIBRARY_VERSION=v0.229.0 + +RUN apt-get update && apt-get install -y \ + libc6-dbg \ + && rm -rf /var/lib/apt/lists/* + +# Enable non-root Docker access in container +ARG ENABLE_NONROOT_DOCKER="true" +# Use the OSS Moby CLI instead of the licensed Docker CLI +ARG USE_MOBY="false" +RUN script=$(curl -fsSL "https://raw.githubusercontent.com/microsoft/vscode-dev-containers/${VSCODE_DEV_CONTAINERS_SCRIPT_LIBRARY_VERSION}/script-library/docker-debian.sh") && bash -c "$script" -- "${ENABLE_NONROOT_DOCKER}" "/var/run/docker-host.sock" "/var/run/docker.sock" "${USERNAME}" "${USE_MOBY}" + +# Setting the ENTRYPOINT to docker-init.sh will configure non-root access to +# the Docker socket if "overrideCommand": false is set in devcontainer.json. +# The script will also execute CMD if you need to alter startup behaviors. +ENTRYPOINT [ "/usr/local/share/docker-init.sh" ] +CMD [ "sleep", "infinity" ] + +ARG MAMBAFORGE_VERSION=22.9.0-2 + +# Based on https://github.com/conda-forge/miniforge-images/blob/master/ubuntu/Dockerfile +RUN wget --no-hsts --quiet https://github.com/conda-forge/miniforge/releases/download/${MAMBAFORGE_VERSION}/Mambaforge-${MAMBAFORGE_VERSION}-Linux-$(uname -m).sh -O /tmp/miniforge.sh \ + && /bin/bash /tmp/miniforge.sh -b -p /opt/conda \ + && rm /tmp/miniforge.sh \ + && /opt/conda/bin/conda clean --tarballs --index-cache --packages --yes \ + && find /opt/conda -follow -type f -name '*.a' -delete \ + && find /opt/conda -follow -type f -name '*.pyc' -delete \ + && /opt/conda/bin/conda clean --force-pkgs-dirs --all --yes \ + && groupadd -r conda --gid ${CONDA_GID} \ + && usermod -aG conda ${USERNAME} \ + && chown -R :conda /opt/conda \ + && chmod -R g+w /opt/conda \ + && find /opt -type d | xargs -n 1 chmod g+s + +# Create a conda environment from the environment file in the repo root. +COPY --from=file-normalizer --chown=$USER_UID:conda /data/environment.yml /tmp/build/ +RUN umask 0002 \ + && /opt/conda/bin/mamba env create -f /tmp/build/environment.yml \ + && /opt/conda/bin/mamba clean -fy \ + && sudo chown -R :conda /opt/conda/envs + +# Add a file that is to be sourced from .bashrc and from the devops pipeline stages +COPY --from=file-normalizer /data/devcontainer.bashrc /opt/devcontainer/ + +# Add a section to /etc/bash.bashrc that ensures that a section is present at the end of ~/.bashrc. +# We can't just write to .bashrc from here because it will be overwritten if the devcontainer user has +# opted to use their own dotfiles repo. The dotfiles repo is cloned after the postCreateCommand +# in the devcontainer.json file is executed. +RUN echo "\n\ +if ! grep -q \"^source /opt/devcontainer/devcontainer.bashrc\" \${HOME}/.bashrc; then\n\ + echo \"source /opt/devcontainer/devcontainer.bashrc\" >> \${HOME}/.bashrc\n\ +fi\n" >> /etc/bash.bashrc + +ENV CMAKE_GENERATOR=Ninja + +# Create a kits file for the VSCode CMake Tools extension, so you are not prompted for which kit to select whenever you open VSCode +RUN mkdir -p /home/vscode/.local/share/CMakeTools \ + && echo '[{"name":"GCC-10","compilers":{"C":"/opt/conda/envs/prd/bin/x86_64-conda_cos6-linux-gnu-gcc","CXX":"/opt/conda/envs/prd/bin/x86_64-conda_cos6-linux-gnu-g++"}}]' > /home/vscode/.local/share/CMakeTools/cmake-tools-kits.json \ + && chown vscode:conda /home/vscode/.local/share/CMakeTools/cmake-tools-kits.json + +# Install the yardl tool +ARG YARDL_VERSION=0.3.2 +RUN wget --quiet "https://github.com/microsoft/yardl/releases/download/v${YARDL_VERSION}/yardl_${YARDL_VERSION}_linux_x86_64.tar.gz" \ + && tar -xzf "yardl_${YARDL_VERSION}_linux_x86_64.tar.gz" \ + && mv yardl "/opt/conda/envs/${CONDA_ENVIRONMENT_NAME}/bin/" \ + && rm "yardl_${YARDL_VERSION}_linux_x86_64.tar.gz" diff --git a/.devcontainer/devcontainer.bashrc b/.devcontainer/devcontainer.bashrc new file mode 100644 index 0000000..1bd9398 --- /dev/null +++ b/.devcontainer/devcontainer.bashrc @@ -0,0 +1,11 @@ +#! /bin/bash +# shellcheck source=/dev/null + +source /opt/conda/etc/profile.d/conda.sh +conda activate prd +source <(yardl completion bash) + +if [[ "${BASH_ENV:-}" == "$(readlink -f "${BASH_SOURCE[0]:-}")" ]]; then + # We don't want subshells to unnecessarily source this again. + unset BASH_ENV +fi diff --git a/.devcontainer/devcontainer.json b/.devcontainer/devcontainer.json new file mode 100644 index 0000000..6a0e73f --- /dev/null +++ b/.devcontainer/devcontainer.json @@ -0,0 +1,126 @@ +// For format details, see https://aka.ms/devcontainer.json. For config options, see the README at: +// https://github.com/microsoft/vscode-dev-containerdevcotns/tree/v0.238.0/containers/go +{ + "name": "prd", + "build": { + "dockerfile": "Dockerfile", + "context": ".." + }, + "runArgs": [ + "--cap-add=SYS_PTRACE", + "--security-opt", + "seccomp=unconfined", + "--platform=linux/amd64" + ], + + "postStartCommand": "git submodule update --init --recursive", + + // Configure tool-specific properties. + "customizations": { + // Configure properties specific to VS Code. + "vscode": { + // Set *default* container specific settings.json values on container create. + "settings": { + "files.trimFinalNewlines": true, + "files.trimTrailingWhitespace": true, + "files.insertFinalNewline": true, + + "[cpp]": { + "editor.formatOnSave": true + }, + + "[json]": { + "editor.defaultFormatter": "esbenp.prettier-vscode", + "editor.formatOnSave": true + }, + + "[jsonc]": { + "editor.defaultFormatter": "esbenp.prettier-vscode", + "editor.formatOnSave": true + }, + + "[python]": { + "editor.defaultFormatter": "ms-python.black-formatter", + "editor.formatOnSave": true + }, + + "cmake.sourceDirectory": "${workspaceFolder}/cpp", + "cmake.buildDirectory": "${workspaceFolder}/cpp/build", + "cmake.configureOnOpen": false, + + "python.defaultInterpreterPath": "/opt/conda/envs/prd/bin/python", + "python.analysis.typeCheckingMode": "strict", + "python.analysis.diagnosticMode": "workspace", + "python.analysis.diagnosticSeverityOverrides": { + "reportUnknownArgumentType": "none", + "reportUnknownLambdaType": "none", + "reportUnknownMemberType": "none", + "reportUnknownParameterType": "none", + "reportUnknownVariableType": "none", + "reportUnnecessaryIsInstance": "none", + "reportUnusedImport": "none" + }, + "python.terminal.activateEnvironment": false, // Disable the extension calling activate when the integrated terminal launches. We take care of this in ~/.bashrc. + + "testMate.cpp.test.executables": "cpp/{build,Build,BUILD,out,Out,OUT}/**/*{test,Test,TEST}*", + + // enable pretty printing when debugging C++ tests + "testMate.cpp.debug.configTemplate": { + "type": "cppvsdbg", + "linux": { "type": "cppdbg", "MIMode": "gdb" }, + "darwin": { "type": "cppdbg", "MIMode": "lldb" }, + "win32": { "type": "cppvsdbg" }, + "program": "${exec}", + "args": "${argsArray}", + "cwd": "${cwd}", + "env": "${envObj}", + "environment": "${envObjArray}", + "sourceFileMap": "${sourceFileMapObj}", + "setupCommands": [ + { + "description": "Enable pretty-printing for gdb", + "text": "-enable-pretty-printing", + "ignoreFailures": true + } + ], + + "gitlens.showWelcomeOnInstall": false, + "gitlens.showWhatsNewAfterUpgrades": false + }, + + "gcovViewer.gcovBinary": "/opt/conda/envs/prd/bin/x86_64-conda-linux-gnu-gcov", + "gcovViewer.buildDirectories": ["${workspaceFolder}/cpp/build"], + + "search.useIgnoreFiles": false, + "search.exclude": { + "**/cpp/build": true + } + }, + + // Add the IDs of extensions you want installed when the container is created. + "extensions": [ + "cschlosser.doxdocgen", + "eamodio.gitlens", + "esbenp.prettier-vscode", + "JacquesLucke.gcov-viewer", + "matepek.vscode-catch2-test-adapter", + "mhutchie.git-graph", + "ms-python.black-formatter", + "ms-python.python", + "ms-vscode.cmake-tools", + "ms-vscode.cpptools", + "timonwong.shellcheck", + "twxs.cmake" + ] + } + }, + + // Use 'forwardPorts' to make a list of ports inside the container available locally. + // "forwardPorts": [], + + // Use 'postCreateCommand' to run commands after the container is created. + // "postCreateCommand": "go version", + + // Comment out to connect as root instead. More info: https://aka.ms/vscode-remote/containers/non-root. + "remoteUser": "vscode" +} diff --git a/.gitattributes b/.gitattributes new file mode 100644 index 0000000..d66b2f8 --- /dev/null +++ b/.gitattributes @@ -0,0 +1,4 @@ +# Shell scripts should have LF +*.bashrc text eol=lf +*.sh text eol=lf +*.csh text eol=lf diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md new file mode 100644 index 0000000..f1b9c8b --- /dev/null +++ b/.github/PULL_REQUEST_TEMPLATE.md @@ -0,0 +1,23 @@ +## Changes in this pull request + + +## Testing performed + + +## Related issues + + + +## Checklist before requesting a review + +- [ ] I have performed a self-review of my code +- [ ] I have added docstrings/doxygen in line with the guidance in the developer guide +- [ ] The code builds and runs on my machine + +## Contribution Notes + +Please read and adhere to the [contribution guidelines](https://github.com/ETSInitiative/PRDdefinition/blob/master/CONTRIBUTING.md). + +Please tick the following: + + - [ ] The content of this Pull Request (the Contribution) is intentionally submitted for inclusion in the ETSI software (the Work) under the terms and conditions of the [Apache-2.0](https://www.apache.org/licenses/LICENSE-2.0) License. diff --git a/.github/actions/configure-environment/action.yml b/.github/actions/configure-environment/action.yml new file mode 100644 index 0000000..1eacc5b --- /dev/null +++ b/.github/actions/configure-environment/action.yml @@ -0,0 +1,16 @@ +name: Configure Environment +description: Configures the conda environment +runs: + using: composite + steps: + + - name: Initial setup + shell: bash + run: | + # filter conda environment file + cat environment.yml | grep -v "#.*\<\local\>" > ci-environment.yml + + - uses: conda-incubator/setup-miniconda@v2 + with: + activate-environment: yardl + environment-file: ci-environment.yml diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml new file mode 100644 index 0000000..5b7b603 --- /dev/null +++ b/.github/workflows/ci.yml @@ -0,0 +1,58 @@ +name: CI + +on: + push: + branches: [main] + paths-ignore: + - '**/*.md' + pull_request: + branches: [main] + +defaults: + run: + # See https://github.com/marketplace/actions/setup-miniconda#important + shell: bash -el {0} + +jobs: + validate: + strategy: + matrix: + cppVersion: [17] + + name: Run tests + runs-on: ubuntu-latest + + steps: + - uses: actions/checkout@v3 + with: + submodules: recursive + + - name: Configure environment + uses: ./.github/actions/configure-environment + + - name: Install yardl + run: | + YARDL_DIR=${{github.workspace}}/yardl + mkdir ${YARDL_DIR} + cd ${YARDL_DIR} + echo "${{github.workspace}}/yardl" >> $GITHUB_PATH + YARDL_VERSION=0.3.2 + wget --quiet "https://github.com/microsoft/yardl/releases/download/v${YARDL_VERSION}/yardl_${YARDL_VERSION}_linux_x86_64.tar.gz" + tar -xzf "yardl_${YARDL_VERSION}_linux_x86_64.tar.gz" + rm "yardl_${YARDL_VERSION}_linux_x86_64.tar.gz" + + - name: Build model + run: | + cd PETSIRD/model + yardl generate + + - name: Python + run: | + cd python + python start.py + + - name: Cpp + run: | + cd cpp && mkdir -p build && cd build + cmake -G Ninja -S .. -DHDF5_ROOT="$CONDA_PREFIX" + ninja diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..a0232e3 --- /dev/null +++ b/.gitignore @@ -0,0 +1,7 @@ +**/build/ +**/__pycache__/ + +# Common editor backups +~$* +*~ +*.bak diff --git a/.gitmodules b/.gitmodules new file mode 100644 index 0000000..c1703ce --- /dev/null +++ b/.gitmodules @@ -0,0 +1,3 @@ +[submodule "PETSIRD"] + path = PETSIRD + url = https://github.com/ETSInitiative/PRDdefinition diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..2555c1c --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,137 @@ +Contributing +============ + +(This document largely follows the [SIRF Contribution guidelines](https://github.com/SyneRBI/SIRF/blob/master/CONTRIBUTING.md).) + +Please help us by finding problems, discussing on the mailing lists, contributing documentation, +bug fixes or even features. Below are some brief guidelines. + +## Reporting a problem + +Please use our [issue-tracker]. + +## Submitting a patch + +For contributing any code or documentation that is non-trivial, we require a +signed Contributor License Agreement, stating clearly that your +conributions are licensed appropriately. This will normally need to be signed by your +employer/university, unless you own your own copyright. +You will have to do this only once. Please contact us for more information. + +Please keep a patch focused on a single issue/feature. This is important to keep our history clean, +but will also help reviewing things and therefore speed-up acceptance. + +### Process + +This is our recommended process. If it sounds too daunting, ask for help. + +1. Create a new issue (see above). State that you will contribute a fix if you intend to do so. +2. Create a [fork](https://help.github.com/articles/fork-a-repo) on github and work from there. +3. Create a branch in your fork with a descriptive name and put your fixes there. If your fix is +simple you could do it on github by editing a file, otherwise clone your project (or add a remote +to your current git clone) and work as usual. +4. If your change is important, add yourself to `NOTICE.txt`, describe it in `CHANGES.md` (if it exists) +and other documentation files. +5. Use [well-formed commit messages](http://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html) +for each change (in particular with a single "subject" line +followed by an empty line and then more details). +6. Push the commits to your fork and submit a [pull request (PR)](https://help.github.com/articles/creating-a-pull-request) +(enable changes by project admins.) Be prepared to add further commits to your branch after discussion. +In the description of the PR, add a statement about which Issue this applies to +using [a phrase such that github auto-closes the issue when merged to master](https://help.github.com/articles/closing-issues-using-keywords/). +7. Be prepared to add further commits to your branch after discussion. +Please by mindful about the resources used by our Continuous Integration (CI) workflows: + - Group your commits and only push once your code compiles and tests succeed on your machine + - Use specific keywords in the body of the last commit that you push to prevent CI being run: + - `[ci skip]` skips all CI runs (e.g. when you only change documentation, or when your update isn't ready yet) + - `[actions skip]` does not run GitHub Actions, see [here](https://github.blog/changelog/2021-02-08-github-actions-skip-pull-request-and-push-workflows-with-skip-ci/). +8. After acceptance of your PR, go home with a nice warm feeling. + +Suggested reading: +https://help.github.com/articles/fork-a-repo/, https://git-scm.com/book/en/v2/GitHub-Contributing-to-a-Project or https://guides.github.com/activities/forking/. + +### A note on copyright dates and notices (and licenses) + +We recommend adding a brief copyright and license header to new files, e.g. in C++ +```c++ +/* + Copyright (C) 2023 University College London + + SPDX-License-Identifier: Apache-2.0 +*/ +``` +If you modify an existing file, you need to make sure the copyright header is up-to-date for your changes +(unless it's a trivial change). + +If you copied code from somewhere, you need to preserve its copyright date/notice. If you copied external code, +you need to make sure its license is compatible with the Apache 2.0 license, and indicate clearly what the license +of the copied code is (and follow its terms of course). + +## Project rules + +- Only one official, stable, up-to-date branch: **main** + + Essentially "latest stable beta version with no known bugs + since the last official release version" + + Never knowingly add a bug to **main** +- Any work-in-progress commits should be in their own branches. +- GitHub assigns a unique number to each issue, c.f. the [issue-tracker]. +- A pull request (PR) is an issue with an associated branch, + c.f. [pull-requests]. Even for "internal" development, we prefer a PR for + a branch to allow review and discussion. +- Branches and PRs are kept small (ideally one 'feature' only) and branch from **main**, + not from another branch, unless required. This allows + commenting/improving/merging this branch/PR + independent of other developments. +- Contributions of new features should also update documentation and release notes. After version 1.0, + this documentation needs to state something like "introduced after version 1.xxx". +- We prefer issues to be opened via [github][issue-tracker] due to the following reasons: + + Ensures issues will never get lost in emails + * Facilitates issue status tracking + + Allows focused comments/discussion + * Easy cross-referencing of related issues, PRs, and commits + +``` + + +## Submodules + +This project uses [submodules] to point to a specific version of the PETSIRD model. If you want to use a more recent model, +you will need to update the submodule. + +1. How to pull updates to this repo +```bash +# first time +git clone --recursive +# subsequently +git pull --recurse-submodules +# or +git pull +git submodule update --init --recursive +``` +2. How to update to the most recent version of the model +```bash +git submodule update --remote --recursive --init +``` + +3. How to update to a specific version of the model +```bash +# first get the version you want +cd PETSIRD +git fetch +git checkout v1.0.0 +cd .. +# now tell the main project to use that version +git add PETSIRD +# probably update some other files +git commit -m "Use PETSIRD v1.0.0" +``` +4. Switching branches + +If different branches have different versions of the submodule, it is highly recommended to use +```bash +git switch --recurse-submodules +``` +Without the `--recurse-submodules` option, the submodule will be kept the same as on the +original branch, and you need to manually run `git submodule update --recursive`. + +[submodules]: https://git-scm.com/docs/gitsubmodules diff --git a/LICENSE.txt b/LICENSE.txt new file mode 100644 index 0000000..0c8a800 --- /dev/null +++ b/LICENSE.txt @@ -0,0 +1,53 @@ +Apache License + +Version 2.0, January 2004 + +http://www.apache.org/licenses/ + +TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION + +1. Definitions. + +"License" shall mean the terms and conditions for use, reproduction, and distribution as defined by Sections 1 through 9 of this document. + +"Licensor" shall mean the copyright owner or entity authorized by the copyright owner that is granting the License. + +"Legal Entity" shall mean the union of the acting entity and all other entities that control, are controlled by, or are under common control with that entity. For the purposes of this definition, "control" means (i) the power, direct or indirect, to cause the direction or management of such entity, whether by contract or otherwise, or (ii) ownership of fifty percent (50%) or more of the outstanding shares, or (iii) beneficial ownership of such entity. + +"You" (or "Your") shall mean an individual or Legal Entity exercising permissions granted by this License. + +"Source" form shall mean the preferred form for making modifications, including but not limited to software source code, documentation source, and configuration files. + +"Object" form shall mean any form resulting from mechanical transformation or translation of a Source form, including but not limited to compiled object code, generated documentation, and conversions to other media types. + +"Work" shall mean the work of authorship, whether in Source or Object form, made available under the License, as indicated by a copyright notice that is included in or attached to the work (an example is provided in the Appendix below). + +"Derivative Works" shall mean any work, whether in Source or Object form, that is based on (or derived from) the Work and for which the editorial revisions, annotations, elaborations, or other modifications represent, as a whole, an original work of authorship. For the purposes of this License, Derivative Works shall not include works that remain separable from, or merely link (or bind by name) to the interfaces of, the Work and Derivative Works thereof. + +"Contribution" shall mean any work of authorship, including the original version of the Work and any modifications or additions to that Work or Derivative Works thereof, that is intentionally submitted to Licensor for inclusion in the Work by the copyright owner or by an individual or Legal Entity authorized to submit on behalf of the copyright owner. For the purposes of this definition, "submitted" means any form of electronic, verbal, or written communication sent to the Licensor or its representatives, including but not limited to communication on electronic mailing lists, source code control systems, and issue tracking systems that are managed by, or on behalf of, the Licensor for the purpose of discussing and improving the Work, but excluding communication that is conspicuously marked or otherwise designated in writing by the copyright owner as "Not a Contribution." + +"Contributor" shall mean Licensor and any individual or Legal Entity on behalf of whom a Contribution has been received by Licensor and subsequently incorporated within the Work. + +2. Grant of Copyright License. Subject to the terms and conditions of this License, each Contributor hereby grants to You a perpetual, worldwide, non-exclusive, no-charge, royalty-free, irrevocable copyright license to reproduce, prepare Derivative Works of, publicly display, publicly perform, sublicense, and distribute the Work and such Derivative Works in Source or Object form. + +3. Grant of Patent License. Subject to the terms and conditions of this License, each Contributor hereby grants to You a perpetual, worldwide, non-exclusive, no-charge, royalty-free, irrevocable (except as stated in this section) patent license to make, have made, use, offer to sell, sell, import, and otherwise transfer the Work, where such license applies only to those patent claims licensable by such Contributor that are necessarily infringed by their Contribution(s) alone or by combination of their Contribution(s) with the Work to which such Contribution(s) was submitted. If You institute patent litigation against any entity (including a cross-claim or counterclaim in a lawsuit) alleging that the Work or a Contribution incorporated within the Work constitutes direct or contributory patent infringement, then any patent licenses granted to You under this License for that Work shall terminate as of the date such litigation is filed. + +4. Redistribution. You may reproduce and distribute copies of the Work or Derivative Works thereof in any medium, with or without modifications, and in Source or Object form, provided that You meet the following conditions: + +You must give any other recipients of the Work or Derivative Works a copy of this License; and +You must cause any modified files to carry prominent notices stating that You changed the files; and +You must retain, in the Source form of any Derivative Works that You distribute, all copyright, patent, trademark, and attribution notices from the Source form of the Work, excluding those notices that do not pertain to any part of the Derivative Works; and +If the Work includes a "NOTICE" text file as part of its distribution, then any Derivative Works that You distribute must include a readable copy of the attribution notices contained within such NOTICE file, excluding those notices that do not pertain to any part of the Derivative Works, in at least one of the following places: within a NOTICE text file distributed as part of the Derivative Works; within the Source form or documentation, if provided along with the Derivative Works; or, within a display generated by the Derivative Works, if and wherever such third-party notices normally appear. The contents of the NOTICE file are for informational purposes only and do not modify the License. You may add Your own attribution notices within Derivative Works that You distribute, alongside or as an addendum to the NOTICE text from the Work, provided that such additional attribution notices cannot be construed as modifying the License. + +You may add Your own copyright statement to Your modifications and may provide additional or different license terms and conditions for use, reproduction, or distribution of Your modifications, or for any such Derivative Works as a whole, provided Your use, reproduction, and distribution of the Work otherwise complies with the conditions stated in this License. +5. Submission of Contributions. Unless You explicitly state otherwise, any Contribution intentionally submitted for inclusion in the Work by You to the Licensor shall be under the terms and conditions of this License, without any additional terms or conditions. Notwithstanding the above, nothing herein shall supersede or modify the terms of any separate license agreement you may have executed with Licensor regarding such Contributions. + +6. Trademarks. This License does not grant permission to use the trade names, trademarks, service marks, or product names of the Licensor, except as required for reasonable and customary use in describing the origin of the Work and reproducing the content of the NOTICE file. + +7. Disclaimer of Warranty. Unless required by applicable law or agreed to in writing, Licensor provides the Work (and each Contributor provides its Contributions) on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied, including, without limitation, any warranties or conditions of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A PARTICULAR PURPOSE. You are solely responsible for determining the appropriateness of using or redistributing the Work and assume any risks associated with Your exercise of permissions under this License. + +8. Limitation of Liability. In no event and under no legal theory, whether in tort (including negligence), contract, or otherwise, unless required by applicable law (such as deliberate and grossly negligent acts) or agreed to in writing, shall any Contributor be liable to You for damages, including any direct, indirect, special, incidental, or consequential damages of any character arising as a result of this License or out of the use or inability to use the Work (including but not limited to damages for loss of goodwill, work stoppage, computer failure or malfunction, or any and all other commercial damages or losses), even if such Contributor has been advised of the possibility of such damages. + +9. Accepting Warranty or Additional Liability. While redistributing the Work or Derivative Works thereof, You may choose to offer, and charge a fee for, acceptance of support, warranty, indemnity, or other liability obligations and/or rights consistent with this License. However, in accepting such obligations, You may act only on Your own behalf and on Your sole responsibility, not on behalf of any other Contributor, and only if You agree to indemnify, defend, and hold each Contributor harmless for any liability incurred by, or claims asserted against, such Contributor by reason of your accepting any such warranty or additional liability. + +END OF TERMS AND CONDITIONS diff --git a/NOTICE.txt b/NOTICE.txt new file mode 100644 index 0000000..0464368 --- /dev/null +++ b/NOTICE.txt @@ -0,0 +1,11 @@ +Copyright 2023 University College London (UCL) + +This software product is developed for the Emission Tomography Standardization +Initiative (ETSI), https://etisinitiative.org. + +Main contributors: +Kris Thielemans (UCL) + +### Apache License ### + +All documents are covered by the Apache 2.0 license, unless otherwise specified. diff --git a/PETSIRD b/PETSIRD new file mode 160000 index 0000000..f168903 --- /dev/null +++ b/PETSIRD @@ -0,0 +1 @@ +Subproject commit f16890385facda7ac949d8ab622e4e8fee3332d2 diff --git a/README.md b/README.md new file mode 100644 index 0000000..2221be9 --- /dev/null +++ b/README.md @@ -0,0 +1,50 @@ +# PETSIRD template for use cases + +The purpose of this repo is to provide a starting point for other software that uses PETSIRD. + +## Background +The [Emission Tomography Standardization Initiative (ETSI)](https://etsinitiative.org/) +is working towards establishing a standard for PET Raw Data, called PETSIRD ("PET ETSI Raw Data"). + +The specification uses the [yardl](https://aka.ms/yardl) tool to define the model. `yardl` can be +used to read the specification (in the `model` directory) and generate an PI for both C++ and API to read/write PETSIRD data. + +Currently, a draft model is defined in https://github.com/ETSInitiative/PRDdefinition. + +CAVEAT: the draft model generates code in the `prd` namespace. Nevertheless, we have used the name PETSIRD here +in most places (except where needed). + +## How to use this template? + +These instructions will use `YourRepoName` for the name of your new repository. Obviously replace it with something appropriate. + +#### Create a new repository based on this template + +Easiest is to start from GitHub: +1. Navigate to the URL of this repo: https://github.com/ETSInitiative/PETSIRDUseCaseTemplate +2. Click on the `Use this template` button and create your own repo +3. Pull it to your own local machine and modify + 1. Search-and-replace all occurences of `PETSIRDUseCaseTemplate` with `YourRepoName` + 2. Update the README.md to remove references to this template and write something about what your repo is going to do + 3. Update the `environment.yml`to include what you need. For instance, if you need ROOT, add something like `- root=6.28.0` + 4. Make some other basic changes and commit + ```sh + git commit -a -m "Updated template to YourRepoName" + git push + ``` + +### Using your repo + +1. Open ***your*** repo in [GitHub Codespaces](https://code.visualstudio.com/docs/remote/codespaces) or +in a [VS Code devcontainer](https://code.visualstudio.com/docs/devcontainers/containers). +This codespace/container will contain all necessary tools, including `yardl` itself, as well as your repository. +2. Use `yardl` to generate C++ and Python code for the model: + ```sh + cd YourRepoName + cd PETSIRD/model + yardl generate + cd ../.. + ``` +3. Start working in either the [`cpp`](cpp/README.md) and/or [`python`](python/README.md) directories. + + diff --git a/SUPPORT.md b/SUPPORT.md new file mode 100644 index 0000000..8cdf0e9 --- /dev/null +++ b/SUPPORT.md @@ -0,0 +1,13 @@ +# Support + +## How to file issues and get help + +This project uses GitHub Issues to track bugs and feature requests. Please search the existing +issues before filing new issues to avoid duplicates. For new issues, file your bug or +feature request as a new Issue. + +For help and questions about using this project, please [start a discussion](https://github.com/ETSInitiative/PRDdefinitions/discussions). + +## Support Policy + +Support for this project is limited to the resources listed above. diff --git a/cpp/CMakeLists.txt b/cpp/CMakeLists.txt new file mode 100644 index 0000000..a0bbfe0 --- /dev/null +++ b/cpp/CMakeLists.txt @@ -0,0 +1,17 @@ +cmake_minimum_required(VERSION 3.12.0) # older would work, but could give warnings on policy CMP0074 +project(PETSIRDUseCaseTemplate VERSION 0.1.0) + +set(CMAKE_CXX_STANDARD 17) + +if(WIN32) + add_compile_options(/W3 /WX) +else() + add_compile_options(-Wall -Wextra -pedantic) +endif() + +# Example lines for a new executable +# add_executable(my_prog my_prog.cpp) +# target_link_libraries(my_prog PUBLIC prd_generated) +# install(TARGETS my_prog DESTINATION bin) + +add_subdirectory(../PETSIRD/cpp/generated PETSIRD_generated) diff --git a/cpp/README.md b/cpp/README.md new file mode 100644 index 0000000..af2056c --- /dev/null +++ b/cpp/README.md @@ -0,0 +1,15 @@ +# PETSIRD basic C++ example + +This directory provides a skeleton for C++ example code to read/write PETSIRD data. You need to `yardl generate` in the `model` directory first. + +Check the example in the PRDdefinition repo first. + +1. Compile the code: + ```sh + cd cpp + mkdir -p build && cd build` + cmake -G Ninja -S .. -DHDF5_ROOT=$CONDA_PREFIX + ninja` + ``` + If you did not use `conda` to install HDF5, do not add the `-DHDF5_ROOT=$CONDA_PREFIX` part of the `cmake` line. + diff --git a/environment.yml b/environment.yml new file mode 100644 index 0000000..a61c4e7 --- /dev/null +++ b/environment.yml @@ -0,0 +1,20 @@ +name: prd +channels: + - conda-forge + - defaults +dependencies: + - bash-completion>=2.11 + - cmake>=3.21.3 + - fmt>=8.1.1 + - compilers + - h5py>=3.7.0 + - hdf5>=1.12.1 + - howardhinnant_date>=3.0.1 + - ipykernel>=6.19.2 + - ninja>=1.11.0 + - nlohmann_json>=3.11.2 + - numpy>=1.24.3 + - python>=3.11.3 + - shellcheck>=0.8.0 + - xtensor-fftw>=0.2.5 + - xtensor>=0.24.2 diff --git a/python/README.md b/python/README.md new file mode 100644 index 0000000..ed4b962 --- /dev/null +++ b/python/README.md @@ -0,0 +1,6 @@ +# PETSIRD basic Python example + +This directory contains some instructions to wrote Python code to read/write PETSIRD data. You need to `yardl generate` in the `model` directory first. + +As we currently do not have a `set_up.py` for PETSIRD yet, the example file hard-codes the path to the generated files. +Alternatives would be to use the `PYTHONPATH` environment variable or symbolic links. \ No newline at end of file diff --git a/python/start.py b/python/start.py new file mode 100644 index 0000000..60f13f9 --- /dev/null +++ b/python/start.py @@ -0,0 +1,5 @@ +import sys +# Currently hard-wire location of generated files. This will need to change! +sys.path.append('../PETSIRD/python/') +import prd +