# Ledgerly Home Battery Simulator

> Is a home battery worth it? Hour-by-hour year with your load, several battery sizes compared. Simulates a year hour by hour: solar power from the offline yield model (or your monthly figures), your consumption from a smart-meter export, hourly values or a simple household profile, and a battery with its capacity, power and losses. Compares several sizes by self-consumption, self-sufficiency, grid import, export, cycles and the money each one saves. Part of Ledgerly’s Solar & Heat.

Part of usefulweb.app (https://usefulweb.app/). Part of [Ledgerly](https://ledgerly.usefulweb.app/) (ownerApp: ledgerly). Results are deterministic calculations from the inputs and the listed assumptions; the API returns exactly what the web page shows.

## Use it
- Human interface: https://ledgerlybatterysim.usefulweb.app/ (interactive tool at https://ledgerlybatterysim.usefulweb.app/tool)
- JSON API: POST https://ledgerlybatterysim.usefulweb.app/api/v1/calculate with a JSON object of inputs (schema: https://ledgerlybatterysim.usefulweb.app/api/v1/tool)
- OpenAPI: https://ledgerlybatterysim.usefulweb.app/openapi.json
- MCP (Streamable HTTP): https://ledgerlybatterysim.usefulweb.app/mcp - tool `ledgerly_battery_sim`

## Inputs
- currency (text): Currency
- latitude (number): Latitude (°, south negative)
- longitude (number): Longitude (°, west negative)
- peakPowerKw (number): Peak power of the PV system (kWp)
- tilt (number): Tilt (° from horizontal)
- azimuth (number): Orientation (° from south: east −90, west 90)
- layout (select): Panel layout
- utcOffset (number): Time zone (hours from UTC, standard time)
- pvMonthlyKwh (text): PV yield per month (kWh, 12 values; empty = offline estimate) - Paste the monthly figures from the yield calculation or PVGIS; the daily curve still comes from the sun’s path.
- annualLoadKwh (number): Electricity use per year (kWh; empty = from the profile) - With the built-in profile an empty value means 4,000 kWh. With your own profile it rescales the profile to this total.
- loadProfile (textarea): Your load profile: 24, 288 or 8,760 hourly kWh values, or smart-meter readings - Empty = Ledgerly’s simple household profile. Meter readings: one line per reading with date, time and kWh.
- batteryKwh (number): Usable battery capacity (kWh)
- compareCapacities (text): Also compare these capacities (kWh)
- batteryPowerKw (number): Battery charge and discharge power (kW)
- roundTripEfficiencyPercent (number): Round-trip efficiency (%)
- exportLimitKw (number): Feed-in limit (kW, 0 = none)
- electricityPrice (number): Electricity price per kWh
- feedInTariff (number): Feed-in payment per kWh
- seed (integer): Weather sequence (seed) - Sunny, mixed and dull days are drawn from this seed; the same seed always gives the same year.

## Method
- 8,760 hourly steps (365 days). Solar power per month comes from the offline yield model or your 12 monthly figures, shaped by the sun’s path for your tilt and orientation; each day is sunny, mixed or dull, drawn from a seeded sequence in which a class often lasts several days, and every month keeps its total.
- Consumption: smart-meter readings (any interval, averaged per month and clock hour), 24 / 288 / 8,760 hourly values, or Ledgerly’s simple household profile; the yearly total rescales it.
- Each hour solar power first covers the load, the surplus charges the battery (limited by capacity and power), and the battery covers later demand; round-trip losses are split evenly between charging and discharging. The battery starts empty on 1 January.
- Self-consumption = solar power used in the house (directly or via the battery) ÷ solar power; self-sufficiency = consumption not bought from the grid ÷ consumption. The worth of a battery = grid power saved × price − export lost × feed-in payment, against the same system without a battery.

## Limits
- Hourly steps smooth out short load peaks, so real self-consumption is usually a few points lower. Battery installation is electrical work for a qualified installer following local codes (e.g. VDE, NEC).