Ecosizing — User Manual

1. Introduction

Ecosizing is an intelligent microgrid planning and operation simulation platform that helps energy engineers and project developers design optimal renewable energy systems with maximum economic returns over their entire lifecycle.

1.1 What Ecosizing Does

Ecosizing solves the complex challenge of determining the optimal configuration of microgrid components—including PV system and battery energy storage system under Design Mode . It answers critical questions such as: What equipment should be installed? How much capacity is needed? What operational strategy maximizes profitability while ensuring reliable power supply?

Additionally, Ecosizing offers an Operation Mode that evaluates the economic performance of a predefined capacity configuration. This mode is valuable when you already have a specific equipment layout in mind—whether from preliminary studies, vendor proposals, or existing installations—and need to assess its financial viability, compare different design alternatives, or validate third-party recommendations before committing to investment.

1.2 Core Capabilities

Design Optimization:

Ecosizing formulates the sizing problem as a Mixed-Integer Linear Programming (MILP) model, incorporating comprehensive economic factors—including capital investment, financing options (loans, PPA), equipment degradation, taxes, operation & maintenance costs, and salvage value. Critically, the optimization uses full-year, high-resolution time-series data (8760 hours for standard years, 8784 hours for leap years) to evaluate economic returns, ensuring that the sizing decisions account for actual seasonal variations, daily load patterns, and solar resource availability throughout the entire year. This comprehensive temporal modeling—not simplified averages or typical days—guarantees that the optimal equipment configuration maximizes net present value (NPV) under realistic operating conditions.
The Design Mode offers flexible optimization strategies: users can either optimize all equipment capacities simultaneously, or fix certain component capacities (e.g., specify a predetermined PV capacity) while optimizing others (e.g., battery storage capacity). This enables scenario analysis, incremental expansion planning, and evaluation of specific design constraints.

Operation Simulation:

Building on the optimized design, Ecosizing performs year-by-year operation planning across the entire project life. For each year, it simulates hourly or sub-hourly operations, accounting for equipment aging, performance degradation, battery replacements, battery augmentations, and changing economic conditions. This provides a realistic forecast of system behavior and economic performance.

Financial Analysis:

Ecosizing computes comprehensive financial metrics including NPV, IRR, equity IRR, levelized cost of energy (LCOE), payback period, and detailed annual cash flows. It supports multiple investment modes (self-investment vs. power purchase agreement), loan scenarios, and tax considerations, following industry-standard financial modeling practices.

Design Report: (coming soon)

1.3 Why Ecosizing is Reliable

Unlike heuristic or simulation-based tools, Ecosizing uses proven mathematical optimization solvers (CBC, Gurobi) to find provably optimal solutions. The MILP formulation ensures that results are unique, optimal, and interpretable—not dependent on random initial conditions or approximation algorithms. This mathematical rigor provides confidence that the recommended design truly maximizes economic value under the given constraints.

1.4 What You Get

Optimal Equipment Sizing: Exact number and capacity of each component (PV modules, batteries, inverters)
Operation Strategy: Hourly or sub-hourly operation plan showing energy flows, charging/discharging patterns, grid interactions, state-of-charge of battery
Financial Projections: Detailed cash flow statements, profitability metrics, and sensitivity analysis
Professional Reports: Exportable design reports with charts, tables, and economic analysis (testing)

1.5 Typical Use Cases

Off-grid renewable microgrids for remote communities, industrial sites, or mining operations
Grid-connected solar + storage systems for commercial buildings or industrial facilities
Solar + BESS (Constant Power) systems for PPA scenarios

Ecosizing is designed for energy consultants, project developers, utilities, and research institutions seeking rigorous, data-driven microgrid design solutions.

2. System Requirements

Browser: Latest Chrome
Network: Stable internet connection

3. Quick Start

Step 1: Input Project Configuration, select Run Mode (Design Mode: optimize equipment capacity; Operation Mode: evaluate given capacity) and Scenario.
Step 2: Configure Finance Parameters (Loan, Tax).
Step 3: Configure Components (PV System-AC, PV System-DC, BESS, Grid).
Step 4: Configure Load (load profile).
Step 5: Configure Genset (if applicable).
Run simulation.
Review Results: investment scheme, operation policy, KPIs, cash flow, design reports.

4. UI Tour (Page-by-Page)

Input www.ecosizing.com in your browser to access Ecosizing.
Click the 📖 button in the top-right corner to open user manual at any time.

4.1 Authentication & Session

Ecosizing provides a secure authentication system with user registration, login, email verification, and password recovery. Session management ensures your work is preserved during long optimization runs.

Registration

Access: Click "Create an account" on the login page or navigate to www.ecosizing.com/en/auth/register.
Fields:
- Username: required.
- Email: required; used for verification.
- Full Name: optional.
- Password and Confirm Password: required; show/hide toggle available.
- Security Question and Answer: optional but recommended for account recovery.
Flow:
1. Fill required fields and submit "Create account".
2. A verification email is sent; the page shows verification status and your email.
3. If not received, use "Resend verification email"; then return to Sign In after verifying.
Tips:
- Keep the verification page open to use the resend button if needed.
- Use the language toggle to switch CN/EN.
Example:

Access: Navigate to the login page at www.ecosizing.com/en/auth/login or click "Sign In" from the homepage.
Fields:
- Email or Username: Enter your registered email address or username.
- Password: Your account password (show/hide toggle available).
- Remember Me: Optional checkbox to keep you signed in across browser sessions.
Actions:
- Click "Sign In" to access your account.
- "Forgot Password?" link for password recovery.
- "Create an account" link to register a new account.
Session: Once authenticated, your session remains active. For long-running optimizations, the system automatically maintains your session to prevent timeout interruptions.

4.2 Getting Started: Two Ways to Configure Your Project

After signing in, click + New Plan to new an optimization job, you can set up this project using one of two methods:

Method 1: Import JSON Configuration (Quick Start)

Best for: Users with pre-configured projects, or replicating previous studies.
Click Download Examples in the left sidebar to download JSON file for you explore.
Click Import Config in the left sidebar to import pre-configured JSON file.
Select a JSON file containing your complete project configuration.
The system automatically populates all sections: Project info, Finance, and all component parameters.
Review and modify: After import, you can navigate to any section and adjust individual parameters as needed. The imported configuration serves as a starting point, not a final locked-in setup.
Click Start Simulation to start the optimization once satisfied with the configuration.
Advantages: Fast setup, ensures consistency across projects, easy to share configurations with team members, flexible post-import editing.
Notes:
- The JSON must follow the top-level keys: project, finance, inverter, pv, battery, grid, genset, load.
- When a component's included is true, its required fields must be present (see Section 4.3).
- If a component is not included in the project, its corresponding key-value pair can be omitted from the JSON file.
- Time-series arrays should be numeric and consistent with time_resolution. Valid lengths are 8760/8784 for 60-minute steps, 17520/17568 for 30-minute steps, and 35040/35136 for 15-minute steps.

Method 2: Manual Configuration (Step-by-Step)

Best for: New users, custom projects, or when you want full control over each parameter.
Configure each section sequentially using the left navigation panel:
1. Project Configuration: Set project name, time resolution, run mode, scenario, currency, location.
2. Finance Parameters: Define project life, discount rate, loan options, tax rates.
3. Components: Configure PV, Battery, Inverter, Grid connection.
4. Load Profile: Upload or input load data by grade (1/2/3).
5. Genset: Set fuel type, capacity, production cost, minimum output, carbon dioxide emission factor (if included in scenario).
The UI validates inputs in real-time, highlighting any missing or invalid fields.
Click Start Simulation when all required fields are complete.
Advantages: Full transparency, easier to understand each parameter, flexible customization.
Note:
- Fields marked with an asterisk (*) are required and must be filled in before running the simulation.
- Genset is configured separately from Components because they are typically purchased independently by electricity users or already exist on-site. Users are responsible for their operation and maintenance. This tool does not optimize genset capacity nor consider their investment costs in the economic analysis.

Switching Between Methods:

