APTG · nbassler · Mar 28, 2026 · Mar 28, 2026 · Mar 28, 2026 · Mar 28, 2026
diff --git a/.clang-tidy b/.clang-tidy
@@ -0,0 +1,25 @@
+# clang-tidy configuration for libdedx
+#
+# Enabled check groups:
+#   clang-analyzer-*  Clang's own inter-procedural static analyzer (high confidence)
+#   bugprone-*        Common bug patterns in C code
+#
+# Disabled individually:
+#   bugprone-easily-swappable-parameters        too noisy for physics code (many float params)
+#   clang-analyzer-security.insecureAPI.*       flags printf/strcpy family — too noisy for now
+
+Checks: >-
+  clang-analyzer-*,
+  bugprone-*,
+  -bugprone-easily-swappable-parameters,
+  -bugprone-narrowing-conversions,
+  -bugprone-reserved-identifier,
+  -bugprone-branch-clone,
+  -bugprone-switch-missing-default-case,
+  -clang-analyzer-security.insecureAPI.DeprecatedOrUnsafeBufferHandling,
+  -clang-analyzer-security.insecureAPI.strcpy
+
+WarningsAsErrors: '*'
+
+# Only report issues in our own headers, not system or third-party ones
+HeaderFilterRegex: '(libdedx|tests|examples|buildbins)/'
diff --git a/.github/workflows/clang-tidy.yml b/.github/workflows/clang-tidy.yml
@@ -0,0 +1,28 @@
+name: clang-tidy
+
+# Automatic triggering is disabled until the findings logged in the clang-tidy tracking issue
+# are resolved. The workflow can still be run manually from the Actions tab via workflow_dispatch.
+# To re-enable: replace the trigger below with `on: [push, pull_request]`.
+on:
+  workflow_dispatch:
+
+jobs:
+  clang-tidy:
+    runs-on: ubuntu-24.04
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install clang-tidy-19
+        run: |
+          sudo apt-get update
+          sudo apt-get install -y clang-tidy-19
+
+      - name: Configure (generates compile_commands.json)
+        run: cmake -S . -B build
+
+      - name: Run clang-tidy
+        run: |
+          run-clang-tidy-19 \
+            -p build \
+            -header-filter='(libdedx|tests|examples|buildbins)/' \
+            '(libdedx|tests|examples|buildbins)/.*\.c$'
diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml
@@ -5,22 +5,20 @@ on: [push]
 jobs:
   build_docs:
     runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      pages: write
+      id-token: write
     steps:
       - name: Checkout
         uses: actions/checkout@v4
         with:
-          fetch-depth: 0 # otherwise, you will fail to push refs to dest repo
+          fetch-depth: 0
 
-      - name: Build and Commit
-        uses: sphinx-notes/pages@2.0
+      - name: Build and Deploy
+        # Deploys to GitHub Pages only on main or release tags (v*)
+        if: "github.ref == 'refs/heads/main' || (github.event_name == 'push' && startsWith(github.event.ref, 'refs/tags/v'))"
+        uses: sphinx-notes/pages@3.5
         with:
           documentation_path: docs/source
           requirements_path: docs/source/requirements.txt
-
-      - name: Push changes to gh-pages branch
-        # triggered on main branch or release tags (named v*)
-        if: "github.ref == 'refs/heads/main' || (github.event_name == 'push' && startsWith(github.event.ref, 'refs/tags/v'))"
-        uses: ad-m/github-push-action@v0.6.0
-        with:
-          github_token: ${{ secrets.GITHUB_TOKEN }}
-          branch: gh-pages
diff --git a/.gitignore b/.gitignore
@@ -3,6 +3,7 @@
 build/
 build-release/
 build-coverage/
+docs/doxygen/html/
 .codex
 
 # Generated by CMake at configure time - do not commit

diff --git a/CMakeLists.txt b/CMakeLists.txt
@@ -2,6 +2,9 @@ cmake_minimum_required(VERSION 3.21)
 
 project(dedx LANGUAGES C)
 
