Metadata-Version: 2.4
Name: mcprojsim
Version: 0.2.0
Summary: Monte Carlo simulation system for software development effort estimation
License: MIT
License-File: LICENSE
Keywords: monte-carlo,simulation,project-management,estimation
Author: Johan Persson
Author-email: johan162@gmail.com
Requires-Python: >=3.14
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: End Users/Desktop
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.14
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Topic :: Office/Business
Classifier: Topic :: Scientific/Engineering :: Information Analysis
Classifier: Topic :: Utilities
Classifier: Typing :: Typed
Requires-Dist: click (>=8.0.0)
Requires-Dist: jinja2 (>=3.0.0)
Requires-Dist: matplotlib (>=3.5.0)
Requires-Dist: numpy (>=2.4.2)
Requires-Dist: pydantic (>=2.0.0)
Requires-Dist: pyyaml (>=6.0)
Requires-Dist: scipy (>=1.17.1)
Requires-Dist: tomli-w (>=1.0.0)
Project-URL: Documentation, https://github.com/johan162/mcprojsim/docs
Project-URL: Homepage, https://github.com/johan162/mcprojsim
Project-URL: Repository, https://github.com/johan162/mcprojsim
Description-Content-Type: text/markdown

# Monte Carlo Project Simulator (mcprojsim)

