chargefw 0.1__tar.gz

chargefw-0.1/.clang-format

@@ -0,0 +1,19 @@
+BasedOnStyle: LLVM
+Language: Cpp
+Standard: Latest
+
+IndentWidth: 4
+TabWidth: 4
+UseTab: Never
+
+ColumnLimit: 100
+
+BreakBeforeBraces: Attach
+AllowShortFunctionsOnASingleLine: Empty
+AllowShortIfStatementsOnASingleLine: Never
+AllowShortLoopsOnASingleLine: false
+
+PointerAlignment: Left
+ReferenceAlignment: Left
+
+SortIncludes: true

chargefw-0.1/.clang-tidy

@@ -0,0 +1,38 @@
+Checks: >
+  bugprone-*,
+  clang-analyzer-*,
+  cppcoreguidelines-*,
+  modernize-*,
+  performance-*,
+  portability-*,
+  readability-*,
+  -readability-magic-numbers,
+  -cppcoreguidelines-avoid-magic-numbers,
+  -cppcoreguidelines-owning-memory,
+  -cppcoreguidelines-pro-bounds-pointer-arithmetic,
+  -cppcoreguidelines-pro-type-reinterpret-cast,
+  -cppcoreguidelines-pro-bounds-avoid-unchecked-container-access,
+  -cppcoreguidelines-non-private-member-variables-in-classes,
+  -readability-identifier-length,
+  -bugprone-easily-swappable-parameters,
+  -portability-avoid-pragma-once,
+  -readability-avoid-const-params-in-decls,
+  -readability-isolate-declaration,
+  -readability-math-missing-parentheses,
+  -readability-function-cognitive-complexity,
+  -modernize-use-designated-initializers,
+  -modernize-use-trailing-return-type,
+  -performance-enum-size,
+  -readability-redundant-member-init,
+  -cppcoreguidelines-avoid-c-arrays,
+  -bugprone-exception-escape,
+  -bugprone-unchecked-optional-access,
+  -readability-qualified-auto,
+  -readability-avoid-nested-conditional-operator,
+  -readability-convert-member-functions-to-static,
+  -readability-named-parameter,
+  -cppcoreguidelines-missing-std-forward
+
+WarningsAsErrors: ''
+HeaderFilterRegex: '.*'
+FormatStyle: file

chargefw-0.1/.dockerignore

@@ -0,0 +1,4 @@
+build/
+_release_install/
+**/__pycache__/
+.git/

chargefw-0.1/.gitignore

@@ -0,0 +1,79 @@
+# Prerequisites
+*.d
+
+# Compiled Object files
+*.slo
+*.lo
+*.o
+*.obj
+
+# Precompiled Headers
+*.gch
+*.pch
+
+# Linker files
+*.ilk
+
+# Debugger Files
+*.pdb
+
+# Compiled Dynamic libraries
+*.so
+*.dylib
+*.dll
+*.so.*
+
+
+# Fortran module files
+*.mod
+*.smod
+
+# Compiled Static libraries
+*.lai
+*.la
+*.a
+*.lib
+
+# Executables
+*.exe
+*.out
+*.app
+
+# Build directories
+build/
+Build/
+build-*/
+
+# CMake generated files
+CMakeFiles/
+CMakeCache.txt
+cmake_install.cmake
+Makefile
+install_manifest.txt
+compile_commands.json
+
+# Temporary files
+*.tmp
+*.log
+*.bak
+*.swp
+
+# vcpkg
+vcpkg_installed/
+
+# debug information files
+*.dwo
+
+# test output & cache
+Testing/
+.cache/
+__pycache__/
+*.py[cod]
+
+# Jetbrains
+.idea
+
+# Local devel
+_*install
+old
+CMakeUserPresets.json

chargefw-0.1/.pre-commit-config.yaml

@@ -0,0 +1,8 @@
+repos:
+  - repo: local
+    hooks:
+      - id: clang-format
+        name: clang-format
+        entry: clang-format -i --style=file
+        language: system
+        types_or: [c++, c, cuda]

chargefw-0.1/AGENTS.md