You can start with Method 1 (import JSON) and then modify parameters manually.
After completing manual configuration, export your settings as JSON for backup or future use.
Before running: It's recommended to export your configuration by clicking Export Config in the left sidebar. This saves your setup locally and allows you to:
- Re-run the same configuration later without re-entering data
- Share the exact configuration with colleagues or clients
- Create variations by importing and modifying the JSON
- Keep a record of what parameters were used for each optimization run
The exported JSON file can be re-imported at any time to restore the complete configuration.

4.3 Configuration Parameters Reference

Note:
- Fields marked with an asterisk (*) are required; other fields are optional.
- All prices and monetary values are tax-inclusive (including VAT where applicable).

4.3.1 Project Configuration

Fields shown on the left navigation under "Ecosize → Project Configuration".
Required fields:
- Project Name
- Run Mode: Design Mode or Operation Mode
  - Design Mode: Optimizes technology capacities, then performs lifecycle operation simulation and analyzes the economic performance of the optimized configuration.
  - Operation Mode: Performs lifecycle operation simulation for given capacities and analyzes the economic performance of the predefined scheme.
- Scenario: Choose the system topology that matches your project. Six scenarios are supported:
  - Battery + Grid (battery-grid): Grid-connected battery storage only, no PV. Useful for pure arbitrage, peak-shaving, or demand management using grid electricity. Requires: Battery, Grid, Load.
  - PV + Battery (Constant Power) (pv-battery-constant-power): Off-grid system with PV and battery, optimized to deliver a constant-power supply profile. Suitable for remote sites with flat power demand. Requires: PV, Inverter, Battery, Load.
  - PV + Battery + Grid (pv-battery-grid): Grid-connected solar+storage system. Revenue comes from self-consumption, TOU arbitrage, feed-in tariffs, and demand charge avoidance. Requires: PV, Inverter, Battery, Grid, Load.
  - PV + Battery + Genset (pv-battery-genset): Off-grid microgrid with solar, storage, and diesel/gas backup. The optimizer minimizes fuel cost while maintaining supply reliability. Requires: PV, Inverter, Battery, Genset, Load.
- Currency: CNY, USD, or EUR
- Time Resolution: simulation step length. Options are 60 minutes (hourly), 30 minutes, or 15 minutes. It determines the required length of full-year time-series inputs and the time granularity of operation-plan charts and exported dispatch data.
- Longitude: between -180 and 180 (Eastern Longitude is positive, Western Longitude is negative)
- Latitude: between -90 and 90 (Northern hemisphere is positive, Southern hemisphere is negative)
- Altitude: between -500 and 9000 (meters)

Project field reference

Field	JSON path	Unit	Range / Default	Required when	Description
Project Name	`project.project_name`	—	free text	always	Human-readable project identifier used in reports and exports.
Run Mode	`project.run_mode`	enum	`design` \| `operation`	always	`design` optimizes capacities then simulates; `operation` simulates only using given capacities.
Scenario	`project.scenario`	enum	one of the six scenario ids	always	Selects the system topology and drives which components are required.
Currency	`project.currency`	enum	`CNY` \| `USD` \| `EUR`	always	All monetary values in the config and reports use this currency.
Time Resolution	`project.time_resolution`	minutes	`15` \| `30` \| `60` (default 60)	always	Simulation step length. Full-year time-series lengths: 35040/35136, 17520/17568, or 8760/8784 points. Grid fields (purchase price, grid connect, TOU demand) accept coarser input and are auto-expanded.
Longitude	`project.longitude`	deg	-180 – 180	always	East positive, West negative. Drives PV auto-generation and weather-based modeling.
Latitude	`project.latitude`	deg	-90 – 90	always	North positive, South negative. Also used as the default PV tilt when auto-generating.
Altitude	`project.altitude`	m	-500 – 9000	always	Site elevation above sea level; used in PV resource modeling.

Example:

4.3.2 Finance Parameters

Project Life: ≥10 (years). The total project lifecycle over which the economic analysis is performed.
Optional Capital Investment: default no limit (leave empty), if applicable, input number > 0. Maximum total capital expenditure (CAPEX) budget including equity and loan. The optimizer will not exceed this budget.
Investment Mode:
- Self-Invest: Evaluates economic performance from the perspective of electricity consumers. The investor is the electricity consumer who pays for equipment and benefits from reduced electricity bills.
- PPA: Evaluates economic performance from the perspective of a capital investor. The investor builds and owns the system, then sells electricity to the end user under a Power Purchase Agreement (PPA).
Expected Annual ROI: 5-100 (%), default 10%. The expected annual return on investment, used as a reference benchmark for project profitability assessment.
Construction Rate: 0-100 (%), default 10%. The ratio of civil construction and installation cost to total equipment cost. This is added on top of equipment CAPEX.
Discount Rate: 0-100 (%), the WACC (Weighted Average Cost of Capital) or required rate of return, used to discount future cash flows to present value.
Insurance Rate: 0-1 (%), annual insurance fee as a percentage of total CAPEX. Applied each year as an OPEX item.
Depreciation Period: 0-30 (years), the accounting period over which the asset cost is written down for tax purposes. If left empty, defaults to the project life.
Salvage Ratio: 0-20 (%), the estimated residual value of assets at end of project life, expressed as a percentage of original CAPEX. This is recovered as income in the final year.
Tax Settings
- Income Tax Rate: 0-100 (%), corporate income tax rate applied to taxable profit each year.
- Equipment VAT Rate: 0-100 (%), Value Added Tax percentage applied to equipment purchases. Input VAT on equipment can be deducted.
- Service VAT Rate: 0-100 (%), VAT percentage applied to installation, fuel and service costs.
- Optional Surtax Rate: 0-100 (%), default 0. Surcharges (e.g., urban construction tax, education surcharge) levied as a percentage of the VAT payable.
- Optional Stamp Duty and Fund Rate: 0-100 (%), default 0. Taxes calculated as a percentage of revenue (excluding VAT), such as stamp duty or water conservancy fund.
Loan Settings (default not included; click the toggle to include if project uses debt financing)
- Loan Ratio: 0-100 (%), ratio of loan amount to total CAPEX.
- Loan Interest Rate: ≥0 (%), annual nominal interest rate on the loan.
- Loan Period: 1 – project life (years), total repayment term.
- Repayment Type:
  - Equal Installment (Annuity): Fixed total payment each period. Interest-heavy in early years, shifting to principal in later years.
  - Equal Principal (Linear): Fixed principal repayment each period. Higher total payments initially, decreasing over time.
Land Settings (default not included; click the toggle to include if land cost applies)
- Land Cost per Unit: total land acquisition cost (>0, in selected currency).
- Land Area: area of land (>0).
- Area Unit: sqm (square meters), mu (Chinese land unit, 1 mu ≈ 667 m²), or acre.

Finance field reference