| Category | Link |
|----------|--------|
|**Package**|[![PyPI version](https://img.shields.io/pypi/v/mcprojsim.svg)](https://pypi.org/project/mcprojsim/) [![Python 3.14+](https://img.shields.io/badge/python-3.14+-blue.svg)](https://www.python.org/downloads/)|
|**Documentation**|[![Documentation](https://img.shields.io/badge/docs-mkdocs-blue)](https://johan162.github.io/mcprojsim/)|
|**License**|[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)|
|**Release**|[![GitHub release](https://img.shields.io/github/v/release/johan162/mcprojsim?include_prereleases)](https://github.com/johan162/mcprojsim/releases)|
|**CI/CD**|[![CI](https://github.com/johan162/mcprojsim/actions/workflows/ci.yml/badge.svg)](https://github.com/johan162/mcprojsim/actions/workflows/ci.yml) [![Doc build](https://github.com/johan162/mcprojsim/actions/workflows/docs.yml/badge.svg)](https://github.com/johan162/mcprojsim/actions/workflows/docs.yml) [![Coverage](https://img.shields.io/badge/coverage-83%25-brightgreen.svg)](coverage.svg)|
|**Code Quality**|[![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black) [![Checked with mypy](https://www.mypy-lang.org/static/mypy_badge.svg)](https://mypy-lang.org/) [![Linting: flake8](https://img.shields.io/badge/linting-flake8-yellowgreen)](https://flake8.pycqa.org/)|
|Repo URL|[![GitHub](https://img.shields.io/badge/GitHub-100000?style=flat-square&logo=github&logoColor=white)](https://github.com/johan162/mcprojsim)|


# Table of Content

- [Monte Carlo Project Simulator (mcprojsim)](#monte-carlo-project-simulator-mcprojsim)
- [Table of Content](#table-of-content)
  - [Overview](#overview)
  - [Features](#features)
  - [Installation](#installation)
    - [Best for end users: Install with `pipx`](#best-for-end-users-install-with-pipx)
      - [Install with `pipx`](#install-with-pipx)
      - [Install a pre-release from TestPyPI](#install-a-pre-release-from-testpypi)
    - [Containers: Run with Podman or Docker](#containers-run-with-podman-or-docker)
      - [Prerequisites](#prerequisites)
      - [Build the container image](#build-the-container-image)
      - [Run the CLI in the container](#run-the-cli-in-the-container)
      - [Run Container with local files](#run-container-with-local-files)
      - [Container Troubleshooting](#container-troubleshooting)
    - [Local development / source install prerequisites](#local-development--source-install-prerequisites)
    - [From Source](#from-source)
    - [Activate the Virtual Environment](#activate-the-virtual-environment)
    - [From PyPI (when published)](#from-pypi-when-published)
  - [Quick Start](#quick-start)
    - [1. Create a Project Definition File](#1-create-a-project-definition-file)
    - [2. Run the Simulation](#2-run-the-simulation)
    - [3. Validate Input Files](#3-validate-input-files)
  - [Command-Line Interface](#command-line-interface)
    - [Commands](#commands)
    - [Options](#options)
  - [Configuration](#configuration)
  - [Examples](#examples)
  - [Documentation](#documentation)
    - [View Documentation Locally](#view-documentation-locally)
    - [Documentation Server Options](#documentation-server-options)
  - [Development](#development)
    - [Setup Development Environment](#setup-development-environment)
    - [Run Tests](#run-tests)
    - [Code Quality](#code-quality)
    - [Build Documentation](#build-documentation)
  - [Project Structure](#project-structure)
  - [Requirements](#requirements)
  - [License](#license)
  - [Contributing](#contributing)
  - [Support](#support)
  - [Citation](#citation)
  - [Acknowledgments](#acknowledgments)


## Overview

A Monte Carlo simulation system for software development effort estimation. This tool helps you generate probabilistic estimates for project completion by modeling uncertainties in task duration, applying risk impacts, handling task dependencies, and generating confidence intervals through iterative simulation.

## Features

- **Triangular & Log-Normal Distribution Sampling** for task estimates
- **Project-Level and Task-Level Risk Modeling** with probabilistic impacts
- **Task Dependency Resolution** (precedence constraints)
- **Uncertainty Factor Application** (team experience, requirements maturity, etc.)
- **Resource Allocation and Availability Modeling**
- **Percentile-Based Confidence Intervals** (P25, P50, P75, P80, P85, P90, P95, P99)
- **Sensitivity Analysis** and critical path identification
- **Multiple Export Formats** (JSON, CSV, HTML reports)

## Installation

### Best for end users: Install with `pipx`

If you want to install `mcprojsim` as a normal command-line tool, `pipx` is the simplest option.
It installs the application in an isolated environment and makes the `mcprojsim` command directly available on your `PATH`.
This is however limited to official releases (either pre- or production)

#### Install with `pipx`

```bash
# Install pipx if needed
python3 -m pip install --user pipx
python3 -m pipx ensurepath

# Install mcprojsim
pipx install mcprojsim

# Run it directly
mcprojsim --help
mcprojsim --version
mcprojsim simulate examples/sample_project.yaml
```

This is the recommended non-container option for end users.

#### Install a pre-release from TestPyPI

Pre-releases are published (based on pre-release tags) to TestPyPI before a full production release reaches PyPI.
When installing from TestPyPI, use TestPyPI as the main index and keep PyPI as the extra index for dependencies.

```bash
# Install the latest pre-release from TestPyPI
pipx install \
  --pip-args="--pre --index-url https://test.pypi.org/simple --extra-index-url https://pypi.org/simple" \
  mcprojsim

# Or install a specific pre-release version
pipx install \
  --pip-args="--index-url https://test.pypi.org/simple --extra-index-url https://pypi.org/simple" \
  mcprojsim==0.2.0rc2
```

If `mcprojsim` is already installed with `pipx`, use `pipx upgrade` with the same `--pip-args` values.

### Containers: Run with Podman or Docker

Running `mcprojsim` as a container is the best way to run the downloaded source in a defined environment.
It avoids installing Poetry locally and provides an isolated runtime with the CLI preconfigured.
This is recommended for advanced users and/or developers who might modify the source or run development
versions of the project.

#### Prerequisites

- Podman or Docker

#### Build the container image

```bash
# Clone the repository
git clone https://github.com/johan162/mcprojsim.git
cd mcprojsim

# Automaticall selects available container manager (Podman or Docker)
make container-build
```

This will be the same as ether running

```bash
# Preferred: Podman
podman build -t mcprojsim .
```

or

```bash
# Alternative: Docker
docker build -t mcprojsim .
```

#### Run the CLI in the container

To run the container the recommended way is to use the supplied `./bin/mcprojsim.sh` shell script. It 
will allow you to run the program as any other CLI tool.

```bash
./bin/mcprojsim --help
./bin/mcprojsim simulate sample_project.yml
```


The container entrypoint is already set to `mcprojsim`, so you only need to pass the CLI arguments, for example as (here the cntainer is automatically removed as soon as it is finished)

```bash
# Preferred: Podman
podman run --rm mcprojsim --help
podman run --rm mcprojsim --version

# Alternative: Docker
docker run --rm mcprojsim --help
```

#### Run Container with local files

Mount your working directory into the container so it can read input files and write result files.

```bash
# Preferred: Podman
podman run --rm -v "$PWD:/work:Z" mcprojsim validate examples/sample_project.yaml
podman run --rm -v "$PWD:/work:Z" mcprojsim simulate examples/sample_project.yaml --seed 42

# Alternative: Docker
docker run --rm -v "$PWD:/work" mcprojsim validate examples/sample_project.yaml
docker run --rm -v "$PWD:/work" mcprojsim simulate examples/sample_project.yaml --seed 42
```

Generated JSON, CSV, and HTML reports are written back to your local working directory.

#### Container Troubleshooting

- **No proxy in your environment:** you do not need any certificate file or extra build flags. A standard `podman build -t mcprojsim .` or `docker build -t mcprojsim .` works as-is.
- **Corporate proxy / TLS interception:** some environments re-sign HTTPS traffic with an internal CA. In that case, pass the CA certificate as a build secret so Poetry and `pip` can trust outbound HTTPS during the image build.

```bash
# Preferred: Podman
podman build \
  --build-arg USE_PROXY_CA=true \
  --secret id=proxy_ca,src=CA_proxy_fw_all.pem \
  -t mcprojsim .

# Alternative: Docker
docker build \
  --build-arg USE_PROXY_CA=true \
  --secret id=proxy_ca,src=CA_proxy_fw_all.pem \
  -t mcprojsim .
```

### Local development / source install prerequisites

- Python 3.14 or higher
- [Poetry](https://python-poetry.org/) for dependency management

Install Poetry if you haven't already:
```bash
curl -sSL https://install.python-poetry.org | python3 -
```

### From Source

```bash
# Clone the repository
git clone https://github.com/johan162/mcprojsim.git
cd mcprojsim

# Install all dependencies (including dev dependencies)
poetry install

# Or install only production dependencies
poetry install --only main

# Or install with documentation dependencies
poetry install --with docs
```

### Activate the Virtual Environment

```bash
# Activate the Poetry-managed virtual environment
poetry shell

# Or run commands directly with poetry run
poetry run mcprojsim --help
```

### From PyPI (when published)

```bash
# Using pipx
pipx install mcprojsim


# Or using Poetry in your project
poetry add mcprojsim
```

If you prefer running the project from a source checkout without installing it locally, you can also use the containerized CLI wrapper:

```bash
./bin/mcprojsim.sh --help
./bin/mcprojsim.sh simulate project.yaml --seed 12345
```

## Quick Start

### 1. Create a Project Definition File

Create a `project.yaml` file:

```yaml
project:
  name: "My Project"
  description: "Sample project for estimation"
  start_date: "2025-11-01"
  confidence_levels: [25, 50, 75, 80, 85, 90, 95, 99]

tasks:
  - id: "task_001"
    name: "Database schema design"
    description: "Design normalized schema"
    estimate:
      min: 3
      most_likely: 5
      max: 10
      unit: "days"
    dependencies: []
    uncertainty_factors:
      team_experience: "high"
      requirements_maturity: "medium"
      technical_complexity: "low"
    risks:
      - id: "risk_001"
        name: "Schema migration issues"
        probability: 0.20
        impact: 2
```

### 2. Run the Simulation

```bash
# Run with default settings (10,000 iterations)
poetry run mcprojsim simulate project.yaml

# Or activate the shell first
poetry shell
mcprojsim simulate project.yaml

# Specify number of iterations
mcprojsim simulate project.yaml --iterations 50000

# Use custom config file
mcprojsim simulate project.yaml --config custom_config.yaml

# Specify random seed for reproducibility
mcprojsim simulate project.yaml --seed 12345

# Export to specific formats
mcprojsim simulate project.yaml --output-format json,html
```

Container equivalent:

```bash
# Preferred: Podman
podman run --rm -v "$PWD:/work:Z" mcprojsim simulate project.yaml --seed 12345

# Alternative: Docker
docker run --rm -v "$PWD:/work" mcprojsim simulate project.yaml --seed 12345
```

### 3. Validate Input Files

```bash
mcprojsim validate project.yaml
```

Container equivalent:

```bash
# Preferred: Podman
podman run --rm -v "$PWD:/work:Z" mcprojsim validate project.yaml

# Alternative: Docker
docker run --rm -v "$PWD:/work" mcprojsim validate project.yaml
```

## Command-Line Interface

### Commands

- `mcprojsim simulate <project-file>` - Run Monte Carlo simulation
- `mcprojsim validate <project-file>` - Validate input file without running
- `mcprojsim config show` - Show current configuration

### Options

- `--iterations, -n` - Number of simulation iterations (default: 10000)
- `--config, -c` - Path to configuration file
- `--seed, -s` - Random seed for reproducibility
- `--output, -o` - Output file path
- `--output-format, -f` - Output formats: json, csv, html (comma-separated)
- `--quiet, -q` - Suppress progress output


## Configuration

Create a `config.yaml` file to customize uncertainty factors:

```yaml
uncertainty_factors:
  team_experience:
    high: 0.90      # 10% faster
    medium: 1.0     # Baseline
    low: 1.30       # 30% slower
  
  requirements_maturity:
    high: 1.0
    medium: 1.15
    low: 1.40

simulation:
  default_iterations: 10000
  random_seed: null

output:
  formats: ["json", "csv", "html"]
  include_histogram: true
  histogram_bins: 50
```

## Examples

See the `examples/` directory for:
- `sample_project.yaml` - Complete project definition example
- `sample_config.yaml` - Configuration file example

To use a custom configuration file together with a project file use this syntax (see `mcprojsim simulate --help` for supported options)

```bash
mcprojsim simulate --config example/sample_config.yaml examples/sample_project.yaml  
```


## Documentation

The source documentation is available in the `docs/` directory. These doc sources are used to build a `mkdocs` site that can be run locally. It is also available in GitHub as a static site [mcprojsim documentation](https://johan162.github.io/mcprojsim/)

- **[Getting Started](docs/getting_started.md)** - Step-by-step guide to your first simulation
- **[Formal Grammar](docs/grammar.md)** - Complete EBNF specification of the input file format
- **[Examples](docs/examples.md)** - Working examples and use cases
- **[Configuration](docs/configuration.md)** - Customizing uncertainty factors
- **[API Reference](docs/api_reference.md)** - Python API documentation

### View Documentation Locally

Use the local MkDocs server when you are editing documentation or Python code and want fast live-reload during development.

```bash
# Install with documentation dependencies
poetry install --with docs

# Serve documentation locally at http://127.0.0.1:8000
poetry run mkdocs serve
```

### Documentation Server Options

- Use `make docs-serve` for day-to-day documentation editing with the fastest feedback loop.
- Use `make docs-container-start` when you want to validate the containerized docs environment or run the docs server without relying on a local Poetry environment.
- Use `./scripts/docs-contctl.sh ...` directly when you want full container lifecycle control such as `start`, `stop`, `restart`, `status`, `logs`, or `build`.

```bash
# Fast local development server
make docs-serve

# Containerized docs server
make docs-container-start

# Direct container management
./scripts/docs-contctl.sh status
./scripts/docs-contctl.sh logs --follow
```

## Development

### Setup Development Environment

```bash
# Install with all dependencies including dev dependencies
poetry install

# Activate the virtual environment
poetry shell

```

### Run Tests

```bash
# Run all tests
poetry run pytest

# Run with coverage
poetry run pytest --cov=mcprojsim --cov-report=html

# Run tests in parallel
poetry run pytest -n auto

# Run specific test file
poetry run pytest tests/test_simulation.py

```

### Code Quality

```bash
# Format code
poetry run black src/ tests/

# Type checking
poetry run mypy src/

# Linting
poetry run flake8 src/ tests/
```

or using the `Makefile`

```bash
# Run both Lint, formatting, and type checks
make check
```

### Build Documentation

Choose the command based on what you are doing:

- `make docs-serve` or `poetry run mkdocs serve` for editing docs locally.
- `make docs-container-start` for the containerized docs server.
- `make docs-container-stop` and `make docs-container-logs` for container lifecycle tasks.

```bash
# Install with documentation dependencies
poetry install --with docs

# Serve documentation locally
poetry run mkdocs serve

# Or use the Makefile wrapper
make docs-serve

# Start the containerized docs server
make docs-container-start

# Stop the containerized docs server
make docs-container-stop

# Build documentation
poetry run mkdocs build
```

## Project Structure

```
mcprojsim/
├── bin/                    # User-facing wrapper scripts
│   └── mcprojsim.sh        # Runs the containerized CLI like a local command
├── src/mcprojsim/          # Source code
│   ├── models/             # Data models
│   ├── parsers/            # Input file parsers
│   ├── simulation/         # Simulation engine
│   ├── analysis/           # Statistical analysis
│   ├── exporters/          # Output exporters
│   └── utils/              # Utilities
├── tests/                  # Test files
├── docs/                   # Documentation
├── examples/               # Example files
└── scripts/                # Build, release, setup, and docs-control scripts
```

## Requirements

- Python 3.14+
- Poetry 2.0+
- NumPy 2.3.4+
- PyYAML 6.0+
- Pydantic 2.0+
- Click 8.0+

All Python dependencies are managed by Poetry and will be installed automatically.

## License

MIT License - see LICENSE file for details.

## Contributing

Contributions are welcome! Please:
1. Fork the repository
2. Create a feature branch
3. Make your changes with tests
4. Run the test suite
5. Submit a pull request

## Support

For issues and questions:
- GitHub Issues: https://github.com/johan162/mcprojsim/issues
- Documentation: https://github.com/johan162/mcprojsim/docs

## Citation

If you use this tool in your research or project management, please cite:

```
@software{mcprojsim,
  title = {Monte Carlo Project Simulator},
  author = {Johan Persson},
  year = {2026},
  url = {https://github.com/johan162/mcprojsim},
  version = {0.2.0}
}
```

## Acknowledgments

Inspired by the work of:
- Steve McConnell - *Software Estimation: Demystifying the Black Art*
- Frederick Brooks - *The Mythical Man-Month*
- Douglas Hubbard - *How to Measure Anything in Cybersecurity Risk*

