Plant Design

A plant design ties the spatial layout of a solar and battery plant to its electrical topology so the physics is calculated on what is actually drawn. It is served by the maintained /v2 API, the plant designer in the web app, the Daly CLI and SDK, and Bubba’s tools. The original API is unchanged.

Objects

Object	Where it lives	What it holds
Layout data file (`layoutVersion: "2"`)	Object storage, referenced by a layout	Tables, equipment placements and cable routes in local metres around a geographic origin, plus the site boundary, exclusions and buildable area
`PlantDesign` (`schemaVersion: "plant-design-1"`)	`metadata.design` of a layout	The equipment catalog (modules, inverters, transformers, conductors, batteries, converters, DC combiners), how the strings are made up, and the electrical topology: buses, cables, transformers, inverters, converters, batteries, loads, shunts, combiners and the grid connection
`PlantSimulationInput` (`contractVersion: "plant-1"`)	A request body	A design (inline or `{ "layoutId": … }`) paired with a study: time axis, dispatch, prices and options

Cable lengths are the physics. Every cable carries lengthM and a lengthSource of measured (taken from its route on the drawing) or declared. A cable’s impedance is the conductor’s per-kilometre values times the measured length divided by its parallel circuits, and that is what the hybrid executor receives.

Start with what you know

Use an existing project as the identity of the plant, including an operating plant. A design describes its equipment and electrical connections. A study describes one operating scenario. A layout adds positions and measured routes when a drawing is available. An equipment type is a reusable specification; an installed unit has its own id and connection. The catalog’s converters are battery power conversion systems (PCS). Each inverter can override the design’s default strings configuration, which supports mixed equipment and repowered blocks. For an existing site, enter the as-built design directly. You can run standalone storage or supply PV power without a boundary, drawing or weather file. Importing table polygons is useful for planning a network around them; it does not recover the site’s existing electrical connections. Put changing conditions in study.pv[inverterId] and study.batteries[batteryId]. Battery conditions include initialEnergyMwh, initialSohFraction, initialAgeHours, temperatureC, available and connected. This lets the same physical design represent a new battery, an aged battery or an outage scenario. Existing unit-level values remain accepted as defaults. Initial age is explicit, not inferred from a commissioning date.

Workflow

Site. Draw the parcel on the map, import GeoJSON, KML, WKT or a coordinate list, or start from a project’s stored boundary. Add exclusions, site features (roads, fences and drainage lines with a corridor width; wetland, floodplain, laydown and easement footprints), a setback and, optionally, the point of interconnection. An existing plant’s tables can be imported instead (GeoJSON, KML or DXF) through POST /v2/layouts/import.
Array. Choose a shed preset or set mounting, module orientation, modules high, strings per table and modules per string; a module and an inverter from the workspace library (or the engine defaults); GCR, azimuth, DC/AC ratio, collection voltage and battery storage; the electrical arrangement (auto, typical blocks on access corridors, or a serpentine fill; tables per corridor side, corridor width, strings per combiner and the objective the planner optimises); a collector substation with a main power transformer and an HV gen-tie to a placed utility point of interconnection; and the design rules the checks judge against. Compare alternatives evaluates every arrangement (POST /v2/layouts/plan) without touching the drawing: capacity, blocks and inverter fill, combiners, cable and road metres, DC loss, the worst DC drop and a cost index per kW, with the one the objective would build marked; Use this builds any of them.
Generate. POST /v2/layouts/generate fills the buildable area with rows of tables, lays access corridors across the rows, forms blocks of whole rows on each corridor with the inverter station beside it, groups strings into DC combiners at the row ends, sizes every feeder for its current and the DC drop budget, routes DC strings and feeders and MV feeders to the point of interconnection and measures every run. The response carries the drawing (layoutData), the design, a summary, rated-flow diagnostics, the design checks, the alternatives considered and the rationale for the one built.
Draft. Add, move, rotate, copy or delete individual tables and rows, and reassign selected tables to an inverter. Move equipment or place transformers, substations, junctions, inverters, PCS units, batteries and DC combiners; add capacitor or reactor banks to their buses. Draw or redraw cable runs (snapped to the rows when you ask), edit vertices, and measure lengths and areas. Undo and redo cover drawing and equipment edits, boundaries, site features and generation parameters. The design is re-measured as you draw, losses update, and the one-line diagram follows.
Check and save. POST /v2/plant-designs/validate validates the design and returns cable and transformer losses at rating plus the design checks; POST /v2/plant-designs/review does the same for a saved layout on its drawing. Saving writes a new layout version; earlier versions can be compared and restored, and a variant is saved as a copy that records its origin. POST /v2/layouts/{id}/design re-measures the stored design on the stored drawing. Export the cable schedule and bill of quantities as CSV, and the drawing as GeoJSON, KML, DXF or a PNG.
Run. The designer first calls POST /v2/plant-designs/prepare-study to recount the edited drawing, measure routes and rebuild solar blocks. It uses the returned design and pv mapping in a plant-1 request to POST /v2/energymodels?calculationEngine=hybrid. The service translates it deterministically into hybrid-1, so results carry the hybrid-result-1 ledger and open on the hybrid results page; a finished run’s blocks colour the map by specific yield. A variant sweep generates and runs one parameter over a list of values and opens the runs in Compare.
Life of plant. Still in the Study step, project the design over its project life: every battery unit ages on its own clock from the year it enters service, tranches enter in their years, and the strategies (the plant as designed, a given schedule, a solved plan that holds a target with a year-0 overbuild to compare, or a retrofit timing sweep) are tabled and charted with their findings and, when priced, their economics. This calls POST /v2/plant-designs/life-study and queues nothing.