Field	JSON path	Unit	Range / Default	Required when	Description
Project Life	`finance.project_life`	years	10 – 30	always	Number of years over which lifecycle cash flows are computed.
Capital	`finance.capital`	currency	number > 0 or no limit	always (defaults no limit)	Maximum CAPEX budget. Leave empty for no limit
Invest Mode	`finance.invest_mode`	enum	`self_invest` \| `ppa`	always	Determines revenue calculation.
Expected Annual ROI	`finance.expected_annual_roi`	%	5 – 100 (default 10)	optional	Expected annual return on investment benchmark.
Construction Rate	`finance.construction_rate`	%	0 – 100 (default 10)	always	Civil + installation cost multiplier on equipment CAPEX.
Discount Rate	`finance.discount_rate`	%	0 – 100	always	Applied to every future cash flow to obtain present value.
Insurance Rate	`finance.insurance_rate`	%	0 – 1	always	Annual insurance premium as % of CAPEX.
Depreciation Period	`finance.depreciation_period`	years	1 – project_life	optional	If empty, defaults to project life.
Salvage Ratio	`finance.salvage_ratio`	%	0 – 20	always	Residual asset value (% of CAPEX) recovered in the final year.
Tax Included	`finance.tax.included`	bool	true / false	always	Toggles the whole tax block.
Income Tax Rate	`finance.tax.income_tax_rate`	%	0 – 100	if `tax.included`	Corporate income tax.
Equip VAT Rate	`finance.tax.equip_vat_rate`	%	0 – 100	if `tax.included`	VAT on equipment; deductible as input VAT.
Service VAT Rate	`finance.tax.service_vat_rate`	%	0 – 100	if `tax.included`	VAT on installation/fuel/service.
Surtax Rate	`finance.tax.surtax_rate`	%	0 – 100 (default 0)	optional	Surcharges on VAT payable.
Stamp Duty & Fund	`finance.tax.stamp_duty_and_fund_rate`	%	0 – 100 (default 0)	optional	Taxes on revenue (ex-VAT).
Loan Included	`finance.loan.included`	bool	true / false	always	Toggles the whole loan block.
Loan Ratio	`finance.loan.loan_ratio`	%	0 – 100	if `loan.included`	Debt-to-CAPEX ratio.
Loan Interest Rate	`finance.loan.loan_interest_rate`	%	≥ 0	if `loan.included`	Nominal annual rate.
Loan Period	`finance.loan.loan_period`	years	1 – project_life	if `loan.included`	Repayment term.
Repayment Type	`finance.loan.repayment_type`	enum	`equal_principal` \| `equal_installment`	if `loan.included`	Linear vs annuity.
Land Included	`finance.land.included`	bool	true / false	always	Toggles the land-cost block.
Land Cost	`finance.land.land_cost`	currency	> 0	if `land.included`	unit cost of land acquisition.
Land Area	`finance.land.land_area`	area	> 0	if `land.included`	Land area value.
Area Unit	`finance.land.area_unit`	enum	`sqm` \| `mu` \| `acre`	if `land.included`	Unit of `land_area`.

4.3.3 Components

Each technology component has an included field and an Alternative Models array (the lib array in JSON) for the equipment library. When included is true, relevant parameters become required. Library entries have Unit Capacity, Unit Price, and Selected Number fields.

PV System-DC (PV Module)

Optional First Year Decay Rate: 0-5 (%), default 2%, performance degradation rate for the first year.
Optional Average Annual Decay Rate: 0-2 (%), default 0.5%, average annual performance degradation rate from 2nd year onwards.
Optional Calendar Life: 10-30 (years), default 30 years.
O&M Cost: >0 (currency/kW/year) when PV is included.
Optional Maximum PV Capacity, default no limit, number > 0 (kW) or leave empty for no limit, usually limited by the installable area.
Alternative Models: Users can select PV model from the dropdown list or customize component specifications. For custom specifications, input Unit Capacity (kW) and Unit Price (currency/kW). You can select one or multiple models as alternatives (one model is recommended). If you have already determined the PV capacity, check Specify number of units and input the Number of Units.
PV Unit Output Timeseries: A full-year normalized PV generation profile is required, representing the power output per kWp of installed PV capacity. Its length must match Time Resolution (8760/8784 for 60-minute steps, 17520/17568 for 30-minute steps, or 35040/35136 for 15-minute steps), with values between 0 and 1.5.
- Upload CSV: You can either download the CSV template, fill in the data, and upload it, or
- Auto-Generate: choose Auto-Generate and click Generate PV Timeseries. The auto-generation utilizes the Open-Meteo weather data source and the pvlib library for simulation, taking the AC-side output as the result (assuming 99% inverter efficiency).
Note:
You can lock the number of PV modules by checking the Specify number of units checkbox (if you have already determined the capacity). Once checked, a Number of Units input field will appear for each model.
In Operation Mode, the Number of Units must be specified for each selected model.
You can select the PV module model and specification from the dropdown list in the Model field.
PV Unit Output Timeseries represents the full-year power generation per kW of installed PV capacity at the selected simulation step. You can import it via CSV (refer to the CSV template) or use the Auto-Generate feature.

PV (DC) field reference

Field	JSON path	Unit	Range / Default	Required when	Description
Included	`pv.included`	bool	—	always	Turns the component on/off.
Specify number of units	`pv.given_selected_number`	bool	—	always	When true, `lib[].selected_number` is treated as a fixed input, not a decision variable. Must be true in Operation Mode.
First Year Decay Rate	`pv.decay_rate[0]`	%	0 – 5 (default 2)	optional	First-year PV performance drop.
Average Annual Decay Rate	`pv.decay_rate[1]`	%	0 – 2 (default 0.5)	optional	Average annual PV degradation from 2nd year.
Calendar Life	`pv.calendar_life`	years	10 – 30 (default 30)	optional	Physical PV module lifetime.
O&M Cost	`pv.operation_and_maintenance_cost`	currency/kW/year	> 0	if `pv.included`	Annual PV O&M cost per installed kW.
Max PV Capacity	`pv.capacity_max_kw`	kW	> 0 or empty	optional	Upper bound on total PV; empty = no limit.
Unit Capacity	`pv.lib[].unit_capacity`	kW	> 0	if `pv.included`	Nameplate capacity of one PV module.
Unit Price	`pv.lib[].unit_price_per_kw`	currency/kW	> 0	if `pv.included`	CAPEX per kW for this model.
Selected Number	`pv.lib[].selected_number`	count	≥ 0, integer	if `Specify number of units` or Operation Mode	Number of units of this model.
PV Unit Timeseries	`pv.pv_unit_ts`	kW/kWp	Length must match `project.time_resolution`; values 0 – 1.5	if `pv.included`	Normalized PV output per kWp at the selected simulation step.

PV System-AC (Inverter)

Optional Overload Ratio: 100–150 (%), default 100%, inverter overload tolerance.
Optional PV/Inverter Ratio: 100 – 1000 (%), maximum allowed ratio of PV DC capacity to inverter AC capacity.
O&M Cost: ≥0 (currency/kW/year) when inverter is included.
Alternative Models: Users can select inverter model from the dropdown list or customize component specifications. For custom specifications, input Unit Capacity (kW) and Unit Price (currency/kW). You can select one or multiple models as alternatives (one model is recommended). If you have already determined the inverter capacity, check Specify number of units and input the Number of Units.
Note:
Inverter must be included whenever PV is included, and excluded whenever PV is excluded.
You can lock the number of inverters by checking the Specify number of units checkbox (if you have already determined the capacity). Once checked, a Number of Units input field will appear for each model.
In Operation Mode, the Number of Units must be specified for each selected model.

Inverter field reference

Field	JSON path	Unit	Range / Default	Required when	Description
Included	`inverter.included`	bool	—	must match `pv.included`	Enables the AC side of the PV system.
Overload Ratio	`inverter.overload_ratio`	%	100 – 150 (default 100)	optional	Short-term overload tolerance.
PV/Inverter Ratio	`inverter.pv_inverter_ratio`	%	100 – 1000	optional	DC/AC ratio upper bound (e.g., 120 = 1.2).
O&M Cost	`inverter.operation_and_maintenance_cost`	currency/kW/year	≥ 0	if `inverter.included`	Annual inverter O&M cost per kW.
Unit Capacity	`inverter.lib[].unit_capacity`	kW	> 0	if `inverter.included`	Rated capacity of one inverter unit.
Unit Price	`inverter.lib[].unit_price_per_kw`	currency/kW	> 0	if `inverter.included`	CAPEX per kW for this model.
Selected Number	`inverter.lib[].selected_number`	count	≥ 0, integer	if `Specify number of units` or Operation Mode	Number of inverter units.

Integrated AC-DC Battery Storage System (BESS)

