# Energy Sector

**Purpose:** The `EnergySector` serves as the central power authority for the entire simulation. Its sole responsibility is to manage the generation, storage, and distribution of electrical power to meet the aggregate demand from all other sectors. It abstracts the complexity of the power grid through a single `MicrogridManager`.

**Core Components:**
*   **`MicrogridManager`:** This is the brain of the energy sector. It manages a portfolio of power generators (e.g., Solar, Nuclear) and energy storage units (e.g., Li-ion Batteries) to create a resilient power grid.
*   **`PowerGenerator`:** Represents a single power generation unit. Each generator has a maximum power capacity, an efficiency rating, and an availability factor (e.g., a solar panel's availability might be affected by the lunar day/night cycle).
*   **`PowerStorage`:** Represents a battery or other storage unit. It has a maximum capacity, a current charge level, and separate efficiencies for charging and discharging, simulating real-world energy losses.

## Operational Cycle & Equations

The `EnergySector`'s `step` method is a sophisticated orchestration of power flow. The key calculations are defined below.

**Variables:**
*   $P_{\text{demand}}$: The total power demand from all sectors for the current step.
*   $C_{\text{max}, i}$: The maximum capacity of battery \(i\).
*   $C_{\text{current}, i}$: The current charge of battery \(i\).
*   $\eta_{\text{charge}, i}$: The charging efficiency of battery \(i\).
*   $\eta_{\text{discharge}, i}$: The discharging efficiency of battery \(i\).
*   $P_{\text{gen}}$: The total power generated by all generators in the step.
*   $P_{\text{supply}}$: The final power supplied to the grid.

**1. Calculate Total Power Need**

The microgrid proactively calculates the `max_useful_power` it could possibly need. This is the sum of the current `power_demand` plus the total energy required to fully charge all batteries.

```math
P_{\text{needed\_to\_charge}} = \sum_{i \in \text{batteries}} \frac{C_{\text{max}, i} - C_{\text{current}, i}}{\eta_{\text{charge}, i}}

```
```math
P_{\text{useful}} = P_{\text{demand}} + P_{\text{needed\_to\_charge}}
```

**2. Generate Power**

All available generators produce power, up to the calculated \(P_{\text{useful}}\).

**3. Meet Demand & Calculate Shortfall**

Freshly generated power is used first. If that is not enough, batteries are discharged.

```math
P_{\text{from\_gen}} = \min(P_{\text{demand}}, P_{\text{gen}})
```
```math
\text{Demand}_{\text{remaining}} = P_{\text{demand}} - P_{\text{from\_gen}}
```
```math
P_{\text{from\_storage}} = \text{Microgrid discharges batteries to meet } \text{Demand}_{\text{remaining}}
```

The final power supplied is the sum from both sources, and any remaining unmet demand is the shortage.

```math
P_{\text{supply}} = P_{\text{from\_gen}} + P_{\text{from\_storage}}
```
```math
P_{\text{shortage}} = \max(0, P_{\text{demand}} - P_{\text{supply}})
```

**4. Charge Storage**

If there was excess power generated $P_{\text{gen}} > P_{\text{demand}}$, this surplus is used to charge the batteries.

```math
P_{\text{excess}} = \max(0, P_{\text{gen}} - P_{\text{demand}})
```
```math
\text{Microgrid uses } P_{\text{excess}} \text{ to charge batteries, accounting for } \eta_{\text{charge}}.
```

## Configuration Options

The `EnergySector` is configured in the `world_system` JSON file by defining its `generators` and `storage_units`.

```json
"energy": {
  "sector_name": "energy",
  "generators": [
    {
      "name": "Main Solar Array",
      "type": "SOLAR",
      "capacity_kW": 500,
      "efficiency": 0.95,
      "availability": 1.0
    },
    {
      "name": "Kilopower Reactor",
      "type": "NUCLEAR",
      "capacity_kW": 10,
      "efficiency": 0.99,
      "availability": 1.0
    }
  ],
  "storage_units": [
    {
      "name": "Primary Battery Bank",
      "type": "LI_ION",
      "capacity_kWh": 2000,
      "charge_efficiency": 0.9,
      "discharge_efficiency": 0.9,
      "initial_charge_percent": 0.75
    }
  ]
}
```