+set(CMAKE_C_STANDARD 11)
+set(CMAKE_C_STANDARD_REQUIRED ON)
+
 set(CMAKE_EXPORT_COMPILE_COMMANDS ON)
 
 # ---- Version from git tag ----
@@ -48,9 +51,6 @@ configure_file(
     "${PROJECT_BINARY_DIR}/dedx_config.h"
 )
 
-include_directories("${PROJECT_SOURCE_DIR}/libdedx")
-include_directories("${PROJECT_BINARY_DIR}")
-link_directories("${PROJECT_SOURCE_DIR}/libdedx")
 option(DEDX_BUILD_BINARY_TABLE "Build the binary data tables (requires a working install of libdedx data)" ON)
 if(DEDX_BUILD_BINARY_TABLE)
     add_subdirectory(buildbins)

diff --git a/README.md b/README.md
@@ -1,7 +1,79 @@
 # libdedx
 
-libdEdx is a physics library for stopping power calculations.
-Stopping power is the energy loss of a particle per unit length (dE/dx).
-libdedx is supposed to be both fast and easy to use, and features multiple standard dE/dx lists (ICRU, MSTAR...)
+[![CI](https://github.com/APTG/libdedx/actions/workflows/ci.yml/badge.svg)](https://github.com/APTG/libdedx/actions/workflows/ci.yml)
+[![Coverage](https://codecov.io/gh/APTG/libdedx/graph/badge.svg)](https://codecov.io/gh/APTG/libdedx)
+[![License: GPL v3](https://img.shields.io/badge/License-GPLv3-blue.svg)](https://www.gnu.org/licenses/gpl-3.0)
 
-For the documentation see: https://aptg.github.io/libdedx/
+A C library for stopping power calculations (dE/dx) — the energy loss of a charged particle per unit length of material.
+
+Full documentation: https://aptg.github.io/libdedx/
+
+## Supported programs
+
+| Program         | Description                                      | Ions          |
+|-----------------|--------------------------------------------------|---------------|
+| `DEDX_PSTAR`    | NIST PSTAR database                              | Protons       |
+| `DEDX_ASTAR`    | NIST ASTAR database                              | Alpha particles |
+| `DEDX_MSTAR`    | MSTAR code                                       | Heavy ions    |
+| `DEDX_ICRU49`   | ICRU Report 49 (1993)                            | p, He         |
+| `DEDX_ICRU73`   | ICRU Report 73 (2005)                            | Heavy ions    |
+| `DEDX_ICRU73_OLD` | ICRU Report 73, older parametrization          | Heavy ions    |
+| `DEDX_BETHE_EXT00` | Bethe formula with extensions                 | All ions      |
+| `DEDX_ICRU`     | Auto-selects ICRU49 or ICRU73 by ion type        | p, He, heavy  |
+
+## Quick start
+
+One-call API for a single stopping power value:
+
+```c
+#include <dedx.h>
+
+int err = 0;
+float stp = dedx_get_simple_stp(DEDX_PROTON, DEDX_WATER, 100.0f, &err);
+// stp in MeV cm² / g at 100 MeV/u
+```
+
+Full API with workspace for repeated evaluations:
+
+```c
+#include <dedx.h>
+#include <stdlib.h>
+
+int err = 0;
+dedx_workspace *ws = dedx_allocate_workspace(1, &err);
+dedx_config *cfg   = calloc(1, sizeof(dedx_config));
+
+cfg->program = DEDX_PSTAR;
+cfg->ion     = DEDX_PROTON;
+cfg->target  = DEDX_WATER;
+
+dedx_load_config(ws, cfg, &err);
+float stp = dedx_get_stp(ws, cfg, 100.0f, &err);
+
+dedx_free_config(cfg, &err);
+dedx_free_workspace(ws, &err);
+```
+
+See the [examples/](examples/) directory for more usage patterns.
+
+## Building
+
+Requires CMake 3.21+ and a C11 compiler.
+
+```bash
+cmake --preset debug
+cmake --build --preset debug
+ctest --preset debug
+```
+
+To install:
+
+```bash
+cmake --preset release -DCMAKE_INSTALL_PREFIX=/your/prefix
+cmake --build --preset release
+cmake --install build-release
+```
+
+## License
+
+libdedx is free software, distributed under the [GNU General Public License v3](https://www.gnu.org/licenses/gpl-3.0).
diff --git a/buildbins/CMakeLists.txt b/buildbins/CMakeLists.txt
@@ -1,5 +1,3 @@
-include_directories ("${PROJECT_SOURCE_DIR}")
-
 # here we create `dedx_build_bin` executable which builds *.bin files from *.dat files
 add_executable(dedx_build_bin dedx_build_bin.c)
 target_link_libraries (dedx_build_bin dedx)

diff --git a/docs/doxygen/Doxyfile b/docs/doxygen/Doxyfile
@@ -0,0 +1,29 @@
+PROJECT_NAME           = "libdedx"
+PROJECT_BRIEF          = "Stopping power (dE/dx) library"
+PROJECT_NUMBER         =
+
+INPUT                  = ../../libdedx/dedx.h ../../libdedx/dedx_wrappers.h ../../libdedx/dedx_tools.h
+RECURSIVE              = NO
+
+OUTPUT_DIRECTORY       = .
+GENERATE_HTML          = YES
+HTML_OUTPUT            = html
+GENERATE_LATEX         = NO
+
+EXTRACT_ALL            = NO
+EXTRACT_PRIVATE        = NO
+EXTRACT_STATIC         = NO
+
+HIDE_UNDOC_MEMBERS     = YES
+HIDE_UNDOC_CLASSES     = YES
+
+QUIET                  = YES
+WARNINGS               = YES
+WARN_IF_UNDOCUMENTED   = NO
+
+JAVADOC_AUTOBRIEF      = YES
+QT_AUTOBRIEF           = NO
+
+OPTIMIZE_OUTPUT_FOR_C  = YES
+
+ALPHABETICAL_INDEX     = YES
diff --git a/docs/doxygen/README.md b/docs/doxygen/README.md
@@ -0,0 +1,13 @@
+# Doxygen API documentation
+
+Generate the HTML documentation locally:
+
+```bash
+cd docs/doxygen
+doxygen Doxyfile
+```
+
+Then open `docs/doxygen/html/index.html` in a browser.
+
+The generated `html/` directory is gitignored.
+For full documentation including narrative pages, see the Sphinx docs in `docs/source/`.
diff --git a/docs/source/requirements.txt b/docs/source/requirements.txt
@@ -1,2 +1,2 @@
 sphinx>=5
-pydata-sphinx-theme>=0.13
+pydata-sphinx-theme>=0.13.3
diff --git a/examples/CMakeLists.txt b/examples/CMakeLists.txt
@@ -1,5 +1,3 @@
-include_directories ("${PROJECT_SOURCE_DIR}")
-
 add_executable(dedx_example dedx_example.c)
 add_executable(getdedx dedx_get.c)
 add_executable(dedx_list dedx_list.c)

diff --git a/gui/Makefile b/gui/Makefile
diff --git a/gui/dropdown/prog.cpp b/gui/dropdown/prog.cpp
diff --git a/gui/dropdown/prog.h b/gui/dropdown/prog.h
diff --git a/gui/dropdown/target.cpp b/gui/dropdown/target.cpp
diff --git a/gui/dropdown/target.h b/gui/dropdown/target.h
diff --git a/gui/main b/gui/main
diff --git a/gui/main.cpp b/gui/main.cpp
diff --git a/gui/mainMenu.cpp b/gui/mainMenu.cpp
diff --git a/gui/mainMenu.h b/gui/mainMenu.h