Optional Calendar Life: 10–30 (years), default 20, battery calendar lifetime in years.
Optional Cycle Life: 2000–10000 (cycles), default 8000 cycles, number of full charge-discharge cycles.
O&M Cost: ≥0 (currency/kWh/year) when battery is included.
Alternative Models: Users can select BESS model from the dropdown list or customize component specifications. For custom specifications, input Unit Capacity (kWh), PCS Capacity (kW), Unit Price (currency/kWh), and C-Rate. You can select one or multiple models as alternatives (one model is recommended). If you have already determined the battery capacity, check Specify number of units and input the Number of Units.
- Note: In Operation Mode, the Number of Units must be specified for each selected model.
Example:
Advanced Settings: Expand to configure additional parameters for fine-tuning battery performance and operational constraints.
Optional Maximum PV/Battery Ratio: 0-3, default 2, maximum ratio of PV capacity to PCS capacity. This parameter considers the grid-forming requirements of the battery energy storage system to ensuPV-BESS System stability.
- Note: This parameter only takes effect in off-grid scenarios when grid-forming is required.
Optional Charging Efficiency, Discharging Efficiency: 85–98 (%), charge/discharge efficiency.
Optional Initial SOC: 0-100 (%). Minimum SOC: 0-30 (%). Maximum SOC: 70-100 (%).
- Note: Initial SOC must be between Minimum SOC and Maximum SOC.
Optional State of Health (SOH): 80–100 (%), initial State of Health. The SOH value is used to calculate the available capacity for the typical year in the design optimization phase. During the full lifecycle operation simulation, the battery will be restored to a new battery condition (100%). For grid-connected scenarios, it is recommended to set SOH to 85-90%. For off-grid scenarios, it is recommended to set SOH to 90-95% and enable Consider Capacity Augmentation.
Optional PCS Capacity Reserve: 10–50 (%), default 20%, the ratio of reserve power of PCS. For example, for a battery system with 10 MW PCS capacity, if pcs_capacity_margin is 20%, the system operates at a maximum power of 8 MW during normal operation, reserving 2 MW as backup capacity.
- Why this matters: PCS capacity margin prevents the power conversion system from running at 100% rated load continuously, which preserves equipment lifetime and leaves headroom for transient events. It is particularly important in off-grid / grid-forming scenarios where the BESS must absorb sudden load steps or PV fluctuations without tripping. For grid-connected only projects, a lower margin (e.g., 10–15%) may be acceptable.
- Tip: If your project requires grid-forming (off-grid or weak-grid scenarios), keep this at 20% or higher. For pure grid-following applications, 10–15% is usually sufficient.
Allow Grid Charge: Only shown when investment mode is PPA and grid is included. Enables battery charging from the grid.
Optional Arbitrage Threshold: {currency}/kWh, default CNY: 0.5 / USD: 0.07 / EUR: 0.06. Minimum peak-valley price spread for battery arbitrage. The battery only performs charge/discharge arbitrage when the spread exceeds this threshold. Only shown when grid is present.
Consider Battery Replacement: default disabled, whether to consider battery replacement during the project lifecycle when the battery calendar life or cycle life ends.
Replacement SOH Threshold: 50–90 (%), State of Health threshold triggering replacement.
Consider Capacity Augmentation: default disabled, whether to add capacity to compensate for battery degradation and restore available capacity. Due to battery degradation over time, users may need capacity augmentation to maintain the designed capacity level, especially in off-grid scenarios where this is strongly recommended.
Capacity Augmentation Threshold: 50–95 (%), SOH value at which capacity augmentation is triggered (defaults to match the initial SOH when empty).

Battery (BESS) field reference

Field	JSON path	Unit	Range / Default	Required when	Description
Included	`battery.included`	bool	—	always	Turns the BESS on/off.
Specify number of units	`battery.given_selected_number`	bool	—	always	Fix `selected_number` as input; mandatory in Operation Mode.
Require Grid Forming	`battery.require_grid_forming`	bool	—	optional	Enables grid-forming constraint (relevant off-grid).

| Arbitrage Threshold | battery.arbitrage_threshold | {currency}/kWh | ≥0 (default CNY:0.5/USD:0.07/EUR:0.06) | optional | Min peak-valley spread for arbitrage. Only shown when grid is present. | | Max PV/Battery Ratio | battery.pv_2_batt_ratio_max | ratio | 0 – 3 (default 2) | optional | Upper bound on PV-to-PCS ratio when grid-forming. | | Calendar Life | battery.calendar_life | years | 10 – 30 (default 20) | optional | Physical battery lifetime. | | Cycle Life | battery.cycle_life | cycles | 2000 – 10000 (default 8000) | optional | Full equivalent cycles before end-of-life. | | Charge Efficiency | battery.eta_charge | % | 85 – 98 (default 95) | optional | Round-trip charge efficiency. | | Discharge Efficiency | battery.eta_discharge | % | 85 – 98 (default 95) | optional | Round-trip discharge efficiency. | | SOH | battery.soh | % | 80 – 100 (default 95) | optional | Initial state of health; shapes available capacity. | | Initial SOC | battery.soc_init | % | 0 – 100 (default 95) | optional | Must lie between soc_min and soc_max. | | Minimum SOC | battery.soc_min | % | 0 – 30 (default 5) | optional | Discharge cutoff. | | Maximum SOC | battery.soc_max | % | 70 – 100 (default 95) | optional | Charge cutoff. | | PCS Capacity Reserve | battery.pcs_capacity_margin | % | 0 – 50 (default 0) | optional | Reserve fraction of PCS power. | | O&M Cost | battery.operation_and_maintenance_cost | currency/kWh/year | ≥ 0 | if battery.included | Annual battery O&M per kWh. | | Unit Capacity | battery.lib[].unit_capacity | kWh | > 0 | if battery.included | Nameplate capacity of one battery unit. | | Unit Price | battery.lib[].unit_price_per_kwh | currency/kWh | > 0 | if battery.included | CAPEX per kWh for this model. | | C-Rate | battery.lib[].c_rate | C | > 0 | if battery.included | Max charge/discharge rate as a multiple of capacity. | | PCS Capacity | battery.lib[].pcs_capacity | kW | > 0 | if battery.included | Rated Power for this model. | | Selected Number | battery.lib[].selected_number | count | ≥ 0, integer | if Specify number of units or Operation Mode | Units of this model. | | Consider Replacement | battery.consider_replacement | bool | default false | always | Include end-of-life replacements in CAPEX. | | Replacement SOH Threshold | battery.replacement_soh_threshold | % | 50 – 90 | if Consider Battery Replacement | SOH value that triggers replacement. | | Consider Capacity Augmentation | battery.consider_capacity_augmentation | bool | default false | always | Top up capacity instead of full replacement. | | Capacity Augmentation Threshold | battery.capacity_augmentation_threshold | % | 50 – 95 | if Consider Capacity Augmentation | SOH value that triggers augmentation (defaults to match SOH). |

Grid (Utility Grid Connection)

Optional STS (Static Transfer Switch / On-Off Grid Cabinet):
- What it is: The STS is a power-electronic switch that enables seamless, sub-cycle transfer between grid-connected and islanded (off-grid) modes. It is essential for projects that require:
  - Grid-forming capability: When the microgrid must establish its own voltage and frequency reference during islanding.
  - Weak-grid support: When the utility grid is unreliable (frequent outages, voltage sags, frequency deviations) and the system must disconnect and reconnect smoothly without interrupting the load.
  - Fast transfer during grid disturbances: The STS detects grid faults and isolates the microgrid within milliseconds, preventing equipment damage and supply interruption.
