Metadata-Version: 2.4
Name: citymind-engine
Version: 1.0.0
Summary: CITYMIND: Urban Human Systems Intelligence Framework — Independent Subsystem Modeling with AI-Enhanced Aggregation
Author: Samir Baladi
Author-email: Samir Baladi <gitdeeper@gmail.com>
License: MIT
Project-URL: Homepage, https://citymind-v1.netlify.app
Project-URL: Documentation, https://citymind-v1.netlify.app/documentation
Project-URL: Repository, https://github.com/gitdeeper13/CITYMIND
Project-URL: Issues, https://github.com/gitdeeper13/CITYMIND/issues
Project-URL: DOI, https://doi.org/10.5281/zenodo.20444647
Keywords: urban-systems,human-intelligence,transport-flow,population-density,energy-consumption,mobility-behavior,infrastructure-load,urban-health-index,ai-enhancement
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Science/Research
Classifier: Intended Audience :: Urban Planning
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Topic :: Scientific/Engineering
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy>=1.21.0
Requires-Dist: scipy>=1.7.0
Requires-Dist: pandas>=1.3.0
Requires-Dist: matplotlib>=3.4.0
Requires-Dist: scikit-learn>=1.0.0
Requires-Dist: xgboost>=1.5.0
Requires-Dist: streamlit>=1.12.0
Requires-Dist: plotly>=5.5.0
Requires-Dist: pyyaml>=5.4.0
Dynamic: author
Dynamic: license-file
Dynamic: requires-python

<div align="center">

# CITYMIND

### Urban Human Systems Intelligence: Independent Subsystem Modeling and AI-Assisted UHI Aggregation

**Transport Flow · Population Density · Energy Consumption · Mobility Behavior · Infrastructure Load · AI-Enhanced Governance**

---

