Skip to main content

​
Solar Template Preparation

Use this flow to run a saved solar template through the native v2 solar and hybrid executor. It is separate from the retained standard solar quick-run API. Preparation resolves the template’s workspace resources and returns a complete solar-only hybrid-1 request. It does not run the physics, create a saved model or queue a task.

​
Import, prepare and run

  1. Upload supported source project, variant, weather and equipment files through the project’s import UI, backed by POST /v2/projects/import. Review the imported template and warnings before running it. A source variant can contain calculated result sections; those sections are not modeling inputs.
  2. Call POST /v2/plant-designs/prepare-solar-study with the saved template under solarInput. Supply exactly one location source: projectId, locationId or inline location. The authenticated workspace must own the referenced weather, equipment and other resources.
  3. Review the returned warnings and provenance, including networkModel, weatherDateUtcOffsetHours and isAsBuiltTopology: false. The same warnings become assumptions in the returned simulation.
  4. Submit only the returned simulation, unchanged, to POST /v2/energymodels?calculationEngine=hybrid. Poll the returned task and retrieve the saved run and results on the /v2 base.
The preparation response contains simulation, warnings and provenance. Its inputHash identifies the canonical solar input JSON, not immutable revisions of all referenced resources. Admission resolves those resources again; a prepared request is not a snapshot of a completed run.

​
Choose the electrical representation

The UI offers these modes explicitly. Collection-equivalent studies use dataQuality: "screening_assumption"; they do not calculate physical switching, islanding, bus voltage or component loading. Unsupported source controls fail with an actionable error. Do not remove a cap, auxiliary law or other source input merely to make preparation succeed. A cap at inverter output is a different boundary from a POI export limit. For actual cable routes, equipment ratings, electrical audits, full power flow or batteries, use a physical plant design. An imported geometry file does not automatically bind a shading scene to a solar template. nearShading: "unlimited" still represents unlimited rows; review the scene and string bindings before treating a run as spatially shaded.

​
Monthly power factor and availability

Collection policy solar-collection-equivalent-2 preserves source monthly powerFactor magnitudes in (0, 1]. The original local weather clock selects the month. Native inverter conversion retains that PF; positive-flow collection losses that depend on squared current scale by 1 / PF². All native blocks must use the same monthly profile and clock. A PF magnitude does not establish leading or lagging reactive power. Non-unity intervals return unavailable (null) signed POI Q; a run containing those intervals also has unavailable aggregate poi_reactive_mvarh. Separate inverter_reactive_magnitude_mvar collection metrics and inverter_reactive_magnitude_mvarh totals describe inverter-output magnitude, not solved reactive network flow. Unity-PF intervals retain zero signed Q. Source plant.availability.periods recur by local month, day and time. Collection mode accepts at most 1,000 periods, each no longer than 8,784 hours (366 days). Larger schedules fail admission before queuing; they are not truncated. Overlapping periods are merged and partial overlaps with centered source-weather intervals determine the lost fraction. February 29 starts recur only in leap years. The loss reduces positive final POI export after native conversion, inverter curtailment, collection losses and plant auxiliary demand. Upstream physics and negative/nighttime imports remain unchanged; this policy does not model equipment switching. Results expose pre_availability_export_mwh, plant_availability_loss_mwh and plant_availability_loss_fraction separately. These controls are supported only in the explicitly selected collection mode. The default reduced-network scope remains unchanged. Collection mode still rejects physical electrical audits, optimization/reactive targets, grouped MV chains, POI-side caps, auxiliary cap compensation and unsupported night policies.

​
Opt into whole-scene irradiance screening