- When to fill in: Only if your project physically includes a static transfer switch or on/off-grid cabinet. If you do not have this equipment, leave this section disabled.
- STS Capacity (kW): rated capacity of the transfer switch connecting the microgrid to the utility grid. Must be > 0 when STS is enabled.
- STS Price (currency): equipment cost of the STS/transfer cabinet. Include this if the STS is an investment item for the project.
Optional Grid Investment: ≥0 (currency), one-time investment cost for grid connection or upgrade (e.g., step-up transformer, line extension).
Optional O&M Cost: ≥0 (currency/year), annual operation and maintenance cost for the grid connection infrastructure.
Optional Max Export Capacity: ≥0 (kW), default 0. Maximum power the system can feed back to the grid. When greater than 0, the Feed-in Tariff field must be filled in.
Max Import Capacity: ≥0 (kW), maximum grid import power limit.
Optional Feed-in Tariff: ≥0 (currency/kWh), electricity selling price when exporting to the grid. Required if Max Export Capacity > 0.
Consider Demand Management Revenue: Consider demand management revenue during economic evaluation.
Demand Type: Billing method for grid capacity/demand charges (basic electricity fees). Options:
- None: No demand charge applied.
- Monthly: Billed monthly based on peak power demand (typically the highest 15-min average within each calendar month). Fill in Demand Charge (per kW per month).
- Yearly: Billed annually based on the highest peak demand recorded over the year. Fill in Demand Charge (per kW per year).
Purchase Price per kWh: Time series of electricity purchase prices at the selected simulation step. Download the CSV template, fill in the data, and upload. You may fill in only Year 0 (column index 0) to apply the same prices for all years, or provide a column for each project year to model electricity price escalation. Coarser granularity is accepted (e.g. hourly data for a 15‑min simulation) and will be auto-expanded.
Optional Grid Connect Schedule: Binary time series (1 = grid available, 0 = unavailable). Coarser granularity is accepted and will be auto-expanded. Use this to model scheduled outages, rolling blackouts, or load-shedding periods imposed by the utility.
Optional Time of Use Demand Schedule: Grid capacity availability (kW) at the selected simulation step. Coarser granularity is accepted and will be auto-expanded. Use this when the utility limits the maximum import capacity during specific periods (time-based curtailment).
Optional CO₂ Emission Factor: default 0.55 kg CO₂/kWh, used to calculate carbon emissions from grid electricity consumption.
Note: For PV and load time-series, arrays must strictly match Time Resolution: 8760/8784 points for 60-minute steps, 17520/17568 for 30-minute steps, or 35040/35136 for 15-minute steps. Grid-related fields (purchase price, grid connect schedule, TOU demand schedule) accept coarser granularity and are auto-expanded: 1 h → 4×15 min, 1 h → 2×30 min, 30 min → 2×15 min.
Example:

Grid field reference

Field	JSON path	Unit	Range / Default	Required when	Description
Included	`grid.included`	bool	—	always	Enables utility grid connection.
Grid Investment	`grid.grid_investment`	currency	≥ 0 (default 0)	optional	One-time grid upgrade CAPEX.
O&M Cost	`grid.operation_and_maintenance_cost`	currency/year	≥ 0 (default 0)	optional	Annual grid O&M.
Max Import	`grid.max_import_capacity_kw`	kW	≥ 0	if `grid.included`	Maximum power drawn from the grid.
Max Export	`grid.max_export_capacity_kw`	kW	≥ 0 (default 0)	optional	Maximum feed-in; if > 0 requires `Feed-in Tariff`.
Feed-in Tariff	`grid.feed_in_tariff_per_kwh`	currency/kWh	≥ 0	if `max_export_capacity_kw` > 0	Price received per exported kWh.
Demand Type	`grid.demand_type`	enum	`none` \| `monthly` \| `yearly`	optional	Billing basis for demand charges.
Demand Charge (Month)	`grid.demand_charge_per_kw_per_month`	currency/kW/month	≥ 0	if `demand_type = monthly`	Monthly peak demand charge.
Demand Charge (Year)	`grid.demand_charge_per_kw_per_year`	currency/kW/year	≥ 0	if `demand_type = yearly`	Yearly peak demand charge.
Purchase Price	`grid.purchase_price_per_kwh`	dict[year→array]	Length can match simulation step or be coarser, ≥ 0	if `grid.included`	Purchase price series; coarser granularity auto-expanded (e.g. hourly → 15‑min).
Grid Connect Schedule	`grid.grid_connect_schedule`	0/1	Length can match simulation step or be coarser	optional	1 = grid available, 0 = outage. Coarser granularity auto-expanded.
TOU Demand Schedule	`grid.tou_demand_schedule`	kW	Length can match simulation step or be coarser, ≥ 0	optional	Max import limit by period. Coarser granularity auto-expanded.
CO₂ Emission Factor	`grid.carbon_dioxide_emission_factor`	kg/kWh	0 – 2 (default 0.55)	optional	Carbon intensity of grid electricity.
STS Capacity	`grid.sts.capacity`	kW	> 0	if STS enabled	rated capacity of Static Transfer Switch.
STS Price	`grid.sts.price`	currency	≥ 0	if STS enabled	Transfer-switch CAPEX.

4.3.4 Load (Electricity Demand)

Supply Hours per Year: 0–8784. The minimum required hours of electricity supply for Load Grade 1 and Load Grade 2 per year. E.g., 8000 hours means the cumulative annual energy supply to Grade 1 and Grade 2 loads equals (8000 / 8760) × (Grade 1 + Grade 2 load). In off-grid scenarios this is the key reliability constraint that determines battery and genset sizing.
Optional Green Power Ratio: 0–100 (%). Minimum percentage of total electricity that must come from PV+BESS (renewable sources). Leave empty for no constraint.
Supply Cost by Genset: 0–1000 (currency/kWh). This is the benchmark electricity cost for economic evaluation when no other power supply cost is entered. This field appears only in self-invest scenarios with neither grid nor genset; otherwise, it is hidden and not applicable.
PPA Pricing (visible when Invest Mode is PPA):
- PPA Price Mode: how electricity price to end-users is structured. Three modes:
  - Fixed: Single flat price per kWh.
    - Power Supply Guaranteed Volume (kWh/year): minimum annual energy guaranteed to the buyer.
    - PPA Price (currency/kWh): flat price for all energy supplied.
    - Insufficient Penalty (currency/kWh): penalty per kWh shortage.
  - Step: Tiered pricing above/below a volume threshold.
    - Annual Guaranteed Volume (kWh/year): minimum guaranteed annual energy.
    - PPA Price (currency/kWh): energy price for the guarantee volume.
    - Excess Volume Price (currency/kWh): energy price significantly above guaranteed volume.
    - Insufficient Penalty (currency/kWh): penalty per kWh shortage.
  - TOU (Time-of-Use): Price varies by time of day.
    - Annual Guaranteed Supply (kWh/year): minimum guaranteed annual energy.
    - Insufficient Penalty (currency/kWh): penalty per kWh shortage.
    - TOU PPA Price Time Series: price array at the selected simulation step (currency/kWh). Used when importing a full-year PPA price series directly.
    - PPA Discount Dict: maps project year → discount factor (%). E.g., {"1": 100, "5": 95, "10": 90} means full price in year 1, 5% discount from year 5, 10% from year 10. Used when pricing is derived as a discount off the grid purchase price (grid-connected scenarios only; requires importing grid purchase price series). Fill in the discount percentage for each pricing tier.
    - Note: TOU PPA pricing supports two methods: (1) import a full-year PPA price time series directly via TOU PPA Price Time Series; (2) derive prices as a discount off the grid purchase price (grid-connected scenarios only, requires grid purchase price data), by filling in Grid Discount Dict with the discount factor for each pricing tier.
- Optional Yearly PPA Discount: list of annual discount factors (0–100, %) applied to power supply revenue or cost per project year. E.g., [100, 98, 96] models a 2% annual discount step.
Load Grades — at least one must be included:
- Grade 1 Load (Critical/Firm): highest priority, must always be satisfied. Unsatisfied critical load counts as supply failure.
- Grade 2 Load (Interruptible): normal priority, can be curtailed (reduced or shut off) when energy is scarce.
- Grade 3 Load (Flexible): normal priority, can be adjusted upward or downward (both increase and curtailment) within defined limits.
Each grade requires:
- Load Time Series (load_ts): load profile (kW) at the selected simulation step; length must match Time Resolution.
Additional fields for Grade 3 Load:
- Upward Limit (%): 100–200. Maximum percentage of baseline allowed as peak (e.g., 120 = up to 120% of baseline).
- Downward Limit (%): 0–100. Floor percentage allowed (e.g., 80 = cannot drop below 80% of baseline).
- Operating Rate: 0–100, overall operating rate constraint for flexible loads.
- Optional Constant Power Hours: list of hour indices (0–23) during which the flexible load must hold constant power (no curtailment/increase allowed).

Load field reference