@@ -0,0 +1,112 @@
+# ChargeFW Development Guide
+
+## Required reading and document ownership
+
+Read this file before changing the repository. Then read only the relevant sections of:
+
+- [docs/PROJECT.md](docs/PROJECT.md): implemented architecture, philosophy, capabilities, and limits;
+- [docs/CLI.md](docs/CLI.md): implemented command-line behavior;
+- [docs/NATIVE.md](docs/NATIVE.md): implemented public C++ API and installation;
+- [docs/PYTHON.md](docs/PYTHON.md): implemented Python API and package behavior;
+- [TODO.md](TODO.md): unfinished product work; and
+- [README.md](README.md): concise project entry point.
+
+Keep ownership clear. The files under `docs/` are user documentation and must describe implemented
+behavior, not development plans or milestone history. Unfinished work belongs in `TODO.md`; remove it
+when complete rather than retaining checked history. `README.md` should remain a concise user entry
+point.
+
+## Repository map
+
+```text
+include/chargefw/   Public C++ API
+src/                Native library implementation, organized by public domain
+apps/chargefw/      Command-line application
+python/chargefw/    Public Python package and private extension stubs
+python/src/         Nanobind extension implementation
+data/parameters/    Bundled parameter sets
+tests/cpp/          Native tests and downstream CMake consumer
+tests/python/       Python package and adapter tests
+tests/fixtures/     Molecular and parameter test data
+cmake/              Dependencies, diagnostics, and installation rules
+docs/               Implemented user documentation
+Dockerfile           User-facing CLI container image
+docker/              Developer compatibility containers
+```
+
+`include/chargefw/adapters/{native,gemmi}/all.h` are application convenience headers. Library code
+should include only the individual adapter headers it uses.
+
+## Architectural rules
+
+- Keep `core` small and toolkit-neutral. File formats, toolkit objects, preparation policy, and cached
+  derived data do not belong in `core::Molecule`.
+- Put cached topology/geometry data and spatial fragments in `features`.
+- Parameter matching is immutable external data:
+  `ParameterSet + Molecule + TopologyFeatures -> ParameterClassification -> ParameterView`.
+- Methods are stateless algorithms. Request-specific options, geometry, targets, and parameters enter
+  through `methods::CalculationInput`.
+- Keep scientific applicability, execution availability, deterministic selection, and calculation
+  distinct, while allowing the application facade to compose them.
+- Keep execution policy separate from method options. Never silently change method, parameter set,
+  classification, execution mode/radius, charge correction, topology, protonation, or geometry.
+- Preserve source atom order, molecule/conformer identity, and mappings at every result boundary.
+- Missing scientific prerequisites are hard failures. Resource thresholds only guide automatic
+  execution; explicit full execution may override them with a reported warning.
+- Full calculations must remain faithful to their cited methods. Approximate execution must be
+  capability-checked, explicit in provenance, and validated per method.
+- Bindings, adapters, and applications translate representations into the native facade; they must not
+  duplicate applicability, selection, or scientific policy.
+- Avoid global mutable state. The library must remain suitable for concurrent and embedded use.
+
+## Change discipline
+
+1. Inspect the relevant public headers, implementation, tests, and user documentation section first.
+2. Make the smallest coherent change and run clang-format each time on modified files.
+3. Add focused tests for behavior changes, especially numerical, mapping, applicability, and policy
+   cases.
+4. Follow the validation cadence below. Build the directly affected target and run its focused test first;
+   do not make the full compiler/sanitizer matrix part of every edit cycle.
+5. Stop for approval before heavyweight dependencies, broad rewrites, destructive commands, automatic
+   chemistry policy, or public API changes beyond the requested scope.
+6. Remove a TODO only when its full deliverable and validation are complete. Update the owning user
+   document with durable implemented behavior.
+
+### Validation cadence
+
+- Use `gcc-debug` for the rapid edit/build/focused-test loop. After a coherent change, run the full
+  `ctest --preset gcc-debug` suite.
+- Use `clang-debug` for cross-compiler validation when changing templates, conversions, overloads,
+  headers, or compiler-sensitive C++ behavior; run its focused test before substantial work is complete.
+- Use `gcc-release` and `clang-release` for optimization- or `NDEBUG`-sensitive behavior, numerical
+  methods, Eigen code, and before completing substantial changes. Run the affected test under both
+  release configurations when practical.
+- Use `clang-asan` for ownership, lifetime, bounds, mapping, parser, container, view, and pointer
+  changes. Use `clang-ubsan` for arithmetic, conversions, shifts, alignment, indexing, and other
+  undefined-behavior risks. Run the focused sanitizer test first and the full relevant sanitizer suite
+  before completing substantial risk-sensitive work. Keep sanitizer builds serial or deliberately
+  low-parallel because template-heavy translation units can consume substantial memory.
+- Run `clang-tidy` after meaningful implementation or public-interface changes and before a milestone;
+  it is static analysis, not a replacement for compiler or runtime tests.
+- Before a substantial merge or milestone, run the full debug, release, sanitizer, and clang-tidy
+  matrix. CI may distribute those configurations across independent jobs.
+
+### Container validation
+
+The root `Dockerfile` builds the user-facing Ubuntu 26.04 CLI image. It performs an optimized native
+release build without tests, Python bindings, or host-specific `-march=native` instructions.
+
+`docker/Dockerfile.ubuntu-26.04`, `docker/Dockerfile.debian-13`, and `docker/Dockerfile.fedora-44` are
+developer compatibility containers. Each builds and tests the `gcc-release` configuration; run them one
+at a time because template-heavy builds consume substantial memory. Fedora is pinned to release 44; update
+that release intentionally before it reaches end of life.
+
+## C++ conventions
+
+- Use C++23. Public names remain under
+  `chargefw::{core,features,parameters,methods,charges,calculation,adapters}`.
+- Follow `.clang-format`: LLVM-derived, four spaces, 100-column limit, left-attached pointers and
+  references.
+- Prefer value ownership, `std::span` for read-only views, and explicit non-owning references/pointers
+  when caller lifetime is guaranteed.
+- Use exceptions for invalid inputs and calculation failures; preserve actionable target context.