From the CLI

These commands use the versioned API. Configure the base URL in your CLI profile or set it for the current shell:

export DALY_API_BASE_URL=https://api.dalyenergy.com/v2

daly layouts plan request.json --objective cost
daly layouts generate request.json --save
daly layouts import tables.json --save --name "Existing plant"
daly layouts design 12 --save
daly layouts versions 12
daly layouts data-url 12 --version 2
daly plant-designs validate design.json
daly plant-designs review --layout-id 12 --summary-only
daly plant-designs equipment get
daly plant-designs equipment put library.json
daly plant-designs life-study life.json --mode hold_target --summary-only
daly plant-designs simulate study.json --wait

request.json is a LayoutGenerateRequest (a site with a boundary, optional exclusions and features, optional array, inverter, electrical (strategy, tables per corridor side, corridor width, objective, combiner type, or a strategyId from a plan), collection, storage, grid with interconnection, rules and pvContext). daly layouts plan prints the alternatives with their metrics and the id the objective would build. tables.json is a LayoutImportRequest whose source carries tablesGeojson, localTables with an origin, or a scene. study.json is a plant-1 request whose design may be { "layoutId": 12 }. life.json is a life-of-plant request (design, life, augmentation, optional operation, batteries and economics); --summary-only drops the per-year rows. library.json is an equipment catalog (conductors, transformers, batteries, converters, each with an optional unitCost).

From the SDK

from dalysdk import DalyClient

client = DalyClient(workspace_api_key=..., user_api_key=..., base_url="https://api.dalyenergy.com/v2")
plan = client.layouts.plan({"site": {"boundary": parcel, "setbackM": 15}, "electrical": {"objective": "balanced"}})
for alternative in plan["alternatives"]:
    print(alternative["id"], alternative["metrics"]["dcKw"], alternative["metrics"]["costIndexPerKw"])
result = client.layouts.generate({"name": "Sunset Ridge", "site": {"boundary": parcel, "setbackM": 15}, "electrical": {"strategyId": plan["chosenId"]}, "storage": {"energyMwh": 40, "powerMw": 10}, "grid": {"interconnection": {"hvKv": 138}}, "save": True})
review = client.plant_designs.review(layout_id=result["layoutId"])
for finding in review["checks"]:
    print(finding["severity"], finding["code"], finding["message"])
report = client.layouts.build_design(result["layoutId"])
history = client.layouts.versions(result["layoutId"])
library = client.plant_designs.equipment()
prepared = client.plant_designs.prepare_study({"design": {"layoutId": result["layoutId"]}})
study.update({"pv": prepared["pv"], "solarInput": prepared.get("solarInput")})
accepted = client.plant_designs.simulate({"contractVersion": "plant-1", "design": prepared["design"], "study": study})
life = client.plant_designs.life_study({
    "design": {"layoutId": result["layoutId"]},
    "life": {"startYear": 2027, "years": 25},
    "augmentation": {"mode": "hold_target", "target": {"kind": "usable_energy_mwh", "value": 36}},
    "economics": {"discountRate": 0.08, "batteryCostPerKwh": 240},
})
for strategy in life["strategies"]:
    print(strategy["id"], [(t["calendarYear"], t["units"]) for t in strategy["tranches"]], strategy["economics"]["npv"])
