Metadata-Version: 2.4
Name: obgeneration
Version: 0.1.1
Summary: Occupancy generation models
License-Expression: MIT
License-File: LICENSE
Requires-Python: >=3.10
Requires-Dist: matplotlib>=3.7.0
Requires-Dist: numpy>=1.24.0
Requires-Dist: pandas>=2.2
Requires-Dist: pydantic>=2.0.0
Requires-Dist: scipy>=1.10.0
Provides-Extra: dev
Requires-Dist: hypothesis>=6.90.0; extra == 'dev'
Requires-Dist: pytest-cov>=4.1.0; extra == 'dev'
Requires-Dist: pytest-xdist>=3.3.0; extra == 'dev'
Requires-Dist: pytest>=7.4.0; extra == 'dev'
Description-Content-Type: text/markdown

# Occupant Behavior Generation

`obgeneration` generates annual residential occupant-behavior schedules from a structured occupant profile.

Outputs include:

- occupancy fraction
- lighting usage
- equipment power
- domestic hot water usage
- HVAC setpoints
- window opening fraction

## Structure

```text
src/obgeneration/
├── model/       Pydantic input models
├── generator/   Schedule generators and orchestrator
├── stochastic/  Probability distributions and Markov logic
└── data/        Packaged CSV/JSON runtime assumptions
```

## Installation

```bash
git clone <repo-url>
cd OccupancyGeneration
uv sync
```

For development:

```bash
uv sync --extra dev
```

## Usage

```python
from obgeneration.model import Occupant
from obgeneration.generator import OccupantBehavior

profile = Occupant.from_json_file("test/unit/input/OB_1.json")
annual = OccupantBehavior.to_OB_annual(
    resolution_mins=15,
    occupant_profile=profile,
)

print(annual.num_occupants)
print(len(annual.occupancy_schedule))
```

## Generator Results

The generator convenience methods return structured result models rather than
bare tuples. For example:

```python
from obgeneration.generator import OccupancyGenerator

result = OccupancyGenerator.generate_with_defaults(
    occupancy=profile.occupancy,
    resolution_mins=15,
    rng=42,
)

print(result.peak_value)
print(len(result.schedule))
```

For explicit assumptions and downstream integration, use `generate_result(...)`:

```python
from obgeneration.generator import (
    ClusterAssumptions,
    OccupancyGenerator,
)

result = OccupancyGenerator.generate_result(
    occupancy=profile.occupancy,
    cluster_assumptions=ClusterAssumptions.default(),
    resolution_mins=15,
    rng=42,
)
```