When a template links a tracker scene but has no verified electrical table map, the API can prepare a declared whole-scene approximation with these options:
The defaults remain pvSceneShadingPolicy: "explicit_spatial" and pvBifacialRowPolicy: "source". An imported scene link does not enable these options automatically. source keeps a declared rear row count; scene_geometry supplies only a missing count and cannot replace source rows. Whole-scene screening requires a linked nearShading: "octavia" scene with explicit electricalImpact: false. Conventional tracker geometry and controls must agree across the scene and source block, including signed axis tilt, GCR, backtracking and rotation limits. Terrain-aware tracking, active wind stow, diffuse irradiance optimization, string maps, shading-profile identifiers and native spatial mappings are unsupported combinations. Preparation does not disable these settings to make a request pass. Preparation authenticates the original scene snapshot, completed task and exact result receipt. Every receiver must appear at every planned sun position. Its beam-shading grid averages optical losses by receiver area and applies that same mean to each native block linked to the scene. Ground-reflected shading uses the directional artifact bound to the same geometry. Sky diffuse and rear irradiance retain regular-row approximations. The policy does not infer wiring, per-inverter shading or electrical mismatch. The prepared source carries sceneScreening, an immutable content binding for the scene inputs, results, directional field, runtime layout and beam grid. Submission checks the authenticated resources again; stale or mismatched resources require fresh preparation. Worker checks preserve that identity. For missing rear rows, scene_geometry groups occupied tracker extents into transverse runs. It uses their collector-area-weighted mean edge fraction, sum(areaFraction / runRowCount), and its reciprocal as the effective row count. Disconnected runs and singleton portions remain included. The effective count may be fractional but must be at least two; the scene table total is never a row count. Incompatible orientation, chord, spacing or overlapping geometry fails explicitly. The source template, declared rows, GCR, pitch and actual tracker axis remain unchanged. This is an averaged finite-field irradiance approximation, not a reconstruction of separate field-level electrical calculations. The default bifacial model uses axis tilt 0° only inside its rear calculation. Tracking, backtracking and front transposition retain the actual signed axis tilt, and tracker rotation remains in use. See hybrid PV policies for the execution boundary and spatial alternatives.

​
Preserve weather and source losses

Weather labels represent interval centers. An explicit dateUtcOffsetHours declares a fixed local-standard offset; preparation subtracts it once, then half the weather step, to obtain UTC interval starts. sourceTimezone is descriptive provenance and does not supply a missing offset. All native blocks must resolve to the same regular UTC centers. See Data Quality and Limits for observation validation and the retained unmarked stored-calendar exception. Older imported weather whose source offset was discarded requires reimport from a verified source. The preparer does not infer that offset from longitude. Source solar-geometry corrections are distinct from timezone offsets: nonzero sourceTimeAdjustments.solarGeometryOffsetMinutes is unsupported. Already-applied label shifts are recorded without shifting the dates again. Older imported weather without correction metadata produces an unverified metadata warning; that warning does not establish equivalence to its source. Soiling is an irradiance loss. Supported direct source encodings are preserved:
  • A scalar SoilingLoss fraction from 0 to 1, with neither a monthly declaration nor an unknown soiling selector, applies in every month.
  • SoilingLossM supplies exactly twelve finite monthly fractions from 0 to 1.
  • SoilProfile supplies exactly twelve finite monthly percentages from 0 to 100.
Multiple declarations must agree in every month. Malformed profiles, conflicting values and unknown selectors fail before resources are saved; there is no fallback to zero or an averaged profile. Declared source string totals must also be positive integers with a supported exact per-inverter allocation. Unsupported distributions fail instead of being rounded down. Older saved imports may have omitted soiling or lost a source string total. Reimport supported source files, or supply a verified soiling override where appropriate, before making a same-input numerical comparison. Existing templates and completed runs are not automatically rewritten.

​
Compare a reference CSV in the browser

The import comparison UI runs the prepared Daly study, then compares its signed net POI energy with the reference E_Grid column. The reference CSV is read in the browser; it is not sent as weather, equipment, a model coefficient or a simulation input. This is separate from uploading the source project files. Specify the reference units, interval length, start/center/end label convention and fixed UTC offset. Energy columns may use Wh, kWh or MWh; power columns may use W, kW or MW and are integrated over the declared interval. The initial reference offset can come from imported or prepared weather metadata, but a user’s explicit selection is retained. Changing comparison settings does not change the Daly simulation inputs. Exact timestamp alignment compares UTC instants. Explicit calendar alignment compares matching local calendar intervals across reference years and rejects ambiguous multi-year matches. Both require complete matching coverage and interval durations; missing hours and leap-day differences cannot be ignored to produce a score. Full-calendar-year coverage is required for an annual label; other complete periods are reported as period energy. The comparison shows period and monthly energy bias, MAE and RMSE. These are diagnostics, not a certification, a predefined acceptance tolerance or proof that every upstream physical stage agrees. Check source preservation, clock alignment, shading assumptions and the electrical boundary alongside the numbers. A local-engine comparison also does not establish authenticated hosted API acceptance.