chargefw-0.1/CMakeLists.txt

@@ -0,0 +1,114 @@
+cmake_minimum_required(VERSION 3.28)
+
+project(
+  chargefw
+  VERSION 0.1
+  DESCRIPTION "Empirical partial atomic charge calculation framework"
+  LANGUAGES CXX
+)
+
+include(GNUInstallDirs)
+include(CMakePackageConfigHelpers)
+
+file(RELATIVE_PATH CHARGEFW_PARAMETER_DIRECTORY_FROM_LIBRARY
+  "${CMAKE_INSTALL_FULL_LIBDIR}"
+  "${CMAKE_INSTALL_FULL_DATADIR}/chargefw/parameters"
+)
+
+option(CHARGEFW_ENABLE_CCACHE "Use ccache if available" ON)
+option(CHARGEFW_BUILD_TESTS "Build tests" ${PROJECT_IS_TOP_LEVEL})
+option(CHARGEFW_BUILD_CLI "Build the chargefw command-line application" ${PROJECT_IS_TOP_LEVEL})
+option(CHARGEFW_BUILD_PYTHON "Build the ChargeFW Python extension" OFF)
+set(CHARGEFW_PYTHON_EXECUTABLE "" CACHE FILEPATH
+    "Python interpreter for ChargeFW bindings (empty uses CMake discovery)")
+option(CHARGEFW_USE_SYSTEM_DEPENDENCIES "Prefer compatible system dependencies" OFF)
+option(CHARGEFW_ENABLE_WARNINGS "Enable project warnings" ON)
+option(CHARGEFW_ENABLE_ASAN "Enable AddressSanitizer" OFF)
+option(CHARGEFW_ENABLE_UBSAN "Enable UndefinedBehaviorSanitizer" OFF)
+option(CHARGEFW_ENABLE_CLANG_TIDY "Enable clang-tidy" OFF)
+option(CHARGEFW_ENABLE_NATIVE_OPTIMIZATIONS "Optimize for the build host CPU" ON)
+
+set(CMAKE_EXPORT_COMPILE_COMMANDS ON)
+set(CMAKE_CXX_SCAN_FOR_MODULES OFF)
+
+include(cmake/dependencies.cmake)
+include(cmake/developer_tools.cmake)
+include(cmake/optimization.cmake)
+include(cmake/warnings.cmake)
+include(cmake/sanitizers.cmake)
+
+chargefw_setup_dependencies()
+chargefw_setup_developer_tools()
+
+add_library(chargefw_core SHARED)
+add_library(chargefw::core ALIAS chargefw_core)
+set_target_properties(chargefw_core PROPERTIES EXPORT_NAME core)
+
+target_compile_features(chargefw_core
+  PUBLIC
+    cxx_std_23
+)
+
+target_include_directories(chargefw_core
+  PRIVATE
+    src
+
+  PUBLIC
+    $<BUILD_INTERFACE:${PROJECT_SOURCE_DIR}/include>
+    $<BUILD_INTERFACE:${PROJECT_BINARY_DIR}/generated>
+    $<INSTALL_INTERFACE:${CMAKE_INSTALL_INCLUDEDIR}>
+)
+
+target_link_libraries(chargefw_core
+  PUBLIC
+    nlohmann_json::nlohmann_json
+    gemmi::gemmi_cpp
+  PRIVATE
+    $<BUILD_LOCAL_INTERFACE:Eigen3::Eigen>
+    $<BUILD_LOCAL_INTERFACE:nanoflann::nanoflann>
+    TBB::tbb
+    $<BUILD_LOCAL_INTERFACE:${CMAKE_DL_LIBS}>
+)
+
+target_compile_definitions(chargefw_core
+  PRIVATE
+    EIGEN_DONT_PARALLELIZE
+)
+
+chargefw_enable_optimizations(chargefw_core)
+
+configure_file(
+  ${PROJECT_SOURCE_DIR}/include/chargefw/config.h.in
+  ${PROJECT_BINARY_DIR}/generated/chargefw/config.h
+  @ONLY
+)
+
+if(CHARGEFW_ENABLE_WARNINGS)
+  chargefw_enable_warnings(chargefw_core)
+endif()
+
+if(CHARGEFW_ENABLE_ASAN)
+  chargefw_enable_sanitizer(chargefw_core address)
+endif()
+
+if(CHARGEFW_ENABLE_UBSAN)
+  chargefw_enable_sanitizer(chargefw_core undefined)
+endif()
+
+add_subdirectory(src)
+
+if(CHARGEFW_BUILD_PYTHON)
+  add_subdirectory(python)
+endif()
+
+if(CHARGEFW_BUILD_CLI)
+  add_subdirectory(apps/chargefw)
+endif()
+
+if(CHARGEFW_BUILD_TESTS)
+  chargefw_setup_test_dependencies()
+  enable_testing()
+  add_subdirectory(tests)
+endif()
+
+include(cmake/install_rules.cmake)