print(life["recommendedId"], life["rationale"])

client.layouts.import_tables(...) designs an existing plant from its table polygons, and client.plant_designs.put_equipment(...) stores shared equipment types for the workspace.

A `plant-1` request

{
  "contractVersion": "plant-1",
  "name": "Sunset Ridge · June",
  "design": { "layoutId": 12, "layoutVersion": 3 },
  "study": {
    "time": { "timestamps": ["2026-06-01T00:00:00Z", "2026-06-01T01:00:00Z"], "durationSeconds": 3600 },
    "dispatch": { "method": "surplus", "chargeSource": "curtailed_pv_only" },
    "options": { "preset": "fast", "outputDetail": "plant", "dataQuality": "screening_assumption" }
  }
}

Add top-level projectId to associate the run with its plant, including when no solar input is present. The project must belong to the current workspace. The saved model expands a layout reference into the actual design snapshot, including its layout id, version and hash. Later layout edits do not change that saved input. The hybrid-1 translation remains its normalised input and outputs use the existing hybrid results format. prepare-study is read-only and accepts an inline design or a layout reference, an optional edited drawing, a solarInput assumption template, and supplied pv availability. It returns the prepared design, solar input, PV mapping and notes. Native PV requires workspace module and inverter records and location or weather context. It rejects unsupported mixed orientations within one inverter block. It preserves the drawing and gives empty blocks zero DC availability. For an operating battery, a study override can be as small as:

{
  "batteries": {
    "battery-1": {
      "initialSohFraction": 0.85,
      "initialAgeHours": 17520,
      "initialEnergyMwh": 1.7
    }
  }
}

The key must identify an installed battery. Energy and power use MWh and MW; state of health is a fraction of nameplate capacity. Without explicit starting energy, the model uses the midpoint of the allowed SOC range at that reduced capacity. See the generated API schema for all physical and study fields.

Editing a layout

The map editor also supports adding, moving, rotating and copying tables or rows, and assigning selected tables to compatible inverters and combiners. Battery and combiner placement requires an explicit electrical connection. A newly installed combiner can have zero strings until tables are assigned to it. Undo and redo cover the site, feature geometry, generator and study settings, and the physical drawing. Save preserves the edited design; regeneration is a separate action. Weather-driven study preparation requires consistent orientation and regular row spacing within each inverter. Unsupported drawings can still be saved and exported.

Diagnostics and checks

The editor checks the current unsaved drawing, including edited site features. API clients can submit design and drawing together to POST /v2/plant-designs/review without saving a layout first. Validation and generation return rated-flow diagnostics for radial networks: each cable’s current, loading and I²R loss with every source at its rating, each transformer’s loading and copper loss, total cable length by kind and the collection loss fraction at rating. Meshed networks are validated for connectivity and left to the power flow. The DC side is reported too: for every combiner the current and continuous current at STC, the feeder’s loading against its ampacity, the drop from the farthest string through the feeder to the inverter, and the ohmic loss, with totals and the worst combiner. They also return the design checks: string open-circuit voltage at the coldest ambient against the module and inverter limits, MPPT voltage at the hottest cell, DC/AC ratio, strings and current per MPPT input, combiner inputs, string fuses against the module’s short-circuit current and its maximum series fuse, combiner output and DC feeder ampacity at continuous current, DC voltage drop against the DC drop rule, transformer loading, conductor ampacity after derating, feeder voltage drop to the point of interconnection and declared (unmeasured) lengths. Each finding has a severity, a code, a message and the element it concerns. The limits come from the design’s rules and the checks are advisory: a design with findings still validates and runs.

Life of plant and augmentation

A design’s batteries do not stay the size they were built. POST /v2/plant-designs/life-study projects a design over its project life, year by year, without running the hourly executor: a base-year operating profile (cycles per year of usable energy, or a plant discharge demand shared across the units) is repeated every year, every battery unit ages on its own clock with the same retention law the hybrid engine uses (a calendar fraction per year of service and a capacity fraction per MWh discharged, floored at a minimum, with power ratings untouched), PV degrades at its rate, and each tranche enters service in its year with a converter and a transformer path checked. The year a battery is added can be any year from 0 to the last, and there are three ways to set it:

A schedule you give. augmentation.tranches, each a year, a number of units of a battery type, and where it connects (an existing PCS by converterId, a new one by converterTypeId and acBusId, or the PCS with the most spare rating).
Solved to hold a target. augmentation.mode: "hold_target" with a target (usable energy in MWh, usable power in MW, or a fraction of the year-0 usable energy). At the first year the target is short, the solver adds the smallest tranche that holds it until the next allowed year, and compares the result with the smallest overbuild at year 0 that would have held it throughout.
Retrofit timing. augmentation.mode: "retrofit_sweep": PV first, storage entering in year k, swept over k.

Every strategy returns its tranches, per-year and per-unit curves (usable energy and power, state of health, throughput, shortfall), findings such as an overloaded PCS or a transformer above its rating with every source at rating, and, when economics are given, cash flows with each tranche’s capital in its own year from a battery cost that declines yearly, NPV, IRR, LCOE and LCOS. Capital and investment credits occur at the start of the service year; operating flows and energy occur at year end. Discounted metrics use that timing. If no merchant price is supplied, the escalated PPA price continues. The projection is bounded to 200 battery units, 1,000 converters and 100,000 returned unit-years across strategies. Oversized requests are rejected, and the bounded calculation pool returns a retryable error when occupied. These are annual screening economics: battery discharge is before conversion and network losses, charging procurement is excluded, and the combined PV plus storage LCOE denominator can count PV charging energy twice. The UI saves the assumptions with layout versions; projection results themselves are not saved. recommendedId and rationale name the choice. In the designer the Study step tables and charts the strategies; from the CLI daly plant-designs life-study, from the SDK client.plant_designs.life_study, and Bubba’s study_plant_life tool lets the agent read the tranche years and the economics and recommend one.

{
  "design": {"layoutId": 12},
  "life": {"startYear": 2027, "years": 25, "pvDegradationPerYear": 0.005},
  "operation": {"throughputBasis": "cycles", "cyclesPerYear": 300},
  "augmentation": {
    "mode": "hold_target",
    "target": {"kind": "initial_usable_fraction", "value": 0.9},
    "firstYear": 1,
    "minYearsBetween": 2
  },
  "economics": {"discountRate": 0.08, "storageValuePerMwh": 60, "batteryCostPerKwh": 250, "batteryCostDeclinePerYear": 0.05}
}

Electrical arrangement

The planner arranges a plant the way a utility-scale design does. Access corridors cross the rows at a regular spacing (two tables on each side by default); an existing road across the rows is used as one. Each block is a run of whole rows on one corridor, with its inverter station (inverter and MV transformer on a pad) beside the corridor at the block’s middle. DC combiners sit at the row ends on each side of the corridor, each collecting a group of adjacent rows up to its inputs; string runs follow their row to the corridor, feeders run along the corridor to the station, MV feeders follow the corridor to the next station or the collector. Feeders are sized per combiner from the DC conductor ladder for continuous current and the DC drop budget; string fuses follow the module’s short-circuit current. Every arrangement the parcel allows (corridor depths, and a serpentine fill that models no roads) is built and scored so the choice is explicit: the objective picks the lowest cost index within a small share of the most capacity, the lowest cost, or the most capacity; a person or an agent can pick otherwise with electrical.strategyId.

Substations, gen-ties and reactive compensation

grid.interconnection adds a collector substation at the plant’s point of interconnection (an MV collector bus, a main power transformer sized to the plant unless given, an HV bus) and an overhead gen-tie to the utility point of interconnection at the transmission voltage. Fixed capacitor or reactor banks on any bus are part of the design (electrical.shunts) and are simulated as constant reactive loads. Transformer tap settings are not part of the model: the hybrid engine’s transformers carry ratings and impedances but no winding voltages, so a tap has nothing to act on.

​Plant Design

​Objects

​Start with what you know

​Workflow

​From the CLI

​From the SDK

​A plant-1 request

​Editing a layout

​Diagnostics and checks

​Life of plant and augmentation

​Electrical arrangement

​Substations, gen-ties and reactive compensation