[![PyPI version](https://img.shields.io/pypi/v/citymind-engine?color=1B4F72&label=PyPI&logo=pypi&logoColor=white)](https://pypi.org/project/citymind-engine)
[![PyPI downloads](https://img.shields.io/pypi/dm/citymind-engine?color=154360&label=Downloads&logo=pypi&logoColor=white)](https://pypi.org/project/citymind-engine/#files)
[![Python versions](https://img.shields.io/pypi/pyversions/citymind-engine?color=306998&logo=python&logoColor=white)](https://pypi.org/project/citymind-engine)
[![DOI](https://img.shields.io/badge/DOI-10.5281%2Fzenodo.20444647-blue.svg)](https://doi.org/10.5281/zenodo.20444647)
[![OSF Preregistration](https://img.shields.io/badge/OSF-Preregistered-blue?logo=osf&logoColor=white)](https://doi.org/10.17605/OSF.IO/AN2HV)
[![ORCID](https://img.shields.io/badge/ORCID-0009--0003--8903--0029-A6CE39?logo=orcid&logoColor=white)](https://orcid.org/0009-0003-8903-0029)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Domain](https://img.shields.io/badge/Domain-Urban%20Human%20Systems%20Intelligence-1B4F72)](https://doi.org/10.5281/zenodo.20444647)
[![Series](https://img.shields.io/badge/Series-CITY--INTEL--01-1A5276)](https://doi.org/10.5281/zenodo.20444647)
[![Version](https://img.shields.io/badge/Version-1.0.0-orange)](https://github.com/gitdeeper13/CITYMIND)

</div>

---

## 📌 Overview

**CITYMIND** is an Urban Human Systems Intelligence framework for the continuous modeling, analysis, and safety governance of five analytically independent urban subsystems — Transport Flow, Population Density, Energy Consumption, Mobility Behavior, and Infrastructure Load — aggregated into a single composite Urban Health Index (UHI) via an AI-assisted dynamic weighting mechanism, with AI serving strictly as a bounded optimization layer at the aggregation interface, not as a replacement for domain-specific subsystem knowledge.

> *"A city is not a single unified system — it is a collection of independent subsystems whose interaction must be governed through aggregation, not structural merging. CITYMIND treats each urban subsystem as analytically separate, governed by its own domain-specific equations and calibrated independently against subsystem-specific data. AI methods are applied only in the bounded role of enhancing aggregation accuracy — not replacing domain knowledge."*

Conventional annual survey-based urban composite indices cannot provide real-time subsystem-level diagnostics, detect early warning signals of subsystem stress events with 24–48 hour lead times, or calibrate composite index weights dynamically to the current city-specific context. CITYMIND provides a continuous, quantitative, five-subsystem analytical framework that classifies urban system condition in real time as:

| Signal | Urban System Status | Action |
|---|---|---|
| 🟢 **OPTIMIZED URBAN FLOW** | `UHI ≥ 0.85` | All subsystem scores within operational bounds — standard monitoring, no intervention |
| 🟠 **STRESSED SUBSYSTEM WARNING** | `0.70 ≤ UHI < 0.85` | One or more subsystems below threshold — activate anomaly detection and targeted response |
| 🟠 **SYSTEMIC MITIGATION PHASE** | `0.55 ≤ UHI < 0.70` | Multiple subsystem degradation — apply cross-subsystem balancing measures |
| 🔴 **CRITICAL INFRASTRUCTURE BREACH** | `UHI < 0.55` | Critical threshold breached — emergency operational intervention, cross-agency coordination |

---

## 🗂️ Table of Contents

- [Overview](#-overview)
- [Key Features](#-key-features)
- [Five Independent Urban Subsystems](#-five-independent-urban-subsystems)
- [Project Structure](#-project-structure)
- [Quick Start](#-quick-start)
- [CITYMIND Pipeline](#-citymind-pipeline)
- [Governing Equations](#-governing-equations)
- [Scoring & Safety Bounds](#-scoring--safety-bounds)
- [Platforms & Mirrors](#-platforms--mirrors)
- [Clone & Download](#-clone--download)
- [Citation](#-citation)
- [License](#-license)
- [Author](#-author)

---

## ✨ Key Features

- **Five analytically independent urban subsystems** — Transport Flow (TFS), Population Density (PDS), Energy Consumption (ECS), Mobility Behavior (MBS), Infrastructure Load (ILS), each with its own domain-specific governing equations
- **Urban Health Index (UHI)** — AI-assisted dynamic weighted composite with four-level governance decision logic, 15-minute update interval
- **AI-assisted dynamic weight calibration** — gradient boosting weight predictor calibrated on historical monitoring data, subject to Σwᵢ = 1 constraint, producing context-sensitive UHI vs fixed equal-weight baseline
- **Mahalanobis distance anomaly detector** — 91.6% sensitivity for early warning of subsystem stress events at 24–48 hour lead times
- **Transport Flow: BPR congestion function** — V/C ratio with dynamic travel time T(v) = T₀·[1 + α·(V/C)^β]
- **Energy Consumption: supply-demand balance model** — smart meter calibration + peak demand forecasting
- **Mobility Behavior: discrete choice multinomial logit** — utility-based mode share with Bayesian real-time updating
- **Infrastructure Load: weighted geometric mean** — consequence-weighted composite of k infrastructure systems
- **Three-city validation** — European compact city, Middle Eastern growing city, North American suburban area
- **±4.2% UHI accuracy** — validated against independent urban condition assessments across three contrasting city profiles
- **Full open-source distribution** — available across 11 platforms

---

## 🏗️ Five Independent Urban Subsystems

| # | Subsystem | Output Score | Core Governing Equation |
|---|-----------|-------------|------------------------|
| 1 | **Transport Flow (TFS)** | `T_score` | T_score = [1 − (V_demand / C_capacity)] + ε_T(t) |
| 2 | **Population Density (PDS)** | `P_score` | P_score = 1 − \|(Pop/Area) − Density_opt\| / Density_max |
| 3 | **Energy Consumption (ECS)** | `E_score` | E_score = (Supply_grid − Demand_urban) / Supply_grid |
| 4 | **Mobility Behavior (MBS)** | `M_score` | M_score = (Trips_public + Trips_active) / Total_trips |
| 5 | **Infrastructure Load (ILS)** | `I_score` | I_score = 1 − (Load_infrastructure / Load_critical_limit) |

**Urban Health Index:**
> **UHI(t) = w_T·T_score + w_P·P_score + w_E·E_score + w_M·M_score + w_I·I_score**
>
> *Constraint: Σwᵢ = 1.0 · Weights calibrated by gradient boosting weight predictor · 15-minute update cycle*

---

## 📁 Project Structure

```
CITYMIND/
│
├── citymind/                               # Core Python package
│   ├── __init__.py                         # Package entry point & public API
│   ├── pipeline.py                         # Main CITYMIND assessment pipeline
│   ├── uhi.py                              # UHI composite index & governance logic
│   │
│   ├── subsystems/                         # Five independent urban subsystems
│   │   ├── __init__.py
│   │   ├── tfs.py                          # Subsystem 1: Transport Flow Subsystem
│   │   ├── pds.py                          # Subsystem 2: Population Density Subsystem
│   │   ├── ecs.py                          # Subsystem 3: Energy Consumption Subsystem
│   │   ├── mbs.py                          # Subsystem 4: Mobility Behavior Subsystem
│   │   └── ils.py                          # Subsystem 5: Infrastructure Load Subsystem
│   │
│   ├── transport/                          # Transport Flow subsystem internals
│   │   ├── __init__.py
│   │   ├── bpr_function.py                 # BPR: T(v) = T₀·[1 + α·(V/C)^β]
│   │   ├── volume_capacity.py              # V/C ratio and congestion index
│   │   ├── travel_time.py                  # Network-level travel time computation
│   │   ├── loop_detector.py                # Loop detector data ingestion and QC
│   │   ├── floating_car.py                 # GPS floating car data processing
│   │   └── t_score.py                      # T_score computation and validation
│   │
│   ├── population/                         # Population Density subsystem internals
│   │   ├── __init__.py
│   │   ├── density_model.py                # Density deviation from optimum target
│   │   ├── optimal_density.py              # City-specific Density_opt calibration
│   │   ├── census_integration.py           # Census data ingestion and interpolation
│   │   ├── mobile_sensing.py               # Passive mobile phone data density proxy
│   │   └── p_score.py                      # P_score computation and validation
│   │
│   ├── energy/                             # Energy Consumption subsystem internals
│   │   ├── __init__.py
│   │   ├── supply_demand.py                # Supply-demand balance E_score
│   │   ├── smart_meter.py                  # Smart meter aggregation and calibration
│   │   ├── peak_forecast.py                # Short-term peak demand forecasting
│   │   ├── renewable_integration.py        # Solar/wind supply variability model
│   │   └── e_score.py                      # E_score computation and validation
│   │
│   ├── mobility/                           # Mobility Behavior subsystem internals
│   │   ├── __init__.py
│   │   ├── mnl_model.py                    # Multinomial logit discrete choice model
│   │   ├── utility_function.py             # Mode utility function U_m calibration
│   │   ├── smart_card.py                   # Transit smart card boarding data
│   │   ├── wifi_bluetooth.py               # Passive WiFi/Bluetooth pedestrian counts
│   │   ├── gps_trajectory.py               # GPS trajectory mode inference
│   │   ├── bayesian_fusion.py              # Bayesian real-time mode share updating
│   │   └── m_score.py                      # M_score computation and validation
│   │
│   ├── infrastructure/                     # Infrastructure Load subsystem internals
│   │   ├── __init__.py
│   │   ├── geometric_mean.py               # Weighted geometric mean I_score
│   │   ├── consequence_weights.py          # MCA consequence weight α_k assignment
│   │   ├── load_tracking.py                # Per-infrastructure-system load tracking
│   │   ├── capacity_model.py               # Critical limit Load_critical_limit model
│   │   └── i_score.py                      # I_score computation and validation
│   │
│   ├── aggregation/                        # AI-assisted UHI aggregation layer
│   │   ├── __init__.py
│   │   ├── weight_calibration.py           # Gradient boosting weight predictor
│   │   ├── dynamic_weights.py              # Context-sensitive weight vector (w_T…w_I)
│   │   ├── equal_weight_baseline.py        # Equal-weight UHI baseline (Σwᵢ=0.2)
│   │   ├── weight_constraint.py            # Σwᵢ = 1.0 simplex constraint enforcement
│   │   └── uhi_computation.py              # Final UHI composite computation
│   │
│   ├── anomaly/                            # Anomaly detection layer
│   │   ├── __init__.py
│   │   ├── mahalanobis.py                  # Mahalanobis distance anomaly detector
│   │   ├── threshold_monitor.py            # Per-subsystem Level 1 threshold monitor
│   │   ├── early_warning.py                # 24–48h early warning signal generator
│   │   └── stress_event_log.py             # Subsystem stress event archival
│   │
│   ├── sensors/                            # Urban data ingestion and fusion
│   │   ├── __init__.py
│   │   ├── loop_detector_reader.py         # Traffic loop detector ingestion
│   │   ├── smart_meter_reader.py           # Energy smart meter aggregation
│   │   ├── transit_api.py                  # Smart card transit API connector
│   │   ├── weather_api.py                  # Meteorological data for demand correction
│   │   ├── census_reader.py                # Population census and intercensal data
│   │   └── fusion.py                       # Multi-source data fusion and QC
│   │
│   ├── forecasting/                        # Short-term subsystem forecasting
│   │   ├── __init__.py
│   │   ├── uhi_forecast.py                 # 24–48h UHI trajectory projection
│   │   ├── congestion_forecast.py          # Short-term V/C ratio forecast
│   │   ├── energy_forecast.py              # Peak demand 6h-ahead forecast
│   │   └── uncertainty.py                  # Forecast uncertainty quantification
│   │
│   └── utils/                              # Shared utilities
│       ├── __init__.py
│       ├── metrics.py                      # UHI, T_score, E_score, β computation
│       ├── validators.py                   # Input validation and governance bounds
│       └── constants.py                    # BPR α/β, UHI thresholds, default weights
│
├── monitoring/                             # Real-time monitoring dashboard
│   ├── __init__.py
│   ├── app.py                              # Streamlit application entry point
│   ├── dashboard.py                        # UHI governance dashboard layout
│   ├── subsystem_panel.py                  # Five-subsystem score display
│   ├── weight_tracker.py                   # Dynamic weight vector trend display
│   ├── anomaly_map.py                      # Spatial subsystem anomaly map
│   └── components/
│       ├── uhi_gauge.py                    # UHI composite index gauge display
│       ├── signal_panel.py                 # 🔴🟠🟢 governance signal status
│       └── forecast_panel.py               # 24–48h UHI trajectory projection
│
├── archival/                               # Operational data archival
│   ├── __init__.py
│   ├── writer.py                           # Append-only JSON/CSV record writer
│   ├── checksum.py                         # SHA-256 tamper-evidence layer
│   └── partitioner.py                      # Per-subsystem time-window CSV partitioner
│
├── simulation/                             # Validation and benchmark environment
│   ├── __init__.py
│   ├── city_configs.py                     # City profile and parameter definitions
│   ├── loading_scenarios.py                # Diurnal, seasonal, and event scenarios
│   ├── benchmarks.py                       # Three-city validation suite
│   ├── parameters.py                       # Canonical v1.0.0 parameter registry
│   └── results/                            # Pre-computed validation outputs
│       ├── CityA_European_compact.json
│       ├── CityB_ME_growing_city.json
│       └── CityC_NA_suburban.json
│
├── examples/                               # Usage examples and tutorials
│   ├── quickstart.py                       # Minimal working example
│   ├── basic_uhi.ipynb                     # Jupyter: single-city UHI assessment
│   ├── dynamic_weights.ipynb               # Jupyter: AI weight calibration walkthrough
│   ├── transport_flow.ipynb                # Jupyter: BPR congestion function demo
│   ├── anomaly_detection.ipynb             # Jupyter: Mahalanobis distance anomaly demo
│   ├── streamlit_dashboard.py              # Launch real-time monitoring dashboard
│   └── policy_simulation.py               # UHI policy intervention simulation demo
│
├── tests/                                  # Unit and integration tests
│   ├── test_tfs.py
│   ├── test_pds.py
│   ├── test_ecs.py
│   ├── test_mbs.py
│   ├── test_ils.py
│   ├── test_uhi.py
│   ├── test_aggregation.py
│   ├── test_anomaly.py
│   └── test_pipeline.py
│
├── docs/                                   # Documentation source
│   ├── architecture.md                     # Subsystem architecture reference
│   ├── mathematics.md                      # Governing equations documentation
│   ├── monitoring.md                       # Sensor system and data fusion guide
│   ├── governance.md                       # UHI threshold calibration reference
│   └── api_reference.md                    # Full Python API reference
│
├── paper/                                  # Research paper artifacts
│   ├── CITYMIND_Research_Paper.pdf         # Published paper (PDF)
│   ├── CITYMIND_Research_Paper.docx        # Editable Word version
│   └── figures/
│       ├── uhi_formulation.svg
│       ├── weight_calibration_diagram.svg
│       ├── five_subsystems_overview.svg
│       └── validation_three_cities.svg
│
├── .gitlab-ci.yml                          # GitLab CI/CD pipeline
├── .github/
│   └── workflows/
│       ├── tests.yml
│       └── publish.yml
├── pyproject.toml
├── setup.cfg
├── requirements.txt
├── requirements-dev.txt
├── CHANGELOG.md
├── CONTRIBUTING.md
├── CODE_OF_CONDUCT.md
├── AUTHORS.md
├── LICENSE
└── README.md                               # This file
```

---

## 🚀 Quick Start

### Installation

```bash
# Install from PyPI
pip install citymind-engine

# Install from source
git clone https://github.com/gitdeeper13/CITYMIND.git
cd CITYMIND
pip install -e .
```

### Minimal Example

```python
from citymind import CityMindAssessor

# Initialize assessor with city configuration
assessor = CityMindAssessor(
    city_config="configs/city_a_european.yaml",
    sensor_stream="live"   # or path to historical CSV
)

# Run full CITYMIND assessment pipeline
result = assessor.evaluate()

print(result.uhi)            # Urban Health Index ∈ [0, 1]
print(result.signal)         # "OPTIMIZED" | "STRESSED" | "MITIGATION" | "CRITICAL"
print(result.t_score)        # Transport Flow score
print(result.p_score)        # Population Density score
print(result.e_score)        # Energy Consumption score
print(result.m_score)        # Mobility Behavior score
print(result.i_score)        # Infrastructure Load score
print(result.weights)        # Current dynamic weight vector (w_T, w_P, w_E, w_M, w_I)
```

### With Full Five-Subsystem Configuration

```python
from citymind import CityMindAssessor
from citymind.subsystems import TFS, PDS, ECS, MBS, ILS

assessor = CityMindAssessor(
    city_config="configs/city_a_european.yaml",
    subsystems={
        "tfs": TFS(alpha=0.15, beta=4.0, vc_warn=0.85),
        "pds": PDS(density_opt=8500, density_max=25000),
        "ecs": ECS(supply_source="smart_meter", peak_correction=True),
        "mbs": MBS(mnl_params="calibrated", bayesian_update=True),
        "ils": ILS(consequence_weights="mca_derived"),
    }
)

result = assessor.evaluate()
print(result.breakdown)
# {"t_score": 0.82, "p_score": 0.91, "e_score": 0.78, "m_score": 0.87, "i_score": 0.84}
```

### Dynamic Weight Calibration

```python
from citymind.aggregation import WeightCalibrator

# Train gradient boosting weight predictor on historical data
calibrator = WeightCalibrator(method="gradient_boosting")
calibrator.fit(
    historical_scores="data/city_a_24months.csv",  # min. 24 months required
    validation_split=0.20
)

# Get context-sensitive weight vector for current urban state
w = calibrator.predict(current_scores=[0.82, 0.91, 0.78, 0.87, 0.84])
print(f"Weights: T={w[0]:.3f} P={w[1]:.3f} E={w[2]:.3f} M={w[3]:.3f} I={w[4]:.3f}")
print(f"Sum check: {sum(w):.6f}")  # Must equal 1.0

# Compute dynamic UHI vs equal-weight baseline
uhi_dynamic = calibrator.compute_uhi(current_scores=[0.82, 0.91, 0.78, 0.87, 0.84])
uhi_equal   = sum([0.82, 0.91, 0.78, 0.87, 0.84]) / 5
print(f"Dynamic UHI: {uhi_dynamic:.4f}  |  Equal-weight: {uhi_equal:.4f}")
```

### Anomaly Detection

```python
from citymind.anomaly import MahalanobisDetector

detector = MahalanobisDetector(threshold=3.0)  # 3σ Mahalanobis distance
detector.fit(historical_scores="data/city_a_24months.csv")

# Evaluate current subsystem score vector
score_vector = [0.82, 0.91, 0.78, 0.87, 0.84]
result = detector.evaluate(score_vector)

print(f"Anomaly score: {result.d_mahalanobis:.3f}")
print(f"Anomaly flag:  {result.anomaly}")        # True if d > 3.0
print(f"Stressed subsystems: {result.flagged}")  # e.g. ["ECS", "TFS"]
print(f"Lead time estimate: {result.lead_hours}h")
```

### Launch Real-Time Monitoring Dashboard

```bash
# Start Streamlit UHI governance dashboard
streamlit run examples/streamlit_dashboard.py

# Dashboard at: http://localhost:8501
# Panels:
#   · UHI composite gauge with 4-level signal
#   · Five-subsystem score display
#   · Dynamic weight vector trend
#   · Mahalanobis anomaly map
#   · 24–48h UHI trajectory forecast
```

---

## 🧩 CITYMIND Pipeline

```
┌────────────────────────────────────────────────────────────────────────────┐
│  Urban Data: Loop Detectors · Smart Meters · Transit Smart Cards · Census  │
│              GPS Trajectories · WiFi/Bluetooth · Weather APIs              │
└──────────────────────────┬─────────────────────────────────────────────────┘
                           │
     ┌─────────────────────┼──────────────────────────┐
     │         │           │           │              │
     ▼         ▼           ▼           ▼              ▼
   TFS        PDS         ECS         MBS            ILS
   BPR        Density     Supply-     MNL+           Weighted
   V/C ratio  Deviation   Demand      Bayesian       Geometric
   T_score    P_score     E_score     M_score        I_score
     │         │           │           │              │
     └─────────┴───────────┴───────────┴──────────────┘
                           │
             AI-Assisted Aggregation Layer
             Gradient Boosting Weight Calibrator
             Context-Sensitive w_T, w_P, w_E, w_M, w_I
             Constraint: Σwᵢ = 1.0
             Mahalanobis Anomaly Detection (3σ threshold)
             24–48h Early Warning Lead Time
                           │
                           ▼
               Urban Health Index (UHI)
               UHI = Σ wᵢ · Score_i
               15-minute update interval
                           │
                  ┌────────┴────────┐
                  ▼                 ▼
           Safety Signal       Archival
           🟢🟠🔴             JSON/CSV + SHA-256
           4-level UHI        Streamlit dashboard
```

### Subsystem Summary

| # | Subsystem | Score Output | Core Method | Data Source |
|---|-----------|-------------|-------------|------------|
| 1 | **TFS** | `T_score` | BPR congestion function + V/C ratio | Loop detectors, GPS floating car |
| 2 | **PDS** | `P_score` | Density deviation from city-specific optimal | Census, mobile passive sensing |
| 3 | **ECS** | `E_score` | Supply-demand balance + peak demand forecast | Smart meters, grid operator API |
| 4 | **MBS** | `M_score` | Multinomial logit + Bayesian mode share update | Smart card, WiFi/BT, GPS trajectory |
| 5 | **ILS** | `I_score` | Weighted geometric mean consequence index | SCADA, infrastructure monitoring |
| — | **AI Layer** | `w_T…w_I` | Gradient boosting weight calibration | 24-month historical score vectors |
| — | **UHI** | `UHI(t) ∈ [0,1]` | Dynamic weighted composite Σwᵢ·Score_i | All five subsystems |

---

## ⚙️ Governing Equations

```
Eq. 1 — Transport Flow (BPR congestion function):
  T(v) = T₀ · [1 + α · (V/C)^β]
  T_score = 1 − (V_demand / C_capacity) + ε_T(t)

Eq. 2 — Population Density (deviation from optimum):
  P_score = 1 − |(Pop/Area) − Density_opt| / Density_max

Eq. 3 — Energy Consumption (supply-demand balance):
  E_score = (Supply_grid − Demand_urban) / Supply_grid

Eq. 4 — Mobility Behavior (multinomial logit mode share):
  P(mode = m | X) = exp(V_m) / Σⱼ exp(V_j)
  M_score = (Trips_public + Trips_active) / Total_trips

Eq. 5 — Infrastructure Load (weighted geometric mean):
  I_score = 1 − (Load_infrastructure / Load_critical_limit)

Eq. 6 — AI-Assisted Dynamic Weight Calibration:
  w(t) = GradBoost[Score_vector(t), historical_data]
  subject to: Σwᵢ = 1.0,  wᵢ ≥ 0

Eq. 7 — Urban Health Index:
  UHI(t) = w_T·T_score + w_P·P_score + w_E·E_score
            + w_M·M_score + w_I·I_score
```

---

## 📊 Scoring & Safety Bounds

```
UHI governance certification thresholds:
  UHI ≥ 0.85   →   🟢 Optimized Urban Flow
  0.70 ≤ UHI < 0.85   →   🟠 Stressed Subsystem Warning (Level 1)
  0.55 ≤ UHI < 0.70   →   🟠 Systemic Mitigation Phase (Level 2)
  UHI < 0.55   →   🔴 Critical Infrastructure Breach

Subsystem-level governance bounds:
  T_score   ≥  0.70   (V/C ratio below congestion threshold)
  P_score   ≥  0.65   (density within ±35% of city-specific optimum)
  E_score   ≥  0.60   (positive supply margin > 0)
  M_score   ≥  0.35   (≥ 35% sustainable modal share)
  I_score   ≥  0.70   (load < 30% of critical limit)
```

**Validation results (CITYMIND v1.0.0):**

| City | Profile | UHI Accuracy | TFS Accuracy | ECS Accuracy | Anomaly Detection |
|---|---|---|---|---|---|
| City A | European compact · high PT (47%) | ±3.8% | ±3.1% | ±2.9% | 93.2% |
| City B | Middle Eastern growing · car-dependent (68%) | ±4.2% | ±4.4% | ±3.8% | 90.7% |
| City C | North American suburban · low density | ±4.6% | ±3.7% | ±4.1% | 91.0% |
| **Mean** | — | **±4.2%** | **±3.73%** | **±3.6%** | **91.6%** |

---

## 🌐 Platforms & Mirrors

| Platform | URL | Role |
|---|---|---|
| 🐙 **GitHub** (Primary) | [github.com/gitdeeper13/CITYMIND](https://github.com/gitdeeper13/CITYMIND) | Source code, issues, PRs |
| 🦊 **GitLab** (Mirror) | [gitlab.com/gitdeeper13/CITYMIND](https://gitlab.com/gitdeeper13/CITYMIND) | CI/CD mirror |
| 🪣 **Bitbucket** (Mirror) | [bitbucket.org/gitdeeper-13/CITYMIND](https://bitbucket.org/gitdeeper-13/CITYMIND) | Enterprise mirror |
| 🏔️ **Codeberg** (Mirror) | [codeberg.org/gitdeeper13/CITYMIND](https://codeberg.org/gitdeeper13/CITYMIND) | Open-source community |
| 📦 **PyPI** | [pypi.org/project/citymind-engine](https://pypi.org/project/citymind-engine) | Python package distribution |
| 🔬 **Zenodo** | [doi.org/10.5281/zenodo.20444647](https://doi.org/10.5281/zenodo.20444647) | Citable DOI, paper & data |
| 📋 **OSF Project** | [osf.io/citymind](https://osf.io/r7ebg) | Research project registry |
| 📝 **OSF Preregistration** | [doi.org/10.17605/OSF.IO/AN2HV](https://doi.org/10.17605/OSF.IO/AN2HV) | Pre-registered study protocol |
| 🌐 **Website** | [citymind-v1.netlify.app](https://citymind-v1.netlify.app) | Live documentation & dashboard |
| 🧑‍🔬 **ORCID** | [orcid.org/0009-0003-8903-0029](https://orcid.org/0009-0003-8903-0029) | Researcher identity |
| 🗄️ **Internet Archive** | [archive.org/details/osf-registrations-citymind](https://archive.org/details/osf-registrations-citymind) | Permanent archival copy |

### 🌐 Official Website Pages

| Page | URL |
|---|---|
| Homepage | [citymind-v1.netlify.app](https://citymind-v1.netlify.app) |
| Dashboard | [citymind-v1.netlify.app/dashboard](https://citymind-v1.netlify.app/dashboard) |
| Results | [citymind-v1.netlify.app/results](https://citymind-v1.netlify.app/results) |
| Documentation | [citymind-v1.netlify.app/documentation](https://citymind-v1.netlify.app/documentation) |

---

## 🔄 Clone & Download

### Git Clone

```bash
# GitHub (Primary)
git clone https://github.com/gitdeeper13/CITYMIND.git

# GitLab (Mirror)
git clone https://gitlab.com/gitdeeper13/CITYMIND.git

# Bitbucket (Mirror)
git clone https://bitbucket.org/gitdeeper-13/CITYMIND.git

# Codeberg (Mirror)
git clone https://codeberg.org/gitdeeper13/CITYMIND.git
```

### Direct ZIP Download

| Source | Link |
|---|---|
| GitHub | [CITYMIND-main.zip](https://github.com/gitdeeper13/CITYMIND/archive/refs/heads/main.zip) |
| GitLab | [CITYMIND-main.zip](https://gitlab.com/gitdeeper13/CITYMIND/-/archive/main/CITYMIND-main.zip) |
| Bitbucket | [CITYMIND-main.zip](https://bitbucket.org/gitdeeper-13/CITYMIND/get/main.zip) |
| Codeberg | [CITYMIND-main.zip](https://codeberg.org/gitdeeper13/CITYMIND/archive/main.zip) |
| PyPI files | [pypi.org/project/citymind-engine/#files](https://pypi.org/project/citymind-engine/#files) |
| Zenodo record | [doi.org/10.5281/zenodo.20444647](https://doi.org/10.5281/zenodo.20444647) |

---

## 📖 Citation

If CITYMIND contributes to your research, please cite using one of the following formats.

### 📦 PyPI Package

```bibtex
@software{baladi2026citymind_pypi,
  author       = {Baladi, Samir},
  title        = {{CITYMIND}: Urban Human Systems Intelligence:
                  Independent Subsystem Modeling and
                  AI-Assisted UHI Aggregation},
  year         = {2026},
  version      = {1.0.0},
  publisher    = {Python Package Index},
  url          = {https://pypi.org/project/citymind-engine},
  note         = {Python package, MIT License, Series CITY-INTEL-01}
}
```

### 🔬 Zenodo Archive (Paper & Data)

```bibtex
@dataset{baladi2026citymind_zenodo,
  author       = {Baladi, Samir},
  title        = {{CITYMIND}: Urban Human Systems Intelligence:
                  Independent Subsystem Modeling and AI-Assisted
                  UHI Aggregation — Research Paper and Simulation Data},
  year         = {2026},
  publisher    = {Zenodo},
  version      = {1.0.0},
  doi          = {10.5281/zenodo.20444647},
  url          = {https://doi.org/10.5281/zenodo.20444647},
  note         = {Urban Human Systems Intelligence · CITY-INTEL-01}
}
```

### 📝 OSF Preregistration

```bibtex
@misc{baladi2026citymind_osf,
  author       = {Baladi, Samir},
  title        = {{CITYMIND} Framework: Pre-registered Study Protocol for
                  Urban Human Systems Intelligence — Independent Subsystem
                  Modeling and AI-Assisted UHI Aggregation},
  year         = {2026},
  publisher    = {Open Science Framework},
  doi          = {10.17605/OSF.IO/AN2HV},
  url          = {https://doi.org/10.17605/OSF.IO/AN2HV},
  note         = {OSF Preregistration}
}
```

### 📄 Research Paper

```bibtex
@article{baladi2026citymind,
  author       = {Baladi, Samir},
  title        = {{CITYMIND}: Urban Human Systems Intelligence:
                  Independent Subsystem Modeling and
                  AI-Assisted UHI Aggregation},
  year         = {2026},
  month        = {May},
  version      = {1.0.0},
  doi          = {10.5281/zenodo.20444647},
  url          = {https://doi.org/10.5281/zenodo.20444647},
  note         = {Ronin Institute / Rite of Renaissance,
                  Series CITY-INTEL-01}
}
```

### APA (inline)

> Baladi, S. (2026). *CITYMIND: Urban Human Systems Intelligence — Independent Subsystem Modeling and AI-Assisted UHI Aggregation* (Version 1.0.0, Series CITY-INTEL-01). Zenodo. https://doi.org/10.5281/zenodo.20444647

---

## 📜 License

This project is licensed under the **MIT License** — see the [LICENSE](LICENSE) file for details.

```
MIT License

Copyright (c) 2026 Samir Baladi

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

---

## 👤 Author

**Samir Baladi**
Interdisciplinary Researcher — Urban Systems Intelligence, Structural Reliability Engineering & Computational Safety Analysis
Ronin Institute / Rite of Renaissance

| Contact | Link |
|---|---|
| 📧 Email | [gitdeeper@gmail.com](mailto:gitdeeper@gmail.com) |
| 🧑‍🔬 ORCID | [0009-0003-8903-0029](https://orcid.org/0009-0003-8903-0029) |
| 🐙 GitHub | [github.com/gitdeeper13](https://github.com/gitdeeper13) |
| 🔬 Zenodo | [doi.org/10.5281/zenodo.20444647](https://doi.org/10.5281/zenodo.20444647) |

---

<div align="center">

**CITY-INTEL-01 · Version 1.0.0 · May 2026**

[![DOI](https://img.shields.io/badge/DOI-10.5281%2Fzenodo.20444647-blue.svg)](https://doi.org/10.5281/zenodo.20444647)
[![PyPI](https://img.shields.io/pypi/v/citymind-engine?color=1B4F72)](https://pypi.org/project/citymind-engine)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Domain](https://img.shields.io/badge/Domain-Urban%20Human%20Systems%20Intelligence-1B4F72)](https://doi.org/10.5281/zenodo.20444647)

*"A city is not a single unified system — it is a collection of independent subsystems whose interaction must be governed through aggregation, not structural merging. CITYMIND maintains five analytically independent urban subsystems, applying AI only in the bounded role of enhancing aggregation accuracy."*

</div>
