# ⚖️ SamplePlan — Nim-Powered Balanced Sampler for Python
[](https://pypi.org/project/sampleplan/)
A blazing-fast compiled backend for generating balanced random sequences in
Python. Built using [Nim](https://nim-lang.org/) 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](https://nim-lang.org/) if you intend to rebuild the
shared library from source.
Create your virtual environment:
```bash
python -m venv venv
```
Then activate it:
```bash
venv\Scripts\activate
```
Install the project's dependencies from the requirements file, if any:
```bash
python -m pip install -r requirements.txt
```
## 🐍 Python Usage
Install the local package:
```bash
python -m pip install -e .
```
Then use it. This call returns a `3 × 6` NumPy array (3 simulations of 2 × 3
symbols):
```python
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.
```c
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)
```bash
nim c --cc:vcc --app:lib --out:sampler/sampleplan.dll nimsrc/sampleplan.nim
```
For faster release builds:
```bash
nim c --cc:vcc --app:lib --out:sampleplan/sampleplan.dll -d:release nimsrc/sampleplan.nim
```
This generates `sampleplan.dll`, which is required for Python execution.
## 📦 Packaging and Distribution
To build the Python wheel:
```bash
python -m build --wheel
```
## 📁 Project Structure
```bash
sampleplan/
├── __init__.py
├── sampleplan.py # Python interface to the DLL
├── sampleplan.dll # Compiled Nim shared library
nimsrc/
└── 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](LICENSE).
## 📜 Changelog
### [0.1.0] — Initial Release
- First public version of `sampleplan`
- Exposes `sample_balanced()` via a compiled Nim DLL
- Supports any unique sequence of symbols (str/int)
- Deterministic sampling with `seed`
- 1D or 2D NumPy output based on `size` argument
### [0.1.1] — 2025-07-11
- Improved and clarified `README.md` formatting
- Added Changelog section to `README.md`
- Declared GitHub metadata in `pyproject.toml`
- Removed unnecessary exclusions from `.gitignore`
- Restored previously unversioned Nim source file `sampleplan.nim`
- Refined reformatting in `test_sampler.py`
Raw data
{
"_id": null,
"home_page": null,
"name": "sampleplan",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": null,
"keywords": "sampling, random, balanced, permutation, simulation, nim, ctypes",
"author": null,
"author_email": "Maxime Larocque <maxime.larocque@randomschemes.com>",
"download_url": null,
"platform": null,
"description": "# \u2696\ufe0f SamplePlan \u2014 Nim-Powered Balanced Sampler for Python\r\n\r\n[](https://pypi.org/project/sampleplan/)\r\n\r\nA blazing-fast compiled backend for generating balanced random sequences in\r\nPython. Built using [Nim](https://nim-lang.org/) and exposed via `ctypes`.\r\nIdeal for simulations, experimental design, or randomized testing scenarios\r\nwhere equal representation of categories is required.\r\n\r\n## \ud83d\udea7 Note\r\n\r\n> This is a lightweight, low-level library that demonstrates how to integrate\r\n> compiled Nim code with Python. It exposes a single high-performance utility\r\n> for generating balanced permutations, useful in simulation, randomization,\r\n> and probabilistic workflows.\r\n\r\n## \ud83d\ude80 Features\r\n\r\n- \u26a1 Fast compiled DLL backend (Nim \u2192 C \u2192 Python)\r\n- \ud83d\udce6 Seamless Python interface via `ctypes`\r\n- \ud83e\uddee Returns balanced permutations of symbols\r\n- \ud83e\uddea Deterministic output with `seed`\r\n\r\n## \ud83d\udce6 Setup\r\n\r\nInstall Python and [Nim](https://nim-lang.org/) if you intend to rebuild the\r\nshared library from source.\r\n\r\nCreate your virtual environment:\r\n\r\n```bash\r\npython -m venv venv\r\n```\r\n\r\nThen activate it:\r\n\r\n```bash\r\nvenv\\Scripts\\activate\r\n```\r\n\r\nInstall the project's dependencies from the requirements file, if any:\r\n\r\n```bash\r\npython -m pip install -r requirements.txt\r\n```\r\n\r\n## \ud83d\udc0d Python Usage\r\n\r\nInstall the local package:\r\n\r\n```bash\r\npython -m pip install -e .\r\n```\r\n\r\nThen use it. This call returns a `3 \u00d7 6` NumPy array (3 simulations of 2 \u00d7 3\r\nsymbols):\r\n\r\n```python\r\nfrom sampleplan import sample_balanced\r\n\r\nout = sample_balanced([\"A\", \"B\", \"C\"], m=2, size=3, seed=42)\r\nprint(out)\r\n# array([\r\n# ['A', 'B', 'C', 'C', 'B', 'A'],\r\n# ['B', 'C', 'A', 'A', 'B', 'C'],\r\n# ['C', 'A', 'B', 'B', 'C', 'A']\r\n# ])\r\n```\r\n\r\n## \ud83e\uddf1 Underlying C Signature\r\n\r\nThis function accepts raw memory buffers from Python and writes directly into\r\nthe pre-allocated output array. It is not meant to be called directly from user\r\ncode.\r\n\r\n```c\r\nvoid sampleBalanced(\r\n int* symbols, int symbolCount, int m, int size, int seed, int* outSeq\r\n);\r\n```\r\n\r\nAll pointer data is managed from the Python side using NumPy and ctypes.\r\n\r\n## \ud83c\udfd7\ufe0f Build the DLL (Windows)\r\n\r\nCompile the DLL using the Nim compiler and Microsoft's Visual C++ (MSVC)\r\n\r\n```bash\r\nnim c --cc:vcc --app:lib --out:sampler/sampleplan.dll nimsrc/sampleplan.nim\r\n```\r\n\r\nFor faster release builds:\r\n\r\n```bash\r\nnim c --cc:vcc --app:lib --out:sampleplan/sampleplan.dll -d:release nimsrc/sampleplan.nim\r\n```\r\n\r\nThis generates `sampleplan.dll`, which is required for Python execution.\r\n\r\n## \ud83d\udce6 Packaging and Distribution\r\n\r\nTo build the Python wheel:\r\n\r\n```bash\r\npython -m build --wheel\r\n```\r\n\r\n## \ud83d\udcc1 Project Structure\r\n\r\n```bash\r\nsampleplan/\r\n\u251c\u2500\u2500 __init__.py\r\n\u251c\u2500\u2500 sampleplan.py # Python interface to the DLL\r\n\u251c\u2500\u2500 sampleplan.dll # Compiled Nim shared library\r\nnimsrc/\r\n\u2514\u2500\u2500 sampleplan.nim # Nim source code (not distributed)\r\ntests/\r\n\u2514\u2500\u2500 test_sampler.py\r\npyproject.toml\r\nLICENSE\r\nMANIFEST.in\r\nREADME.md\r\n```\r\n\r\n## \u26a0\ufe0f Platform Support\r\n\r\n- \u2705 Windows\r\n- \u23f3 Linux and macOS coming soon\r\n\r\n## \ud83e\udde0 License\r\n\r\nMIT \u2014 use freely, cite kindly. See [LICENSE](LICENSE).\r\n\r\n## \ud83d\udcdc Changelog\r\n\r\n### [0.1.0] \u2014 Initial Release\r\n\r\n- First public version of `sampleplan`\r\n- Exposes `sample_balanced()` via a compiled Nim DLL\r\n- Supports any unique sequence of symbols (str/int)\r\n- Deterministic sampling with `seed`\r\n- 1D or 2D NumPy output based on `size` argument\r\n\r\n### [0.1.1] \u2014 2025-07-11\r\n\r\n- Improved and clarified `README.md` formatting\r\n- Added Changelog section to `README.md`\r\n- Declared GitHub metadata in `pyproject.toml`\r\n- Removed unnecessary exclusions from `.gitignore`\r\n- Restored previously unversioned Nim source file `sampleplan.nim`\r\n- Refined reformatting in `test_sampler.py`\r\n",
"bugtrack_url": null,
"license": null,
"summary": "Fast balanced sequence sampling via a compiled Nim backend",
"version": "0.1.1",
"project_urls": {
"Homepage": "https://github.com/HistoryBeginsAtSumer/sampleplan",
"Source": "https://github.com/HistoryBeginsAtSumer/sampleplan",
"Tracker": "https://github.com/HistoryBeginsAtSumer/sampleplan/issues"
},
"split_keywords": [
"sampling",
" random",
" balanced",
" permutation",
" simulation",
" nim",
" ctypes"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "135a2067d9607b7ade4022e56c88684cfaeac2f04f32269e8de9afc496566ba1",
"md5": "0a78d49caa1a80492c8728f468142e1b",
"sha256": "b4e53697da5aaea2251834863088b5157f3c5ded2d23310a3ed51e5dcc09fd92"
},
"downloads": -1,
"filename": "sampleplan-0.1.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "0a78d49caa1a80492c8728f468142e1b",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 95318,
"upload_time": "2025-07-11T07:52:57",
"upload_time_iso_8601": "2025-07-11T07:52:57.784678Z",
"url": "https://files.pythonhosted.org/packages/13/5a/2067d9607b7ade4022e56c88684cfaeac2f04f32269e8de9afc496566ba1/sampleplan-0.1.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-07-11 07:52:57",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "HistoryBeginsAtSumer",
"github_project": "sampleplan",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "sampleplan"
}
JSON
