pvsyst_update_variant_parameters

[Projects & Variants] Edit existing validated parameters or display name with SHA guard and rollback backup. variant_name changes only one owning header Comment, not the VC identifier, filename, project or nested names. Requires printable single-line text of 1..80 UTF-8 bytes, no surrounding whitespace; bool/numeric values stop at SDK. Missing/duplicate/late root names stop rather than inventing a field. Returns name_change before/after. Existing preview/no-op/restore apply; display-only names need no shading remapping and may accompany ordinary scalar updates. Mode/sharing toggles stay separate. This is not file/variant-ID renaming. Non-ASCII names require an existing UTF-8 BOM or explicit add_utf8_bom=true; that option requires variant_name and changes decoding of the entire VC. bom_added is returned for name transactions, including a marker-only change with unchanged name/text diff. Existing BOM/newline style and formal recovery are retained; no implicit marker insertion or ANSI transcoding. Strict JSON booleans only, not strings/numbers. Raw inspected names do not prove correct native decoding of a BOM-less file. Ordinary non-name edits preserve encoding. dry_run returns a candidate hash/diff without writing. Subarray/orientation/ main-array dictionaries require strict numbers, not booleans or numeric strings. main_array_updates supports existing owning UFactor (constant Uc, W/m2/K) in adapter range [15,100]. Requires one Grid main array with Flags=$00100400, Flags2=$082A, all subarrays declared 8.1.0/8.1.6, no active geometry/layout. This changes the whole main array, not the selected subarray. Flags, wind terms, absorptance and efficiency fields are preserved; no fitting, inferred defaults or transient/wind model edits. Low-value behavior is unverified. Target subarray_id/orientation_id require strict JSON integers, not booleans, strings or floats; numeric dictionary values retain their separate rules. subarray_updates also supports existing root LIDLoss in percent [0,100], text 8.1.0/8.1.6 Grid subarrays without active geometry/layout. It does not infer module technology, change flags, recompute defaults or fit losses. Existing root PMismMPP in percent [0,100] is supported for declared 8.1.0/8.1.6 Grid subarrays without active geometry/layout and with one hexadecimal owning Flags. Setting PMismMPP also clears only default-mismatch bit 0x00040000 so the saved value is consumed; other flags/losses stay intact. Returns mismatch default_before/default_after. Restore the snapshot to recover default mode; this does not fit losses or recalculate the native default. ModuleQualityLoss is a semantic subarray_updates key in adapter percent range [-5,20], negative means gain. Requires verified declared 8.1.0/8.1.6 Grid, no active geometry/layout, unique existing owning PQualityModU/I and hexadecimal Flags. It synchronizes both U/I saved values and clears only quality default bit 0x00100000; PQualityModP, other flags/losses/fields remain unchanged. Raw U/I/P are read-only inspection fields, not independent quality setters. Returns module_quality default_before/default_after; restore recovers default mode. No native-default calculation, tolerance inference or model fitting; this bounded paired mapping is verified on an unshaded generic mono grid case. generator_updates supports text 8.1.0/8.1.6 SystemType=Battery: enabled (only system Flags bit 0x20), filename (existing GEN), operating_power_kw (>0), and thresholds mapping string subarray IDs to VBkUpEncl_syst/VBkUpDecl_syst values in [0,1]. These are native normalized voltage thresholds, not SOC. Missing generator fields can be added. Enabling requires a valid GEN, positive power and both thresholds in every subarray. Disabling preserves its saved configuration. Nominal power/fuel consumption remain component fields. NModSerie edits integer series-module count directly, preserving parallel strings, input grouping and mode. Native model derives module count/operating voltage; hardware voltage/current sizing, shading remapping and loss fitting are not performed. Series edits, angle edits and structural/count/mode edits stop before writes for active scenes/tables or any module-layout block; cached module/string mapping is not remapped. Angle edits additionally require a flat non-averaged FixedPlane, explicit Flags=$00 if present, and absent/unique False UsesTiltAver/UsesAzimAver/UsesSlopeAver. Legacy angle scalars may omit Flags; topology edits still require explicit Flags=$00. subarray_updates NInverter (integer 1..10000) scales ordinary grid inverter groups; NStringCh (positive 32-bit integer) proportionally scales parallel StringNode counts. They may be combined. NInverter alone preserves strings per inverter; NStringCh alone preserves inverter count. All group/leaf allocations must remain integral; declarations and NElements are synchronized together. Requires consistent unshaded fixed-plane counts, NInvMPPT=1 without the independent $0400 subarray flag, no shared power and no explicit MPPT branches. NInvMPPT (integer 1..10000) separately scales existing explicit MPPT groups for verified Version=8.1.0/8.1.6 independent $0400 subarrays with PowerSharingInverterId=-1 and complete exclusive allocation. It preserves inverter/leaf counts and mode, synchronizes total input/string declarations, and requires integral groups and explicit edited NElements. NInverter alone also scales verified Version=8.1.0/8.1.6 independent exclusive inverter groups, synchronizing NInverter, total NInvMPPT and strings while preserving MPPT/leaf multiplicities and mode. Changed inverter NElements must be explicit; all resulting group/input/string counts must be integral. Do not combine this independent-mode operation with NInvMPPT/NStringCh; shared parents stay closed. NStringCh alone also scales explicit parallel leaves in verified Version=8.1.0/8.1.6 unshared independent mode while preserving MPPT/inverter multiplicities; integral explicit leaf counts are required. NStringCh alone also supports a member of one bounded Version=8.1.0/8.1.6 shared parent (matching member versions, common fixed plane, complete allocation, group 0/-1); only its owned leaves/root strings change, not peer members, inputs, sharing or nominal tags. Group 0 must have no outside references. Returns capacity.shared_parent_line; native automatic budgets may change. Do not combine NInvMPPT with NInverter/NStringCh/NoOrientation. No hardware limits or loss/nominal-power refitting is performed. Other system bits and field type are preserved. NoOrientation (positive integer) reassigns the selected subarray to an existing ordinary fixed plane: sequential counted TOrientGroup IDs, flat Flags=$00 non-averaged source/target, fully checked exclusive ordinary branches without explicit MPPT, or verified Version=8.1.0/8.1.6 independent $0400/direct-MPPT branches with disabled sharing -1 and complete declared input counts, and all strings in one orientation are required. Circuit-level orientation references remain unsupported. Every defined plane must retain an assigned subarray. Leaves planes/list counts and circuit quantities unchanged; no automatic pruning or shading remap. Returns orientation_assignment before/after. power_sharing_enabled separately toggles all members of the existing bounded shared parent containing subarray_id. Requires complete counts, Version=8.1.0/8.1.6 independent $0400 members with matching declared versions, the same inverter and fixed plane, all member strings in that plane, and exclusive use of group 0. Synchronizes member PowerSharingInverterId=0/-1 and only Flags bit $0100; preserves topology, quantities, mode, nominal tags and loss parameters. No topology creation, arbitrary group IDs or manual allocation. Do not combine with other parameter updates. Returns power_sharing before/after. independent_mppt_enabled separately switches verified Version=8.1.0/8.1.6 exclusive explicit MPPT layouts with PowerSharingInverterId=-1, complete unshaded fixed-plane counts and all strings in one orientation. It changes only $0400 and NInvMPPT (explicit input total when enabled, 1 when disabled). Requires all owned inverter children explicit MPPT; preserves circuit and other flags/counts, components/nominal/loss tags. Model power interpretation changes; hardware allocations are not redesigned. Returns mppt_mode. soiling_updates configures the native whole-array Soiling block in a separate transaction (variant_name may accompany it). mode=none removes that block; constant requires yearly_loss_pct; monthly requires twelve monthly_loss_pct. Percent values are 0..100 in 0.1 percentage-point increments, matching GUI save precision. Verified scope: 8.1.6 PV-only Grid, one unshaded fixed plane/subarray, main Flags=$00100400/$01900400, Flags2=$082A. Flags and unrelated fields stay unchanged; no irradiance/yield calculation, legacy or file-based soiling edits. grid_limit_updates is a separate transaction (variant_name may accompany it). mode=constant requires positive limit_kw in 0.1 kW increments: native active power at the injection point, with separate grid-curtailment loss. mode=none clears the active-limit bit and removes its scalars, preserving the inactive location bit. Verified 8.1.6 PV-only single-subarray/fixed-plane/unshaded scope; PF, loads/storage, file-based limits and other system modes stop before writes. This is not bit27 export permission, kVA, storage peak shaving or external output clipping. Original native calculations and existing rollback apply. auxiliary_updates is separate (variant_name may accompany it). constant requires explicit operating_kw and night_kw >=0 in 0.01 kW increments for the whole system; native operating power applies above the verified zero inverter-output threshold, not a clock schedule. none clears native bit18 and removes auxiliary powers. Verified 8.1.6 PV-only fixed/unshaded scope; PF, grid limits, loads/storage, proportional/threshold fields stop before writes. Native negative E_Grid is retained, not clipped; no external auxiliary load or energy calculation. seasonal_updates is separate and configures native SeasonalTilt from a verified FixedPlane or SeasonalTilt: explicit summer_tilt/winter_tilt in 0..90 degrees, 0.1-degree steps, and 1..11 distinct winter_months integers in 1..12. Optional orientation_name changes the owning plane label; azimuth is preserved. Require one 8.1.6 PV-only Grid subarray/plane, complete circuit allocation, no geometry/layout, free horizon and plain system Flags. Averaged planes, trackers, loads/storage and coupled system modes stop before writes. Zero fixed BaseSlope is removed as native GUI does. This is not a fixed-mode switch; restore the snapshot to recover the source. No angle or season model is implemented outside PVsyst. horizon_updates is separate: none removes the native far-horizon block; profile requires profile_name and 4..100 increasing [azimuth, elevation] points in native degrees, 0.1-degree steps, x=-180..180, y=0..90. All-zero profiles use none. Fixed-plane plain PV-only Grid scope; no trackers, seasonal modes, loads/storage, PF/aux/grid-limit coupling or near-shading/layout edits. Native FracAlbedo=1 stays inherited. New or changed points use the GUI profile template without stale derived factors; name-only updates preserve them. PVsyst computes interpolation, diffuse and losses. inverter_temperature_updates is separate and requires an ordinary single free-horizon PV-only Grid plane, with no load/storage/PF/aux/grid-limit coupling or geometry. mode ambient removes both native temperature fields; offset/fixed require both offset_c and fixed_c explicitly, including the inactive saved value, with no default. Both values are degC in adapter range [-100,100], 0.1-degree steps: this is an adapter support envelope, not a native GUI or manufacturer limit. Only system temperature mode bits and TempShift/TempFixed change; module Uc and OND curves stay unchanged. PVsyst alone calculates inverter temperature and derating. power_factor_updates is separate (variant_name may accompany it), for native 8.1.6 PV-only single fixed-plane/free-horizon Grid systems without geometry, loads/storage, temperature, auxiliary or grid-limit coupling. mode none removes PF fields; constant requires tan_phi, monthly requires twelve monthly_tan_phi in January-to-December order. Require explicit pnom_limit native/active/apparent; only none requires native; constant/monthly accept all three. Values are signed dimensionless native tangent values in adapter range [-1,1], 0.001 steps, not cosine values or manufacturer limits. GUI leading uses negative, lagging positive; native PVsyst alone computes power and derating. Legacy active/apparent select inverter PNom interpretation, not injection limits, and do not change OND hardware data. p50_p90_updates edits an existing GUI-produced P50 result template, separately from physical changes (variant_name may accompany it). Supply all fourteen native keys: SpecYear/TMY kind, two ordered integer percentiles 51..99, report booleans, PlotKind=1, explicit year deviation and six variability percentages, and a custom ASCII label. YearDevFromAver is percent in [-100,100], variability fields percent in [0,100], all using 0.001 steps; these are adapter domains, not scientific bounds. CustomVarLabel requires 1..80 printable trimmed ASCII bytes. Require native 8.1.6 plain PV-only single fixed/free-horizon Grid, root Flags=$01800001 and one existing flat P50_P90=TP50_P90 block; no creation/deletion, unknown ClimateChange, cumulative plot or coupled physical changes. Native root flags and cached results stay unchanged. Unchecked GUI boxes retain manual values; checked boxes restore native defaults, not include/exclude terms. Native PVsyst alone computes probabilities and reports. power_controls_updates is a separate combined PF/grid transaction (variant_name may accompany it); old power_factor_updates/grid_limit_updates stay separate. Supply power_factor using its existing shape and grid_limit with explicit mode, quantity active/apparent and point injection/inverter. Constant also requires positive limit in 0.1 native units (kW active, kVA apparent), separate_loss bool; none supplies neither. No conversion from tangent or independent power model. Only observed native flag families are accepted: monthly/Legacy with an enabled limit require injection/separate loss. Monthly plus Legacy with an enabled limit supports active quantity only. An enabled inverter-point limit requires constant/native PNom/separate loss; combined loss requires constant/native PNom/injection. Enabled NoPF requires active injection/separate loss. Monthly PNom without a grid limit uses explicit active quantity/inverter point. No temperature, P50, storage/load or geometry coupling. Inactive type/location bits are explicit, not silently reset. The shared 8.1.6 PV-only single fixed/free-horizon/count gates remain in force. string_mismatch_updates is separate (variant_name may accompany it), for native 8.1.6 PV-only single fixed-plane/free-horizon Grid subarrays: mode default clears the manual value and sets the native default bit, constant writes one manual loss_percent (adapter envelope 0.01..100, 0.01 steps; zero is mode default). auxiliary_updates profile has two verified families -- constant power with its threshold, or proportional W/kW with its threshold -- and requires all five values explicitly with night_kw = 0; the old constant/none shapes are unchanged. ageing_updates is separate (variant_name may accompany it) and applies only to an existing activated ageing template: it writes simulation_year and annual_module_degradation_percent, optional keep_mc_values and a paired modules_rms_year_isc_percent/modules_rms_year_voc_percent (adapter 0..100 percent, 0.01 steps). Stored factors and warranty lists are preserved; no degradation or stochastic sampling is computed. The retention flag is a native input; sample-array persistence is not verified. ageing_enabled is a separate strict boolean transaction for an existing fully validated template, toggling only main-array Flags2 bit20; it never creates a block or activates an unsupported template. Disabled templates remain readable but must be enabled before model editing. Zero rate is a value, not the disabled state. iam_updates is separate too and covers only the component IAM bit or the ASHRAE model with an optional b0; PAN files and curve data are never written. system_unavailability_updates={"mode":"none"} separately removes one existing native Periods SystemUnavail child and its owning system tag. It is limited to the verified 8.1.6 PV-only single fixed/free-horizon template, with no P50, loads or storage. It does not generate periods or edit grid availability. Restore the returned transaction backup to recover the original native schedule; clearing a flag alone is not sufficient. No-op edits create no backup.