chargefw-0.1/CMakePresets.json

@@ -0,0 +1,191 @@
+{
+  "version": 6,
+  "configurePresets": [
+    {
+      "name": "gcc-debug",
+      "displayName": "GCC Debug",
+      "generator": "Ninja",
+      "binaryDir": "${sourceDir}/build/gcc-debug",
+      "cacheVariables": {
+        "CMAKE_BUILD_TYPE": "Debug",
+        "CMAKE_CXX_COMPILER": "/usr/bin/g++",
+        "CMAKE_EXPORT_COMPILE_COMMANDS": "ON",
+        "CHARGEFW_BUILD_TESTS": "ON",
+        "CHARGEFW_BUILD_PYTHON": "ON",
+        "CHARGEFW_ENABLE_WARNINGS": "ON",
+        "CHARGEFW_PYTHON_EXECUTABLE": "/usr/bin/python3"
+      }
+    },
+    {
+      "name": "gcc-release",
+      "displayName": "GCC Release",
+      "inherits": "gcc-debug",
+      "binaryDir": "${sourceDir}/build/gcc-release",
+      "cacheVariables": {
+        "CMAKE_BUILD_TYPE": "Release",
+        "CMAKE_INTERPROCEDURAL_OPTIMIZATION": "ON"
+      }
+    },
+    {
+      "name": "clang-debug",
+      "displayName": "Clang Debug",
+      "generator": "Ninja",
+      "binaryDir": "${sourceDir}/build/clang-debug",
+      "cacheVariables": {
+        "CMAKE_BUILD_TYPE": "Debug",
+        "CMAKE_C_COMPILER": "/usr/bin/clang",
+        "CMAKE_CXX_COMPILER": "/usr/bin/clang++",
+        "CMAKE_EXPORT_COMPILE_COMMANDS": "ON",
+        "CHARGEFW_BUILD_TESTS": "ON",
+        "CHARGEFW_BUILD_PYTHON": "ON",
+        "CHARGEFW_ENABLE_WARNINGS": "ON",
+        "CHARGEFW_ENABLE_CLANG_TIDY": "OFF",
+        "CHARGEFW_PYTHON_EXECUTABLE": "/usr/bin/python3"
+      }
+    },
+    {
+      "name": "clang-release",
+      "displayName": "Clang Release",
+      "inherits": "clang-debug",
+      "binaryDir": "${sourceDir}/build/clang-release",
+      "cacheVariables": {
+        "CMAKE_BUILD_TYPE": "Release",
+        "CMAKE_INTERPROCEDURAL_OPTIMIZATION": "ON"
+      }
+    },
+    {
+      "name": "clang-asan",
+      "displayName": "Clang ASan",
+      "inherits": "clang-debug",
+      "binaryDir": "${sourceDir}/build/clang-asan",
+      "cacheVariables": {
+        "CHARGEFW_BUILD_PYTHON": "ON",
+        "CHARGEFW_ENABLE_ASAN": "ON"
+      }
+    },
+    {
+      "name": "clang-ubsan",
+      "displayName": "Clang UBSan",
+      "inherits": "clang-debug",
+      "binaryDir": "${sourceDir}/build/clang-ubsan",
+      "cacheVariables": {
+        "CHARGEFW_BUILD_PYTHON": "ON",
+        "CHARGEFW_ENABLE_UBSAN": "ON"
+      }
+    },
+    {
+      "name": "clang-tidy",
+      "displayName": "Clang Tidy",
+      "inherits": "clang-debug",
+      "binaryDir": "${sourceDir}/build/clang-tidy",
+      "cacheVariables": {
+        "CHARGEFW_BUILD_PYTHON": "ON",
+        "CHARGEFW_ENABLE_CLANG_TIDY": "ON"
+      }
+    }
+  ],
+  "buildPresets": [
+    {
+      "name": "gcc-debug",
+      "configurePreset": "gcc-debug"
+    },
+    {
+      "name": "gcc-release",
+      "configurePreset": "gcc-release"
+    },
+    {
+      "name": "clang-debug",
+      "configurePreset": "clang-debug"
+    },
+    {
+      "name": "clang-release",
+      "configurePreset": "clang-release"
+    },
+    {
+      "name": "clang-asan",
+      "configurePreset": "clang-asan"
+    },
+    {
+      "name": "clang-ubsan",
+      "configurePreset": "clang-ubsan"
+    },
+    {
+      "name": "clang-tidy",
+      "configurePreset": "clang-tidy"
+    }
+  ],
+  "testPresets": [
+    {
+      "name": "gcc-debug",
+      "configurePreset": "gcc-debug",
+      "filter": {
+        "exclude": {
+          "name": "^cpptest$"
+        }
+      },
+      "output": {
+        "outputOnFailure": true
+      }
+    },
+    {
+      "name": "clang-asan",
+      "configurePreset": "clang-asan",
+      "filter": {
+        "exclude": {
+          "name": "^cpptest$"
+        }
+      },
+      "output": {
+        "outputOnFailure": true
+      }
+    },
+    {
+      "name": "clang-debug",
+      "configurePreset": "clang-debug",
+      "filter": {
+        "exclude": {
+          "name": "^cpptest$"
+        }
+      },
+      "output": {
+        "outputOnFailure": true
+      }
+    },
+    {
+      "name": "gcc-release",
+      "configurePreset": "gcc-release",
+      "filter": {
+        "exclude": {
+          "name": "^cpptest$"
+        }
+      },
+      "output": {
+        "outputOnFailure": true
+      }
+    },
+    {
+      "name": "clang-release",
+      "configurePreset": "clang-release",
+      "filter": {
+        "exclude": {
+          "name": "^cpptest$"
+        }
+      },
+      "output": {
+        "outputOnFailure": true
+      }
+    },
+    {
+      "name": "clang-ubsan",
+      "configurePreset": "clang-ubsan",
+      "filter": {
+        "exclude": {
+          "name": "^cpptest$"
+        }
+      },
+      "output": {
+        "outputOnFailure": true
+      }
+    }
+  ]
+}

