Electro-Map Backend

A FastAPI-based REST API for calculating electrical parameters of radial power networks.

Features

• ✅ Calculates line resistance
• ✅ Computes reactive power from active loads
• ✅ Determines power flows in the network
• ✅ Calculates power losses per edge
• ✅ Computes voltage profile across nodes
• ✅ Calculates sensitivity coefficients
• ✅ Optimizes IRG (reactive power compensation) placement
• ✅ Full input validation
• ✅ Reference data for wires, transformers, and consumer types

Requirements

• Python 3.12
• FastAPI 0.104.1
• Pydantic 2.5.0
• Uvicorn 0.24.0

Setup

1. Create virtual environment:

python -m venv .venv
.venv\Scripts\activate

2. Install dependencies:

pip install -r requirements.txt

3. Run tests:

pytest tests/ -v

Running the Server

uvicorn src.api.main:app --reload --host 0.0.0.0 --port 8000

The API will be available at: http://localhost:8000

Swagger Documentation

Access interactive API documentation at: http://localhost:8000/docs

API Endpoints

POST /calculate

Calculates electrical parameters for a radial network.

Request:

{
  "nodes": [0, 1, 2, 3, 4, 5],
  "edges": [
    {"from": 0, "to": 1, "length": 1.0, "wire": "SIP-2 4x25"},
    {"from": 1, "to": 2, "length": 0.8, "wire": "SIP-2 4x25"},
    {"from": 2, "to": 3, "length": 0.6, "wire": "A-16"}
  ],
  "loads": {
    "1": 20,
    "2": 30,
    "3": 40
  },
  "consumer_type": "residential",
  "transformer": "TMG-160/10"
}

Response:

{
  "optimal_node": 2,
  "irg_power_kvar": 40.0,
  "losses_before_kw": 7.234,
  "losses_after_kw": 5.123,
  "min_voltage_pu": 0.945,
  "min_voltage_node": 3,
  "voltages": [...],
  "flows": [...],
  "losses_per_edge": [...]
}

GET /reference

Returns reference data for all wires, consumer types, and transformers.

Response:

{
  "wires": {
    "SIP-2 4x25": 1.15,
    "A-16": 1.91,
    ...
  },
  "consumer_types": {
    "residential": {"cos_phi": 0.95, "tan_phi": 0.33},
    ...
  },
  "transformers": {
    "TMG-160/10": 10.0,
    ...
  }
}

GET /health

Health check endpoint.

Response:

{
  "status": "ok"
}

Input Validation

• Network must be a tree (no cycles, edges = nodes - 1)
• Root node 0 must exist in the network
• All edges must reference valid nodes
• Wire types must be known (SIP-2 4x25, A-16, A-25, A-35, etc.)
• Consumer type must be valid (residential, mixed, electric_stoves)
• Transformer must be known
• Loads must be non-negative numbers
• Edge lengths must be positive

Calculations

All calculations are implemented in src/api/calc.py as pure functions:

1. Line Resistance: R = resistance_per_km × length
2. Reactive Power: Q = P × tan(φ)
3. Power Flow: Traverses tree from leaves to root, summing downstream loads
4. Power Losses: I² × R formula with voltage conversion
5. Voltage Drop: ΔU = (P×R + Q×X) / U, X ≈ 0.3×R for distribution lines
6. Sensitivity Coefficient: Weighted reactive power for IRG placement recommendation
7. IRG Optimization: Brute force search trying each node with power range 0-100 kVAr

Project Structure

.
├── src/
│   ├── api/
│   │   ├── __init__.py
│   │   ├── main.py          # FastAPI app and endpoints
│   │   ├── models.py        # Pydantic v2 schemas
│   │   ├── calc.py          # All calculations (pure functions)
│   │   └── data.py          # Reference data
│   └── __init__.py
├── tests/
│   ├── test_api.py          # Pytest tests
│   └── __init__.py
├── examples/
│   ├── request.json         # Example API request
│   └── response.json        # Example API response
├── requirements.txt
└── README.md

Testing

Run tests with pytest:

pytest tests/ -v

Tests include:

• Network validation (tree structure, root node)
• Calculation correctness (resistance, power, voltages)
• API endpoint validation
• Error handling
• Complex network scenarios

Example Usage

See examples/request.json for a complete network definition and examples/response.json for the expected output.

Architecture

• main.py: FastAPI application with two endpoints
• models.py: Pydantic v2 schemas for validation
• calc.py: NetworkCalculator class with pure calculation methods
• data.py: Hardcoded reference data

No mixing of API route handlers and business logic. All calculations are pure functions suitable for testing and reuse.

Author

Built as a diploma project for electrical grid analysis.