[](https://pypi.org/project/monaco-dict-utils/)
[](https://github.com/hbmartin/monaco-dict-utils/actions/workflows/lint.yml)
[](https://github.com/astral-sh/ruff)
[](https://github.com/psf/black)
# Monaco Dictionary Utils
A Python library for easily bootstrapping Monaco Monte Carlo simulations with a dictionary-based workflow.
[See example notebook here](https://github.com/hbmartin/ai-roi-mcm-npv-marimo/blob/main/ai_roi_mcm_npv.py)
## Overview
Monaco Dictionary Utils provides a simplified interface for creating and running Monte Carlo simulations using the Monaco framework. It streamlines the process of setting up simulations by allowing you to define model factories, input parameters, and distributions using dictionary-based configuration.
## Features
- **Dictionary-based configuration**: Define simulations using simple dictionary structures
- **Model factory support**: Create models from factory functions with configurable parameters
- **Input variable management**: Handle both probabilistic distributions and constants
- **Output conversion**: Convert simulation results to easily accessible dictionary format
- **Parameter normalization**: Automatic parameter name normalization for consistency
## Installation
```bash
uv add monaco-dict-utils
```
## Requirements
- Python ≥ 3.11
- Monaco ≥ 0.16.0
## Quick Start
```python
from monaco_dict_utils import sim_factory, outvals_to_dict
# Define your model factory
def my_model_factory(param1, param2):
def model(x, y):
return {"result": x * param1 + y * param2}
return model
# Configure simulation
factory_vars = {"param1": 2, "param2": 3}
invars = {
"x": {"dist": "uniform", "params": {"loc": 0, "scale": 1}},
"y": {"dist": "_constant", "params": 5}
}
# Create and run simulation
sim = sim_factory(
name="my_simulation",
model_factory=my_model_factory,
factory_vars=factory_vars,
invars=invars,
ndraws=1000
)
sim.run()
# Convert outputs to dictionary
results = outvals_to_dict(sim)
```
## API Reference
#### `sim_factory(name, model_factory, factory_vars, invars, ndraws, *, verbose=True, debug=False)`
Create a Monte Carlo simulation from a model factory and parameters.
**Parameters:**
- `name` (str): Name of the simulation
- `model_factory` (Callable): Factory function that creates the model
- `factory_vars` (dict): Dictionary of variables to pass to model factory
- `invars` (dict): Dictionary mapping input names to distribution parameters
- `ndraws` (int): Number of Monte Carlo draws to simulate
- `verbose` (bool, optional): Whether to print simulation progress. Defaults to True.
- `debug` (bool, optional): Whether to run in debug mode. Defaults to False.
**Returns:**
- `Sim`: Configured Monaco Sim object ready to run simulations
**Example:**
```python
sim = sim_factory(
name="example_sim",
model_factory=my_factory,
factory_vars={"param": 10},
invars={"x": {"dist": "normal", "params": {"loc": 0, "scale": 1}}},
ndraws=5000
)
```
#### `outvals_to_dict(sim)`
Convert simulation output values to a dictionary.
**Parameters:**
- `sim` (Sim): A Monaco Sim object that has been run
**Returns:**
- `dict`: Dictionary mapping output variable names to numpy arrays of output values
**Example:**
```python
results = outvals_to_dict(sim)
# results = {"Result": array([1.23, 4.56, ...]), "Other_Output": array([...])}
```
## Input Variables Configuration
The `invars` dictionary supports two types of inputs:
### 1. Probabilistic Distributions
For random variables, specify a distribution and its parameters:
```python
invars = {
"temperature": {
"dist": "normal",
"params": {"loc": 20, "scale": 5}
},
"pressure": {
"dist": "uniform",
"params": {"loc": 10, "scale": 2}
}
}
```
### 2. Constants
For constant values, use the special `_constant` distribution:
```python
invars = {
"gravity": {
"dist": "_constant",
"params": 9.81
},
"config": {
"dist": "_constant",
"params": {"setting1": 100, "setting2": 200}
}
}
```
## Parameter Normalization
The library automatically normalizes parameter names by:
- Converting to lowercase
- Removing special characters
- Replacing spaces with underscores
For example: `"Air Temperature"` becomes `"air_temperature"`
## Output Formatting
Output values are automatically formatted with:
- Title case conversion
- Underscore preservation
- Example: `"time_savings"` becomes `"Time_Savings"`
Raw data
{
"_id": null,
"home_page": null,
"name": "monaco-dict-utils",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.11",
"maintainer_email": null,
"keywords": "monaco, Monte Carlo, Monte Carlo methods, Monte Carlo simulation, data analysis",
"author": null,
"author_email": "Harold Martin <Harold.Martin@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/11/3c/1ab278bd2f3ce478a03fc2b33411a75a2850e26e0a3a266f808e42c92d63/monaco_dict_utils-0.1.0.tar.gz",
"platform": null,
"description": "[](https://pypi.org/project/monaco-dict-utils/)\n[](https://github.com/hbmartin/monaco-dict-utils/actions/workflows/lint.yml)\n[](https://github.com/astral-sh/ruff)\n[](https://github.com/psf/black)\n\n# Monaco Dictionary Utils\n\nA Python library for easily bootstrapping Monaco Monte Carlo simulations with a dictionary-based workflow.\n\n[See example notebook here](https://github.com/hbmartin/ai-roi-mcm-npv-marimo/blob/main/ai_roi_mcm_npv.py)\n\n## Overview\n\nMonaco Dictionary Utils provides a simplified interface for creating and running Monte Carlo simulations using the Monaco framework. It streamlines the process of setting up simulations by allowing you to define model factories, input parameters, and distributions using dictionary-based configuration.\n\n## Features\n\n- **Dictionary-based configuration**: Define simulations using simple dictionary structures\n- **Model factory support**: Create models from factory functions with configurable parameters\n- **Input variable management**: Handle both probabilistic distributions and constants\n- **Output conversion**: Convert simulation results to easily accessible dictionary format\n- **Parameter normalization**: Automatic parameter name normalization for consistency\n\n## Installation\n\n```bash\nuv add monaco-dict-utils\n```\n\n## Requirements\n\n- Python \u2265 3.11\n- Monaco \u2265 0.16.0\n\n## Quick Start\n\n```python\nfrom monaco_dict_utils import sim_factory, outvals_to_dict\n\n# Define your model factory\ndef my_model_factory(param1, param2):\n def model(x, y):\n return {\"result\": x * param1 + y * param2}\n return model\n\n# Configure simulation\nfactory_vars = {\"param1\": 2, \"param2\": 3}\ninvars = {\n \"x\": {\"dist\": \"uniform\", \"params\": {\"loc\": 0, \"scale\": 1}},\n \"y\": {\"dist\": \"_constant\", \"params\": 5}\n}\n\n# Create and run simulation\nsim = sim_factory(\n name=\"my_simulation\",\n model_factory=my_model_factory,\n factory_vars=factory_vars,\n invars=invars,\n ndraws=1000\n)\n\nsim.run()\n\n# Convert outputs to dictionary\nresults = outvals_to_dict(sim)\n```\n\n## API Reference\n\n#### `sim_factory(name, model_factory, factory_vars, invars, ndraws, *, verbose=True, debug=False)`\n\nCreate a Monte Carlo simulation from a model factory and parameters.\n\n**Parameters:**\n- `name` (str): Name of the simulation\n- `model_factory` (Callable): Factory function that creates the model\n- `factory_vars` (dict): Dictionary of variables to pass to model factory\n- `invars` (dict): Dictionary mapping input names to distribution parameters\n- `ndraws` (int): Number of Monte Carlo draws to simulate\n- `verbose` (bool, optional): Whether to print simulation progress. Defaults to True.\n- `debug` (bool, optional): Whether to run in debug mode. Defaults to False.\n\n**Returns:**\n- `Sim`: Configured Monaco Sim object ready to run simulations\n\n**Example:**\n```python\nsim = sim_factory(\n name=\"example_sim\",\n model_factory=my_factory,\n factory_vars={\"param\": 10},\n invars={\"x\": {\"dist\": \"normal\", \"params\": {\"loc\": 0, \"scale\": 1}}},\n ndraws=5000\n)\n```\n\n#### `outvals_to_dict(sim)`\n\nConvert simulation output values to a dictionary.\n\n**Parameters:**\n- `sim` (Sim): A Monaco Sim object that has been run\n\n**Returns:**\n- `dict`: Dictionary mapping output variable names to numpy arrays of output values\n\n**Example:**\n```python\nresults = outvals_to_dict(sim)\n# results = {\"Result\": array([1.23, 4.56, ...]), \"Other_Output\": array([...])}\n```\n\n## Input Variables Configuration\n\nThe `invars` dictionary supports two types of inputs:\n\n### 1. Probabilistic Distributions\n\nFor random variables, specify a distribution and its parameters:\n\n```python\ninvars = {\n \"temperature\": {\n \"dist\": \"normal\",\n \"params\": {\"loc\": 20, \"scale\": 5}\n },\n \"pressure\": {\n \"dist\": \"uniform\", \n \"params\": {\"loc\": 10, \"scale\": 2}\n }\n}\n```\n\n### 2. Constants\n\nFor constant values, use the special `_constant` distribution:\n\n```python\ninvars = {\n \"gravity\": {\n \"dist\": \"_constant\",\n \"params\": 9.81\n },\n \"config\": {\n \"dist\": \"_constant\",\n \"params\": {\"setting1\": 100, \"setting2\": 200}\n }\n}\n```\n\n## Parameter Normalization\n\nThe library automatically normalizes parameter names by:\n- Converting to lowercase\n- Removing special characters\n- Replacing spaces with underscores\n\nFor example: `\"Air Temperature\"` becomes `\"air_temperature\"`\n\n## Output Formatting\n\nOutput values are automatically formatted with:\n- Title case conversion\n- Underscore preservation\n- Example: `\"time_savings\"` becomes `\"Time_Savings\"`\n\n",
"bugtrack_url": null,
"license": null,
"summary": "Easily bootstrap Monaco Monte Carlo simulations with a dictionary based workflow.",
"version": "0.1.0",
"project_urls": null,
"split_keywords": [
"monaco",
" monte carlo",
" monte carlo methods",
" monte carlo simulation",
" data analysis"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "5b49aaad78af64fef98decbed8c6d4c70785ddae20e34b7903caee6226781ce6",
"md5": "deaa51efc557435db13c5e6bcafed880",
"sha256": "b9ae55ba34c68e5396f2f7cdcb5d338832173230bc268d094d46a991ae2605c0"
},
"downloads": -1,
"filename": "monaco_dict_utils-0.1.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "deaa51efc557435db13c5e6bcafed880",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.11",
"size": 7158,
"upload_time": "2025-07-16T21:12:15",
"upload_time_iso_8601": "2025-07-16T21:12:15.182100Z",
"url": "https://files.pythonhosted.org/packages/5b/49/aaad78af64fef98decbed8c6d4c70785ddae20e34b7903caee6226781ce6/monaco_dict_utils-0.1.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "113c1ab278bd2f3ce478a03fc2b33411a75a2850e26e0a3a266f808e42c92d63",
"md5": "5c8738853ecca95635c8714d2eb6140c",
"sha256": "fa0c997a1a5480a8487c0e047668a3caebcd7b3276d22102e332fa6b1d9db133"
},
"downloads": -1,
"filename": "monaco_dict_utils-0.1.0.tar.gz",
"has_sig": false,
"md5_digest": "5c8738853ecca95635c8714d2eb6140c",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.11",
"size": 7905,
"upload_time": "2025-07-16T21:12:16",
"upload_time_iso_8601": "2025-07-16T21:12:16.423502Z",
"url": "https://files.pythonhosted.org/packages/11/3c/1ab278bd2f3ce478a03fc2b33411a75a2850e26e0a3a266f808e42c92d63/monaco_dict_utils-0.1.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-07-16 21:12:16",
"github": false,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"lcname": "monaco-dict-utils"
}
JSON