qmfcalc 0.1.0__tar.gz

qmfcalc-0.1.0/.github/workflows/publish-pypi.yml

@@ -0,0 +1,88 @@
+name: Publish to PyPI
+
+on:
+  release:
+    types: [published]
+
+jobs:
+  sdist:
+    name: Build source distribution
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Check out source
+        uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.13"
+
+      - name: Build sdist
+        run: |
+          python -m pip install --upgrade pip build
+          python -m build --sdist --outdir dist
+
+      - name: Upload sdist
+        uses: actions/upload-artifact@v4
+        with:
+          name: qmfcalc-sdist
+          path: dist/*.tar.gz
+
+  wheels:
+    name: Build wheel
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, windows-latest]
+
+    steps:
+      - name: Check out source
+        uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.13"
+
+      - name: Build wheel
+        uses: pypa/cibuildwheel@v4.1.0
+        env:
+          CIBW_BUILD: cp313-*
+          CIBW_ARCHS_LINUX: x86_64
+          CIBW_ARCHS_WINDOWS: AMD64
+          CIBW_SKIP: "*-musllinux_*"
+          CIBW_TEST_COMMAND: >-
+            python -c "import qmfcalc; r = qmfcalc.calculate_voltages(15.0, 250.0, 250.0, 1.0); assert r['rf_voltage_v'] > 0.0; assert r['dc_voltage_v'] > 0.0; print(r)"
+        with:
+          output-dir: dist
+
+      - name: Upload wheel
+        uses: actions/upload-artifact@v4
+        with:
+          name: qmfcalc-${{ matrix.os }}-py3.13-wheel
+          path: dist/*.whl
+
+  publish:
+    name: Publish distributions to PyPI
+    runs-on: ubuntu-latest
+    needs: [sdist, wheels]
+    environment: pypi
+    permissions:
+      id-token: write
+      contents: read
+
+    steps:
+      - name: Download distributions
+        uses: actions/download-artifact@v4
+        with:
+          pattern: qmfcalc-*
+          merge-multiple: true
+          path: dist
+
+      - name: List distributions
+        run: ls -l dist
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

qmfcalc-0.1.0/.github/workflows/python-package.yml

@@ -0,0 +1,43 @@
+name: Python package
+
+on:
+  push:
+  pull_request:
+  workflow_dispatch:
+
+jobs:
+  wheel:
+    name: Build wheel
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, windows-latest]
+        python-version: ["3.13"]
+
+    steps:
+      - name: Check out source
+        uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Build wheel
+        uses: pypa/cibuildwheel@v4.1.0
+        env:
+          CIBW_BUILD: cp313-*
+          CIBW_ARCHS_LINUX: x86_64
+          CIBW_ARCHS_WINDOWS: AMD64
+          CIBW_SKIP: "*-musllinux_*"
+          CIBW_TEST_COMMAND: >-
+            python -c "import qmfcalc; r = qmfcalc.calculate_voltages(15.0, 250.0, 250.0, 1.0); assert r['rf_voltage_v'] > 0.0; assert r['dc_voltage_v'] > 0.0; print(r)"
+        with:
+          output-dir: wheelhouse
+
+      - name: Upload wheel
+        uses: actions/upload-artifact@v4
+        with:
+          name: qmfcalc-${{ matrix.os }}-py${{ matrix.python-version }}-wheel
+          path: wheelhouse/*.whl

qmfcalc-0.1.0/.gitignore

@@ -0,0 +1,7 @@
+*.clangd
+build/
+dist/
+wheelhouse/
+*.egg-info/
+__pycache__/
+*.pyc

qmfcalc-0.1.0/.gitmodules

@@ -0,0 +1,3 @@
+[submodule "ext/roothelper"]
+	path = ext/roothelper
+	url = https://github.com/kenji0923/roothelper.git

qmfcalc-0.1.0/CMakeLists.txt

@@ -0,0 +1,88 @@
+# -----
+# Fundamental settings
+# -----
+
+cmake_minimum_required(VERSION 3.28 FATAL_ERROR)
+
+project(qmfcalc VERSION 0.1.0 LANGUAGES CXX)
+
+set(CMAKE_CXX_STANDARD 17)
+set(CMAKE_CXX_STANDARD_REQUIRED True)
+
+option(BUILD_SHARED_LIBS "Build using shared libraries" OFF)
+option(QMFCALC_BUILD_EXECUTABLES "Build ROOT-backed command line executables" ON)
+option(QMFCALC_BUILD_DOCS "Build Doxygen documentation target" ON)
+option(QMFCALC_BUILD_PYTHON "Build Python extension module" OFF)
+
+if(QMFCALC_BUILD_PYTHON)
+    set(CMAKE_POSITION_INDEPENDENT_CODE ON)
+endif()
+
+if(NOT CMAKE_BUILD_TYPE)
+    set(CMAKE_BUILD_TYPE Release)
+endif()
+
+
+# -----
+# External packages
+# -----
+
+include(FetchContent)
+
+if(QMFCALC_BUILD_EXECUTABLES)
+    # argparse: command line argument parsing (header-only).
+    FetchContent_Declare(
+	argparse
+	GIT_REPOSITORY https://github.com/p-ranav/argparse.git
+	GIT_TAG v3.2
+    )
+
+    # fkYAML: YAML serialization for result output (header-only).
+    FetchContent_Declare(
+	fkYAML
+	GIT_REPOSITORY https://github.com/fktn-k/fkYAML.git
+	GIT_TAG v0.4.2
+    )
+
+    FetchContent_MakeAvailable(argparse fkYAML)
+
+    find_package(ROOT REQUIRED COMPONENTS Core Hist Gpad Tree RIO)
+
+    # roothelper (CERN ROOT data management and plot formatting) provides the
+    # RootHelper INTERFACE target. Its own CMake calls find_package(ROOT).
+    add_subdirectory(${PROJECT_SOURCE_DIR}/ext/roothelper)
+endif()
+
+if(QMFCALC_BUILD_PYTHON)
+    find_package(Python COMPONENTS Interpreter Development.Module REQUIRED)
+    set(PYBIND11_FINDPYTHON ON)
+    find_package(pybind11 CONFIG QUIET)
+
+    if(NOT pybind11_FOUND)
+	FetchContent_Declare(
+	    pybind11
+	    GIT_REPOSITORY https://github.com/pybind/pybind11.git
+	    GIT_TAG v2.13.6
+	)
+	FetchContent_MakeAvailable(pybind11)
+    endif()
+endif()
+
+
+# -----
+# Sub-directories
+# -----
+
+add_subdirectory(${PROJECT_SOURCE_DIR}/core)
+
+if(QMFCALC_BUILD_DOCS)
+    add_subdirectory(${PROJECT_SOURCE_DIR}/doc)
+endif()
+
+if(QMFCALC_BUILD_EXECUTABLES)
+    add_subdirectory(${PROJECT_SOURCE_DIR}/exec)
+endif()
+
+if(QMFCALC_BUILD_PYTHON)
+    add_subdirectory(${PROJECT_SOURCE_DIR}/python)
+endif()

qmfcalc-0.1.0/PKG-INFO

@@ -0,0 +1,71 @@
+Metadata-Version: 2.2
+Name: qmfcalc
+Version: 0.1.0
+Summary: Python bindings for quadrupole mass filter voltage calculations
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: C++
+Classifier: Topic :: Scientific/Engineering :: Physics
+Requires-Python: >=3.13
+Description-Content-Type: text/markdown
+
+# qmfcalc
+
+Quadrupole mass filter calculation utilities.
+
+## Python
+
+The Python package builds a native extension with `pybind11`:
+
+```sh
+python -m pip install .
+```
+
+Python 3.13 is the supported target.
+
+or directly from a Git checkout:
+
+```sh
+python -m pip install git+https://github.com/<owner>/<repo>.git
+```
+
+Use it from Python:
+
+```python
+import qmfcalc
+
+result = qmfcalc.calculate_voltages(
+    r0_mm=15.0,
+    target_m_over_q_amu_per_z=250.0,
+    resolution=250.0,
+    rf_frequency_mhz=1.0,
+)
+
+print(result["rf_voltage_v"], result["dc_voltage_v"])
+```
+
+`rf_voltage_v` is the per-rod peak-to-peak RF voltage. `dc_voltage_v` is the
+pole-to-pole DC voltage.
+
+The GitHub Actions workflow in `.github/workflows/python-package.yml` builds and
+tests Python 3.13 Linux and Windows wheels on pushes and pull requests.
+
+## PyPI release
+
+Configure a PyPI pending trusted publisher with:
+
+- PyPI project name: `qmfcalc`
+- Owner: `kenji0923`
+- Repository: `qmfcalc`
+- Workflow name: `publish-pypi.yml`
+- Environment name: `pypi`
+
+Then publish a GitHub Release from a version tag, for example:
+
+```sh
+git tag v0.1.0
+git push origin v0.1.0
+```
+
+The `.github/workflows/publish-pypi.yml` workflow builds the Python 3.13 Linux
+and Windows wheels, builds the source distribution, and publishes them to PyPI.

qmfcalc-0.1.0/README.md

@@ -0,0 +1,60 @@
+# qmfcalc
+
+Quadrupole mass filter calculation utilities.
+
+## Python
+
+The Python package builds a native extension with `pybind11`:
+
+```sh
+python -m pip install .
+```
+
+Python 3.13 is the supported target.
+
+or directly from a Git checkout:
+
+```sh
+python -m pip install git+https://github.com/<owner>/<repo>.git
+```
+
+Use it from Python:
+
+```python
+import qmfcalc
+
+result = qmfcalc.calculate_voltages(
+    r0_mm=15.0,
+    target_m_over_q_amu_per_z=250.0,
+    resolution=250.0,
+    rf_frequency_mhz=1.0,
+)
+
+print(result["rf_voltage_v"], result["dc_voltage_v"])
+```
+
+`rf_voltage_v` is the per-rod peak-to-peak RF voltage. `dc_voltage_v` is the
+pole-to-pole DC voltage.
+
+The GitHub Actions workflow in `.github/workflows/python-package.yml` builds and
+tests Python 3.13 Linux and Windows wheels on pushes and pull requests.
+
+## PyPI release
+
+Configure a PyPI pending trusted publisher with:
+
+- PyPI project name: `qmfcalc`
+- Owner: `kenji0923`
+- Repository: `qmfcalc`
+- Workflow name: `publish-pypi.yml`
+- Environment name: `pypi`
+
+Then publish a GitHub Release from a version tag, for example:
+
+```sh
+git tag v0.1.0
+git push origin v0.1.0
+```
+
+The `.github/workflows/publish-pypi.yml` workflow builds the Python 3.13 Linux
+and Windows wheels, builds the source distribution, and publishes them to PyPI.

qmfcalc-0.1.0/core/CMakeLists.txt

@@ -0,0 +1,46 @@
+# ----- Custom function definition start -----
+
+# Add the standard include directory.
+function(add_include_directory_std target_name scope)
+    target_include_directories(${target_name} ${scope}
+	$<BUILD_INTERFACE:${CMAKE_CURRENT_SOURCE_DIR}/include>
+	$<INSTALL_INTERFACE:$<INSTALL_PREFIX>/include/${PROJECT_NAME}>
+    )
+endfunction()
+
+# Add library with a standard filenames
+# The third argument can be used for specifying library type (STATIC|SHARED|INTERFACE)
+function(add_library_std target_name library_file_name)
+    set(library_type "")
+
+    if(${ARGC} GREATER 2)
+	set(library_type ${ARGV2})
+    endif()
+
+    set(include_scope "PUBLIC")
+
+    if("${library_type}" STREQUAL "INTERFACE")
+	add_library(${target_name} ${library_type} include/${PROJECT_NAME}/${library_file_name}.h)
+	set(include_scope "INTERFACE")
+    else()
+	add_library(${target_name} ${library_type} ${library_file_name}.cpp include/${PROJECT_NAME}/${library_file_name}.h)
+    endif()
+
+    add_include_directory_std(${target_name} ${include_scope})
+
+    add_library(${PROJECT_NAME}::${target_name} ALIAS ${target_name})
+endfunction()
+
+# ----- Function definiion end -----
+
+add_library_std(StabilityDiagram stability_diagram INTERFACE)
+
+add_library_std(ResolutionEstimator resolution_estimator)
+target_link_libraries(ResolutionEstimator PUBLIC
+    StabilityDiagram
+)
+
+add_library_std(VoltageCalculator voltage_calculator)
+target_link_libraries(VoltageCalculator PUBLIC
+    ResolutionEstimator
+)

qmfcalc-0.1.0/core/include/qmfcalc/ion_config.h

@@ -0,0 +1,65 @@
+#ifndef QMFCALC_ION_CONFIG_H
+#define QMFCALC_ION_CONFIG_H
+
+
+#include <vector>
+
+
+namespace qmfcalc {
+
+
+struct IonMotion
+{
+    IonMotion(
+	    const double x,
+	    const double y,
+	    const double v_x,
+	    const double v_y,
+	    const double v_z
+	)
+    :	 x(x),
+	y(y),
+	v_x(v_x),
+	v_y(v_y),
+	v_z(v_z)
+    { }
+
+    double x;
+    double y;
+    double v_x;
+    double v_y;
+    double v_z;
+};
+
+
+struct IonSet
+{
+    IonSet(
+	    const double mass,
+	    const std::vector<IonMotion>& motions
+	)
+    :	mass(mass),
+    	motions(motions)
+    { }
+
+    const double mass;
+    const std::vector<IonMotion> motions;
+};
+
+
+struct PhaseSpacePoint
+{
+    static double get_u_dot(const double omega, const double v) { return 2. / omega * v; }
+
+    PhaseSpacePoint(const double omega, const double u, const double v) : omega(omega), u(u), u_dot(get_u_dot(omega, v)) { }
+
+    const double omega;
+    double u;
+    double u_dot;
+};
+
+
+} // namespace qmfcalc
+
+
+#endif

qmfcalc-0.1.0/core/include/qmfcalc/matrix_method_calculator.h

@@ -0,0 +1,43 @@
+#ifndef QMFCALC_MATRIX_METHOD_CALCULATOR_H
+#define QMFCALC_MATRIX_METHOD_CALCULATOR_H
+
+
+#include <array>
+#include <vector>
+
+#include <qmfcalc/ion_config.h>
+#include <qmfcalc/result.h>
+#include <qmfcalc/rod_config.h>
+
+
+namespace qmfcalc {
+
+
+class MatrixMethodCalculator
+{
+public:
+    // double get_efficiency(const double mass, const Result::PhaseSpacePoint& initial_point) const;
+
+    double get_u_max_infinite_length(
+	    const double mass,
+	    const IonMotion& ion_motion,
+	    const double rod_length
+	) const;
+
+    std::vector<Result::Efficiency> get_efficiency_mass_spectrum_infinite_length(
+	    const std::array<double, 2>& mass_range,
+	    const double mass_step,
+	    const std::vector<IonMotion>& ion_motions,
+	    const RodConfig& rod_config
+	) const;
+
+private:
+    const double RF_omega_;
+    const double RF_period_;
+};
+
+
+} // namespace qmfcalc
+
+
+#endif

qmfcalc-0.1.0/core/include/qmfcalc/resolution_estimator.h

@@ -0,0 +1,49 @@
+#ifndef QMFCALC_RESOLUTION_ESTIMATOR_H
+#define QMFCALC_RESOLUTION_ESTIMATOR_H
+
+
+namespace qmfcalc {
+
+
+// Result of estimating the mass resolution for a single operating line.
+//
+// In a quadrupole mass filter every mass sits on a scan line through the origin
+// of the (q, a) diagram with slope k = a/q = 2U/V (mass independent for fixed
+// rod voltages, frequency and geometry). The line crosses the tip of the first
+// stability region at q_low (rising a0 branch) and q_high (falling b1 branch).
+// Because q is proportional to 1/m, the transmitted mass band corresponds to the
+// q-window delta_q = q_high - q_low, giving m/dm = q_center / delta_q.
+struct ResolutionEstimate
+{
+    bool transmitted;       // false if the scan line clears the apex (no window)
+    double slope;           // k = a/q of the operating line
+    double q_low;           // crossing on the rising a0 branch
+    double q_high;          // crossing on the falling b1 branch
+    double q_center;        // (q_low + q_high) / 2 : transmitted mass center in q
+    double a_center;        // slope * q_center
+    double delta_q;         // q_high - q_low
+    double mass_resolution; // m/dm = q_center / delta_q
+};
+
+
+// Estimate the mass resolution from the line through the origin and (q, a).
+// Only the slope a/q matters; q is required to be non-zero.
+ResolutionEstimate estimate_mass_resolution(double q, double a);
+
+
+// Estimate the mass resolution directly from the operating-line slope k = a/q.
+ResolutionEstimate estimate_mass_resolution_from_slope(double slope);
+
+
+// Inverse of the estimator: the operating-line slope (i.e. the 2U/V ratio)
+// whose window yields target_resolution. The resolution increases monotonically
+// as the slope approaches the apex slope, so a bisection on (0, apex slope) is
+// used. Returns a negative value if target_resolution is below the minimum
+// achievable. This is the kernel of the future RF/DC amplitude solver.
+double find_slope_for_mass_resolution(double target_resolution);
+
+
+} // namespace qmfcalc
+
+
+#endif

qmfcalc-0.1.0/core/include/qmfcalc/result.h

@@ -0,0 +1,26 @@
+#ifndef QMFCALC_RESULT_H
+#define QMFCALC_RESULT_H
+
+
+namespace qmfcalc {
+
+
+namespace Result {
+
+
+struct Efficiency
+{
+    Efficiency(const double mass, const double transmission) : mass(mass), transmission(transmission) { }
+
+    const double mass;
+    const double transmission;
+};
+
+
+} // namespace qmfcalc::Result
+
+
+} // namespace qmfcalc
+
+
+#endif

qmfcalc-0.1.0/core/include/qmfcalc/rod_config.h

@@ -0,0 +1,20 @@
+#ifndef QMFCALC_ROD_CONFIG_H
+#define QMFCALC_ROD_CONFIG_H
+
+
+namespace qmfcalc {
+
+
+struct RodConfig
+{
+    RodConfig(const double u_max_acceptable, const double length) : u_max_acceptable(u_max_acceptable), length(length) { }
+
+    const double u_max_acceptable;
+    const double length;
+};
+
+
+} // namespace qmfcalc
+
+
+#endif

qmfcalc-0.1.0/core/include/qmfcalc/stability_diagram.h

@@ -0,0 +1,57 @@
+#ifndef QMFCALC_STABILITY_DIAGRAM_H
+#define QMFCALC_STABILITY_DIAGRAM_H
+
+
+#include <cmath>
+
+
+namespace qmfcalc {
+
+
+// q value of the apex (tip) of the first stability region, where the rising
+// a0 branch and the falling b1 branch meet.
+constexpr double kFirstStabilityQPeak = 0.706252;
+
+// q value where the falling b1 branch returns to a = 0 (right end of the tip).
+constexpr double kFirstStabilityQMax = 0.909104;
+
+
+// Upper boundary of the first stability region of the Mathieu equation as a
+// single-valued function of q. The region's tip is bounded by two branches that
+// meet at (kFirstStabilityQPeak, apex):
+//   - q <  q_peak : rising a0 characteristic curve
+//   - q >= q_peak : falling b1 characteristic curve
+// Asymptotic series expansions are used for each branch.
+inline double get_first_stability_boundary(const double q, const double q_peak = kFirstStabilityQPeak)
+{
+    const double q2 = std::pow(q, 2);
+    const double q4 = std::pow(q, 4);
+    const double q6 = std::pow(q, 6);
+    const double q8 = std::pow(q, 8);
+
+    if (q < q_peak) {
+	const double a0 = -q2 / 2 + 7 * q4 / 128 - 29 * q6 / 2304 + 68687 * q8 / 18874368;
+	return -a0;
+    } else {
+	const double q3 = std::pow(q, 3);
+	const double q5 = std::pow(q, 5);
+	const double q7 = std::pow(q, 7);
+
+	const double b1 = 1 - q - q2 / 8 + q3 / 64 + q4 / 1536 + 11 * q5 / 36864 + 49 * q6 / 589824 - 55 * q7 / 9437184 - 265 * q8 / 113246208;
+
+	return b1;
+    }
+}
+
+
+// a value of the apex of the first stability region (a_peak ~ 0.237).
+inline double get_first_stability_apex_a(const double q_peak = kFirstStabilityQPeak)
+{
+    return get_first_stability_boundary(q_peak, q_peak);
+}
+
+
+} // namespace qmfcalc
+
+
+#endif