RNG Functionality Support

.github/workflows/python-release.yml

@@ -198,10 +198,16 @@ jobs:
       - name: Install pecos-rslib
         run: pip install ./pecos-rslib-wheel/*.whl
 
-      - name: Install build dependencies
+      - name: Install pecos RNG build dependencies
         run: |
-          python -m pip install --upgrade pip
-          pip install build
+          pip install build nanobind
+
+      - name: Build PECOS RNG
+        run: |
+          cd clibs/pecos-rng && mkdir build && cd build/ && cmake ..
+          make && cd .. && pip install .
+        env:
+            NANOBIND_DIR: python -m nanobind --include_dir
 
       - name: Build quantum-pecos SDist
         run: |
@@ -249,10 +255,16 @@ jobs:
       - name: Install pecos-rslib
         run: pip install ./pecos-rslib-wheel/*.whl
 
-      - name: Install build dependencies
+      - name: Install pecos rng build dependencies
+        run: |
+          pip install build nanobind
+
+      - name: Build PECOS RNG
         run: |
-          python -m pip install --upgrade pip
-          pip install build
+          cd clibs/pecos-rng && mkdir build && cd build/ && cmake ..
+          make && cd .. && pip install .
+        env:
+            NANOBIND_DIR: python -m nanobind --include_dir
 
       - name: Build quantum-pecos wheel
         run: |

.github/workflows/python-test.yml

@@ -69,6 +69,18 @@ jobs:
         uv lock --project .
         uv sync --project .
 
+    - name: Install pecos rng build dependencies
+      run: |
+        uv pip install build nanobind scikit-build-core cmake ninja
+
+    - name: Build PECOS RNG
+      run: |
+        export NANOBIND_CMAKE_DIR=$(uv run -- python -m nanobind --cmake_dir)
+        export NANOBIND_DIR=$(uv run -- python -m nanobind --include_dir)
+        cd clibs/pecos-rng && mkdir build && cd build/ && cmake .. -DCMAKE_PREFIX_PATH=$NANOBIND_CMAKE_DIR
+        cmake --build . && cd ..
+        uv pip install .
+
     - name: Install pecos-rslib with maturin
       run: |
         cd python/pecos-rslib

.gitignore

@@ -32,7 +32,6 @@ dist/
 downloads/
 eggs/
 .eggs/
-lib/
 lib64/
 parts/
 sdist/
@@ -177,3 +176,7 @@ cython_debug/
 #  and can be added to the global gitignore or merged into this file.  For a more nuclear
 #  option (not recommended) you can uncomment the following to ignore the entire idea folder.
 .idea/
+
+# Prevent subdirectory virtual environments
+clibs/*/.venv/
+clibs/*/uv.lock

Makefile

@@ -2,7 +2,6 @@
 
 # Try to autodetect if python3 or python is the python executable used.
 PYTHONPATH := $(shell which python 2>/dev/null || which python3 2>/dev/null)
-
 SHELL=bash
 
 # Requirements
@@ -20,27 +19,37 @@ installreqs: ## Install Python project requirements to root .venv
 	@echo "Installing requirements..."
 	uv sync
 
+.PHONY: buildrng
+buildrng:
+	@echo "Building and installing RNG library..."
+	uv pip install nanobind
+	cd clibs/pecos-rng && CC=gcc CXX=g++ uv pip install --python $(shell uv run which python) -e .
+
 # Building development environments
 # ---------------------------------
 .PHONY: build
 build: installreqs ## Compile and install for development
 	@unset CONDA_PREFIX && cd python/pecos-rslib/ && uv run maturin develop --uv
+	$(MAKE) buildrng
 	@unset CONDA_PREFIX && cd python/quantum-pecos && uv pip install -e .[all]
 
 .PHONY: build-basic
 build-basic: installreqs ## Compile and install for development but do not include install extras
 	@unset CONDA_PREFIX && cd python/pecos-rslib/ && uv run maturin develop --uv
+	$(MAKE) buildrng
 	@unset CONDA_PREFIX && cd python/quantum-pecos && uv pip install -e .
 
 .PHONY: build-release
 build-release: installreqs ## Build a faster version of binaries
 	@unset CONDA_PREFIX && cd python/pecos-rslib/ && uv run maturin develop --uv --release
+	$(MAKE) buildrng
 	@unset CONDA_PREFIX && cd python/quantum-pecos && uv pip install -e .[all]
 
 .PHONY: build-native
 build-native: installreqs ## Build a faster version of binaries with native CPU optimization
 	@unset CONDA_PREFIX && cd python/pecos-rslib/ && RUSTFLAGS='-C target-cpu=native' \
 	&& uv run maturin develop --uv --release
+	$(MAKE) buildrng
 	@unset CONDA_PREFIX && cd python/quantum-pecos && uv pip install -e .[all]
 
 # Documentation
@@ -146,6 +155,12 @@ clean-unix:
 	@find . -type d -name "junit" -exec rm -rf {} +
 	@find python -name "*.so" -delete
 	@find python -name "*.pyd" -delete
+	@# Clean clibs build artifacts
+	@find clibs -type d -name "build" -exec rm -rf {} +
+	@find clibs -type d -name "dist" -exec rm -rf {} +
+	@find clibs -type d -name "*.egg-info" -exec rm -rf {} +
+	@find clibs -type d -name ".venv" -exec rm -rf {} +
+	@find clibs -name "uv.lock" -delete
 	@# Clean all target directories in crates (in case they were built independently)
 	@find crates -type d -name "target" -exec rm -rf {} +
 	@find python -type d -name "target" -exec rm -rf {} +
@@ -167,6 +182,12 @@ clean-windows-ps:
 	@powershell -Command "Get-ChildItem -Path . -Recurse -Directory -Filter '.hypothesis' | Remove-Item -Recurse -Force -ErrorAction SilentlyContinue"
 	@powershell -Command "Get-ChildItem -Path . -Recurse -Directory -Filter 'junit' | Remove-Item -Recurse -Force -ErrorAction SilentlyContinue"
 	@powershell -Command "Get-ChildItem -Path python -Recurse -File -Include '*.so','*.pyd' | Remove-Item -Force -ErrorAction SilentlyContinue"
+	@# Clean clibs build artifacts
+	@powershell -Command "Get-ChildItem -Path clibs -Recurse -Directory -Filter 'build' | Remove-Item -Recurse -Force -ErrorAction SilentlyContinue"
+	@powershell -Command "Get-ChildItem -Path clibs -Recurse -Directory -Filter 'dist' | Remove-Item -Recurse -Force -ErrorAction SilentlyContinue"
+	@powershell -Command "Get-ChildItem -Path clibs -Recurse -Directory -Filter '*.egg-info' | Remove-Item -Recurse -Force -ErrorAction SilentlyContinue"
+	@powershell -Command "Get-ChildItem -Path clibs -Recurse -Directory -Filter '.venv' | Remove-Item -Recurse -Force -ErrorAction SilentlyContinue"
+	@powershell -Command "Get-ChildItem -Path clibs -Recurse -File -Filter 'uv.lock' | Remove-Item -Force -ErrorAction SilentlyContinue"
 	@# Clean all target directories in crates
 	@powershell -Command "Get-ChildItem -Path crates -Recurse -Directory -Filter 'target' | Remove-Item -Recurse -Force -ErrorAction SilentlyContinue"
 	@powershell -Command "Get-ChildItem -Path python -Recurse -Directory -Filter 'target' | Remove-Item -Recurse -Force -ErrorAction SilentlyContinue"
@@ -187,6 +208,12 @@ clean-windows-cmd:
 	-@for /f "delims=" %%d in ('dir /s /b /ad .hypothesis 2^>nul') do @rd /s /q "%%d" 2>nul
 	-@for /f "delims=" %%d in ('dir /s /b /ad junit 2^>nul') do @rd /s /q "%%d" 2>nul
 	-@for /f "delims=" %%f in ('dir /s /b python\*.so python\*.pyd 2^>nul') do @del "%%f" 2>nul
+	-@REM Clean clibs build artifacts
+	-@for /f "delims=" %%d in ('dir /s /b /ad clibs\build 2^>nul') do @rd /s /q "%%d" 2>nul
+	-@for /f "delims=" %%d in ('dir /s /b /ad clibs\dist 2^>nul') do @rd /s /q "%%d" 2>nul
+	-@for /f "delims=" %%d in ('dir /s /b /ad clibs\*.egg-info 2^>nul') do @rd /s /q "%%d" 2>nul
+	-@for /f "delims=" %%d in ('dir /s /b /ad clibs\.venv 2^>nul') do @rd /s /q "%%d" 2>nul
+	-@for /f "delims=" %%f in ('dir /s /b clibs\uv.lock 2^>nul') do @del "%%f" 2>nul
 	-@REM Clean all target directories in crates
 	-@for /f "delims=" %%d in ('dir /s /b /ad crates\target 2^>nul') do @rd /s /q "%%d" 2>nul
 	-@for /f "delims=" %%d in ('dir /s /b /ad python\target 2^>nul') do @rd /s /q "%%d" 2>nul
@@ -201,10 +228,10 @@ pip-install-uv:  ## Install uv using pip and create a venv. (Recommended to inst
 	@echo "Creating venv and installing dependencies..."
 	uv sync
 
-.PONY: dev
+.PHONY: dev
 dev: clean build test  ## Run the typical sequence of commands to check everything is running correctly
 
-.PONY: devl  ## Run the commands to make sure everything runs + lint
+.PHONY: devl  ## Run the commands to make sure everything runs + lint
 devl: dev lint
 
 # Help

clibs/pecos-rng/CMakeLists.txt

@@ -0,0 +1,34 @@
+# CMakeLists.txt
+cmake_minimum_required(VERSION 3.15...3.27)
+project(pecos_rng LANGUAGES C CXX)
+set(CMAKE_OSX_ARCHITECTURES "x86_64;arm64")
+
+
+if (CMAKE_VERSION VERSION_LESS 3.18)
+  set(DEV_MODULE Development)
+else()
+  set(DEV_MODULE Development.Module)
+endif()
+
+# Find Python (for Python 3.13)
+find_package(Python REQUIRED COMPONENTS Interpreter ${DEV_MODULE})
+
+# Detect the installed nanobind package and import it into CMake
+# This executes a Python command to get the nanobind CMake directory
+execute_process(
+    COMMAND "${Python_EXECUTABLE}" -m nanobind --cmake_dir
+    OUTPUT_STRIP_TRAILING_WHITESPACE
+    OUTPUT_VARIABLE nanobind_ROOT
+)
+
+set(CMAKE_PREFIX_PATH "${nanobind_ROOT}" ${CMAKE_PREFIX_PATH})
+
+# This sets up nanobind
+find_package(nanobind CONFIG REQUIRED)
+
+# Add your C source file as a library
+add_library(rng_pcg STATIC src/rng_pcg.c) # Compile test.c as a static library
+nanobind_add_module(pecos_rng src/wrapper.cpp)
+target_link_libraries(pecos_rng PRIVATE rng_pcg)
+# Install the module so it can be found by pip install
+install(TARGETS pecos_rng DESTINATION "pecos_pcg")

clibs/pecos-rng/pecos_pcg/__init__.py

@@ -0,0 +1,10 @@
+"""Python Package responsible for generating random numbers using pcg_rng."""
+
+from .pecos_rng import (
+    pcg32_boundedrand,
+    pcg32_frandom,
+    pcg32_random,
+    pcg32_srandom,
+)
+
+__all__ = ["pcg32_boundedrand", "pcg32_frandom", "pcg32_random", "pcg32_srandom"]

clibs/pecos-rng/pyproject.toml

@@ -0,0 +1,22 @@
+[build-system]
+requires = ["scikit-build-core[pyproject]", "nanobind"]
+build-backend = "scikit_build_core.build"
+
+[project]
+name = "pecos-pcg"
+version = "0.1.0"
+description = "A Python package with a nanobind-based C++ extension"
+license = { text = "MIT" }
+readme = "README.md"
+requires-python = ">=3.8"
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "Programming Language :: C++",
+    "License :: OSI Approved :: MIT License"
+]
+
+[tool.scikit-build]
+wheel.packages = ["pecos_pcg"]
+# Optional: set cmake minimum version or other CMake arguments
+cmake.minimum-version = "3.18"
+cmake.verbose = true

clibs/pecos-rng/src/rng_pcg.c

@@ -0,0 +1,96 @@
+/*
+ * PCG Random Number Generation for C.
+ *
+ * Copyright 2014 Melissa O'Neill <[email protected]>
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ *
+ * For additional information about the PCG random number generation scheme,
+ * including its license and other licensing options, visit
+ *
+ *       http://www.pcg-random.org
+ */
+
+#include <math.h>
+#include "rng_pcg.h"
+
+// RNG state structure
+typedef struct pcg_state_setseq_64 {
+    uint64_t state;
+    uint64_t inc;
+} pcg32_random_t;
+
+// global RNG state
+static pcg32_random_t pcg32_global = {
+    0x853c49e6748fea9bULL,
+    0xda3e39cb94b95bdbULL
+};
+
+// default multi[plier]
+#define PCG_DEFAULT_MULTIPLIER_64  6364136223846793005ULL
+
+// helper functions
+static inline uint32_t pcg_rotr_32(uint32_t value, unsigned int urot) {
+    int rot = (int)urot;
+    return (value >> rot) | (value << ((-rot) & 31));
+}
+
+static inline void pcg_setseq_64_step_r(pcg32_random_t* rng) {
+    rng->state = rng->state * PCG_DEFAULT_MULTIPLIER_64 + rng->inc;
+}
+
+static inline uint32_t pcg_output_xsh_rr_64_32(uint64_t state) {
+    return pcg_rotr_32(((state >> 18u) ^ state) >> 27u, state >> 59u);
+}
+
+static inline uint32_t pcg32_random_r(pcg32_random_t* rng) {
+    const uint64_t oldstate = rng->state;
+    pcg_setseq_64_step_r(rng);
+    return pcg_output_xsh_rr_64_32(oldstate);
+}
+
+static inline uint32_t pcg32_boundedrand_r(pcg32_random_t* rng, uint32_t ubound) {
+    int32_t bound = (int32_t)ubound;
+    uint32_t threshold = -bound % bound;
+    for (;;) {
+        const uint32_t r = pcg32_random_r(rng);
+        if (r >= threshold)
+            return r % bound;
+    }
+}
+
+static inline void pcg32_srandom_r(pcg32_random_t* rng, uint64_t initstate, uint64_t initseq) {
+    rng->state = 0U;
+    rng->inc = (initseq << 1u) | 1u;
+    pcg_setseq_64_step_r(rng);
+    rng->state += initstate;
+    pcg_setseq_64_step_r(rng);
+}
+
+// public interface to RNG
+
+uint32_t pcg32_random() {
+    return pcg32_random_r(&pcg32_global);
+}
+
+uint32_t pcg32_boundedrand(uint32_t bound) {
+    return pcg32_boundedrand_r(&pcg32_global, bound);
+}
+
+double pcg32_frandom() {
+    return ldexp(pcg32_random(), -32);
+}
+
+void pcg32_srandom(uint64_t seq) {
+    pcg32_srandom_r(&pcg32_global, 42u, seq);
+}