chargefw-0.1/Dockerfile

@@ -0,0 +1,35 @@
+FROM ubuntu:26.04 AS build
+
+ENV DEBIAN_FRONTEND=noninteractive
+
+RUN apt-get update && apt-get install --yes --no-install-recommends \
+    build-essential \
+    ca-certificates \
+    cmake \
+    ninja-build \
+    && rm -rf /var/lib/apt/lists/*
+
+WORKDIR /source
+COPY . .
+
+RUN cmake -S . -B /build -G Ninja \
+        -DCMAKE_BUILD_TYPE=Release \
+        -DCMAKE_INTERPROCEDURAL_OPTIMIZATION=ON \
+        -DCHARGEFW_BUILD_CLI=ON \
+        -DCHARGEFW_BUILD_PYTHON=OFF \
+        -DCHARGEFW_BUILD_TESTS=OFF \
+        -DCHARGEFW_ENABLE_NATIVE_OPTIMIZATIONS=OFF \
+    && cmake --build /build --target chargefw_cli --parallel \
+    && cmake --install /build --prefix /opt/chargefw --strip
+
+FROM ubuntu:26.04
+
+RUN apt-get update && apt-get install --yes --no-install-recommends \
+    libstdc++6 \
+    zlib1g \
+    && rm -rf /var/lib/apt/lists/*
+
+COPY --from=build /opt/chargefw /opt/chargefw
+
+ENTRYPOINT ["/opt/chargefw/bin/chargefw"]
+CMD ["--help"]

chargefw-0.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Tomáš Raček
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.