Field	JSON path	Unit	Range / Default	Required when	Description
Included	`load.included`	bool	—	always	Enables load configuration.
Supply Hours / Year	`load.supply_hours_per_year`	hours	0 – 8784	if `load.included`	Annual supply-hours reliability constraint.
Supply Cost by Genset	`load.supply_price_by_genset_per_kwh`	currency/kWh	0 – 1000	optional	Fallback supply cost used in self-invest off-grid.
Yearly PPA Discount	`load.yearly_power_supply_discount`	list[%]	each 0 – 100	optional	Per-year discount factors.
Green Power Ratio	`load.green_power_ratio`	%	0 – 100	optional	Minimum renewable share.
PPA Price Mode	`load.ppa_price_mode`	enum	`fixed` \| `step` \| `tou`	if `invest_mode = ppa`	Structure of end-user pricing.
Fixed PPA Annual Guaranteed Supply	`load.fixed_ppa.power_supply_guarantee_volume`	kWh/year	> 0	optional	Guaranteed energy in fixed PPA.
Fixed PPA Price	`load.fixed_ppa.ppa_price`	currency/kWh	> 0	if `ppa_price_mode = fixed`	Flat PPA price.
Fixed Penalty	`load.fixed_ppa.insufficient_penalty`	currency/kWh	≥ 0	optional	Shortfall penalty.
Step PPA Annual Guaranteed Supply	`load.step_ppa.power_supply_guarantee_volume`	kWh/year	> 0	if `ppa_price_mode = step`	Guarantee threshold.
Step PPA Price	`load.step_ppa.ppa_price`	currency/kWh	> 0	if `ppa_price_mode = step`	Above-threshold price.
Step Excess Price	`load.step_ppa.excess_volume_price`	currency/kWh	≥ 0	optional	Price for volumes far above the threshold.
Step Penalty	`load.step_ppa.insufficient_penalty`	currency/kWh	≥ 0	optional	Shortfall penalty.
TOU PPA Annual Guaranteed Supply	`load.tou_ppa.power_supply_guarantee_volume`	kWh/year	> 0	optional	Guarantee threshold.
TOU PPA Price Time Series	`load.tou_ppa.tou_price_ts`	currency/kWh	Length must match `project.time_resolution`, > 0	if TOU with explicit prices	PPA price series at the selected simulation step.
TOU Discount Dict	`load.tou_ppa.ppa_discount_dict`	dict[year→%]	0 – 100	if TOU with grid-price discounts	Per-year discount versus grid price.
TOU Penalty	`load.tou_ppa.insufficient_penalty`	currency/kWh	≥ 0	optional	Shortfall penalty.
Grade 1 Load	`load.grade_1_load.load_ts`	kW	Length must match `project.time_resolution`, ≥ 0	if grade 1 included	Critical load series.
Grade 2 Load	`load.grade_2_load.load_ts`	kW	Length must match `project.time_resolution`, ≥ 0	if grade 2 included	Standard load series.
Grade 3 Load	`load.grade_3_load.load_ts`	kW	Length must match `project.time_resolution`, ≥ 0	if grade 3 included	Flexible load baseline.
Grade 3 Operating Rate	`load.grade_3_load.operating_rate`	%	0 – 100	if grade 3 included	Overall runtime/utilization ratio.
Grade 3 Upward Limit	`load.grade_3_load.upward_limit`	%	100 – 200	if grade 3 included	Upward flexibility ceiling.
Grade 3 Downward Limit	`load.grade_3_load.downward_limit`	%	0 – 100	optional	Downward flexibility floor.
Grade 3 Constant Hours	`load.grade_3_load.constant_power_hours`	list[0–23]	hour indices	optional	Hours where power must be held constant.

4.3.5 Genset (scenario: `pv-battery-genset`)

Fuel Type: fuel used by the generator. Options: diesel, gasoline, natural_gas, biodiesel, coal, oil.
Installed Capacity (kW): total installed genset nameplate power. This is an upper bound on genset dispatch power; the optimizer will not exceed this value.
Minimum Output (kW): The minimum output of genset when running (prevents inefficient low-load operation).
Production Cost: ≥0 (currency/kWh), all-in variable cost of electricity generated by the genset, including fuel and consumables. Tip: compute as Fuel Consumption Rate [L/kWh] × Fuel Price [currency/L]. The currency-aware cap is 5 CNY/kWh or 0.5 USD/EUR/kWh.
Optional Genset Investment: ≥0 (currency), capital cost of the genset. Leave 0 if the genset is an existing on-site asset and not a new investment.
Optional O&M Cost: ≥0 (currency/year), fixed annual maintenance cost beyond the per-kWh production cost.
CO₂ Emission Factor (kg CO₂/kWh): used to calculate total carbon emissions from genset generation. Typical values: diesel ~0.65–0.70, natural gas ~0.45–0.55.
Note: Genset capacity is not a design variable — the optimizer dispatches genset output but does not size it. Supply the actual installed (or planned) genset capacity.

Genset field reference

Field	JSON path	Unit	Range / Default	Required when	Description
Included	`genset.included`	bool	—	always (genset scenarios)	Enables the generator block.
Fuel Type	`genset.fuel_type`	enum	`diesel` \| `gasoline` \| `natural_gas` \| `biodiesel` \| `coal` \| `oil`	if `genset.included`	Drives emissions and narrative categorization.
Installed Capacity	`genset.genset_capacity`	kW	≥ 0	optional (defaults 1.2× max load)	Installed nameplate power (not a decision variable).
Minimum Output	`genset.min_output`	kW	≥ 0	optional	Minimum output when running; prevents inefficient low load.
Production Cost	`genset.production_cost_per_kwh`	currency/kWh	0 – 5 (CNY) / 0 – 0.5 (USD/EUR)	if `genset.included`	All-in variable cost per kWh.
O&M Cost	`genset.operation_and_maintenance_cost`	currency/year	≥ 0 (default 0)	optional	Fixed annual O&M.
Genset Investment	`genset.unit_price`	currency/kW	≥ 0 (default 0)	optional	Set > 0 only if treating genset as new CAPEX.
CO₂ Emission Factor	`genset.carbon_dioxide_emission_factor`	kg/kWh	0 – 2 (default 0.5)	optional	Used for lifecycle CO₂ reporting.

4.4 Running an Optimization

Validate all sections; fix red-highlighted errors.
Click Start Simulation to begin the optimization.
A progress panel will appear displaying:
- Current stage (Initialization → Design Optimization → Operation Simulation → Finance Calculation)
- Progress percentage
- Elapsed time
Tip: If you accidentally close the progress panel, you can reopen it by clicking the Check Job Status button in the bottom-left corner of the page. This allows you to monitor your running jobs and view their real-time progress at any time.
If interrupted (browser closed, network issue), return to the page and click Check Job Status to view or resume your job. Completed calculations are preserved.

4.5 Results & Reporting

Solution Summary: optimized capacities, library selection (if applicable).
Metrics: economic KPIs (NPV, IRR, payback), reliability.
Financial Table: yearly cash flows, O&M, salvage.
Operation Plan: policy over project life, capacity decay.
Visualization: charts and scene components.
Export: cash flows table, operation plan, formatted design report (coming soon).

4.6 Results Field Reference

4.6.1 Economic Metrics

Field	Unit	Description
CAPEX	currency	Total upfront capital expenditure (equipment + construction + land if included).
AT-NPV	currency	Net Present Value of project cash flows after income tax.
BT-NPV	currency	Net Present Value before income tax.
AT-IRR	%	IRR of project cash flows after income tax.
BT-IRR	%	IRR before income tax.
AT-Equity IRR	%	IRR of equity cash flows (after debt service) after tax.
BT-Equity IRR	%	Equity IRR before tax.
AT-Payback Period	years	Years until cumulative after-tax cash flow turns positive.
BT-Payback Period	years	Years until cumulative before-tax cash flow turns positive.
PV-BESS LCOE	currency/kWh	Levelized cost of renewable (PV + BESS) generation only.
Project LCOE	currency/kWh	Levelized cost of all electricity delivered by the project.
CO2 Reduction	t CO₂	Lifetime CO₂ avoided versus the baseline supply (grid + genset).