clibs/pecos-rng/src/rng_pcg.h

@@ -0,0 +1,42 @@
+/*
+ * PCG Random Number Generation for C.
+ *
+ * Copyright 2014 Melissa O'Neill <[email protected]>
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ *
+ * For additional information about the PCG random number generation scheme,
+ * including its license and other licensing options, visit
+ *
+ *       http://www.pcg-random.org
+ */
+
+#pragma once
+
+#include <stdint.h>
+
+#if __cplusplus
+extern "C" {
+#endif
+
+uint32_t pcg32_random();
+
+uint32_t pcg32_boundedrand(uint32_t bound);
+
+double pcg32_frandom();
+
+void pcg32_srandom(uint64_t seq);
+
+#if __cplusplus
+}
+#endif

clibs/pecos-rng/src/wrapper.cpp

@@ -0,0 +1,12 @@
+#include <nanobind/nanobind.h>
+#include "rng_pcg.h"
+
+namespace nb = nanobind;
+using namespace nb::literals;
+
+NB_MODULE(pecos_rng, m) {
+    m.def("pcg32_random", &pcg32_random,"generate random numbers");
+    m.def("pcg32_frandom", &pcg32_frandom, "Generate random floating point number");
+    m.def("pcg32_boundedrand", &pcg32_boundedrand,  "Generate bounded random number");
+    m.def("pcg32_srandom", &pcg32_srandom,  "seeded random");
+}