Performance analytics#
- space_pv_analytics.add_robust_baseline(frame, *, reference_samples=500)[source]#
Add a telemetry-only upper-envelope normalization.
Case 0 has no trusted Sun/eclipse/attitude state. Normalizing against a high reference quantile is intentionally safer than treating every low-power sample as a fault. Fault screening happens on daily upper-envelope health, not samples.
- space_pv_analytics.power_loss_breakdown(frame, stages=(), *, expected_power_column='expected_power_w', actual_power_column='actual_power_w', timestamp_column='timestamp', group_columns=())[source]#
Explain expected-minus-actual power using ordered cumulative predictions.
For stages
P1, ..., Pnand a declared expected baselineP0, the signed contributions areP0-P1, P1-P2, ..., P(n-1)-Pn. The unexplained remainder isPn-actual. Thus all contributions sum toexpected-actualat every valid sample, including gains.Use an ideal reference baseline for a design loss budget, or a healthy operating model for underperformance analysis. Effects already included in the expected baseline must not be subtracted again. Attribution is order-dependent and conditional on the supplied evidence; this function does not diagnose causes from the residual or normalize supplied losses.
Inputs must be already time-aligned in one DataFrame. Timestamps are converted to UTC (naive timestamps are assumed UTC), then sorted within each group. Duplicate group/timestamp pairs, missing identifiers, infinite powers and negative expected/stage predictions are rejected. Signed actual power is retained, including small negative telemetry sensor offsets. NaN in any required power excludes the entire row from the loss ledger; expected, final-modeled and actual powers remain in
samplesfor inspection. Rows are not dropped, so energy accounting cannot interpolate across missing values.- Parameters:
frame (pandas.DataFrame) – Timestamps, expected/actual powers and optional cumulative stage powers.
stages (sequence of LossStage) – Ordered stages from the chosen baseline to the final modeled power. With no stages, the whole gap remains unexplained.
expected_power_column (str) – Input power column names, in W, at the same declared electrical boundary.
actual_power_column (str) – Input power column names, in W, at the same declared electrical boundary.
timestamp_column (str) – Input timestamp column. Do not combine unrelated campaign-relative times.
group_columns (sequence of str) – Independent series identifiers, e.g.
("panel_id",). Energy is never integrated across groups.
- Return type:
- space_pv_analytics.summarize_power_losses(breakdown, *, max_gap_s)[source]#
Integrate a power ledger on common, observed intervals only.
max_gap_sis a required positive, finite maximum interval length in seconds. An interval contributes only when both endpoint rows are valid for all required powers and their separation is at most this threshold. Missing rows remain boundaries; no missing energy is filled or extrapolated. Each group uses its own recorded first-to-last time span for coverage. Coverage does not include any unrecorded time before or after that span.Power is assumed to vary linearly between accepted endpoints, giving trapezoidal energy integrals. Positive losses and gains split this line exactly where it crosses zero. Event discontinuities and packet timing uncertainty still require suitable sampling; the cutoff is not a claim that the intervening power is known. Choose it from the measurement cadence and context rather than applying a universal default.
All stages, categories and total powers use the same interval mask, so net loss energy reconciles exactly (up to floating-point rounding). Percentages use expected energy over these same intervals; they are signed and are not normalized to make the loss buckets sum to 100%.
- Parameters:
breakdown (PowerLossBreakdown)
max_gap_s (float)
- Return type:
- space_pv_analytics.performance.add_robust_baseline(frame, *, reference_samples=500)[source]#
Add a telemetry-only upper-envelope normalization.
Case 0 has no trusted Sun/eclipse/attitude state. Normalizing against a high reference quantile is intentionally safer than treating every low-power sample as a fault. Fault screening happens on daily upper-envelope health, not samples.
Power and energy loss accounting#
Reconciled, evidence-labelled power losses and gap-aware energy accounting.
- space_pv_analytics.losses.LOSS_CATEGORIES = mappingproxy({'solar_resource': 'Solar resource', 'geometry': 'Eclipse and pointing', 'optical': 'Optical and spectral', 'temperature': 'Cell temperature', 'degradation': 'Radiation and aging', 'electrical': 'Mismatch and wiring', 'conversion': 'Power conversion', 'operations': 'Clipping, availability and curtailment', 'unexplained': 'Unexplained residual'})#
Physical and operational reporting buckets; individual stages retain their names.
- class space_pv_analytics.losses.LossStage(name, power_column, category, evidence)[source]#
One ordered, cumulative power prediction with a declared evidence basis.
power_columncontains the prediction after this stage, not an independent loss estimate. Its contribution is the preceding prediction minus this prediction.evidenceshould identify the measurement, model, operating flag or explicit scenario assumption supporting the attribution. This label records the caller’s evidence; it does not verify causality.categorymust be a key inLOSS_CATEGORIES, exceptunexplainedwhich is reserved for the final model-minus-actual residual. Names must be unique snake_case identifiers within a breakdown.
- class space_pv_analytics.losses.PowerLossBreakdown(samples, components_w, categories_w, stages, group_columns)[source]#
Power ledger returned by
power_loss_breakdown().samplescontains sorted timestamps, group identifiers, power predictions, signed total/attributed/unexplained losses and a commonvalidmask.components_wcontains a column per stage plusunexplained.categories_wcombines stage contributions into reporting buckets. The three frames share the same positional index. Positive values are losses; negative values are gains. Treat these frames as read-only inputs tosummarize_power_losses().
- class space_pv_analytics.losses.PowerLossSummary(totals, components, categories)[source]#
Observed-interval energy totals, components and categories, all in Wh.
totalsreports the signed energy gap and common observation coverage per input group.componentsandcategoriesreport signednet_loss_wh, nonnegativeloss_wh/gain_whand the signed percentage of expected energy. Percentages are NaN when expected energy is zero. All energy values are NaN when there are no usable intervals.Net contributions reconcile with the total gap. Gross positive/negative contributions can cancel between components, so their separate sums need not equal the total positive gap or total surplus.
- space_pv_analytics.losses.power_loss_breakdown(frame, stages=(), *, expected_power_column='expected_power_w', actual_power_column='actual_power_w', timestamp_column='timestamp', group_columns=())[source]#
Explain expected-minus-actual power using ordered cumulative predictions.
For stages
P1, ..., Pnand a declared expected baselineP0, the signed contributions areP0-P1, P1-P2, ..., P(n-1)-Pn. The unexplained remainder isPn-actual. Thus all contributions sum toexpected-actualat every valid sample, including gains.Use an ideal reference baseline for a design loss budget, or a healthy operating model for underperformance analysis. Effects already included in the expected baseline must not be subtracted again. Attribution is order-dependent and conditional on the supplied evidence; this function does not diagnose causes from the residual or normalize supplied losses.
Inputs must be already time-aligned in one DataFrame. Timestamps are converted to UTC (naive timestamps are assumed UTC), then sorted within each group. Duplicate group/timestamp pairs, missing identifiers, infinite powers and negative expected/stage predictions are rejected. Signed actual power is retained, including small negative telemetry sensor offsets. NaN in any required power excludes the entire row from the loss ledger; expected, final-modeled and actual powers remain in
samplesfor inspection. Rows are not dropped, so energy accounting cannot interpolate across missing values.- Parameters:
frame (pandas.DataFrame) – Timestamps, expected/actual powers and optional cumulative stage powers.
stages (sequence of LossStage) – Ordered stages from the chosen baseline to the final modeled power. With no stages, the whole gap remains unexplained.
expected_power_column (str) – Input power column names, in W, at the same declared electrical boundary.
actual_power_column (str) – Input power column names, in W, at the same declared electrical boundary.
timestamp_column (str) – Input timestamp column. Do not combine unrelated campaign-relative times.
group_columns (sequence of str) – Independent series identifiers, e.g.
("panel_id",). Energy is never integrated across groups.
- Return type:
- space_pv_analytics.losses.summarize_power_losses(breakdown, *, max_gap_s)[source]#
Integrate a power ledger on common, observed intervals only.
max_gap_sis a required positive, finite maximum interval length in seconds. An interval contributes only when both endpoint rows are valid for all required powers and their separation is at most this threshold. Missing rows remain boundaries; no missing energy is filled or extrapolated. Each group uses its own recorded first-to-last time span for coverage. Coverage does not include any unrecorded time before or after that span.Power is assumed to vary linearly between accepted endpoints, giving trapezoidal energy integrals. Positive losses and gains split this line exactly where it crosses zero. Event discontinuities and packet timing uncertainty still require suitable sampling; the cutoff is not a claim that the intervening power is known. Choose it from the measurement cadence and context rather than applying a universal default.
All stages, categories and total powers use the same interval mask, so net loss energy reconciles exactly (up to floating-point rounding). Percentages use expected energy over these same intervals; they are signed and are not normalized to make the loss buckets sum to 100%.
- Parameters:
breakdown (PowerLossBreakdown)
max_gap_s (float)
- Return type:
Array procurement screening#
Continuous-area procurement screening at a specified end-of-life power point.
This is a deterministic decision model, not a radiation, thermal, orbit-energy, reliability or qualified flight-hardware model. All costs use one common currency.
- class space_pv_analytics.procurement.ArrayOffer(name, bol_w_m2, eol_retention, kg_m2, cost_m2)[source]#
Array-level inputs at a common spectrum, temperature and incidence.
bol_w_m2includes packing and thermal effects at the chosen design point. Retention includes all assumed aging effects at the specified mission EOL. Areal mass includes deployed structure allocated per area. Procurement cost excludes launch. No AM1.5-to-AM0 conversion or lifetime extrapolation occurs.
- class space_pv_analytics.procurement.ArraySizing(area_m2, mass_kg, eol_bus_w, procurement_cost, launch_cost, total_cost, cost_per_eol_bus_w)[source]#
Modeled sunlit power, size and procurement-plus-launch cost.
- space_pv_analytics.procurement.size_array(offer, required_bus_w, *, margin=0.2, bus_efficiency=0.9, launch_cost_kg=0.0)[source]#
Size continuous area for EOL sunlit bus demand plus fractional margin.
Launch cost is an assumed marginal mass price, not a launch quote. Storage, eclipses, fixed qualification costs, discrete panels and deployment risks are outside this model.
margin=0.2means 20% extra power.- Parameters:
offer (ArrayOffer)
required_bus_w (float)
margin (float)
bus_efficiency (float)
launch_cost_kg (float)
- Return type:
- space_pv_analytics.procurement.break_even_cost_m2(baseline, candidate, *, launch_cost_kg=0.0)[source]#
Maximum candidate procurement price per m² at equal EOL bus power.
Both options must use the same margin and bus efficiency. A negative result means the candidate cannot break even at any nonnegative procurement price. The candidate’s current quoted price does not enter this threshold.
- Parameters:
baseline (ArrayOffer)
candidate (ArrayOffer)
launch_cost_kg (float)
- Return type:
Power-service admission#
Public power-service admission API.
- orbitalpv.utility.screen_power_service(time_s, generation_w, housekeeping_w, customer_counts, *, customer_power_w, delivery_efficiency, battery)[source]#
Screen identical continuous customer loads over supplied intervals.
Customer power is delivered at the customer; generation, housekeeping and battery limits are at the utility bus. The delivery loss applies only to customer power. Housekeeping may include externally modeled heater demand.
Report both finite-horizon service and repeatable-profile feasibility. The latter additionally requires final SOC >= initial SOC; it is not a guarantee for another illumination profile. No load shedding, priority allocation, reliability probability, degradation or economic value is inferred.
Degradation monitoring design#
Known-noise log-power trends and degradation monitoring campaign design.
Inputs must be maximum-power measurements normalized to matched illumination, cell temperature and electrical boundary. These routines do not perform that physical normalization or infer a radiation damage mechanism.
- class space_pv_analytics.monitoring.MonitoringDesign(observations, duration_days, slope_standard_error_per_year, minimum_detectable_annual_loss, confidence, detection_probability, drift_bound_per_year)[source]#
Conditional Gaussian detection capability; annual losses are fractions.
- class space_pv_analytics.monitoring.LogPowerTrend(slope_per_year, slope_lower_per_year, slope_upper_per_year, annual_loss_fraction, loss_detected)[source]#
Log-power slope and drift-expanded confidence interval, in year⁻¹.
- space_pv_analytics.monitoring.log_power_covariance(time_days, *, independent_sigma, correlated_sigma=0.0, correlation_days=7.0)[source]#
Construct log-power covariance: white noise plus an exponential kernel.
Sigmas are standard deviations in natural-log power (dimensionless), not percentage points. They approximate relative errors only for small noise. The kernel is a declared planning assumption, not a fitted instrument model.
- space_pv_analytics.monitoring.design_degradation_monitoring(time_days, covariance, *, confidence=0.95, detection_probability=0.8, drift_bound_per_year=0.0)[source]#
Plan detection of a negative constant log-power slope with known noise.
GLS covariance is
(X.T @ C^-1 @ X)^-1. Reject zero slope when the two-sided confidence interval’s upper endpoint is negative. For a bounded unknown linear calibration drift ±d, the interval expands by d. Guaranteeing the requested detection probability at the worst opposing drift requires a loss magnitude of(z_confidence + z_probability) * slope_se + 2*d. Annual retained power is exp(slope); loss is 1-exp(slope).This is conditional on known Gaussian covariance and a constant physical slope. It is not a qualification or a forecast of perovskite lifetime.
- Parameters:
- Return type:
- space_pv_analytics.monitoring.fit_log_power_trend(time_days, normalized_power, covariance, *, confidence=0.95, drift_bound_per_year=0.0)[source]#
Fit one normalized device series with externally supplied log covariance.
No residual variance rescaling is performed: covariance must come from calibration/replicates or an explicitly labeled scenario. Do not combine devices, eclipse samples, bus-load-limited power, or unmatched IV sweeps. Confidence bounds include a bounded linear drift but not normalization bias, nonlinear aging, hysteresis, recovery, seasonality or unmodeled change points.
- Parameters:
- Return type:
Ground delivery adequacy#
Public delivered-power adequacy API.
- class orbitalpv.delivery.DeliveryAssessment(duration_h, delivered_wh, required_wh, served_wh, shortfall_wh, surplus_wh, availability, shortfall_h, longest_shortfall_h, backup_peak_w, largest_event_shortfall_wh, energy_target_met)[source]#
Finite-horizon metrics; energy in Wh, power in W, duration in hours.
Availability is time at or above the target within a caller-declared watt tolerance. Shortfall energy is never reduced by that numerical tolerance. Backup ratings are ideal point-of-delivery requirements, not battery sizing.
- orbitalpv.delivery.assess_delivery(time_edges_h, delivered_w, required_w, *, energy_target_wh, tolerance_w=0.0)[source]#
Screen piecewise-constant power over explicit contiguous interval edges.
N+1 elapsed-hour boundaries describe N powers. Scalars broadcast. Missing values, duplicate/reversed edges and negative powers are rejected; no gap filling or implicit annualization. Energy target is for the supplied horizon. Event energy integrates each contiguous above-tolerance deficit event; tolerance affects availability/event classification only.
- Parameters:
- Return type:
- orbitalpv.delivery.delivery_chain(pv_dc_w, efficiencies)[source]#
Apply ordered scalar efficiencies to an interval PV DC power vector.
Values are scenario assumptions unless calibrated externally. Beam capture, RF conversion and grid delivery must be separate entries supplied by the caller. This is accounting, not a beam/orbit/thermal propagation model. Each column is cumulative power after its named stage, in watts.
Deployment evidence planning#
Public deployment evidence planning API.
- orbitalpv.qualification.deployment_reliability_lower_bound(successes, failures, *, confidence=0.95)[source]#
Exact one-sided Clopper-Pearson lower bound on per-unit success probability.
Solve P(F <= observed_failures | R=lower) = 1-confidence for n trials. All-success bound is (1-confidence)**(1/n). All-failure bound is zero. Confidence describes repeated-sampling coverage, not a posterior probability. Counts must be independently justified; no pooling across design/protocols.
- orbitalpv.qualification.summarize_deployment_trials(frame, *, confidence=0.95)[source]#
Screen a one-shot trial registry by design and protocol, without pooling.
Columns: unit_id, design_id, protocol_id (nonempty strings), success (0/1). Duplicate unit IDs within a design/protocol fail even if outcomes agree. Unique IDs cannot establish physical independence: the caller must establish representative hardware, comparable stress exposure and absence of shared failure causes. Incomplete/censored records must not be encoded as successes.
- orbitalpv.qualification.zero_failure_sample_size(reliability, *, confidence=0.95)[source]#
Smallest fixed campaign with zero failures supporting the requested bound.
n = ceil(log(1-confidence)/log(reliability)). This is not a sequential stopping rule. No number of repetitions proves unmodeled common-cause risks.