4.6.2 Cashflow Items

Field	Description
Project Investment	Total project investment (same as CAPEX).
Battery Replacement Capacity	Capacity installed as end-of-life replacement.
Battery Augmentation Capacity	Capacity added to counter degradation (top-up).
Annual Revenue (with VAT)	Gross annual revenue including VAT.
Annual Power Supply Revenue	Revenue from electricity sold to end users.
Annual PV Feed-in Revenue	Revenue from exporting PV energy to the grid.
Annual Grid Charge Cost	Cost of grid energy used to charge storage.
Annual Energy Supply Revenue	Energy-charge portion of revenue (ex-demand charge).
Annual Demand Revenue	Demand-charge avoidance or revenue.
Annual System Charge Cost	Cost of energy used to charge the BESS.
Annual System Charge Cost (by grid)	Charge cost attributed to grid.
Annual System Charge Cost (by genset)	Charge cost attributed to genset.
Annual System Discharge Revenue	Revenue from BESS discharge.
Annual System Discharge to Load Revenue	BESS discharge used to supply load.
Annual System Discharge to EV Revenue	BESS discharge used to supply EVs.
Annual Insufficient Supply Penalty	Penalty for PPA shortfall (aggregated).
Annual Insufficient Supply Penalty (load)	Shortfall penalty attributed to load.
Annual Insufficient Supply Penalty (EV)	Shortfall penalty attributed to EVs.
Salvage Value	Residual asset value recovered in the final year.
Annual Revenue (without VAT)	Net-of-VAT revenue.
Annual VAT Payable	VAT owed after netting input and output.
Annual Output VAT	VAT collected on revenue.
Annual Input VAT	VAT paid on equipment and services.
Annual Business Tax	Business tax and surcharges.
Annual Surtax	Urban maintenance and education surcharges on VAT.
Annual Stamp Duty and Fund	Stamp duty and water conservancy fund on revenue.
Operating Profit	Revenue minus operating cost and depreciation.
Annual Operating Revenue	Accounting operating revenue.
Annual Operating Cost	Accounting operating cost (incl. depreciation and interest).
Annual Interest Expense	Interest paid on outstanding loan principal.
Annual Income Tax Payable	Income tax for the year.
Annual Income Tax Payable (Before Benefits)	Income tax before any tax incentives.
Net Profit	After-tax profit.
Annual Cash Inflow	Total cash received in the year.
Annual Cash Outflow	Total cash paid in the year.
Capital Expenditure	CAPEX paid in the year (non-zero in construction/replacement years).
Annual Net Cashflow	Inflow minus outflow.
Annual Repayment Amount	Total debt service (principal + interest).
Annual Depreciation	Asset depreciation for the year.
Annual Total Cost	All accounting costs for the year.
Annual Repayment of Interest	Interest portion of the debt service.
Loan Amount	Principal drawn.
Annual Remaining Principal	Principal outstanding at year-end.
Annual Repayment of Principal	Principal portion of the debt service.
Annual Operating Cost (exclude Depreciation and Interest)	Cash operating cost.
Annual Insurance Cost	Annual insurance premium.
Annual O&M Cost	Annual O&M cost across all components.
Net Cash Flow (Before Income Tax)	Project net cash flow before income tax.
Cumulative Net Cash Flow (Before Income Tax)	Cumulative before-tax project net cash flow.
Net Cash Flow (After Income Tax)	Project net cash flow after income tax.
Cumulative Net Cash Flow (After Income Tax)	Cumulative after-tax project net cash flow.
Net Equity Cash Flow (Before Income Tax)	Equity cash flow before income tax.
Net Equity Cash Flow (After Income Tax)	Equity cash flow after income tax.

4.6.3 Net Present Cost (self-invest mode)

Field	Description
Net Present Cost	Total discounted lifecycle cost (self-invest objective).
Project Net Present Cost	NPC including the whole project boundary.
PV-BESS System Net Present Cost	NPC attributable to PV + BESS only.
Present Value of Capital Expenditure	Discounted CAPEX.
Present Value of Equipment Investment	Discounted equipment CAPEX.
Present Value of Loan Interest	Discounted interest expense.
Present Value of Operating Cost	Discounted operating cost.
Present Value of Annual Operating Cost	Discounted yearly operating cost.
Present Value of Depreciation Tax Shield	Discounted tax benefit of depreciation.
Present Value of Annual Salvage	Discounted salvage value.
Present Value of Salvage	Same as above (aggregate).
Present Value of System Discharge Volume	Discounted BESS discharge volume used in LCOE.
Present Value of RE Supply	Discounted renewable energy supplied.
Present Value of System Supply	Discounted total energy supplied by the project.
Present Value of Grid Charging	Discounted grid charging cost.
Present Value of Genset Fuel	Discounted genset fuel cost.
Investment	Total project investment (CAPEX).
RE Investment	CAPEX attributable to PV + BESS.
RE Supply	Annual energy supplied by PV + BESS.
System Supply	Annual total energy supplied by the project.
Theoretical PV Generation	Theoretical PV output without curtailment.
PV Drop	Curtailed PV energy.
PV Curtailment Ratio	Curtailed PV / Theoretical PV.

4.6.4 Operation Plan Columns

Time-series columns in the exported operation plan CSV. The row interval follows the selected Time Resolution.

Column	Unit	Description
`purchase_price_per_kwh`	currency/kWh	Grid purchase price for the current simulation step.
`grid_sell`	kW	Power exported to the grid.
`grid_buy`	kW	Power imported from the grid.
`genset`	kW	Genset output power.
`total_load`	kW	Total electrical load to be served.
`ev_charge`	kW	Total EV charging power.
`pv_used`	kW	PV output actually used (after curtailment).
`batt_disc`	kW	BESS discharge power.
`batt_char`	kW	BESS charge power.
`batt_soe`	kWh	BESS state-of-energy.
`batt_soc`	%	BESS state-of-charge.
`pv_max`	kW	Theoretical PV output without curtailment.
`pv_drop`	kW	Curtailed PV power.
`grid_2_batt`	kW	Grid power used to charge BESS.
`system_supply`	kW	Total power supplied by the project.
`re_supply`	kW	Renewable power supplied (PV + BESS discharge to load).
`fuel_consumed_liters`	L	Genset fuel consumption.
`total_consumption`	kW	Total consumption (load + EV).

4.6.5 Equipment and System Labels

Key	EN
`PV System`	PV System
`BESS`	BESS
`Genset`	Genset
`Grid Connection`	Grid Connection
`Load`	Load
`Factory Load`	Factory Load
`PV_SYSTEM`	PV System
`STORAGE_SYSTEM`	Storage System
`GENSET_SYSTEM`	Genset System
`CHARGING_SYSTEM`	Charging System
`LOAD_SYSTEM`	Load System
`TOTAL_CAPACITY`	Total Capacity
`PV`	PV
`BATTERY`	Batt
`GENSET`	Genset

5. Examples

Ecosizing ships several end-to-end configurations under examples/. Use them as starting points for new projects by importing the JSON via the Import Config button.

5.1 Minimal demo

Config: examples/demo-pv-battery-genset.json
Runnable example for the pv-battery-genset scenario.

5.2 Typical parameter seed values

When a project has not yet been surveyed, these seeds are a reasonable starting point for the optimizer:

finance.project_life = 25, finance.discount_rate = 8, finance.construction_rate = 10, finance.insurance_rate = 0.25, finance.salvage_ratio = 5.
pv.decay_rate = [2, 0.5], pv.calendar_life = 30, pv.operation_and_maintenance_cost ≈ 0.04 (USD/kW/yr) or 0.3 (CNY/kW/yr).
battery.calendar_life = 20, battery.cycle_life = 8000, battery.eta_charge = battery.eta_discharge = 95, battery.soh = 95, battery.pcs_capacity_margin = 20.
genset.production_cost_per_kwh = diesel price (currency/L) × consumption (L/kWh), typically 0.20 – 0.35 USD/kWh for remote sites.

