# mc-lab
Educational implementations of core Monte Carlo method algorithms. The goal is learning, clarity, and nu## Collaboration
Open to collaboration and contributions. If you're interested:
- Open an issue to discuss ideas or report bugs.
- Submit small, focused PRs with tests when public behavior changes.
- For larger changes, start with a brief design proposal in an issue.
## Publishing new versions to PyPI
This package is published to PyPI as `mc-lab-edu`. To publish a new version:
### 1. Update the version
Edit `pyproject.toml` and increment the version number:
```toml
[project]
name = "mc-lab-edu"
version = "0.1.1" # or 0.2.0 for larger changes
```
### 2. Build and upload
```bash
# Clean previous builds
rm -rf dist/
# Build the package
uv run python -m build
# Check the package for issues
uv run twine check dist/*
# Upload to PyPI (requires API token in ~/.pypirc)
uv run twine upload dist/*
```
### 3. Setup PyPI authentication (one-time setup)
If you haven't set up authentication yet:
1. Get an API token from <https://pypi.org/manage/account/token/>
2. Create `~/.pypirc`:
```ini
[distutils]
index-servers = pypi
[pypi]
repository = https://upload.pypi.org/legacy/
username = __token__
password = pypi-your-actual-token-here
```
**Note**: Never commit API tokens to version control. The `.pypirc` file should remain in your home directory only.
## Course contextorrectness over raw speed or micro-optimizations. Expect straightforward NumPy/SciPy-based code with helpful tests and a couple of demo notebooks.
## What’s inside
- Basic importance sampling
- Rejection sampling and a few more advance rejection sampling methods
- Normal sampling via Box–Muller (classic and polar) — `src/mc_lab/box_mueller.py`
- Inverse transform sampling (analytical, numerical interpolation/root-finding, adaptive; plus alias method for discrete) — `src/mc_lab/inverse_transform.py`
- Multivariate Gaussian sampling with Cholesky/eigendecomposition fallback — `src/mc_lab/multivariate_gaussian.py`
- Tests in `tests/` and a demo notebook in `notebooks/`
## Installation
Install from PyPI:
```bash
pip install mc-lab-edu
```
### Google Colab Compatibility
Version 0.2.2+ has been specifically tested to work with Google Colab's package environment. The numpy version is constrained to `>=1.24.0,<2.0.0` to avoid compatibility issues with pre-installed packages and scipy. This resolves the `_center` import errors that occurred with numpy 2.x versions.
Or for local development:
## Clone the repository
```bash
git clone https://github.com/carsten-j/mc-lab.git
cd mc-lab
```
## Setup for local development
Recommended (uses uv to manage a local .venv and sync dependencies):
```bash
# If you don’t have uv yet, see https://docs.astral.sh/uv/ for install options
uv sync
source .venv/bin/activate
```
Alternative (standard venv + pip):
```bash
python3 -m venv .venv
source .venv/bin/activate
pip install -U pip
pip install -e .
# Dev tools (optional but recommended)
pip install pytest ruff ipykernel pre-commit
```
Verify the install:
```bash
python -c "import mc_lab; print(mc_lab.hello())"
```
## Run tests and linting
With uv:
```bash
uv run pytest
# Format & lint (either use the Makefile below or direct commands)
uv run ruff format .
uv run ruff check --select I --fix
uv run ruff check --fix
```
With a plain venv:
```bash
pytest
ruff format .
ruff check --select I --fix
ruff check --fix
# Or via the Makefile at the repo root:
make format-fix
make lint-fix
make perftest # run only tests marked with @pytest.mark.performance (prints output)
```
## Quick usage example
```python
import numpy as np
from mc_lab.multivariate_gaussian import sample_multivariate_gaussian
mu = np.array([0.0, 1.0])
Sigma = np.array([[1.0, 0.5], [0.5, 2.0]])
X = sample_multivariate_gaussian(mu, Sigma, n=1000, random_state=42)
print(X.shape) # (1000, 2)
```
## Notebooks
Demo notebooks live in `notebooks/`. If you want the environment available as a Jupyter kernel:
```bash
python -m ipykernel install --user --name mc-lab
```
---
Note: This is an educational project; APIs and implementations may evolve for clarity. If you need production-grade performance, consider specialized libraries or contribute optimizations guarded by tests.
## Numba
The Box-Muller implementation can be used with numba for performance improvenments. See the installation notes for numba on how to set it up on your hardware or simply try
```bash
uv pip install numba
```
## Collaboration
Open to collaboration and contributions. If you’re interested:
- Open an issue to discuss ideas or report bugs.
- Submit small, focused PRs with tests when public behavior changes.
- For larger changes, start with a brief design proposal in an issue.
## Course context
This project was initiated and developed while following the course [“NMAK24010U Topics in Statistics”](https://kurser.ku.dk/course/nmak24010u/) at the University of Copenhagen (UCPH) fall 2025.
Raw data
{
"_id": null,
"home_page": null,
"name": "mc-lab-edu",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.12",
"maintainer_email": null,
"keywords": "education, monte-carlo, numerical-methods, sampling, statistics",
"author": null,
"author_email": "Carsten J\u00f8rgensen <carstenj@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/b1/ed/c415436093bdde4482379c9f51e3e536f732965e717f169c9f46c75d7f45/mc_lab_edu-0.2.7.tar.gz",
"platform": null,
"description": "# mc-lab\n\nEducational implementations of core Monte Carlo method algorithms. The goal is learning, clarity, and nu## Collaboration\n\nOpen to collaboration and contributions. If you're interested:\n\n- Open an issue to discuss ideas or report bugs.\n- Submit small, focused PRs with tests when public behavior changes.\n- For larger changes, start with a brief design proposal in an issue.\n\n## Publishing new versions to PyPI\n\nThis package is published to PyPI as `mc-lab-edu`. To publish a new version:\n\n### 1. Update the version\n\nEdit `pyproject.toml` and increment the version number:\n\n```toml\n[project]\nname = \"mc-lab-edu\"\nversion = \"0.1.1\" # or 0.2.0 for larger changes\n```\n\n### 2. Build and upload\n\n```bash\n# Clean previous builds\nrm -rf dist/\n\n# Build the package\nuv run python -m build\n\n# Check the package for issues\nuv run twine check dist/*\n\n# Upload to PyPI (requires API token in ~/.pypirc)\nuv run twine upload dist/*\n```\n\n### 3. Setup PyPI authentication (one-time setup)\n\nIf you haven't set up authentication yet:\n\n1. Get an API token from <https://pypi.org/manage/account/token/>\n2. Create `~/.pypirc`:\n\n```ini\n[distutils]\nindex-servers = pypi\n\n[pypi]\nrepository = https://upload.pypi.org/legacy/\nusername = __token__\npassword = pypi-your-actual-token-here\n```\n\n**Note**: Never commit API tokens to version control. The `.pypirc` file should remain in your home directory only.\n\n## Course contextorrectness over raw speed or micro-optimizations. Expect straightforward NumPy/SciPy-based code with helpful tests and a couple of demo notebooks.\n\n## What\u2019s inside\n\n- Basic importance sampling\n- Rejection sampling and a few more advance rejection sampling methods\n- Normal sampling via Box\u2013Muller (classic and polar) \u2014 `src/mc_lab/box_mueller.py`\n- Inverse transform sampling (analytical, numerical interpolation/root-finding, adaptive; plus alias method for discrete) \u2014 `src/mc_lab/inverse_transform.py`\n- Multivariate Gaussian sampling with Cholesky/eigendecomposition fallback \u2014 `src/mc_lab/multivariate_gaussian.py`\n- Tests in `tests/` and a demo notebook in `notebooks/`\n\n## Installation\n\nInstall from PyPI:\n\n```bash\npip install mc-lab-edu\n```\n\n### Google Colab Compatibility\n\nVersion 0.2.2+ has been specifically tested to work with Google Colab's package environment. The numpy version is constrained to `>=1.24.0,<2.0.0` to avoid compatibility issues with pre-installed packages and scipy. This resolves the `_center` import errors that occurred with numpy 2.x versions.\n\nOr for local development:\n\n## Clone the repository\n\n```bash\ngit clone https://github.com/carsten-j/mc-lab.git\ncd mc-lab\n```\n\n## Setup for local development\n\nRecommended (uses uv to manage a local .venv and sync dependencies):\n\n```bash\n# If you don\u2019t have uv yet, see https://docs.astral.sh/uv/ for install options\nuv sync\nsource .venv/bin/activate\n```\n\nAlternative (standard venv + pip):\n\n```bash\npython3 -m venv .venv\nsource .venv/bin/activate\npip install -U pip\npip install -e .\n# Dev tools (optional but recommended)\npip install pytest ruff ipykernel pre-commit\n```\n\nVerify the install:\n\n```bash\npython -c \"import mc_lab; print(mc_lab.hello())\"\n```\n\n## Run tests and linting\n\nWith uv:\n\n```bash\nuv run pytest\n# Format & lint (either use the Makefile below or direct commands)\nuv run ruff format .\nuv run ruff check --select I --fix\nuv run ruff check --fix\n```\n\nWith a plain venv:\n\n```bash\npytest\nruff format .\nruff check --select I --fix\nruff check --fix\n# Or via the Makefile at the repo root:\nmake format-fix\nmake lint-fix\nmake perftest # run only tests marked with @pytest.mark.performance (prints output)\n```\n\n## Quick usage example\n\n```python\nimport numpy as np\nfrom mc_lab.multivariate_gaussian import sample_multivariate_gaussian\n\nmu = np.array([0.0, 1.0])\nSigma = np.array([[1.0, 0.5], [0.5, 2.0]])\nX = sample_multivariate_gaussian(mu, Sigma, n=1000, random_state=42)\nprint(X.shape) # (1000, 2)\n```\n\n## Notebooks\n\nDemo notebooks live in `notebooks/`. If you want the environment available as a Jupyter kernel:\n\n```bash\npython -m ipykernel install --user --name mc-lab\n```\n\n---\n\nNote: This is an educational project; APIs and implementations may evolve for clarity. If you need production-grade performance, consider specialized libraries or contribute optimizations guarded by tests.\n\n## Numba\n\nThe Box-Muller implementation can be used with numba for performance improvenments. See the installation notes for numba on how to set it up on your hardware or simply try\n\n```bash\nuv pip install numba\n```\n\n## Collaboration\n\nOpen to collaboration and contributions. If you\u2019re interested:\n\n- Open an issue to discuss ideas or report bugs.\n- Submit small, focused PRs with tests when public behavior changes.\n- For larger changes, start with a brief design proposal in an issue.\n\n## Course context\n\nThis project was initiated and developed while following the course [\u201cNMAK24010U Topics in Statistics\u201d](https://kurser.ku.dk/course/nmak24010u/) at the University of Copenhagen (UCPH) fall 2025.\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Educational implementations of core Monte Carlo method algorithms",
"version": "0.2.7",
"project_urls": null,
"split_keywords": [
"education",
" monte-carlo",
" numerical-methods",
" sampling",
" statistics"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "55162de39eb7bdc59738f761728cc2e39fc496bb44432a5038e96d63998ab111",
"md5": "a23859bc3273e89e53bb916e22f0715c",
"sha256": "bf633531dd6cd84fcd48bb5d75a770499f2526ed4cf29cff31e2b838a6ce57a6"
},
"downloads": -1,
"filename": "mc_lab_edu-0.2.7-py3-none-any.whl",
"has_sig": false,
"md5_digest": "a23859bc3273e89e53bb916e22f0715c",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.12",
"size": 720075,
"upload_time": "2025-09-05T15:14:50",
"upload_time_iso_8601": "2025-09-05T15:14:50.835237Z",
"url": "https://files.pythonhosted.org/packages/55/16/2de39eb7bdc59738f761728cc2e39fc496bb44432a5038e96d63998ab111/mc_lab_edu-0.2.7-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "b1edc415436093bdde4482379c9f51e3e536f732965e717f169c9f46c75d7f45",
"md5": "0ba9290eab3ae5e966501cf1f12844d2",
"sha256": "5222be9e65ea4f95bc5cbc419fa9266a3e6b0a867be3673902a188adeaf2cc7a"
},
"downloads": -1,
"filename": "mc_lab_edu-0.2.7.tar.gz",
"has_sig": false,
"md5_digest": "0ba9290eab3ae5e966501cf1f12844d2",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.12",
"size": 5567744,
"upload_time": "2025-09-05T15:14:52",
"upload_time_iso_8601": "2025-09-05T15:14:52.813442Z",
"url": "https://files.pythonhosted.org/packages/b1/ed/c415436093bdde4482379c9f51e3e536f732965e717f169c9f46c75d7f45/mc_lab_edu-0.2.7.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-09-05 15:14:52",
"github": false,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"lcname": "mc-lab-edu"
}
JSON