rooftex 0.1.0__tar.gz

rooftex-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 RoofteX Development Team
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

rooftex-0.1.0/PKG-INFO

@@ -0,0 +1,82 @@
+Metadata-Version: 2.4
+Name: rooftex
+Version: 0.1.0
+Summary: RoofteX - Rooftop Solar eXchange: rooftop PV potential, adoption dynamics, and profile generation
+Author: RoofteX Development Team
+License: MIT
+Project-URL: Homepage, https://github.com/rooftex-dev/rooftex
+Project-URL: Repository, https://github.com/rooftex-dev/rooftex
+Keywords: rooftop solar,photovoltaic,renewable energy,adoption dynamics,solar profiles,distributed generation
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering
+Classifier: Topic :: Scientific/Engineering :: Physics
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy>=1.22
+Provides-Extra: viz
+Requires-Dist: matplotlib>=3.4; extra == "viz"
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: pytest-cov>=4.0; extra == "dev"
+Requires-Dist: ruff>=0.1; extra == "dev"
+Requires-Dist: build>=1.0; extra == "dev"
+Requires-Dist: twine>=4.0; extra == "dev"
+Provides-Extra: all
+Requires-Dist: matplotlib>=3.4; extra == "all"
+Requires-Dist: pytest>=7.0; extra == "all"
+Requires-Dist: pytest-cov>=4.0; extra == "all"
+Dynamic: license-file
+
+# RoofteX — Rooftop Solar eXchange
+
+[![Tests](https://github.com/msotocalvo/rooftex/actions/workflows/tests.yml/badge.svg)](https://github.com/msotocalvo/rooftex/actions/workflows/tests.yml)
+[![DOI](https://zenodo.org/badge/1175040710.svg)](https://doi.org/10.5281/zenodo.18898422)
+
+A Python library for rooftop solar potential assessment, adoption dynamics modeling,
+and stochastic availability profile generation.
+
+## Features
+
+- **Rooftop Potential**: Estimate maximum rooftop PV capacity from population and dwelling data
+- **Adoption Dynamics**: S-curve adoption modeling with urbanization and scenario parameters
+- **Profile Generation**: Stochastic hourly solar profiles with cloud patterns and weather variability
+- **Cost Learning Curve**: Technology cost projection with degradation and learning rates
+
+## Installation
+
+```bash
+pip install rooftex
+```
+
+## Quick Start
+
+```python
+from rooftex import RooftopConfig, generate_profiles, calculate_potential
+
+# Estimate potential from population
+potential = calculate_potential(population=[50000, 30000, 80000])
+
+# Generate hourly availability profiles
+config = RooftopConfig(
+    num_nodes=3,
+    hours=8760,
+    adoption_scenario="medium",
+    target_year=2040,
+)
+result = generate_profiles(config)
+print(result.availability.shape)      # (8760, 3)
+print(result.adoption_factors.mean())  # ~0.3
+```
+
+## License
+
+MIT

rooftex-0.1.0/README.md

@@ -0,0 +1,44 @@
+# RoofteX — Rooftop Solar eXchange
+
+[![Tests](https://github.com/msotocalvo/rooftex/actions/workflows/tests.yml/badge.svg)](https://github.com/msotocalvo/rooftex/actions/workflows/tests.yml)
+[![DOI](https://zenodo.org/badge/1175040710.svg)](https://doi.org/10.5281/zenodo.18898422)
+
+A Python library for rooftop solar potential assessment, adoption dynamics modeling,
+and stochastic availability profile generation.
+
+## Features
+
+- **Rooftop Potential**: Estimate maximum rooftop PV capacity from population and dwelling data
+- **Adoption Dynamics**: S-curve adoption modeling with urbanization and scenario parameters
+- **Profile Generation**: Stochastic hourly solar profiles with cloud patterns and weather variability
+- **Cost Learning Curve**: Technology cost projection with degradation and learning rates
+
+## Installation
+
+```bash
+pip install rooftex
+```
+
+## Quick Start
+
+```python
+from rooftex import RooftopConfig, generate_profiles, calculate_potential
+
+# Estimate potential from population
+potential = calculate_potential(population=[50000, 30000, 80000])
+
+# Generate hourly availability profiles
+config = RooftopConfig(
+    num_nodes=3,
+    hours=8760,
+    adoption_scenario="medium",
+    target_year=2040,
+)
+result = generate_profiles(config)
+print(result.availability.shape)      # (8760, 3)
+print(result.adoption_factors.mean())  # ~0.3
+```
+
+## License
+
+MIT

rooftex-0.1.0/pyproject.toml

@@ -0,0 +1,84 @@
+[build-system]
+requires = ["setuptools>=64", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "rooftex"
+version = "0.1.0"
+description = "RoofteX - Rooftop Solar eXchange: rooftop PV potential, adoption dynamics, and profile generation"
+readme = "README.md"
+license = {text = "MIT"}
+requires-python = ">=3.9"
+authors = [
+    {name = "RoofteX Development Team"},
+]
+keywords = [
+    "rooftop solar",
+    "photovoltaic",
+    "renewable energy",
+    "adoption dynamics",
+    "solar profiles",
+    "distributed generation",
+]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Science/Research",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Scientific/Engineering",
+    "Topic :: Scientific/Engineering :: Physics",
+]
+
+dependencies = [
+    "numpy>=1.22",
+]
+
+[project.optional-dependencies]
+viz = ["matplotlib>=3.4"]
+dev = [
+    "pytest>=7.0",
+    "pytest-cov>=4.0",
+    "ruff>=0.1",
+    "build>=1.0",
+    "twine>=4.0",
+]
+all = [
+    "matplotlib>=3.4",
+    "pytest>=7.0",
+    "pytest-cov>=4.0",
+]
+
+[project.urls]
+Homepage = "https://github.com/rooftex-dev/rooftex"
+Repository = "https://github.com/rooftex-dev/rooftex"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+include = ["rooftex*"]
+exclude = ["tests*"]
+
+[tool.pytest.ini_options]
+minversion = "7.0"
+addopts = "-ra -q --strict-markers"
+testpaths = ["tests"]
+filterwarnings = [
+    "ignore::DeprecationWarning",
+    "ignore::UserWarning",
+]
+
+[tool.ruff]
+target-version = "py39"
+line-length = 100
+
+[tool.ruff.lint]
+select = ["E", "W", "F", "I", "B", "C4", "UP"]
+ignore = ["E501", "B008", "C901"]
+
+[tool.ruff.lint.per-file-ignores]
+"__init__.py" = ["F401"]
+"tests/*" = ["B011"]

rooftex-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

rooftex-0.1.0/src/rooftex/__init__.py

@@ -0,0 +1,38 @@
+"""
+RoofteX — Rooftop Solar eXchange
+
+A Python library for rooftop solar potential assessment, adoption dynamics,
+and stochastic availability profile generation.
+
+Modules:
+- rooftex.core: Adoption curves, solar profiles, rooftop potential
+- rooftex.economics: Cost learning curves and integration
+- rooftex.config: Configuration dataclasses
+"""
+
+__version__ = "0.1.0"
+__author__ = "RoofteX Development Team"
+
+from .config import RooftopConfig
+from .results import RooftopResult
+
+from .core.adoption import compute_adoption_curve
+from .core.profiles import generate_profiles
+from .core.potential import calculate_potential
+
+from .economics.learning_curve import compute_learning_curve, compute_installed_capacity
+
+__all__ = [
+    "__version__",
+    # Config
+    "RooftopConfig",
+    # Results
+    "RooftopResult",
+    # Core
+    "compute_adoption_curve",
+    "generate_profiles",
+    "calculate_potential",
+    # Economics
+    "compute_learning_curve",
+    "compute_installed_capacity",
+]

rooftex-0.1.0/src/rooftex/config.py

@@ -0,0 +1,77 @@
+"""Configuration dataclasses for RoofteX."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Optional
+
+
+@dataclass
+class RooftopConfig:
+    """Configuration for rooftop solar profile generation.
+
+    Parameters
+    ----------
+    num_nodes : int
+        Number of nodes in the system.
+    hours : int
+        Number of hours to simulate (default 8760 = 1 year).
+    base_year : int
+        Base year for adoption calculation.
+    target_year : int
+        Target year for projections.
+    adoption_scenario : str
+        Adoption scenario: 'low', 'medium', or 'high'.
+    weather_variability : str
+        Weather variability level: 'low', 'normal', or 'high'.
+    seed : int or None
+        Random seed for reproducibility.
+    performance_ratio : float
+        Overall PV system performance ratio (0-1).
+    initial_adoption : list[float] or None
+        Initial adoption fraction per node. If None, defaults to 0.05.
+    systems_per_node : list[int] or None
+        Number of potential rooftop systems per node.
+    avg_system_size_kw : list[float] or None
+        Average system size in kW per node.
+    adoption_rates : dict[str, float] or None
+        Custom adoption rate per scenario. Defaults to low=0.05, medium=0.08, high=0.12.
+    max_adoption : dict[str, float] or None
+        Maximum adoption fraction per scenario. Defaults to low=0.30, medium=0.50, high=0.70.
+    """
+
+    num_nodes: int = 1
+    hours: int = 8760
+    base_year: int = 2024
+    target_year: int = 2050
+    adoption_scenario: str = "medium"
+    weather_variability: str = "normal"
+    seed: Optional[int] = None
+    performance_ratio: float = 0.75
+    initial_adoption: Optional[list[float]] = None
+    systems_per_node: Optional[list[int]] = None
+    avg_system_size_kw: Optional[list[float]] = None
+    adoption_rates: Optional[dict[str, float]] = None
+    max_adoption: Optional[dict[str, float]] = None
+
+
+@dataclass
+class LearningCurveConfig:
+    """Configuration for cost learning curve projections.
+
+    Parameters
+    ----------
+    base_cost_per_kw : float
+        Base installation cost in $/kW.
+    cost_reduction_rate : float
+        Annual cost reduction rate (learning rate).
+    degradation_rate : float
+        Annual panel degradation rate.
+    o_and_m_cost : float
+        Annual O&M cost in $/kW.
+    """
+
+    base_cost_per_kw: float = 1200.0
+    cost_reduction_rate: float = 0.08
+    degradation_rate: float = 0.005
+    o_and_m_cost: float = 20.0

rooftex-0.1.0/src/rooftex/core/__init__.py

@@ -0,0 +1,11 @@
+"""Core rooftop solar computation modules."""
+
+from .adoption import compute_adoption_curve
+from .profiles import generate_profiles
+from .potential import calculate_potential
+
+__all__ = [
+    "compute_adoption_curve",
+    "generate_profiles",
+    "calculate_potential",
+]

rooftex-0.1.0/src/rooftex/core/adoption.py

@@ -0,0 +1,102 @@
+"""S-curve adoption dynamics for rooftop solar.
+
+Models technology adoption using logistic (S-curve) functions with
+urbanization factors and scenario-dependent parameters.
+"""
+
+from __future__ import annotations
+
+import numpy as np
+
+
+# Default adoption rates per scenario
+_DEFAULT_ADOPTION_RATES = {
+    "low": 0.05,
+    "medium": 0.08,
+    "high": 0.12,
+}
+
+# Default maximum adoption per scenario
+_DEFAULT_MAX_ADOPTION = {
+    "low": 0.30,
+    "medium": 0.50,
+    "high": 0.70,
+}
+
+
+def compute_adoption_curve(
+    num_nodes: int,
+    base_year: int,
+    target_year: int,
+    adoption_scenario: str = "medium",
+    initial_adoption: list[float] | None = None,
+    adoption_rates: dict[str, float] | None = None,
+    max_adoption: dict[str, float] | None = None,
+    urbanization_factors: np.ndarray | None = None,
+    rng: np.random.Generator | None = None,
+) -> np.ndarray:
+    """Compute adoption factors at the target year using S-curve dynamics.
+
+    Each node gets a logistic adoption curve influenced by its urbanization
+    factor and the chosen scenario.
+
+    Parameters
+    ----------
+    num_nodes : int
+        Number of nodes.
+    base_year : int
+        Base year for adoption calculation.
+    target_year : int
+        Year at which to evaluate adoption.
+    adoption_scenario : str
+        Scenario: 'low', 'medium', or 'high'.
+    initial_adoption : list[float] or None
+        Initial adoption fraction per node. Defaults to 0.05.
+    adoption_rates : dict[str, float] or None
+        Custom adoption rates per scenario.
+    max_adoption : dict[str, float] or None
+        Maximum adoption fraction per scenario.
+    urbanization_factors : np.ndarray or None
+        Urbanization factor per node in [0, 1]. If None, drawn from Beta(2,2).
+    rng : np.random.Generator or None
+        Random number generator.
+
+    Returns
+    -------
+    np.ndarray
+        Adoption factors per node at target_year, shape (num_nodes,).
+    """
+    if rng is None:
+        rng = np.random.default_rng()
+
+    rates = adoption_rates or _DEFAULT_ADOPTION_RATES
+    max_adopt = max_adoption or _DEFAULT_MAX_ADOPTION
+
+    adoption_rate = rates.get(adoption_scenario, 0.08)
+    max_adoption_val = max_adopt.get(adoption_scenario, 0.50)
+
+    years_diff = target_year - base_year
+
+    # Initial adoption per node
+    if initial_adoption is not None:
+        init = list(initial_adoption)
+        while len(init) < num_nodes:
+            init.append(init[-1] if init else 0.05)
+    else:
+        init = [0.05] * num_nodes
+
+    # Urbanization
+    if urbanization_factors is None:
+        urbanization_factors = rng.beta(2, 2, num_nodes)
+    else:
+        urbanization_factors = np.asarray(urbanization_factors)
+
+    adoption = np.zeros(num_nodes)
+    for node in range(num_nodes):
+        node_max = min(0.9, max_adoption_val * (0.8 + 0.4 * urbanization_factors[node]))
+        mid_point = base_year + years_diff * (0.4 + 0.2 * rng.random())
+        growth_rate = adoption_rate * (0.8 + 0.4 * urbanization_factors[node])
+
+        adoption[node] = node_max / (1 + np.exp(-growth_rate * (target_year - mid_point)))
+
+    return adoption

rooftex-0.1.0/src/rooftex/core/potential.py

@@ -0,0 +1,99 @@
+"""Rooftop solar potential estimation.
+
+Estimates maximum rooftop PV capacity from population, dwelling density,
+and roof characteristics.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+import numpy as np
+
+if TYPE_CHECKING:
+    from rooftex.config import RooftopConfig
+
+
+def calculate_potential(
+    population: list[float],
+    dwelling_density: float = 0.35,
+    avg_roof_area: float = 50.0,
+    suitable_fraction: float = 0.3,
+    panel_efficiency: float = 0.20,
+    solar_irradiance: float = 1000.0,
+) -> list[float]:
+    """Calculate rooftop solar potential based on population.
+
+    Parameters
+    ----------
+    population : list[float]
+        Population per node.
+    dwelling_density : float
+        Dwellings per capita.
+    avg_roof_area : float
+        Average roof area in m².
+    suitable_fraction : float
+        Fraction of roof suitable for solar.
+    panel_efficiency : float
+        Solar panel efficiency (0-1).
+    solar_irradiance : float
+        Peak solar irradiance in W/m².
+
+    Returns
+    -------
+    list[float]
+        Maximum potential in MW per node.
+    """
+    max_potential = []
+    for pop in population:
+        num_dwellings = pop * dwelling_density
+        total_roof_area = num_dwellings * avg_roof_area * suitable_fraction
+        peak_power_kw = total_roof_area * panel_efficiency * solar_irradiance / 1000
+        max_potential.append(peak_power_kw / 1000)  # Convert to MW
+
+    return max_potential
+
+
+def calculate_potential_from_config(
+    config: "RooftopConfig",
+    urbanization_factors: np.ndarray | None = None,
+    rng: np.random.Generator | None = None,
+) -> list[float]:
+    """Calculate potential from config, using system specs or randomized base values.
+
+    Parameters
+    ----------
+    config : RooftopConfig
+        Configuration with optional systems_per_node and avg_system_size_kw.
+    urbanization_factors : np.ndarray or None
+        Urbanization factor per node. Used for random potential generation.
+    rng : np.random.Generator or None
+        Random number generator.
+
+    Returns
+    -------
+    list[float]
+        Maximum potential per node in MW.
+    """
+    if rng is None:
+        rng = np.random.default_rng()
+
+    num_nodes = config.num_nodes
+
+    if config.systems_per_node is not None and config.avg_system_size_kw is not None:
+        systems = list(config.systems_per_node)
+        sizes = list(config.avg_system_size_kw)
+
+        while len(systems) < num_nodes:
+            systems.append(systems[-1] if systems else 5000)
+        while len(sizes) < num_nodes:
+            sizes.append(sizes[-1] if sizes else 5.0)
+
+        return [systems[i] * sizes[i] / 1000 for i in range(num_nodes)]
+
+    # Random potential based on urbanization
+    if urbanization_factors is None:
+        urbanization_factors = rng.beta(2, 2, num_nodes)
+
+    base_potential = 50 + rng.gamma(shape=2.0, scale=30.0, size=num_nodes)
+    return list(base_potential * (0.5 + urbanization_factors))

rooftex-0.1.0/src/rooftex/core/profiles.py

@@ -0,0 +1,166 @@
+"""Stochastic rooftop solar profile generation.
+
+Generates hourly availability profiles with bell-curve solar patterns,
+weather variability, and cloud events.
+"""
+
+from __future__ import annotations
+
+from typing import Optional
+
+import numpy as np
+
+from rooftex.config import RooftopConfig
+from rooftex.core.adoption import compute_adoption_curve
+from rooftex.core.potential import calculate_potential_from_config
+from rooftex.results import RooftopResult
+
+
+# Weather variance maps
+_WEATHER_VARIANCE = {"low": 0.05, "normal": 0.15, "high": 0.25}
+_NODE_VARIANCE = {"low": 0.10, "normal": 0.20, "high": 0.30}
+
+
+def generate_base_profile(hours: int, performance_ratio: float = 0.75) -> np.ndarray:
+    """Generate a base bell-shaped solar profile.
+
+    Parameters
+    ----------
+    hours : int
+        Number of hours to simulate.
+    performance_ratio : float
+        System performance ratio (0-1).
+
+    Returns
+    -------
+    np.ndarray
+        Base solar profile, shape (hours,).
+    """
+    hours_mod = np.arange(hours) % 24
+    profile = np.zeros(hours)
+
+    daylight = (hours_mod >= 6) & (hours_mod <= 18)
+    profile[daylight] = np.sin(np.pi * (hours_mod[daylight] - 6) / 12)
+
+    return profile * performance_ratio
+
+
+def generate_cloud_pattern(
+    hours: int,
+    cloud_probability: float = 0.3,
+    rng: np.random.Generator | None = None,
+) -> np.ndarray:
+    """Generate stochastic cloud patterns.
+
+    Parameters
+    ----------
+    hours : int
+        Number of hours.
+    cloud_probability : float
+        Daily probability of cloud events.
+    rng : np.random.Generator or None
+        Random number generator.
+
+    Returns
+    -------
+    np.ndarray
+        Cloud attenuation pattern, shape (hours,). Values in [0, 1].
+    """
+    if rng is None:
+        rng = np.random.default_rng()
+
+    num_days = max(1, hours // 24)
+    pattern = np.zeros(hours)
+
+    for day in range(num_days):
+        if rng.random() < cloud_probability:
+            cloud_start = rng.integers(6, 16)
+            cloud_duration = rng.integers(1, 4)
+            cloud_intensity = rng.uniform(0.3, 0.7)
+            day_offset = day * 24
+            for h in range(cloud_start, min(cloud_start + cloud_duration, 24)):
+                idx = day_offset + h
+                if idx < hours:
+                    pattern[idx] = cloud_intensity
+
+    return pattern
+
+
+def generate_profiles(config: RooftopConfig) -> RooftopResult:
+    """Generate stochastic rooftop solar availability profiles.
+
+    Creates hourly availability matrices with weather variability, cloud
+    patterns, and node-specific factors. Also computes adoption curves
+    and maximum potential.
+
+    Parameters
+    ----------
+    config : RooftopConfig
+        Configuration parameters.
+
+    Returns
+    -------
+    RooftopResult
+        Result containing availability matrix, adoption factors, and potentials.
+    """
+    rng = np.random.default_rng(config.seed)
+
+    num_nodes = config.num_nodes
+    hours = config.hours
+
+    # Base solar profile
+    base_profile = generate_base_profile(hours, config.performance_ratio)
+
+    # Weather variability
+    weather_var = _WEATHER_VARIANCE.get(config.weather_variability, 0.15)
+    node_var = _NODE_VARIANCE.get(config.weather_variability, 0.20)
+
+    # Urbanization factors
+    urbanization = rng.beta(2, 2, num_nodes)
+
+    # Maximum potential
+    max_potential = calculate_potential_from_config(config, urbanization, rng)
+
+    # Daily weather component (shared across nodes)
+    num_days = max(1, hours // 24)
+    daily_weather = np.clip(
+        rng.normal(1.0, weather_var, num_days), 0.2, 1.8
+    )
+    daily_weather = np.repeat(daily_weather, 24)[:hours]
+
+    # Generate availability per node
+    availability = np.zeros((hours, num_nodes))
+
+    for node in range(num_nodes):
+        node_factor = float(np.clip(rng.normal(1.0, node_var), 0.6, 1.4))
+        hourly_noise = rng.normal(0, 0.05, hours)
+        cloud_pattern = generate_cloud_pattern(hours, rng=rng)
+
+        for h in range(hours):
+            raw = (
+                base_profile[h]
+                * node_factor
+                * daily_weather[h]
+                * (1 - cloud_pattern[h])
+                + hourly_noise[h]
+            )
+            availability[h, node] = max(0.0, min(1.0, raw))
+
+    # Adoption factors
+    adoption = compute_adoption_curve(
+        num_nodes=num_nodes,
+        base_year=config.base_year,
+        target_year=config.target_year,
+        adoption_scenario=config.adoption_scenario,
+        initial_adoption=config.initial_adoption,
+        adoption_rates=config.adoption_rates,
+        max_adoption=config.max_adoption,
+        urbanization_factors=urbanization,
+        rng=rng,
+    )
+
+    return RooftopResult(
+        availability=availability,
+        adoption_factors=adoption,
+        max_potential_mw=max_potential,
+    )

rooftex-0.1.0/src/rooftex/economics/__init__.py

@@ -0,0 +1,8 @@
+"""Economics modules for rooftop solar."""
+
+from .learning_curve import compute_learning_curve, compute_installed_capacity
+
+__all__ = [
+    "compute_learning_curve",
+    "compute_installed_capacity",
+]

rooftex-0.1.0/src/rooftex/economics/learning_curve.py

@@ -0,0 +1,114 @@
+"""Cost learning curve and capacity integration for rooftop solar.
+
+Models technology cost reduction over time and computes installed
+capacity accounting for adoption dynamics and degradation.
+"""
+
+from __future__ import annotations
+
+import numpy as np
+
+from rooftex.config import LearningCurveConfig
+from rooftex.results import LearningCurveResult
+
+
+def compute_learning_curve(
+    base_year: int,
+    target_year: int,
+    config: LearningCurveConfig | None = None,
+    years: list[int] | None = None,
+) -> list[tuple[int, float]]:
+    """Compute cost trajectory using exponential learning curve.
+
+    Parameters
+    ----------
+    base_year : int
+        Base year (cost = base_cost_per_kw).
+    target_year : int
+        Final year to compute.
+    config : LearningCurveConfig or None
+        Cost parameters. Uses defaults if None.
+    years : list[int] or None
+        Specific years to evaluate. If None, evaluates every year.
+
+    Returns
+    -------
+    list[tuple[int, float]]
+        List of (year, cost_per_kw) tuples.
+    """
+    if config is None:
+        config = LearningCurveConfig()
+
+    if years is None:
+        years = list(range(base_year, target_year + 1))
+
+    result = []
+    for year in years:
+        years_diff = year - base_year
+        cost_factor = (1 - config.cost_reduction_rate) ** years_diff
+        cost = config.base_cost_per_kw * cost_factor
+        result.append((year, cost))
+
+    return result
+
+
+def compute_installed_capacity(
+    year: int,
+    base_year: int,
+    target_year: int,
+    max_potential_mw: list[float],
+    adoption_factors: np.ndarray,
+    config: LearningCurveConfig | None = None,
+) -> LearningCurveResult:
+    """Compute installed capacity and cost at a specific year.
+
+    Applies S-curve progress factor and degradation to the adoption-based
+    capacity estimate.
+
+    Parameters
+    ----------
+    year : int
+        Year to evaluate.
+    base_year : int
+        Base year.
+    target_year : int
+        Target year for full adoption.
+    max_potential_mw : list[float]
+        Maximum potential per node in MW.
+    adoption_factors : np.ndarray
+        Adoption factors per node (from compute_adoption_curve).
+    config : LearningCurveConfig or None
+        Cost parameters. Uses defaults if None.
+
+    Returns
+    -------
+    LearningCurveResult
+        Installed capacity and cost information.
+    """
+    if config is None:
+        config = LearningCurveConfig()
+
+    years_diff = year - base_year
+
+    # S-curve progress
+    progress = min(1.0, years_diff / max(1, target_year - base_year))
+    s_curve = 1.0 / (1.0 + np.exp(-10.0 * (progress - 0.5)))
+
+    current_adoption = adoption_factors * s_curve
+
+    # Installed capacity with degradation
+    installed = np.array(max_potential_mw) * current_adoption
+    degradation = 1.0 - (config.degradation_rate * years_diff / 2)
+    installed = installed * degradation
+
+    # Cost
+    cost_factor = (1 - config.cost_reduction_rate) ** years_diff
+    cost_per_kw = config.base_cost_per_kw * cost_factor
+
+    return LearningCurveResult(
+        year=year,
+        cost_per_kw=cost_per_kw,
+        cost_factor=cost_factor,
+        installed_capacity_mw=installed,
+        total_installed_mw=float(np.sum(installed)),
+    )

rooftex-0.1.0/src/rooftex/results.py

@@ -0,0 +1,77 @@
+"""Result dataclasses for RoofteX."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any
+
+import numpy as np
+
+
+@dataclass
+class RooftopResult:
+    """Result of rooftop solar profile generation.
+
+    Attributes
+    ----------
+    availability : np.ndarray
+        Hourly availability matrix, shape (hours, num_nodes). Values in [0, 1].
+    adoption_factors : np.ndarray
+        Adoption factor per node at the target year.
+    max_potential_mw : list[float]
+        Maximum rooftop PV potential per node in MW.
+    """
+
+    availability: Any  # np.ndarray (hours, num_nodes)
+    adoption_factors: Any  # np.ndarray (num_nodes,)
+    max_potential_mw: list[float]
+
+    def compute_statistics(self) -> dict:
+        """Compute summary statistics.
+
+        Returns
+        -------
+        dict
+            Dictionary with mean_cf, peak_cf, mean_adoption, total_potential_mw.
+        """
+        avail = np.asarray(self.availability)
+        return {
+            "mean_cf": float(np.nanmean(avail[avail > 0])) if np.any(avail > 0) else 0.0,
+            "peak_cf": float(np.nanmax(avail)),
+            "mean_adoption": float(np.mean(self.adoption_factors)),
+            "total_potential_mw": sum(self.max_potential_mw),
+        }
+
+    def to_dict(self) -> dict:
+        """Convert result to dictionary."""
+        return {
+            "availability": np.asarray(self.availability).tolist(),
+            "adoption_factors": np.asarray(self.adoption_factors).tolist(),
+            "max_potential_mw": list(self.max_potential_mw),
+            "statistics": self.compute_statistics(),
+        }
+
+
+@dataclass
+class LearningCurveResult:
+    """Result of cost learning curve computation.
+
+    Attributes
+    ----------
+    year : int
+        Target year.
+    cost_per_kw : float
+        Projected cost in $/kW.
+    cost_factor : float
+        Cost reduction factor relative to base year.
+    installed_capacity_mw : np.ndarray
+        Installed capacity per node in MW.
+    total_installed_mw : float
+        Total installed capacity in MW.
+    """
+
+    year: int
+    cost_per_kw: float
+    cost_factor: float
+    installed_capacity_mw: Any  # np.ndarray
+    total_installed_mw: float

rooftex-0.1.0/src/rooftex.egg-info/PKG-INFO

@@ -0,0 +1,82 @@
+Metadata-Version: 2.4
+Name: rooftex
+Version: 0.1.0
+Summary: RoofteX - Rooftop Solar eXchange: rooftop PV potential, adoption dynamics, and profile generation
+Author: RoofteX Development Team
+License: MIT
+Project-URL: Homepage, https://github.com/rooftex-dev/rooftex
+Project-URL: Repository, https://github.com/rooftex-dev/rooftex
+Keywords: rooftop solar,photovoltaic,renewable energy,adoption dynamics,solar profiles,distributed generation
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering
+Classifier: Topic :: Scientific/Engineering :: Physics
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy>=1.22
+Provides-Extra: viz
+Requires-Dist: matplotlib>=3.4; extra == "viz"
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: pytest-cov>=4.0; extra == "dev"
+Requires-Dist: ruff>=0.1; extra == "dev"
+Requires-Dist: build>=1.0; extra == "dev"
+Requires-Dist: twine>=4.0; extra == "dev"
+Provides-Extra: all
+Requires-Dist: matplotlib>=3.4; extra == "all"
+Requires-Dist: pytest>=7.0; extra == "all"
+Requires-Dist: pytest-cov>=4.0; extra == "all"
+Dynamic: license-file
+
+# RoofteX — Rooftop Solar eXchange
+
+[![Tests](https://github.com/msotocalvo/rooftex/actions/workflows/tests.yml/badge.svg)](https://github.com/msotocalvo/rooftex/actions/workflows/tests.yml)
+[![DOI](https://zenodo.org/badge/1175040710.svg)](https://doi.org/10.5281/zenodo.18898422)
+
+A Python library for rooftop solar potential assessment, adoption dynamics modeling,
+and stochastic availability profile generation.
+
+## Features
+
+- **Rooftop Potential**: Estimate maximum rooftop PV capacity from population and dwelling data
+- **Adoption Dynamics**: S-curve adoption modeling with urbanization and scenario parameters
+- **Profile Generation**: Stochastic hourly solar profiles with cloud patterns and weather variability
+- **Cost Learning Curve**: Technology cost projection with degradation and learning rates
+
+## Installation
+
+```bash
+pip install rooftex
+```
+
+## Quick Start
+
+```python
+from rooftex import RooftopConfig, generate_profiles, calculate_potential
+
+# Estimate potential from population
+potential = calculate_potential(population=[50000, 30000, 80000])
+
+# Generate hourly availability profiles
+config = RooftopConfig(
+    num_nodes=3,
+    hours=8760,
+    adoption_scenario="medium",
+    target_year=2040,
+)
+result = generate_profiles(config)
+print(result.availability.shape)      # (8760, 3)
+print(result.adoption_factors.mean())  # ~0.3
+```
+
+## License
+
+MIT

rooftex-0.1.0/src/rooftex.egg-info/SOURCES.txt

@@ -0,0 +1,20 @@
+LICENSE
+README.md
+pyproject.toml
+src/rooftex/__init__.py
+src/rooftex/config.py
+src/rooftex/results.py
+src/rooftex.egg-info/PKG-INFO
+src/rooftex.egg-info/SOURCES.txt
+src/rooftex.egg-info/dependency_links.txt
+src/rooftex.egg-info/requires.txt
+src/rooftex.egg-info/top_level.txt
+src/rooftex/core/__init__.py
+src/rooftex/core/adoption.py
+src/rooftex/core/potential.py
+src/rooftex/core/profiles.py
+src/rooftex/economics/__init__.py
+src/rooftex/economics/learning_curve.py
+tests/test_adoption.py
+tests/test_potential.py
+tests/test_profiles.py

rooftex-0.1.0/src/rooftex.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

rooftex-0.1.0/src/rooftex.egg-info/requires.txt

@@ -0,0 +1,16 @@
+numpy>=1.22
+
+[all]
+matplotlib>=3.4
+pytest>=7.0
+pytest-cov>=4.0
+
+[dev]
+pytest>=7.0
+pytest-cov>=4.0
+ruff>=0.1
+build>=1.0
+twine>=4.0
+
+[viz]
+matplotlib>=3.4

rooftex-0.1.0/src/rooftex.egg-info/top_level.txt

@@ -0,0 +1 @@
+rooftex

rooftex-0.1.0/tests/test_adoption.py

@@ -0,0 +1,61 @@
+"""Tests for rooftex.core.adoption."""
+
+import numpy as np
+import pytest
+
+from rooftex.core.adoption import compute_adoption_curve
+
+
+class TestAdoptionCurve:
+    def test_basic_shape(self):
+        result = compute_adoption_curve(
+            num_nodes=3,
+            base_year=2024,
+            target_year=2050,
+            rng=np.random.default_rng(42),
+        )
+        assert result.shape == (3,)
+        assert np.all(result >= 0)
+        assert np.all(result <= 1)
+
+    def test_higher_scenario_more_adoption(self):
+        rng_low = np.random.default_rng(42)
+        rng_high = np.random.default_rng(42)
+        low = compute_adoption_curve(
+            num_nodes=5, base_year=2024, target_year=2050,
+            adoption_scenario="low", rng=rng_low,
+        )
+        high = compute_adoption_curve(
+            num_nodes=5, base_year=2024, target_year=2050,
+            adoption_scenario="high", rng=rng_high,
+        )
+        assert np.mean(high) > np.mean(low)
+
+    def test_reproducibility(self):
+        a = compute_adoption_curve(
+            num_nodes=3, base_year=2024, target_year=2050,
+            rng=np.random.default_rng(99),
+        )
+        b = compute_adoption_curve(
+            num_nodes=3, base_year=2024, target_year=2050,
+            rng=np.random.default_rng(99),
+        )
+        np.testing.assert_array_equal(a, b)
+
+    def test_custom_initial_adoption(self):
+        result = compute_adoption_curve(
+            num_nodes=2, base_year=2024, target_year=2050,
+            initial_adoption=[0.1, 0.2],
+            rng=np.random.default_rng(42),
+        )
+        assert result.shape == (2,)
+
+    def test_custom_urbanization(self):
+        urban = np.array([0.9, 0.1])
+        result = compute_adoption_curve(
+            num_nodes=2, base_year=2024, target_year=2050,
+            urbanization_factors=urban,
+            rng=np.random.default_rng(42),
+        )
+        # Higher urbanization → higher adoption
+        assert result[0] > result[1]

rooftex-0.1.0/tests/test_potential.py

@@ -0,0 +1,41 @@
+"""Tests for rooftex.core.potential."""
+
+import pytest
+
+from rooftex.core.potential import calculate_potential
+
+
+class TestCalculatePotential:
+    def test_basic(self):
+        result = calculate_potential(population=[100000])
+        assert len(result) == 1
+        assert result[0] > 0
+
+    def test_multiple_nodes(self):
+        result = calculate_potential(population=[50000, 100000, 200000])
+        assert len(result) == 3
+        # Larger population → more potential
+        assert result[0] < result[1] < result[2]
+
+    def test_linear_scaling(self):
+        r1 = calculate_potential(population=[50000])
+        r2 = calculate_potential(population=[100000])
+        assert r2[0] == pytest.approx(r1[0] * 2, rel=1e-10)
+
+    def test_custom_params(self):
+        result = calculate_potential(
+            population=[100000],
+            dwelling_density=0.5,
+            avg_roof_area=40.0,
+            suitable_fraction=0.25,
+            panel_efficiency=0.22,
+            solar_irradiance=1000.0,
+        )
+        # 100000 * 0.5 = 50000 dwellings
+        # 50000 * 40 * 0.25 = 500000 m² suitable
+        # 500000 * 0.22 * 1000 / 1000 = 110000 kW = 110 MW
+        assert result[0] == pytest.approx(110.0)
+
+    def test_zero_population(self):
+        result = calculate_potential(population=[0])
+        assert result[0] == 0.0

rooftex-0.1.0/tests/test_profiles.py

@@ -0,0 +1,88 @@
+"""Tests for rooftex.core.profiles."""
+
+import numpy as np
+import pytest
+
+from rooftex.config import RooftopConfig
+from rooftex.core.profiles import generate_base_profile, generate_cloud_pattern, generate_profiles
+
+
+class TestBaseProfile:
+    def test_shape(self):
+        profile = generate_base_profile(8760)
+        assert profile.shape == (8760,)
+
+    def test_nighttime_zero(self):
+        profile = generate_base_profile(24)
+        # Hours 0-5 and 19-23 should be zero
+        assert profile[0] == 0.0
+        assert profile[3] == 0.0
+        assert profile[23] == 0.0
+
+    def test_peak_at_noon(self):
+        profile = generate_base_profile(24, performance_ratio=1.0)
+        assert profile[12] == pytest.approx(1.0, abs=0.01)
+
+    def test_performance_ratio(self):
+        p1 = generate_base_profile(24, performance_ratio=1.0)
+        p075 = generate_base_profile(24, performance_ratio=0.75)
+        np.testing.assert_allclose(p075, p1 * 0.75)
+
+
+class TestCloudPattern:
+    def test_shape(self):
+        pattern = generate_cloud_pattern(8760, rng=np.random.default_rng(42))
+        assert pattern.shape == (8760,)
+
+    def test_values_range(self):
+        pattern = generate_cloud_pattern(8760, rng=np.random.default_rng(42))
+        assert np.all(pattern >= 0)
+        assert np.all(pattern < 1)
+
+    def test_zero_probability(self):
+        pattern = generate_cloud_pattern(8760, cloud_probability=0.0, rng=np.random.default_rng(42))
+        assert np.all(pattern == 0)
+
+
+class TestGenerateProfiles:
+    def test_basic(self):
+        config = RooftopConfig(num_nodes=3, hours=48, seed=42)
+        result = generate_profiles(config)
+        assert result.availability.shape == (48, 3)
+        assert result.adoption_factors.shape == (3,)
+        assert len(result.max_potential_mw) == 3
+
+    def test_values_bounded(self):
+        config = RooftopConfig(num_nodes=2, hours=8760, seed=42)
+        result = generate_profiles(config)
+        assert np.all(result.availability >= 0)
+        assert np.all(result.availability <= 1)
+
+    def test_reproducibility(self):
+        config = RooftopConfig(num_nodes=2, hours=168, seed=99)
+        r1 = generate_profiles(config)
+        r2 = generate_profiles(config)
+        np.testing.assert_array_equal(r1.availability, r2.availability)
+
+    def test_statistics(self):
+        config = RooftopConfig(num_nodes=3, hours=8760, seed=42)
+        result = generate_profiles(config)
+        stats = result.compute_statistics()
+        assert "mean_cf" in stats
+        assert "peak_cf" in stats
+        assert stats["mean_cf"] > 0
+        assert stats["total_potential_mw"] > 0
+
+    def test_custom_systems(self):
+        config = RooftopConfig(
+            num_nodes=2,
+            hours=48,
+            seed=42,
+            systems_per_node=[1000, 2000],
+            avg_system_size_kw=[5.0, 4.0],
+        )
+        result = generate_profiles(config)
+        # Node 0: 1000 * 5.0 / 1000 = 5 MW
+        # Node 1: 2000 * 4.0 / 1000 = 8 MW
+        assert result.max_potential_mw[0] == pytest.approx(5.0)
+        assert result.max_potential_mw[1] == pytest.approx(8.0)