6. Data Analysis

The PPA Pricing Analysis tool helps you find the break-even PPA price or evaluate the profitability of a given PPA price.

Navigate to the Results page.
Click the PPA Pricing Analysis tab.
Select the PPA price mode (fixed, step, or tou) and enter the relevant price parameters.
Click Calculate to compute the financial metrics (NPV, IRR, payback period) at the specified PPA price.
Use this tool iteratively to find the minimum PPA price that achieves your target IRR.

7. Troubleshooting & FAQs

7.1 Validation and data format

Ensure required fields are set when a component included is true.
Time-series must be numeric and non-empty.
In Operation Mode, Number of Units must be specified for all equipment.
Check CSV headers and units; match templates under public/templates/.
purchase_price_per_kwh keys must be sequential integers starting from 0.
Time-series arrays must match Time Resolution: 8760/8784 values for 60-minute steps, 17520/17568 for 30-minute steps, or 35040/35136 for 15-minute steps. Grid-related fields (purchase price, grid connect schedule, TOU demand schedule) additionally accept coarser granularity (e.g. hourly for a 15‑min sim) and are auto-expanded.

7.2 Common issues

"Supply hours not met" warning: reduce required supply hours, add genset capacity, or increase battery/PV size.
Job stuck at "Design Optimization": check for infeasible constraints (e.g., capital budget too low, supply hours too high for given components).
Inverter/PV consistency error: PV and inverter must be included together, or excluded together.
Feed-in tariff missing: set grid.feed_in_tariff_per_kwh whenever grid.max_export_capacity_kw > 0.
Time-series validation errors: ensure all arrays have the correct length for Time Resolution (60 min: 8760/8784; 30 min: 17520/17568; 15 min: 35040/35136). Grid fields (purchase price, grid connect schedule, TOU demand) also accept coarser lengths that are multiples of the hourly count. Check for non-numeric characters, empty cells, or incorrect column formats.
"Maximum PV capacity too low" — the optimizer cannot place enough PV to meet load requirements. Increase pv.capacity_max_kw or leave it empty for no limit.
"Battery capacity insufficient for grid-forming" — in off-grid scenarios, the PCS capacity must be large enough to handle peak load plus PV/BESS ratio constraints. Increase battery PCS capacity or relax battery.pv_2_batt_ratio_max.
Loan period exceeds project life — finance.loan.loan_period must be ≤ finance.project_life.
SOH + augmentation threshold mismatch — when Consider Capacity Augmentation is enabled, the Capacity Augmentation Threshold should typically match or be close to the initial State of Health (SOH) value.

7.3 How to judge which scenario to use

Use this quick decision guide:

Question	Answer → Scenario
Is there a grid connection?	No → off-grid scenarios. Yes → grid-connected scenarios.
Off-grid with diesel backup?	Yes → `pv-battery-genset`.
Off-grid with flat constant-power supply?	Yes → `pv-battery-constant-power`.
Grid-connected, no PV needed (pure arbitrage / peak-shaving)?	Yes → `battery-grid`.
Grid-connected PV + storage for C&I self-consumption?	Yes → `pv-battery-grid`.

Typical keyword-to-scenario cues:

"mining", "mine site", "remote", "diesel", "island", "no grid" → pv-battery-genset (or pv-battery-constant-power if load is very flat).
"C&I", "factory", "commercial", "peak-valley arbitrage", "demand charge", "feed-in" → pv-battery-grid.
"storage only", "arbitrage", "no PV" → battery-grid.

7.4 Missing-materials checklist (minimum inputs before running)

Any project:

Selected scenario.
Location: longitude, latitude, altitude.
At least one load grade with load_ts matching Time Resolution.
Finance basics: project_life, discount_rate, invest_mode.

Add per scenario:

battery-grid: battery lib, grid.purchase_price_per_kwh, grid.max_import_capacity_kw.
pv-battery-constant-power: PV lib + pv_unit_ts, inverter lib, battery lib, grade-3 operating_rate and constant_power_hours.
pv-battery-grid: PV lib + pv_unit_ts, inverter lib, battery lib, grid.purchase_price_per_kwh, feed-in tariff if exporting, demand settings if applicable.
pv-battery-genset: PV lib + pv_unit_ts, inverter lib, battery lib, genset fuel_type + production_cost_per_kwh + genset_capacity, supply_hours_per_year.

8. Glossary

BESS: Battery Energy Storage System. The combined battery + power conversion system.
BMS: Battery Management System. Electronics that monitor and protect individual battery cells/modules.
Calendar Life: The physical service life (years) of equipment before it must be replaced, independent of usage cycles. Distinct from cycle life (wear from charge/discharge). PV panels, inverters, chargers, and batteries each have their own calendar life.
CAPEX: Capital Expenditure. Upfront investment cost for equipment and construction.
C-Rate: Charge/discharge rate expressed as a multiple of battery capacity. A 0.5C rate on a 100 kWh battery means 50 kW charge or discharge power.
Curtailment: Intentional reduction of PV output when the system cannot absorb or export the energy.
C&I: Commercial & Industrial. A customer segment characterized by medium-to-large loads and regular business-hour operation.
Cycle Life: Number of full equivalent charge-discharge cycles before the battery reaches end-of-life. A battery with 8000 cycle life and one full cycle per day would last ~22 years from cycling alone (calendar life may limit it sooner).
Equity IRR: IRR calculated on equity cash flows only (after accounting for debt service), reflecting the return to the project owner's equity investment.
Genset: Generator set (typically diesel). Dispatchable thermal backup with fuel cost + O&M.
GFM (Grid-Forming): A control mode where the inverter/PCS actively establishes voltage and frequency references, enabling off-grid or islanded operation without an external grid reference. Contrast with GFL (Grid-Following).
GFL (Grid-Following): A control mode where the inverter/PCS synchronizes to an existing grid voltage and frequency. Used in grid-connected systems where the utility provides the reference.
IRR: Internal Rate of Return. The discount rate that makes NPV = 0. A higher IRR indicates a more profitable investment.
LCOE: Levelized Cost of Energy (currency/kWh). Total lifecycle cost divided by total lifetime energy produced. Lower LCOE = cheaper electricity.
LP / MILP: Linear Programming / Mixed-Integer Linear Programming. Mathematical optimization frameworks. MILP can handle discrete decisions (e.g., integer number of battery units) alongside continuous variables.
NPC: Net Present Cost. The sum of all discounted lifecycle costs; used in self-invest mode where minimizing cost is the objective.
NPV: Net Present Value. The sum of discounted future cash flows minus the initial investment. Positive NPV means the project creates value.
OPEX: Operating Expenditure. Ongoing annual costs (O&M, insurance, fuel, etc.).
O&M: Operation and Maintenance cost (annual recurring cost per unit of installed capacity).
PCS: Power Conversion System. The bidirectional inverter/converter that interfaces the battery DC bus with the AC grid or load.
PCS Capacity Reserve: The fraction of PCS rated power reserved as headroom (not used for normal dispatch). Prevents continuous 100%-load operation, preserves equipment life, and provides buffer for transient events. Especially important in grid-forming / off-grid scenarios. E.g., 20% margin on a 10 MW PCS means 8 MW usable, 2 MW reserve.
PPA: Power Purchase Agreement. A contract under which the project owner sells electricity to an off-taker at an agreed tariff (the PPA Price).
PV: Photovoltaic (solar). Panels that convert sunlight directly into DC electricity.
SOC: State Of Charge (%). The instantaneous energy level of the battery expressed as a fraction of nameplate capacity.
SOH: State Of Health (%). Remaining battery capacity relative to its original (new) capacity. Degrades with cycles and calendar age.
STS (Static Transfer Switch): A power-electronic switch (also called on/off-grid cabinet) that enables seamless, sub-cycle transfer between grid-connected and islanded modes. Essential for projects requiring grid-forming, weak-grid support, or fast islanding during grid disturbances. See Section 4.3.3 → Grid.
TOU: Time-Of-Use. A tariff structure where electricity prices vary by hour/season (e.g., peak / flat / valley periods).