Simulation Engine

The simulation engine (xylem-simulation-backend) is a Python FastAPI service that performs computational geometry and optimization tasks for building design. It generates tower configurations, floorplate layouts, and performs environmental analysis.

Architecture

┌──────────────────────────────────────────────────────┐
│              Simulation Engine                        │
│               (FastAPI :4902)                          │
│                                                      │
│  ┌────────────────────────────────────────────────┐  │
│  │                  API Layer                      │  │
│  │        src/api/main.py (FastAPI app)            │  │
│  └─────────────────┬──────────────────────────────┘  │
│                    │                                  │
│        ┌───────────┼───────────────┐                 │
│        ▼           ▼               ▼                 │
│  ┌──────────┐ ┌──────────┐ ┌─────────────┐          │
│  │  Tower   │ │Floorplate│ │  Analysis   │          │
│  │Optimizer │ │Generator │ │  (Solar,    │          │
│  │          │ │          │ │  Setbacks)  │          │
│  └──────────┘ └──────────┘ └─────────────┘          │
│        │           │               │                 │
│        ▼           ▼               ▼                 │
│  ┌──────────────────────────────────────────────┐    │
│  │           Core Libraries                      │    │
│  │  Shapely, GeoJSON, pyproj, pvlib, pandas     │    │
│  └──────────────────────────────────────────────┘    │
└──────────────────────────────────────────────────────┘

Modules

Tower Optimizer (src/tower_optimizer/)

Generates optimal tower placement configurations on a given site:

File	Purpose
main.py	Entry point and orchestration
solver.py	Core optimization solver
generator.py	Candidate solution generation
datatypes.py	Data structures for towers and sites
helpers.py	Geometry utility functions

Process:

1. Receives site polygon, setbacks, and constraints
2. Generates candidate tower footprint positions
3. Evaluates placement feasibility (setbacks, spacing)
4. Scores configurations by efficiency metrics
5. Returns ranked tower placement solutions

Floorplate Generator (src/floorplate_generator/)

Assembles apartment units into floorplate layouts:

Process:

1. Receives tower footprint dimensions and product mix
2. Fetches matching catalog units (by BHK type and dimensions)
3. Arranges units on the floorplate using geometric packing
4. Handles corner units, entrance directions, and corridor placement
5. Returns complete floor layouts with unit positions

Analysis (src/analysis/)

Environmental and regulatory analysis:

• Solar Analysis — Uses pvlib for precise solar position calculations, irradiance modeling, and shadow analysis
• Setback Calculator — Computes regulatory setback distances based on building height, road width, and zoning rules
• Coordinate transformations — Uses pyproj for converting between geographic and projected coordinate systems

Configuration

src/config.py

# Contains simulation parameters:
# - Default setback values
# - Tower spacing constraints
# - Floor height assumptions
# - Solar analysis parameters
# - Optimization bounds

API Endpoints

The FastAPI app exposes endpoints for:

Endpoint	Method	Description
/optimize	POST	Run tower optimization
/generate-floorplate	POST	Generate floorplate layout
/analyze/solar	POST	Solar analysis for a solution
/health	GET	Health check

Dependencies

Package	Purpose
fastapi	API framework
uvicorn	ASGI server
shapely	2D computational geometry
geojson	GeoJSON handling
pydantic	Data validation
pvlib	Solar irradiance modeling
pandas	Data manipulation
matplotlib	Chart generation
pyproj	Coordinate system transformations

Running

# Install dependencies
uv sync

# Start server
uv run uvicorn src.api.main:app --host 0.0.0.0 --port 4902 --timeout-keep-alive 300

# Or via PM2 (production)
pm2 restart xylem-simulation-backend