mcprojsim 0.2.0

Monte Carlo simulation system for software development effort estimation

Monte Carlo Project Simulator (mcprojsim)

Category	Link
Package
Documentation
License
Release
CI/CD
Code Quality
Repo URL

Table of Content

• Monte Carlo Project Simulator (mcprojsim)
• Table of Content
  • Overview
  • Features
  • Installation
    • Best for end users: Install with pipx
      • Install with pipx
      • Install a pre-release from TestPyPI
    • Containers: Run with Podman or Docker
      • Prerequisites
      • Build the container image
      • Run the CLI in the container
      • Run Container with local files
      • Container Troubleshooting
    • Local development / source install prerequisites
    • From Source
    • Activate the Virtual Environment
    • From PyPI (when published)
  • Quick Start
    • 1. Create a Project Definition File
    • 2. Run the Simulation
    • 3. Validate Input Files
  • Command-Line Interface
    • Commands
    • Options
  • Configuration
  • Examples
  • Documentation
    • View Documentation Locally
    • Documentation Server Options
  • Development
    • Setup Development Environment
    • Run Tests
    • Code Quality
    • Build Documentation
  • Project Structure
  • Requirements
  • License
  • Contributing
  • Support
  • Citation
  • 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

# 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.

# 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

# 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

# Preferred: Podman
podman build -t mcprojsim .

or

# 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.

./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)

# 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.

# 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.

# 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 for dependency management

Install Poetry if you haven't already:

curl -sSL https://install.python-poetry.org | python3 -

From Source

# 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

# Activate the Poetry-managed virtual environment
poetry shell

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

From PyPI (when published)

# 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:

./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:

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

# 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:

# 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

mcprojsim validate project.yaml

Container equivalent:

# 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:

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)

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

• Getting Started - Step-by-step guide to your first simulation
• Formal Grammar - Complete EBNF specification of the input file format
• Examples - Working examples and use cases
• Configuration - Customizing uncertainty factors
• API Reference - 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.

# 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.

# 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

# Install with all dependencies including dev dependencies
poetry install

# Activate the virtual environment
poetry shell

Run Tests

# 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

# Format code
poetry run black src/ tests/

# Type checking
poetry run mypy src/

# Linting
poetry run flake8 src/ tests/

or using the Makefile

# 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.

# 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