sampleplan 0.1.0

Fast balanced sequence sampling via a compiled Nim backend

⚖️ SamplePlan — Nim-Powered Balanced Sampler for Python

A blazing-fast compiled backend for generating balanced random sequences in Python. Built using Nim and exposed via ctypes. Ideal for simulations, experimental design, or randomized testing scenarios where equal representation of categories is required.

🚧 Note

This is a lightweight, low-level library that demonstrates how to integrate compiled Nim code with Python. It exposes a single high-performance utility for generating balanced permutations, useful in simulation, randomization, and probabilistic workflows.

🚀 Features

• ⚡ Fast compiled DLL backend (Nim → C → Python)
• 📦 Seamless Python interface via ctypes
• 🧮 Returns balanced permutations of symbols
• 🧪 Deterministic output with seed

📦 Setup

Install Python and Nim if you intend to rebuild the shared library from source.

Create your virtual environment:

python -m venv venv

Then activate it:

venv\Scripts\activate

Install the project's dependencies from the requirements file, if any:

python -m pip install -r requirements.txt

🐍 Python Usage

Install the local package:

python -m pip install -e .

Then use it. This call returns a 3 × 6 NumPy array (3 simulations of 2 × 3 symbols):

from sampleplan import sample_balanced

out = sample_balanced(["A", "B", "C"], m=2, size=3, seed=42)
print(out)
# array([
#   ['A', 'B', 'C', 'C', 'B', 'A'],
#   ['B', 'C', 'A', 'A', 'B', 'C'],
#   ['C', 'A', 'B', 'B', 'C', 'A']
# ])

🧱 Underlying C Signature

This function accepts raw memory buffers from Python and writes directly into the pre-allocated output array. It is not meant to be called directly from user code.

void sampleBalanced(
    int* symbols, int symbolCount, int m, int size, int seed, int* outSeq
);

All pointer data is managed from the Python side using NumPy and ctypes.

🏗️ Build the DLL (Windows)

Compile the DLL using the Nim compiler and Microsoft's Visual C++ (MSVC)

nim c --cc:vcc --app:lib --out:sampler/sampleplan.dll build/sampleplan.nim

For faster release builds:

nim c --cc:vcc --app:lib --out:sampleplan/sampleplan.dll -d:release build/sampleplan.nim

This generates sampleplan.dll, which is required for Python execution.

📦 Packaging and Distribution

To build the Python wheel:

python -m build --wheel

Optional: Build a Windows-specific wheel manually using platform tag

python -m pip wheel --platform win_amd64 .

📁 Project Structure

sampleplan/
├── __init__.py
├── sampleplan.py            # Python interface to the DLL
├── sampleplan.dll           # Compiled Nim shared library
build/
└── sampleplan.nim           # Nim source code (not distributed)
tests/
└── test_sampler.py
pyproject.toml
LICENSE
MANIFEST.in
README.md

⚠️ Platform Support

• ✅ Windows
• ⏳ Linux and macOS coming soon

🧠 License

MIT — use freely, cite kindly. See LICENSE.

📋 Design Quality Summary

Area	Upgrade
🔍 Clarity	Clear description of purpose and how to use it
🧪 Example	Shows expected behavior with sample_balanced
📦 Structure	Documents project folder layout
⚠️ Platform	Transparently marks this as Windows-only
🧠 Professionalism	Adds a polished voice and structure for PyPI or GitHub