diff --git a/.github/workflows/unit-test.yml b/.github/workflows/unit-test.yml index f2a82b8..436f29c 100644 --- a/.github/workflows/unit-test.yml +++ b/.github/workflows/unit-test.yml @@ -31,7 +31,7 @@ jobs: - name: Install project in editable mode run: | - pip install -e ".[preprocess]" + pip install -e ".[preprocess,tradespace]" - name: Run unit tests run: python -m unittest diff --git a/.gitignore b/.gitignore index a82df84..d60a7cc 100644 --- a/.gitignore +++ b/.gitignore @@ -73,7 +73,7 @@ docs/_build/ # Reference data downloaded by example and validation notebooks docs/validation/data/ -docs/examples/data/ +docs/examples/osse/data/ # PyBuilder .pybuilder/ diff --git a/CHANGELOG.md b/CHANGELOG.md index 287aa26..0b1f415 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -11,8 +11,45 @@ Added: - Field `blind_intervals` of `Attitude`: intervals of argument of latitude in which a space system's instruments do not observe, for example while the body or a mechanism moves. Observations in them are not valid, so point observations, ground tracks (`valid_obs`, and the swaths of `compute_ground_track`), orbit tracks, and ground pixels omit them, and the periods and swaths of region observations end at them. Method `is_observing` of attitudes, schedules, and instruments. - Field `is_swept` of `PointedInstrument`, for an instrument whose view sweeps along track: its footprint over a time step is the strip its cross-track line (the directions at an along-track angle of zero, which `collect_observations` checks) sweeps between the step's bounds, trimmed to blind intervals, so that ground track swaths (`compute_ground_track`) and region swaths do not depend on the time step, while its along-track field of view still sets the instantaneous view. Method `PointedInstrument.compute_swept_footprints`, utility method `compute_swept_footprints`, argument `time_step` of `collect_ground_track` and `compute_ground_track` (the span of each footprint, by default half the gap to the neighboring times on each side), and runtime configuration `swept_footprint_max_substep`. The default, `False`, leaves footprints unchanged. - Field `type` (`instrument`, `pointed`, or `conical`) of `Instrument`, `PointedInstrument`, and `ConicalInstrument`, which identifies the instrument class in serialized data. Data without a `type` loads as the class its fields imply. + - Arguments `count`, `rotate`, and `seed` of `generation.generate_points_fibonacci_lattice`: a lattice of a number of points (about that many inside a mask) in place of a distance between them, and in a random orientation, drawn from a seed: a stratified sample of the sphere (or of a mask), each point uniform by area, whose statistics have about 1.5 to 4 times less variance between replicates of trade studies than those of random points. + - Analysis methods of the statistical sufficiency of observations (module `analysis.sufficiency`): `estimate_sampling_error`, the error of estimating the mean of a field over a period from each target's samples, for a field with a standard deviation and an exponential correlation in time (exact, see `sampling_error_variance`), with the effective number of independent samples; `sample_field`, which samples a field (an xarray `DataArray`, such as a nature run) at the time and place of each observation, and `compare_sampled_means`, which measures the sampling error against it; `compute_revisit_statistics`, the quantiles of revisits and the longest gap of each target (including the edges of the period); and `compute_local_time_coverage`, the distribution of samples in local time of day. The decorrelation time of `estimate_sampling_error` may differ between targets. The validation notebook `ValidateSamplingErrorIMERG` compares its predictions with the errors of monthly means of IMERG precipitation sampled by four constellation designs, and the example notebook `AssessSamplingSufficiency` shows the qualities of the methods with a synthetic nature run. `estimate_sampling_error` and `compute_revisit_statistics` compute the statistics of every target at once (the sum of the correlations between pairs of samples by a recursion over their times, and the gaps and their quantiles from the samples in order), with the same results 3 to 12 times faster. + - Module `tradespace` (prototype) for trade studies. A `DesignSpace` declares design variables (`Real`, `Integer`, `Categorical`), fixed and `Derived` values, and `Uncertain` parameters (drawn per replicate, not searched), grouped hierarchically with `Choice` (one of several branches) and `Repeat` (a variable number of items, such as orbit planes, optionally unordered). Bounds, derived values, and constraints are callables of the values decided before them. `DesignSpace.enumerate` gives every feasible design (a full factorial design, including variables that exist only in some designs), and `sample` a Latin hypercube or random sample. A `Design` has a `key` from its decisions and `flat` values by path, and `realize` draws a replicate's uncertain parameters, with common random numbers between designs by default. `Study` builds and evaluates designs in replicates into a data frame, in worker processes with `n_jobs` (or on an `executor`; idle workers wait two minutes for more evaluations before they exit), giving the realized design to an evaluation function with a parameter named `design`, recording as infeasible the designs that its functions reject with `Infeasible` or that fail the validation of TAT-C's schemas (other errors, including other `ValueError`s, are raised or recorded as failed), and raising an error for metrics that would replace its status columns or a design's values; `summarize` gives the mean, standard deviation, and standard error of metrics over replicates. + - Class `tradespace.SatelliteCache`, which caches an analysis of single satellites by their content (orbit, instruments, and attitude, not their name, see `get_satellite_key`), in memory or on disk, so that designs that share satellites compute their results once. On disk, results are kept by namespace and by the definition of the function (see `get_definition`); a cache warns if its namespace has results only of its function with other code, naming what differs, `SatelliteCache.prune` removes the results of other definitions, and results that cannot be read are computed again. + - Functions `tradespace.pareto_front`, `pareto_ranks` (both with optional tolerances of objectives, within which designs near the front are efficient), and `hypervolume` (exact) of designs with several objectives to minimize or maximize, and `pareto_probability`, the probability that each design is efficient given the uncertainty of its replicates (a bootstrap that resamples the same replicates for every design). + - Criteria by which designs are judged (`tradespace.Criteria`): objectives to minimize or maximize, requirements (`Requirement`, output constraints that designs meet or violate once evaluated, by an amount relative to the required value or a `scale`), the statistics over replicates that they name (`Mean`, `StandardDeviation`, `Minimum`, `Maximum`, `Quantile`, and `Probability`, the share of replicates that meet a threshold; other names are means of metrics), tolerances of objectives, and the columns that group the records of an evaluation (`by`, such as a sensor), whose designs are judged separately. `summarize` gives statistics of each design (and, with criteria, the violations of their requirements), with the standard deviations and standard errors of means. `pareto_front`, `pareto_ranks` (which ranks designs that miss requirements after those that meet them), `hypervolume`, `pareto_probability` (which also gives the probability of meeting the requirements), `refine`, `confirm`, `screen`, `optimize_optuna` (a constraint of each trial for each requirement), and `optimize_pymoo` (a constraint for each requirement) take criteria, or a mapping of objectives to their directions. Results with several records of an evaluation that `by` does not separate raise an error. + - Function `tradespace.refine` (and class `Refinement`), which adds replicates only to the designs whose Pareto efficiency is uncertain, until it is settled, optionally with a tolerance of differences that do not matter (also of `pareto_probability`), and within a `budget` of evaluations (refining the least settled designs first). Designs about a tolerance from the front, which more replicates settle only slowly, are `indifferent` and not refined once their objectives are known to within a share of their tolerances (`precision`, from the standard errors of the objectives that `pareto_probability` gives). `Study.run` evaluates given replicates (`replicate_indices`). + - Class `tradespace.ResultStore`, a persistent store (SQLite) of the evaluations of a study (argument `store` of `Study`), from which a study that is interrupted or extended takes the evaluations stored before (except evaluations that failed and designs that failed validation, which are evaluated again). Workers add each evaluation as it completes, so that an interrupted run loses only the evaluations in progress, and records are kept as JSON (with values such as dates and infinite numbers tagged, so that they are read exactly). Function `tradespace.sensitivity` (and `main_effects`), the share of the variance of metrics explained by each design variable where it is active. Tolerances of objectives may be percentages of their values (such as `"5%"`). `Uncertain.seed` draws a seed of random numbers for each replicate, and `remove_failures` removes the satellites that fail, the same in every design. + - Building blocks of constellations: fragments of design spaces of Walker constellations (`tradespace.walker_space`) and planes of sun-synchronous orbits (`sso_planes_space`, whose planes have different crossing times), `build_constellation`, which builds the satellites of either with instruments or entries of the instrument catalog (with their validated attitudes, and several entries on one satellite), and `count_satellites` and `count_planes`. The phase and node of the lead satellite of a Walker constellation (`phase_fraction` and `node_fraction`, design variables or uncertain parameters) are fractions of the intervals over which they give distinct constellations (`360 / per_plane` degrees of phase, and `360 / planes` degrees of node for a delta configuration or 360 for a star), so that a search does not evaluate the same constellation at several phases or nodes. Planes of inclined orbits (`planes_space`), each with its own inclination and node (uncertain by default, as of satellites launched as secondary payloads). Streets-of-coverage constellations (`soc_space`), whose planes and satellites in each plane the fragment derives from a swath width, inclination, and altitude, and mutual orbiting groups (`mog_space`), launched together as one plane. The fragments name the number of planes `planes` and the satellites in each plane `per_plane`. The satellites of the planes of `sso_planes_space` and `planes_space` are evenly spaced, or follow each other in a train at an `interval` (minutes), on the same ground track or in the same plane (`repeat_ground_track`). The phase of each plane (`phase_fraction`) is a fraction of the interval over which it gives distinct planes (`360 / per_plane` degrees for evenly spaced satellites, 360 for a train), from which each fragment derives the plane's `true_anomaly`, as for the lead satellite of a Walker constellation. `build_constellation`, `count_satellites`, and `count_planes` take several layouts (a list, or a `Repeat` of a `Choice` of layouts), such as the shells of a mixed constellation. The values of each fragment in a design are those of a `Layout` (`layout_of`, with `WalkerLayout`, `SSOPlanesLayout`, `PlanesLayout`, `SOCLayout`, `MOGLayout`, and `Layouts` of several), which gives its `Plane`s and the orbits of their satellites in order; other layouts subclass it and are built, counted (`plane_sizes`), deployed, and costed as the others. + - Function `tradespace.screen` (and class `Screening`), which screens designs with studies of increasing fidelity, keeping whole fronts of the best designs of each stage for the next. + - Searches of design spaces with optional optimizers: `tradespace.optimize_optuna` suggests designs with Optuna trials (define-by-run over the hierarchical space), and `optimize_pymoo` and `make_pymoo_problem` search the unit hypercube that encodes a design space (a dimension per decision) with pymoo, whose algorithms eliminate the proposals of designs proposed or evaluated before (`distinct`, by design, `make_pymoo_problem`'s `duplicates`). Each design is evaluated once, and the designs proposed together are evaluated together, in parallel if the study is. A search returns its results and designs (`Search`), which `refine` and `confirm` refine and confirm as for any study. Constraints of a design space may return the amount of their violation (`Infeasible.violation`), which Optuna's trials record (`set_constraint`) for its constraint-aware samplers, and which is the constraint value of pymoo problems. Optional dependencies `tradespace` (joblib, Optuna, and pymoo). + - Deployment of constellations (`tradespace.DeploymentSchedule`): from the rates and durations of a study (the mission, the design life, development, and production rate of each type of satellite, its production on a line, and launches at a cadence and capacity, in number or mass, optionally in an order of planes), each design's deployment (`DeploymentSchedule.plan`, a `Deployment` of its `Production`, `Launch`es, and replacements), so that a design of more satellites and planes takes longer to deploy. A sustained constellation (`DeploymentSchedule.sustained`, such as of an operational program over the period of a study) is replaced after the end of the mission as before it, and its costs are those incurred by the end, which count the units in production then by the share produced and later blocks by the share of their development done. A deployment's launches divide the mission into phases of constant sets of operating satellites (`Deployment.phases`), evaluated over the study's representative period from the observations of the full constellation (`evaluate_phases`) and combined over the mission (`summarize_phases`: the time-weighted mean of each metric and the time until it first meets a requirement). + - Simulated missions with failures (`Deployment.simulate`, a `MissionHistory` for each replicate, drawn from its seed with common random numbers between designs): lives of satellites whose failure rates vary over the lifecycle (`tradespace.Exponential`, `Weibull`, `Bathtub` of competing causes, and `Piecewise` rates by age, `Lifetime`), failures of launches (`FailureModel`), and a policy that degrades or restores failed satellites (`RestorationPolicy`) by spares in orbit (taking a failed satellite's place after drifting), spares on the ground (launched at the next launch slot), or satellites produced when needed (after procurement, on the production line), optionally replenishing spares and batching restorations in launches. A history gives the phases in which satellites operate (`MissionHistory.phases`), measures of the mission (`MissionHistory.metrics`: failures, restorations, spares used, time to restore, and availability), and, priced by a `CostModel`, the cost of what it produces and launches. Policies are decisions of designs with a fragment of a design space (`policy_space`: whether to restore, spares in orbit and on the ground, and other fields of the policy, without spares that would never be used), and `configure` makes a policy (or a deployment schedule, or another dataclass) from the values of a design. Many histories of a replicate's mission (`Deployment.simulate_many`) share its sample of targets: `evaluate_histories` evaluates them (with their measures and costs) with a cache that evaluates each set of operating satellites once (`PhaseCache`, keyed by the content of the satellites and shared by the histories, policies, and designs of a replicate), and `summarize_histories` gives their means, quantiles (the risk of the mission), and probabilities of meeting requirements, as one record of the replicate. The histories of a replicate are stratified by default (a Latin hypercube over the histories of each satellite's life and each launch, drawn from uniform numbers by `Lifetime.from_uniform`), which estimates the means of missions 3 to 15 times more precisely than independent histories, and means may be estimated with control variates (`summarize_histories(controls=...)`, such as the availability of the mission, whose expected value simulations alone estimate). `allocate_histories` recommends the histories of each replicate (and the replicates, for a standard error) from a pilot with independent histories, by the variances between replicates and between histories and their costs (from the `StandardDeviation` of a metric over the histories). `exact_expectations` computes the expected capability and availability of a mission without restoration exactly (the sets of operating satellites by their probabilities, from the survival of each launch group, with planned replacements), without sampling error. Histories may be drawn from stressed failures for importance sampling (`simulate_many(stress=...)`: hazards and launch failures times a factor, each history weighted by its likelihood ratio censored at the end of the mission, `Lifetime.stressed` and `MissionHistory.weight`), which `summarize_histories` weighs in every statistic, with the effective number of histories: the probabilities of rare losses with 30 to 70 times less variance. + - Life-cycle costs of deployments for trade studies (`tradespace.CostModel`): the development of each type of satellite, the production of its units on a learning curve (`SatelliteCost`), launches (per launch, or prices per satellite and kg, `LaunchCost`), operations (`OperationsCost`), replacements, and spares in orbit, dated by the deployment for their present value at a discount rate (`CostEstimate.present_value`, metric `cost present`) and annual costs (`CostEstimate.annual`, metric `cost peak annual`), with growth factors for cost risk (such as uncertain parameters, whose quantiles over replicates give the cost at a confidence level). TAT-C does not include cost-estimating relationships: the costs are given by the study. Fingerprints describe dataclasses (such as cost models) by their fields. + - Function `tradespace.confirm` (and class `Confirmation`), which evaluates selected designs (such as a front) with new replicates that played no part in their selection, removing the optimism of the selection (the winner's curse, `Confirmation.optimism`). `ResultStore` keys evaluations by the fingerprint of a study (`Study.fingerprint`, a hash of `Study.definition`, see `get_definition`: its seed, use of common random numbers, design space, and build and evaluation functions, with the data frames they are given described by their content, the version of Python, and the source of the modules of TAT-C and resource files they depend on, found from their imports) and keeps each definition, so that variants of a study share a store without mixing their evaluations, and a study warns of evaluations of the same study with other code (of its functions, of TAT-C, or of Python), which are not reused, naming what differs (`fingerprint.compare_definitions`); `Study.prune` removes them (and not the evaluations of other studies that share the store). Changes to TAT-C that a study does not depend on (such as to modules it does not use) keep its results. Namespaces of stores and caches are optional, for what fingerprints cannot see (data that functions read from files, and the code of other modules). `refine` treats designs with fewer than `min_replicates` (5) as uncertain whatever their probability, adds the replicates left to `max_replicates` in a last partial step, and warns if designs remain uncertain without a tolerance. `sensitivity` gives adjusted shares (epsilon squared) by default, without the share that the levels of a variable explain by chance (`adjusted=False` for correlation ratios). + - The schedule and cost model of a `tradespace.MissionPlan` may be functions of the design, which size them by its values with relationships of the study's own, such as the costs of a type of satellite from its payload or the capacity of launches to the design's altitude; launches limited in mass take the masses of the satellites from the plan (`masses`). The `launch_mass_capacity` of a `DeploymentSchedule` may be a function of a plane, for planes at different inclinations. + - The start of the period of `tradespace.Observations` may be a value of the design (`start_of` and `end_of` give a design's period), such as an uncertain epoch drawn for each replicate over the mission, whose observations are cached apart, so that replicates average over the geometry and seasons of the mission that the one window of quasi-static phases misses (see `evaluate_phases`). The schedule of deployments states that a design life does not retire a satellite that is not replaced, and simulations that a planned replacement whose launch fails is not flown again. + - Utilities of the metrics of designs (`tradespace.Utility`), for trade spaces of utility against cost: a single-attribute utility of each metric (`LinearUtility`, `ExponentialUtility` of a risk attitude, `PiecewiseUtility`, or any function), combined by weights additively or in Keeney and Raiffa's multiplicative form. A utility is a metric of any statistic (its `Mean` is the expected utility over the replicates, and a utility given as a statistic of `Criteria` is its mean), computed in each replicate, and gives the utility of each row of a data frame (such as a summary of the means of designs). Statistics name the columns they need (`Statistic.columns`). + - Staged deployments (`tradespace.Stage`, argument `stages` of `DeploymentSchedule.plan` and `MissionPlan`, which may give the stages of each design): planes that are produced and launched only if a rule decides to, at times during the mission, from what it knows then (`Decision`: the satellites operating, the history so far, and, through the design, its uncertain parameters and scenario), after a lead time and at the next launch slots, and replaced and restored as other planes. Rules may also read the capability of the satellites operating at a decision (`Decision.capability`, the study's metrics of their observations, as of a phase), which the evaluations of an `ObservationStudy` give each deployment (`Deployment.capability`, a `tradespace.Capability` of its satellites, observations, and cached phases, which also caches the phases of studies without failures), such as for a plane deployed only if those in orbit fall short. A stage that is not deployed is neither produced, launched, nor priced; `MissionHistory.decided` gives when each was deployed, and its metrics the `stages deployed`. Exact expectations of missions without restoration (`exact_expectations`) need deployments that are not staged, so that studies of staged deployments sample their histories. + - Scenarios of studies (argument `scenarios` of `tradespace.Study`): conditions under which designs are compared rather than averaged over, each giving fixed values or uncertain parameters of the design space other values (`Design.realize` takes a `scenario`), so that each design is evaluated in each scenario (recorded as `scenario`, and judged in each with criteria `by` it). Each scenario's evaluations are stored by its values, so that a scenario added later is evaluated alone. Function `tradespace.robustness` gives each design's Pareto trace (the share of scenarios in which it is efficient) and its regret in each scenario (the improvement in every objective it would need to match the scenario's front) and the largest. The metrics of an `ObservationStudy` (and of `PhaseCache`, `evaluate_histories`, and `exact_expectations`) are given the realized design if they have a parameter named `design`. + - Criteria across the scenarios of a study (`tradespace.Across`, argument `across` of `Criteria`), which judge each design once by its worst or its (weighted) mean statistics over the scenarios (or the groups of another column), so that searches find designs robust to scenarios; a requirement may be met in every scenario while objectives are means. + - Function `tradespace.attribute_variance` (and class `Attribution`), which attributes the variance of metrics between the replicates of each design to its uncertain parameters (or groups of them): the share that each causes, alone or with others, and the share that knowing it would remove, with standard errors, by evaluating designs with one parameter drawn as in other replicates and the others held (which works for seeds, whose values do not order outcomes); `Attribution.summary` pools the shares of several designs, and `Attribution.differences` attributes the variance of the differences between pairs of designs, from the same evaluations (parameters that act alike on both cancel, with common random numbers). `Design.realize` and `Study.run` take a `shift`, which draws named parameters as in other replicates (kept apart in a `ResultStore` as a variant of the replicates), and `DesignSpace.uncertain_paths` lists the uncertain parameters. + - Structured cost risk (after Maier, Yeakel, and Wendoloski, "Cost Variance Analysis in Constellation Architecture Studies," 2023): growth factors of each type of satellite (by kind, for development, production, and launches, in `CostModel.estimate` and `MissionPlan.growth`), and the costs of types of satellites as sums of their components (`tradespace.Component`, `SatelliteCost.components`), whose growth has a distribution by maturity (such as `tradespace.Triangular`), correlated between components (`CostModel.correlation`). `CostModel.draw` draws the growth of the components from standard normal scores of the components and a common score, which `tradespace.risk_space` declares as uncertain parameters of a design space (named by `MissionPlan.scores`, also of a nested group), so that common random numbers give the designs that share a component the same growth of it; without drawn growth, components cost their expected growth. Types of satellites that share a component (by name) develop it once in a deployment. Production in blocks (`SatelliteCost.block_size`): each block after the first develops its type again (a share of its development, `redevelopment`) before its first unit is produced, and restarts the learning curve; `CostEstimate.blocks` counts the blocks of each type. Function `tradespace.exceedance` gives the probability that a metric of each design exceeds that of each other in the same replicate (such as that one design costs more than another), and `plot_exceedance` plots them as a matrix. The validation notebook `ValidateCostVarianceNSOSA` reproduces the paper's example of two NSOSA constellations that share a configuration. + - Searches with Optuna accept categorical options that depend on earlier decisions (a parameter for each set of options), use TPE with a constant liar in batches by default (which spreads the trials of a batch), and stop after `max_designs` designs evaluated (trials that suggest designs evaluated before are told their objectives without evaluating them again). A design infeasible in some of its replicates violates its feasibility by their share (`Evaluations.infeasibility`), and the first design evaluated in a search is evaluated alone, to check that evaluations give one record each. `Study` records errors of evaluations as infeasible, without storing them, with `errors="record"`. Enumeration walks the items of unordered repetitions in one order only, and `DesignSpace.size` counts designs without keeping them. Pareto fronts are found by a vectorized sweep in lexicographic order that compares designs only with the efficient designs before them, and fronts with tolerances by comparing designs only with the efficient designs without tolerances (which dominate every design that any design dominates within the tolerances), in blocks of bounded memory. + - Studies of the observations of constellations (`tradespace.ObservationStudy`): the targets of each replicate (`Targets`, fixed or generated from a seed of the design), the observations of each satellite, cached on disk (`Observations`), the metrics of the observations, and, with a `MissionPlan`, the costs of the deployment and the summaries of its phases or of the histories of its `Failures`. Plots of the results of studies (`plot_designs`, `plot_progress`, and `plot_means`, with matplotlib, in the `tradespace` extra), and the hypervolume of a search as it proceeds (`hypervolume_progress`). + - The steps of trade studies share their arguments and outcomes: `tradespace.refine(study, criteria, results)`, `confirm(study, criteria, results)` (by default, the front of the results), `screen(studies, criteria, designs)` (with criteria for each stage), and `attribute_variance(study, metrics, designs)` take designs as `Design` objects, their keys, or rows of a summary or of results, and `Refinement`, `Confirmation`, `Screening`, and `Search` give their `results`, the `summary` of their designs, and the `designs`. `DesignSpace.designs_of` rebuilds designs from rows of their values, which summaries keep (also those of `pareto_probability`, `confirm`, and `screen`), and `DesignSpace.extend`, `DesignSpace.design(design, **overrides)`, and `Study.replace` make variants of design spaces, designs, and studies. `summarize` takes criteria or a mapping of objectives (as the other functions do), and other `statistics` by name; `pareto_front`, `pareto_ranks`, `hypervolume`, `sensitivity`, and `main_effects` raise an error given the results of a study (a row per replicate) instead of a summary. Studies with a mission plan record the years by which it is `deployed`, and the parts of observation studies that refer to values of designs are typed as a `Reference`. Columns: ` se`, ` mission` for the mean over the phases of a mission, ` histories p`, ` histories std`, and `P() histories` for statistics over the histories of failures, and `pareto_trace` and `max_regret`. Package `tradespace` exports the functions and classes of trade studies; the parts from which they are made (such as `PhaseCache`, `Layout`, `configure`, and the fingerprints) are imported from its modules. + - Values of `tradespace` designs by the paths of the columns of results (`d["layout.walker.planes"]`, also in the callables of design spaces and in references), choices equal to the names of their branches, and reserved names of children that views and designs give otherwise (such as `values` and `key`). `Repeat` counts may be `Integer`, `Categorical`, `Fixed`, or `Derived`; `DesignSpace.design` checks decisions against their domains; and the constructors of uncertain parameters (with `Uncertain.triangular`) take nominal values and name their distributions. Summaries of criteria give whether each design is efficient (`pareto`, also of `confirm`, `screen`, and searches), and designs with a missing objective are not efficient. `Study.realize` realizes a design as a study does (in a scenario), and an `ObservationStudy` gives the mission of a design as its evaluation plans it (`mission_of`). `Study.prune` removes a study's evaluations with other code (and not those of other studies that share its store), `Observations.prune` removes the results of its caches with other code, and caches warn of results of other code once, in the main process. Fingerprints describe geometries by their content, ignore docstrings, and describe the functions of a study's own modules (such as one next to a notebook) by their code. Missions restore failures by default, and `Failures` sample histories with importance sampling (`stress`), control variates (`controls`), and spreads over the histories. Layouts describe themselves (`Layout.describe`) and are built at their own altitude (the given one is for layouts without one; `soc_space` keeps the altitude its planes are derived at). `plot_designs` colors some designs over the others (`highlight`, `label`, `others`, `front_label`), and `COLORS`, `INK`, and `GRAY` name the colors of plots. Each design confirmed gives its ` optimism`, `robustness` keeps the values of designs, and `Search.summary` keeps the designs the search found feasible. The simulation of missions is in module `simulation`. + - Decisions given to `tradespace.DesignSpace.design` by value are levels of their domains (`2.0` or `numpy.int64(2)` give the key of the enumerated design), designs and scopes tell whether they have a value (`"layout.walker.planes" in design`), and the items of a `Repeat` take slices. `DesignSpace.designs_of` gives a series of designs aligned to the rows of a data frame (`space.designs_of(summary).map(describe)`). Statistics given without names are named by convention (`Statistic.name`, such as `"cost p70"` for `Quantile("cost", 0.7)` and `"P(cost <= 150)"`), so that `statistics` may be a list, `summarize(results, criteria, statistics=...)` adds the means and spreads of other metrics to a summary of criteria, criteria `across` scenarios are summarized as others, and `Requirement.met` tells which values meet a requirement. An `ObservationStudy` counts the satellites and planes of a design's `layout` by default, gives the histories of a design's failures (`mission_of(design).histories()`) and its satellites, targets, and observations (`satellites_of`, `targets_of`, `observations_of`) as its evaluation realizes them, and `MissionPlan.policy` refers to each design's restoration policy (such as of `policy_space`). Fingerprints describe the classes and callable objects of a study's own modules by their attributes and the code of their methods, and tell studies that differ in constants apart from the same study with other code; `Observations.prune` removes only the results of its own analyses with other code. `plot_designs` colors designs by a column or by values of their rows (`by`), `plot_shares` plots shares of variance (of `sensitivity` or `attribute_variance`) as grouped bars with their standard errors, and `use_style` applies the style of the plots of trade studies (with constrained layouts) to the figures of a session. `robustness` gives each objective of a design in each scenario (` `). `Deployment.planes` are `PlannedPlane`s (type, satellites, and spares in orbit), replacements launch at the next slot that keeps the launch interval, and `Capability.evaluate` evaluates phases with a deployment's cached observations. Searches with Optuna are seeded by default (`seed=0`), and lives of satellites are drawn from uniform numbers (`Lifetime.from_uniform`, which subclasses implement). + - Designs of another design space (such as the space that a study's space extends) are evaluated in the study's space, and constraints are checked in each scenario: a design that violates them in a scenario is infeasible in it, and a constraint that gives `NaN` is violated. Children of design spaces may not take the names of the status columns of results (`design`, `feasible`, `error`, `seconds`, and `scenario`). `DesignSpace.design` takes the name of a branch for a choice (`space.design(base, layout="sso")`), unordered items are in the order of their levels, `Design.scenario` names the scenario of a realized design, `Design.realize` takes the `overrides` of a scenario, and `DesignSpace.check_uncertain` and `check_overrides` check the paths of uncertain parameters and of scenarios. The options of `Study` and `DesignSpace.sample` are keyword-only. Fingerprints describe the globals of a study's functions as they describe its given values (pydantic models, partials, objects of the study's own classes, containers by their content, and the functions of its own modules reached through them), and find the same study with other code alike in every version of Python. `Study.prune` also removes the definitions of a study without evaluations, warnings of studies and caches point at the code that runs them, and an evaluation that gives an empty data frame raises an error. + - Summaries give the share of the replicates of each design that are feasible (`feasible`, which requirements may name, such as `Requirement("feasible", ">=", 1)`), and judge designs by their feasible replicates, as searches do. Statistics are in module `statistics`, and summaries (`summarize` and `pareto_probability`) in module `summary`. The tolerances of criteria are `Criteria.tolerances`. Each step gives the designs it selects for the next step (`designs`: the efficient designs of a refinement or a search, the survivors of a screening, and the designs confirmed) and its `criteria`, with `Refinement.candidates` and `Refinement.evaluations` (those it added), `Search.evaluated`, and `Screening.history` (the results of every stage; its `results` are those of the last stage, which other steps take). `robustness` takes the column of the scenarios from the criteria, gives ` ` for every objective that is not a value of designs, and gives an infinite regret for a missing objective. `optimize_pymoo` stops after `max_designs`, `screen` checks the share or number of designs it keeps (`keep`), `plot_designs` and `plot_means` draw the designs without a group (`by`) in gray, and `summarize` gives the spread of the mean of a `Utility`. + - The mission of each design of an observation study (module `plans`): `MissionPlan.policy` gives the restoration policy of each design (by default, the design's value `policy` if it has one, and otherwise restoring failed satellites; a policy, a function, or a reference to values that configure it, such as those of `policy_space`), with its spares in orbit (`RestorationPolicy.orbit_spares`, launched with their planes) and on the ground, and `ObservationStudy.mission_of` gives the `Mission` of a design (its deployment, phases, cost estimate, and histories) as its evaluation plans it (`MissionPlan.plan_mission`). With failures, the requirements on the phases of a study (`phases`) give the time until each history meets them, and `Failures` checks its options when it is made. Exact expectations fall back to the means of the histories for missions with too many sets of satellites (`expectations.MAX_SETS`). Planned replacements keep the launch interval, spares in orbit that are never used are not replaced at the end of their design life, launches are priced by the masses of the deployment, the phases of a mission are cached by the uncertain values of its replicate, and studies of staged deployments record the `stages deployed`. A deployment is planned with its restoration policy (`DeploymentSchedule.plan(policy=...)`, `Deployment.policy`), whose spares its planned history (`Deployment.planned`), its simulations (`Deployment.simulate(model)`), and its costs share, the options of `DeploymentSchedule.plan` and `ObservationStudy` are keyword-only, `layout_of` is exported, a layout names its pattern (`pattern`), `Stage` takes numpy values, and the development of a staged type that is never deployed is the cost of its option. References to values of designs are in module `references`. + - Fingerprints describe objects by what their `__fingerprint__()` returns (designs, and caches of satellites by their function and namespace), so that a study whose functions use them is evaluated again when they change. Decisions that name no child of a design space raise an error (also those of designs of another space, in a study's space), `errors="record"` records the errors of realizing a design, metrics may not be named `scenario`, replicates and shifts must not be negative, and a design space takes a single constraint. Module `references` reads designs: `configure` and `value_of` are exported, and functions given the design follow one convention (a parameter named `design`). `Design.uncertain_values()` gives the values of a design's uncertain parameters, and `Statistic` and the classes of the steps (`Refinement`, `Confirmation`, `Screening`, `Search`, `Attribution`) are exported. `summarize` gives the spread of the statistics it reports across scenarios (of the worst scenario, or of the weighted mean over the replicates that the scenarios share) and leaves out spreads that are zero for every design. Statistics may not take the names of columns of the results, and `summarize_histories` names the share of histories that meet a requirement `P() histories`. `refine` charges the evaluations of every scenario to its budget (`Refinement.rounds` gives its rounds), `pareto_probability` leaves out of a resample a design without a feasible replicate drawn, `main_effects` orders its bins, searches with pymoo leave the caller's algorithm unchanged, and Optuna's constraints of requirements have distinct names. `exceedance` gives the `shared_replicates` of two designs. A ground spare goes up at the next launch slot, the planes of a stage launch in the order they are ready, and `MissionHistory.deployed` is infinite for a deployment that outlasts the mission. `SatelliteCache` keeps a context with each namespace, `Observations` generates the targets of a replicate only to observe them, an `ObservationStudy` computes the metrics of all of a design's satellites once, exact expectations are faster (module `expectations`), and the options of `Study.run`, `designs_of`, `ResultStore`, `SatelliteCache`, and `Repeat` are keyword-only. + - A `tradespace.Study` may describe its designs (`describe`, a `description` column of the results that summaries keep, outside the fingerprint), and `DesignSpace.enumerate(designs)` gives every design that extends designs of a space it extends (such as each design with each policy). `summarize` gives the statistics of designs with the spreads of their means (or without, `spread=False`) and takes criteria or a mapping of objectives, with metrics and other statistics in `statistics`; `pareto_probability` gives the standard errors of means as `summarize` does, and of other objectives by its bootstrap. `Failures` take statistics over the histories (`Quantile`, `Probability`, and `StandardDeviation`) and require a `seed`, a study's requirements on phases (`phases`) apply with or without failures, and each field of a `MissionPlan` is a value or a reference to the design (also `stages`), with the restoration policy of the design's value `policy` by default. The masses of satellites are given by the plan (`MissionPlan.masses`), `Triangular` takes its `mode` by keyword, the options of the optimizers are keyword-only (`optimize_optuna(n_trials=100)`), `plot_designs` rings the efficient designs (`pareto`) by default and labels designs with `annotate`, and the outcomes of steps give their `results`, `summary`, `designs`, and `criteria` first (`Screening.summaries` gives the summaries of every stage in one frame). The parts of criteria, design spaces, stores, missions, and observations that only the module uses are private, and `DesignSpace` neither encodes designs nor documents the internals of its optimizers. + - `tradespace.Targets` take a fixed seed (an integer) or a value of the design, the layout fragments a single constraint or several, and the per-type `masses` of a `MissionPlan` references to values of the design. Designs list their values for completion (`dir`) and suggest the names of misspelled ones. Fingerprints describe statistics by their attributes (such as the quantiles of `Failures`). Phases take at most one requirement on each metric, and a design's value `policy` that neither is nor configures a policy raises an error. The summaries of `Search`, `Screening`, and `Confirmation` give the spreads of means, as `summarize` does; rows without a value of `by` are judged as a group of their own; and `plot_designs` annotates only with a front. Statistics over histories of equal weights are those over replicates, control variates keep infinite means, and exact expectations enumerate at most 4,096 sets of satellites (`MAX_SETS`, about 12 satellites) before failures fall back to histories. + - Trade space tutorial (`docs/examples/tradespace`): eight notebooks that follow one trade of constellations, each adding one idea to those before it: `EvaluateTradeSpace` (design space, study, and Pareto front), `ExplainTradeSpace` (sampling error, revisits, and sensitivity), `SearchTradeSpace` (hypervolume, screening, and optimizers), `RankUncertainDesigns` (probability of efficiency, refinement, confirmation, and requirements on statistics), `CompareScenarios` (scenarios, regret, and searches across scenarios), `TradeCostAndUtility` (costs with uncertain growth, budgets, and utility), `PlanDeployment` (phases and staging), and `PlanForFailures` (failures, restoration policies, and the attribution of variance). Each notebook defines what it introduces, and imports what earlier notebooks defined from `trade_space_example.py`. + - The `RunOSSEMonsoon` example declares its constellation trade as a design space, caches the looks of each satellite, evaluates its replicates in parallel, and finds its Pareto-efficient designs. Changed: + - The OSSE examples (`RunOSSEMonsoon`, `RunOSSEHurricane`) are in `docs/examples/osse`, and download the Nature Run to a `data` directory beside them. - Instruments reject unknown fields, rather than ignoring them: a misspelled field in the data of a `PointedInstrument` previously gave an `Instrument` with a field of regard of 180 degrees. - Dumping a `Satellite` or other system with a `PointedInstrument` or `ConicalInstrument` keeps the fields of its class, and loading the data restores it. Previously, these instruments were written and restored as a base `Instrument`, without a warning. Data written by earlier versions lacks these fields, so it still loads as an `Instrument`. - Dumping a space system with an `attitude` omits the `velocity_frame` of its instruments, which the attitude sets, so the data can be loaded. diff --git a/README.md b/README.md index faf5380..79e388a 100644 --- a/README.md +++ b/README.md @@ -4,7 +4,7 @@ [![Python Versions](https://img.shields.io/pypi/pyversions/tatc.svg)](https://pypi.org/project/tatc/) [![Unit Tests](https://github.com/code-lab-org/tatc/actions/workflows/unit-test.yml/badge.svg)](https://github.com/code-lab-org/tatc/actions/workflows/unit-test.yml) [![Documentation](https://readthedocs.org/projects/tatc/badge/?version=latest)](https://tatc.readthedocs.io) -[![License](https://img.shields.io/badge/license-BSD--3--Clause-blue.svg)](LICENSE) +[![License](https://img.shields.io/badge/license-BSD--3--Clause-blue.svg)](https://github.com/code-lab-org/tatc/blob/main/LICENSE) [![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.17363628.svg)](https://doi.org/10.5281/zenodo.17363628) The Tradespace Analysis Toolkit for Constellations (TAT-C) provides low-level @@ -35,6 +35,7 @@ Note: the following optional dependencies are available with bracket notation: * `pip install -e ".[examples]"`: for running optional examples * `pip install -e ".[osse]"`: for running optional observing system simulation experiment (OSSE) examples * `pip install -e ".[preprocess]"`: for preprocessing functions (e.g., terrain masks) + * `pip install -e ".[tradespace]"`: for parallel trade studies and searches with optimizers (joblib, Optuna, and pymoo) * `pip install -e ".[validation]"`: for running validation notebooks (includes `examples` and `preprocess`) Multiple optional dependencies can be installed with a comma-separated list (e.g., `pip install -e ".[dev,examples]"`) @@ -100,12 +101,12 @@ pylint --rcfile=.pylintrc src/tatc ## License This project is licensed under the BSD 3-Clause License — see -[LICENSE](LICENSE) for details. +[LICENSE](https://github.com/code-lab-org/tatc/blob/main/LICENSE) for details. ## Citation If you use TAT-C in your research, please cite it using the metadata in -[CITATION.cff](CITATION.cff), or the DOI badge above for the latest release. +[CITATION.cff](https://github.com/code-lab-org/tatc/blob/main/CITATION.cff), or the DOI badge above for the latest release. ## Contact diff --git a/docs/api_reference/analysis/index.rst b/docs/api_reference/analysis/index.rst index 83bc153..7bc2418 100644 --- a/docs/api_reference/analysis/index.rst +++ b/docs/api_reference/analysis/index.rst @@ -8,6 +8,7 @@ Analysis functions simulate mission operation to compute key performance metrics :maxdepth: 1 coverage + sufficiency track coincidence feature_coverage diff --git a/docs/api_reference/analysis/sufficiency.rst b/docs/api_reference/analysis/sufficiency.rst new file mode 100644 index 0000000..477ef6a --- /dev/null +++ b/docs/api_reference/analysis/sufficiency.rst @@ -0,0 +1,23 @@ +Statistical Sufficiency +======================= + +.. automodule:: tatc.analysis.sufficiency + :no-members: + +Estimate Sampling Errors +------------------------ +.. autofunction:: tatc.analysis.estimate_sampling_error + +.. autofunction:: tatc.analysis.sampling_error_variance + +Sample Fields +------------- +.. autofunction:: tatc.analysis.sample_field + +.. autofunction:: tatc.analysis.compare_sampled_means + +Revisits and Local Times +------------------------ +.. autofunction:: tatc.analysis.compute_revisit_statistics + +.. autofunction:: tatc.analysis.compute_local_time_coverage diff --git a/docs/api_reference/generation/index.rst b/docs/api_reference/generation/index.rst index a376c32..475089a 100644 --- a/docs/api_reference/generation/index.rst +++ b/docs/api_reference/generation/index.rst @@ -31,6 +31,10 @@ Weights for random points can be read from a GeoTIFF raster with :func:`tatc.preprocess.read_raster_weights` (requires the optional `preprocess` dependencies, ``pip install tatc[preprocess]``). +Rotated Lattice +--------------- + + Cells ===== diff --git a/docs/api_reference/index.rst b/docs/api_reference/index.rst index a09a2b7..1165539 100644 --- a/docs/api_reference/index.rst +++ b/docs/api_reference/index.rst @@ -11,5 +11,6 @@ The following provide documentation on the Python API to TAT-C. catalog generation/index analysis/index + tradespace/index preprocess/index utils/index diff --git a/docs/api_reference/tradespace/define.rst b/docs/api_reference/tradespace/define.rst new file mode 100644 index 0000000..7a31b5f --- /dev/null +++ b/docs/api_reference/tradespace/define.rst @@ -0,0 +1,102 @@ +============== +Design Spaces +============== + +.. automodule:: tatc.tradespace.space + :no-members: + +Design Spaces and Designs +========================= + +.. autoclass:: tatc.tradespace.DesignSpace + :members: enumerate, size, sample, design, designs_of, extend, uncertain_paths + +.. autoclass:: tatc.tradespace.Design + :members: flat, uncertain_values, realize, values, decisions, scenario + +.. autodata:: tatc.tradespace.space.RESERVED_NAMES + :annotation: + +.. autodata:: tatc.tradespace.space.STATUS_COLUMNS + :annotation: + +Variables and Values +==================== + +.. autoclass:: tatc.tradespace.Real + +.. autoclass:: tatc.tradespace.Integer + +.. autoclass:: tatc.tradespace.Categorical + +.. autoclass:: tatc.tradespace.Fixed + +.. autoclass:: tatc.tradespace.Derived + +.. autoclass:: tatc.tradespace.Uncertain + :members: uniform, normal, triangular, choice, seed + +.. autoclass:: tatc.tradespace.Choice + +.. autoclass:: tatc.tradespace.Repeat + +.. autoexception:: tatc.tradespace.Infeasible + +.. autoclass:: tatc.tradespace.nodes.Variable + :members: domain + +Building Blocks of Constellations +================================= + +Fragments of design spaces of common layouts of constellations, and of the +policies that restore their failures, whose values a study builds into +satellites (see :doc:`missions` for the layouts themselves). + +.. autofunction:: tatc.tradespace.walker_space + +.. autofunction:: tatc.tradespace.sso_planes_space + +.. autofunction:: tatc.tradespace.planes_space + +.. autofunction:: tatc.tradespace.soc_space + +.. autofunction:: tatc.tradespace.mog_space + +.. autofunction:: tatc.tradespace.policy_space + +.. autofunction:: tatc.tradespace.build_constellation + +.. autofunction:: tatc.tradespace.count_satellites + +.. autofunction:: tatc.tradespace.count_planes + +Views of Values +=============== + +The callables of a design space (bounds, derived values, and constraints) +and the values of designs are views of the values decided so far. + +.. autoclass:: tatc.tradespace.values.Values + +.. autoclass:: tatc.tradespace.values.ChoiceValues + :members: choice, value + +.. autoclass:: tatc.tradespace.values.RepeatValues + :members: count + +.. autoclass:: tatc.tradespace.values.Scope + +.. autofunction:: tatc.tradespace.values.generic_path + +Reading Designs +=============== + +.. automodule:: tatc.tradespace.references + :no-members: + +.. autodata:: tatc.tradespace.references.Reference + :annotation: + +.. autofunction:: tatc.tradespace.value_of + +.. autofunction:: tatc.tradespace.configure diff --git a/docs/api_reference/tradespace/evaluate.rst b/docs/api_reference/tradespace/evaluate.rst new file mode 100644 index 0000000..cb72ebc --- /dev/null +++ b/docs/api_reference/tradespace/evaluate.rst @@ -0,0 +1,72 @@ +======= +Studies +======= + +Trade Studies +============= + +.. autoclass:: tatc.tradespace.Study + :members: run, realize, replace, prune, workers, definition, fingerprint + +Observation Studies +=================== + +.. automodule:: tatc.tradespace.observations + :no-members: + +.. autoclass:: tatc.tradespace.ObservationStudy + :members: satellites_of, targets_of, observations_of, mission_of, prune + +.. autoclass:: tatc.tradespace.Observations + :members: start_of, end_of, prune, __call__ + +.. autoclass:: tatc.tradespace.Targets + +The parts of observation studies read the values of designs by references +(see :doc:`define` for :py:data:`tatc.tradespace.references.Reference` and +:py:func:`tatc.tradespace.value_of`). + +Missions of Designs +=================== + +.. automodule:: tatc.tradespace.plans + :no-members: + +.. autoclass:: tatc.tradespace.MissionPlan + :members: plan_mission + +.. autoclass:: tatc.tradespace.Failures + +.. autoclass:: tatc.tradespace.mission.Mission + :members: phases, estimate, histories, capability, requirements + +Stores of Results +================= + +.. autoclass:: tatc.tradespace.ResultStore + :members: clear + +Caches of Satellites +==================== + +.. automodule:: tatc.tradespace.cache + :no-members: + +.. autoclass:: tatc.tradespace.SatelliteCache + :members: __call__, prune, clear_memory, folder, fingerprint, hits, misses + +.. autofunction:: tatc.tradespace.cache.get_satellite_key + +Fingerprints +============ + +.. automodule:: tatc.tradespace.fingerprint + :no-members: + +.. autofunction:: tatc.tradespace.fingerprint.get_fingerprint + +.. autofunction:: tatc.tradespace.fingerprint.get_definition + +.. autofunction:: tatc.tradespace.fingerprint.compare_definitions + +.. autofunction:: tatc.tradespace.fingerprint.describe diff --git a/docs/api_reference/tradespace/index.rst b/docs/api_reference/tradespace/index.rst new file mode 100644 index 0000000..f219c0f --- /dev/null +++ b/docs/api_reference/tradespace/index.rst @@ -0,0 +1,153 @@ +=========== +Trade Space +=========== + +.. automodule:: tatc.tradespace + :no-members: + +The :doc:`../../examples/tradespace/index` shows each step on a study of the +observations of constellations, one step at a time. + +Steps of a Trade Study +====================== + +A trade study takes a few steps, each of which takes the outcome of the one +before:: + + from tatc.tradespace import ( + Criteria, DesignSpace, Integer, ResultStore, Study, Uncertain, + confirm, refine, summarize, + ) + + space = DesignSpace(planes=Integer(1, 4), per_plane=Integer(1, 4), seed=Uncertain.seed()) + study = Study(space, build, evaluate, replicates=5, store=ResultStore("results.sqlite")) + results = study.run() # a row per design and replicate + + criteria = Criteria({"satellites": "min", "coverage": "max"}) + summary = summarize(results, criteria) # a row per design, with `pareto` + front = summary[summary.pareto] + + refinement = refine(study, criteria, results) # replicates where efficiency is uncertain + confirmation = confirm(study, criteria, refinement.results) # the front, with new replicates + +1. **Define** a design space (:doc:`define`): design variables, choices and + repetitions, constraints, and uncertain parameters, which each replicate + of a design draws. +2. **Evaluate** designs with a study (:doc:`evaluate`): a function builds + each realized design and another evaluates it, in parallel, with a store + of the evaluations. An `ObservationStudy` evaluates the observations of + constellations, and their deployment, costs, and failures + (:doc:`missions`). +3. **Judge** designs by criteria (:doc:`judge`): objectives and + requirements on statistics of their replicates, summarized with a row per + design, and their Pareto efficiency. +4. **Settle** the uncertainty of the replicates, or **search** spaces too + large to enumerate (:doc:`search`). Each of these steps takes a study and + criteria, and returns its `results`, the `summary` of its designs, the + `designs` themselves, for the next step, and its `criteria` (as an outcome, + such as a `Refinement`, see :doc:`search`). + +Results and Summaries +===================== + +A study gives **results**: a row per evaluation (a design in a replicate, +and a scenario), with the key of the design (`design`), the `replicate`, the +values of the design by path (see `Design.flat`), whether it is `feasible`, +and its metrics. A **summary** has a row per design (and per group of the +criteria's `by`): statistics over its feasible replicates, the number of +them (`replicates`), the share of its replicates that are `feasible` (which +requirements may name), and the values of the design, and, of criteria, the +`violation` of their requirements, whether the design meets them +(`meets_requirements`), and whether it is efficient (`pareto`). Functions +take one or the other: + +.. list-table:: + :header-rows: 1 + + * - Take results (a row per replicate) + - Take summaries (a row per design) + * - `summarize`, `pareto_probability`, `hypervolume_progress`, + `robustness`, `exceedance`, `refine`, `confirm`, `plot_means` + - `pareto_front`, `pareto_ranks`, `hypervolume`, `sensitivity`, + `main_effects`, `plot_designs` + +The functions of summaries raise an error if a design has several rows, as +in the results of a study: summarize them first. The steps that evaluate +designs (such as `confirm` and `attribute_variance`) take designs, their +keys, or rows of either (see `DesignSpace.designs_of`). + +Columns +------- + +Columns named after a metric or a statistic take a suffix after a space, +and columns that TAT-C defines are named in snake case: + +* statistics over the replicates of a design: named by the criteria, or by + convention if given without names (see `Statistic.name`, such as + `"cost p70"` for `Quantile("cost", 0.7)`), the means of metrics by + their names, each mean followed by its spread, ` std` and + ` se` (by `summarize`, and by `pareto_probability`, which gives + the standard error of an objective that is not a mean by its bootstrap, + left out where they are zero for every design), and of confirmed designs, + ` selected` (by the replicates that selected them) and + ` optimism`. A statistic other than the mean of a metric must not have the + name of a column of the results. +* statistics within a replicate, over the mission of a design (see + `ObservationStudy`): ` mission` (the mean over the phases of the + mission), ` time` (when the phases first meet a requirement), and, + over the histories of its failures, ` histories p`, + ` histories std`, and `P() histories`. +* columns of judgments: `violation`, `meets_requirements`, `pareto`, + `pareto_rank`, `pareto_probability`, `requirements_probability`, + `pareto_trace`, `max_regret`, and the ` regret` of each scenario. + +Designs and Their Variants +========================== + +Results keep the values of designs, from which `DesignSpace.designs_of` +rebuilds them, so that the steps of a study take designs as `Design` +objects, their keys, or rows of a summary or of results. A design gives its +values by attribute (`d.layout.planes`) or by the path of a column of the +results (`d["layout.walker.planes"]`, see `Values`), and a study realizes +it as it evaluates it (`Study.realize`, and, of an `ObservationStudy`, +`satellites_of`, `observations_of`, and `mission_of`, whose `Mission` gives +its deployment, phases, cost estimate, and histories):: + + confirmation = confirm(study, criteria, results, summary[summary.pareto]) + +A variant of a design space adds or replaces children +(`DesignSpace.extend`), and its designs take the decisions of a design of +the other (`DesignSpace.design`). A variant of a study replaces some of its +arguments (`Study.replace`):: + + policies = space.extend(policy=policy_space(orbit_spares=Integer(0, 1))) + designs = [policies.design(d, policy=p) for d in front_designs for p in policy_designs] + results = study.replace(space=policies, replicates=20).run(designs) + +The parts of an `ObservationStudy` (such as its targets and mission plan) +refer to values of designs by a `Reference` (see +:py:data:`tatc.tradespace.references.Reference`): a name or path of a +value, or a function of the realized design. + +Stores of Results +================= + +A `ResultStore` keeps the evaluations of studies, keyed by the fingerprint +of each study's definition (see `Study.fingerprint`), so that a study that is +run again takes its evaluations from the store, and variants of a study +(other settings, design spaces, or scenarios) share a store without mixing +their evaluations. A namespace of the store identifies only what +fingerprints cannot see (such as data that the functions read from files). A +study warns if the store has evaluations of the same study with other code +(of its functions, of TAT-C, or of Python), which it does not reuse +(`Study.prune` removes them, and not the evaluations of other studies that +share the store). + +.. toctree:: + :maxdepth: 1 + + define + evaluate + judge + search + missions diff --git a/docs/api_reference/tradespace/judge.rst b/docs/api_reference/tradespace/judge.rst new file mode 100644 index 0000000..bf3f68d --- /dev/null +++ b/docs/api_reference/tradespace/judge.rst @@ -0,0 +1,129 @@ +======================= +Criteria and Summaries +======================= + +Criteria, Statistics, and Requirements +====================================== + +.. automodule:: tatc.tradespace.criteria + :no-members: + +.. autoclass:: tatc.tradespace.Criteria + :members: names, metrics + +.. autoclass:: tatc.tradespace.Requirement + :members: met, violation + +.. autoclass:: tatc.tradespace.Across + +.. automodule:: tatc.tradespace.statistics + :no-members: + +.. autoclass:: tatc.tradespace.Mean + +.. autoclass:: tatc.tradespace.StandardDeviation + +.. autoclass:: tatc.tradespace.Minimum + +.. autoclass:: tatc.tradespace.Maximum + +.. autoclass:: tatc.tradespace.Quantile + +.. autoclass:: tatc.tradespace.Probability + +.. autoclass:: tatc.tradespace.Statistic + :members: name, metric, reduce + +Summaries +========= + +.. automodule:: tatc.tradespace.summary + :no-members: + +.. autofunction:: tatc.tradespace.summarize + +.. autofunction:: tatc.tradespace.pareto_probability + +Pareto Efficiency +================= + +.. automodule:: tatc.tradespace.pareto + :no-members: + +.. autofunction:: tatc.tradespace.pareto_front + +.. autofunction:: tatc.tradespace.pareto_ranks + +.. autofunction:: tatc.tradespace.hypervolume + +.. autofunction:: tatc.tradespace.hypervolume_progress + +Comparisons +=========== + +.. automodule:: tatc.tradespace.comparison + :no-members: + +.. autofunction:: tatc.tradespace.exceedance + +Scenarios +========= + +.. automodule:: tatc.tradespace.scenarios + :no-members: + +.. autofunction:: tatc.tradespace.robustness + +Sensitivity +=========== + +.. autofunction:: tatc.tradespace.sensitivity + +.. autofunction:: tatc.tradespace.main_effects + +Utility +======= + +.. automodule:: tatc.tradespace.utility + :no-members: + +.. autoclass:: tatc.tradespace.Utility + :members: columns, scaling, evaluate, __call__ + +.. autoclass:: tatc.tradespace.LinearUtility + +.. autoclass:: tatc.tradespace.ExponentialUtility + +.. autoclass:: tatc.tradespace.PiecewiseUtility + +Plots +===== + +.. automodule:: tatc.tradespace.plotting + :no-members: + +.. autofunction:: tatc.tradespace.plot_designs + +.. autofunction:: tatc.tradespace.plot_means + +.. autofunction:: tatc.tradespace.plot_exceedance + +.. autofunction:: tatc.tradespace.plot_progress + +.. autofunction:: tatc.tradespace.plot_shares + +.. autofunction:: tatc.tradespace.style_axes + +.. autofunction:: tatc.tradespace.use_style + +.. autodata:: tatc.tradespace.plotting.STYLE + :annotation: + +.. autodata:: tatc.tradespace.plotting.COLORS + :annotation: + +.. autodata:: tatc.tradespace.plotting.INK + :annotation: + +.. autodata:: tatc.tradespace.plotting.GRAY + :annotation: diff --git a/docs/api_reference/tradespace/missions.rst b/docs/api_reference/tradespace/missions.rst new file mode 100644 index 0000000..0ffb270 --- /dev/null +++ b/docs/api_reference/tradespace/missions.rst @@ -0,0 +1,162 @@ +=========================== +Constellations and Missions +=========================== + +The parts of observation studies (see `ObservationStudy`): the layouts of +constellations, their deployment, the failures of their satellites, the +phases and histories of their missions, and their costs. Studies use them +through a `MissionPlan` and `Failures`; the rest are for analyses of their +own. + +Constellations +============== + +.. automodule:: tatc.tradespace.constellations + :no-members: + +.. autoclass:: tatc.tradespace.constellations.Layout + :members: planes, orbits, names, describe, satellites, build + +.. autoclass:: tatc.tradespace.constellations.Plane + +.. autofunction:: tatc.tradespace.layout_of + +.. autoclass:: tatc.tradespace.constellations.WalkerLayout + +.. autoclass:: tatc.tradespace.constellations.SSOPlanesLayout + +.. autoclass:: tatc.tradespace.constellations.PlanesLayout + +.. autoclass:: tatc.tradespace.constellations.SOCLayout + +.. autoclass:: tatc.tradespace.constellations.MOGLayout + +.. autoclass:: tatc.tradespace.constellations.Layouts + +.. autofunction:: tatc.tradespace.constellations.plane_sizes + +.. autofunction:: tatc.tradespace.constellations.hours_to_time + +.. autofunction:: tatc.tradespace.constellations.remove_failures + +Deployment +========== + +.. automodule:: tatc.tradespace.deployment + :no-members: + +.. autoclass:: tatc.tradespace.DeploymentSchedule + :members: plan, launches_of + +.. autoclass:: tatc.tradespace.Stage + +.. autoclass:: tatc.tradespace.deployment.Deployment + :members: simulate, simulate_many, planned, phases, begin, end, deployed, units, stages, policy, capability + +.. automodule:: tatc.tradespace.events + :no-members: + +.. autoclass:: tatc.tradespace.events.PlannedPlane + +.. autoclass:: tatc.tradespace.events.Launch + +.. autoclass:: tatc.tradespace.events.Production + +.. autoclass:: tatc.tradespace.mission.Decision + :members: time, since_launch, stage, satellites_operating, history, stages_deployed, capability + +Failures +======== + +.. automodule:: tatc.tradespace.failures + :no-members: + +.. autoclass:: tatc.tradespace.FailureModel + :members: life_of + +.. autoclass:: tatc.tradespace.failures.Lifetime + :members: survival, hazard, cumulative_hazard, sample, from_uniform, dimensions, stressed + +.. autoclass:: tatc.tradespace.Exponential + +.. autoclass:: tatc.tradespace.Weibull + +.. autoclass:: tatc.tradespace.Bathtub + +.. autoclass:: tatc.tradespace.Piecewise + +.. autoclass:: tatc.tradespace.RestorationPolicy + :members: orbit_spares_of, ground_spares_of + +Missions +======== + +.. automodule:: tatc.tradespace.mission + :no-members: + +.. autoclass:: tatc.tradespace.mission.MissionHistory + :members: phases, metrics, in_orbit, deployed, decided + +.. autoclass:: tatc.tradespace.mission.Phase + :members: duration + +.. autoclass:: tatc.tradespace.mission.Failure + +.. autoclass:: tatc.tradespace.mission.Restoration + +.. autofunction:: tatc.tradespace.mission.evaluate_phases + +.. autofunction:: tatc.tradespace.mission.summarize_phases + +.. autoclass:: tatc.tradespace.mission.PhaseCache + :members: clear + +.. autoclass:: tatc.tradespace.mission.Capability + :members: evaluate, names + :special-members: __call__ + +.. automodule:: tatc.tradespace.histories + :no-members: + +.. autofunction:: tatc.tradespace.histories.evaluate_histories + +.. autofunction:: tatc.tradespace.histories.summarize_histories + +.. autofunction:: tatc.tradespace.histories.allocate_histories + +.. automodule:: tatc.tradespace.expectations + :no-members: + +.. autofunction:: tatc.tradespace.expectations.exact_expectations + +.. autoexception:: tatc.tradespace.expectations.ExactExpectationsError + +.. autodata:: tatc.tradespace.expectations.MAX_SETS + :annotation: + +Costs +===== + +.. automodule:: tatc.tradespace.cost + :no-members: + +.. autoclass:: tatc.tradespace.CostModel + :members: estimate, satellite_cost_of, draw, score_names, discount + +.. autoclass:: tatc.tradespace.SatelliteCost + :members: production, blocks, total_development, total_first_unit + +.. autoclass:: tatc.tradespace.Component + :members: uncertain, factor + +.. autoclass:: tatc.tradespace.Triangular + :members: mean, std, ppf + +.. autofunction:: tatc.tradespace.risk_space + +.. autoclass:: tatc.tradespace.LaunchCost + +.. autoclass:: tatc.tradespace.OperationsCost + +.. autoclass:: tatc.tradespace.cost.CostEstimate + :members: total, present_value, annual, metrics diff --git a/docs/api_reference/tradespace/search.rst b/docs/api_reference/tradespace/search.rst new file mode 100644 index 0000000..f75f7cc --- /dev/null +++ b/docs/api_reference/tradespace/search.rst @@ -0,0 +1,62 @@ +======================== +Refinement and Searches +======================== + +Each of these steps takes a study and criteria (or metrics), and returns an +outcome (exported for type hints, such as `Refinement`) of its `results`, the +`summary` of its designs, the `designs` themselves, which the next step +takes, and its `criteria`, in that order (an `Attribution` gives the +`shares` of the variance of each design, and their `summary`). + +Adaptive Replication +==================== + +.. autofunction:: tatc.tradespace.refine + +.. autoclass:: tatc.tradespace.Refinement + :members: results, summary, designs, criteria, rounds, candidates, evaluations + +Confirmation +============ + +.. autofunction:: tatc.tradespace.confirm + +.. autoclass:: tatc.tradespace.Confirmation + :members: results, summary, designs, criteria, optimism + +Screening +========= + +.. autofunction:: tatc.tradespace.screen + +.. autoclass:: tatc.tradespace.Screening + :members: results, summary, designs, criteria, history, summaries + +Attribution of Variance +======================= + +.. automodule:: tatc.tradespace.attribution + :no-members: + +.. autofunction:: tatc.tradespace.attribute_variance + +.. autoclass:: tatc.tradespace.Attribution + :members: results, shares, designs, by, summary, summary_of, differences + +Optimizers +========== + +.. automodule:: tatc.tradespace.optimization + :no-members: + +.. autofunction:: tatc.tradespace.optimize_optuna + +.. autofunction:: tatc.tradespace.optimize_pymoo + +.. autoclass:: tatc.tradespace.Search + :members: results, summary, designs, criteria, evaluated, state + +.. autofunction:: tatc.tradespace.optimization.make_pymoo_problem + +.. autoclass:: tatc.tradespace.optimization.Evaluations + :members: evaluate, results, worst, designs, search diff --git a/docs/examples/AssessSamplingSufficiency.ipynb b/docs/examples/AssessSamplingSufficiency.ipynb new file mode 100644 index 0000000..4deaf0c --- /dev/null +++ b/docs/examples/AssessSamplingSufficiency.ipynb @@ -0,0 +1,1295 @@ +{ + "cells": [ + { + "cell_type": "markdown", + "id": "949d68b3", + "metadata": {}, + "source": [ + "# Assess Sampling Sufficiency\n", + "\n", + "Observations sample a varying field, such as precipitation or temperature, at discrete times, and a study estimates a statistic of the field from the samples: for example, the mean precipitation at each place over a month. Whether a constellation samples a field *sufficiently* depends on more than how many samples it takes. It depends on how the samples are spread in time relative to how quickly the field changes, and, for fields with daily cycles, on the times of day they see. This example uses the methods of `tatc.analysis` that assess the sufficiency of observations to show these qualities:\n", + "\n", + "* `estimate_sampling_error` predicts the error of estimating the mean of a field over a period from each target's samples, for a model of the field, with the effective number of independent samples;\n", + "* `compute_revisit_statistics` describes the times between samples, including the longest gap;\n", + "* `compute_local_time_coverage` describes the samples' times of day;\n", + "* `sample_field` and `compare_sampled_means` measure the actual errors against a simulation of the field (a nature run).\n", + "\n", + "The example compares four designs of a constellation: one satellite in a sun-synchronous orbit, a train of three satellites in that orbit minutes apart, three satellites in sun-synchronous orbits of different crossing times, and one satellite in a precessing, inclined orbit. Running it requires xarray for the nature run (in addition to `tatc[examples]`, `pip install xarray`)." + ] + }, + { + "cell_type": "markdown", + "id": "5e7868c1", + "metadata": {}, + "source": [ + "## The Model of a Sampled Field\n", + "\n", + "`estimate_sampling_error` models the field at each target as stationary, with a standard deviation and an exponential correlation in time, `exp(-|dt| / T)`, whose decorrelation time `T` is the time over which its values become nearly independent: hours for convective precipitation, days for synoptic temperature. For this model, the variance of the error of the mean of the samples, compared with the mean of the field over the period, is exact (`sampling_error_variance`). The error is relative to the field's standard deviation (`relative_error`), or in its units (`sampling_error`) given the standard deviation.\n", + "\n", + "The model's predictions show the first quality: what matters is how the samples spread in time relative to the decorrelation time. The figure gives the relative error of the monthly mean from samples evenly spaced over 30 days, for fields that decorrelate in an hour, six hours, and a day, and the error of independent samples, `1 / sqrt(n)`, often assumed." + ] + }, + { + "cell_type": "code", + "execution_count": 1, + "id": "5d7db5c4", + "metadata": { + "execution": { + "iopub.execute_input": "2026-11-13T23:01:06.400277Z", + "iopub.status.busy": "2026-11-13T23:01:06.400277Z", + "iopub.status.idle": "2026-11-13T23:01:09.148247Z", + "shell.execute_reply": "2026-11-13T23:01:09.148247Z" + } + }, + "outputs": [ + { + "data": { + "image/png": "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", + "text/plain": [ + "
" + ] + }, + "metadata": {}, + "output_type": "display_data" + }, + { + "data": { + "text/html": [ + "
\n", + "\n", + "\n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + "
1 hour6 hours1 dayindependent
samples per day
0.50.25280.22350.14430.2582
2.00.11780.07220.03720.1291
8.00.04270.01860.00930.0645
24.00.01510.00620.00310.0373
\n", + "
" + ], + "text/plain": [ + " 1 hour 6 hours 1 day independent\n", + "samples per day \n", + "0.5 0.2528 0.2235 0.1443 0.2582\n", + "2.0 0.1178 0.0722 0.0372 0.1291\n", + "8.0 0.0427 0.0186 0.0093 0.0645\n", + "24.0 0.0151 0.0062 0.0031 0.0373" + ] + }, + "execution_count": 1, + "metadata": {}, + "output_type": "execute_result" + } + ], + "source": [ + "from datetime import datetime, timedelta, timezone\n", + "\n", + "import matplotlib.pyplot as plt\n", + "import numpy as np\n", + "import pandas as pd\n", + "\n", + "from tatc.analysis import sampling_error_variance\n", + "\n", + "INK, GRAY, GRID = \"#0b0b0b\", \"#8a8984\", \"#e6e5e0\"\n", + "plt.rcParams.update(\n", + " {\n", + " \"axes.edgecolor\": GRAY,\n", + " \"axes.labelcolor\": INK,\n", + " \"axes.titlecolor\": INK,\n", + " \"xtick.color\": GRAY,\n", + " \"ytick.color\": GRAY,\n", + " \"xtick.labelcolor\": INK,\n", + " \"ytick.labelcolor\": INK,\n", + " \"axes.spines.top\": False,\n", + " \"axes.spines.right\": False,\n", + " \"grid.color\": GRID,\n", + " }\n", + ")\n", + "\n", + "START = datetime(2025, 7, 1, tzinfo=timezone.utc)\n", + "END = START + timedelta(days=30)\n", + "LENGTH = (END - START).total_seconds()\n", + "\n", + "\n", + "def evenly_spaced(per_day):\n", + " \"\"\"The times (seconds after the start) of samples evenly spaced over the period.\"\"\"\n", + " count = round(30 * per_day)\n", + " return (np.arange(count) + 0.5) * LENGTH / count\n", + "\n", + "\n", + "# decorrelation times, light to dark\n", + "RAMP = {\n", + " \"1 hour\": (timedelta(hours=1), \"#86b6ef\"),\n", + " \"6 hours\": (timedelta(hours=6), \"#2a78d6\"),\n", + " \"1 day\": (timedelta(days=1), \"#104281\"),\n", + "}\n", + "rates = np.geomspace(0.25, 48, 60) # samples per day\n", + "errors = pd.DataFrame(\n", + " {\n", + " label: [\n", + " np.sqrt(\n", + " sampling_error_variance(evenly_spaced(r), LENGTH, t.total_seconds())\n", + " )\n", + " for r in rates\n", + " ]\n", + " for label, (t, _) in RAMP.items()\n", + " },\n", + " index=rates,\n", + ")\n", + "errors[\"independent\"] = 1 / np.sqrt(np.round(30 * rates))\n", + "\n", + "fig, ax = plt.subplots(figsize=(8, 4.5))\n", + "ax.plot(\n", + " rates,\n", + " errors[\"independent\"],\n", + " color=GRAY,\n", + " lw=2,\n", + " ls=\"--\",\n", + " label=\"independent samples, 1 / sqrt(n)\",\n", + ")\n", + "for label, (_, color) in RAMP.items():\n", + " ax.plot(\n", + " rates, errors[label], color=color, lw=2, label=f\"decorrelation time {label}\"\n", + " )\n", + " ax.annotate(\n", + " label,\n", + " (rates[-1], errors[label].iloc[-1]),\n", + " xytext=(4, 0),\n", + " textcoords=\"offset points\",\n", + " va=\"center\",\n", + " color=INK,\n", + " fontsize=9,\n", + " )\n", + "ax.set(\n", + " xscale=\"log\",\n", + " yscale=\"log\",\n", + " xlabel=\"Samples per day, evenly spaced over 30 days\",\n", + " ylabel=\"Relative error of the monthly mean\",\n", + ")\n", + "ax.set_xticks(\n", + " [0.25, 0.5, 1, 2, 5, 10, 20, 48], [\"0.25\", \"0.5\", \"1\", \"2\", \"5\", \"10\", \"20\", \"48\"]\n", + ")\n", + "ax.set_yticks(\n", + " [0.002, 0.005, 0.01, 0.02, 0.05, 0.1, 0.2, 0.5],\n", + " [\"0.002\", \"0.005\", \"0.01\", \"0.02\", \"0.05\", \"0.1\", \"0.2\", \"0.5\"],\n", + ")\n", + "ax.minorticks_off()\n", + "ax.grid(True, lw=0.8)\n", + "ax.legend(frameon=False, fontsize=9, loc=\"lower left\")\n", + "plt.show()\n", + "\n", + "# the errors at a few rates\n", + "pd.DataFrame(\n", + " {\n", + " **{\n", + " label: [\n", + " np.sqrt(\n", + " sampling_error_variance(evenly_spaced(r), LENGTH, t.total_seconds())\n", + " )\n", + " for r in (0.5, 2, 8, 24)\n", + " ]\n", + " for label, (t, _) in RAMP.items()\n", + " },\n", + " \"independent\": [1 / np.sqrt(30 * r) for r in (0.5, 2, 8, 24)],\n", + " },\n", + " index=pd.Index([0.5, 2, 8, 24], name=\"samples per day\"),\n", + ").round(4)" + ] + }, + { + "cell_type": "markdown", + "id": "e32fcdd3", + "metadata": {}, + "source": [ + "Samples farther apart than the decorrelation time are nearly independent, and their error is about `1 / sqrt(n)`: at one sample every two days, 0.253 for a field that decorrelates in an hour, against 0.258. Samples closer together than the decorrelation time repeat each other, but they also follow the field's variations through the month, so the error of their mean falls faster than `1 / sqrt(n)`: at eight samples a day (every three hours), the error for a field that decorrelates in six hours is 0.019, against 0.065. Assuming independent samples overstates the error of dense sampling, here by more than three times.\n", + "\n", + "A field that changes slowly is followed by fewer samples: at two samples a day, the error is 0.037 for a field that decorrelates in a day and 0.118 for one that decorrelates in an hour. The error is that of the mean over the period (here, the month), not of a long-term mean. The monthly mean of a slowly changing field itself differs from month to month, which the error does not include." + ] + }, + { + "cell_type": "markdown", + "id": "eb178431", + "metadata": {}, + "source": [ + "## Four Designs\n", + "\n", + "The designs observe a grid of points from 50 deg S to 50 deg N (every 5 deg of latitude and 10 deg of longitude) over July 2025. Three carry a sounder with a 2,600 km swath at 824 km (like ATMS) in sun-synchronous orbits, which cross the equator at fixed local times; the precessing design carries a radiometer with an 885 km swath at 407 km in a 65 deg inclined orbit (like GMI on the GPM Core Observatory), whose crossing times drift through the day over about 46 days. The train's three satellites follow one another in the same orbit five minutes apart (`TrainConstellation`). The field decorrelates in six hours.\n", + "\n", + "For each design, the table gives the median over the points of the samples, the effective samples, the relative error, and the error that the samples would have if they were independent, and of the revisit statistics: the mean time between samples, its median and 90th percentile, and the longest gap (including those from the start of the month to the first sample and from the last sample to the end)." + ] + }, + { + "cell_type": "code", + "execution_count": 2, + "id": "be0a90c8", + "metadata": { + "execution": { + "iopub.execute_input": "2026-11-13T23:01:09.149714Z", + "iopub.status.busy": "2026-11-13T23:01:09.149714Z", + "iopub.status.idle": "2026-11-13T23:01:51.926380Z", + "shell.execute_reply": "2026-11-13T23:01:51.926380Z" + } + }, + "outputs": [ + { + "data": { + "text/html": [ + "
\n", + "\n", + "\n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + "
satellitessampleseffective samplesrelative errorif independentmean revisit (h)median revisit (h)90th percentile revisit (h)longest gap (h)
one sun-synchronous1.063.044.6860.0760.12611.41712.42112.42514.041
train of three3.0189.045.1090.0750.0733.7660.08312.25713.874
three sun-synchronous3.0189.057.5300.0290.0733.8073.3875.0495.653
precessing1.025.022.2030.1690.20027.64023.12651.28957.615
\n", + "
" + ], + "text/plain": [ + " satellites samples effective samples relative error \\\n", + "one sun-synchronous 1.0 63.0 44.686 0.076 \n", + "train of three 3.0 189.0 45.109 0.075 \n", + "three sun-synchronous 3.0 189.0 57.530 0.029 \n", + "precessing 1.0 25.0 22.203 0.169 \n", + "\n", + " if independent mean revisit (h) median revisit (h) \\\n", + "one sun-synchronous 0.126 11.417 12.421 \n", + "train of three 0.073 3.766 0.083 \n", + "three sun-synchronous 0.073 3.807 3.387 \n", + "precessing 0.200 27.640 23.126 \n", + "\n", + " 90th percentile revisit (h) longest gap (h) \n", + "one sun-synchronous 12.425 14.041 \n", + "train of three 12.257 13.874 \n", + "three sun-synchronous 5.049 5.653 \n", + "precessing 51.289 57.615 " + ] + }, + "execution_count": 2, + "metadata": {}, + "output_type": "execute_result" + } + ], + "source": [ + "import geopandas as gpd\n", + "from shapely.geometry import Point\n", + "\n", + "from tatc.analysis import (\n", + " collect_observations,\n", + " compute_revisit_statistics,\n", + " estimate_sampling_error,\n", + ")\n", + "from tatc.schemas import (\n", + " CircularOrbit,\n", + " Instrument,\n", + " Satellite,\n", + " SunSynchronousOrbit,\n", + " TrainConstellation,\n", + ")\n", + "from tatc.utils import hash_geometry, swath_width_to_field_of_regard\n", + "\n", + "LATITUDES = np.arange(-50, 51, 5)\n", + "LONGITUDES = np.arange(-180, 180, 10)\n", + "lon, lat = np.meshgrid(LONGITUDES, LATITUDES)\n", + "points = gpd.GeoDataFrame(\n", + " geometry=[Point(x, y) for x, y in zip(lon.ravel(), lat.ravel())], crs=\"EPSG:4326\"\n", + ")\n", + "points[\"target_hash\"] = [hash_geometry(point) for point in points.geometry]\n", + "\n", + "SOUNDER = Instrument(\n", + " name=\"sounder\", field_of_regard=swath_width_to_field_of_regard(824e3, 2600e3)\n", + ")\n", + "RADIOMETER = Instrument(\n", + " name=\"radiometer\", field_of_regard=swath_width_to_field_of_regard(407e3, 885e3)\n", + ")\n", + "\n", + "\n", + "def sun_synchronous(crossing):\n", + " \"\"\"A sun-synchronous orbit at 824 km with an ascending equator crossing time.\"\"\"\n", + " return SunSynchronousOrbit(\n", + " altitude=824e3, equator_crossing_time=crossing, epoch=START\n", + " )\n", + "\n", + "\n", + "train = TrainConstellation(\n", + " name=\"train\",\n", + " orbit=sun_synchronous(\"13:30\"),\n", + " number_satellites=3,\n", + " interval=timedelta(minutes=5),\n", + " instruments=[SOUNDER],\n", + ")\n", + "DESIGNS = {\n", + " \"one sun-synchronous\": [\n", + " Satellite(name=\"13:30\", orbit=sun_synchronous(\"13:30\"), instruments=[SOUNDER])\n", + " ],\n", + " \"train of three\": train.generate_members(),\n", + " \"three sun-synchronous\": [\n", + " Satellite(name=crossing, orbit=sun_synchronous(crossing), instruments=[SOUNDER])\n", + " for crossing in (\"13:30\", \"17:30\", \"21:30\")\n", + " ],\n", + " \"precessing\": [\n", + " Satellite(\n", + " name=\"precessing\",\n", + " orbit=CircularOrbit(altitude=407e3, inclination=65, epoch=START),\n", + " instruments=[RADIOMETER],\n", + " )\n", + " ],\n", + "}\n", + "COLORS = dict(zip(DESIGNS, [\"#2a78d6\", \"#eb6834\", \"#1baf7a\", \"#eda100\"]))\n", + "DECORRELATION_TIME = timedelta(hours=6)\n", + "\n", + "observations = {\n", + " name: collect_observations(points, satellites, START, END)\n", + " for name, satellites in DESIGNS.items()\n", + "}\n", + "estimates, revisits = {}, {}\n", + "for name in DESIGNS:\n", + " estimates[name] = estimate_sampling_error(\n", + " observations[name], START, END, DECORRELATION_TIME, targets=points\n", + " ).set_index(\"target_hash\")\n", + " revisits[name] = compute_revisit_statistics(\n", + " observations[name], START, END, targets=points\n", + " ).set_index(\"target_hash\")\n", + "hours = pd.Timedelta(hours=1)\n", + "pd.DataFrame(\n", + " {\n", + " name: {\n", + " \"satellites\": len(DESIGNS[name]),\n", + " \"samples\": estimates[name].samples.median(),\n", + " \"effective samples\": estimates[name].effective_samples.median(),\n", + " \"relative error\": estimates[name].relative_error.median(),\n", + " \"if independent\": (1 / np.sqrt(estimates[name].samples)).median(),\n", + " \"mean revisit (h)\": revisits[name].revisit.median() / hours,\n", + " \"median revisit (h)\": revisits[name][\"revisit p50\"].median() / hours,\n", + " \"90th percentile revisit (h)\": revisits[name][\"revisit p90\"].median()\n", + " / hours,\n", + " \"longest gap (h)\": revisits[name].max_gap.median() / hours,\n", + " }\n", + " for name in DESIGNS\n", + " }\n", + ").T.round(3)" + ] + }, + { + "cell_type": "markdown", + "id": "8beba2fc", + "metadata": {}, + "source": [ + "The count of samples does not rank the designs. The train takes three times the samples of one satellite (189 against 63 at the median point), but its error is the same (0.075 against 0.076): its satellites pass each point within minutes, and samples minutes apart repeat each other entirely. The three sun-synchronous satellites take the same 189 samples spread through the day, and cut the error by 2.6 times (0.029). The precessing satellite, with a narrower swath, takes 25 samples and has the largest error (0.169).\n", + "\n", + "The effective number of samples (`effective_samples`, the number of independent samples whose mean would vary as much as the mean of the samples) shows the repetition: the train's 189 samples are worth 45.1 independent samples, as one satellite's 63 are worth 44.7. It is not itself the error. The three sun-synchronous satellites' samples are worth 57.5 independent samples, but their error (0.029) is much smaller than that of 57.5 independent samples (0.13), as their samples follow the field's variations through the month.\n", + "\n", + "The revisit statistics show why. The mean revisit hides the clustering: the train's is 3.8 hours, as is that of the three sun-synchronous satellites. Its median revisit is five minutes and its 90th percentile 12.3 hours, and its longest gap (13.9 hours) is that of one satellite. The three sun-synchronous satellites revisit every 3.4 hours at the median, and their longest gap (5.7 hours) is shorter than the decorrelation time. The samples of one point over three days:" + ] + }, + { + "cell_type": "code", + "execution_count": 3, + "id": "04180688", + "metadata": { + "execution": { + "iopub.execute_input": "2026-11-13T23:01:51.926380Z", + "iopub.status.busy": "2026-11-13T23:01:51.926380Z", + "iopub.status.idle": "2026-11-13T23:01:52.026501Z", + "shell.execute_reply": "2026-11-13T23:01:52.026501Z" + } + }, + "outputs": [ + { + "data": { + "image/png": "iVBORw0KGgoAAAANSUhEUgAAAywAAAE5CAYAAAByCqScAAAAOnRFWHRTb2Z0d2FyZQBNYXRwbG90bGliIHZlcnNpb24zLjEwLjEsIGh0dHBzOi8vbWF0cGxvdGxpYi5vcmcvc2/+5QAAAAlwSFlzAAAPYQAAD2EBqD+naQAAWBRJREFUeJzt3Qm8TPUf//GPJZJ937JG9p0QSZYoKqUsEUmIFqHSpqSktKGUJVqIEAlJJdl3CoUsEfUrZV+zzv/x/v7/Z/5zr7vM5eqeuff1fDzGNTNnzvmec+bO/X7O5/P9TqpAIBAwAAAAAPCh1EndAAAAAACIDQELAAAAAN8iYAEAAADgWwQsAAAAAHyLgAUAAACAbxGwAAAAAPAtAhYAAAAAvkXAAgAAAMC3CFgAAAAA+BYBC3CJZMqUyWbOnJmkbRg4cKAVK1YswW1p2rSpPfHEE+ZHfm5bUihbtqwNHz7cUiI//I4BAC49AhZErH/++cd69uxppUuXthw5cljx4sXttttus2XLliV103xh8+bNNmjQIBs2bJht377dbrzxxvOWWbhwoev0HTx40CLFhAkTrF+/fmEv/9tvv7l9XL9+/UVvu1u3btamTZt4l3v99detXr16li9fPitatKh7zZYtW6Is8++//1qvXr2scOHCljdvXrv77rttz5495kfeMdS+HDlyJMpztWvXdoFxQuzfv9/uu+8+y58/vxUsWNB69OhhR48eNT/yfkdiuvn1fAFAckPAgojVrl071wkdOXKk/fjjjzZ58mS77rrrXGcIZjt27HA/mzdv7jrE6dOnt+RAwWnmzJnNzxYvXmxdu3a1efPmuQzA6dOnXTB97Nix4DJ9+/a1r776yj7++GObM2eO/fXXX+497WcKKoYOHXrR6+ncubNt2rTJZsyYYVOmTLElS5bYww8/bH72ww8/uMA/9JY7d+6kbhYApAwBIAIdOHAgkDFjxsDChQvjXG7YsGGBGjVqBHLnzh24+uqrAz179gwcOXIk+Py4ceMCBQoUCMyePTtQuXLlQK5cuQJ333134NixY4Hx48cHypQpEyhYsGCgT58+gTNnzgRfp8cHDRoU6Nixo1t3iRIlAiNGjIiybbVvxowZwfu7d+8OtG/f3m3vyiuvDLRq1Sqwc+fO4PMLFiwI1KtXz61PyzRs2DDw22+/xbpvGzZsCNx0002BnDlzBgoVKhR48MEHg/v20ksvue2H3qLTtqMv07VrV/dckyZN3D4/88wzrq3FihVz64x+Dnr06BEoXLhwIF++fK4t69evj7W93vYmT54caNCgQSBHjhyB6tWrn3cOdV/HIXv27IHixYsH+vXrFzh9+nTwebXt8ccfj3IuBg8eHHjggQcCefPmDZQqVSowZsyYKOch9KbXx0Tnt3v37oGyZcu6Y6r3wzvvvBN8PqZjqnMWjr///tstv2jRInf/4MGDgWzZsgWmTZsWXGbz5s1umRUrVsS6nj179gTuvPNO1z6189NPP3X7H9rOcM7LK6+8EihSpIg7XlpWx7hWrVrxnju9H/QatcOj10V/b8Rl06ZNbl1r1qwJPvbNN98EMmXKFPjf//4X6+u2bt0aaNy4sXvfVK1aNfDdd98l+HdM7yO9r/W8fmeeffbZQJcuXQKtW7eOdbs6x9qOjisAIGmQYUFE8koyZs2aZSdPnox1udSpU9trr71mq1atcpmYBQsW2LPPPhtlmePHj9t7771nH374oX3++ee2aNEia9u2rX399dc2depUGz16tI0dO9Y9F0pXmitUqOCuDvfu3duNq9AV9Zh4V9iVGdB6v/32W8uYMaO1aNHCTp06ZWfOnHHbrFu3ri1fvty+++4769Spk6VKlSrG9elKvV6bLVs2t0+6Sj9//nzr06ePe16lciNGjHD/964GR3fllVfaJ598EuXq8eDBg6OUXl1xxRX2/fff20svvWSvvPJKlP275557XFmed8wqV65szZo1izfDpeOvq+k6bjVr1rRWrVrZvn373HP/+9//rGXLlla1alVX2jdkyBD76KOP7NVXX41znW+//bZVqVLFrbNLly726KOPBkuwdHxEmQ7to/YrJufOnbMCBQrYuHHjbPXq1fbkk0/aCy+84N4D3jG94447rHHjxsFjWqtWLQvH4cOH3c/s2bMHj7feEzfccENwmVKlSlmhQoVs5cqVsa7ngQcesN9//91mz55t48ePd+9NnYNQ8Z2XSZMmud+JF1980T2v98H7778f1n7cddddrvRS74ULpf3T+1bn2KPjoN9V/Z7Gdm5UMpcuXTr3PtfvXvSywPh+x+TNN990mVj9vut5nRd9hgAAfC6JAiXgon3++efuKqquNisb8fzzz7usQ1x0RVtXVkMzLLp6un379uBjDz/8sMty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Bw602rVr24cffmjlypWznDlzusdVRvbggw9akSJFLH/+/HbzzTfbhg0bomx31qxZVqdOHfea8uXL28svv2xnzpyJs0Tt+uuvtzx58rgyqUaNGtmuXbuC+9CmTZsoyytjpMyRR/9/7LHH7Nlnn7VChQpZ8eLFXfvj6/z37t3brrrqKtfOMmXK2Ouvv+6e6969u915551Rlj99+rQVLVrUPvroo7C3qWP18MMPW7Fixdw2atSoYV999VWUZebOnWtVq1a1vHnzWosWLeyvv/4KPuft++DBg61EiRJWpUoV9/hPP/3kjnuuXLmscOHC9tBDD9nRo0fPe93QoUPd/mmZXr16uX3wHDhwwLp06WJXXnmlO/+33367bdu27bzzH2r48OFWtmzZsM4bAAAAUq6wAxZ1dGvWrGn33nuvbd++3d3UQfUMGDDABRPqeKZJk8Z69OgR5fW//vqrffHFFzZhwgRbtmyZe+yee+6xf/75xz7//HNbtGiRVa5c2Zo1a2b79+93zy9ZssS6du3q1rV69WobNmyYffLJJ64tMVEg07ZtW6tbt64tX77cvvvuO+vUqZOlSpUqQQdFbbziiivs+++/t5deesleeeUVmzdvXqzLv/feezZ79mz7+OOPXeA2ZswY17GXjh072rfffhsleFCgceLECWvZsmVY2zx37pzdcccdbp+0bh0LHW8dZ8/x48ddUPH+++/b119/bbt377ann346Sjvnz59vW7dutRkzZtiUKVPs2LFjLrDJli2bLViwwLVfy/Tp0yfK63ROdf60jyNHjnTnQONmPA888ICtXbvWJk2a5NocCATcvoUGNXFJrPMGAACA5CdtuAtmzZrVLrvsMtep1hX86J577jmXYRF1eNVh/ffff+3yyy8PZiFGjRrlrsDL0qVLbc2aNbZjxw5Lnz69e0wBjzIq06dPt/vuu88GDRrkMhft2rVzzyu70K9fP5eJiN4Zl8OHD9uhQ4dcxkJZCildunSCD4qyQN76lY1QJ10d+QYNGsS4vIIDZR+uvfZa18n2ghWpVauWlSxZ0iZOnOgyE6LOvrIQylKFs00FMQpSdLy0Lu9YhFJwoIDF229lRhT0hNK5U2YjXbp07v4HH3xgJ0+etNGjR1vGjBndY2+88YbdddddLiDyzrMCmjfffNMFSKVKlbImTZq4timoUCblyy+/dNkd7aso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HzZsmFWoUMGWLFliffv2tV9//dUFGy1atLDly5e7QGTZsmXWp0+f4GsU4EyZMsWtb82aNS5gyJgxo3vu4MGD1qxZM6tUqZILPqZPn25///23dejQIRhAdOrUyd3Xa2fPnm233nqrC6LOnDljbdu2tbp167ptf/fdd27ZVKlSxbp/2obarPWMHDnSPvnkExs/fnyUtv7555/21VdfuefGjh1r//zzzyU62gAAAIg0lIQlMWUpXn31Vdfpv/rqq132Q0GLAgGpV6+ePfLII8HlH3zwQWvVqpX7KSVKlHCBibI1Q4YMsd27d9u0adNs5syZdsMNN7hllEXxKGhQsNK/f//gY++9957LxmzdutVlUhSYKEhRRkTKly/vfu7fv98OHTrktlW8eHH3WOnSpePcv2zZstmbb75padKkcdto0qSJC860f7/88ot9//33LqipWrWqW16ZFbUPAAAAEAKWJKbSq9AMhe4rq3L27Fl33+vIezZs2GA//fSTK53yKPtx7tw527lzpwt4FBwoCxITvV4BgsrBotuxY4c1bNjQ6tevbzVr1nT/103ZnOzZs7vysvbt27v7DRo0cMupnCtfvnyx7l+ZMmVcezxaVm0UBUjKLlWuXDn4vErHtC0AAABAKAnzOa+Uy3P06FG777773DgW76aSsHXr1rmsR4YMGeJcnzIoN910U5TX66bX16lTxwUXys4oS6PsyYgRI6xKlSouGBLdnzdvngtotIyCjZUrV8a6vcsuuyzKfQVnCq4AAACAcBCwJLFVq1add19ZhtCsRCgFCJs3b3bLRL9pBjENXFdAsHjx4hhfr3KrTZs2WZEiRc57vRccKajQ4Plnn33WBTNar4KY0HVooL/GsGiAfGi2JyFKlizpys8ULHm2b99uBw4cuKD1AQAAIPkhYEliv//+uz355JO2ZcsW1/FXBqNHjx6xLq8ZxVasWOF+rl+/3rZt2+a++0T3RYFIu3btrHv37i7IUGZEJWBTp04NztylgODee+91g+o1IH7u3Ln2wAMPuDI0BUwaE7N27Vo3HuaLL75wM4hp/InW9fzzz7vta2YwBSzavp67EHqdxtlo9rPVq1e7wEX/jy9LBAAAgJSDMSxJTLNunThxwo0HUVZFgYZKvmKjAfBz5syxF154wW688UY3fkWD6jWWxKPB9xpUrymENVC+UKFCLiMimh5ZAYqmPb7tttvcFMh6XtMkp06d2jJnzuxmJNPg9yNHjriB9y+//LLb1p49e9xAec3mpfVqPErXrl2tc+fOF7z/o0ePdgGaBuNrXI3arQzQ5ZdffsHrBAAAQPKRKuB96Qf+c5ptS9+RMnjw4KRuim/88ccfLvMSOssZgJTtwGdXWuD4H5bqioKW/c7fk7o5ABAFn1GXHhkWJClNcayJADT2Rt8Bo8yPytpim+UMAAAAKQsBC5KUBt2rDEzjYzJlyuRmHxszZsx5s4sBAAAgZSJgSUIai5LSNWrUyN0AAACAmDBLGAAAAADfImABAAAA4FsELAAAAAB8i4AFAAAAgG8RsAAAAADwLWYJAwD42uVle1vg1GFLlS5LUjcFAM7DZ9SlxzfdAwAAAPAtSsIAAAAA+BYBCwAAAADfImABAAAA4FsELAAAAAB8i4AFAAAAgG8RsAAAAADwLQIWAAAAAL7FF0ci4uirg06dOpXUzQAAAEA80qVLZ6lSpbKLQcCCiHP8+HF7d/iQpG4GAAAA4tHjwUctY8aMdjEIWBBx0qRJ4352e+BhS58+vUWykydP2sgRbyeLfRH2x7+S074I++NfyWlfhP3xr+S0L8l5f9L8v37bxSBgQcTx0or6ZU4Ov9DJbV+E/fGv5LQvwv74V3LaF2F//Cs57Uty3J9UF1kOJgy6BwAAAOBbBCwAAAAAfIuABRFHtZDXXntdotREJrXktC/C/vhXctoXYX/8Kznti7A//pWc9kXYn9ilCmiOWAAAAADwITIsAAAAAHyLgAUAAACAbxGwAAAAAPAtAhYAAAAAvkXAgogycuRIK1u2rOXMmdPq169vq1evtkj1v//9zzp37myFCxe2XLly2TXXXGNr1661SLB48WK76667rESJEpYpUyabOXNm8LnTp09bv3793P7kyZPHLdOlSxf7888/LdL2RY4ePWq9e/e2q6++2p2natWq2fvvv29+9frrr1u9evUsX758VrRoUWvTpo1t2bIlxmU158rtt98e4377wejRo61mzZqWP39+d2vQoIF98803wef//fdf69Wrl/sdyps3r9199922Z88e86v49kdWrFhhN998s/vd0TI33nijnThxwvzujTfecO+jJ554wt3fv3+/9enTx6pUqeJ+b0qXLm2PPfaYHTp0yCJB9P0Rvbfuv/9+K168uDs/derUsenT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BQAAAIBvEbAAAAAA8C0CFgAAAAC+RcACAAAAwLcIWAAAvrRs2TK75pprLFu2bNamTZska0fZsmVt+PDhSbZ9Pzl+/Ljdfffdlj9/fsuUKZMdPHgwUdbbtGlTe+KJJxJlXQCSHwIWAIhw3bp1i7FDv3DhwkTtVP7XnnrqKatYsaL9/PPPNmLECBs4cKDVrl37km1v/PjxVrBgQUtqv/32mztv69evT5T1Jeb74JNPPrGlS5fa3Llzbfv27ZY1a1ZfHMcNGzbYvffea6VKlbJcuXJZ1apVYwwydSzq1KljOXLkcO8ttTXU66+/bvXq1bN8+fJZ0aJF3e/Vli1bzguudDxDb4888sgl30cgJUub1A0AAES206dP22WXXZbo6/3111+tc+fOid75PXXqlKVLl85SyrlJTDt27HBBQbly5cxPfvjhB8udO7e9//77duWVV9qKFSvs4YcftjRp0tgDDzzgltm5c6fdeeed7j01ZswYmz9/vj344IMuOGnUqJFbZvHixda1a1cX8Jw9e9b69+9vt912m61evdoyZswY3J6Co379+gXvZ8iQIQn2Gkg5yLAAQAoyffp0q169urvCrFKnYcOGRXleV4tnzpwZ5TEFDN6VaO/q/2effWZNmjSxnDlz2qRJk2zXrl121113uc5injx53Da+/vrrWNsxceJEu+6661xnsXjx4tapUyf7+++/o2xj//791r17d/d/bX/QoEHuSrp3VdtrkzIH6ngWKVLElSrdfPPNbjmPl5n58MMPXUdbbY7pyrs6tocOHQquX68LLYVSW9Te0qVL29ixY6O8/vfff7d77rnHHatChQpZ69at3X7E5sCBA3bfffe5NisjUKlSJRs3bpx7zgsGrr32WtcOXdGXNWvW2C233GKFCxe2AgUKuOP/448/nnf+Ro8eba1atXLn4aGHHnLHQ3Ru9Lwychfy/lA7dH/JkiVR2nUhGUCVf8X2ep3nGjVqnPe4zuGAAQNifE2HDh3stddec++pYsWKue21b9/eZsyYEVxGQYqOt9avc6jz3aJFC3vnnXei7L9ep32vUKGCy+zt3r3bBUShrrjiCsubN2/wliVLlrCOBYALQ8ACACmEOl3q2Okqs65AP/300/biiy+eVxYTjueff9569OjhOtG6Ot27d287efKkzZkzx61b6w29Ih3TlX9dodY4lU8//dQFPN6VcHWsVW6kTuCrr77q/t+yZUtXdlOmTBl333tMFCj8888/9vnnn9uiRYuscuXK1qxZMxfwhGZrvvjiC5swYYLbZnS1atVy29I2vfX37Nkz+Pzbb79tVapUcZ31Ll262KOPPhosFdK+6Cp85syZXZD27bffun1XZ1jZnJjo+GzevNm1WcdwyJAhwUBqwYIF7qcCR7VDbZYjR45Yu3bt3PrnzZtnJUqUsDvuuMM9Hurll192gY3OwzPPPOPKuLzzr/UNHjz4gt4faocyCzVr1ozSrsSmNvzyyy/uuHjWrVtnP/30kzvX4Tp8+LBlz549eF/7dMMNN0RZRu/dlStXxrkOCV2PKEhX4KjASr8LCmgBXDqUhAFAMvDVV1+5K72hVNISSp3u+vXr25NPPunulyxZ0nWa1VnWVeWEULCiTrpHV6F1v3z58u6+rnLH1yn1aFldHdfYgaNHj7qr99qXVKlSuTES3n4pCEibNm2U/dR4CnVsVaqUPn36YId91qxZ7mq5shiiwGHUqFGubCgmKhHTtrTN6MdRbrzxRlcqJArOdFVeWZmrr77apk6daufOnXNjJvR60ZV5ZVsUQDVs2PC89Skjo6yKSo9EV/49yriIApjQtujcRT+f2obKmG666abg48quhHbsVQol2ndNYBCb+N4fyroos6Dyv5iOUWLRPimQUMapWrVq7jH9v27duvG+rzzLly9350U3jzJ4yjqF0n0FJSdOnDivrEvntG/fvi6zE1oCp+OrYEXZNo2vUuCt4FVZQwCXBgELACQD6uyrYxlKdfeq1/foqrUyD9EzC+poK7hRvX+4vI62R+VSyjroyr86vcoueMFLbFfzFViodEslXeoceoGPsijh0usV5KgDGUodUAUxHj0fW7ASjtB98YIaZXW8NiiDow5sqH///dc9HlPAcv/997tsiUq69Hzz5s3duYjLnj17XMZDQZC2rXOmK/s6ZnGdm3Al5vvjYimTo6D4lVdesdSpU9vkyZNdBiwcCiJUkqdJG2I69uHq1auXbdy40WW0QnlBsPe+0HtB50/nWuWNABIfAQsAJAPKPlx11VVRHvvjjz8SvB51xgOBQLwDt6OXe6mDqaviKgn77rvv7I033nABiQKZ6I4dO+ayMVpe4wqUUVDGQY8ldJC41qVAQRmm6EJnsFJm4GJEn1RAx8kLshQwqVxM+xKdly2JKWOjzvA333zjgjx1eJXB0TGLayyIytxU0qVxMsooNWjQ4LxjdrH7mtgUcITzngqlcTfKemkMin6eOXPGBcHx2bRpkzuWGhOl7Ej0bIo3Tsqj+yoDjJ5dURZN72WV+MU36YM33oaABbh0CFgAIIXQ7E4qlQml+xoL4V09Vwf7r7/+Cj6/bdu2sOvzNfZEmQPdVNevQe4xBSwqn1HHWwOo9RqJPqg5Juq4Ri9z03gVZR5UKhZaVnUhYlp/ONSGadOmuQxOQgZfa3llWXTTAPtnn33WBSzeDGbR26Jz9dZbb7nB9qIgb9++fWHtV0zru5D3x4XQe0rBWShlpXTOYqPndFw0fkbt13il+Gbi0jaUIdLrNLtXdBp7E30iCAWL+q4fjwKrPn36uPFDCoI1tXF8vOmno2fYACQeBt0DQAqhQeuaylVlNlu3bnWDsUeOHBllcPn111/vHtMg57Vr17rnwpmyWLM+6bs5NF5CZU4a36EOcEwUpKgTqnEeKtv68ssvwyr3UUCimbfUQdy7d68b5K9B1OpwalYoZXb0vDrZ6rCq/QmhsjFlS77//nu3/nADNZUfabyJfmpQvo6B9v+xxx6LNcul0i6Ns9HgdXW0dTXfO14KZNQ5VymSgjHNXCbKoGmchMaVrFq1ypUmhTOdrvZLGSFtQ6Vk2scLfX9cCL2ndC40SF8B8EsvvXReABOTjh07ugkIdBxCxzzFVgamrIxKwDSdsY6bbl7Znqg8UudGgaHK3zSmSYGmZlILLQPTgHrNAqdJFLz1qMTQy6Lo+CjA1ntN711lxvTdLnGVQAK4OAQsAJBCKBPw8ccfuymJ1clXx1Gdt9AB95ryVQGFSpbUIVZnNZwSI129VxmNBkmrdEdX5ZUNiIk65ApWNEOWptB98803o0whHBuvjEwdU135njJliuuIq9OpDqNmGdM+qjxN4zqiD7COj8ZrqFOrjrLWH1v7o9Px0ZV7lWnpW+B1DDTNssawqNMbEwVsykJpm5reVxkMZaS87IImIVCnWQPfFQjJu+++68b7aPC5ZipT9iqccTmaAlmzhT333HOuZEkZhAt9f4RDpXKhGRmdM5VnaV0KXhQwtW3bNt716D2krIgmNohpmuNQmmBBQaZmnFNg5920PY/OqfZNWRUNpNckAxqf430Hi+h7XBQgahKD0PV4g/d13hTQ6r2osUKaSU3/13sRwKWTKhC9sBQAAOACafySAgdlgS6GuieaSU3BmbImAFIuxrAAAICLphI6jU/SuJPGjRtf1LpUyqVsiMqxEprhAZD8ELAAAICL9sEHH7jxHaHf5XKh9H0rGheksq3oX9oIIOWhJAwAAACAbzHoHgAAAIBvEbAAAAAA8C0CFgAAAAC+RcACAAAAwLcIWAAAAAD4FgELAAAAAN8iYAEAAADgWwQsAAAAAMyv/g94XhZsf0UQGQAAAABJRU5ErkJggg==", + "text/plain": [ + "
" + ] + }, + "metadata": {}, + "output_type": "display_data" + } + ], + "source": [ + "# the samples of one point over the first three days\n", + "point = points.set_index(\"target_hash\").geometry\n", + "where = point[(point.x == 0) & (point.y == 20)].index[0]\n", + "fig, ax = plt.subplots(figsize=(8, 3))\n", + "for row, name in enumerate(DESIGNS):\n", + " samples = observations[name][observations[name].target_hash == where]\n", + " times = (pd.to_datetime(samples.epoch) - pd.Timestamp(START)) / hours\n", + " times = times[times < 72]\n", + " ax.vlines(times, row - 0.3, row + 0.3, color=COLORS[name], lw=2)\n", + "labels = {name: name for name in DESIGNS} | {\n", + " \"train of three\": \"train of three\\n(three samples a pass)\"\n", + "}\n", + "ax.set_yticks(range(len(DESIGNS)), list(labels.values()))\n", + "ax.set(\n", + " xlim=(0, 72), xticks=range(0, 73, 6), xlabel=\"Hours after the start of July 2025\"\n", + ")\n", + "ax.tick_params(axis=\"y\", length=0)\n", + "ax.spines[\"left\"].set_visible(False)\n", + "# the decorrelation time, for scale\n", + "ax.annotate(\n", + " \"\",\n", + " xy=(66, -0.8),\n", + " xytext=(72, -0.8),\n", + " arrowprops={\"arrowstyle\": \"|-|\", \"color\": INK, \"lw\": 1},\n", + ")\n", + "ax.text(\n", + " 65.5,\n", + " -0.8,\n", + " \"decorrelation time, 6 hours\",\n", + " ha=\"right\",\n", + " va=\"center\",\n", + " color=INK,\n", + " fontsize=8,\n", + ")\n", + "ax.set_ylim(len(DESIGNS) - 0.5, -1.2)\n", + "ax.set_title(\"Samples of the point at 20 deg N, 0 deg E\", loc=\"left\", fontsize=10)\n", + "plt.show()" + ] + }, + { + "cell_type": "markdown", + "id": "b7666a96", + "metadata": {}, + "source": [ + "The sun-synchronous satellite passes the point twice a day, about 12 hours apart, and the train at the same times. The three sun-synchronous satellites pass about every four hours, and the precessing satellite twice in three days.\n", + "\n", + "## Local Time of Day\n", + "\n", + "A field with a daily cycle, such as afternoon convection, needs samples across the times of day; a stationary model has none. `compute_local_time_coverage` counts each target's samples in intervals of local (mean solar) time. The table gives the share of each design's samples in each 3-hour interval, over all points, and the median number of intervals each point is sampled in." + ] + }, + { + "cell_type": "code", + "execution_count": 4, + "id": "a76b1aa0", + "metadata": { + "execution": { + "iopub.execute_input": "2026-11-13T23:01:52.026501Z", + "iopub.status.busy": "2026-11-13T23:01:52.026501Z", + "iopub.status.idle": "2026-11-13T23:01:52.576993Z", + "shell.execute_reply": "2026-11-13T23:01:52.576993Z" + } + }, + "outputs": [ + { + "data": { + "text/html": [ + "
\n", + "\n", + "\n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + "
local 00:00local 03:00local 06:00local 09:00local 12:00local 15:00local 18:00local 21:00median intervals sampled
one sun-synchronous47.91.00.01.047.91.10.01.12.0
train of three47.81.30.00.847.81.40.00.82.0
three sun-synchronous16.013.17.813.116.013.17.813.18.0
precessing17.111.76.214.917.011.96.314.97.0
\n", + "
" + ], + "text/plain": [ + " local 00:00 local 03:00 local 06:00 local 09:00 \\\n", + "one sun-synchronous 47.9 1.0 0.0 1.0 \n", + "train of three 47.8 1.3 0.0 0.8 \n", + "three sun-synchronous 16.0 13.1 7.8 13.1 \n", + "precessing 17.1 11.7 6.2 14.9 \n", + "\n", + " local 12:00 local 15:00 local 18:00 local 21:00 \\\n", + "one sun-synchronous 47.9 1.1 0.0 1.1 \n", + "train of three 47.8 1.4 0.0 0.8 \n", + "three sun-synchronous 16.0 13.1 7.8 13.1 \n", + "precessing 17.0 11.9 6.3 14.9 \n", + "\n", + " median intervals sampled \n", + "one sun-synchronous 2.0 \n", + "train of three 2.0 \n", + "three sun-synchronous 8.0 \n", + "precessing 7.0 " + ] + }, + "execution_count": 4, + "metadata": {}, + "output_type": "execute_result" + } + ], + "source": [ + "from tatc.analysis import compute_local_time_coverage\n", + "\n", + "coverage = {\n", + " name: compute_local_time_coverage(observations[name], targets=points)\n", + " for name in DESIGNS\n", + "}\n", + "bins = [\n", + " column\n", + " for column in coverage[\"precessing\"].columns\n", + " if column.startswith(\"local \") and \":\" in column\n", + "]\n", + "table = pd.DataFrame(\n", + " {name: 100 * c[bins].sum() / c[bins].sum().sum() for name, c in coverage.items()}\n", + ").T\n", + "table[\"median intervals sampled\"] = [\n", + " c.local_bins_sampled.median() for c in coverage.values()\n", + "]\n", + "table.round(1)" + ] + }, + { + "cell_type": "markdown", + "id": "f4e8358b", + "metadata": {}, + "source": [ + "The sun-synchronous satellite and the train sample each point at two local times, 12 hours apart: 96% of their samples are in the intervals from 00:00 and 12:00 (its crossings at 01:30 and 13:30). The three sun-synchronous satellites sample every interval, though unevenly (8 to 16% of their samples in each). The precessing satellite's crossing times drift through the day, so over the month it samples seven of the eight intervals at the median point.\n", + "\n", + "## Testing the Estimate with a Nature Run\n", + "\n", + "A nature run is a simulation of the field, from which the samples of a design are taken at the times and places of its observations (`sample_field`) and compared with the true mean of the field over the period (`compare_sampled_means`). Here the nature run is synthetic: at each point, a series of half-hourly values over the month that follows the model exactly (a first-order Markov process with a standard deviation of 1 and a decorrelation time of six hours), independent between points. A second version adds a daily cycle peaked at 16:00 local time, as of afternoon convection, whose standard deviation is half that of the random variations." + ] + }, + { + "cell_type": "code", + "execution_count": 5, + "id": "09ed8836", + "metadata": { + "execution": { + "iopub.execute_input": "2026-11-13T23:01:52.578577Z", + "iopub.status.busy": "2026-11-13T23:01:52.578577Z", + "iopub.status.idle": "2026-11-13T23:01:52.711532Z", + "shell.execute_reply": "2026-11-13T23:01:52.709942Z" + } + }, + "outputs": [], + "source": [ + "import xarray as xr\n", + "\n", + "STEP = timedelta(minutes=30)\n", + "times = pd.date_range(START, END, freq=STEP, inclusive=\"left\").tz_convert(None)\n", + "shape = (len(times), len(LATITUDES), len(LONGITUDES))\n", + "rng = np.random.default_rng(2025)\n", + "correlation = np.exp(-STEP / DECORRELATION_TIME) # between consecutive half-hours\n", + "anomaly = np.empty(shape)\n", + "anomaly[0] = rng.standard_normal(shape[1:])\n", + "for k in range(1, len(times)):\n", + " anomaly[k] = correlation * anomaly[k - 1] + np.sqrt(\n", + " 1 - correlation**2\n", + " ) * rng.standard_normal(shape[1:])\n", + "\n", + "\n", + "def peaked(hour):\n", + " \"\"\"A daily cycle peaked at 16:00 local time.\"\"\"\n", + " return np.exp(2 * np.cos(2 * np.pi * (hour - 16) / 24))\n", + "\n", + "\n", + "day = np.linspace(0, 24, 1440, endpoint=False)\n", + "local_hour = (times.hour + times.minute / 60).to_numpy()[\n", + " :, None, None\n", + "] + LONGITUDES / 15\n", + "cycle = 0.5 * (peaked(local_hour) - peaked(day).mean()) / peaked(day).std()\n", + "FIELDS = {\n", + " name: xr.DataArray(\n", + " values,\n", + " coords={\"time\": times, \"lat\": LATITUDES, \"lon\": LONGITUDES},\n", + " dims=(\"time\", \"lat\", \"lon\"),\n", + " name=\"value\",\n", + " )\n", + " for name, values in {\"stationary\": anomaly, \"daily cycle\": anomaly + cycle}.items()\n", + "}" + ] + }, + { + "cell_type": "markdown", + "id": "c869f41e", + "metadata": {}, + "source": [ + "The values of the nature run at the point of the earlier figure (20 deg N, 0 deg E) over the first three days show what its decorrelation time means, with the samples of the sun-synchronous satellites there: the 13:30 satellite is the one sun-synchronous design, and with the 17:30 and 21:30 satellites, the three." + ] + }, + { + "cell_type": "code", + "execution_count": 6, + "id": "340a57c0", + "metadata": { + "execution": { + "iopub.execute_input": "2026-11-13T23:01:52.711532Z", + "iopub.status.busy": "2026-11-13T23:01:52.711532Z", + "iopub.status.idle": "2026-11-13T23:01:52.911737Z", + "shell.execute_reply": "2026-11-13T23:01:52.910603Z" + } + }, + "outputs": [ + { + "data": { + "image/png": "iVBORw0KGgoAAAANSUhEUgAAAxUAAAIvCAYAAAACi/Z1AAAAOnRFWHRTb2Z0d2FyZQBNYXRwbG90bGliIHZlcnNpb24zLjEwLjEsIGh0dHBzOi8vbWF0cGxvdGxpYi5vcmcvc2/+5QAAAAlwSFlzAAAPYQAAD2EBqD+naQABAABJREFUeJzsnQW4VNXXxhfS3d1IiCAqIQ1Kh4SAdAoCggiKCvq3UMEuQsAipUNSBKQbFCRVurs753vedb89zh1m5s7c6Zn39zz3Tp05s0/ts3olsFgsFiGEEEIIIYSQePJAfL9ICCGEEEIIIYBKBSGEEEIIIcQrqFQQQgghhBBCvIJKBSGEEEIIIcQrqFQQQgghhBBCvIJKBSGEEEIIIcQrqFQQQgghhBBCvIJKBSGEEEIIIcQrqFQQQgghhBBCvIJKBSGEEEIIIcQrqFQQQgghhBBCvIJKBSGEEEIIIcQrqFQQQgghhBBCvIJKRRjx3nvvyY0bNyQSWbZsmSxYsMDp54MHD5bixYvLI488IiVKlJDx48fH+vzDDz+UBx98UP/+97//uf27mTJlkgMHDogvtyNBggTywQcfWN/bvn275MuXz63v7969WypUqCCFCxeWMmXKyI4dO9z63tChQ6Vjx47iS5588knJnz+/PPbYY9a/3377TYLJtZv3ZOSSM1Lr0z1S/M1d+ojXeD/cr+0+ffr4/Xdu3bolTz/9tF5HPXv2jHOOwTn19ddfe/27zZo1kxw5cui1ceHCBev7V69elbJly8qjjz6qf3Xq1HF6Pc6cOVOvfZyHDz/8sF7nFovF6zkgLrZs2SKTJk1ya1mMPV26dNbXtttbr149+eeff/T56NGj5e+//473mJ599llZu3ZtvL8fjWA+++WXXyScePXVV2XChAnBHgYhbkOlIowYMGBAvJSKe/fu6V98uHPnjoSCUlGsWDFZvXq1bNu2TebNm6cC2N69e/WzFStWyMSJE2Xr1q2yc+dOFXyxTLDIli2bDBkyRM6cOePxd7t16yZdu3aVf//9V/r16+dzRcFTvvrqKxWqzF/t2rWDNhYoDp1+OCiDF52Wo+dvC+RJPOI13g93xSIQbN68WRVXXEfDhg3z2RwTF927d9fzx57kyZPL4sWL5a+//tI/nF+9e/d2uI4aNWrEOhcXLVpkFRL9OQd4olS4Yv78+VKkSBGvlYoNGzbIuXPnpHz58l6PiQTvnucOr7/+uir6d+/eDfZQCHGLqFIqYNWCZcyff7aWM2fAejVo0CB54okn1BI8atSoWJYJWKhhjatSpYrVsoWbMqhcubJ+durUqfusiPguJiCAx6ZNm+pNGhb+48eP6422UqVKUqpUKf3tpUuXOrXovPTSS3rTqlWr1n3WtytXrug2uLM9tkCQwe+XLFlSLY2wLJqb9ogRI+Tnn3/WbXv//ffv+2716tUlbdq0+jx37twquB8+fFhfT548Wdq1aycpU6aUpEmTynPPPacChiNmz54tRYsWVYsnJmxbIGzVr19f9z8+h/XfMGvWLP0erKkQ9l15OLJmzarjsfVWuAOO6aZNm6Rt27b6GscP27hnz577lr18+bK0aNFChRTsU+xbWz7//HM9HtjXsP4ePHgw1vceeughPZegxARbcXGXcavPyfYjjgVevD9uzTmv1n/9+nXdNzg3cZxx7oMTJ07IU089pdcNlNsXX3zRqqRDOISw26pVK/0evEwQap955hk9X7AOXC+212S1atV0/zdo0EDOnj3rcCzOjt+cOXOs1npc1zgvHfHZZ5/pWOGRaNOmjVy8eFHHheeHDh3S748dOzbWdxzNMWDXrl16/cF71qRJE/V2gNu3b0v//v11nFi+efPmcv78eYfjwT7KkiXLfe8/8MADkjp1an2OufPSpUux5hZbsByWB1B8bt68aV3W3TnA02OMffDOO+/oXIltNPto48aNehxLly4tjz/+uEydOlXiAt5KzHU//PCDXucvv/yyrhPKhqtjbs/IkSOldevW1tcYI44LjjXOCXxu+5sYP+ZyzM1mzjXbjGOG38R333rrLYe/t27dOt0v5pwbPny4vh/X/Qf7Gec49jX2FRQhd9d/7NgxnUevXbtmXQ7bbH7b1T0H5yvue7hO8Id7i2HVqlV6fsObZY6l2RacM7jnYgzOrqG4tg3C/2uvvabrwF+vXr2s14ur/eXsusY1g7EuXLjQ4b4jJOSwRBFXrlyxpEyZ0q9/+I24wG7//PPP9fmuXbssqVKlsty+fVtfnzp1yrrcxIkTLbVr1471vfPnz1tfd+jQwfLVV19ZX/ft29fy7rvv6nM8Zs+e3XLixAl9vXfvXku5cuUsFy9e1Ne7d++2ZMuWzXLjxo37xle1alX93Vu3bunr/fv3W9KmTWv9/PLlyzoWd7bHlkuXLll/79q1a5bHHnvMsnbtWut4e/fubXGHRYsWWXLkyGHd108//bRlwoQJ1s/nzZtnqVy58n3fO3nypCVDhgyWHTt26OuRI0fq2LF9d+7csZQqVUrHD65evWp55JFHLBs2bLB+z3z2008/Wb9nz9KlSy2PPvqo5ezZs5bMmTNb9u3bZ9m2bZslb968cW7Xpk2bLIULF471XpkyZSy///77fcu++uqrlnbt2lnu3btnuXDhguWhhx7S8wH8/PPPli5duug2gbFjx1rq1atn/R6Ww/dwPIoXL279nqPzIF++fLo95m/Pnj2WYFHzk92Wh/vvdPqHz71hxowZllq1allf4xiC69ev6zkPsE/r16+v1yYYNWqUJU2aNJaDBw/q67Zt21oKFChgve6w7NChQ63nOM6J48eP6+sXXnjB8vzzz993/rs6fiVKlLCsWbNGn9+9ezfWfGCYP3++ng/mM/xG9+7dY52fznA0xzzxxBN6PWA8FSpUsF5rAwcOtLz//vvWZfG8R48eLvex/foN1atXt2TJksVSrFgxy5EjR6zv161b17Jx40br69WrV+s5mzRpUkufPn30PPZkDojvMW7UqJH1Oxg/5q5jx47p69OnT1ty586t47afK223F3PA5s2brdfWzJkzrcu5Oub24PzCnGJo3ry5pX///vocc1WuXLms8yp+s1evXtZx4lw1+xf7YdmyZfoc8zXm/ClTptz3ew0bNoy1b8+dO+fW/Qe/febMGX3dokULy6BBgxxuj7P1t27dWudogOsJ1445Rs7uOfgrVKhQrPVhu80+b9y4sS6D+w/mNnMtYVtwbWFOjOsacrVt3377rf4O7nP4HZy/H3/8cZz7y9V1PWDAAF2WkHAgUbCVmmgFlg8Ai2WiRInUapQrVy516SN0BhZlWMqcWXfcATG8sPYAhBbB4g1LjAFWP1gtCxUqdN93YS1PnDix19tjbyXs0aOHWuvw27DC43m5cuXc/h1Y5Dt16qSWSVglPQEWMViDYF0CnTt3VksSgEcI+QstW7a0Lo9jAOsuvDz4HrYNdOjQIZaVyxEZMmTQEC1Y/9544w3xNb///ruGJsFiBw8OrHgmHAwhIbCkwvoHbF3ntt+D5RcWN0eeEAOWbdy4sYQCxy7cdvn58Tg+jwtYrmHlxDlatWpVvX4ArkN4p2DlhDwDyzCsieZcgRU4T548+hyWa1jwzXUHrxc8YAZ4wuBlAwhzg4XZHlfHDx4DhAchRwFWdlg27UE4EY6r8S6+8MILGoMfX+B1SZEihT6HZdj2PIP1dvr06foaFll3c4ccjRn7eeDAgfr37bff6vvGim+AJwhzwOnTp9Xrs3Llylhzmr+OsS1r1qyRffv2Sd26dWO9jzmkQIEC8dp+V8fcniNHjljPL7Pv/vjjD6tlG+cU3jPzqvFqwLuK8e3fv1/PDcwFJ0+etK4HHjXjGbcFHhx4XXEewyoPz6g7wNuSMWNG6zVi702Na/04z59//nm9Tr7//nv1BqZKlcrlPQfnI7xYWNaA7TbgusCy+MO1g3PZhJHhGjFes7iuIWfbhu/BIwFvGcD4EWaIc8sVrq5rzBe4DxESDkSVUoEbo+0k6q/fcIdkyZJZnydMmFDjOCHgw+2OmwtcnogPdnXDxMRoe/PBZGo76do+x42yZs2abid92X7X0e+4sz32vPnmmzrBI64b68TNz5P4bUysSDL96aefYt3YINDZhgogLMkIea6wDbPA/oEi4CjuGyFT8QFKBUJGcANyB4R1QYHBvsP+wZhwTsRnW6DI4GbsyfdCnRzpEmsOhTOyp3NfCXYEBC6cY0uWLFHhAOFxOB8gFEDIXL9+vZ7nr7zySqzz1v7cd+dacLX/XR2/L7/8UpVfhONAuYVgZR/G585veIKz7cE4YQAxIUTeAkMDhDAYOYxS4YzMmTOrQoCwI8yR7s4B8T3GtmC7ERYD5cKe+BZ98OSaxT3G1bxpf7wdHT8TpgtDi+3nzuaxRo0a6f7CHA5lC8cnrvuPs/MGgrMxZECxcbZ+KLDYVpzr3333nX4e13bFhavv2I49Pvs0ru+52l+urmssh9wjQsKBqMqpwAUO67Y//7y5gcPKAu9A9uzZddK3jekHsKKYuE5QsGBBTdoDiM22t+rZghhTTMpQVAzmu3EBSwnGY6wl9rHY7oJ4a3gvMLnCIgavjCFNmjSxts0eWBchRODmAuXIFliQxo0bpzktiLOG0uHIwgiLErbfJEhiORPvitwEjME2Nhc3PniKYPHD94wVD5WnzPdcgRvi22+/rTHNtrRv314r2dgDKyPiqU1lK1iAsb9wnB3FqGOsJg7dNn4cngXEERsvFyznUOQALIFjxozR78EyOWXKFAkXmpZO5/rzMq4/jwtYgHH9NmzYUOPbsY/gTcN5i2sAggSsoe7EzzsD16gxbCC2HsfRHlfHD+euifmH9RRCoT1YJ44rzguAGHt3BX/7OcYVGCc8WSbuHY/uViszYH/a5mHAAwmvoCOw7SaXBV5EJGKbZd2dA+JzjO3nJnhLYO23FXKhmLgzJzhbp6tjbg+22dajgOMNSz6AB2fGjBn3zZH2QJiFh+Djjz+2voc8Buwfe/BbyFuAwgeh35xzntx/bJk2bZo12R7WfmfrB7DeY75EfhIMNHGBeRzzru18GJ+CGfG9hvA93B9xLkDRwDVuvudqf7m6rnHvg4eNkHAgqpSKUAcJYbgRYnJB2IS9pa1v3756szBJlLBq4SaCCRcTr6swIkxo8FIgMRcTFL7jbqlIKAGwSMJLgHHhhhcfEAoEQRg3RSR4QsC1DbHATcZZojYSx3EThhvZvrwpEsvhqsb+w3ZhH2GsjqybEDbwW9gHcLcbFza2ce7cuXpDxvhwDBAehZAtCPu4OeDGj9+Fqxs3ZdvkdWdgHUmSJIn1HpI04ZVwBG5e+MMNFDd8Z0nvUFYwNrj+oWzZem5g5YILHkIDthNjhmUWQMGBQIb9BA8KPne1HSaZ1PwhmT5YtKuYQYrncmxVxfvtKmTwav04rhUrVtR9guRbJP7iXIBgAws2zgm850gRcBckiSIcBccNlnUkm9rj6vhB6MI4MD4I0SbR0xaE5SBEEEo0rgkIRh999JFb47OfY1yBaxHzAUrCYj9h/nHk6TNhXyYcEuPHNQvgicM8gO9jrLDU2paLxrmN68UoHLBiY59g2xAy0qVLF4/mgPgcY/wOFBUsh7DH9OnTq0KDY4f1IJwS85knFfYwd+P7JlHb1TG3B5Z+29LOKLcNwRPbju+jnC6OSVzgWobhxJTqhufYUeEAGLfMOYc5/IsvvrBug7v3H1c4W7/ZVhg/IGy7A+ZxJDlj3sQ2YV+a8DxPiO81hH0CwxD+cAwRDmhKRbvaX86uayi98ObgnkVIOJAAiRXBHgQhoQ4EcRNvi/hnhCrgRu4puKlAqLT10gQSKIRwwcMiC6suPFjIK4FAFg6gbCyqPE3feEFzLBASBQ8FFIoUSUPbRgJBAT0LfNH3gUQvELLhLUGfCk/zysINKJSYL2HJN5W/ognkQkLJtu/LREioElU5FYTEF3hqYCmFQI7Qhfha7OEtCZZCARDmASsctgOxuohlRlnJcAGKQ7enMukfIdEIvKQIO0MIlil/GonAC4VSqvASR6NCAeCd//TTT4M9DELchp4KQgghhBBCiFdEp/pPCCGEEEII8RlUKgghhBBCCCFeQaWCEEIIIYQQ4hVUKgghhBBCCCFeQaWCEEIIIYQQ4hVUKoIAmuKg7wFAzXp0cA01li1bpjWyDQcOHHDZJA1dalGDn5BAcOzaBTl+3b3Oz+EAeliYJln+BJ1+0RQODb169uzpcBwoNWxAQzZf9NVAE7McOXLcN0+gGZ1tc0U0C8uQwXETQ/RlMMuhURgaeaIpneHHH3+UQoUKyYMPPqjdmePbpNNdSpcurfOkPdimKlWqaINDlHx97rnntFFlXPvCnpkzZ2rDPWwvGuyhqZ1tscYPP/xQtxV/+MxXoIHhpEmT3FrW/r5gu01oXGg6f48ePVp7TfgSdHDHMTD3UnfL1KLBouk3ZNu5GscS+9od0ETUlBW3v1e6AvvGtou5adyIsRDPwDmFhrThxNatW7WkeyRDpSIIYNI2jdTCRakgJJQY8u9y/SOesXnzZu0kD8F32LBh930+YMCAWEqFr0AnakfdtqHc4H3zB4UH3aUdge7IGzdu1OUwfnT8/vbbb/Uz9GxAl/mVK1dql+iTJ0/Kd999J8EAjSXRJRpC9F9//aVNJj/55JM494U96Optu2/Q38YInytWrJCJEyeqkLJz507tsI0u34FWKlyBTuFFihTxm1KBfYw+O+Ze6g7oeYGu446UCk94//33reept0qFu9y5cyde3yOhs+9KlCghSZMmlSVLlkikQqUiCBhrDiamY8eOaTdjWEgwmc+ZM8dqnYKVa9asWfd9H5MYPnvhhRd0WdyYcXOBVRHPy5YtK0ePHtVl0eTstdde0+Xxh+7JsFYCLA9rX/Xq1aVw4cLSpEkT/QzjGDFihFpiMA6M0/Duu+9KqVKlpGDBgnrTsGfatGlSq1Yt62v8ft68efXGZw8sNH379lWrXp48eVQowDorVaqkFssvv/zSuiwEofr160uZMmV0m3FDMWByh8UK72MZo6QZK1pcYybh56WYfOgPmXRwk0+9FbAm41qEVRgCrDmPcT5BEME5BAv5iy++KPfu3bMKSxD+WrVqpd9Dp2Oc688884wULVpU14EOyMYL0LRpU6lWrZpasRs0aCBnz551OJbPP/9cnnjiCSlZsqTUqVNHDh48qO+7Mz+Azz77TMeK+QDXB5poYVx4fujQIf3+2LFjY30Hwi6oXLmyfg6hHaBzvP0cAeAJ6N+/v44Ty6OJIporOgL7KEuWLC73P5QZzDmdO3d2+HmKFCkkceLE+hxjwPHCXGrmnYYNG0q2bNn0PWwLhG5HvPrqqzqPYMyYe4w1HeC7gwYN0m3Knz+/jBo1yvrZmjVrrPu9U6dOTgUVeEtwjEDChAn1tzAXebIvAIRl0/QN+wZeGbO9aMTZrl077agNIQXeEEfb6+k5jWMOKzys+dhWc05AmcN5i3n28ccfl6lTp8Y5fszhuJdAkEdn7JdfflnXaeZgb8/xkSNHardtgCZ5ZtsuXbqk54lRKnGeY//YegUwhtmzZ+t1gt/BGAGOaY8ePXRfYb9g3I4wHjxX90pHYH/Cs4JlsS8Nq1at0usOXiezz83vYOw4T02jw3Hjxuk9HvsN70NxNTjbp+6cE/aemu3bt+sx9PRe6mz9MBhMmDDBuhyOGbbDlSwC8GhkGKwP22XA3Iq5F/Mc9ue+ffus24Ljh7kE2wSvH44l5mecW9hHq1evdmvboLBjf+J7VatWtcoyrvbX6dOndbsxLnwP84UB48W5G7FYooxbt25ZThw/5rc/rD8usNvPnz+vz/PmzWvZvHmz9bMSJUpY1qxZo8/v3r1rXc6WpUuXWhImTGjZtGmTvn7rrbcsGTNmtOzatUtf9+jRw/Lqq6/q82+//dZStWpVy40bNyy3b9+21K1b1/Lxxx/rZx06dLA88cQTlqtXr1ru3LljqVChgmXChAn62bvvvmvp3bu39Tf379+v4542bZq+/vXXXy2FCxe+b5uwHmzT33//re/PmDHDUq1aNYf7AeNq2rSpfufcuXOWNGnSWHr27Gm5d++e5ciRI5aUKVNa11mqVCnr9mG8jzzyiGXDhg36+tSpU9Z1fvTRR5Zu3bq5NWYSnvTf/Isl58w39e+NLbN8tl6cq7Vq1bK+Pnv2rD5ev37dcvnyZX2Oc7F+/fqWiRMn6utRo0bpeXvw4EF93bZtW0uBAgUsJ06c0NdYdujQodZrKnPmzJbjx4/r6xdeeMHy/PPP33e9/fzzz5YuXbrob4GxY8da6tWr5/b8MH/+fMtDDz1k/Qy/0b17d+vc8eijj7o1N8U1RwwcONDy/vvvW5fFc8w9rrBfvy3Y7pIlS8Z6r3PnzpZZs/47xrimsQ8wNzRv3txy8+ZNff/FF1+0DBo0yLrcjh07LLlz53b4O7bzBY5j7dq1Y43v888/1+eYb1KlSqXzJn4nV65clkWLFulnv/32my6L/emKK1euWIoUKaLnljv7AvPzxo0bra9Xr15tKV68uCVp0qSWPn366NwInn76aetxAPPmzbNUrlzZZ+d0o0aNrN/BGB977DHLsWPH9PXp06d132KOxvFImzZtnPc2zPUzZ860LuftOX7o0CG95xmuXbtmSZ8+vd7nfvnlF0v58uUtzz77rPWaxO/ZjwPn9ldffXXffXXdunX6evjw4bH2nS2237W/V7rCfn+ZMTVu3FjPM2xHvnz5rNuP38H+uHTpkr5etWqVniPYTrBixQrLww8/HOc+deecsJ8btm3bpsfQ03ups/UvXLhQj4uhYcOGOsa45pn33ntPlzXbbK5fM/fu27dPX/fr18/StWtX67YkSJDAsmzZMn2N6xfn7IIFC/T1ypUrLVmzZtVrwNW2nTx50pIhQwbL1q1b9fX48eMtRYsW1evQ1f768ssvrWOx3QcA9wrbczfSSCRRxrmzZ2Ts2J/8tv727Z+TrNmyx/v70NR79+6tcbfQdJ3FeEKbhlYNoKHjNayfAFo4NHOwePFitQLAmgUQa4ywh379+ulrWFRhATTf27t3r0u3PiwIoHz58g6XhWUOlh78xuDBg/URVjBnYDvxnfTp00uBAgXUmgFrXM6cOSVz5sxqRUiSJIns2LFDWrZsaf0erD2wGMAKCOsHrDew5uEvU6ZMHo2ZhJ+XwgBvRa/CVSV78rRerxtWMFjlcf7CIoWYcAALLq4XWBMhN8GaC6uZOR9xXsHTZq5FWPCzZs2qr3F+wstmgCcN1nTQtWtX67lpCyypsAyb6xvePk/mB1zzsBSaWHd4NJ999tl47xdncwTGCQ/I9OnTrRZFY6mLD8iJsPdSGAuyAeuHZRYWyrZt28qMGTNizQvugDCiIUOG6ByCY3vu3LlYn5uwFsyniRIlUqs+lsFzeBkA9j3mK1dgf+A4YFnsQ3ewt/7CsopQL1g+4eVCeBes0/4+p22BhwYWYPtYcHh44toHzvD2HD9y5Ij1GgPJkyfX5WB9xvkPD9orr7yi24lQE3gk3AH3UWM9x3UNy38gwHmC8wt/2A5cY/h9gGvXhHjBa4Pz34wR4NyEd8DVPnXnnIgLd++lztZfs2ZNzRtDCCbypjZs2CBTpkyJc56ZO3euhg8aGQZygQHjgEfRPMd1bcC5id835yq8frVr19bXiIbA+QNPU65cuZxu2/r169XbgD8zNyAXzUSCOKNcuXLy1VdfWSMxbL0rmP/hoYasgt+NNKJOqciQMZMK/v5cvzcg5AcCNNzPHTp00JP49ddfv28525MRQrn9a2eueeM+d7YeV7GHuKjN97Gss0kLigtcn+3bt9f4ZoQlOMOd7YArG5OQozhk3BShvCCJEyEFcGnDfe/pmEl4gDyKW/f+O4Z4jvcGPer8HHMX3ISgqEIIgWCC6w7nHBRjCF24weD8hLBim3cQ32vR0fUIIOS98cYbqnTEd36I6zc8wdn2YJy4iduGO8YX5EQgvt0oKHGRKlUqFYARdoJHKHW2Qg6MEUbRswWhXzByQPhCqAnCRu2F9PjOpbZAsYSgmD17dvnmm2/EWyBIQThD2JEJF7UNbXG2vfE9p23BcUYoCZQLe2zDujzB23Mcwqf9eKHwYRuRb4K8BQiC48ePV4OVUeTjwpNr15e4+l2c67b7DfsEIXqe7FN3zgkoNLb3R/v96+xeivAyE6oMZRChPo7Wj+Pw0ksv6ZwBgR5hXUZRiGsfeLvf4rp+4yMnuNpf5cuX123G9sPwgdBuKFNYN5bDI4ylkUjU5VRAQIUnwV9/JubXXdKkSaPWPgOS2UyMKyyM8U0ks51ocdHDaoYLDpY/d4QA+3F5AiYPJNDB8oA4SVxA3oBkP4zHNr4ZygosNIjhhhUnY8aMuo0RHasY5dh7KQy+yq2A9RM3FijBsFDiJn348GE9xyCU4AYGq7U78eSuLNFIIga4Fo3l2xZUNEGctrGgQ0DFDcnd+QHrhAUQseUA14S7gj+uJXeve4wT1jhU4QF4hDAYH3766SedL1xVmMM1byo64Vo31ZEArPgwKOD44Lhh/zmyumPbMEdD2MdytrlZroDXAvOnqRwEYcGZpRbL4bdhCEFcf3yVOhxrk7sDrwoSsc32wnoN7yySwJFrgf3naHvjc07bz/3wlkDpwzYbIDCZmHd3sF+nt+c47glQimyrauG8h9ca5xByTfAaBiZH15ijMcUXR+uBtwWWeEfLYsye7DtbcByhKEE5Bjg/TN6Hq33qzjkBZQOKKrxiAOeXO8B4aIoJQKFwtn6APCDkKOBebps7Etc2QzE3ld7M+DwB5wv2FbyUAAoyzvu4qn3B4wBPIfIlAAoYIIoCf6721/79+1WpQZ4ZlKh///3XmlsHLw68giZfKtKIOk9FqAHNHZZ9WF6Q9IlEL7jqoMXiveHDh3u1flgtcPNDopFJVHOndCVu8LhIcNHBLYiJwxOwTdgePHoLLAJwgWLcEGJgHUCIE24gcCtiksWkAcUCN5C4XJMkMrwUvvZW4OYBSx9ughAMcQOEEGdCMSDooBSoMyHFHZCMieRSnKNI6MU1Yg8ss3CPmyo1GAusekiQffPNN+OcHxCmgpsgrGW4cWEbTJWkuIC7HmEKWDcSKV2B8Bnc6BGKYQRnvIf9ZA/CvkxCKT7HtptyrLjZYz/YJ46bEqAQKvAHyye8ksYiCcENFkCAGzwqV1WsWNE6z8GgYQ+s1xC+MQbMF+6WpMT+RnI0Qjow/yCsDWEejsBysE5iv+OYAYzLVNtytS/gjcA9AGF0WA/+oAThN3EOYn+Y7YMnxIRl4DlCR31xTmO/QhjEclAoIKhCoUGCO84PCKvwinhSBhX3IXwX8zes7N6e41CGoCjjnMD+BNhnEO4xfoDzGIqJeW0P9gVCg7EdCGlB6FN8sL9Xorwvji/CauyBool7KfYthE5nieCu5o9PP/1UfxP7DMoJth/b7mqfunNOAHgVEHoET0J8S5+6Wj+OJ/YRCtTkzp3brfVhTsE+hQyDawHnq6cFV3Au4ZqEvIXzEOcPijvgGJw5c8alhxDeUBwzbAsMplDAMd9hHM7217Jly9R7Y+YqhN+lTRsTootKYbj2IpUESKwI9iBI5IGbEjRyxEkT4i0nb1yW6r9/IzfvOXaJJ30gkfxevbdkTeZ+eclAg+pPqPrmi74PhEQ78ARAAYPBKZRAaB28g/b5QCQmzwM5H7DeQ0GKNm7duqUKIJRh29zPSIKeCuJzYP2CJs8+F8RXQFnYXv+tYA+DEBIiwEIMqzdCwzzpVeFv4MXCH4kNwhPhKYBFPxoVChMWhXyfSFUoAD0VhBBCCCGEEK+IzEwRQgghhBBCSMCgUkEIIYQQQgjxCioVhBBCCCGEEK+gUkEIIYQQQgjxCioVhBBCCCGEEK+gUhEE0CQHZfAAatajs6M3oNFVvnz54lwOjXbQJAkcOHDAZffaQICys6jbTwghhBBCwpuo7FOBBiTOQAdadHB2Z1kIxejw6CloZ2+AUoHuqNmyZRN/Y7q0EkIIIYQQ4kuiUqn45uvPnH5WoMCD0rRZS+vrb4d9Lbdv33a4bO7ceaRlq3Ye/z6UkfPnz8vgwYO1XT28B8mTJ5fRo0fL4cOHtSU9lBu0dx84cKA0atTIYXdetI9PkyZNrPbw+E79+vXl7Nmzcv36dXn00Ufl+++/l5QpU2rr+D59+sRSakz363///Ve+++47fQ3vQcGCBfW9DBkyxFoWXbKxjuPHj+vrHj16qLLStm1b/QzbBipUqCBvv/22jm3evHk6Xiho+BzdRsuWLRtrvbt379b1njp1Sm7evCldu3aVF1980eN9SwghhBBCAk9UKhWhwjvvvCM//fSTeg8QEgU6dOigQnf58uXl3r17cunSpfu+ByF96tSp8scff2gn0Xbt/lNsEiZMKBMmTJCMGTMK+hpC6B8yZIj079/f6Ti6dOkihQsXlk8//VRDokaNGqWKjL1CAYUF7w8YMEBatWql7505c0a7Q+L3Fi1aJLVq1ZLNmzfL6dOnpU6dOqqYdOrUSVasWCEPPfSQKmjXrl2Ltd67d+/q+saPH6/L4PNy5cqp4sHOpIQQQgghoU9UKhW9+7zm9DN4CGzp0bOP02WNVd6XVK9eXXr37i3NmjVTAd0oG7b8/vvv0rx5c/VSgG7dusmqVav0ORSJr776ShUPKAEXL15Ur4EroEjg96DgvPzyyzJ8+HCHYVL//POP3Lhxw6pQANNuHmMeOnSojnnYsGGqzGD/QNGAcgFlASBcLG3atPetd8eOHdKy5X8eIuSc7Ny5k0oFIYQQQkgYEJVKRZIkSfyyrC/48ssvVcBeunSpei3atGkjr7/+usvv2Co38FIsWbJEli9frkoHQqzwOi5eeukladiwoRQtWlQyZ84sjz/+uEfjbtKkiY4TXorZs2drSJW7QBGCV8Q+LIsQQgghhIQHrP4UZCD4w5tg+Pvvv6VYsWKaT/DCCy/IunXr7vtOjRo1NPwJ1nwI5CYXAiBXA94DrBefI0/DHeBJKFCggMtchiJFikiKFClk4sSJ1vcQ/gSQ3N69e3dVTJ555hlrZanatWvLb7/9ptsFEP5ku71mvRgvwq4Me/bskXPnzrk1dkIIIYQQElyoVAQZeAief/55DXOCpf7NN99UpQKegnHjxmmCsz316tXTcKWSJUtqknSePHmsn7Vv315zEiCoI0m6cuXKbo8F40DIFNbtCCgOs2bNUuH/kUce0STw6dOnWz/v3LmzHD16NJZSgoRvLI9EbiyPPAmEO9mvd+7cuTJjxgwpUaKEbj/WhURzQgghhBAS+iSwwNRNiIgqA1mzZtWqTfFh2rRpmo+BnA9CCCGEEBI9RGVOBYkNytpWq1ZN8xoQqhQfTKWnmTNn+nx8hBBCCCEktKGnghBCCCGEEOIVzKkghBBCCCGEeAWVCkIIIYQQQohXUKkghBBCCCGEeAWVCkIIIYQQQohXUKkghBBCCCGEeAWVCkIIIYQQQohXUKkghBBCCCGEeAWVCkIIIYQQQohXUKkghBBCCCGEeAWVCkIIIYQQQohXUKkghBBCCCGEeAWVCkIIIYQQQohXUKkghBBCCCGEeAWVCkIIIYQQQohXUKkghBBCCCGEeAWVCkIIIYQQQohXUKkghBBCCCGEeAWVCkIIIYQQQohXUKkIAOPHj5ecOXNKOLN27Vp54oknJF26dNKyZUtZsWKFpEqVSi5cuOD2Oh5++GEZNmyYy2Wwzjlz5vhgxIQQQgghJFBEpVJx+vRp6d27tzz00EOSIUMGKVCggDRq1EgFZ2+FW0eCc9OmTWXz5s0SzrzxxhtSokQJ2bFjh4wYMULKlSsne/fulbRp0wZ7aIQQQgghJMgkkiikTZs2cvv2bRk5cqTkz59fTp06JcuWLZNz58755feSJ0+uf8Hm1q1bkiRJknh9d9++fdK5c+dYHpesWbP6cHSEEEIIISRciTpPBcJ11qxZI++//75UrVpV8uTJI6VLl5ZXX31V6tevb/U2gFatWqnHwryGYN2iRQtVRCBQV6lSRZYuXWpdd506deTQoUPSr18//R7+nIU/ff/99/LII49I+vTp5fHHH5eJEyfG+hzfHT16tIYaZc6cWR599FGZN2+e9fO7d+9Kjx49pFixYpIpUyZdh72HpFu3bvr9Tz/9VAoWLKjLfPTRR1KmTJn79kv58uV1n9hz8OBBHQsUrhdeeEGfY3schT9hv9asWVPHU6RIEd2nV69edXos9uzZI7Vq1ZKMGTNKqVKlZMmSJU6XJYQQQgghoUvUKRVG2J87d67cvHnT4TLLly/XR4T5IMTHvIaADCEY3129erXUqFFDnn32WTl8+LB+PmHCBFUe3nrrLf0e/hwxe/Zsef3116VXr16yYcMGee6556R79+7W3zFAAWjSpImsW7dOfxeeAuNNuXfvnuTIkUPGjRsnmzZtkv79+8uAAQNk+vTpsdYBD8zu3bv1N6dOnSrt27eXf/75R/744w/rMn/99Zds375d2rVrd99Yc+XKpduRJk0a+eSTT/Q5wrnsgcL1zDPPSOPGjXW8Y8aM0XCyvn37OtwHGH/r1q3Vc4IxfvPNN/L22287XJYQQgghhIQ4lihk5syZlly5clkyZsxoqV69uuXdd9+1bNu2LdYyKVOmtMyePTvOdZUuXdoyfPhw6+uiRYtahg4dGmuZcePGWXLkyGF9jd/s2bNnrGXatm1radKkSazfHzBggPX1lStX9L2FCxc6HcvLL79sad26tfV1165dLfnz57fcvHkz1nLPPPOMpXfv3tbXffv2tdSpU8fldmL82A7D8uXLdTznz5/X1z169LC8+OKLsb6zevVqS+rUqS3Xr1+/b98sXrzYkjZtWsuxY8esy2Pb3N3vhBBCCCEkdIg6TwWANR3W+ylTpqi3YeXKlVKxYkUN63HFlStX5M0335SSJUuqRwIhULD6HzlyxKPfx3cQbmQLEp/xvi3Fixe3Pk+ZMqV6C5BkbkBOSKVKlSRv3rw6llGjRt03FoRH2edRdOzYUaZNmyY3btzQPAvsB3gwvGHbtm3y888/6zjMH/YzPBIHDhy4b/m///5bvSDZs2e3vofqUoQQQgghJPyIykRtkCxZMqlWrZr+IXSoZ8+eMnDgQGnbtq3T70ChQA4FlkPFKCRfY3kI5v4gceLEsV4nSJBAhXSAUKb//e9/MmjQIClbtqyGdH399dcaCmULlBF76tWrp4oGQqLweOfOHVUAvAEKF8K4kHdhT+7cub1aNyGEEEIICW2iVqmwB+VlbUvIQqBHMrQtyBVA5aiGDRtaBWkkZtsCId3+e/YgiRn5BliX7boxBnfB8lAmunbtan1v//79bn03UaJE+tvwzGC8yJHwtjrVY489pt6HBx980K3lsa3wqpw4cUKyZcum723cuNGrMRBCCCGEkOAQdeFPZ8+eVUv9pEmTNDkZoTkzZsyQr776Sp5++mnrcggpQgLxyZMn5fz58/oeBGZY97du3arhPrDMG8+BAdWkkMR97NgxOXPmjMMxoEcGQoVQAQoVkIYMGaLrfemll9zeDowFvS8WL16soVyo3PTnn3+6/f0OHTpoYviiRYu8Dn0Cr7zyiqxfv14fsX+wXUhox2tHPPXUU1qRCkoR9iX2GRLNCSGEEEJI+BF1SgXChFBSdejQoVK7dm2N4//ggw80z+CLL76wLoewIoQ6wauAfAvw8ccfa0fp6tWra9UnPKLUqy2o/IQyrCgXmy9fPodjaNCggZZ5HTx4sI7lp59+0kpTKFHrLqgEBY8JlAMI6KgK9fzzz7v9fQj08HQULlzYYYlZT0H+x4IFC6xlYrHPPvzww1g5E7Y88MADWkb3+vXrWtr3xRdflHfffdfrcRBCCCGEkMCTANnaQfhdEmRw2KEQQRFBaVtCCCGEEELiS9R5KohoBSl4RhDa5SoxnRBCCCEk2nEWzh7OnPHDNlGpiELQERyhXMjlQEdvQgghhBByPyiCg4qf7hbDieZtYvWnKARVqwghhBBCiGsuXryoRXnwGClc9NM20VNBCCGEEEII8QoqFYQQQgghhBCvoFJBCCGEEEII8YoHoq2M6s2bN/WREEIIIYQQ4huiSqm4deuWDP7mc30khBBCCCGE+IaoUioIIYQQQgghvodKBSGEEEIIIcQrqFQQQgghJCzJkyePHDx4UEKNgQMHyuuvvx7ncitWrJBFixZZXx8/flxq1qzp07HMmTNHNmzYYH39559/Svv27SWQbN++XerUqSMlS5bUv1mzZjlc7uGHH5atW7cGdGzEd7D5HSGEEEKIC+7cuSOJEiVy+jq+rFy5UhuQGUUie/bssZQMXzB37lwpUaKEPPHEE/oaQv3YsWMlUFy7dk1atmwp3333nVSoUEHu3r0r586dk2Dgq+NGHENPBSGEEELCgnnz5qlQXLZsWXnrrbdifbZnzx5p2rSpVKlSRT8fMWKE9bP169er4F6uXDn9DIK2sdpXr15d36tataqsXbtW34f3I2fOnPL2229LxYoVZeTIkWppf/XVV6VatWrSsGFDXe6bb77R72GZxo0by6FDhxxa6fHbWKZUqVLyySef6PuwyP/4448yefJkKV++vHz00UfW3zUsXrxYv4fx1a5dW3bt2mX1cJQpU0b69Omj21S6dGndFnt+++03mT9/vnz99df6G6NHj9bv4rntdr7//vv6O48++qjug379+uky+I0dO3ZY1zdx4kR58sknddlatWrJtm3b4jxmU6ZM0fVAoQAJEyaUzJkzO10eXgzs42LFiln3Fdi7d688/fTTui8wNnhgDKlSpZILFy449GDB+4HjiOPUtWtXPU9q1Kih+w2K1oABA+LcBuImlijixo0blk8/+VAfCSGEEBI+nDx50pI7d27Lzp079fWPP/5oSZkypeXAgQOWO3fuWCpVqmT5+++/9bOrV69annjiCcumTZssZ8+eteTLl8+yatUq/ezu3bv63s2bNy1FihSxLFq0SN9fvXq1JX/+/JbLly/rOrHun3/+2fr7tWvXtjRq1Mhy69YtfT158mRLz5499bfBhAkTLE2aNNHnH374oeW1117T55cuXbLKHdeuXbOUL1/esn79+vuWA/jdHDlyxNrebdu26etJkyZZSpYsabl3755l+fLlljRp0lg2bNign33//feWhg0bOtxvXbt2tQwdOtT6Gt8tV66c9fewnbNnz9bXo0ePtmTJksWybNkyff3VV19Z2rRpo8/XrFljeeaZZ6zbgv1ZqlSpOI9bv379LN26dbM0bdpUf7dLly6WU6dOOVy2aNGilr59++rz06dPW7Jnz245evSovq5atarlhx9+0Oe7d+/WfXPw4EF9jW04f/68dT34DNtm1tmjRw/db+DVV1+1fPbZZ9ZlcS64YvPmzbp+PEYKm/20TfQBEUIIISTk2bhxo1qvixYtqq87dOigngPw77//qhW/Y8eO1uWvXLkif//9t5w+fVoKFSqk1nXwwAMPSIYMGdSDgOewWgNY0rNkyaIeBFjvEydOrGE7tuA13gewlMM7UKlSJX2NsB5HXL9+XV5++WVdL37v6NGj+tyEIzlj06ZNamUvXry4vm7RooW88sorcuzYMX1doEAB9QAAWO8HDx4cr/2aLFkyadCggT6HFyhlypRq1QfwrMCTYrxE8EzAU2E4f/68bl/y5MldhhwtXbpU/xDe9d5776mH5eeff3a4fPPmzfUxU6ZMki9fPjlw4ICkTp1atmzZop4bULBgQfVWrFmzRr0ScdGmTRtJkCCBPsd5AC8Xzo/KlSvLU0895fK7xiMGT1SSJEkkErj1/60VcOx8CZUKQgghhIQdRkgEaGqbPn16a/iSLQsWLIjXOlOkSKFKgC0QuG1/s2/fvvLcc8+5XCfCazJmzKgCMOL5W7VqpY14vQXKgAHjhPAeH5ImTRprPbbrRaiSWS+2F8I5lAJPyJ07t4ak5ciRw6ocQUB3hrPfd3WssJytUme/fxEeZcBvI/RpyZIlGtY2bNgwmTFjhtPxIDxu2bJlqnhly5ZNIoETJ07IqFGjrAqyr6BSQQghhJCQB5Z9xPf/888/UqRIEU02NhbXwoULqzV73Lhx0q5dO2sMPhQNWPHxfPXq1Wqlvnfvnsbf4zt4DuESMfzr1q2TkydPalLz2bNn4xwPhEx4ByCkwvNx+/Zt2blzp+Yl2AJrPsYLhQIeFVjsjXcjTZo0cvjwYYfrhxcC68M2w0MzdepUtfRDOMf2uAv2C5LBvaVevXrSuXNn/YOigH0H7wG8G/Ce1K9fXzZv3nzf95o0aSJjxoyRS5cu6fYuXLhQHnnkEY9+G9vw2GOP6fHt1KmTbj+UtM8++8zqtYFnB3knyMm4evWq03UhpwLLt27dWj0xxlPlDOPJwHZjDJHAli1bVKnwddI6lQpCCCGEhDxI7v3222/V0o8wFCQ/Q5gHEI6mTZumCcZDhw5VqzW8AxCcIIQjwfjNN9+Uy5cvqzUeibsQkidMmCCvvfaavPHGG2ohHz9+vFq13VEqYHHHclgPgEUdpVrtlQqMqUuXLhrukz9/fmtokVFMMDaE8iD5G4Ku7fYikRvJxVh3unTpVKi2tdC7A/ZXt27dNDkd64JAHR+gkH3wwQe6PowHCp0pEwulwpmACgUE+xgWf+x7HI8hQ4Z4/PvYF71791bvAvYBPAxYN0BCN34DCedQLMx54YhffvlFJk2apOcQFCMksRPfkACJFRIlwB02+JvP5aXer8Zy9xFCCCGEkPgBwRyhQfY5KJFi1YdnadWqVRHlqajkh22ip4IQQgghhMQbJF4Twj4VhBBCCCGEEK+gUkEIIYQQQgjxCioVhBBCCCGEEK+gUkEIIYQQQgjxCioVhBBCCCGEEK+gUkEIIYQQQgjxCioVhBBCSISB5l558uTR7sWEEBIIqFQQQgghEQS6BA8cOFDOnTunXYZv374d7CERQqIAKhWEEEJIBLF06VLZv3+/Pt+7d6+MHz8+2EMihEQBVCoIIYSQCOKHH37Qx5w5c+rjRx99JDdu3AjyqAgJT9KmTSsPPPCAPkYKaf20TVQqCCGEkAjh+PHjMn/+fH0+efJkyZUrlxw7dsyqaBBCPCN//vyyb98+fYwU8vtpm6hUEEIIIRHC2LFj5e7du1K+fHl57LHH5I033tD3P/vsM7l8+XKwh0dIWJIpUyaJNDL5YZvCRqn4/PPPpUqVKpItWzbJly+ftGzZUv79999gD4sQQggJCaBMjBo1Sp937txZH9u0aSMFCxaUs2fPypo1a/S9Y9cuyPHrF/X56dOnZdasWZrcTQghUaFUrFq1Srp27SpLliyROXPmaDWLRo0aydWrV4M9NEIIISToLFq0SI4cOSIZMmSQxo0b63uJEiWSt956S5ImTSqPPPKIvjfk3+X6B27duiWdOnWSb775JqhjJ4SEP4kkTPjll19ivR4xYoTGgm3evFkqVaoUtHERQgghocCPP/5o9U4kS5bM+n6TJk3kwIEDkiNHDvVSTD70h77fq3BVTebu0KGDfPHFF/oIhYQQQiJaqbDn0qVL+pg+fXqny9y5c0fdwYabN2/qI9y8dPUSQgiJFOCh+O233/R5x44d77vH9ezZUx/hobh17671+aBHG2rexZgxYzTvAv0tCCHRxQMPPBC9SgUmy379+mkiWrFixZwut37dGlmzZuV97586eUSSJEni51ESQgghgeHbYUP13liu3BOSJnUyOXnisPWzFClSSdp0GWN5KcCkg5vUW5E9Sxb1UiACoGmThpIzZ44gbQUhJBhkz5HXJ+tJYLFYLBJm9O7dW2NH8WfqcLvrqRg5Yoi82OsVjS8lhBBCwh3c62BgQzlZJGo3bdo01ucJEiTQvze2zJJxBzbE+qx9/rLqrUDCdpEiRTRU6rvvvgvwFhBCgknUeipeeeUVWbBggbp5XSkUJkENf452nq92ICGEEBJMRo8erQoFSkSigImj+5u9l+I+b0XmzNK+fXvNy4DhziR1E0KIu4SNZA2HChQKVH6aN2+elpUlhBBCopVTp05J27Zt9d5oysg6C+21zaWwBe+ZSlBvv/22JE6cWB8JISRilYqXX35Zu4P+9NNPkjp1ajl58qT+Xb9+PdhDI4QQQgJqZJs2bZqULl1aKyMmTJhQ8wz79+/vcPmTNy7LnKPbJHnCxA7/Zh/ZqstkzJhRy8suXrxYli5dGvDtIoSEN2GTU5EqVSqH7yOxDJYad0BOxeBvPpeXer/KnApCCCFhx5UrV+T5559Xrz1AmBLug48++qhP1n/hwgUpUKCAPPzww7JixQqGChNCIi+nAhMpIYQQEs18++23qlAgXxDeib59+/q0mmG6dOlUaRk2bJh6K6pXr+6zdRNCIhuaIAghhJAwYfnymPyHjz76SPtL+KM8+tWrV/Vx1apVPl83ISRyoVJBCCGEhAG3bt2SDRtiSsI++eSTfvudkiVL6qP5LUIIcQcqFYQQQkgYsGXLFi1OkiFDBnnooYf89jtly5bVx02bNmkPDEIIcQcqFYQQQkgYsGbNGn2sUKGCNrPzF0WLFpU0adJoGNTOnTv99juEkMiCSgUhhBASRkpFxYoV/fo7qPiEcrVg/fr1fv0tQkjkQKWCEEIICXHu3bsna9eutXoq/I0JgaJSQQhxFyoVhBBCSIiDMKTz589LypQpfdaTwh2lgsnahBB3oVJBCCEB5ti1C3L8+sVgDyPqOX36tPz4448ydepUCZfQpyeeeEJ7VPgbE/60b98+OXXqlN9/jxAS/lCpIISEVUlNdPk9fPiwhDND/l2ufyTwoGP0+PHjpVGjRlKwYEHp3bu3dOrUSfbs2SOhzOrVqwOST2HbBA8J24DeCkKIO1CpIISENHfv3tXOvj179pQCBQpIvXr1pHHjxhLOXorJh/6QSQc30VsRYAYOHKjnUPfu3eX333/Xc8s0j/vzzz8lVLFYLLEqPwUKhkARQjyBSgUhJGQFKQiBhQoVkgYNGsiYMWPUygz++ecf6/NwAx6KW/fu6h+9FYHjypUr8sUXX6i3Cz0e3n77bfnrr7+kQ4cO+vnWrVslVDlw4IAcP35cEidOLGXKlAm4UrFu3bqA/SYhJHyhUkEICUn+/fdf+eijjzSeG82+EKIyf/58yZYtm36+e/duCVcvhYHeisCxbNkyVSjy588vGzdulH79+smDDz5oTXoOZaXCeClKlSolyZMnD9jvIn8DbN68WW7fvh2w3yWEhCdUKgghIYkpZQnBZu/evTJkyBCpUqWKFClSxKp0hKuXwuAvbwXKjz7zzDNSp04dOXTokM/XH44sWLBAH2vXrh2rcVyJEiX0EV4LeMdCOZ8ikKFPAF7C9OnTaxfvbdu2BfS3CSHhB5UKQkhIYuK4K1WqpGEfhsKFC4elUmHvpfCnt+LYsWOyaNEiWbVqle4/WOmjGSgLCxcu1OdQtGx5+OGHJWHChHL27FkNMQpFgpFPYZrgGW8FQ6AIIXFBpYIQEvKeCluMUoG8inD2UvjTW2FbHevcuXNa6Wjo0KEha4n3N7CyQ9FKkSKFKlm2JEuWzOr9grci1Dh58qRWpoJ3pVy5cgH/fXP9MVmbEBIXVCoIISHHxYsX5e+//3aoVIRj+NPJG5dlztFtkjxhYod/s49s1WV8rVSg10Dr1q21ylH//v2lS5cucu3aNYnW0KennnpKlQh7TAhUKOZVGC9F8eLFtcxroDHXHztrE0Liwv8ddAghxEM2bdqkVnUk1WbJksWhpwJNuZA8ahsaFapkTZZattd/K2C/d+TIEX1EH4aRI0fKY489Jm+88YZMnjxZTpw4IfPmzZNo4rffftPHWrVqOfwcydqTJk0KSaUiWPkUBiimCIOCoorwsOzZswdlHISQ0IeeCkJIyGFCLey9FCBHjhySMmVKuXPnjuzfvz8Iowt9jFKRK1cuDZvp0aOHzJ07VxWw5cuXh3yjN19y5swZ6/mEJG1HPPLII/oYikpFsPIpDKlTp5ZixYrpc3orCCGuoFJBCAk5jBDoqCY/rKaoShNuIVB9+vRRrwseQbVq1fQ1Eqr9pVTkzp3b+l7lypWtgqlJWo4G0OQOXi+ED0HJcoQJf4KSitC7UAFjMVWXAtVJ21W/CnulAmF1qDRGCCGASgUhJKSAkII+ArbCjD3hVgHq6tWrGl6DfIZnn31W38uaNau+RrlcX2NyKmyVCtvwn8WLF0u05VPYV32yBX1QzL4KpdKpqNoFhQj9NEx/lmBg21kb40H38ddee027k2Ns8AYRQgiVCkJISAFFAd2y0eQL1uVIUCpmz56tHZ2RI2K8Bfny5dPHgwcP+jX8yZYaNWro44oVK7T3QKSDEDmjQDkLfQrVZG14TXr37u0yFyRQmDBEKBPwHqJfzPDhw7UM7+nTp2Xp0qVBHR8hJDSgUkEICcnQp5IlSzpNwg43pWL8+PH62KZNG2vjtbx58+rjgQMHfPpbly9flvPnzztUKtCTIWfOnHLjxg3tYREN5xL2BRq4OQqlC1WlAmWAmzRpoh4AJJG/++67QR0PPBKZMmXSwgioyoYKWs2aNbMqO8y1IIQAKhWEkJBUKpyFPtkrFaHeewEdrZEcDWUC5V0NxlPha6XCeClQfjRNmjSxPsMYatasGTV5FabqEzw0iRIlCgul4ubNm9KqVSvZvXu3KoXTpk2TVKlSBXVMOG8GDRokTz/9tAwbNkxD9kaPHm09n6lUEEIAlQpCSNgkaRtQKhWCDsKkTp06JaEKSnC+8847+rxq1aqSJ08e62fGU4HwJ18qRs5CnwzGuuyPBPFQVSpc5VPYKxW7du2SW7duSTDAefDCCy9oGVkohFAoQqWEKxQI5AV16NBB0qZNq++ZZnxQxJA3RAiJbsJKqYC7HkmOEChguZkzZ06wh0QI8XG1Gwh1zsrJGhB+YSz9oRgChdjzzp07S9GiRVUwBGg8Z4tRKi5dumQNV/JnkrbhySefVKs9ysqi10ekAuVq+/btWi3M5JK4AgofvDsmxCcYvP/++zJlyhQ9Pj///LPTnKJQAYorwulQBQrnPCEkugkrpQKVUjDJfvnll8EeCiHED/zxxx9qrYXCgOpIrgjFvAoI6ggvQiIrGs0hUbh8+fJq4W3cuHGsZVOkSGHdRl8maxulwpmnAhZwjCnSQ6CMlwLKacaMGeNcHp6vYPargHfis88+0+dDhgzR7t/hgLNys4SQ6COslAq47ZGw1rBhw2APhRDiB4xg4spLEcpKxcsvvyxr165VS3PLli21yhLCjBCL7gh/5FU46lERjSFQcXXRdgSSosFff/0lgcZUUHrmmWekXbt2Ei5QqSCEGFxnroU5sBLCLWubAGfq4LNhD4k2UFFm+vTp0rx5c2tMdKhhBBPkU8R1jZoGeP/884/LZWGBNhWXHAHPiC9yGpA/gb4CpgvyQw89pM9djQ0hN9hmKBW+mpOMpwJhKc7WiXCgt99+W5UeeIARThZJIIQJyfEAniN3960JN4KnItD3CKPIQEgPp/uTyX3CeYz7ratrjRASmiBM1BdEtFKxft0aWbNm5X3vnzp5RJIkSRKUMRESLHr37ivzf10gM2dOlx9/GOmzScRXQJAySdoPFsgjJ0/ECMfOyJQxnT7+/fcup8tmyJhFkiZNLtdu3pNxq8/J9E0X5NiF25IjXWJpWjqdtKuYQVIkfUBu3boh5856l/A96qfRqpyUKvm4pE+XMs7x6zZkSq+Pu3Ztd2t5dzBej5QpkjhdZ8YMqTX06uTJkzJ3zkypXLmSRBKbNv2hicMoJZslczq3923OHFmsAv7xYwcDeo1s2bJZH3Pnzu6zcyEQZM2SXpImTapGi/XrVkn+/DHeN0JI+JA9R0yOn7dEtFJRtlwFKV2mbCxPxcgRQyRL1lw6CRISLSAhd8FvMfHzq1atkSlTf7E21goVEMaEpGU0vav6ZA2nPSoM5con18ejR49J6jQZNUfBHgiFUCg6/XBQth+5YX3/6PnbMnjRaVmy67KM6pJXUiRNLlmzOQ8XQr+An376STp27ChZssQInvb8uiBm/7Zt197lumwpViym4tDJk2fc/o4rYCmGogBKPFpKsmZznFdhmsGNHTtWNm7aIs2ebSWRxF9bx+kj8hI8uVlmyJhNDU5oVHjj5j3Jn983N9q4QBO548dP6POqVavfVwo41ClVqpR65/buOyTlylcO9nAIIUEiopUKxDU7qk0OQSPUrLSE+JOhQ4eqJyBbtmxy4sQJGTBggFSuXFlKly4tocLGjRv18fHHH3dL6c+cObNkyJBBLaToPmySbO2Bh8JWobAF749bc066PZXJ5Zzw4osvyvz58zWRfOrUqfd9jopVsG5jvkHTMnfnF5NTgV4WvpiToFAg9CdhwoSSI0cOl+tErgGUCnScjrT50IShVatWzaNtw3mHBoFbtmyRbdu2yYMPPiiBAFWqTJM5VKAKNxCyBaUCIVDhlA9CCPEtkXUnIYTcB/o4mI7OsLYjERT5Rp06dVLPQKjlU7hqemcLYrdNsjbyKpyBkCdXTN94Ic4EWigU4Ndff1XFwh5UejLWf3cqDdkrFaj+5Is4epNPAYUirmZvsOJjGTRZg1IWKeCcNgpqfCoomWTtQFaAMvkUpldGuMFkbUJI2CkVcEljojeTPW7EeG5upISQ+xkxYoTcuHFDvRLwTqBcJRKEIUgiBCoUOlIj/AOWTncrP3lSAQo5FK447uJzhBO98cYb+tx0NUZnYVugDBjvBZLgPQFlX+FVQLM1eJD8XU7WFiTrG2EwkqpAoZ8Rjhu8DKYXiCcYjxc8FYFWKoxCE26Yaxb9PdCQkhASnYSVUoHmOhUqVNA/0L9/f33+4YcfBntohISsIv7999/r8z59+qh1H+EVo0aNUmEWwrDxYgQSNHubMWOGvPLKKyqQQPgzioGvlQokZbsiu4vPER6E0BTsMzTbxD5DqVJjCQfr1q1TA0fq1KmlXr164gnwFJjSr74oK+tOOdlILy1rSrOiyV98MN6CQJaVDXelAnlGUOJgoNi0aVOwh0MICRJhpVSgoRSEJPu/kSNH+tRi+tZbb8nmzTGVOAgJZ8aMGaMCPLrQN2jQwPo+LNQ4z0Hfvn0dhvT4A1j1f/jhBy3d2b59e/nuu+9k586d+hlKsA4cODDOpneeKhWo8uSKpmXSOQ2jQYdjAG8FSme2bt1aX2Oc9qFPjRo10iRzTzHWdF80wIurm7Y9ptP0ypUrw6qMqSuWLFmij/FtHmc8FceOHZPTp0+Lv0GVKoSghbNSYWsMgJJNCIlOwkqp8DeoDoWGVV9//bU2sSIknEHCLkKdwEsvvaRWdlvgJYA1F30KTNKuP4HygN+Bx+TixYuq6HTv3l09JQjFgoXT04pURqmAUOZMKEbZ2OK5HPdhwPvtKqS3GhRs+fzzz1WoxDiff/55fe/1119X7wKSmxE/jrClmTNn6mctWrSQ+ODLBnjGU4EeFe5QrFgxVYRgnEE38HAHigDya+CRgxEqPsDjhGMeqLwKeMJg4Ycy7YlCHWqYUDpTFpoQEn1Qqfh/MKlDoEE3XAABx9ygCQlHpk2bpucwqiQZC7stUDJ+/vlnDdmBQt2jRw/p1auXtUmkr7h+/bq89957GqoIKyZyEz755BP1jkBwb9y4sY4xvgI5Ss/iN5xdr+hDMapLHnmpVmbJmT6xoDcXHvEa76dImlCt27ASI5EdygkEfFTMMjkUpq9N/vz5pU2bNlZvBcKGUH0KVbXiK8QaT0Uwwp+gIBnLPCoeRUrVp5IlS2plsPjy2GOP6WMgPNbhHvpkKFeunD4iNNC26SwhJHqgUvH/DB48WC2mKD9okhxnz54d7GEREm8l+auvvtLnUBacdUxGsu6kSZPknXfeUesuci3gTfCVQg1Lft26dVV5QMWp+vXrq8Les2fP+zwn8QFCsSn76SwECgnQUBxQNnbh6wVl+6Ci+ojXeB9W+i+++EITTOHRgZIFbwrGDk8Oxm+L8VZAEcF+A88++2y8t8eXngpPw58CLUAHKp8ivqFP9vskEIqW8YaEa+UnQ9GiRdXLc/nyZS2xTAiJPqhUiGi5SBNfDgsqatIDKhUkXIEFHeFG8Ap06dLF5bJQpCEoI4wH1l14ECpWrBinkInr480331QhwhlffvmlKhHobAyvCBQYdyoTeUJcZWUR5gVPDRoAOgL7CNuCax8N9FA9yPRu+Pjjj1XZsvcstG3bNtZvxjf0yazPFzkVCGMzIVye7GP0BYkETwUUaW+TtA3GaxCIZO1wLydrgFJt+t4wr4KQ6CTqlQrEsz733HN6Q8IjYrwbNmyon6HEJWr8ExJumIpPHTp0UIHe3aRdJOzCSgvhFGFJzqz/EydOVEEdHj7kGzjKZ4BSA0EdwBOARGZ7Ad0XuErWhhdi4cKFqjTguSuBCN4T5EkYgbRr166aUO4IKGGm4zd+35vQFeOpOHr0qHpH4ovxLsFaDA+Up1Z5CLfhnKwN6zi8UvDKmVCc+GKOJ3J9UOjAn3lPO3bsiPWb4QzzKgiJbqJSqUCMNPInOnbsqIIThI2qVauq4AOhBzX8Yb3DDXbevHnBHi4hHierouwpgKLsqdUcnjuc/1AsoAhA2LVl1qxZ0q1bN+vruXPnyqeffhprGVw7CLuC0IRwIoQH+YsiRYroo6kiZQsUCvToQKdiZx23bUHOBErHIiTls88+c7oc5gjjAcI+9kZZQjlOJEvDsOFNzx2jVMBL4cl4UHULnaRR7cqZNyccMF4K5O44C/dzF3jsjAfJn8na8HRBkYQiiHMv3DHKHAxyUPKglB0/flznEhjooPgj5wKeQOR8mU7irmB+BvElmOPiuqaPXbsgx69fDNiYJNqVCsRGYwL/8ccfraEPmDhcWQJDCVTEwdgxqcGyhZjscePGWS2PAMKUEaAICScQZgShvnz58laB2xPSpEmjPSQKFSqkQi6uBRNWg7AqKONYf7t27WTYsGH6PnImILzbhuJg4sa6UE3NHx4K+/AdFFkYPnx4rM/M9euJlwTLQQmJa3mERiGvAsqTN+B3fBECFZ98CoB5zyhc4ZBXgX5FKPFrn4NikrSrVavmk98JRAiUEW6w/xFuF+4g/AnnM44NSjBjuzCP4PzGNYUEeuS7wJiHeQTGPFdhd2imh1wN5HnZV2cj4QMMJlAwg91o9eTJk1pQo1KlSrJ69Wqnyw35d7n+Ec/xeBY7dOiQ1qNGDDFilc+cOWONnUZ8dTjQtevzOlaEZiBMZPny5fdVCjEhULhRsUMoCSVchajgMyjIAH0g4guqMUEgz5Ejh97YmzVrplb/Vq1aqfehSZMmWh0J4VUIf8JvwTpsLDzIU8BnH330ka7Dn8DSbnKiXnvtNZkyZYo+R0WoBQsW6HMIMb4GIVOYC30hDPoiWduTbtrBTEz2FlQSg2EIoTZQInHO45xE6J4vkrQDmWsSKZWfDGgSiZxEXPMZM2bUeQBFDQwIy4OXD8oGPDOoNIdqaqig5uzaRi8bzEfwePqi63yogKa9UKqiQVlC0RAcc1/2FIsP7777rspzmDPgaXYk2+EeNvnQHzLp4CZ6K+KDxUNatGhh6dy5s+XmzZuWrFmzWvbt26fvL1++3FKiRAlLKHPjxg3Lp598qI/uULp0aUvKlCktEyZM8PvYCHGHLVu2WLJkyWL54IMPHH6O6xDnLK7Ny5cve/17O3bssOTKlUvXaf6aNm2q178Bz0+dOqXP+2/+xfLGlln6/PTp05Z79+5ZAgF+p2/fvjq+tGnTWn777TfLnDlz9PVDDz0UsHHEl1deeUXH+vbbb8d7Hd26ddN1fPrppx5/d/To0frdevXqWUKdggULxjofa9SoYRkzZow+z507t+Xu3bs++Z2FCxfqOh9//HGLv6hdu7b+xrhx4yyRzO3bty137tyJ9d65c+csxYsX1+1v3bp1nNfo77//bilXrpzl4MGDlnAH52i2bNl020eOHGmJZC5cuGDJkSOH9VoK1ly8bt0665xRoEABfezUqdN9y+EelnPmm/pn7mXEfTw2sSFWEkmKpm67Ae5NxHJHEsZbwRAoEiogxwcdeJHDgDAQe0wDO3gWYCX0locfflimT5+uVZEAXMfwhNhe/3gOS6K9hSdTpkx+DXuyBb+DfdK8eXMNz4T1EzlSwF8J4r7El54KT8Of7JO1gx2i4Ao0TUSorekTgnMcYW8mBA1J9r4KIzLVmNBY0R+hvdjP27ZtiyhPhTPgrbAvuYwCEhMmTNC5pXPnznqNXrt5T0YuOSO1Pt0jxd/cpY94jfcR1oZjXrt2bWsH8nAFuSUmdNzkv0UqiAbBdWu221+eP4TfOvP6IC8HkTUAXnWcdzgf4dWePHmydTlzDzPQW+E5Hs++cBs5SpxCMqcvhJhQwoRMIKksXPJFSGSDUCRzHaLYgO21CFfuL7/84nXokz0I8UEY0fvvv6+TMJKKHYEY1Fv37upfMOJRIUyOGDFC468R+oSEUNv8qFDGFzkVtonanoK4dSiHOIcQ+xyqmApf2bNn1/MfVYaqV69u/dxXoU8A3a0RxgPh3x/J2lAgIWxhvyPMJxpBSAyMFlAYrt28K51+OCiDF52Wo+dvC3RbPOI13jeKBcLScI0bhSwcQdluA8KvkYMWicAAhlBFYLrF2wrxvgLXaNOmTdU4g4qE9oYRNDWFwQTheQifROhk//799bN+/fqpIcr2HmYI1r0sqpQKXNQmORPAugCB21gQIgmUk0TcJzRgJKgSEipKhUmqNaVjwdSpU/VchYCCJElfggRLWHqcGQ5CxcIDAQ2eFFPaEp2uzfNI9lRAyfS0m7b9fjPlc0M5Wdv0BTEFCBCfD0Ua1wFye+Cp8iX+zDUx+RTwBtoWCYk2KleurI/jVp+X7Uf+K/ZgC94ftyYm7+Lll1+W06dPayNNd6pHhbpSgTkbikUkMnr0aPUeQI5CwQ5znzJCvK9AXxTsQygTyJdFXo8pz428XxjEAHLvUG3P5N+hWtkzzzyjnjT7e5iB3go/KxVIvMQBLFWqlF4MKKeISRGhT+bARQpQmIyVk43wSLDBRGzc/saVO2DAAGs4iAl9QlWVQIf7hJKFJ2XKlHrjQiIerGThUFXHeCpwA4aRBscaSamwkLtT5hVCFpJecdzjmxgfDsna9koFwDajgACSQXHsfYk/K0BFWpK2t0zf5LogyvSNMZ/DYIKywUjufvrpp8Oye7dRKuBxA7/++qtEGjB04Nhg/sX9qk6dOloQBxWYfK1EmQRwGNTwe2PGjLFWLYRnAr1m4BWzbQQLReKHH35Q5cLRPcxAb4VneHy3zZkzpyoVOBDQBhF3CmUCuRZGA4zEvAqEf+Cm7QhXcaCE+AoIl6hyA8HpnXfe0fKNiMuFGxehALAww+LZsmXLgI4rFC08uHnBMla3bl0JB1AVx1Sgg5EG8eYFCxZU4QnhHr///rvL7xsvBYSU+Fq9w6GztlEqTMNDf+NPRcuEVIV7J21fcezCbZefH7f5HGGYODawQkOxCKccC8gRJnTr1VdfteZVhHIuU3yAcI8KgVCY0CgV8xJClHwdAgWjmgn7RasAGJTQ9wXV4FA6FgoGQI6dbSUy4yGGEebkjcsy5+g2SZ4wscO/2Ue26jIkbmLvYTfBgQm04BIsILjhpIMnBr05oG3bAsUB8Z62blsTB7pk12UZ1SWvpEga+pZSEj6hT7DS4hr85ptvNHQAMckmFh8hAUiQDiRxWXgGPRqjmJO4Q8yQv2XKa+KmjJsj4u7hfVqxYoXTBmneJGk7EqAh4IRicrsjT4U/MYoWrj3k6TjLJ4oP9FTEJke6xHrvdEb2dP8py4iNRwEVEwKFRwjm4dBAEONFaA6MCMh9Q0gOclLxvjsNOkMRyEHjVp9TbxOUQxzLpqXTSbuK6aVixYrW5SA3IlQRkR++8ixCkYBnF32ZcC3hD/MoGq6iBQKAJxMGGmdkTZZattePKUtOvMNjaRdZ867+Ig3c2Bs0aKDP4ZnBNtr2CcCF5E4cKCG+UipMUicmzxdeeEGfb9q0SR/RGyKQ0MLjO2BRQ3dyVDPau3evuuzhnUK4B57jhozER18naRtMbD9+y5uEcX+BcFuTRB6oxGZ4flDZDAURduzY4bP1IgQE4W1Q3EwuS7QDIdTl52Vif44+GBBOcS7A6AfFwgiR4RD6hBByKKmmuEC4hkAZw6rjBPtDsSI2UPQDih9CPFHJ0FugnCEJG3Tr1s36frFixbTHWI0aNXReQ08QEqKeCpSTtQXhGKhcgEQ/lIaDmyvSQJURJGrjBt+1a1dNPkIjMHfjQLs9FVjLMYkOpQLAyjVz5ky9qUKg9FU3YXehhce3IVAoiWoLyh6iQzrc+BBqUToV84+9F8EXnoqkSZPqzRieCoTSmeTxUAGKFgw62E+mkoy/wX6GBwfzP/YLPNe+DH1CiFukVU2ML+0qZlDvviMjXfFcyaRdhdgNagFCrqGII4Jgz5490qdPH5kxY4aEi1IBUOBm/vz56mmxl6/CAXcMq0YGwvWEYgpoPIwQKG8LK+Ded+rUKVX+7av84dwwYVHesHPnTp2XER2AeTFQc0/UeCpgEbP9g8UFOxqup1GjRkkkggojKE+J3BHcAExZQ0/jQAkBsDYjDhgV07xVKhAeg7hVCFrIc7KvBU/CH4Rfjh8/Xm9qCHVD2Jsvu2mHS7K2behTIEOzTHiSL/eJESxNeBURDRNGuPBLtTJLzvSJBYcYj3jtKowYFd5M3Pzq1asdlrwPZaXChFSjPDIKLkRqgr2hRYsW+ogQJW+3FyXEAfqc+KuCGjwdMLZcunRJJk2a5JffiCR8EuwPawsEbpNFH4nAiocKBrixQCA0IHbQFbZxoIQAxMbDNYtmbe5OqrhRGmXWPp4cNdsRk4uJlUQmiAfG+QKQpI8bsm1iJ46/t56KcFEqApWkbb9PYLH0FaZxpREsSQxQHGDVXvh6Qdk+qKg+4nVceYkIIYPBDwYb27LbwQAVj5AvYEqa2oLCGuY8Rg6VKX6DZH1cz7iuww1PDau4frHtuKfBSOKNcgZjL6JkOnXqJP7E9H2C8hppCfW+xmcZxLCiIUY00oFVBJZhaK3xiQMlxCgHmFThvnUHxLgjphzKbaiFpZDAgD4MuLkhBAiNORFTXqBAAbV2m2oy3ioVxnIO73Oo3TwDnaRtr1T4SgHAfjU5UFQqfAM8tOY42faACDRI5m/WrJm8/fbb8u233973ubmucJ3ahtGYHl/hmFcRH8Oq8VZ4UwXKlJFt0qSJ30OSULUK4f24d69fv96vvxV1SgWSa2z/EM+IWr+wkqKRSLSQJk0aaxwo4j0d4SwOlEQ3tuFzKH/nDsb6BisPQ5yiE4T8fPnll+qZArCEIp4Y5TTxHJVUvFU44eaHgQgVqExIVbQrFeghAmMS4vV9AbxKOG64jllO1neYfJdgKhXo5myKHCAc3Laoi6PQJ4MpfY3S0chTDSfiY1iF4oXzH54G5Ep5Cq6fadOm3Zeg7U95D8qLbT8o4iOlAhVIbP+QmD1o0CB1Pw4fPlyijfjGgZLoxQhHAJV+3Km04yifgkQfyZIl00RU1GZHmAXOHyR5oiodQuqMscOb9SOGONQ6a8OrZ3oRBFqpgDLXt29fDVNBTxZve68YwRL7GdZP4huMoB4spQI5puiFYKpGQli2b/LmTKnAa3geUT4a13Q4ER/DKjwLpupVfKqGolgFDCnYb6iOFwjatWunj0j+DjUvbijhscSLmEDbP4QBoSoStHJYc6KR+MaBkugDk5FRKkznY3e8FVQqiC1I0EcIBeraV6lSRZt0Fi1a1Cfrtg2BChVQKjSY4X+mqiH6rnjbXZf5FP7B7E/0e8C5EmhQiQ+VMFG05rnnnrP2UHBHqYDV3oRAoQpUNBhW27Rpo48oQuFJcj1CzEzoU/fu3SVQQHmBFxcyrynhTe6HUq+fQKM8dP0kxBYkZqMPAKyfSPw3caVxWT6oVJBAVzsyzdlCKWQQRUGCEf6H6mqmc7y3neKZT+EfoGSjpwgaoZmSvYECVacQjoN5/fPPP5cuXbro+wgPR4VMgEeEFGIZR1W/TBWocMyriI9hFf2/0qdPr+GAS5Yscfu3EH6EfYnjbTp0BwIkhGP+AcEuBhD2fSr69+/v9go//vhjiXYgJCLHBO5tb+swk8jCCEcoU4zwwTfffFPDWNCDwFkTLMTlGu8GlQrib0xVGljUQ6WzdrAqPznrHB/fTvG4lo0HiEqFb8F5irwKCOVQ3NBoLRDAyv7qq6/qc1QhMkp52bJlNal33Lhx+rnxUCF8D55Ge6pXr66WcNwjDhw4EPEFORBqiYRtlIVFVaWaNWvG+R2EPH399df6HDlOEPQDCe6/UCjw5854oxG3PBWwWLnzFwjrANxeENYRf4iGJMbqE0ogkRKTA0oQxicJiUQutsmm6dKls7q8XZXWg6sVpRJRhxvVfgjxJwipwrl29uxZFW6iOUnbYLwUhvh6K9CgDeET6KTsq3A14lgh9ofygOOH8Bv7+H5UX8N8jnLPBhMCZRK2nYU+2XrDjEISzGRzb+jZs6cqQ/DWuEOHDh30EUV/3Cmvjj4R8PYgJ8OUeQ0k5pqFIZB4oVRA83fnDwmD/gTuxTfeeEP/Vq1apZZdlFZEJYBQAi69ypUr6/M5c+YEezgkBD0VxuJqSuu5sgYbVytcr/5q8EOIAXkLpipRqBhtgq1U2HopAJ7HJ7fCCIsQHnkth1cFKFjIUbYWuXAwaPbr109DnAcMGKCf/+9//5NMmWI6RwNUC4KigUIcqOoUl1IBzHUX6PAtX4F71ZkzZ9w2fsGAgVAwVLyKq7wswtpMInzv3r1VMQ80JlKA4U8RklOB/hAdO3bULHxojCjfhhML7sVQA/GCgEoFscW+gR3iaBEH7KpxHfMpSLRV0nFW3CAY14C9l8Ibb4XZn8aiTnyL2a+oFHbhgutOz55iEqghAEPZHjZsmHojUH4Z8gj6yNgC2cQk+CNh2x2lIhTzmTzBVGgrVKiQ298xHgd4fFzlFqLqHSI/MmTIYPUCBctTgXsyK0B5kVNhD1yLOMBwQ9l3jZw4caL4A/wOYlFR2s+Asm0oS4b29s40W9uqAjdv3tRHuCLt60f7mnr16mkiLmIqjx07FrWVsUhsjHCESRfnIGJCUZLZlKuExyJ78rSxzk/jaoUi4u/zlhBbwQd15IN9zsETbYobwAIaqPHg9/Bn76Ww91YgtwIChjtChhEsYZ0N9n6NRBAlgPAbhO1hX5uypd6CY2W8B/BOoPQr7u2QPdD095tvvlF5xP6YIscCTfCQsA0w3yN829mxN54KKBWQXUIhn8ldEC4JBQvkz5/f7fMbydaIPoGgjn3qKBcG6/rss8/0eY8ePbQUczCuH8w/KBRhKkDhvu1rbt68qedJoI89zt+gKBUof9m1a1epUaOGuvSQXIQ4Q0z8xjrvrxMWF1mWLFlivY/Xts3EbFm/bo2sWbPyvvdPnTzi9wSfhA/A6lBC/vprq0ycOF5at4oJcyHRC2JxURoTpE+XSk6eiGku1qhRI32EgIKJJEZIuSenTh7V97dti7mZZc+W2fodQvxJvrwxN8stW7bIkcP7ghqqs359jNEIN/BLF8/IJe/aRLhFihSpJG26jHLyxmWZc3SbJE/oePtnH9kqvYs8JVmTpZZLF8/JtWtXZP78BZI9R3Z5/LEYq7OtYcxYoLF/eS37h2LFiqpSsXzZEnm4aEy1Hm/Zv/+AXLlyRUMDHyleRHMmn6xaIdYyjo5nurQppHTpUrJpU4wy+VCRwnLhvPNw7cyZ0qrQivyCbVv/lKxZY8s7ocyff8YUIMiRI7tcvnRW/9ylTu1a8sus2fLdyOGSN0/2+z5fuHCxGtdSpUolzzSuH9RrB80w0UZh7dqVUrlSRZ+ue9XqNdK5czd5uc9L0r17bM+Xv8meI29wlAok4KDCE7oYwvr+6aefqmWgV69eIWeNL1uugpQuUzaWBjhyxBDJkjWXTg7+pkmTpqpULF++Sl5+OaY6BIlejEAB923Rh0vEshDYhlj0KlxVvRVZs+VW6+e+ffv1/bLlKup7hPibzFlyauIoLLJnzl7SWPJgcep0TNgJLLyBOv+NlRDKwvb6b7n1nTRpM8iOnf9I7z59tboPkndxrRugoEGxQJz9E2UrhpUVOpyoWLGyzJv3q/zz7x6fnS8rV6235gDkzJXfo+927/6CtcRs2XLl4xwT8u0gQB89dkpKPBo+FcLOnovJMSpS5CGP93vXbt1VqZj/62/y9TdDVHkw4B74/Q+jrH0pChUuJsEE5wCUihMnzvh8PpoyZYZ6YL7/4Sd5pe9rDquEhToeKxX79++31lOGtR9VaTA5vvjii1K/fn1tAOMPUO0JGrx9UjZeoxKAI2BNwJ89Z06fCkgpsooVyuvjihUrZO+e3V53u3WHFClT6uO1q1f9/lvEMzZt2mh1oZ4+FVO7PFPmLE7LVWIy3bF9m7pace6nSZ3K+j1C/M0jxYvLqtWrZfmypZIzx/3Ww0Dx119brCEVZ06fVi+eP0mePIWkSZvW4+/hPmiq/aEx7GeffSqvvPyy9fPly5fpY7FiD+s9iPiHBwvECP3Ie7CfL+EtnjxlitSqWdPafNQd1q5do49FChf2eA6uUL6chmUhhK9QoYJxfr/I/ysV+M3SpcIn9+avLTHXaa6cOT3eR4ULFVQPAJLax40dI82aNbN+tmDBAlXIkaPSovmzQb8H5s6dSx8xJl+O5dKlS7J48WLr8+9GjpT27WO6eAeCrNmyB0epgJUFEybInj27lk1FFSZYtOxLrfkSKAGIQ122bJk1zAoaHV7Da+IJkyaNl0CROXMmOX36jLz/wXtS4hHHfQh8xeOPl5IaNWMUvnVr18iWLcFPsiT/sXTpCn28e/e2jB37k/V4OSpXabwVO3Zs1/fSpUsrkyf/HLSxk+gjQYKYHIHpM6bLnTs3gjSGBJI0aRKNSUfFHcPBg/tly+Y/ZPfuf32eMAkF3ll88blz52XEyB/1876v9IoVFoYcvi+/Gmp9/cMPP0rKFEmsVWpmzZ73/9uEBl4/+XTM5D/gDcJ5gwZpQ4d+I2nS/GftnTP3V/nzzy1amr7r853cbqT4n7B3Pl7HrlatavLPP7vlwvnTcX4fIXRgwYJfJW2aFBIuLF8RozSfPnMyXvvowQfzqVIxdNgwOXr0kGzfsVN27NglJ0/GKOCPPvqIzJ37iwSb48djummvWbPap9fxli1btQgAzl3MaUOGDhGLJeZcDgSvvf6/wCoVaM5VrFgxqVixonaLhiLxzDPPyOuvv66WeHRErFq1qvgTeEOgQKDCAxIJUX3h2rVr0rZtW4/W07Jl24A1TYELEzeXpElTSPv2/q1YYKzeoFr1mlKiROyYXhJcNm6MseTUrVNPzwVHXgr7BND6TzeUJEle0vPd3+cPIbbkzJlXVq5aI1evXAvKuYebadp06R2GqubNm1//ENJ68cL5gFViwe9MnDRNjh8/LgUKFJZKlSrFsqjCwogwYBjfkHh67fpt6datp34+afIMfWzTpq1ayon/mPnLPN3/hYs8bN3XSKoe8P5H+vzUqdNy9dotebFnzLGJ65h//c23+rxLl25SvLh/w28KFXpYFi76Xa4E6bqLLxMmTNXHFs1bSZUqMSX1PaF27fpSaVkVOXz4iAweMtz6PhT3GtWry6BBAwMS7eFOsZXp02fJxYuXpF27Tj4T+pcui6kA2aVLZ5k0abIaMPLkKeCzYgOBwm2loly5cirYPP3006pMACgUOODI2EeyKV77E7jEUAP5ww8/VCsEKiXMnDnTafiTM7JkzRaQnArw5JNPqVKxY8dOn7mXXGFbQSgQv0fc58DBg/pYqnRp67FxVa5SvRVp0mrJPbjPeTxJIKleI0YY27N3ryRPkTJoN/RrN+/KuNXnZfqmC3Lswm3JkS6xNC2dTtpVzCApkibV+TyQ4CY/YcIE2bZ9hzRt9qz1/V8XxOR+oIwo7pVt2rSRsWPHSb9+/dWIZcptVq9eg9eyn4G8AqVi7959krVddrlx44a88+57+hkMotu3b5dhw75VBS+uMsWwniMSA7JOpcqV/S47PPn/QiSqCyVJmkzn/lAHRXQO/n8RkifKlo3X+Y3vIIQeZfghw1SpUkWeffZZadiwYazcpGCTLn0G9XAhYsciCSSbD67ls2fPypo1MSF2L7zQQ5IlSy7fffed3Lh5K+zmCrdrSMEKgxq9aD6CCRMVoNauXaslXlFi7aOPPgrIyY9EHcQbonQZQp/KlCkjoYwZHzw9yD/xN7Bwx6cpE/EvphurfQOvuMpVgldffVW9hIQEEhhrcueOKRaAct7B4NrNe9Lph0MyeNFpOXr+tsAhgUe87vTDQf080EDYAfDQ2woFpo9By5YtNUQX1yw8F/Coo0gDwnURMuxJLD/xriSyad6IAjNQ6nBOo1Fv7dq1NUwKBWbiKk2K2HmA4xkIYyS8XCh+E4pN8LAvHMkxqGqI/Yn9gzkjvuBaGTt2rB4rdNlGX7JQUigAttE09/NVZ+3Zs2dr+CSSwJGoj4gcbDv+wg23lQqEPQ0fPlwFI1yg0N6RsI2qIF9++aV6Dsj9oAwibiSYuPx9YzZW7/g0ZbIFk24oNL2KJHC9YNJNliyZ5MmTR9+zLVfp6A/lKrFMrly51PJGSLA6FAers/a41edk+xHH+Rx4f9yamLr4wVAqMEea/EL0bUI8NLznqFKFnAvU3ge4b6L8elyNz4jvMPsZ91wY9EwnZvQ6gPET3bFRYQiG0e+//94tpSKQFdBs+1WECghxR7gfwtDtMV64Bx980Kt+B1Ag0Ik81CqJ2mO8W75SKqZPn27t2QGgVL755psSjnh89FOmTKkdrWGVwcXWuHFjddNgJzdv3tw/owxzAnVjNlZvWyu3bfM/d4BbGC5HHEt2jPR90zsjcNiWq9zd4D2Hf/gMywBaN0k4zF2YM7Asct18AUKeXH6+0bddk90BRgFUosLcakIWJk2apI+tWrWyLoewDVzvCJ356quv9D120g4MiKpAgjz2PcLRoPChIa0J3YY1fcCAAfr83Xff1Ua+cSkVptt1IAjFztqIDAG//PKLtcmdN520wxnTWdsXSsXJkyetXk+jVJiKpzAUe2MgDgZetdCDVvraa69pLgXq6SJEityP6RCJ7rT+wlEFIZyM7la3MMDlaE50ep98h2nQ2LlzTDJWsLpdEhIfi6+7nstp06ZplSZf5dchh8IVx+P43F+YoiTLly/XmvXIK8Q1CoOMAa/79++vz+GlBPRUBAbkPxjPAsr8wiuBiArbpNrnn39eypcvr03t+vTp49CIZhv6F0hPRSgqFSYUCwrarFmzolqpMJ4KYyz0hlmzZmkkCwwOMFaEezh7vCWVVatWadwXFAv0poBVxpRdI4H3VDirIAQ8aWdvqxgi0Y34BjP5nDhxwu3v4HpC6JMRTAgJNCjjrc0Zjx3TP3fd+CigAeHDW5CU7YrscXweiLwK46VAArd92AY8+caqafYnCQy2XiF4IzCX2oLzeujQoZpEj8gLKMT2oMoXisPAOIcE70ArFTBG+crr5y1o5mhAHm00KxXwQBoZyduIjul2oU++Dmd3lLeCEDZ/yaMeKRW4wBCTCI29bt26aqHBa5xQuDiNRZ44vjEfPXpU96GvcVVBCCeju1ZuNBK0PdF8oYW7Cy5MuJk9DdcKN08FlHB3qVGjhvaBQREEQoIBwl3NDTSumxDKu6LcOEDYiQkN8gZUeXL5eRnXn/tbqYAlGYml9qFPBtvcCuzHUEs6jWRMXxPIJSgs4wgUzUAhDIC8C3sB0YQ+YTnTbyQQQDnNnDmzGgSRExJsIBsgcsF4emBUtjUymCIk0aJUFCxYUK9tNDT0JqLj+PHj1nkSuSRxhbP7gsmTJ8vo0aP9Jt+5rVQgFhEWlxEjRmhlC7jDFy1apPkVuPEQ58D1am7M/giBcqeCkDvaNI6n7XKBVCqGDBmiSWADBw6USAP71OzLuMoX2oMynoFqfkOIN55W3BxtK8P4Ihy2XcX0UjxXMoef4f12FYIjpEPoQ5UWXNso/ZkiRQott+7s3vnzzz/LmDFjAj7OaAaFZFB0BOElrsKAX3jhBVUYkE+4bt26oCdpA8z55jdDIQQK+8YI0wgZw3lvLOy45mEwNZ9HAyi4YgyE3uRVzJgxQ/dl2bJlY1XNchbO7gvl8M8//9Tn1atXl6AqFYhRHD9+vFpcP/jgA51QSfBDoNytIOSOYIoJGOTNmzegSgVKqcElB0aNGuWTsIlQ4vTp02rRwDHwxFNBSDjNXUaJQLU72/kkviBPIUXShDKqS155qVZmyZk+sXajxiNe4/0USYOXa2S8FQDhvzAeOQLXPfo42YZBEf+D/V65cmXN93QFqkGZIjMoOmOLEegDmaRtML9pFJtQyKdACJjZVyYEyngpkFgcTZ44UxreW6XClZfC4CtvhfEko7qYvypsuT0j4wSCJcbTxF8Su1+Frz0VnlQQcuWtQCIhSsYBUzLOhOz4GwgjxtIBATzScnOMcoYycYF0oRPiS6UCCauuwhNNnwbEr8MIBWHDxFp7CkIrkI+AOQmKQ7enMsnC1wvK9kFF9RGvg6lQ2CZrm94UJHxB0rapbGQbzmIE+mDkwpiysqHQq8LkU6CPAjxviRIl0vkAMoK5xqPN0GyMBPHNPT18+LAaTqD82ioVcYWzewOiUUDN/+8y7w9YUibAN2a4noKVN+DKW4HQBTRqQhynuUEi3g+x0f7mxx9/1EdjUUKoQCRhlLNom3RJZICQPYT3oCeDM+8lFAj8QZmA1R6hjN54K6BM4Pc+/PBDCVWgVMAyC4ulid8n4QlCjZB7AS+5CVNDqAiMXbhvQpgOlqcCORXB9t4bpQKKTqZMmayhM1OnTrUqFdES+uSrsrKzZ8/WR4STGe+uu+Hs8QH5OcZgi3xNf0GlIoA3ZrjHEX/oq4YptqDBUpYsWfRmbu+RQJ4CPkNyvTNvhQldQKdRuIONa8zf3or9+/dbT3Tk64D58+ffVwc7nDH70LaTNiHhAqySxlLrrLSs8VJUqFBB84Aw13ijVJg5IZSFdSgUsNZCAcI+IuGNSeaGkQshuTCoodQshMe4Qqj8AcqL4ndRACGQ+Y323Lhxw3oPM8qVCYGyVSqiJUnbYPIj41sBatH/ew3q16/vcTh7fEAoHyqZ4ZxCDoe/oFIRIBA2ZmqU+zoEChMgEp1Reg59EOw9El26dFHvyMqVK2X16tUuhQIoFbYCsL8nM+RQ4IKE5oy4Y8RsIhTLUXm/cMXsQ3oqSKTmVSxcuDDW/GGUCnhAkU/kqUXNhGL6K5nQVyCOPG3atMEeBvEBCLfD8YR3AlX3ICTDU+aog3QgQHUhI8QHMwQKQjNkDCjRpgkrBGGE8sI7aWSHaFMqsL2mAhS8Wp5w/fp1raBlH4rkSTh7fJUYeFhRRtlfUKkIQl6Fr5O1586dK4cOHdKL3lFsb9asWbWrKDCdXW0xsc+wtpmbeCCUClhgjKvZNIVr27atPk6YMEEiBXoqSKQoFfAiIizJFjQPg8HCVqmAlRWWPBgzPM2RgkUNnkpY1FimnASyok/Hjh0ladKkVuEZmC7cwSBQFaBwjSJqwFXoEwx+xmCJqAt0KAcmRDrawp+gVJlmdZ5Gn6xcuVI9QDlz5gxYAYdA5FMAKhVBuDH72lOB0CcjmDtLBO7du7dq1bAqmBwGg7E0VKxYUUMXAqVUoNTf2bNndQI3lk10pIVXB4pXMF2+vgLhblD4AD0VJJzLc6LQAPKsPv7441ifoas0vIv43PYcN0KHpyFQRgmBRQ05GoQEiueee046dOigeQNImEVibDBCnwJZAer3339XLw3uvY7CeGzzKWwxIVAAskWBAgUk2ohvsvbC//fsQsB3t2Q8jg/C2H/44QeHnyMUrVixYlYDjy0XLlyQDRs2+D2fAlCpCIKnAlqtvbXPG2s/KgiA9u3bO10OVoQ333xTn7/yyis6kRjMTd8I9oFSKszFAeuQiUmGV6VWrVoR462AwGW2C651QsIRGCvQHAyg0altQy4kkcKdDi+F7Q0SioixkCF8wl3M3FStWjUfbgEhcYNy6v/73//0OZJifdl0zBulAoI9wgL9wffff28VjE0/CltM6JV9sjoEYuRfAhgU4OGJNkxehaeeikX/7zUwso47wGuLEHdTFtYWeITfe+89OXjwoBqQ7efbZcuW6TIw+piWAf6CSkUAgWCJBiewBpgGJN6CsCWcQIjrxYXtin79+mnXV5xcaFqIuFFUfDKxfUYIsL1Y4BKFm87X4LcRbw2vBJQKW9q0aWNVKsK9w/bIkSP1kSUnSbgDpQGNT3FNvvzyy1arJqycsO7azh8AyYAIyUTMsX1TMWfA2GKW9bdFjRBHwPhjynr6qulYfIFxD8I67tPxLV3qihMnTsTyJJq+CQZc40bRsFcqYEhAHmQ0hj7Zeyogz7jL3r179Q+GVE8KUaDnCoC8Zq9gQkmBQmHCre0bbRrvr79DnwCVijBvgmdOZnTsjsuNhs9hZUSFFkxSzZo1k0mTJqlSgknBdmKAAoRQKJy8prmNLzEhWAiRsI1fNR4TWEAQagENO1zBxQ2rK/Y7kuUJCXc+/fRTLS+LKlBINjS89tpr1jKyBhgMTI6FuyFQcN1jPkKscjSGU5DQwJT19FXTsfiC8D/TD2XevHk+Xz/Kt8NIYMKm0afDNgQK3eIROgMB2FFOYN++feWpp54KWjJ7sDE5L2vXrpVPPvnEIy9FuXLlrOHm7oBCP5h7ETJur8QYb5MxLKPAgImGwfEMVD4FoFIR5k3wTBgClAp3gNVj4sSJ2tkZsf6YFIC9lRGCsJlEfF1WFnkGGINt0yH7MSJ+MNx7VpgLHfvWJHQREs7A09q/f3/1TOAGZ+LOYRhwlM9l5hV3lQqGPpFgY998LNjeCngHTUGW+GCuUXtgMDQW7QEDBuh9F5EPtqGNJp8CkQuOwptwX5szZ07UXq+Qkd555x19/sEHH+hfXOVl4xP6ZBRM9LQAtnkTiCYxORrIq4BshybCX3/9tTU0CxXNUIgAebP+hkpFED0V8alt7MpT4Yl7FyVbEZpgxmAsirb4K68C1hB4SnDyO3P/mRAoTFiBaMDna2AlMApR9+7dgz0cQnwGrJIIpXQn7hwhTLBywjABl7+7SgVDn0iwsG8+FmxvBbz5MPLBOwjh0FOcXaMrVqyQffv2qbUcRgJjxbYNgXKWT0H+4/XXX1dlAnzyySea2+BMtkMoOfZ7fJQK2xAoW6Xip59+0t9D5U6EY73//vv6/uDBg+XYsWPW0Cd811khH19CpSII7jLcZBHLGJ8JwplSgax/T2ssQ+hFXCRCnRxpsP5SKozggPArVI1wRMmSJfX3EWIxfvx4CTcQVgbFCfsZ7mFCIgUzZ7gTd45cLzO3oJy1qwIVBw4c0FBLhE1VqVLFb+MnxF0vRSh4K3CtIVQmLm8FBEt7YdbVNWq8FIgKSJkypbV07syZM63rMZ4KKhWuQY6ZCX/64osv5I033nCoWKBPGGQadND2VGZzlFcBJcUcRxP10bBhQ/Vo4Heg7BjPSKAMNVQqAgxCBlDv2RchULhBm+QcTzwVticoPCbQnB01Q3GlVKAz49NPPy3Dhg3z6DdxoZnEcHOBOAKWGdPhFJq/rUs21ME2mgRtXOjOFCdCoiHu3BQpGD16tN5Iv/zyS+1tYcDNEVZYU6oWVU7YUI6EgpciVLwVuNcaz70jIEBCeU+XLp1W+Dl58qTLaxRx+SjpDjp16mTNZTQhUMZY6SxJm9xPz549dW4DyF1FmKi9YhGfUrL2xlYogOjjg2MEBRDPc+XKZQ01xXoHDRqkz2GQNV6NQORTAEo7QQAnhi9qT5syZtB6EcoUH5AMiQYsjjBKBSYZ+ypMyBdAEjViMW0FhLiAuxUuOSgxcTW2gkCOCwETJpriefI7wS4ji0oduPhNGBch0Rp3jmsX5aNRCAI3QMQgQ7mAsQACDeKykYxqPJL2+V2EBIKTNy7LnKPbJHnCxA7/Zh/ZqssEU6mAgOioQz0UdoQq4T6NZW09iY6uUSgL6C2DkrUm2RhhUMaaDWEVRksTsmgMocQ1Xbt2VYUCwOBqnjtSKuKDbV4FjMEmbxP9VUxZfpO726RJE1VqUPgCZWQD1fGcSkUQME1kTLxioJK0PQWVBCD8w8VmGrgBTFzG5Ya6yZ5UpTBeCuSWwGvjClj4cdEgCRSKzUsvveSTPBRfgQnj7bfftlqFDMZLgfK9tLiSaI87h+UM3gp4Rb/77jvNpYKl9PPPP9fEQjxHgzEIQ0OGDInaSjIkuGRNllq2139Ldjd4z+EfPsMywQDXDO7zuPcuWLAg1mdQDkxS7kcffWQNw3F1jSLxGvd2+3LutiFQRr6A0TJz5sx+3sLIoWPHjjJw4EB9jt5gyCE14Z2QYxDe6U1ItInwgGyEhnZQNJATYw8MvqZ5KJTF+HhG4gOViiA2tPnrr7+Ckk/hLjj5TZlZ2xAoxOih1Jxt/oC7GFecfflJZ6CzKRQYjGXKlCkyatQoCQUwQcC9iThxHE+U2oRH5fDhw1Yly4RvERJJxDfuHJa01q1ba6gTlAtUtUEp2t9++02NFphH4LmIxiZahLhbBco+BAr9nJCfmS1bNi0KAkEyrmsUngyUObftim1CoKBs4H4PhR8w9MlzXnrpJY20gBEU+xkNik1uA/r3IEzNW6UCCorpE4TjaQ88wG+99ZZGTLhqjOxrqFQEASgBsMKfOnVKE7YDWfnJUxzlVaDaAKhfv7418dreWu8IXGBGqXCVT2EP3H0IlQAQQrz18PgC0z8DxxFhWai4ADcyJhPEiCPR1J/HhZBwjTs3ygXKSr/77rsaC24saoQQ10oFqvmYHjEIbTFx/EgWNteRO9cojGL2nnS8NiFQ5j5PpcJzEiRIIJ999pkqaYj0QDK8Ce+MT9UnWx5//HFVFAyOyvIb0DIAMiZ6XASKsFEqYAlGySy44ZzlAIQLCPsx8W3eCMj+Dn8C9r0qYBEx7lcI0ojdgxA9ffp0t6z7+D4mPmjrnoDW87hAb968qd3AUVkpFJSKV199VSdf1O/HthlrRLdu3YI6PkKiLe6ckEgGHnHcZxByvGTJEn0P913kKSKn0jRYdfcadZaHaUKgbt++rY9UKuJHokSJNNcFSgByyeCh9UXCNOQnNDA2BmqTY+GMQIU9Gf7L7AhxEDeIkx3JvWPHjpVImCBg/UcIVHw0V3g5UIEJJwziIwPlqUAoEpQIhC/hM7hPUcVq8uTJ0qNHD5frMl4Kd/Ip7IFHALkKsGoieQzxhKZxn6/BxQ9lz1TFcORxQTI2QNMf7AtYkZCYhXJyiH81XhxCIjHunBASWHCvR97R8OHDtbQsjGywhhujmwkb9PYaRV8MhEBB5gJUKuJPypQptScYcigQ4okwJZNT623eBrp4I7wp0EpDxHgqsPOQwOev/IFwy6swXgpUb/JUQPcEo7BAqYCr1SRoo9oAaNq0qeY7QBCPq/O2SdKOb1dHWFaMImGfrOZL4CpEtQQkljrb9+hYif1uKlihqQy8Fsg1Wbp0aaxKDIQQQoivqkAhbw8JwKgyiJCluAx6noD1ISrE3NdMXiWJH1mzZtWGgojOQMiZL5SARo0aaViTCYkLJSJa8oEQbFsKFaEzAJZ2/AUTU6INSkV8xmIb+uTPbYHSgosAZewQE4gQHwj3OJnxu0ikxgSEUmlItITy506SdnzHbCY7VD2ASzE+CU/YHvxdu3lPxq0+J9M3XZBjF25LjnSJpWnpdNKuYnr1QEBJcjRO43qG2xHKg+0yWC+UrGCfX4QQQiIL3HPSp0+v9z54J0xMPbwUvrznICrk119/1TxB3NN4P/OOwoULW0OjQ3Vf+qqfVkQrFevXrZE1a/5rZ244dfKIw2ZvgSR7tkz6uH//ftmzZ5ekTpXKo+//+UdM47w8eXLKyROHxZ+gsQqqGg0YEJMs/UzjhnLh/Cnr53Xq1FClAlUounRuLylTppa06TLqZxcvnJVr167IkSNHdR0QwvPni/+YkyV9QBUdxJH+8ss0qVuntmffT5ZC0mfIrApFpx8OyvYjN6yfHT1/WwYvOi1Ldl2WUV3y6ERw9sxJuXXrv2XAwoW/6WOpUo/5fd8TQgghhiefrCIzZ85SQx88Cc82a+zz+1DVKuVl4IcDpGTJx3mPixKy58gb/koFmiCZygXOQFiNiev3lLLlKkjpMmVjeSpGjhgiWbLmCnrZwqzZcquwjnCZU6fOS8GCRT36/r79MZ20n3iivK7LnxQtWlQVgtOnz+jrHj17xfrN1q3byzvvvK/bcujwCSlb9r+TM03aDJI6TXpZ/PsKa+O//AXidzwNiCVF/sLGjZulY8eY5DR3Ma5HeChsFQpb8P64Neel21OZJGGipJI1w381upG8tmlTTMLV00838vu+J4QQQgzNm7dUpQJ07txZij7sfYy+I3q99LJf1ksim6AqFb169Yqz4zBq7cYXWMUdxbbDzeMrV4+3eRUQxJEU7G7fBuM+QyylbXlaf4K8CtMJEqVg7ZW8VKlSaTgUSkRie8qVK6d1siHAZ0+eVh9Xr16ty6LUqrfjrV27tioVKK1nQpk8BSFPLj/feEGVCvvwqs2bN2sJWYSAwTUcCucRIYSQ6MBUwUSpUoRA8R5EQomgKhW4MKK5UyOqKiDhatu2bR59D1UEINgihAuVhvyNrRJhErTtQcdcJCOZJGzUwoawP+jRhvp63bp1+uiJ8uQMlFNDkvTx48c1t8Tkp3gCcihccdzmc+TlIE/CtpSsL5QjQgghxBNw70PRE9yX0O2akFAibKQihN/Aoo9HXEx4jj8I19FWAco0vYOwH4imUWacSMpu2DBGSbCnatWqWp0Lk5zp5mnbYRcl1SCYw4vhLcmSJVOhHhgPiqcgKdsV2W0+R+k2g1EqnnzyyXj9LiGEEOIN6NWVJ0+eYA+DkPBVKj788EO1UA8cOFAVCTzH359//inhihHWd+3aZa0JHSqdtG1BmM+oUaO0hJ2zXBSEmb3yyiuxunnadu9EuVWUVEOolC8wDWRMRQVPQZUnl5+Xifkc5WFNYz80HULVKUClghBCCCEkDJUKND6DMmH/ZyzW4Qi6Y6I8HJJ/oVh4Wk42kD070GYeykVc9a2Nl8JgvBWwrCCHxlcYpQJehPh0125XMYMUz5XM4Wd4v12FmG6jaLIHZQreMfwWlD8k2Aci7IwQQgghJFwIG6UiEkHOgelWiVCuUPVUeILxUhhsvRXetqe3BWVl0ZQHvUhMSJInpEj6gJaNfalWZsmZPrEg1xuPeD2qS179HAnxSDBHozvEsNqGPoVaF0tCCCGEkGBCpSLM8irg1TCdq0Otu7i9l8LeW4FcCF/iKgQKHoU9e/Y4/e7evXslRdKEWuFp4esFZfugovqI11AoABKxTQdTJKEbpQL5IYQQQggh5D+oVASZEiVKeKRU7N69WxWL1KlTaxhOKHspHHkrfEmtWrWsSoXFYrG+f/HiRalRo4aGa6HsrCM6deokrVu31lb3rmjatKlVqdiyZYs1KZ0QQgghhPwHlYoQUSq2b9/uVvt2k0+B0KdQCsE5eeOyzDm6TZInTOzwb/aRrbqML0F5Wng/0BvD5KQgzwaKgEng/+yzz+77HsKZ8Pns2bPj3IfI2UFPCnQvheKCnh3ZsmXz6XYQQgghhIQ7Qe1TQWLKwqKi0uXLl2X//v1xJgCHaj5F1mSpZXv9twL6m8mTJ9dmfPBUwCOBRoktWrTQnhhoWnf16lXNidi0aZOULl3a+j0TxoT+FlmzZnX5G6hq1ahRI61+BVj1iRBCCCHkfuipCDIQWk1uhDshUMYiH2pKRbAweRVoItiuXTtZvny5lq2dOXOmNG/eXD8bPHhwrO8sWbLE2pnUHZo0aWJ9TqWCEEIIIeR+qFSEUAhUXBWgUNYUVvdQTNIOtlIBj8SCBQvUezFt2jQpU6aMtYQtSsIeOHBAnyOEySgV1apVc+s34A2BRwlejXAuYUwIIYQQ4i+oVIRQBai4lAoIzkgsRmgPGskR0bKyCHsCSZIkkYkTJ2quhQlvQsI2clWGDRum7/3zzz9y9OhRDTlD80R3vUnwgCAPI02aNH7cGkIIIYSQ8IRKRRhVgJoyZYo+Nm7c2Gln62gDidbdu3eXzJkzy9ixY1WJsKV37976OGbMGDl37pzVSwGFAl4Nd0FIFZr7EUIIIYSQ+6FSEQLAog7h+OTJk/rnCPRdmDVrlrW7NfmPnj17yr59+6w9JWxBDgQaDF67dk1+/PFHj/MpCCGEEEJI3FCpCAFSpkwphQoV0ucbNmxwuAyqG6Gsafbs2a3hPeQ/nJWGxfvGWzF8+HBZuXKlPqdSQQghhBDiO6hUhAgmbAeVimwbudmHPqEHQ8KECQM+vnAG+yxHjhxy6tQpLTOLUCkmuhNCCCGE+A4qFSFCnz59NE9i7dq11hAdAxq6oWQqMGVSifskTpxYQ6QMqPr0wAM89QkhhBBCfAUlqxABlvTOnTvr8w8//DCWtwIKxfXr17XS0eOPPx7EUYYvHTt2lNSpU3tUSpYQQgghhLgHlYoQom/fvlqRaOPGjbJw4cL7Qp+QoO0sd4C4BpWbkFPx3HPPaTgUIYQQQgjxHVQqQgg0V+vatWssb8WZM2fk999/1/dY9ck7UIoXOSvJkiUL9lAIIYQQQiIKKhUhmFuBalCbN2/WsCd0g75z546GPRUuXDjYwyOEEEIIIeQ+qFSEGKhM9MILL1i9FZMnT9bnTNAmhBBCCCGhCpWKEKRXr16aVLx9+3atBoU8CuYBEEIIIYSQUIVKRQiSMWPGWCVQK1eurNWhCCGEEEIICUWoVIQoL774oqRLl06fM0GbEEIIIYSEMomCPQDiGCgUY8aMkWXLlkmbNm2CPRxCCCGEEEKcQqUihKlevbr+EUIIIYQQEsow/IkQQgghhBDiFVQqCCGEEEIIIZGvVBw8eFB69OghxYoVk0yZMskjjzyiPRxu3boV7KERQgghhBAS9YRFTsW///4r9+7dk8GDB0uBAgVk586dWh3p2rVrMmjQoGAPjxBCCCGEkKgmLJSKmjVr6p8hf/78snv3bvnhhx+oVBBCCCGEEBJkwkKpcMTFixclffr0Lpe5c+eO3L171/r65s2b+givB/4IIYQQQgiJZh544IHoVSr27t0rI0eOlIEDB7pcbv26NbJmzcr73j918ogkSZLEjyMkhBBCCCEk9MmeI69P1pPAYrFYJEi888478uWXX7pc5o8//pAiRYpYXx87dkzq1KkjlStXlmHDhnnsqRg5Yoi82OsVSZo0qQ+2gBBCCCGEkPAlIjwVvXr1irNbNPInDMePH5d69epJ2bJlZciQIXGuP1GiRPrnaOf5agcSQgghhBAS7QRVqcicObP+uQM8FFAoHnvsMRkxYgSVAkIIIYQQQkKEsMipgEJRt25dyZ07t1Z7OnPmjPWzrFmzBnVshBBCCCGERDthoVQsWbJEk7PxV7hw4VifXblyJWjjIoQQQgghhIRJR+22bduq8uDojxBCCCGEEBJcwkKpIIQQQgghhIQuVCoIIYQQQgghXkGlghBCCCGEEOIVVCoIIYQQQgghXkGlghBCCCGEEOIVVCoIIYQQQgghXkGlghBCCCGEEBL5ze98hcVi0cebN28GeyiEEEIIIYSEBEmSJJEECRJ4tY6oUiquX7+mjyNHDAn2UAghhBBCCAkJevTsIylTpvRqHVGlVCRLllwfu3V7UZImSyaRDLwxUJ66de8lSZMmlUgmmrY12raX2xq5RNP2clsjk2ja1mjb3mjc1oQJE3q9rqhSKh54ICaFBApFpJ8kBmwntzUyiabt5bZGLtG0vdzWyCSatjXatjeatjWBl6FPgInahBBCCCGEEK+gUkEIIYQQQgjxiqhSKhAvVqFCZZ/EjYU63NbIJZq2l9sauUTT9nJbI5No2tZo215ua/xIYDF1VgkhhBBCCCEkHkSVp4IQQgghhBDie6hUEEIIIYQQQryCSgUhhBBCCCHEK6hUEEIIIYQQQryCSgUhhBBCCCHEK6hUEEIIIYQQQryCSgUhhBBCCCHEK6hUEEIIIYQQQryCSgUhhBBCCCHEK6hUEEIIIYQQQryCSgUhhBBCCCHEK6hUEEIIIYQQQryCSgUhhBBCCCHEK6hUEEIIIYQQQryCSoWbrFixQlKlSiUXLlxwudzDDz8sw4YNk2BQp04def311+O9TePHj5ecOXNKqBLq47OlW7du0rJlS5+uc+DAgVK+fHmfrjNSCMa+ic+1fvDgQb3mtm7d6rdxEUIIIcEg6pSKH374QbJlyyZ37tyxvnflyhVJly6dCuWOhO59+/ZJuXLlZO/evZI2bdqwE3CdYb9NJPJxV9lZtWqVPPvss1KwYEG9BubMmeNwub///luaN28uOXLkkCxZskiVKlXk8OHDLte9fft2qVmzpmTMmFGKFCkiX3311X3LzJgxQx5//HFd5oknnpDffvtNImFf58qVS685KCSEEEJIJBF1SgWEHigRf/75p/W9NWvWSNasWWXTpk1y48aNWEpF7ty5pUCBApIkSRJdJkGCBBIpROI2Ed9w7do1KV68uHz55ZdOl4GyXatWLSlcuLD8+uuvsm7dOunXr58kTZrU6XcuXbokDRs2lDx58sjKlSvlww8/lEGDBslPP/1kXQbr6dSpk3To0EFWr14tTz/9tArnO3bskHAnYcKEes0lSpQo2EMhhBBCfErUKRUQgOCpgEBjwPP69etL3rx5ZcOGDbHehxJiHyqE5927d5eLFy/qe/hD+IWtQPbCCy/o7zz00EOxBCZHLFq0SC238HxA2GrWrJkKbK64evWqPP/88yqgPPjggzJ48OD7lpk4caJUrlxZxwHFCILaqVOn3ArpQphG6tSpYylfAOEeRYsWlXv37jkc182bN+Xtt99WC3SGDBmkRIkSMmbMGLFYLPr8m2++ibU8wkAwBlhvAcbSq1cvyZ8/v1qpy5QpowKrM+bOnSsVK1bUZSEEQ0C19UI5sx5jORzv7Nmzy0svvSS3bt2yLoNt+/zzz6VYsWKSKVMm9ejMnDnT+vndu3elR48e1s9hUY8rDOaPP/7Q3zNCOrazZ8+e1jHUq1dPtm3bFus7X3zxhe4HHD/8HvatK+IaF87Rn3/+WfeZOW9xDjgCysK7776rCoAzBgwYoMtBMXj00Uf1HMN1BI+FMyZPniy3b9+W4cOHq7Ue3hBcK0OGDLEu8+233+r10KdPH71+3nnnHXnsscdk5MiR4i44hh999JFe7zgPERqF68yWo0ePSseOHdVwgDHjWtm4caN+huuvRYsWuv9xjWEeWLp0qdu/72xf24c/mWtw8eLFUqFCBT1uOBdwnS5cuFBKliyp5weuXcwr7p6jhBBCSKCJOqUCQECwFabwHAJFpUqVrO9fv35dPRdGqbAFN/BPPvlE0qRJo8Iw/nr37m39HAISBDpYWSH4Qzj6999/XSoIL774ov42hJAHHnhAWrVq5VRwB//73/80RGXSpEkya9YsVYD++uuvWMtAeIOAv3btWl3u0KFDqgy5A4Tdp556SsaNGxfrfbxu06aNjtER2N6pU6fKZ599poI0lIiUKVOqN6Rdu3YO1welAIoRtrdJkyZqqf7xxx91/7///vtq3XUE9m/Xrl1VkMayUKwgyH366acut23ZsmXyzz//qLIyatQomT17tioZBghrEyZM0LFDyMSx6dKli1URxTgR7oOx43f79++vAvb06dOd/h6Ecwjpr7zyir6HfXH69GkVBLFeCM0QyM+dO6efY10Y03vvvafnBQTb77//3uV2xTUunKPYvxDYzXmLczk+4LcQkoTwqEaNGkm+fPnkySefvC9MCkqcbVghlHYcb3jJDNWrV5fdu3fL+fPnrcvg3LMFy9gq/HEBxQTXIYR7nE81atTQMK09e/bo5/BWYlzHjh1TRQfXCK5Tc83hmoTChOsR5xm+DwUortAug6f7GscaSuTvv/+uyk779u1VIcT5OW3aNH1/xIgRbp+jhBBCSMCxRCGjRo2yZMmSxXL79m3LpUuXLGnTprWcOnXKMnnyZEutWrV0maVLl1pSpkxpOXTokL5evny5vj5//ry+HjdunCVHjhz3rbto0aKWzp07W1/fu3fPki9fPsv333/v9vhOnz6tv7V9+3aHn1++fNmSPn16y/Tp063vnT171pIpUybLa6+95nS9f/zxh64X33dnm6ZNm2bJlSuX5caNG/p68+bNllSpUlkOHDjgcP3//vuvrm/JkiUOPz927JglTZo0lo0bN+rrW7duWfLkyWMZP368vl68eLElderUuh5H2I+vfv36ls8++yzWMhMn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Tfur+xqZRNO+Rtv+RuO+pkmTJsmfFVVGRerUMSUkGBSRfpFY2E/d18gkmvZX9zVyiab91X2NTKJpX6Ntf6NpX1MlMfUJtFBbURRFURRFUZQkoUaFoiiKoiiKoihJIqqMCvLFrr22UUDyxkId3dfIJZr2V/c1comm/dV9jUyiaV+jbX91XxNHKpfVWVUURVEURVEURUkEURWpUBRFURRFURQl8KhRoSiKoiiKoihKklCjQlEURVEURVGUJKFGhaIoiqIoiqIoSSJqjIqhQ4eaypUrmzx58pimTZuapUuXmkhl9+7d5p577jHFixc3efPmNfXq1TN//vmnCXd+//1306VLF1O2bFmTNWtWM3nyZPdr58+fNy+++KLsa/78+eU99957r9mzZ4+JtH2Ff//91zzxxBOmfPnyco6vueYa8/nnn5tw5P333zeNGzc2BQsWNCVLljTdunUzGzZs8PpedCX+85//eD0m4cJnn31m6tevbwoVKiSPG264wcyYMcP9+pkzZ8zjjz8u47dAgQLm9ttvN/v27TORuK+waNEic9NNN8m45T2tWrUyp0+fNuHOBx98INfpM888I78fPnzYPPnkk6ZWrVoyZitWrGieeuopc+zYMRNp+wpcs7179zalS5eWc3vdddeZH3/80YQjb7zxhuyf88F5jMT5yZ81BPv52muvmTJlysjr7dq1M5s2bTKRul5av369ufXWW03hwoXlWuZ+tXPnThNuVK5c+arrmAf3m0DNT1FhVPzwww/mueeekweLtapVq5qOHTua/fv3m0jjyJEjpkWLFiZdunRm/PjxYjy99dZbJmfOnCbcOXXqlJy7Dz/80Otrf/31l3n22WflHI8aNcps3LhRJoJI21f473//a2bNmiWGxLJly8zDDz8sE8KUKVNMuMH5uu+++8zs2bPlRoyB2KFDB3Py5Mmr3vvJJ58EpOtnMClSpIh59dVXzW+//WbmzZsnN6iuXbuatWvXyutcwz///LP5+uuvzbRp08zevXvNHXfcYSJxXzEoWIQ1b97czJkzx8ydO9fcf//9JnXq8L41MSa/+OILGcMWHBw8WKAuXrzYDBkyRMbwQw89ZCJtXwGnDnPw999/L+e5ffv2pkePHmbFihUmHKlUqZLZvHmz+zFz5syInJ/8WUN89NFHcv32799fxm2WLFlkTYVDJJzwZ1+3bNki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cDNnzhzz8MMPiwHRokULec/vv/9u7rvvPjFKLl68aPr162c6dOhgli5darJkyeL+PgyYF1980f17pkyZ4l3QTps2zXzwwQcmHClQoIAJZziXGBTsxy+//GL27t1r7r33Xpm3OMehSPbs2eW69gVjsFSpUmb06NHiWFKUiMKlKEpQuO+++1xdu3a96u9z5851ZcmSxXXkyBH33yZMmOC65pprXLly5XJVqlTJ1b9//1j/hvdPmjQp1t8KFy7sGjlypPy8bds2ec/YsWNdrVq1cuXOnVte2759u6tz586uIkWKuPLlyyffMW3aNJ/bPGrUKNf111/vKlCggKtUqVKunj17uvbt2xfrO5wPvsPb34D9e+ihh1zFixd3FSxY0NWmTRvXypUr3d/1+uuvuxo0aOD68ssvXZUrV3ZlzZrV57FyPvh3wHF69913XQ888IBsb4UKFVzDhw+P9e937tzp6t69uxyrokWLum699VbZD18cPnzY1atXL9nmPHnyuKpXr+76+uuv3efA+WjdurX8fenSpa527dq5ihUr5ipUqJAc/+XLl191/oYNG+bq0qWLnAeuDc/P42++iOv6YDu8bZcnnBeOQ1zX59NPPx3r3/Mzf4M333zTVadOnas+l3P4yiuvuPzlsccek2vB8sILL1z1uT169HB16NDB52fs379f9vW3337zuq3+8vHHH7saNWoU53ECzl3VqlVdOXPmdNWsWVPGiROu9UceecRVsmRJGXvsz9SpU+W1gwcPuu666y5X2bJlXXnz5nXVrVvXNWbMmFj/Pq5tj2uMOecFOz5/+OEHV4sWLeT6Zd82bNgg1yjjOn/+/K6OHTvK8XPCGKxVq5ZsO/s3dOjQOI/bjBkz5Ds4Tlz3nTp1cm3evNn9uq+x4sn06dNd2bJlc+3du9f9t88++0zG0dmzZ31+/5IlS1wNGzaU7WW/Jk6cKN+zYsUK93tWr14t+8o+c17uuece14EDB9yvHz9+XMY647F06dKugQMHxnsNebs2vMFY4fgoSqSh6U+KEuLg9erRo4d4a/Hk/u9//zOvvfbaVSkg/kAqx0MPPWSWLVsmXt4nnnjCnD17VryxfDaf6/TsevOg4+mlbgJP244dO9weZTzNpFvgqXvnnXfkZ7yMpJhUqlRJfrd/gzvvvNMcOHDATJgwwfz222+mZs2apm3btubw4cOx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", + "text/plain": [ + "
" + ] + }, + "metadata": {}, + "output_type": "display_data" + } + ], + "source": [ + "from tatc.analysis import sample_field\n", + "\n", + "# the values over the first three days, with the samples of the sun-synchronous satellites\n", + "elapsed = (times - times[0]) / hours\n", + "shown = elapsed < 72\n", + "three = observations[\"three sun-synchronous\"]\n", + "three = three[three.target_hash == where]\n", + "SAMPLES = {\n", + " \"samples of the 13:30 satellite (one sun-synchronous)\": (\n", + " three[three.satellite == \"13:30\"],\n", + " COLORS[\"one sun-synchronous\"],\n", + " \"o\",\n", + " ),\n", + " \"samples of the 17:30 and 21:30 satellites (with it, three sun-synchronous)\": (\n", + " three[three.satellite != \"13:30\"],\n", + " COLORS[\"three sun-synchronous\"],\n", + " \"^\",\n", + " ),\n", + "}\n", + "TITLES = {\n", + " \"stationary\": \"Stationary field\",\n", + " \"daily cycle\": \"With a daily cycle peaked at 16:00 local time\",\n", + "}\n", + "fig, axes = plt.subplots(2, 1, figsize=(8, 5.6), sharex=True, sharey=True)\n", + "for ax, (field, values) in zip(axes, FIELDS.items()):\n", + " series = values.sel(lat=20, lon=0)\n", + " ax.axhline(float(series.mean()), color=GRAY, lw=1)\n", + " if field == \"daily cycle\":\n", + " daily = series - FIELDS[\"stationary\"].sel(lat=20, lon=0)\n", + " ax.plot(elapsed[shown], daily.values[shown], color=GRAY, lw=1.5, ls=\"--\")\n", + " ax.plot(elapsed[shown], series.values[shown], color=INK, lw=1.5)\n", + " for samples, color, marker in SAMPLES.values():\n", + " sampled = sample_field(samples, values)\n", + " at = (pd.to_datetime(sampled.epoch) - pd.Timestamp(START)) / hours\n", + " ax.plot(\n", + " at[at < 72],\n", + " sampled.value[at < 72],\n", + " ls=\"none\",\n", + " marker=marker,\n", + " ms=8 if marker == \"o\" else 9,\n", + " color=color,\n", + " markeredgecolor=\"white\",\n", + " markeredgewidth=1.5,\n", + " )\n", + " ax.set_title(TITLES[field], loc=\"left\", fontsize=10)\n", + " ax.set_ylabel(\"Value\")\n", + " ax.grid(True, axis=\"y\", lw=0.8)\n", + "# the decorrelation time, for scale\n", + "axes[0].annotate(\n", + " \"\",\n", + " xy=(66, 2.6),\n", + " xytext=(72, 2.6),\n", + " arrowprops={\"arrowstyle\": \"|-|\", \"color\": INK, \"lw\": 1},\n", + ")\n", + "axes[0].text(\n", + " 65.5,\n", + " 2.6,\n", + " \"decorrelation time, 6 hours\",\n", + " ha=\"right\",\n", + " va=\"center\",\n", + " color=INK,\n", + " fontsize=8,\n", + ")\n", + "axes[1].set(\n", + " xlim=(0, 72),\n", + " xticks=range(0, 73, 6),\n", + " xlabel=\"Hours after the start of July 2025 (local time at 0 deg E)\",\n", + ")\n", + "handles = [\n", + " plt.Line2D([], [], color=INK, lw=1.5, label=\"nature run at 20 deg N, 0 deg E\"),\n", + " plt.Line2D([], [], color=GRAY, lw=1, label=\"its monthly mean\"),\n", + " plt.Line2D([], [], color=GRAY, lw=1.5, ls=\"--\", label=\"its daily cycle\"),\n", + "] + [\n", + " plt.Line2D(\n", + " [],\n", + " [],\n", + " ls=\"none\",\n", + " marker=marker,\n", + " ms=8,\n", + " color=color,\n", + " markeredgecolor=\"white\",\n", + " markeredgewidth=1.5,\n", + " label=label,\n", + " )\n", + " for label, (_, color, marker) in SAMPLES.items()\n", + "]\n", + "fig.legend(\n", + " handles=handles,\n", + " loc=\"upper left\",\n", + " ncol=2,\n", + " frameon=False,\n", + " fontsize=8,\n", + " bbox_to_anchor=(0.07, 1.0),\n", + ")\n", + "fig.tight_layout(rect=(0, 0, 1, 0.9))\n", + "plt.show()" + ] + }, + { + "cell_type": "markdown", + "id": "b00d8ade", + "metadata": {}, + "source": [ + "The field wanders above and below its monthly mean over hours. Its values half an hour apart are nearly the same (a correlation of 0.92), values six hours apart are loosely related (0.37, or `exp(-1)`), and values a day apart are nearly independent (0.02). The 13:30 satellite's samples, 11 to 13 hours apart, are nearly independent of each other, but they miss the variations between them, such as the rise to 2 near 45 hours; the train's three samples a pass, minutes apart, would repeat each of them. With the 17:30 and 21:30 satellites, the samples are 3 to 5 hours apart and follow the variations.\n", + "\n", + "With the daily cycle, the 13:30 satellite sees the cycle near its trough (at 01:30 local time) and on its rise (at 13:30), never at its peak. The two average 0.06 above the cycle's mean, so the satellite's monthly means are biased high. The three satellites see the cycle at six times of day.\n", + "\n", + "The predictions use the model's standard deviation (1) and decorrelation time in both cases, as a study would from the field's random variations. If the predictions hold, the actual errors divided by the predicted ones (the standardized errors) have a root mean square of 1, and 95% of them are within 2. The table gives these for each design and field, with the root mean square of the predicted and actual errors and the mean error." + ] + }, + { + "cell_type": "code", + "execution_count": 7, + "id": "ede859c6", + "metadata": { + "execution": { + "iopub.execute_input": "2026-11-13T23:01:52.913840Z", + "iopub.status.busy": "2026-11-13T23:01:52.913840Z", + "iopub.status.idle": "2026-11-13T23:01:54.228077Z", + "shell.execute_reply": "2026-11-13T23:01:54.228077Z" + } + }, + "outputs": [ + { + "data": { + "text/html": [ + "
\n", + "\n", + "\n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + "
pointspredicted RMS erroractual RMS errorRMS standardized errorwithin 2 predicted (%)mean error
fielddesign
stationaryone sun-synchronous756.00.0760.0771.01594.5770.003
train of three756.00.0750.0761.01594.5770.004
three sun-synchronous756.00.0290.0280.96896.4290.001
precessing756.00.1620.1631.01395.767-0.002
daily cycleone sun-synchronous756.00.0760.1151.51581.2170.057
train of three756.00.0750.1211.61677.6460.069
three sun-synchronous756.00.0290.0301.03394.8410.001
precessing756.00.1620.1931.28287.566-0.000
\n", + "
" + ], + "text/plain": [ + " points predicted RMS error \\\n", + "field design \n", + "stationary one sun-synchronous 756.0 0.076 \n", + " train of three 756.0 0.075 \n", + " three sun-synchronous 756.0 0.029 \n", + " precessing 756.0 0.162 \n", + "daily cycle one sun-synchronous 756.0 0.076 \n", + " train of three 756.0 0.075 \n", + " three sun-synchronous 756.0 0.029 \n", + " precessing 756.0 0.162 \n", + "\n", + " actual RMS error RMS standardized error \\\n", + "field design \n", + "stationary one sun-synchronous 0.077 1.015 \n", + " train of three 0.076 1.015 \n", + " three sun-synchronous 0.028 0.968 \n", + " precessing 0.163 1.013 \n", + "daily cycle one sun-synchronous 0.115 1.515 \n", + " train of three 0.121 1.616 \n", + " three sun-synchronous 0.030 1.033 \n", + " precessing 0.193 1.282 \n", + "\n", + " within 2 predicted (%) mean error \n", + "field design \n", + "stationary one sun-synchronous 94.577 0.003 \n", + " train of three 94.577 0.004 \n", + " three sun-synchronous 96.429 0.001 \n", + " precessing 95.767 -0.002 \n", + "daily cycle one sun-synchronous 81.217 0.057 \n", + " train of three 77.646 0.069 \n", + " three sun-synchronous 94.841 0.001 \n", + " precessing 87.566 -0.000 " + ] + }, + "execution_count": 7, + "metadata": {}, + "output_type": "execute_result" + } + ], + "source": [ + "from tatc.analysis import compare_sampled_means\n", + "\n", + "\n", + "def compare(field, name):\n", + " \"\"\"The actual and predicted errors of the monthly means of the points a design observes.\"\"\"\n", + " sampled = sample_field(observations[name], field)\n", + " actual = compare_sampled_means(\n", + " sampled, field, START, END, targets=points\n", + " ).set_index(\"target_hash\")\n", + " predicted = estimate_sampling_error(\n", + " observations[name], START, END, DECORRELATION_TIME, 1.0, targets=points\n", + " )\n", + " merged = actual.join(predicted.set_index(\"target_hash\")[[\"sampling_error\"]])\n", + " merged = merged[merged.samples > 0]\n", + " merged[\"standardized\"] = merged.error / merged.sampling_error\n", + " return merged\n", + "\n", + "\n", + "compared = {\n", + " (field, name): compare(FIELDS[field], name) for field in FIELDS for name in DESIGNS\n", + "}\n", + "results = pd.DataFrame(\n", + " {\n", + " key: {\n", + " \"points\": len(m),\n", + " \"predicted RMS error\": np.sqrt((m.sampling_error**2).mean()),\n", + " \"actual RMS error\": np.sqrt((m.error**2).mean()),\n", + " \"RMS standardized error\": np.sqrt((m.standardized**2).mean()),\n", + " \"within 2 predicted (%)\": 100 * (m.standardized.abs() <= 2).mean(),\n", + " \"mean error\": m.error.mean(),\n", + " }\n", + " for key, m in compared.items()\n", + " }\n", + ").T\n", + "results.index.names = [\"field\", \"design\"]\n", + "results.round(3)" + ] + }, + { + "cell_type": "markdown", + "id": "42f14f91", + "metadata": {}, + "source": [ + "When the field follows the model, the predictions hold for every design: the root mean square of the standardized errors is 0.97 to 1.02, 95 to 96% of the errors are within 2 predicted standard deviations, and the mean errors are near zero. This includes the train, whose samples repeat each other, and the precessing satellite, whose samples are few and irregular: the estimate accounts for the times of the samples, whatever their pattern.\n", + "\n", + "The daily cycle does not change the predictions, which model a stationary field, but it changes the errors of the designs that sample few local times. The sun-synchronous satellite's monthly means are too high by 0.057 on average, as its local times of sampling suggest, and its errors are 1.5 times those predicted. The train's are 1.6 times those predicted. The precessing satellite's means are not biased on average, but each point is sampled at different local times, and its errors are 1.3 times those predicted. The three sun-synchronous satellites sample every local time, and their predictions still hold (1.03).\n", + "\n", + "The predicted and actual errors of each design, for the stationary field (filled) and with the daily cycle (hollow):" + ] + }, + { + "cell_type": "code", + "execution_count": 8, + "id": "cf5e7dd0", + "metadata": { + "execution": { + "iopub.execute_input": "2026-11-13T23:01:54.228077Z", + "iopub.status.busy": "2026-11-13T23:01:54.228077Z", + "iopub.status.idle": "2026-11-13T23:01:54.344223Z", + "shell.execute_reply": "2026-11-13T23:01:54.344223Z" + } + }, + "outputs": [ + { + "data": { + "image/png": "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", + "text/plain": [ + "
" + ] + }, + "metadata": {}, + "output_type": "display_data" + } + ], + "source": [ + "MARKERS = dict(zip(DESIGNS, [\"o\", \"s\", \"^\", \"D\"]))\n", + "fig, ax = plt.subplots(figsize=(6, 5.5))\n", + "limits = (0.02, 0.4)\n", + "ax.plot(limits, limits, color=GRAY, lw=1, ls=\"--\", label=\"actual = predicted\")\n", + "for name in DESIGNS:\n", + " for field, filled in ((\"stationary\", True), (\"daily cycle\", False)):\n", + " row = results.loc[(field, name)]\n", + " ax.plot(\n", + " row[\"predicted RMS error\"],\n", + " row[\"actual RMS error\"],\n", + " marker=MARKERS[name],\n", + " ms=9,\n", + " ls=\"none\",\n", + " color=COLORS[name],\n", + " markerfacecolor=COLORS[name] if filled else \"white\",\n", + " markeredgewidth=2,\n", + " )\n", + "# direct labels at the stationary points (one sun-synchronous satellite and the train coincide)\n", + "LABELS = {\n", + " \"one sun-synchronous\": \"one sun-synchronous\\nand train of three\",\n", + " \"three sun-synchronous\": \"three sun-synchronous\",\n", + " \"precessing\": \"precessing\",\n", + "}\n", + "for name, label in LABELS.items():\n", + " ax.annotate(\n", + " label,\n", + " (\n", + " results.loc[(\"stationary\", name), \"predicted RMS error\"],\n", + " results.loc[(\"stationary\", name), \"actual RMS error\"],\n", + " ),\n", + " xytext=(10, -6),\n", + " textcoords=\"offset points\",\n", + " va=\"top\",\n", + " color=INK,\n", + " fontsize=9,\n", + " )\n", + "# legend: the designs by marker and color, and the fields by fill\n", + "handles = [\n", + " plt.Line2D(\n", + " [], [], marker=MARKERS[name], ls=\"none\", ms=8, color=COLORS[name], label=name\n", + " )\n", + " for name in DESIGNS\n", + "]\n", + "handles += [\n", + " plt.Line2D(\n", + " [], [], marker=\"o\", ls=\"none\", ms=8, color=GRAY, label=\"stationary field\"\n", + " ),\n", + " plt.Line2D(\n", + " [],\n", + " [],\n", + " marker=\"o\",\n", + " ls=\"none\",\n", + " ms=8,\n", + " color=GRAY,\n", + " markerfacecolor=\"white\",\n", + " markeredgewidth=2,\n", + " label=\"with a daily cycle\",\n", + " ),\n", + " plt.Line2D([], [], color=GRAY, ls=\"--\", label=\"actual = predicted\"),\n", + "]\n", + "ax.legend(handles=handles, frameon=False, fontsize=8, loc=\"upper left\")\n", + "ax.set(\n", + " xscale=\"log\",\n", + " yscale=\"log\",\n", + " xlim=limits,\n", + " ylim=limits,\n", + " xlabel=\"Predicted RMS error of the monthly means\",\n", + " ylabel=\"Actual RMS error of the monthly means\",\n", + ")\n", + "ticks = [0.02, 0.05, 0.1, 0.2, 0.4]\n", + "ax.set_xticks(ticks, [str(t) for t in ticks])\n", + "ax.set_yticks(ticks, [str(t) for t in ticks])\n", + "ax.minorticks_off()\n", + "ax.grid(True, lw=0.8)\n", + "plt.show()" + ] + }, + { + "cell_type": "markdown", + "id": "992afab0", + "metadata": {}, + "source": [ + "## Summary\n", + "\n", + "* **Spread, not count.** The error of a sampled mean depends on how the samples spread in time relative to the field's decorrelation time. Samples minutes apart add almost nothing (the train), and samples spread within the decorrelation time reduce the error faster than independent samples would (the three sun-synchronous satellites). Rank designs by `estimate_sampling_error` rather than by their samples or mean revisit.\n", + "* **Revisits explain it.** The mean revisit hides clusters of samples; the quantiles of the revisits and the longest gap (`compute_revisit_statistics`) show them.\n", + "* **Calibrated for its model.** The estimate is exact for a stationary field with an exponential correlation. When a field follows it, the predicted errors hold for any pattern of samples.\n", + "* **Daily cycles.** A field with a daily cycle sampled at few local times has biased means and errors larger than predicted. Check the local times of the samples (`compute_local_time_coverage`) for such fields.\n", + "\n", + "The predictions need the field's standard deviation and decorrelation time, which may differ between targets (mappings by `target_hash`, such as a field that decorrelates faster over land). A study takes them from climatology or another period. The validation notebook `ValidateSamplingErrorIMERG` tests this with real precipitation: the statistics of one month predict the errors of the next, and the daily cycle makes the errors of one sun-synchronous satellite up to 25% larger than predicted. The trade space examples (from `SearchTradeSpace`) use the relative error in an objective: the share of points whose daily means a design estimates within half the field's standard deviation." + ] + } + ], + "metadata": { + "kernelspec": { + "display_name": "Python 3", + "language": "python", + "name": "python3" + }, + "language_info": { + "codemirror_mode": { + "name": "ipython", + "version": 3 + }, + "file_extension": ".py", + "mimetype": "text/x-python", + "name": "python", + "nbconvert_exporter": "python", + "pygments_lexer": "ipython3", + "version": "3.10.16" + } + }, + "nbformat": 4, + "nbformat_minor": 5 +} diff --git a/docs/examples/CollectPlatformTrack.ipynb b/docs/examples/CollectPlatformTrack.ipynb index 8c7e45a..48e05a0 100644 --- a/docs/examples/CollectPlatformTrack.ipynb +++ b/docs/examples/CollectPlatformTrack.ipynb @@ -63,7 +63,7 @@ "id": "24c69568", "metadata": {}, "source": [ - "The `collect_platform_track` method computes each instrument's footprint. By default it projects onto the platform's ground elevation; pass `elevation` to use another target elevation, either below the instruments (looking down) or above them (looking up, see [Looking Up](#Looking-Up)). As in `collect_ground_track`, `instrument_index` selects one instrument of each platform (the first by default), or `None` selects all of them. Results are formatted as a flat GeoDataFrame, similar to a regular pandas DataFrame with a geospatial column labeled `geometry`. Other columns:\n", + "The `collect_platform_track` method computes each instrument's footprint. By default it projects onto the platform's ground elevation; pass `elevation` to use another target elevation, either below the instruments (looking down) or above them (looking up, see the section Looking Up below). As in `collect_ground_track`, `instrument_index` selects one instrument of each platform (the first by default), or `None` selects all of them. Results are formatted as a flat GeoDataFrame, similar to a regular pandas DataFrame with a geospatial column labeled `geometry`. Other columns:\n", " * `platform`: platform name\n", " * `instrument`: instrument name\n", " * `elevation`: target elevation (m) onto which the footprint is projected" diff --git a/docs/examples/index.rst b/docs/examples/index.rst index bc8a476..0ad624b 100644 --- a/docs/examples/index.rst +++ b/docs/examples/index.rst @@ -20,11 +20,14 @@ The following provide examples of TAT-C use in a Jupyter notebook environment. CollectRO.ipynb CollectLimb.ipynb CollectSpace.ipynb - RunOSSEMonsoon.ipynb - RunOSSEHurricane.ipynb + AssessSamplingSufficiency.ipynb + osse/index + tradespace/index Note that running the above examples in a local Python environment requires additional dependencies which can be installed via:: pip install tatc[examples] -using the pip package manager. +using the pip package manager. The AssessSamplingSufficiency example also requires xarray (``pip install xarray``) for its nature run. The trade space tutorial also requires:: + + pip install tatc[tradespace] diff --git a/docs/examples/RunOSSEHurricane.ipynb b/docs/examples/osse/RunOSSEHurricane.ipynb similarity index 99% rename from docs/examples/RunOSSEHurricane.ipynb rename to docs/examples/osse/RunOSSEHurricane.ipynb index 5b9c1b4..3c6df58 100644 --- a/docs/examples/RunOSSEHurricane.ipynb +++ b/docs/examples/osse/RunOSSEHurricane.ipynb @@ -9,7 +9,7 @@ "\n", "An observing system simulation experiment (OSSE) evaluates how well an observing system, real or planned, would observe a phenomenon, by sampling a high-resolution model simulation (the *nature run*) as the system would. This example is an OSSE of a **hurricane** in the 7-km [GEOS-5 Nature Run (G5NR)](https://gmao.gsfc.nasa.gov/global_mesoscale/7km-G5NR/). In late August of the Nature Run's second year, a simulated hurricane crosses the North Atlantic from near the Cape Verde Islands (about 15 N, 27 W on 20 August) to Nova Scotia (30 August). This example covers two days, 25 and 26 August, when the storm passes north of Puerto Rico and Hispaniola and begins to recurve to the north.\n", "\n", - "The observing systems are the same as in the [monsoon OSSE](RunOSSEMonsoon.ipynb): the atmospheric sounders on the current NOAA/NASA polar-orbiting satellites ([ATMS](../validation/ValidateImagerATMS.ipynb) and [CrIS](../validation/ValidateImagerCrIS.ipynb)) and two notional future sounders with finer resolution. Unlike the monsoon, whose features are scattered convective cells over land with a strong diurnal cycle, the features here are organized around one large storm over the ocean. Two kinds of features are defined:\n", + "The observing systems are the same as in the [monsoon OSSE](RunOSSEMonsoon.ipynb): the atmospheric sounders on the current NOAA/NASA polar-orbiting satellites ([ATMS](../../validation/ValidateImagerATMS.ipynb) and [CrIS](../../validation/ValidateImagerCrIS.ipynb)) and two notional future sounders with finer resolution. Unlike the monsoon, whose features are scattered convective cells over land with a strong diurnal cycle, the features here are organized around one large storm over the ocean. Two kinds of features are defined:\n", "\n", "* **cold cloud tops**, as in the monsoon OSSE, which outline the storm's central dense overcast and the convective cells of its rainbands; and\n", "* **heavy precipitation**, which outlines its eyewall and rainbands, where microwave sounders sense the rain and ice beneath the cloud tops.\n", @@ -69,7 +69,7 @@ "import shapely\n", "from shapely.geometry import box\n", "\n", - "DATA_DIR = Path(\"data\") / \"osse\"\n", + "DATA_DIR = Path(\"data\")\n", "DATA_DIR.mkdir(parents=True, exist_ok=True)\n", "\n", "# study region: a box around the storm's track over the two days\n", @@ -1334,7 +1334,7 @@ "source": [ "## Define the Sensors\n", "\n", - "The platforms, swaths, and sensors are those of the monsoon OSSE (see there for their basis): ATMS and CrIS on Suomi NPP, NOAA-20, and NOAA-21, with the swaths of TAT-C's [instrument catalog](../validation/catalog.rst), tested against NOAA-20 data, and the notional future microwave (MW) and infrared (IR) sounders with finer resolution, sharing the ATMS and CrIS swaths. Here the element sets are those of 25 August 2026." + "The platforms, swaths, and sensors are those of the monsoon OSSE (see there for their basis): ATMS and CrIS on Suomi NPP, NOAA-20, and NOAA-21, with the swaths of TAT-C's [instrument catalog](../../validation/catalog.rst), tested against NOAA-20 data, and the notional future microwave (MW) and infrared (IR) sounders with finer resolution, sharing the ATMS and CrIS swaths. Here the element sets are those of 25 August 2026." ] }, { diff --git a/docs/examples/RunOSSEMonsoon.ipynb b/docs/examples/osse/RunOSSEMonsoon.ipynb similarity index 80% rename from docs/examples/RunOSSEMonsoon.ipynb rename to docs/examples/osse/RunOSSEMonsoon.ipynb index ab3d3f9..eebc547 100644 --- a/docs/examples/RunOSSEMonsoon.ipynb +++ b/docs/examples/osse/RunOSSEMonsoon.ipynb @@ -7,7 +7,7 @@ "source": [ "# OSSE: North American Monsoon Convection\n", "\n", - "An observing system simulation experiment (OSSE) evaluates how well an observing system, real or planned, would observe a phenomenon, by sampling a high-resolution model simulation (the *nature run*) as the system would. This example is an OSSE of **convection during the North American Monsoon**. The nature run is the 7-km [GEOS-5 Nature Run (G5NR)](https://gmao.gsfc.nasa.gov/global_mesoscale/7km-G5NR/). The *features* of interest are patches of very cold cloud tops over the American Southwest. The observing systems are the atmospheric sounders on the current NOAA/NASA polar-orbiting satellites ([ATMS](../validation/ValidateImagerATMS.ipynb) and [CrIS](../validation/ValidateImagerCrIS.ipynb)) and two notional future sounders with finer resolution.\n", + "An observing system simulation experiment (OSSE) evaluates how well an observing system, real or planned, would observe a phenomenon, by sampling a high-resolution model simulation (the *nature run*) as the system would. This example is an OSSE of **convection during the North American Monsoon**. The nature run is the 7-km [GEOS-5 Nature Run (G5NR)](https://gmao.gsfc.nasa.gov/global_mesoscale/7km-G5NR/). The *features* of interest are patches of very cold cloud tops over the American Southwest. The observing systems are the atmospheric sounders on the current NOAA/NASA polar-orbiting satellites ([ATMS](../../validation/ValidateImagerATMS.ipynb) and [CrIS](../../validation/ValidateImagerCrIS.ipynb)) and two notional future sounders with finer resolution.\n", "\n", "The experiment asks two questions about each feature:\n", "\n", @@ -63,7 +63,7 @@ "import shapely\n", "from shapely.geometry import box\n", "\n", - "DATA_DIR = Path(\"data\") / \"osse\"\n", + "DATA_DIR = Path(\"data\")\n", "DATA_DIR.mkdir(parents=True, exist_ok=True)\n", "\n", "# study region: the American Southwest, the core of the North American Monsoon\n", @@ -1179,7 +1179,7 @@ "\n", "**Platforms.** The current constellation of sounders is Suomi NPP, NOAA-20, and NOAA-21, three satellites in a sun-synchronous orbit with an ascending node of about 13:30 local time. Each carries both the Advanced Technology Microwave Sounder (ATMS) and the Cross-track Infrared Sounder (CrIS).\n", "\n", - "**Swaths.** The swaths of ATMS and CrIS come from TAT-C's [instrument catalog](../validation/catalog.rst) (`tatc.catalog`), whose swath configurations of NOAA-20 (`swath_noaa_20` of ATMS and `swath` of CrIS) were tested against its data: each is a rectangular `PointedInstrument` spanning the scan positions measured in the validation notebooks ([ATMS](../validation/ValidateImagerATMS.ipynb) and [CrIS](../validation/ValidateImagerCrIS.ipynb)), with CrIS's scan plane tilted forward as measured, on a satellite whose attitude scans perpendicular to the inertial velocity (`VelocityFrame.INERTIAL`) rather than to the ground track. The catalog tailors the along-track field of view to the 30 s time step, so that consecutive footprints tile the swath. The configurations of NOAA-20 are used for all three satellites, so NOAA-21 and Suomi NPP are assumed identical to it.\n", + "**Swaths.** The swaths of ATMS and CrIS come from TAT-C's [instrument catalog](../../validation/catalog.rst) (`tatc.catalog`), whose swath configurations of NOAA-20 (`swath_noaa_20` of ATMS and `swath` of CrIS) were tested against its data: each is a rectangular `PointedInstrument` spanning the scan positions measured in the validation notebooks ([ATMS](../../validation/ValidateImagerATMS.ipynb) and [CrIS](../../validation/ValidateImagerCrIS.ipynb)), with CrIS's scan plane tilted forward as measured, on a satellite whose attitude scans perpendicular to the inertial velocity (`VelocityFrame.INERTIAL`) rather than to the ground track. The catalog tailors the along-track field of view to the 30 s time step, so that consecutive footprints tile the swath. The configurations of NOAA-20 are used for all three satellites, so NOAA-21 and Suomi NPP are assumed identical to it.\n", "\n", "**Resolution.** Each sensor has a horizontal resolution (the diameter of its footprint at nadir) and a sample spacing (the distance between the centers of neighboring footprints at nadir). A sensor cannot resolve detail finer than either its footprint or its sample spacing, so its *resolution element* is the larger of the two. ATMS oversamples (its 2.2 degree beams overlap at a 1.11 degree spacing), so its footprint limits it. CrIS undersamples slightly (its 0.963 degree views leave gaps at a 1.09 degree pitch), so its sample spacing limits it. The future sensors are assumed to sample in proportion to their footprints, in the same ratio as their heritage counterparts, so a future infrared sounder has as many more views per scan as its finer footprint requires.\n", "\n", @@ -2413,9 +2413,13 @@ "\n", "An OSSE is most useful for comparing designs that do not exist yet. The analysis above finds that the current sounders observe only 12 to 14% of the features, because all three satellites share one orbit plane, and that finer resolution helps only with the features that are observed. This section trades the two: how many satellites, in how many orbit planes, carrying heritage or future sensors.\n", "\n", - "Each design places satellites in sun-synchronous orbits at 830 km (the altitude at which the nominal resolutions of the sensors apply), in planes whose ascending equator crossing times are spread evenly over 12 hours from 13:30, so that `P` planes observe at `2P` evenly spaced local times. The satellites of a plane are evenly spaced in it, and each carries both swaths (ATMS and CrIS). Two strategies are compared for 1 to 6 satellites: all in one plane, like the current constellation, and one per plane. A design of 6 satellites in 2 planes (3 per plane) shows how much of the benefit of separate planes a single additional plane gives. Which passes cross the study region depends on the phase of the satellites in their planes, so each design is evaluated for `N_DRAWS` random phases and the results averaged.\n", + "The designs are declared as a design space (`tatc.tradespace.DesignSpace`): the number of orbit planes `P` (a repetition of planes, `Repeat`) and the number of satellites in each plane, for at most six satellites, which gives 14 designs. Each design places satellites in sun-synchronous orbits at 830 km (the altitude at which the nominal resolutions of the sensors apply), in planes whose ascending equator crossing times are spread evenly over 12 hours from 13:30 (a value `Derived` from the index of the plane), so that `P` planes observe at `2P` evenly spaced local times. The satellites of a plane are evenly spaced in it, and each carries both swaths (ATMS and CrIS). The designs include the two strategies of all satellites in one plane, like the current constellation, and one satellite per plane, and designs in between, such as 6 satellites in 2 planes (3 per plane), which shows how much of the benefit of separate planes a single additional plane gives.\n", "\n", - "Two days are too few to rank designs, so the trade uses two weeks of the Nature Run (`TRADE_DURATION`), downloaded once (about 120 MB, a few minutes). Evaluating the designs takes about three minutes." + "Which passes cross the study region depends on the phase of the satellites in their planes, which is not a design choice but an uncertain parameter (`Uncertain`). A trade study (`tatc.tradespace.Study`) builds and evaluates each design in `N_DRAWS` replicates, each with random phases, and the results are averaged. The replicates use common random numbers: the phase of a plane (the first plane, the second plane, and so on) is the same in the same replicate of every design, so that differences between designs are not differences between their draws.\n", + "\n", + "Designs share satellites: in the same replicate, the first satellite of the first plane is the same in every design, and so are others (such as the satellites of the planes of designs with the same number of planes). A cache of the looks of each satellite (`tatc.tradespace.SatelliteCache`), keyed by its orbit and instruments rather than its name, computes them once for the designs of a replicate: 32 satellites rather than 57. The replicates are evaluated in parallel, each by its own worker process (`n_jobs`).\n", + "\n", + "Two days are too few to rank designs, so the trade uses two weeks of the Nature Run (`TRADE_DURATION`), downloaded once (about 120 MB, a few minutes). Evaluating the designs takes about a minute with six processors." ] }, { @@ -2431,27 +2435,11 @@ } }, "outputs": [ - { - "name": "stderr", - "output_type": "stream", - "text": [ - "c:\\Users\\paulg\\github\\tatc\\.venv\\Lib\\site-packages\\xarray\\coding\\times.py:215: SerializationWarning: Ambiguous reference date string: 1-1-1 00:00:0.0. The first value is assumed to be the year hence will be padded with zeros to remove the ambiguity (the padded reference date string is: 0001-1-1 00:00:0.0). To remove this message, remove the ambiguity by padding your reference date strings with zeros.\n", - " ref_date = _ensure_padded_year(ref_date)\n" - ] - }, - { - "name": "stderr", - "output_type": "stream", - "text": [ - "c:\\Users\\paulg\\github\\tatc\\.venv\\Lib\\site-packages\\xarray\\coding\\times.py:215: SerializationWarning: Ambiguous reference date string: 1-1-1 00:00:0.0. The first value is assumed to be the year hence will be padded with zeros to remove the ambiguity (the padded reference date string is: 0001-1-1 00:00:0.0). To remove this message, remove the ambiguity by padding your reference date strings with zeros.\n", - " ref_date = _ensure_padded_year(ref_date)\n" - ] - }, { "name": "stdout", "output_type": "stream", "text": [ - "1590 features in 14 days\n" + "14 designs, 1590 features in 14 days\n" ] }, { @@ -2498,50 +2486,50 @@ " \n", " 1\n", " 1 plane(s) x 1\n", - " 4.2\n", - " 3.5\n", - " 0.5\n", - " 2.2\n", - " 3.5\n", + " 4.4\n", " 3.4\n", + " 0.4\n", + " 1.9\n", + " 3.2\n", + " 3.3\n", " \n", " \n", " 2\n", " 1 plane(s) x 2\n", - " 8.4\n", - " 6.9\n", + " 8.5\n", + " 6.8\n", " 0.8\n", - " 4.2\n", - " 6.9\n", - " 6.9\n", + " 4.1\n", + " 6.8\n", + " 6.8\n", " \n", " \n", " 2 plane(s) x 1\n", - " 10.0\n", - " 8.0\n", - " 1.1\n", - " 4.5\n", - " 7.7\n", + " 10.1\n", " 7.9\n", + " 1.1\n", + " 4.3\n", + " 7.6\n", + " 7.8\n", " \n", " \n", " 3\n", " 1 plane(s) x 3\n", - " 12.6\n", - " 10.5\n", + " 13.0\n", + " 10.4\n", " 1.2\n", - " 6.1\n", + " 6.2\n", + " 10.1\n", " 10.3\n", - " 10.4\n", " \n", " \n", " 3 plane(s) x 1\n", - " 14.0\n", + " 14.2\n", " 11.3\n", " 1.6\n", - " 6.8\n", - " 11.3\n", - " 11.2\n", + " 6.6\n", + " 10.9\n", + " 11.1\n", " \n", " \n", " current (3 in the 13:30 plane)\n", @@ -2553,70 +2541,88 @@ " 9.6\n", " \n", " \n", - " 4\n", + " 4\n", " 1 plane(s) x 4\n", - " 14.8\n", - " 12.3\n", + " 14.7\n", + " 12.4\n", " 1.5\n", " 7.4\n", " 12.1\n", - " 12.1\n", + " 12.2\n", + " \n", + " \n", + " 2 plane(s) x 2\n", + " 19.6\n", + " 15.7\n", + " 2.4\n", + " 9.2\n", + " 15.4\n", + " 15.6\n", " \n", " \n", " 4 plane(s) x 1\n", - " 19.0\n", + " 19.4\n", " 15.6\n", - " 2.1\n", - " 8.9\n", + " 2.2\n", + " 9.0\n", " 15.2\n", - " 15.5\n", + " 15.4\n", " \n", " \n", " 5\n", " 1 plane(s) x 5\n", " 15.5\n", - " 13.3\n", - " 1.5\n", - " 7.9\n", - " 12.9\n", - " 13.1\n", + " 13.0\n", + " 1.7\n", + " 8.1\n", + " 12.7\n", + " 12.8\n", " \n", " \n", " 5 plane(s) x 1\n", - " 23.8\n", + " 24.4\n", + " 19.6\n", + " 2.6\n", + " 11.5\n", + " 19.4\n", " 19.4\n", - " 2.7\n", - " 11.4\n", - " 19.1\n", - " 19.2\n", " \n", " \n", - " 6\n", + " 6\n", " 1 plane(s) x 6\n", - " 15.5\n", - " 13.3\n", + " 15.8\n", + " 13.1\n", " 1.8\n", - " 8.3\n", - " 13.2\n", - " 13.2\n", + " 8.4\n", + " 13.1\n", + " 13.0\n", " \n", " \n", " 2 plane(s) x 3\n", - " 29.8\n", - " 24.0\n", - " 3.4\n", - " 14.2\n", - " 23.6\n", + " 29.7\n", + " 23.9\n", + " 3.6\n", + " 14.3\n", + " 23.3\n", " 23.7\n", " \n", " \n", + " 3 plane(s) x 2\n", + " 28.1\n", + " 22.7\n", + " 3.5\n", + " 13.8\n", + " 22.4\n", + " 22.5\n", + " \n", + " \n", " 6 plane(s) x 1\n", - " 29.3\n", + " 29.2\n", " 23.9\n", - " 3.6\n", - " 14.5\n", - " 23.3\n", - " 23.7\n", + " 3.5\n", + " 14.2\n", + " 23.0\n", + " 23.6\n", " \n", " \n", "\n", @@ -2625,83 +2631,93 @@ "text/plain": [ "sensor observed, ATMS swath \\\n", "satellites design \n", - "1 1 plane(s) x 1 4.2 \n", - "2 1 plane(s) x 2 8.4 \n", - " 2 plane(s) x 1 10.0 \n", - "3 1 plane(s) x 3 12.6 \n", - " 3 plane(s) x 1 14.0 \n", + "1 1 plane(s) x 1 4.4 \n", + "2 1 plane(s) x 2 8.5 \n", + " 2 plane(s) x 1 10.1 \n", + "3 1 plane(s) x 3 13.0 \n", + " 3 plane(s) x 1 14.2 \n", " current (3 in the 13:30 plane) 11.6 \n", - "4 1 plane(s) x 4 14.8 \n", - " 4 plane(s) x 1 19.0 \n", + "4 1 plane(s) x 4 14.7 \n", + " 2 plane(s) x 2 19.6 \n", + " 4 plane(s) x 1 19.4 \n", "5 1 plane(s) x 5 15.5 \n", - " 5 plane(s) x 1 23.8 \n", - "6 1 plane(s) x 6 15.5 \n", - " 2 plane(s) x 3 29.8 \n", - " 6 plane(s) x 1 29.3 \n", + " 5 plane(s) x 1 24.4 \n", + "6 1 plane(s) x 6 15.8 \n", + " 2 plane(s) x 3 29.7 \n", + " 3 plane(s) x 2 28.1 \n", + " 6 plane(s) x 1 29.2 \n", "\n", "sensor observed, CrIS swath \\\n", "satellites design \n", - "1 1 plane(s) x 1 3.5 \n", - "2 1 plane(s) x 2 6.9 \n", - " 2 plane(s) x 1 8.0 \n", - "3 1 plane(s) x 3 10.5 \n", + "1 1 plane(s) x 1 3.4 \n", + "2 1 plane(s) x 2 6.8 \n", + " 2 plane(s) x 1 7.9 \n", + "3 1 plane(s) x 3 10.4 \n", " 3 plane(s) x 1 11.3 \n", " current (3 in the 13:30 plane) 9.7 \n", - "4 1 plane(s) x 4 12.3 \n", + "4 1 plane(s) x 4 12.4 \n", + " 2 plane(s) x 2 15.7 \n", " 4 plane(s) x 1 15.6 \n", - "5 1 plane(s) x 5 13.3 \n", - " 5 plane(s) x 1 19.4 \n", - "6 1 plane(s) x 6 13.3 \n", - " 2 plane(s) x 3 24.0 \n", + "5 1 plane(s) x 5 13.0 \n", + " 5 plane(s) x 1 19.6 \n", + "6 1 plane(s) x 6 13.1 \n", + " 2 plane(s) x 3 23.9 \n", + " 3 plane(s) x 2 22.7 \n", " 6 plane(s) x 1 23.9 \n", "\n", "sensor resolved, ATMS resolved, CrIS \\\n", "satellites design \n", - "1 1 plane(s) x 1 0.5 2.2 \n", - "2 1 plane(s) x 2 0.8 4.2 \n", - " 2 plane(s) x 1 1.1 4.5 \n", - "3 1 plane(s) x 3 1.2 6.1 \n", - " 3 plane(s) x 1 1.6 6.8 \n", + "1 1 plane(s) x 1 0.4 1.9 \n", + "2 1 plane(s) x 2 0.8 4.1 \n", + " 2 plane(s) x 1 1.1 4.3 \n", + "3 1 plane(s) x 3 1.2 6.2 \n", + " 3 plane(s) x 1 1.6 6.6 \n", " current (3 in the 13:30 plane) 1.0 5.3 \n", "4 1 plane(s) x 4 1.5 7.4 \n", - " 4 plane(s) x 1 2.1 8.9 \n", - "5 1 plane(s) x 5 1.5 7.9 \n", - " 5 plane(s) x 1 2.7 11.4 \n", - "6 1 plane(s) x 6 1.8 8.3 \n", - " 2 plane(s) x 3 3.4 14.2 \n", - " 6 plane(s) x 1 3.6 14.5 \n", + " 2 plane(s) x 2 2.4 9.2 \n", + " 4 plane(s) x 1 2.2 9.0 \n", + "5 1 plane(s) x 5 1.7 8.1 \n", + " 5 plane(s) x 1 2.6 11.5 \n", + "6 1 plane(s) x 6 1.8 8.4 \n", + " 2 plane(s) x 3 3.6 14.3 \n", + " 3 plane(s) x 2 3.5 13.8 \n", + " 6 plane(s) x 1 3.5 14.2 \n", "\n", "sensor resolved, Future MW \\\n", "satellites design \n", - "1 1 plane(s) x 1 3.5 \n", - "2 1 plane(s) x 2 6.9 \n", - " 2 plane(s) x 1 7.7 \n", - "3 1 plane(s) x 3 10.3 \n", - " 3 plane(s) x 1 11.3 \n", + "1 1 plane(s) x 1 3.2 \n", + "2 1 plane(s) x 2 6.8 \n", + " 2 plane(s) x 1 7.6 \n", + "3 1 plane(s) x 3 10.1 \n", + " 3 plane(s) x 1 10.9 \n", " current (3 in the 13:30 plane) 9.6 \n", "4 1 plane(s) x 4 12.1 \n", + " 2 plane(s) x 2 15.4 \n", " 4 plane(s) x 1 15.2 \n", - "5 1 plane(s) x 5 12.9 \n", - " 5 plane(s) x 1 19.1 \n", - "6 1 plane(s) x 6 13.2 \n", - " 2 plane(s) x 3 23.6 \n", - " 6 plane(s) x 1 23.3 \n", + "5 1 plane(s) x 5 12.7 \n", + " 5 plane(s) x 1 19.4 \n", + "6 1 plane(s) x 6 13.1 \n", + " 2 plane(s) x 3 23.3 \n", + " 3 plane(s) x 2 22.4 \n", + " 6 plane(s) x 1 23.0 \n", "\n", "sensor resolved, Future IR \n", "satellites design \n", - "1 1 plane(s) x 1 3.4 \n", - "2 1 plane(s) x 2 6.9 \n", - " 2 plane(s) x 1 7.9 \n", - "3 1 plane(s) x 3 10.4 \n", - " 3 plane(s) x 1 11.2 \n", + "1 1 plane(s) x 1 3.3 \n", + "2 1 plane(s) x 2 6.8 \n", + " 2 plane(s) x 1 7.8 \n", + "3 1 plane(s) x 3 10.3 \n", + " 3 plane(s) x 1 11.1 \n", " current (3 in the 13:30 plane) 9.6 \n", - "4 1 plane(s) x 4 12.1 \n", - " 4 plane(s) x 1 15.5 \n", - "5 1 plane(s) x 5 13.1 \n", - " 5 plane(s) x 1 19.2 \n", - "6 1 plane(s) x 6 13.2 \n", + "4 1 plane(s) x 4 12.2 \n", + " 2 plane(s) x 2 15.6 \n", + " 4 plane(s) x 1 15.4 \n", + "5 1 plane(s) x 5 12.8 \n", + " 5 plane(s) x 1 19.4 \n", + "6 1 plane(s) x 6 13.0 \n", " 2 plane(s) x 3 23.7 \n", - " 6 plane(s) x 1 23.7 " + " 3 plane(s) x 2 22.5 \n", + " 6 plane(s) x 1 23.6 " ] }, "execution_count": 12, @@ -2713,38 +2729,58 @@ "from datetime import time as time_of_day\n", "\n", "from tatc.schemas import SunSynchronousOrbit\n", + "from tatc.tradespace import (\n", + " Derived,\n", + " DesignSpace,\n", + " Integer,\n", + " Repeat,\n", + " SatelliteCache,\n", + " Study,\n", + " Uncertain,\n", + ")\n", "\n", "TRADE_DURATION = timedelta(days=14)\n", - "N_DRAWS = 6 # random phases of the satellites in their planes, per design\n", - "# designs (planes, satellites per plane): all in one plane, one per plane, and 6 satellites in 2 planes\n", - "DESIGNS = [(1, n) for n in range(1, 7)] + [(n, 1) for n in range(2, 7)] + [(2, 3)]\n", + "N_DRAWS = 6 # replicates of each design: random phases of the satellites in their planes\n", + "\n", + "# the design space: P planes whose ascending equator crossing times are spread evenly over 12 hours from 13:30, each\n", + "# with the same number of satellites at a random phase, for at most 6 satellites\n", + "space = DesignSpace(\n", + " per_plane=Integer(1, 6),\n", + " planes=Repeat(\n", + " DesignSpace(\n", + " crossing=Derived(lambda d: (13.5 + 12 * d.index / d.planes.count) % 24),\n", + " phase=Uncertain.uniform(0, 360),\n", + " ),\n", + " count=Integer(1, 6),\n", + " ),\n", + " constraints=[lambda d: d.planes.count * d.per_plane <= 6],\n", + ")\n", "\n", "\n", - "def constellation(n_planes, per_plane, rng):\n", - " \"\"\"Satellites in n_planes sun-synchronous planes at 830 km, whose ascending equator crossing times are spread evenly\n", - " over 12 hours from 13:30, with per_plane satellites evenly spaced in each plane at a random phase.\n", - " \"\"\"\n", + "def build(design):\n", + " \"\"\"The satellites of a design: in sun-synchronous orbits at 830 km, evenly spaced in each plane from its phase.\"\"\"\n", " members = []\n", - " for p in range(n_planes):\n", - " hours = (13.5 + 12 * p / n_planes) % 24\n", - " crossing = time_of_day(int(hours), round(60 * (hours % 1)) % 60)\n", - " phase = rng.uniform(0, 360)\n", - " for s in range(per_plane):\n", + " for p, plane in enumerate(design.planes):\n", + " crossing = time_of_day(int(plane.crossing), round(60 * (plane.crossing % 1)) % 60)\n", + " for s in range(design.per_plane):\n", " orbit = SunSynchronousOrbit(\n", " altitude=830e3,\n", " equator_crossing_time=crossing,\n", " epoch=start,\n", - " true_anomaly=(phase + 360 * s / per_plane) % 360,\n", - " )\n", - " members.append(\n", - " sounder_satellite(f\"plane {p + 1} satellite {s + 1}\", orbit)\n", + " true_anomaly=(plane.phase + 360 * s / design.per_plane) % 360,\n", " )\n", + " members.append(sounder_satellite(f\"plane {p + 1} satellite {s + 1}\", orbit))\n", " return members\n", "\n", "\n", - "def evaluate(members, features):\n", - " \"\"\"The share (%) of the features that each sensor observes and resolves, flown on the members.\"\"\"\n", - " looks = collect_looks(members, TRADE_DURATION, features)\n", + "def evaluate(members, features, cache=None):\n", + " \"\"\"The share (%) of the features that each sensor observes and resolves, flown on the members, with their looks\n", + " from a cache of the looks of each satellite (in the order of the features and times, as for all members), if any.\n", + " \"\"\"\n", + " if cache is None:\n", + " looks = collect_looks(members, TRADE_DURATION, features)\n", + " else:\n", + " looks = cache(members).sort_values([\"feature\", \"time\"], kind=\"stable\", ignore_index=True)\n", " return (\n", " assess(looks, features, members)\n", " .groupby(\"sensor\")[[\"observed\", \"resolved\"]]\n", @@ -2754,16 +2790,21 @@ "\n", "\n", "trade_features = find_features(load_nature(TRADE_DURATION))\n", - "rng = np.random.default_rng(0)\n", - "trade = pd.concat(\n", - " [\n", - " evaluate(constellation(n_planes, per_plane, rng), trade_features).assign(\n", - " planes=n_planes, per_plane=per_plane, draw=draw\n", - " )\n", - " for n_planes, per_plane in DESIGNS\n", - " for draw in range(N_DRAWS)\n", - " ]\n", - ").reset_index()\n", + "# the looks of each satellite, cached by its orbit and instruments (not its name): designs of the same replicate\n", + "# share satellites, such as the first satellite of the first plane\n", + "trade_looks = SatelliteCache(lambda satellite: collect_looks([satellite], TRADE_DURATION, trade_features))\n", + "# common random numbers: the phase of a plane is the same in the same replicate of every design; each replicate is\n", + "# evaluated by its own worker process, whose cache its designs share\n", + "study = Study(\n", + " space,\n", + " build,\n", + " lambda members: evaluate(members, trade_features, trade_looks),\n", + " replicates=N_DRAWS,\n", + " n_jobs=N_DRAWS,\n", + " chunks_per_job=1,\n", + ")\n", + "trade = study.run()\n", + "trade[\"planes\"] = trade[\"planes.count\"]\n", "trade[\"satellites\"] = trade.planes * trade.per_plane\n", "trade[\"design\"] = (\n", " trade.planes.astype(str) + \" plane(s) x \" + trade.per_plane.astype(str)\n", @@ -2773,7 +2814,7 @@ " satellites=3, design=\"current (3 in the 13:30 plane)\"\n", ")\n", "\n", - "# features observed (by each swath) and resolved (by each sensor), % of all features, averaged over the draws\n", + "# features observed (by each swath) and resolved (by each sensor), % of all features, averaged over the replicates\n", "trade_summary = pd.concat([trade, current.reset_index()]).pivot_table(\n", " index=[\"satellites\", \"design\"], columns=\"sensor\", values=[\"observed\", \"resolved\"]\n", ")\n", @@ -2786,7 +2827,7 @@ " ],\n", " axis=1,\n", ")\n", - "print(f\"{len(trade_features)} features in {TRADE_DURATION.days} days\")\n", + "print(f\"{len(space.enumerate())} designs, {len(trade_features)} features in {TRADE_DURATION.days} days\")\n", "trade_summary.round(1)" ] }, @@ -2805,7 +2846,7 @@ "outputs": [ { "data": { - "image/png": "iVBORw0KGgoAAAANSUhEUgAABCgAAAGqCAYAAADJKHWIAAAAOnRFWHRTb2Z0d2FyZQBNYXRwbG90bGliIHZlcnNpb24zLjExLjIsIGh0dHBzOi8vbWF0cGxvdGxpYi5vcmcvgI3uAAAAAAlwSFlzAAAPYQAAD2EBqD+naQABAABJREFUeJzsnQd4VMX6xt/t2fSE3nvvHQtKEQFRRFQUFLFju/q/196vvffutTdExQIoICK9I9Kk9w6hpJdt5/+8szmb3c0m2YRAks33y7NPdk+dM2f3zMw7XzFomqZBEARBEARBEARBEAShAjFW5MkFQRAEQRAEQRAEQRCICBSCIAiCIAiCIAiCIFQ4IlAIgiAIgiAIgiAIglDhiEAhCIIgCIIgCIIgCEKFIwKFIAiCIAiCIAiCIAgVjggUgiAIgiAIgiAIgiBUOCJQCIIgCIIgCIIgCIJQ4YhAIQiCIAiCIAiCIAhChSMChSAIgiAIgiAIgiAIFY4IFEKV5p9//sHrr7+uXm+88QY+//xzLF68uELKkpaWpspx6NCh03K+H3/8EX/88UdY2y5duhQffPCBKp+maaiOLFmyBF988UVFF6PSs3LlSnz88cdFfi7PY1cEeXl56newe/fucj1uRV4bn3m//fZboeX79+/H+++/j08++SSs40yePFnVzd69eytV3Qqnj6p+D09H+bdt21bmtvRk9g2nT/D7779XumNFAunp6apOPvroI2zYsKFcjz1p0iTMnTsXVYWvvvoKmzZtquhiCBGOCBRClR90/vvf/1YNxs6dO9WAfdiwYTjjjDOQlZV1WsuSkpKiyrJr167Tcr53330X3377bYnbPfvssxg+fDj+/vtvVbby6hidOHFCdbSOHDmCqsCvv/6q6qI6sHz58rAHpcHwN/T4448X+flkzl+WY5U3OTk56ne6cePGcj1uRV0bn3OjR4+GwWDwLdu3b5/vOfjqq6/iySefLPE48+fPx5VXXqnqZvPmzZWqboXTR3ndw5N5Bp0Mp+M7uHr1anUOt9t9WvcNp0/wzTfflGqfH374IeRER1mOFalMnToVzZo1U3Xy119/Yfz48eX6rH/ttdfUfagqHD58GDfeeGNFF0OIcESgECICdsA5WP7yyy+xcOFCZTHwzjvvVHSxKo3a/X//939qJpV1ZDQay62RYkdrz5495XI8ofzgzFc4g9LTff5evXpFbMemoq7trbfeQq1atZQgocPBz5133qlE24EDB5Z4jIyMDNXpvuOOO05xaYXqQkU/g6ojl156Kc4///xS7fP222+HnOgoy7EikfXr1+Oyyy7DK6+8ooSc9957T4lv5513Hqort912m6qXadOmVXRRhAjGXNEFEITyplOnTkhKSlLuH/4cPHgQc+bMUa4YXbt2VbOLwSZ8s2bNwrFjx9CmTRv069ev0GCeZm2LFi1SA4A+ffqgS5cuIcvg8XhUwz9gwABVnuCO29GjRzF27Niwy0aWLVuGVatWqWsbOnRoifVAywbOgHA2lftRnOB16QOZ4s7pdDp9Ag/roF69eujbty8aNWqklnEf3V1i4sSJShQym81qgEPzcJqK33LLLYiKivIdkzMEycnJvgETLU6+/vprjBs3Ts3Yrl27Fs2bN/d1ilhmzlbwuOwM6OfW2bJli6oTWoT07t0bbdu2RbgzziwvrUlYH/379w8wv2WjO2HCBNjt9oD9WB+85z179iz2+GvWrFHm/jExMepaa9euHfC9YJ2z7PHx8eq66tSpE2ARtHXrVlxxxRVqRptlZJ3wOP4z5MVdP8/N4/D7zHtO2rVrhyFDhvj2Lalui4PWSrrpr81mQ9OmTVUd6vVV3PkTEhIKnas86yQUDodDuT/w+96iRQslJBTFyXznQl1bbm4upk+frty+eO5zzjlHCYWXXHIJmjRpctLXx7rjrN4999wTsJzH1o8fDhQaO3TogKuuusp3z8IhnLot6ftSmt9cWX/z/uj1zQEYn+UUcVj2QYMGqfrms4FtB7+DF1xwAaxWa6m+JyVd78ne8/I+fml+H8GU5RlUEeUvzTkvv/xyzJgxQ7lH0fKQM+dsq/g75u+Z7WBpCHdfl8uFP//8E9u3b0fNmjVVOx0bG6vWzZ49Wz1D+Pv0h9dM94AxY8ao7ytf+j5k5syZPkuSuLg4dX/OOuss33q6LLB/oLvFELa/7du3L3QsXchkPXJygt/5wYMHB7TxLAv347OEv63jx4+r+xHcByqK4o4fbh2UVJf+5WT7z+OynLfffjtMJlOhMj399NPo3Lkzrr32Wt8yfgfZPywJ/TytW7dWk2bs97ENKOq5xe9KcfVW0v3U4TG4HfuKLKd/HySc+inpGPzd0GqPfdwLL7ywxHoQhLIgFhRCxEHf09TUVNUJ8e/o8vP//vc/1aG6+OKLcc011/jW0/2hcePG6oHLzudTTz2lHvz+biIPPfSQEiTYGeLDnQP6omZMOaj/5Zdf8NhjjwUsp7Bx/fXXY926dWGXjdx1112qQzVv3jx8//33qhxsXIqDnQ527HhONnh8zwYwnHOyw8nt+eIAgrE92BjqJrsUMNiB0zsI3E73+aXYwAFPZmZmQHlYt999953vM/fndiNGjMC//vUvJVCwAWdHbuTIkaohZ+dhypQpqiPhv+8LL7yA7t27K7cN1gk7lY8++ihKguIT9+OsMzu+vG7uq7u91KhRQ93n4Bkl3m+KL+zcFmdazHKfffbZqkNKs1A27LpvKUUdfmcoyLDOGROEnV92EnV4PXfffbfqnHDgyU4zy8eXP8VdP89D9xt2QvR7qN/3cOq2JHhf9eNSjGF9cfDBzn1J5w92gyjPOgkFv/cc3NKCaMWKFXjkkUdCdqjK4zsXfG285m7duuE///mPOjefBRwEB5ufn8z1cZBMQZAd+bJCcYDPFAonpSHcui3p+xLub66sv/lguD/vCTv/fP5RkGC5OfDhd+D+++9XA2xeF3+//qb44XxPSrrek73n5Xn8cO9hKMr6DKqI8pfmnD169MBnn32m1vGZzoFlq1atVPvF92wzOJseDuHuyza2Y8eOqj/B2Xluw/aWApB+nbRwOnDgQMB+fF7SbZHCfyi3DNa5ft38nrP++Axi+00oBPA7TWFA305vt4OPxWdNy5YtVd+I7ymKsowsu7+rAi23+EznM5x9JX5HeKySKOn44dZBSXUZXE6KUTt27Ajp+splFEwo2rC/xecFRYdwrUZ5HvZtKN6xPvi84HMnlHUv+yMl1VtJ95PPKoqqFPb4m+GkEJ9h/G7rlFQ/4RyDsM3hM5DfHUE4JWiCUIX53//+x1ZFe/LJJ7XXXntNe+SRR7QmTZpovXr10o4dO6a2WbJkiWYwGLSnn37at9+uXbu0mJgY7aefflKfb775Zm3w4MEBx165cqWWkZGh3i9YsECdR9+ezJs3Ty374Ycf1OetW7eqzzwf+eqrrzSLxaIdOXLEt89vv/2mttmyZUvYZZs/f77aZ/bs2b5tJk2apJbdcMMNJdZRnTp1VN3ohHPOUHz99ddabGyslp6erj5v3LhRlWHFihUB282aNUstT0lJCVh+7rnnahMmTPB9/vvvv9V2o0eP1jwej2/5Pffco1mtVm3NmjW+Ze+9956WnJyspaamqs98/8EHH/jWc/+5c+cWWw8PP/ywOt8bb7zhW8ZzmEwmbeLEib5lrFN+f/y57LLLtLPOOqvY4991111aYmKitn37dt8ylnf16tW+9XXr1g34Ptx5553qWvTvql5Gfk90Fi5cqJatWrXKt6yk63/qqafU7yCYcOr2ueee0xo0aOBbH/w5FKNGjdIuvfTSEs8ffKzyrJNQ8FjNmjXTTpw44aunK664Qu07ffr0UtVLSXUefG233Xab1qJFCy0tLc23/dixYwud+2Suj99lu90e8PsJhr+5UPeCHD16VNX/+++/rz7zt8zz8jdcEuHWbTjfl3B+c2X5zYdCr++ZM2f6lr355ptqGe+Zzu7du9VzcsqUKaX6noRzvSdzz8vz+CdzD8v6DKos5S/qnN9++61vmdvt1jp16hTQRvFcPCe3dTqdRR4/3H25rnv37lqHDh183yEu4/d/yJAh6nNeXp5Wo0YN9YzR4TZNmzbV7r77bt+yQYMGaePHjy+yTDx+w4YN1XfWv10O1Y/wPxavpXPnztoFF1yguVwutSw7O1vr0aOHdt555/n26dOnjyrngQMHfMv++9//qu9KcYRz/HDqIJy61MvJvgz7PcXB+8V7xbqoV6+eds0112hDhw7VbDZbQB0WBc/D/oX/8+L111/XoqKitD179px0vQXfT/42WF7/Pgj7sHofLZz6KekYOjt27Ai7rRCEsiAWFEJEwFlEmupSeeeMPmdUdEWdcSloOn7ffff5tqf5M018P/30U/WZPtxUkKko63AmRTd7o4rMmRDOnulwFo0mm0UFN+LxaebP8+vQAoFqNI8Vbtl4fJoY+vuS07yOFh9lIZxz6ubjnBnjMmZI4SwDZ1fKGkCvKG666aYAs126jjBYH6/ZfxvOxnEGQr9fVO95rwn3P/fcc0s8F81Fb731Vt9nnoMzEP73kKaenI3jd4nwHD///LPyuywp1gdnJWiK7G/2r7sB8RzXXXedKrsO7wFnhujioFO3bt2AeAL8jvH6/Gf7ynr94dRtOHCGlBZC9MelaTDPz1nn0lKedVLc8RMTE9Vn7sPZ82BOxXfup59+Uufmb03fns+lUJT1+jibSBPdcFxdQkE3LM6e3XzzzaXeN9y6Def7Es5vrqzf+aLq29+/Xnch8bci4/OV5/S/B+H+fsL5fZT1npfn8UtzD4M5mftREeUP55x8XnPmWIdtHa0d+bvVf2M8VzixZsLdl778tNqk5Q7P738dNOln/dLNiBY+/u0zLYw4k06LzOJgv4iz/rQa5P402S/ts5p9I1o40sJEd4OgmT+tA2g5xrrV4T2jS6gOrQL4POfrZI4fTh2EU5c6dDcqyQ2OfSDd3YEWDrQkpXUkLXVo1cq6LQn2L/yfF3ym0TIj2CIh3Hor7n6yz8v6oxWGbv3LPqz+fAunfko6ho7u8qFb0gpCeSMxKISIgMG42KEhzz33nPIXpCkdXxQv+DAONqujP6P+cH3ggQeUqRrdDdgoUUS44YYblKkboUlfKEGADVxR6cw4GGZnlo0IGwC6F7AT++GHH/q2Cads3CbUuUsTN8CfcM7J+BV0KcnOzlZ1wUZQNyPkdZQn+n3T/Yl5bj1DiD/ssOhuLTRJ5z2jzzHrhn7grGN/caCoc1kslkL1yM6RDs3yzzzzTNWRZUoxvnj9FHCKc6dhvbA8oaDZJAeTwfexQYMGyo/d/zukdxx02FmgyxDrRqcs1x9u3YbjEkB/X3a6OLilLyxdqkr7vSjvOgl1fHa4go8f/PlUfOc4YOXvqWHDhmH9ZstyfYTPqrIGvWVHlwM8ulFQgCR6elF2Tln+q6+++qTqNtzvSzi/ubL+5sOpb/2ZEGq5fg/C/Z6E+/so6z0vr+OX5h6Goqz3oyLKH+45/dsi/99DWeoo3H317eh64l8exu8g/F5x4Mr+yJtvvqlM++lGyMkOijaMF1EUDz74oNqHbTmfRfye6m1VadBdGoLLrg/w+azWB+HB902P4VLc9zrc45dUB+HWZah7HQqKy3wG0N2X7ic67F/SnYnCBV0SiyP4mng8njvYTSSceivpfrK+KF6wD8zycXLkoosuUu4s/M6HUz+s1+KOoaMLSaciG40gEBEohIiDvovs4D788MNKEKCPMx+iwek/6YOqB4akQsxOOl9U8+lTTF9WqtxUtuvXrx9yZoudeA6oioLKPn27OTtIfz76U/v70YZTNjao3D8Y+o+WJUhcOOekeMGGj7NAug84/eZ5LSWlKeXgMlTDFRyTIhRslNkI6j6x/lDs0a0RKDzx3rDxZt08//zzqqPCQRetVoqCPpwsv/+MMwcdvL/+cEaXM6P0s6bfKe9jcfEnuI6dmaJmE9iYc8aB98wfxtzgYLa471AoynL94dZtSXD2hR1F/0Ea/YbpY10ayrtOQh2fs7zBxw/+fCq+c/wN8HcWnIK3vFPysqPL+ioLvGbOAhL9uvXysY6KmxkLt25L830p6TdX1t98eRHu96S8fh+n4/cX7j0MRVnvR0WUv6zn1AezPKb/8yicOgp3Xz4n9LaJzz1/+PvULUE5QGdcAk54sO5poaULi6GgeMN7wlhI/nE5GG+rtKnG9faRZfcfqLP/Q072WR3u8Uuqg3DrMlz4HGe8huBJjaL6OKEIvt+sez6zg/scJRHu/aSoyxetTmiFyO8+LYNpPRRu/RR3DB09poy/1YcglCciUAgRBxsTihTs8DIaOwUBZpXg7I6/mk2LAD0AE2fQ9RkARlymCR8DW3E5BQpmzeCgnR0aPRI3M3pQyS8uuJweiZlKP/dlRzY6Otq3Ppyy0RSR5/AvI10vuL4sJs7hnJOzhDRH9R8gMBhVKMXfP5Co/6wHy6sH76MyT/PCkjJgEKb0YmTxV199NWB2mJ0VfQaN7iYUZzho4OwG3QLocqNnSygKlpWzA7wPhDMKzNzCcwXXEeuHs24cqDHDQEmMGjVKdZxopqqbHLMTwHNwloXfIWYtYWOvRyankMbvQzgRwXXCuX7em+D7Ek7dhgO/G/4RvWll4+/GRIo6fzDlVSdFwd8OXW8YmFLvZPL4p+M7RxcCZrjhufUOLYPvlSfMcMF65u/Wv2MfDnQNCbYEoKkwy0w3qJLS6IVbt+F8X0r6zYVT/xRAeX5mTgpXbCst4fx+wr3eslKexw/3HpbnM6giyl/Wc/L62J6x/ebAWG8n9QxW5bEvXUnZPnB7zpD7w5lufwsJina0WuEyiux6OxYKXjPxv266nHCiRLcMDfdZzUCwDKrNutWzRnBQzGtj+fWBb1kpzfGLq4PS1GW40IrsiSeeUANy3RWRA3UKZKGyrQXD/gWfGbo1HfsfDExK14/SEM79ZF+D4iCFBt5XuiRTwNC/c+HUT0nH0Fm9erWq/9Jk/RGE0iAChRCR0C/1v//9L1588UXlN0hfRj6c6V/KhoIPYfrPcjBJywE+fPmZcR7YCDHzAhtI3dqBijXTgnJARR9SdoY+/vhjtX1JPqAsCxsDWiTQhNkfNiwllY1uJzw/GzTOAnHQy+ja/qkYS0M452SjTFGEg242QGwE2UgFz95yW4o5jE7OASbNxdkAslFjxG3OiLIxpsl4sAljUTCqNMvITh3TvHGwyjRxzPJA/0/OYvK+8Dy8Bpq5c5DLe1OcOEFYBl4jTTP5nt8NDmZYTn94f7mMKcYoUJVkxklefvllJchQkGKniR13RuNm54b702SSHRoOKlmvnGlk55omm6WZTeGsTUnXT+GKvqscaLLzp6f4K6lug9ORhYLfd0ZNp4koLY9obcRo9/4Udf5gyqtOioL3j8dmp5dmqhTNgr/Hp+o798wzz6hz02SWx6RYqvsKl9UtIxhGh+c9oy+2v0DBZ5c+s8hOrH+6R/8Up6ejbsP5vpT0mwvnO0+TfQ5UKSyfKoEinN9PuNdbVsrz+OHew/J8BlVE+ct6Tn4n6evPZxNnwjlBwBnscMTXcPeleMnysJ1nu8TrYV+BVim01lm8eLFvW8Zg4OQLrUPZxvib3AfDQSjdprgdXRL4+2B7R2HSHwp6zD7E/hKFdT3NaPC10DWVZWQd8rnD/gLrmjEiTpbSHL+4OihNXYYL+zRsx9lOsV/Ee0mhmd8nTmaVBPtpFNtZbt4DijB6P6s0hHM/aWXB9RQK+ZujRRzPp2eXCqd+SjqGDi0rOFkX/H0ShPJCBAqhSkPzO5qmBZuUcrBMiweapXFAz8ECBQY2NDSv4yCSMz56R52DS3bkqXazgWTni2nv9Jlwwg4YAwktWLBAdchohsxOkT7Y4LYsS7DJG1Mo0oeSHaNQedBLKhuhKSMbFgY44mwCLTdYlnBMFhkAjz7epTknOwisD1pasCGkAEFBhvvp6VupnlPI4YwrZwj8oW8764+ddx6T2/Ea/EUVCkGsr+AGjr7nbDx5fbQ6YQPKeub59Vl2qv0cELBh5UwGB7TsHBcHG3d+T9i4cwaEZtoUD9jp0Ge4/aEoxA6wf1DN4uB90c0gGeyPLh/8zuidPX4vaEXCGRS6zjBQKrfzH0zpZQyG9aR3aOh3WtL1szPMumMd8run13E4dUtByj+QW/Bn1gnLyc4MB8Ic+PJaGdSwpPMHH6u86qQoaCHE7zFnS9nxooDEjjDvu38a4vL4zgVfG4/Pc1Nw4awyxUwKlV27dg14rpzM9emDegqs/oEu9TTBern40j8XNzDj75PnDcfHPty6Def7UtJvLpzvvB6wjh3r4ghV3/p1Bz9PeT/9ZwjD+Z6Ec70nc8/L8/jh3sNgTuYZVBHlP5lz8v5yoMy2kJYX9MvneWktV5LQGO6+tCykaymFfLpSsmz33ntvISsmPjdovcNnZaiJEZrl6xMBPD4H+ZzM4PZsb2l5yT6EHk+KMLYA22gu908z6n8swrql1Sjbdg7SKXSyjfdv0zmwDY6zwwmQUH20YMI5fjh1EE5dhipnUXCigd9hHo91RAGOEzZ8jocDn2mcWKKITGGP/YNgsT6cegvnfrLfxt8l+1qsS7av7K/6l7Wk+gnnGPokGfvNgnCqMDCVxyk7uiAIQhWF0dc548XGXA8IJQjhQjN4ip3+giUHTuxcU7DgIK884Dko7DAeQDgmx5H6m6M1DiPtc9AsCIJQ0XBCioIArboiCbresB2jm0eoyR1BKA/kmyUIguAHB0icIXn33XfV7LeIE0JZ4GwZZwXp4sHZMc50UUTg96q8xAndcoczsowJUFUFivL4zTGQHgMfCoIgCKcOBs+kBbGIE8KpRCwoBEEQ/KC5Nk0oaSruHy1bEMrSkaN5N4NYMqYGTeBLG8yyOiC/OUEQIg26ElGcLi5FuSAIoRGBQhAEQRAEQRAEQRCECqd8QokLgiAIgiAIgiAIgiCcBCJQCIIgCIIgCIIgCIJQ4YhAIQiCIAiCIAiCIAhChSMChSAIgiAIgiAIgiAIFY4IFIIgCIIgCIIgCIIgVDgiUAiCIAiCIAiCIAiCUOGIQCEIgiAIgiAIgiAIQoUjAoUgCIIgCIIgCIIgCBWOCBSCIAiCIAiCIAiCIFQ4IlAIgiAIgiAIgiAIglDhiEAhCIIgCIIgCIIgCEKFIwKFIAiCIAiCIAiCIAgVjggUgiAIgiAIgiAIgiBUOCJQCIIgCIIgCIIgCIJQ4YhAIQiCIAiCIAiCIAhChSMChSAIgiAIgiAIgiAIFY4IFIIgCIIgCIIgCIIgVDgiUAiCIAiCIAiCIAiCUOGIQCEIgiAIgiAIgiAIQoUjAoUgCIIgCIIgCIIgCBWOCBSCcJpISUnBjh07pL6D2LRpE3Jzc6VeylBvaWlpxW7zzz//wO12S90KgiBUU1JTU7FhwwbVB6lM7N27FwcPHixxu23btiErK+u0lKkqsHPnThw5cqTYbbZu3Yrs7OzTViZBKG9EoBCEMnL8+HGsX79eNbLB5OXlqXUcROp88MEHGDt2rNS3H3PmzMGIESNgNpsD6sXhcKj682+E2dhyWXGvEydOqG23b9+uPmdmZhaq70OHDql1hw8fLrSO++/atQsej6dS3afNmzerTqY/Z599NqZPn17sfvfeey/ee++9U1w6QRAE4VRCMZrtlqZppdqPbUCjRo1w+eWX46effkJl4t///jeeeeaZYrdZvXo1zj333JDr2L5zIF6SUO/Pvn37sHv37pDH4gSS0+lEZYL9keC+yrhx4/Duu+8Wux/b/fvuu+8Ul04QTh0iUAhCGfnmm2/QqVMnnHnmmYUGtJ999plax0GkTu3atdGiRQupbz/uvvtuPPzww4UEiokTJ6r6u/rqqwMG6VdeeaXvdc4556B3794By2bNmqW2vfTSS9X+L730UqH6vuiii9S61157zbds8eLF6NKlC5o0aYJBgwYhOTkZd911F44dO1Yp7hfL9PPPP5d6v8ceewyPP/64zD4JgiBUYShGs93i5Ee4HD16FC+//DLmzp2rrOluvvlmVDUosPznP/9BTEyMb9mqVatUm1irVi1ccMEFaN68OVq2bKkmgUrinnvuwYQJE3yfKXAMHDhQ9c8GDx6MGjVq4Kqrrqo01q433nhjQF8lXB544AF88skn6voEoSoiAoUgnARJSUnq/++//x6w/KOPPkLnzp0Dll1yySV46qmnCh2Dij1n/IPN8aiaUz3X32/cuDFgPU0jafoYbMJPM06aAAZbI/jPwPN4+izCnj171Hp2YEKZgHLGIZSVyIEDB3zl0+E52LC7XC6UxLx581T5ObMTDOuPIsPs2bN95+jWrVuAtcSoUaNUHfsvGz16tO8YXPfpp58GiEdr165VQkfTpk19y2g6StGCszTs0PFesG5bt25dqM6D4b7Bsy7c17++cnJyVNkyMjIC6o71Sri/Xv+0ygmG5WF97t+/X21HU91guC7ULFLfvn1Vx+urr74q9joEQRCEqgPFc7YNhH0Htuf+bR2tAefPnx/QBrEv4L8f2zu2J7TKYPukt6Nsk0K5Bha1r056erpq03meomA5g60Bi4JtIvsJ11xzjW/Z8uXL1cRP+/btlTUkB+AsF/sK3D6UGwTPGcpqglx22WWIjY1VfSJeG9tgWnX+9ddfxZaNQhHriXWrw315/TqsQ9Yn6ypUHeptOsvNawmGfQT2Mbi/fm+CLTx4jaH6bWz3hwwZUqKlhSBUWjRBEMrEW2+9pdWoUUN75JFHtMsuu8y3fM2aNVpcXJz29NNPq/U6Tz31lNanT5+AYzzzzDNq23r16mkJCQnavffeq3k8HrXu/vvv17p166YNHTpUq1OnjtarVy+1fNeuXVrfvn216Ohotbx27dra999/7zvm119/rY6nM3XqVPYgtAceeMC37NJLL9Vuv/129f62227TOnTooF5JSUla+/bttb///tu37csvv6w1bdrUVy6dzp07aw8++KB6f/z4cW3kyJFabGys1qxZM/Wf11scd955p3bBBRcUWr5582bNaDSq6zzzzDO1xx57LOT+N9xwQ6H61OnSpYt2zz33aA0aNNBmzJjhW37HHXdoN910k7pW1i9ZtmyZqp9169Zp4cK6+Ne//qXZ7XatRYsW6t49+uijat0bb7yhdezY0bftp59+qo7PetQ599xztccff1y9Hzt2rCoP6z0+Pl7r2bOntmXLloB7ZTab1bVwu+7du6vl/G7deOON6t7wZbFYtJtvvjlkPZ9//vlhX5sgCIJQuZg4caJqR3JyctTnl156SWvZsqU2ZswY1Q+oWbOm1rhxY2316tVq/eTJk1XbxH3atm2r2o49e/b49rv88svVPlyel5enzZ4929cPaNKkiRYTExPQZvmfM3jfzMxM7eqrr1btfvPmzVXfhO2v2+327bt//37VtrHNrFu3rtavXz/trLPO8vVDQvHkk09qvXv3DljGflBR7b4/PPaoUaO0du3aqfZxwoQJavkVV1yhDRkyRL1PTU1V9ePffwqHV155xXetiYmJqi+SnZ2tzZw5U127w+FQ2y1ZskQdn+20DsvBMpCHH37YV+dsz3m8hQsX+rZlHfI+6HXNF+uR18Z+AftgvFesU7bx+ndD591331XfCUGoiohAIQgnKVDs2LFDs9lsWkpKim8QzAbptddeK1ag4P5s5ObMmaM+O51O7YUXXlANPuEAmo3bO++8E3DeAQMGaIMHD9aysrLUZ54nKipK2717t/p84MABtd+mTZvU57vvvls1fBQ19MF1rVq1QjbKLpdLiST+A2w2iBQM/BtODuZ5jn/++Ud9pojCjhI7KoQDbJ5j0qRJRdYf60IXOPzh+Xk88vnnn2uNGjUK6OiEK1Cw/tgBGD16tFrGxpsCzNKlSwMEioMHD6rBPTsOFFrC4c8//1QdEYoohPeMghTrjwKVwWDQjhw5otaNHz9e1f+FF16oPufm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PfVUvQ6fv5DQWDzzzDP44Ycf9vv7CILQOIhAIQhCDXgRb9++Pe688060adNGCQHHHnss/v77b+86u3fvVlELvNlsNjVb8uKLL3qf37JlC4YPH64e8/Vc76yzzlJ/r1+/XkVkJCYmIj09Haeddhq2b98e9qfAFA+r1apSPPblfcrKynDFFVegQ4cOSE5OVvu4du1a+TYIgiAIQj34+uuvcemll+Kwww5TERQ9evRQaRWPP/64d50nnnjC22/gNXfChAlYvHix9/kHHnhAiRzsg2jrTZ8+XT332WefqcmJmJgY9OrVC08++WS9BIabb74ZJ5544j6/DyM2GV3KfkVGRobqJ9ntdvmuCEIjIwKFIAg1SEhIUALEihUrgh4ZChfl5eXqRqHghRdeUBf9zz//XD3fuXNnzJ49Wz3mtrjehx9+iD179mDMmDHo378/Vq9ejSVLliA6OhqTJ0+Gw+EI65PwjZjYl/d57LHHMGvWLPz222/YuHEjrrzySrzxxhvybRAEQRCEevYb5s6dq4T/UCKB1m/gdXnkyJE46qijUFhYqJ6/66671KQBJwu09Y444gh89NFHuP7665XYsWPHDnzwwQd4/fXXVVREuPhGTOzL+zAtZMiQIdiwYQNmzpypxJhff/1VviuC0MiIQCEIQg0uueQSDBo0CAMGDMCwYcNw7bXX4vvvv68lIGgzD1FRUSodhLMnX3zxhfd5g8Hgved6er0er732Grp164b7779fiRyMbOAydlYWLFjQoE+ioe9DUYL717NnT8THx6uOUn3DUQVBEAShtfP0009j4cKFaNu2rRr404/iv//+q7GOTqfz9huY/vHggw/CZDLhzz//VM/z2s11fNfj4/vuu09NgEycOFEJArxu33333XjzzTcb1NaGvg9TS7OysnDcccchKSkJHTt2VKmvxxxzTCMcQUEQfBGBQhCEGsTGxqrIgr/++ktdeNetW4dTTz1VzRr4GlFyVqFfv35qfV7gGZGwdevWOv0t5s2bp1I0LBYLzGazimxgiCQFg8YinPc577zzVMQHOxuvvvpqo76/IAiCILQWGIHAayijEDk58Omnn6pJjnvuuce7DlMszz33XHTq1Eldl9lv4LJQ/Ya9e/eqaIWrrrqqxvX8oosuatRrdjjvQzHlwgsvVKkinLj59ttvUVxc3GhtEAShGhEoBEGoBWcT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", + "image/png": "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vnLlSldMTIzrueeeU+t1nn32WVeXLl18jvH888+rbatVq+aKi4tz3X///S6n06nWPfjgg6527dq5BgwY4KpataqrU6dOavn27dtdXbt2dUVGRqrlVapUcX3//feeY3799dfqeDpTpkxhD8L10EMPeZZdeOGFrttuu029v/XWW10tWrRQr4SEBFfz5s1dy5cv92w7duxYV926dT3l0mndurXr4YcfVu+PHDniGj58uCs6OtpVr1499Z/XWxR33nmna9CgQfmWb9iwwWUwGNR1nnXWWa4nnniiwP2vv/76fPWp06ZNG9d9993nqlGjhuv333/3LL/99ttdN954o7pW1i9ZuHChqp/Vq1e7AoV1cccdd7hsNpurQYMG6t49/vjjat2bb77patmypWfbzz77TB2f9ajTs2dP15NPPqneX3755ao8rPfY2FhXx44dXRs3bvS5VyaTSV0Lt2vfvr1azu/WDTfcoO4NX2az2XXTTTcVWM/nnXdewNcmCIIglC8mTJig2pHMzEz1+ZVXXnE1bNjQddlll6l+QOXKlV21a9d2rVixQq2fNGmSapu4T9OmTVXbsXPnTs9+F198sdqHy7Ozs13Tp0/39APq1KnjioqK8mmzvM/pv29aWprryiuvVO1+/fr1Vd+E7a/D4fDsu2fPHtW2sc1MTk529ejRw9W9e3dPP6QgnnnmGVfnzp19lrEfVFi77w2PPWLECFezZs1U+zh69Gi1/JJLLnH1799fvU9NTVX1491/CoRXX33Vc63x8fGqL5KRkeH6448/1LXn5OSo7ebPn6+Oz3Zah+VgGcijjz7qqXO25zze3LlzPduyDnkf9Lrmi/XIa2O/gH0w3ivWKdt4/buh895776nvhCBURESgEIRTFCi2bt3qslqtroMHD3oGwWyQXn/99SIFCu7PRm7mzJnqc25uruull15SDT7hAJqN27vvvutz3t69e7v69evnSk9PV595noiICNeOHTvU571796r91q9frz7fe++9quGjqKEPrpOSkgpslO12uxJJvAfYbBApGHg3nBzM8xxr1qxRnymisKPEjgrhAJvnmDhxYqH1x7rQBQ5veH4ej3zxxReuWrVq+XR0AhUoWH/sAIwcOVItY+NNAWbBggU+AsW+ffvU4J4dBwotgTBjxgzVEaGIQnjPKEix/ihQaZrmSklJUetGjRql6v/8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", "text/plain": [ "
" ] @@ -2921,14 +2962,210 @@ "id": "8d240737", "metadata": {}, "source": [ - "Over the two weeks, the study region has 1,590 features. The current constellation observes 12% of them in the ATMS swath and 10% in the CrIS swath, and resolves 1% (ATMS), 5% (CrIS), and 10% (either future sensor), somewhat different from the two days above. Evenly spaced in its plane, a constellation of three satellites does slightly better (13% and 11% observed) than the current one, whose satellites are spaced unevenly.\n", + "Over the two weeks, the study region has 1,590 features. The current constellation observes 12% of them in the ATMS swath and 10% in the CrIS swath, and resolves 1% (ATMS), 5% (CrIS), and 10% (either future sensor), somewhat different from the two days above. Evenly spaced in its plane, a constellation of three satellites does slightly better (13% and 10% observed) than the current one, whose satellites are spaced unevenly.\n", "\n", "* **Satellites in one plane saturate.** Adding satellites to a single plane observes more features up to about four satellites, and then hardly any more (15 to 16% in the ATMS swath for four to six satellites), because they all observe at the same local times (near 13:30 and 01:30).\n", - "* **A second plane gives most of the benefit.** Six satellites in separate planes observe 29% of the features, almost twice as many as six in one plane. Six satellites in two planes (three in each) observe as many (30%): what matters is that the satellites do not duplicate each other's local times, not how many planes there are.\n", - "* **Planes and resolution trade against each other.** With heritage sensors, six satellites in separate planes resolve 14.5% of the features with CrIS, more than six satellites with a future infrared sounder in one plane (13.2%). Finer resolution pays off fully only with separate planes: a future sounder on six satellites in separate (or two) planes resolves 23 to 24% of the features: nearly all of those observed in the CrIS swath, and four fifths of those in the wider ATMS swath.\n", + "* **A second plane gives most of the benefit.** Six satellites in separate planes observe 29% of the features, almost twice as many as six in one plane. Six satellites in two planes (three in each) observe as many (30%), and in three planes (two in each) nearly as many (28%); likewise, four satellites in two planes observe as many as four in separate planes (19 to 20%). What matters is that the satellites do not duplicate each other's local times, not how many planes there are.\n", + "* **Planes and resolution trade against each other.** With heritage sensors, six satellites in separate planes resolve 14.2% of the features with CrIS, more than six satellites with a future infrared sounder in one plane (13.0%). Finer resolution pays off fully only with separate planes: a future sounder on six satellites in separate (or two or three) planes resolves 22 to 24% of the features: nearly all of those observed in the CrIS swath, and four fifths of those in the wider ATMS swath.\n", "* **ATMS is limited by resolution, not sampling.** More planes raise the share resolved by ATMS only from 2% to 4%, because its resolution element is larger than most features wherever they are observed.\n", "\n", - "The spread between the random phases (the shaded bands) is small compared with these differences. The trade holds the sensors and the altitude fixed; their swaths, altitudes, and resolutions, and orbits other than sun-synchronous ones, are further dimensions of a full trade study." + "The spread between the random phases (the shaded bands) is small compared with these differences. The trade holds the sensors and the altitude fixed; their swaths, altitudes, and resolutions, and orbits other than sun-synchronous ones, are further dimensions of a full trade study, which would add variables to the design space." + ] + }, + { + "cell_type": "markdown", + "id": "3f9c2a71", + "metadata": {}, + "source": [ + "### Pareto-efficient designs\n", + "\n", + "A design is Pareto-efficient if no other design is as good in every objective and better in one. With three objectives (the fewest satellites, the fewest orbit planes, each of which needs its own launch, and the most features resolved), the table gives the share of features resolved by each sensor's efficient designs (`tatc.tradespace.pareto_front`, from the means over the replicates by `tatc.tradespace.summarize`), blank where a design is not efficient for a sensor." + ] + }, + { + "cell_type": "code", + "execution_count": 14, + "id": "8b41d5e0", + "metadata": {}, + "outputs": [ + { + "data": { + "text/html": [ + "
\n", + "\n", + "\n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + "
sensorATMSCrISFuture MWFuture IR
satellitesplanesper_plane
1110.41.93.23.3
2120.84.16.86.8
211.14.37.67.8
3131.26.210.110.3
311.66.610.911.1
4141.57.412.112.2
222.49.215.415.6
5151.78.112.712.8
512.611.519.419.4
6161.88.413.113.0
233.614.323.323.7
\n", + "
" + ], + "text/plain": [ + "sensor ATMS CrIS Future MW Future IR\n", + "satellites planes per_plane \n", + "1 1 1 0.4 1.9 3.2 3.3\n", + "2 1 2 0.8 4.1 6.8 6.8\n", + " 2 1 1.1 4.3 7.6 7.8\n", + "3 1 3 1.2 6.2 10.1 10.3\n", + " 3 1 1.6 6.6 10.9 11.1\n", + "4 1 4 1.5 7.4 12.1 12.2\n", + " 2 2 2.4 9.2 15.4 15.6\n", + "5 1 5 1.7 8.1 12.7 12.8\n", + " 5 1 2.6 11.5 19.4 19.4\n", + "6 1 6 1.8 8.4 13.1 13.0\n", + " 2 3 3.6 14.3 23.3 23.7" + ] + }, + "execution_count": 14, + "metadata": {}, + "output_type": "execute_result" + } + ], + "source": [ + "from tatc.tradespace import pareto_front, summarize\n", + "\n", + "OBJECTIVES = {\"satellites\": \"min\", \"planes\": \"min\", \"resolved\": \"max\"}\n", + "# the mean shares over the replicates, by design and sensor, and the efficient designs of each sensor\n", + "trade_means = summarize(trade, statistics=[\"observed\", \"resolved\"], by=[\"sensor\"])\n", + "efficient = pd.concat(\n", + " [group[pareto_front(group, OBJECTIVES)] for _, group in trade_means.groupby(\"sensor\")]\n", + ")\n", + "efficient.pivot_table(\n", + " index=[\"satellites\", \"planes\", \"per_plane\"], columns=\"sensor\", values=\"resolved\"\n", + ")[sensors.index].round(1)" + ] + }, + { + "cell_type": "markdown", + "id": "c7d05a94", + "metadata": {}, + "source": [ + "For every sensor, the efficient designs are those in one plane (the fewest launches) and those in two planes (the most features resolved for the number of satellites): two planes of two satellites resolve more features than four planes of one, and two planes of three about as many as six planes of one, with fewer launches. Designs with more than two planes are efficient only if their satellites cannot be divided evenly between two planes (three or five satellites, in separate planes). Some of these differences are smaller than the spread between the replicates (the standard errors of the means are given by `summarize`), so designs that are nearly efficient deserve as much attention as those that are." ] }, { diff --git a/docs/examples/osse/index.rst b/docs/examples/osse/index.rst new file mode 100644 index 0000000..d01ed00 --- /dev/null +++ b/docs/examples/osse/index.rst @@ -0,0 +1,27 @@ +======================================= +Observing System Simulation Experiments +======================================= + +These notebooks run observing system simulation experiments (OSSEs): they +sample features of the simulated weather of the 7-km GEOS-5 Nature Run with +the swaths of the atmospheric sounders of current polar-orbiting satellites +(ATMS and CrIS) and of notional future ones. The hurricane OSSE uses the +observing systems of the monsoon OSSE, so read that one first: + +#. :doc:`RunOSSEMonsoon`: the cold cloud tops of North American Monsoon + convection over the American Southwest, the horizontal resolution of the + sounders, and a trade of the satellites and orbit planes of a + constellation. +#. :doc:`RunOSSEHurricane`: the cold cloud tops and heavy precipitation of a + simulated North Atlantic hurricane, with the same sensors. + +Each notebook downloads the part of the Nature Run that it needs once, to a +``data`` directory beside it. The notebooks require:: + + pip install tatc[osse] + +.. toctree:: + :hidden: + + RunOSSEMonsoon.ipynb + RunOSSEHurricane.ipynb diff --git a/docs/examples/tradespace/CompareScenarios.ipynb b/docs/examples/tradespace/CompareScenarios.ipynb new file mode 100644 index 0000000..ea75737 --- /dev/null +++ b/docs/examples/tradespace/CompareScenarios.ipynb @@ -0,0 +1,679 @@ +{ + "cells": [ + { + "cell_type": "markdown", + "id": "4679e176", + "metadata": {}, + "source": [ + "# Compare Designs across Scenarios\n", + "\n", + "How accurately samples estimate a daily mean depends on the field: samples hours apart estimate a field that varies slowly better than one that varies within the hour, such as rain rates. Which field a mission will serve may not be known when it is designed. Replicates average over the sample of points, but the field is a condition under which to compare designs: a **scenario**.\n", + "\n", + "It covers:\n", + "\n", + "* evaluating designs in several **scenarios**;\n", + "* the front of each scenario, and how often each design is efficient;\n", + "* **regret**, and designs that are robust to the scenarios;\n", + "* **searching** for designs that do well across the scenarios.\n", + "\n", + "It builds on `ExplainTradeSpace`: the objectives are fewer satellites, fewer planes, and more points accurately sampled." + ] + }, + { + "cell_type": "markdown", + "id": "5922e667", + "metadata": {}, + "source": [ + "## Define the Scenarios\n", + "\n", + "A scenario gives other values to fixed values or uncertain parameters of the design space. The field's decorrelation time must therefore be a value of the design space, which the metrics read from each design, rather than a constant of the metrics:\n", + "\n", + "* `field_space` adds the decorrelation time to the design space as a `Fixed` value (3 hours, as in `ExplainTradeSpace`);\n", + "* `sample_field` gives each design's decorrelation time to the metrics of `ExplainTradeSpace` (`sample`);\n", + "* `FIELDS` names three fields, which decorrelate within an hour, in 3 hours, and in 12 hours.\n", + "\n", + "With `scenarios`, the study evaluates every design in each field, with the same samples of points, and records the field as the `scenario` of each evaluation." + ] + }, + { + "cell_type": "code", + "execution_count": 1, + "id": "4c97b966", + "metadata": { + "execution": { + "iopub.execute_input": "2026-11-15T04:33:44.728113Z", + "iopub.status.busy": "2026-11-15T04:33:44.727957Z", + "iopub.status.idle": "2026-11-15T04:33:47.238570Z", + "shell.execute_reply": "2026-11-15T04:33:47.238053Z" + } + }, + "outputs": [ + { + "name": "stdout", + "output_type": "stream", + "text": [ + "16440 evaluations in 1 s\n" + ] + } + ], + "source": [ + "import time\n", + "from datetime import timedelta\n", + "\n", + "import pandas as pd\n", + "\n", + "from trade_space_example import ACCURACY, DECORRELATION_TIME, MAX_SATELLITES, accuracy_study, sample, space\n", + "from tatc.tradespace import Fixed\n", + "\n", + "field_space = space.extend(decorrelation_time=Fixed(DECORRELATION_TIME))\n", + "\n", + "\n", + "def sample_field(observations, design):\n", + " \"\"\"The shares (%) of points sampled sufficiently and accurately (of its field).\"\"\"\n", + " return sample(observations, design.decorrelation_time)\n", + "\n", + "\n", + "FIELDS = {\n", + " \"1 hour\": {\"decorrelation_time\": timedelta(hours=1)},\n", + " \"3 hours\": {}, # the fixed value\n", + " \"12 hours\": {\"decorrelation_time\": timedelta(hours=12)},\n", + "}\n", + "field_study = accuracy_study.replace(space=field_space, metrics=sample_field, scenarios=FIELDS)\n", + "began = time.perf_counter()\n", + "fields = field_study.run() # every design of the design space, in each field\n", + "print(f\"{len(fields)} evaluations in {time.perf_counter() - began:.0f} s\")" + ] + }, + { + "cell_type": "markdown", + "id": "7ec2c26b", + "metadata": {}, + "source": [ + "## Compare the Fronts of the Scenarios\n", + "\n", + "Criteria `by` the scenario judge designs in each field: `summarize` gives a row per design and field, with whether it is on the front of the field (`pareto`). `robustness` gives the share of the fields in which each design is efficient (its **Pareto trace**). The table gives the designs efficient in more than half of the fields:" + ] + }, + { + "cell_type": "code", + "execution_count": 2, + "id": "8e021fe5", + "metadata": { + "execution": { + "iopub.execute_input": "2026-11-15T04:33:47.240358Z", + "iopub.status.busy": "2026-11-15T04:33:47.240030Z", + "iopub.status.idle": "2026-11-15T04:33:47.357928Z", + "shell.execute_reply": "2026-11-15T04:33:47.357304Z" + } + }, + "outputs": [ + { + "name": "stdout", + "output_type": "stream", + "text": [ + "efficient designs: {'1 hour': 14, '3 hours': 13, '12 hours': 6}\n" + ] + }, + { + "data": { + "text/html": [ + "
\n", + "\n", + "\n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + "
descriptionsatellitesplanes1 hour accurate3 hours accurate12 hours accuratepareto_trace
design
33b006848799800 km, 60 deg FOR, Walker 45 deg: 2 x 1 (spac...2.02.026.234.260.40.67
b85daf65c3a4800 km, 60 deg FOR, Walker 75 deg: 1 x 3 (spac...3.01.08.017.095.60.67
87addc291d43800 km, 60 deg FOR, SSO: 1 at 09:00, 2 at 15:003.02.040.860.685.80.67
904a205f7cd9800 km, 60 deg FOR, SSO: 2 at 09:00, 2 at 15:004.02.069.085.493.00.67
cb6bd361b577800 km, 60 deg FOR, Walker 75 deg: 4 x 2 (spac...8.04.096.696.697.80.67
5529c21520be800 km, 60 deg FOR, Walker 75 deg: 3 x 3 (spac...9.03.097.897.897.80.67
de505bc89299800 km, 60 deg FOR, Walker 75 deg: 3 x 3 (spac...9.03.097.897.897.80.67
679ca275c8fc800 km, 60 deg FOR, Walker 75 deg: 3 x 3 (spac...9.03.097.897.897.80.67
\n", + "
" + ], + "text/plain": [ + " description satellites \\\n", + "design \n", + "33b006848799 800 km, 60 deg FOR, Walker 45 deg: 2 x 1 (spac... 2.0 \n", + "b85daf65c3a4 800 km, 60 deg FOR, Walker 75 deg: 1 x 3 (spac... 3.0 \n", + "87addc291d43 800 km, 60 deg FOR, SSO: 1 at 09:00, 2 at 15:00 3.0 \n", + "904a205f7cd9 800 km, 60 deg FOR, SSO: 2 at 09:00, 2 at 15:00 4.0 \n", + "cb6bd361b577 800 km, 60 deg FOR, Walker 75 deg: 4 x 2 (spac... 8.0 \n", + "5529c21520be 800 km, 60 deg FOR, Walker 75 deg: 3 x 3 (spac... 9.0 \n", + "de505bc89299 800 km, 60 deg FOR, Walker 75 deg: 3 x 3 (spac... 9.0 \n", + "679ca275c8fc 800 km, 60 deg FOR, Walker 75 deg: 3 x 3 (spac... 9.0 \n", + "\n", + " planes 1 hour accurate 3 hours accurate 12 hours accurate \\\n", + "design \n", + "33b006848799 2.0 26.2 34.2 60.4 \n", + "b85daf65c3a4 1.0 8.0 17.0 95.6 \n", + "87addc291d43 2.0 40.8 60.6 85.8 \n", + "904a205f7cd9 2.0 69.0 85.4 93.0 \n", + "cb6bd361b577 4.0 96.6 96.6 97.8 \n", + "5529c21520be 3.0 97.8 97.8 97.8 \n", + "de505bc89299 3.0 97.8 97.8 97.8 \n", + "679ca275c8fc 3.0 97.8 97.8 97.8 \n", + "\n", + " pareto_trace \n", + "design \n", + "33b006848799 0.67 \n", + "b85daf65c3a4 0.67 \n", + "87addc291d43 0.67 \n", + "904a205f7cd9 0.67 \n", + "cb6bd361b577 0.67 \n", + "5529c21520be 0.67 \n", + "de505bc89299 0.67 \n", + "679ca275c8fc 0.67 " + ] + }, + "execution_count": 2, + "metadata": {}, + "output_type": "execute_result" + } + ], + "source": [ + "from tatc.tradespace import Criteria, robustness, summarize\n", + "\n", + "BY_FIELD = Criteria(ACCURACY, by=\"scenario\")\n", + "by_field = summarize(fields, BY_FIELD) # a row per design and field, and whether it is efficient in the field\n", + "print(\"efficient designs:\", by_field[by_field.pareto].scenario.value_counts()[list(FIELDS)].to_dict())\n", + "\n", + "# a row per design: its share accurately sampled in each field, and the share of the fields in which it is efficient\n", + "traced = robustness(fields, ACCURACY).set_index(\"design\")\n", + "ACCURATE = [f\"{field} accurate\" for field in FIELDS]\n", + "traced[traced.pareto_trace > 0.5].sort_values([\"satellites\", \"planes\"])[\n", + " [\"description\", \"satellites\", \"planes\", *ACCURATE, \"pareto_trace\"]\n", + "].round(2)" + ] + }, + { + "cell_type": "markdown", + "id": "130532b7", + "metadata": {}, + "source": [ + "Every design in each field, by its layout, with the front of each field ringed:" + ] + }, + { + "cell_type": "code", + "execution_count": 3, + "id": "8b9e713f", + "metadata": { + "execution": { + "iopub.execute_input": "2026-11-15T04:33:47.359293Z", + "iopub.status.busy": "2026-11-15T04:33:47.359131Z", + "iopub.status.idle": "2026-11-15T04:33:47.870108Z", + "shell.execute_reply": "2026-11-15T04:33:47.869597Z" + } + }, + "outputs": [ + { + "data": { + "image/png": "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DRP/3nDDDYamaUYmUFdXZ9x2221GaWmpOJe//OUvD/q8Rx55RPy+f//+ht1uNy655BIjFosZmQqd97vuukuMK06n07jmmmuMTIbGlB//+Mfi+zd48GAxBtK/K1euNDKVDRs2GKeeeqpRUlIirm2Hw2GceeaZ4rNkOk1NTaIPoTHm3XffNTKVZ5991rBarV/ppzP5u6eqquhTqJ+g66Jbt27Gvffea2QqV1999VfOL82PLrroIiNT+eMf/yj6tYEDBxq9e/c2cnNzjRdeeMHIVFavXi3myNRXUL/m8XiM5557zsgUVqxYYVx88cWi36U+geYZB0LfORr36LqmcZDGQxoXM5mNGzcaV155pRjf6XO9/PLLRqa396yzzhLXM83vXC6XcfbZZ4vxPFP5+OOPxXq7V69exoABA8T18XXzqEzjiy++MCwWi7g2WlpajEzliiuuEN/N9n309ddfb2QyNLem+RHN+Wkd2717d+O999470s06KLRGPXAMpH6arou//vWvRiYSjUZFf0zzTtJhaGyhsXDp0qVGpvLmm2+K9TXpA9Rf0Nzoyy+/NDIFmguPGzdO9L/0t49EIl95zu7du40hQ4YI3auyslJ8nhkzZnyj47AYnCZuv/12Y82aNWICng1i8D333GPU1ta23X/ssccMs9ksBMFMhNpFkypa9KQmiSSwDh8+3Mh0Hn30UeO0004THX02iME7duwwsgXqSBVFMd555522xz788ENj586dRjZAgysJ2XfccYeRiZDgSwPQzTff3PYYbQ7QdULnORO57rrrxKDf0NAg7lM/RyIU9XGZwOLFi0WfQOIYLWQOtoiZM2eOIUmSMW3aNHF/165dYmJ+//33G5ksVP7+978X53vixIkZLwZv3rzZePLJJ9smXzSmkBhFk61MZerUqcbnn3++3+KnrKzM+NnPfmZkOrRBQ9d6NojB1F9kE6nNJRJ2CNr4evrpp41sgfpEui5I5MlUYZXa99Zbb7U99uCDD4q5R6YKOrRIv/DCC414PC7uz58/X4hQy5YtMzKBV155xXjttdeMvXv3fq0YfN999wnBgRbDqf6PxsW5c+camQr1bRSgEA6Hs0IMpnncBx98sN+YQtfOD37wAyOT++j26xQSWDN5TpqC+ooePXqI8TobxOCrrrrKyBZIGyABeNKkSW2b43R+qZ/JFh5++GGxEU1r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", + "text/plain": [ + "
" + ] + }, + "metadata": {}, + "output_type": "display_data" + } + ], + "source": [ + "import matplotlib.pyplot as plt\n", + "\n", + "from tatc.tradespace import plot_designs, use_style\n", + "\n", + "use_style() # the style of the plots of trade studies\n", + "\n", + "LAYOUTS = {\"walker\": \"Walker\", \"sso\": \"Sun-synchronous\"}\n", + "fig, axes = plt.subplots(1, 3, figsize=(14, 4.2), sharey=True)\n", + "for ax, field in zip(axes, FIELDS):\n", + " plot_designs(\n", + " by_field[by_field.scenario == field],\n", + " \"satellites\",\n", + " \"accurate\",\n", + " by=\"layout\",\n", + " names=LAYOUTS,\n", + " jitter=0.18, # spreads the designs of each number of satellites, for legibility\n", + " legend=\"lower right\" if ax is axes[0] else None,\n", + " ax=ax,\n", + " )\n", + " ax.set(xlabel=\"Satellites\", ylabel=\"\", xticks=range(1, MAX_SATELLITES + 1), ylim=(0, 105))\n", + " ax.set_title(f\"A field that decorrelates in {field}\")\n", + "axes[0].set_ylabel(\"Points accurately sampled (%)\")\n", + "plt.show()" + ] + }, + { + "cell_type": "markdown", + "id": "0685f3c7", + "metadata": {}, + "source": [ + "Which designs are efficient depends on the field: 14 designs in the field of 1 hour, 13 in that of 3 hours, and 6 in that of 12 hours, and no design is efficient in all three. In the field of 12 hours, one plane samples well: three satellites in one plane sample 96% of the points accurately. In the fields that vary within hours, the samples must spread over the day: the same three satellites sample 17% (3 hours) and 8% (1 hour), against 61% and 41% for three satellites in two sun-synchronous planes." + ] + }, + { + "cell_type": "markdown", + "id": "41e6700a", + "metadata": {}, + "source": [ + "## Choose a Robust Design\n", + "\n", + "A design need not be efficient in any field to be a good choice when the field is unknown. Its **regret** in a field is how far it falls behind the best design there, and a **robust** design has the least regret in its worst field.\n", + "\n", + "Regret here is in one objective, the share accurately sampled, among the designs of at most a number of satellites (a `Requirement`). With the numbers of satellites and planes as objectives too, a design could match the cheapest efficient design by dropping satellites, and regret would mostly count satellites." + ] + }, + { + "cell_type": "code", + "execution_count": 4, + "id": "acf5055d", + "metadata": { + "execution": { + "iopub.execute_input": "2026-11-15T04:33:47.871376Z", + "iopub.status.busy": "2026-11-15T04:33:47.871141Z", + "iopub.status.idle": "2026-11-15T04:33:48.063602Z", + "shell.execute_reply": "2026-11-15T04:33:48.062897Z" + } + }, + "outputs": [ + { + "data": { + "text/html": [ + "
\n", + "\n", + "\n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + "
descriptionsatellitesplanesmax_regret1 hour regret3 hours regret12 hours regret
at most
2800 km, 60 deg FOR, Walker 75 deg: 2 x 1 (spac...2.02.011.07.66.411.0
3800 km, 60 deg FOR, SSO: 1 at 09:00, 2 at 15:003.02.09.89.80.49.8
4800 km, 60 deg FOR, SSO: 2 at 09:00, 2 at 15:004.02.05.00.00.05.0
6700 km, 60 deg FOR, Walker 75 deg: 3 x 2 (spac...6.03.00.40.40.20.4
\n", + "
" + ], + "text/plain": [ + " description satellites \\\n", + "at most \n", + "2 800 km, 60 deg FOR, Walker 75 deg: 2 x 1 (spac... 2.0 \n", + "3 800 km, 60 deg FOR, SSO: 1 at 09:00, 2 at 15:00 3.0 \n", + "4 800 km, 60 deg FOR, SSO: 2 at 09:00, 2 at 15:00 4.0 \n", + "6 700 km, 60 deg FOR, Walker 75 deg: 3 x 2 (spac... 6.0 \n", + "\n", + " planes max_regret 1 hour regret 3 hours regret 12 hours regret \n", + "at most \n", + "2 2.0 11.0 7.6 6.4 11.0 \n", + "3 2.0 9.8 9.8 0.4 9.8 \n", + "4 2.0 5.0 0.0 0.0 5.0 \n", + "6 3.0 0.4 0.4 0.2 0.4 " + ] + }, + "execution_count": 4, + "metadata": {}, + "output_type": "execute_result" + } + ], + "source": [ + "from tatc.tradespace import Requirement\n", + "\n", + "robust, robust_design = [], {}\n", + "for limit in (2, 3, 4, 6):\n", + " within = Criteria({\"accurate\": \"max\"}, requirements=[Requirement(\"satellites\", \"<=\", limit)])\n", + " regret = robustness(fields, within).set_index(\"design\")\n", + " best = robust_design[limit] = regret[\"max_regret\"].idxmin() # the design of least regret in its worst field\n", + " robust.append(\n", + " {\n", + " \"at most\": limit,\n", + " **traced.loc[best, [\"description\", \"satellites\", \"planes\"]],\n", + " **regret.loc[best, [\"max_regret\", *(f\"{field} regret\" for field in FIELDS)]],\n", + " }\n", + " )\n", + "pd.DataFrame(robust).set_index(\"at most\").round(1)" + ] + }, + { + "cell_type": "markdown", + "id": "8d72e778", + "metadata": {}, + "source": [ + "In each field, the robust design of each number of satellites (blue) against the best design of at most as many satellites in that field (gray): the gap between them is the robust design's regret in the field." + ] + }, + { + "cell_type": "code", + "execution_count": 5, + "id": "ae6ac96b", + "metadata": { + "execution": { + "iopub.execute_input": "2026-11-15T04:33:48.065013Z", + "iopub.status.busy": "2026-11-15T04:33:48.064674Z", + "iopub.status.idle": "2026-11-15T04:33:48.239143Z", + "shell.execute_reply": "2026-11-15T04:33:48.238612Z" + } + }, + "outputs": [ + { + "data": { + "image/png": "iVBORw0KGgoAAAANSUhEUgAABYMAAAFzCAYAAABsLxaJAAAAOnRFWHRTb2Z0d2FyZQBNYXRwbG90bGliIHZlcnNpb24zLjExLjIsIGh0dHBzOi8vbWF0cGxvdGxpYi5vcmcvgI3uAAAAAAlwSFlzAAAPYQAAD2EBqD+naQAA73VJREFUeJzs3QWcG2X6B/Bn3d136y5bp+5e6i1FywGH3R8pHHC4HIWD4nA4B4ce0lJoqQt1WqqUuvt23Xe7vsn/83u3k02ySVaa1fy+n0/aZCaZmcwmb9555pnnddLr9XohIiIiIiIiIiIioibNub43gIiIiIiIiIiIiIhqH4PBRERERERERERERA6AwWAiIiIiIiIiIiIiB8BgMBEREREREREREZEDYDCYiIiIiIiIiIiIyAEwGExERERERERERETkABgMJiIiIiIiIiIiInIADAYTEREREREREREROQAGg4mIiIiIiIiIiIgcAIPBRA5Op9PJ448/XuE+ERFVzdNPPy1FRUUV7hMRUeX+9a9/SVZWVoX7RERUuTfffFMSExMr3CeyhcFgavTQ4C1YsMBkWklJiTz55JP1tk1VWX9mZqZ8/PHHqtO7bdu2Ol+/BgFg7ENL97XAcH3vTyKqPR9++KF89dVXFabjO4/vfn2pbP2lpaXyww8/yD//+U/1G1BcXFyn6zf273//2xAANr5vHBiu7/1JRLXjiy++UP05cy+88ILk5OTU226v6vrPnj0r//jHP+TQoUP1sn7A/tOea3zfODBc3/uTiGrH999/L++8806F6a+99pqkpKTU226vyvrj4+PlrbfekkcffVT1R+t6/ca/Q6mpqRXuGweG63t/UsPDYDA1aufOnZNXX31VHnnkERUY0OCA++2336637aps/XFxcTJw4EDZt2+fXLp0SaZMmSKffvppna2/KpycnCQiIsJuyyOihgedxeeff14ee+wxyc/PN5mH73x9Bi8rW/+kSZNkxYoV4urqKq+88orccsstdbr+qkAbirbUXssjooYFfTi0nwgCZGRkVDjRhvn1pSrr1+v1cs8996gTaydOnKjz9VcmLCxMXFxc7LY8ImpY0C/Ccfy8efPU8bGxzz//XNLS0upt2ypb/+HDhyU2Nlb++OMPCQ8PNxw319X6qyIkJETc3NzstjxqWlzrewOIrgTOfN1+++2qEV65cqVMnjxZTf/ss8/UjwsyHeCNN94weR0ytebOnate+/PPP4u3t7fcddddcuTIEfW4Q4cOMnv2bMPz8/Ly5Ntvv1Vn/wYNGiRjx441zNu6dav8+uuvKlshKipK/aBVtn4vLy/ZuHGj4UejY8eO6r1gGyyxtA4t66ywsFACAgJk5MiRMmTIEKvvH8FyZM8dPXpU2rZtKzfeeKPhx8HaAUJSUlKNlmdte4moYfnf//4nM2fOlPT0dPnpp5/k5ptvVtO//PJLwxUBOBBHdpanp6fJa3HlAIIIaDOdnZ3l7rvvVifo0C40b95cbrvtNjVda3PRhmJ+3759VSBXs3v3btV+I/srMDBQnnnmmSqtH4GBNm3aqPsTJkyQ6dOnW32fltYBWC6u0vDz85OhQ4fKqFGjrL5/d3d39V4PHDggLVq0UL8R5ttkDm0o2tLqLs/a9hJRw/Ljjz/K6NGjxd/fX7Vx999/v5o+f/581QdCNiv6mOivBQUFmbwWAWScxFq+fLlqI9GGImvru+++U0HQO++8U53sAvS5kD138uRJ6d69u2q3NWhDfvnlF9VeoF156aWXqrR+eP/992X48OGVZtxaWoeWdZaQkCA+Pj4yYMAAufrqq22+fyxj7969qm+I3xu8zhbsD7z36i7P2vYSUcOybNky1abhhr6S1t9ZsmSJ+v4jmzU4OFgefvhhiY6ONnktEgFmzJhhOObEcTSO2b/++mvVJuOx1q9CXwztNQK4nTt3lmuvvdbQRz127Jjqj6EvjOdhndiuytaPfvB9990nL774YqXv09I6sP4PPvhAzpw5o2IDV111lUydOlUlEVh7/6tWrZIdO3ZIaGioavMQA7AFwV9cOVfd5VnbXmpa+BelRgsNEy5tRsDh1ltvVWe7NOggoiGNjIxUN3PodL/++usqGIwfDQRikZ3797//XTV06GyicQYcwCNIsHjxYtUhxQ8LXgu7du2SG264QZVUwHpw9q0q68fzjM8eIkCCALQl1tYBWAamYbvwXtDxtbR+7KuJEyfK6tWrxcPDQxYtWmQzcGJeMqI6y7O1vUTUsKDts9WGam2Mlt1qDO3DX/7yF8nOzpaFCxeqNvRvf/ubei5KJSDLA9BejBs3TgVKcP+hhx5SB/KAk0l4HU5qYT0IgFR1/QgEo52eM2eOaru19sqctXUA7mvLf+CBBwzlMiyt/7rrrlMdY7R5OPAYM2aMej+2aCUjqrM8W9tLRI2jDcUBNU78aG2Mlt1qDO0XTqTjYBsH5DhJhmWh/4RlGZfnQvBXK0WBIDICEIBMOiQoIGMW7YvWt6zK+hFYRhuEy5ttsbYOQB8Py0cyAII4aPOsrR/9VLSxCM7+/vvvKoGhsvI+WsmI6izP1vYSUcNtQxEM1vpVOElv/J23lMCEZKXrr79enXj/7bff1Mmom266SbUDCPyif6jB8rXjd/yP/iug/cUJMVzZYdxHq2z92M5169aptgYn+HH1V3JyssX3aG0dxm0ogta42hkxCGvvHwHc9957T50kxNXF/fv3V3GMyvYvrgKszvJsbS81MXqiRurXX3/VDxgwQN3Py8vTh4SE6JOTk9Xj/Px8vYeHh9XX5uTk4JdGn5CQoB7//vvven9/f7Uc+PHHH/XTp09X95cvX67v2bOn4bV79+7VBwcHq/s//PCDfvTo0frz58+bLL+y9RvbuHGjvm3btvqLFy9anG9tHXD69Gn9G2+8oX/00Uf1kydP1t92220W17927Vp9q1at9I888ojh5unpqU9JSdEXFxfrXVxc1POs3a/O8mxtLxE1HLt379Z36tRJ3S8pKdFHRUWpNkWD7zy++9agfTh69Ki6f+TIEb2rq6s+IyPD0EaMGDFC3d+6dau+TZs2ah1w5swZtWy0MatWrdL379/fZL1VXT98//33+rlz5+q7d++uf/rppy0+x9Y6Lly4oH/77bf1jz32mP6aa64xtPvm69+1a5c+MjLSpM0LCAjQnzx5Us338fFRvyu27ld1eba2l4gaDnxfmzVrZmjb2rdvr/qImoiICEM/0xL0W7dv367u43nol8bFxRnaCK3veejQIbWsgoIC9TgpKUn1udDe4vWxsbH648ePV1i+rfWXlpbqx4wZo5YNgwcP1i9atMjic22tIzExUf/uu++qNnT27NmGdt98/SdOnNAHBQWZtHmYj98hiImJUe2xrftVXZ6t7SWihgPtR1hYmKFvdNVVV+k3bNhgmN+xY0fVv7QGx8/oMwGO4Z2cnPQHDx40tBE4VgUcY/v5+emzs7PV46ysLHXcf+7cOdWPbd26tWoLdTqdyfJtrR/tL9pstJ3PPfecav/QBuFY2JytdaSlpek/+OAD/eOPP66//fbbTWIOxutHu+/r62vS5rVo0ULFQ6Br1676AwcO2Lxf1eXZ2l5qWpgZTI0WznThLBVKFzz77LPqcpBvvvmmyq/HpWRa1i4uw8UlZrhEQ3usXTKHDIOuXbsaXtetWzd1pgxnznBpCmoF4UwaSiXgsuXqwBlFZNIhw9b80hONtXVgwI9+/fqpS0twVhE383p1GjwH70nL7MUNl7Rolx9Wl63lXek+IaK6a0NxuS3aUFzqhswrTKsOfMcB7QHaIPxvqQ3FJXlaZlqrVq1UNiwyKJBRgRI3yEBo2bKlugytOnAVwnPPPSfr169Xlwsim8GctXVg/bgkD5m4yNxFtkR12lBkwfn6+lZre6uyvCvdJ0RUN9Beou+J9hPtKPqVxtnB1W1D0S7GxMRYbEPbtWun5gNqU+KG0mXoa+Fy5/Hjx6vXVnUAI2QEY7nYXmw7+pTIytu0aVOF51pbB64K6dOnjyrTgO3FNtlqQ7GvjNs8rLemVz7YWl5N9wkR1S0ct+N7jP4Pvr/oJ9a0DcUxPK4SMG5TjdtQlONCdixgneiLYjpKNeJKC1zhinYEV0rg6ozKoM+M7NqnnnpKlZ5E2TX0dVH2x5y1deDKMZROw0DyWntmrQ3FVcTosxu3ech8Rlm2mrC1vJruE2qE6jsaTVQTmZmZ6gzfK6+8on/99dfV7eGHH1ZnvwAZZ25ublZfj0wtZGxpcJYMZ8s0yGpDdqt2H9lzWubHtm3bVEaXOZyJxBk2LdvW1vq1jGNkkWiZZVVhvA5kxM2aNcsw74knntBPmzbN4vvftGmTOtt36dKlCsusSmZwdZZnbXuJqOFAhhmucHjxxRcNbSgya/G9RsYY4LurZbVagvYBbQMgWwsZERpktfXp08dwH9lzWlbb4cOHVfurtakaZHEhQwTZHJWtPz09XWUYa3Af21NZm2S8jpUrV6rMOA1+T4YPH254bLz+ffv2qddhvZZUJTO4Osuztk+IqGFAO9m8eXPVbmptKNpTZPtqbR3aPS2r1RI8V+sfmV+Bhe88st60+2ivtaw2XHnl5eVVoX08e/asyoRDm1vZ+vfv32/YbtzwOlxdpr3WGuN14Ko6ZPJpPv74Y32PHj0Mj43XjzYamXjWMpWrkhlcneVZ2ydE1HB06dJFHb9r7RD6YfheI3MXkOGvZbVagjbSuH9kfAUW2la0scZZsFp7i//xOD4+3mR5uDIDsQQc+1dl/UOGDNEvXLjQ8BhXdX377bc237PxOhB/aNeunWEerq5t2bKl4bHx+pFB7O3trT916pTF5VYlM7g6y7O2T6hp4QBy1Chh1OPBgwerbAwNzlhh4KKdO3eqjNn27durWmzICjAfwK06MDAIljFw4EDp1auXqh2sDUSBDIqlS5eq+6dPn5ZmzZqpDDOc2bS1fhRlRwYtBrz76KOP1DRkVGBEanPW1oEzicgqRs00DJCBWj/IyAVk6Jqvf9iwYao4PzIlcPYUZyCRUVcV1Vmete0looYD7RjqlJsPTIb636hfixq/+H5jcCPU5rU0gFtVIfsWbTKytTDAEAaxQE00tJNor9Fuw4ULF1RmnXaVhK31o1Ybau4iWw6vwUAf+D1AloM5a+vA/xioDetAdgYGIjW+QsN8/Vhfz549Vb10vBYZIVpd5Kqo6vJs7RMiahjWrl2rvpv4LhtbsWKFGr8B329859FPQ7aYtQHcqgLt3LRp01QbiisGsA5kauFKAgyUptU6T0xMVLUytYE1ba0fV7nhZvybgHWgvTZnbR0YYwPZZegbop+IMSOM22nz9WNwvd69e6ua6FqGHq7oqOpValVdHgaDtrZPiKhhwKBlOH5F/V7jgclwHInjfAyoie/8gw8+qI6/LQ3gVlU4xsaYP+iD4uor9HNx/Iyrgk+cOCGffPKJeh5q6+LWqVMn9biy9eO4F4P/rlmzRk6dOiW5ubmqHTVnbR0YtA3jQ6AmPDKN0f8zZr5+XOWAeAQGmdMGesM0rf2rTFWXh3bT2j6hpoXBYGqU0Hibj9yJH5L//Oc/hssY0FHHpRr4oTGHS+1efvllkx8J48AygiTocAJKUaCMA5aFEZPvvfde6dGjh0mpCawbHWgEd7VLoW2tHx1485GNrQ20Zm0duAwGP6QbNmyQ1q1bq8cYIVVjvn5cioPi+vv371clLrQRl7Es7TJka/erszxb+4SIGgZcPqcNpGE+srw2SASCAwjcZmZmWhw4Au2D9t3GySDjS3FxmRkGddNggDkMkITAwZ133mkIOOBEkjYwBTqnaMO1gK6t9WMk5I0bN6ogMC5VRlBAa5fNWVsHbnv27FGdeJy0QhABbarGfP3YNwjm4jUYmMg4gIHfE+0Sbmv3q7o8W/uEiBoGfK/xHTaHk+Xapcm4bBjfe5SvsdQPwkkxre+Ek0FogzQIEhgPIIdLpxHAQFABAx8NGjTIsB1ae4EDfQzghvaxKus3hjZUSyiw9F6trQPtF4LTmI+TWSjZozFfP/q9s2bNUgEPbR9pbTvKvWllhqzdr+rybG0vETUMOF5H/8Y4EAw4vr948aJhAEkkKaSkpFgcQA5tJNpKDdpQ7XloW7XB2OCtt95SgVocK2PQuREjRqjpxu0FykJiGVoZycrWj8Dy5s2bVdlHJI8hqGopccLWOnASDScQEQdAG6olVFlaP5LGkECAATO143GtbUeZDcRHbN2v6vJsbS81LU5ID67vjSAiIiIiIiIiIiKi2sUB5IiIiIiIiIiIiIgcAIPBRERERERERERERA6AwWAiIiIiIiIiIiIiB8BgMFUKA1b897//bfB7CoNHYORRwOAS9913nzQWGFwJBd0dQVJSUoXRt5saFP/HgHtEVwojpp8+fZo7koioBjDI2MGDB7nviMhhnTx5Ug3G2Bjg+B3H8YDjem1wyIZu9+7d8s4774gjKC0tlUceeUQNAthU7d+/Xz799FNp6sqHwqZGCyOhYxTKoqIiGTp0qBplWBud9+jRo/LRRx9Jfn6+GrV8yJAhhtfZmmf+A/Lnn3/KHXfcUSvbjzEM//rXv8qrr74qERERatq7776rRlfXRlLG/bvuuku+/PJLcXd3t7icwsJC+fnnn9XIpHl5eWqffPDBB3bdVgTFzYN8kydPlptvvln9CGAUaQ1GE8X2VgUOVDCS/IwZM6Q2Yf+sXr1ajbyK/dmqVasrXubevXvV3w569uwpTzzxhM3nY5RYfE7r0pIlS9Rn6MYbb7TrcjGKtnaiBPuzV69e6n6/fv3UCLP43piPkktNBz5TaG8OHDggQUFBctttt0m3bt0M87/77jvVXjRr1kweeughk9HMbc0zhu8r2oU2bdrU2vvIzc2Vzz77TL2P1q1bq8+y1hbbmgfnzp1T3wH8Hx0dLbfeeqt06tSpyuvGwcmJEyfU/blz50rHjh1r9B7wG4btsDTaM+D3Eb8H+E726NFD7r//fsNvCUZVxjy8hwEDBsidd95pGJ25OsuxNa8yCQkJ8sknn0h8fLwMGzZMbrrpphq1HZXtB1v7GyceTp06ZXiMbcDI2HW5H8ixoN+G9uWPP/4QPz8/1Ze66qqrTPosy5Ytk/DwcPn73/9uMpq5rXnGNmzYIP3795fY2Nhaex/oR3/xxRfqfaBNRxuC/yubB/jOYx/gu4f3gj589+7dq7zu1NRU1XacPXtWtV9og9GfrK7/+7//U325gIAAqwf/WM/OnTtVu4F97uXlpeZlZmaq7zyOF9APuueee6y2QbaWY2teQ9kPr7zyimrb4PHHHzf0+7QTD/it1EybNs1qv7O29gM1PubHj9C8eXN5/fXXDX2Ut99+W/UTJk6cKNdee63hebbmmX8/0OfEMVhtee6552TSpEmqvQUch69cuVI+/vhjw3PmzJmjPs9t27a1uhy8Dsf/6BejnX/55ZfV74M9k9zQ5hpD3x19IOxPbKOxf//73yb9Xmvi4uLkt99+U++vNiF+g34e+uc41pw5c6Zdlottnz9/vmo3Z8+ebfJbbA6/aejX1eUx7r59+9TnqbI4g73ed9euXdXvMfrBVfn7N1aMUjRy69evVx2Ndu3aqQ8vMi61s1I4qzZ48GDVIWvfvr0KWuIsR2Xz6hoC18h8Q4dd8+GHH8rnn3+uAsWwdetWOXToUL0fUOLAdvr06YbbunXrJCQkxPAjgM68Nm/KlCnSkDz22GPy/fffS+/evSUjI0N9XpCle6XQQOL9IsC8ceNGm8/F2d3Fixer59clfMbRqNsTPrMjR45UB2/YB6NGjZILFy6oeXiMjg4CedR0IWMBJxoQvMPJH5xQS0xMVPNwNhmdWXzPjh07ZtIe2JpXH9DRwfsYNGiQOgjFZxkH95XN2759u2oTcRCCEzzomOI94QRlVQ0fPly1B1u2bFGd8JpasGCB2j5rEHD/4YcfZODAgfLTTz+px1BQUKB+C8+fP6/ew7fffqsOaKq7nMrm2ZKcnKz2K34L0T6/8MIL6qCkNvaDrf2N9gpBKO03DO1mXe4HcjwPP/yw/O9//1NtJw788ZuKgCL8+OOPcu+996pgG9oYHPRqfUJb8+oDDiDxPhAEQT91woQJqk9Y2TwEDvGdw3tG+4MsK3xvEACpCiQ+4HVox3ASGv1/80BGVaFvhsC1NWgXEaBEoBV9XwS1Ae0N/m5IasC2LF++3GYwxNpyKpvXUPYD/j5oH5EMcPHiRZN5OI7B8ZjWhtrqd9bGfqDGKSoqyuTYEoFbnFQFtGvjxo1TxxzoX6HNxLFcZfPqA/qGxle5fvXVV+qxdmyEvg6CsDExMVKfkNhgvL/R/mpBTSR54DtnPN/Hx0caCsRCkECHE4qdO3dWba09rt7GbxT6nR06dFAnwkaMGCE7duyw+vz33ntPJcDUJRxbo/21p//ZeN9ICkGgHfGoJk1Pjdqnn36qnzp1quHxs88+q7/vvvvU/Xfeecdk3nPPPae/6667Kp1n7qOPPtL/7W9/U/eLior0TzzxhH7VqlX6tWvX6v/zn//oP/vsM/0dd9yh//rrr/WFhYX6V199VT1euXJlld8H1q+t4/z58/pBgwbpp02bpt+/f7+a9uSTT+offPBBfWlpqf76669Xt//7v//TL1q0yLCMlJQUfUhIiLp/4cIFfUxMjGHe//73P/28efP0Op1Ov23bNv3f//539frly5cbnvPjjz/q58+fr//www/1t956q1qXLbt27dI3a9ZMX1JSoh5jW7DNVbVgwQL93XffrX///ffV3+3FF180zLO2jYBt1F6H+z///LOafurUKat/Q0hISDB53KtXL/0vv/xi8bnYFu3vh/2Abdm7d6/N9/PNN9/ox48fb/M5WN+kSZMMj5OSktTffvbs2epvunHjRpO/xXvvvafe68KFCw2vwecOz73pppvUZ/HMmTMm68C+e/jhh/U33HCD+sxo6/3uu+8My8a+x+f6zjvv1H/77bdV2r/msG48T4P7+DtqsO34+1HT1b9/f/2SJUsM3xO0B9r3JDY2tsK8HTt2VDrPXJ8+fVRbA4cPH1btZFpamv6pp57Sb9q0Sf/MM8+oz9nRo0f1R44c0d9///36hx56SJ+YmFil95Cfn48IilqmJiMjQ19QUGBzHvTo0UP/0ksvmSzvgw8+0Ldo0cLQfr7xxhv6FStWVLodHTt21G/ZssXmc+6991713cf39quvvjJZh7Ozs/7aa69V8y9dumTyupycHL23t7f+3LlzhrbQx8dHn5WVpf/tt9/0rVu3NjwXvx3+/v6G92i8/baWY2teZfLy8kyehza/W7dudt8Ple1v48+aubrYD+R40GdA31HTpUsX/YYNG9T9IUOGVJi3evXqSueZGz16tOo3wOnTp1U/CZ/Lf/3rX/p169bpn3/+eTXtzz//VPPR35kzZ47hM1wVnp6eqg+mwfcgNze30nnDhw/XP/rooybLQp8kNDRUtb+APin6LZagT56ammp4vHXrVn3z5s2tbuc//vEP1Tbcfvvtqv9eXFxsWAe2E31YzE9OTjZ5HZ4XGBho6JPj+4zvdXx8vP7gwYOq7621Q9nZ2XovLy/1W2G+/baWY2teZepqP5j//i9dutTqZ81cXewHavzw94+MjNTv27dPPcZxUatWrdTxK+CYpG/fvpXOM/f777+rz6zm3Xff1X/yySf6EydOqH4kPsvoX+IYHtvw5Zdf6v/617+qY/yqwvq1dWCb0Ld6+umnDW01jqnQ5tn6DgKO39EXA7QtOL4H9NfQPqPPdPLkSXUchn7QF198YWh/0IdBfwXHjWjXjdteS/D9Qp/v4sWL6jGOKVu2bFnl94x+1D333KOOm3EcfM011xjmWdtG2Lx5s+F1+M17++231XQtzmHc7zaWmZlpsq9wvIubJdgeHOtq3nzzTf3ixYstPtf8mAF/+7lz51p8Ln4bjWMs+K3CPr/lllvUtqNfavy3MI53aPsAnzs8VztW37lzp8k6sO8Q+8GxPp6HPjl+oxHLMV42Yi9Y9ltvvWWyX6zt3+q+7y1btugHDBigb8qYGdzI4ZI67UwGLg/Ztm2bIaMIZ49wVlmD+5hW2TxbWZ3IYPP29pbx48erM2n/+Mc/VGYbzkiidszo0aPVGXVcbnHDDTeoy7WqAtu/adMmw5l1ZC8h207LNMX/eA4yp7QzdShJ8M9//lNlrdmCy7ZwdhI1iFasWKGylHDZFV6PS7yQuQTIasDlrMjYwPvTSm1Yg7ObOCtmfDnx4cOH1Rm7p556yuRyW3Nff/21PProo2obcGmycTkLZFVY20ZcloHH2utwKZ72d8Nl6ldffbXVdRpfQomzt8iEs3Yp4jXXXKOyHvEc7D/sE6zzSiELBmffNLfffrvKTsZ242/aokULw98CWT9YLzIPsT9wWb3xGV1cioRsTGQE4VJTwGcBl+UhSxn/Y572d8HlJeZ/Z3xu8XfAWeDK9q+5yr5DOGNbX9n2VDfwvUUWJz6P+Cz97W9/U58dZHfhMi7t84GMA2Qr4fNha54tyOScNWuWWgcy6JDFic8xSjPgCg9km6GNw3ca2Re4RLYq8B3q06ePvPbaa3LkyBEpKSmRwMBA8fDwsDkP31t8p8wzlvCdRhYI3iMgG87W5YDVgXYZ+xqZAciEeP/99w3rQDuM3yfMN788GVkz2G6tfUFbiAwDtNG49DArK0tlNQMyvbKzsw2ZLMbbb2s5tuZVBpf/+vv7Gx4j4wwZwvbeD1WBvzXafpQ4Ms4wrov9QI7nrbfeUu0ofq/79u2rPrvo/9VGHxbfK1wFh7YRn0v0NfEbj/YUN7ShaM9Q5gYZptddd12V3weuLsCl2uhfFBcXi6+vryGbzNo8ZLOiXTdvQ3G1H+ahrASgLbBWegffce3qtKq0Heijo21AFi36lbj8WlsH2nWtL4Z+vjGUskCmolYGCe0V+qho59GGYntxxZn2XBwHaBnexttvazm25lWmrvZDVeDzjHJKKCGlZXfW1X6gxg+lb5D1qR2foV1DH1E7JjVvB63NswZ9UPQdf//9d3UMiyxkZNLjah4s65tvvlF9C5Qowf/o42KbqgJtN0oHoj+F4z183nHVk/mxvK3voDV4Drb7wQcfVP00XLWGKzPRvuKKLsQDAMd2KIWBcgLYHhwb24JjS8Qb0Jc2PkZGu4xjT+wna9BGYztatmyprvrAsb8G7Z+1bdy1a5d67yjViNehvBdKFYAW57BWFgYxH2QvI8aCY1wcZ+LKX0vwe/fmm2+q+ArGskEsBJnklhiXQcBnBKVwrLWh5sfyuCodV6qPGTNGbbvWdml/C6wbx0hYv1biAX8XPBe//dh/OL45c+aMmoe4EvoDOObAsT6eh74trgLSPktYNtaLuA76p8jwRTmPyvZvdd93Zwc4lmfN4Ebu+PHjqjOJGlfokKHDiYYLae04wEWnU4P7mAa25lmCS5/RcCPYYBxkQEOLg0fty4ugnNbY4YuHH5Oq1KXFDw4Cxwgw4It+/fXXq47dvHnzVHABDS4aazSSaLDxo4BLXNFpQw0kS3UNcSCLwAm2CQFWdBZRkwmdcK0xwfvGJSwIfgIOBhD8rAw6vqgvgw6nBg0XfjTR2UdDhMYE83HJmDl0ElEKAwF8MA6a29pGBKBR5xnbaf46NKxVqTmMgxwsCycNrP1t0PihAcd60Bjj/dgDfsCMO9f4wcVnCJ0BLXigwY8KarMBOkY4aEQNS1xetGrVKvWZwPJwAIJOMoLGeA5+DCqrDYzPizaIHT7bKEOCz7et/Wuusu8Q3mdjGfSAagYnH9DRQAADwVJ0KtFGou4UvjeWPh/4zFqbZ2uASZReQKcHnSYNPsP4LONSQXSy0C6i3UEQA/XmqgpBEZSuQCcNJ07QWcRvCd6btXn47qI9Nj4ABwSQ8X60UhLWatHXBNoIdPjQIUQQHW3/Aw88oNaBx6iVh/VX9l013uc4MMF7QucVB19paWmqs42AsPn221oOOqrW5lUHgvw4aNBOjtpzP1QGB2MoIYV9gAMI/IZrdfXqej+QY8BvOfpMaENxIIgyJzjYx2XT+A5aaydtzbO2HrShKL9gXicbB4qA9huPEbxA/xH9MGxbVU6q4GAXJ2bQ/8WBMvo0GPsCy7A2DwETHHyGhYWZLEtrV7U2VKu/WRl8X7Fc1MO0Br8faNNxII3fDbQdKEmAdaDNwIG5pdrLtr7zaI+wD9EHw8lD9KmwDK0NNd5+W8uxNa86anM/VOaZZ55R7x9/O/xu4jOH3+/62A/UOOE313iMHkvHGjgGRdtka56ldks7/kMJKFzmrwWR0d4gCIzH+A1HiRItSQnJBUg0Q2CxMjiphuNHPB/HZTi+w/E9griA41ocY9n6DlqC7zP6REjcwToQpMX3VLucH31uHCdr9ZDRJpnXBLa1v/G91aA9Ro1jtM2IseB4EIFyS8lWKB+ApDgkEQH69tpJPOw/a9uIk+1IRNKCuMavw98AgV5bEPtAsBNBcewbxH0slV/EiXn8ruGYAO8H/cuq1B5HiR30h639zS0dy+M4HQFf/P2NoR1FApyWyIDlIm6kjZOCvytej+ONzZs3q4QvfEZwQk0bj8gaxFcQT9E+wzgOQmKirf1b3fft7e2tvlPYf011DCAGgxs5BBSRHaw1RDgDhS8ZgsE424FGXIP7WufG1jxL0CDixwWdZGPGZ9LQ6TUODGiZD1WBBhMdJTQECMyhcUODhTM06NihcUHDgaAkGknURcIZTATCrQXckJmAHxcsS/tRxBl3dFqNM9WMB/Ko6iBNOGBB0MX4+QhSag04Co7jgBoHHpbO2GF/o8HTGN+3tY0IgBsHcI1fVxVowBE8QvCjsjqOCL7jJAMyna0NpFFd+JHVBi8CHCAh+I4gLuahAdfOyJm/T62+JbYb2Wc4i4gTIGjgtc8AOuFVGYDKuF4VPqc4M17d/VvZdwh//6ZccN7RIViAkxVoG7UALTK/EJBFRgE6EPhMaPO0zwc+s9bmWYMMB2R8mJ8w0dpfdB7RXmqPq9P2ArYJbSpuyEjCiRgcDKBjZG0e2gV0jPD+jTt/CFDi+2i+rVcKmbpotxD0RPY1Tj6i/a8KfA/N6+Ma73PU2MMALth2LBt/F0snymwtB/vC1jqqAkEjBN3xu2Wt7biS/VAZ44wRnKjs0qWL6mibd4Brez+Q48AJCBzgI5AIyCDHyRAcYKM/i88OAsOA+1pbY2ueJfhOoX6r+cl54z4s2mXtMQIiOHhHMkFVgsFofxHwwA0HnjgwR78GAzZam4e68WirETQxroOI9hP9wOq0oQiqoL+GxAfjE4bG0CfByS8kSWh1i5HUUBX4zuPEO7ZfG5TN+HuN4An667iaDH1z9I2ttaHWllPZOhrCfqiMlvUICMCgX4t+t3nN0dreD9Q4IbiH42C0gRp8HhBc1eCzgGNttEu25lmCYx2c8EXMwPjqV3y2tMf4rJof21dnPAftSl8kSOD4F+0fkpWQHKUN7ljd7yAGlEOSmBZARPuIE0/GMQnj71hVj+VxdRvWbRz8w3KMg7F4jEC5pWAw9jeyfo2PGbWgo61txP40Hkjd+HVVjZlo24jfQiRoWBuLB7976JfhuLey42ME5XFVLn6DEFi1Bu0aPkea559/XiXD4aQufjMRd9GS04x/B5CkgvYQxxK4EhcxLFyJhr8rPpvGx/LWMphtHctrxz3V3b96G+8bn1VcbdxUA8HQdN+Zg8BZQG0gCu1AURtxE8E8NKAI4moDbmiX39maZwmej8YGlyQgEFcbMAAFGlz8aOB9oTOOyxBwCSzmAX5McGYJBwoYlMPWmXIsAz9I+NHTzszj4BmvQSOq3WqSuWZ+5tZSoAg/ejgrZwkOsnFwAujwGQ+eZ2sbccmN9lysw1b2mDlkaWDf4aadPLAGnwv88GpnYxGMsgcE/LVyDYAfJpwxRBAG69MGP9TOIGuXKWNfaQd6OCGAs8c4a4jPrDZgF+CAEp/rmqrO/sV3AoE//IjghvvG3yEcGNm70D01HGif0MnV2l98XtD509pfdETQrgKueECHHYOwVTbPEgTk0IHCZx5np+0JHTfjTjjOziMogg6QrXloX3HSEZfFaWVa0JahbUHn1/gkmz3g0kd0apHBgROgWJd5poS2HeZwYIDt1jLFcIIRHTvjwBAyGtCRRecU268ddFR1OVVZhy34jcKBEzIYbWV1X8l+qA5c4ojPsqUOcG3uB3LcPix+R3HfuA+rtZPIHMJnSjvAszXPElxxhb4lri7S+r32hL6rNoAdAng4MEU7aWse7mN7EDDWDmLRvuOEEPoysbGxVVo32gwcUONSbuNLd83hRDyCPDhoR8KC+XfbVtuBgAO+2xhcDZDhjN8u41Jj6Lsi2QAH02ijLAVkbC2nKuuo7/1QHTixgWXhVpf7gRovBMgQ1DNOwEG7hgCxFpA1Pl63Nc8S9MtwhRk+99U5fqwOHK/jOArBN/SrtPYaAUMEgvF9qOw7aOkqPJw0xPO1tgbxDlwFpR0n12QgZmTvI/lKO+lirS9UlWN5ML5vaxuNjzVBK1VYFcgC1q66AOxL86tLjCHIiWxwnCTQruS2BL89SPLAsQbacOMSmOYQ5MZJTO14BMFSxAuwr3BiULtCXIvbaLEavGetpAaO5dFe42pKHEsgDqDB7x+SI2o6KGx19q+ukvftEMfy9V20mK4MCmyj0PzAgQP148aN0wcEBOh//fVXNQ+FtDEQGwbWwP8o5K4VYbc1z9YAchgYoX379mqgIuPpgCLxxoOgYRA2FEwHFEJHAXBbg7KhED4+ko899phh2ssvv6ymaQOdHT9+XL3HCRMmqAHQevfurdZjawA5DBTSvXt3VcAeheGx/Xjdddddp7ZJGwDin//8p7pVBu89KCjIMLiH5t///rdaHorHY39igBNrA/j88ccfalvxN8O2oeC/tu9sbSMKrAcHB6tBVzB4Ewb8QbH/qgwgh/2EdWoD8OG2fv16i89FgX4MAggYxAIDccTFxVktvo5locA6Pou4b23QNfz927VrpwaOA3x+8PwZM2bow8PD1eACgL8D9gne49ixY9VgKtpgCi+88II+KipKDYDYoUMHNXiCNhASCtLjMbYFy9UGkEPB+ccff9zi3/n11183zLO1f81hkJSuXbuqvxNueL7x3xvbf+jQIat/D2r8MGAB2qMpU6boO3XqpP7mWruAgQwxD5/f6OhoNaibxtY8c9qgXvjuYBAKDKaA9tt8sK+IiAjDIJGY7+LiYpiHQWsweI0leC4GcGjbtq36TmFwO3zf0Q7Zmqe1uYMHD1bTJk+erG/Tpo36HmgDf1RlADlsF76rfn5+avAd3LcEvyH43o8cOVKtE985bSASQFuqfe8ttbv4LcKgPPhuo/3+/PPPDfMweAped9VVV6nB/NDGW9t+W8uxNc/WfsD+xN9r6NChhrbZ+LfVnvvB2v7W2nHcxowZowZUwcCr9t4PRMYwOBE+a2g/MGgiflO1wQbxm4/PDz6nGNAHA7tobM0zZzyo1yOPPKLaawxGYz7YFwZVNP7uY9AuDPYG+OzjO2ANBkFCvw/L7tmzp+rPaL//tubhvWq/AxhcF30abAf6MsbfWWsDyGHQNA8PD8N3Hre//OUvFp+LQeu0vumIESPUbwjaaw36m5hmbeA0DMiE3y18r9GXxEDUGvSx8Doci+D97dmzx+r221qOrXkNZT9gcCTMw/ZpbTbaWvQJtXVj+/G5Nh68yV77gZombcA1bSBtYzi2Q98Ev81o94wH9LY1z9oAcseOHVNtDQaDNx9YDp9R40HQMPCWdiylrc/WoGzp6emqP4O+iAbtJ47ltYG5KvsOWhpADn3riRMnqhgBvm/o9+B4ctasWeo7h8HJqjOYO5aH/WXc5gPiDVgeBuLFNmE7z549a3EZ2C70j9Hu4YZ4irbvbG0j+ls4VkUfDq/B/r/xxhurNIAcjndxvIF90a9fP/XbceDAAYvPxSCAaBPRl8fy0EfH4JqW4O/s5uZmGIAYN1t9N/yeYQBW4/Yf7xPvC31q7W+BbcVvO37f0C/86aef1DwMZIc2DscW+M3D8QUGXtc+H9juzp07G7YHv9kY2F4bqN7874zfcm2erf1b3fd91113VRhovqlxwj/1HZCmK4OzGdu3b1dp9zgLZ3yGCFlDOGuIkgm4JMP4Mgpb88zPbuOSJe0MHwppI50fZ3eMp+PsNc6o4EwZoE4OznAjPR9ZG8gsxqVb1mD7UVYBZw61ywpwyQwugcUlHFpdJJw9wiW9qHmEzDxkhiLjFK/H8nFpglYiQqsljCwMnBnSLqPAGSksG2eEevXqpTJUcYk3VJaNgTNfyADEmU7zs3UYdAyX52D7cebMFlxegveB/YXacTgzqu07vBdL2wjIEMCZNmTK4qwaBkDBWTX8LZBNa61uMDK0jLPIQbucz/zvgLpG2HdabSF8vpDtZSkzAdtuPrgAnqe9F3PIvMPlJchsQxYv/lZYD96jdlkkziAD6lPjUiPUYzb+XKMWNbKBMB2DFWB9ODMJyLDBfOwnfGZQfB7LQDYQnmf+d9ZqXWvvzdr+tQSv02o74zukZYDg7zp37lx1ZpOaNlwpgc8Uzrqj7TI+q4zPEtoFXMqEz6oxW/OMoeYg5iOrDT/XyJDAWXOUZ9CmA75LyPrH5WN4HjJEtAGQkJGAzHtbNcVxJQPadmTEoj01vszQ1jzA9wVtHy7ZxnzjLA+0O/gdsJaphd8JbdAIjbV6aWg3kEWN7BbsN/zmaJfgoRaeVnsM31dLl0kigwKvwXffeHvw+4TfCOxLZNoY11SztP3WlmNrHrJEUI7C0qXsyJowv/oC24C6lfbeD9b2t9aO41JRZMGgXI9xm2uv/UBkDqUFcMUQsuGQgWP8mUVfE6XD8Nkzz86xNc8YfqPxvdNKryAzDv1H9K/Mp+P7r2Um42offAeRNYbSA2jbkEFkDbLAkEWEAb+0DLiqzAO8f/S18V4w3zhTDd9Z9M8t9U3RfzK/Ggq/QchGswQZZehT47JwlCLDsvG7ofX90HagfUGf29IxAX4L0OfCdxrZvxq8Dn1z/A2xD43rmFrafmvLsTUPl2Pj6jFLv5d1uR+wbeg3GkPmHX53cQwDaEPxO62VMbHnfqCmCb/BaIPwmbU0gDk+P/iO4Xtgnglqa54GfRx8nlDqS2uTcKyC7yvaJm06jhPRn9PKH6CviTgDjtHQb0XmMbJ+bQ2uiH4qjue0gcdxXIZpuMpVu2rM1ncQz8WVyOgH4XgUx3HIJsVxHDLmcbyF94ntQB8c8Qwcd6PtRLuOPk5lV/3i9wP9KPMxh3C8iPYY/VhkL1vq85r/3fA7hOeij4zvrXHpCEvbCChJgPXjdSiRiLYBmc9oR3BFHn57rNX3RZ8Rxw/4G+A43toYEejToS+nlf1ANi9iD+bxC8BxjHZ8rEHbY20QObxnxHVwVZvW/uNvhKxc7fgffyu8N2Rg47OGecblF7E9+N3D5wTbhd8N/DYDYh84lkf/APdRGhJ/M7S9+Aya/53x2dTqVNvav9V53xkZGapvjc8m3ltTxWAw1Ql80dDJxY1qDj/SKJGBhhH7FB1ONMI1GTW+vuAHEYF57UffEi0YrP3f2PYvOhIIDtr7UnmimsAov+b13qnu4KQROsLGBwhE1HiwDa1f6JMhecW4Ji8R1S0E4BD8rMrYLGQbSl2ivBwC70gwQ9KV8cmjxgAnL1Dz2VqZDy0YrJW8aWz79/z58yrwjgGmmzIGg4kaES2DDA0vAo04Y2mrrk9jVdUsbXtzlP1LREREREREdQsD0SMLGElyONa0lWndWFU1S7s2OML+tRcGg4mIiIiIiIiIiIgcgO3hG4mIiIiIiIiIiIioSWAwmIiIiIiIiIiIiMgBMBhMRERERERERERE5AAYDCYiIiIiIiIiIiJyAAwGX4YRB7Ozs9X/RERUPWxDiYhqjm0oERHbUCKiusJg8GU5OTkSEBCg/iciouphG0pEVHNsQ4mI2IYSEdUVBoOJiIiIiIiIiIiIHACDwUREREREREREREQOgMFgIiIiIiIiIiIiIgfAYDARERERERERERGRA2AwmIiIiIiIiIiIiMgBMBhMRERERERERERE5AAYDCYiIiIiIiIiIiJyAPUaDM7Pz5cvv/xSBgwYIIGBgfLbb79ZfN7nn38uPXr0kMjISBk7dqzs3bu3Rs8hIiIiIiIiIiIiclT1Ggx+/vnnZcOGDfLoo49KVlaWlJSUVHjO999/L/fcc496ztatW6Vt27YyatQoSUhIqNZziIiIiIiIiIiIiByZk16v19fXyrFqJycniYuLk+bNm6vA8IgRI0ye0717dxk0aJB8/PHH6nFpaanExMTI3XffLS+88EKVn1OZ7OxsCQgIUEFpf39/u79XIqKmjG0oERHbUCKi+sB+KBFRI8oMRiDYlszMTDlw4ICMHj3aMM3FxUVl/WolJaryHCIiIiIiIiIiIiJH5yoNWHx8vPo/IiLCZHp4eLj88ccfVX6OJYWFhepmfDYRdDqduhEROSpn58rPE7INJSKqeTvKNpSIiG0oEVF9Hc836GCwtTfi6uqqSkxU9znG5s2bJ3Pnzq0wPTk5QfLzc694m4mIGquoqGaVPodtKBFRzdtRtqFERGxDiYjq63i+XmsGa6zVDE5NTZWwsDBZtGiRTJ8+3TD9lltukTNnzsiWLVuq9JyqZmRgGzIyMlgzmIgcWk0zg9mGEhFVrR1lG0pE9SkjI10OHjygxsvBuDmxsd0kKCi4wfxR2IYSUUOWmpYmv2w5LgmZBRIV6CnThnaQ0JAQaSgafWZwaGiotGnTRgV0jQO9mzdvllmzZlX5OZZ4eHiom6WdVpUdR0TkyNiGEhGxDSWixufAgf2yevUKk2m7du2QCRMmSmxsd2kM2A8lovry3xUH5OOtxZKnKz+B9p89F+T/BifKHRO7NZo/TIOPej744IPy2WefydatW6WoqEhdVpeYmCh/+9vfqvUcIiIiIiIiIkfOCEYgGBcHm99WrVqh5hMROTK9Xi8lJSVSUJAvubm5kpmZoSoS4LZ4R7y8tcVF8nSeJq/BY0zH/MaiXjODv/vuO7n33nsNtX0nT56sav0+8cQT6gZz5sxRO33ixIly6dIladWqlSxevFjat29vWE5VnkNERERERETkaHC8jUDvunVrbY6rg6zhYcPKyzYSEdUXtFU6nU4FZrVbaWmJFBeXiK+vr/j4+BieW1hYIMeOHVXPwXw8z/h1xq8fO3aCer3m4MH9snnzJsNr8HqdOIlOXKRU7yyl4iylehfx8guUJcm9L+fUOpltLR7r5Y1V6TKlb5S4OJvPb3jqtWYwsnjz8vIqTPf09FQ3Y9jMgoIC8fLysrq8qjzHGtS7RL0k1E3y9/ev9uuJiBwZ21AiIrahRNRwIKPt/Pmzcu4cbuckJyfb5vOdnJykY8dOMmVKeenFxoL9UGoINWQXbz4qCRkFEhXkKdOHdWpQNWSvlLWgLP6Pioo2ee7Fi3GSnJxkNRirBVzDw8Nl8OChJvG8/333raSkZUhRiU4Ki/VSondSgVjd5YBsWWDWWbp27y3NWrSRwhK9FJfoJTMnT37btk1KxUV0KoBrGsgtu182LzQyRvTiUvbaUr3kXCqU3PxCk3VUDPZW3Rd3tZB+bcoD1Q1VvWYGu7u7q1tV4MepsiBvVZ5DRERERERE1BQh4erbb7+W1NSUar82ICCwVraJyNFqyH6y+5z83+B4u9eQRcC0tLRUSkqKKwRaEQsz/g7jufv2/WnxuVowV3s8YOAQCQqNVEHYohK9nDkfJ2vXrZOiEpHCEp2U6BCULQ+yGgdOhwwbrV6DGwKsp88lSGJyqiEIW/ZcVykVd5NlOLl6iNum41JUrJei0rLX6vV9qrQfft0mItvMSzLEVum18XHFIoKbBoFf02TUK5GSXSKNQYMeQI6IiIiIyBwud8blzFlZmerAp1u37hIUVH4QRkTU1CEglJAQL8XFRdK6dVvDdCRbYZ4xlGJs1qy5hIWFy65dO9XlzJagLSWiqtNqyIrgZl5DViQkJF6m94+WlJRkuXDhvFkJg2IpLCqVguISKSgqlcJinbh6eMuAQSMMQVkESJHxejEhWQVMi0vFJMvVOAM2ODRSwqOaS1GxzhBcPX4yu2y+eg6CsZ4VsmxRDkG/J0tEcDM2uEr7YOcq8xNPKMFQXobBqiLcTNuquuTh6iTuRjcPV2ej+/jf9HFWXqlsOX6p0uWG+TeOMGvj2EoiIiIioss1LTEAkrGdO7fLhAkTJTaWgQwiapqQ5Ydxcs6dO6NKP1y4cEEFgkNDw0yCwdC6dWvx9PSQli1bS8uWrSQ6OkYFhCE0NFQNFmcObShPqhFZV1xcLElJSepEdGZmpsSlZMvru1Aiwd1qDdnnfsmUr7bnS+6lAsm+hECuu5SKlyGQq7dUjmDnabMJzS7fKhGHW6bZxPAG9yd1dxVxd7kcfHUzDcIagrIuTmqeeh7+vzxN3TfMcy5/bCmga5hXNq08+Ossbi5llQWqo1Snl7GvnZSkLGQVW3qtXiID3KRPK29pDBgMJiIiIqJGkxGMQLClIS8Q3IiJacZgBhE1GaiFi7q/Z8+W1f7Ny6uYlYZyEKgPbDwg0qhRY60GOnDSDG0lr64gMoVByDIzs1SwF7cI1Jb1Cpe49CK5kF4sJ+OzZeufJyVH5yO5pf5SLJXVBEZpBZHjiUiBRR3a+q0jiwCouwv+LwuMul0OkHq4IajqIp5uFYOwZc8tD6aWvcY8uGopoFsxsxb/Y3nVDcI2FC7OTvLk5Ah56NuLFq+tcBIneWJyRKMYPA4YDCYiIiKiRgHBi8rmDxs2os62h4iotpw/f07mz//O6nxvbx+V9Yubm5ubybzKgi3IAGZbSY4qLu6COomSlZUlCanZcj61QOKzSiW9wF0FenNKvdX/l3TZopccs1ebDpZWFS7OIp6uTuLqrFNBVhWUNQuilgVkncUTQVl3F0MGq4eVIKwWyNWWYf64KQVhG5Kxsf7y9myRecuSJCmrvDZwZICrCgRjfmPBYDARERERNQrI1LmS+UREDQnqhsbHX1RZv9HR0dK2bXvDvMjIKHF2dhadTqceI+DbvHmLywHg1qrcA4M7ROVw1dClS5dUCQctu1enF2nTtb9cSCuSuPRiuZBeJNv+vCCJOSK5umAp1EdWexe6OOkl3M9J/Lxc5HhS5TVvP7ujhfRrU79ZwWQ/Y2P9ZVQXP9lzNk8NFocawSgN0VgygjUMBhMRERFRo1DZSPeVzSciqu9gVXJykgr+4oYMRQSEoXPnLibBYAwE17NnL/H09FLB36ioKHFxMR2kisiRy0adPHlCBXxT0rPlXGqhJGbrJLPIsyy793KGb67OR3TLTpq9OqjS5Xu76aVZkKu0jvCWZsHu0jzYTZrj/xA3ifB3E1cXpyZXQ5aqDoHfxh7gZzCYiIiIiBp8AAUZcBjpHoPFWYP5REQNre7vmTOnVPAXpR/y8/MtPg/ztbZOM3r0uFrZJgSxGntWGzVNpaWlkp2Nur1Zhgxf1PHt1GOgXBI/ldmLDN9DZ1PlyLliyS4NlwJ9i2qvx0n0EurrpAK8LcM8pWWohyHoi/8DvV0croYsORYGg4mIiIiowR4U/vbbZjVo0tVXT1Z1LjHiPQaLM4fpmE9E1JAcPXpENm1ab3Gen5+foe5vixat6qTsw9qD2RXqXUYEuKqgVmOqd0mNH05+bN++TTIzMyQtI1vi0gslIVtfVrO31McowzdUSreniwhuxmwP4ObhKhIT6CItw7ykRYi7NNOye4PdJDrIXdXSvVJNqYYsORYGg4mIiIiowcnIyJDly3+RhIQE9RiBkq5dYyU2trvExDRTg8UhYwilIZARzEAwEdWH4uJiVe5BK/0wdux4iY6OMcxHoFfj4eEhzZu3VNNatWql2q26rPuLQLClLMbkrBI1HUEtBq/oShUWFl6u2Wuc3ZspvsGREt2+r8SlF8mF9GL1//YDIlnFUXJJ18ZKqQXbgr2dVJC3VZjn5TIO5UHfEF+XOvl+NZUasuRYGAwmIiIiogbl8OFDsnbtKikqKlKPMYgSDi41CKAMGzaiHreQiBwVBnRLTEwwlH24eDFOXcWgKRsMrjwYHB4eLsOGjZQWLVpIRESkas/qA0pDIHvR0uXsmIaw1SvLklRQi0Esqo5jx46qW0ZmhlxML5KUPJfLmb1ahq+f5OgipVjvJrL2rNmrbV/R4+YiEh3gIi1CPS9n95bV7UWwNybITbzc6+f71BRryJJjYTCYiIiIiBoEBH/XrVsjBw8eMEwLDAySKVOmSWRkVL1uGxE5tsOHD8qxY8fkwoVzJienLNUINobMxP79B0h9KCjWyZmUIjmdXChbjueaXMZuKSCcmFWishsZ1HJsKN9w6dKly9m9ZVm9yPLF/eSMXBk5abYkZOtU7d4LaUVy8HShXEhvJrm69qKX6gdnA7zKave2UHV73aRF8OXs3hB3CfdzFWdm2BI1nGBwcXGRpKWV1WwJCQkWNzd3e24XERERETmQpKREWbr0FzVCuKZLl1gZO3acuLt71Ou2EZFjyc/PEy8vb5NpZ8+elZMnj1d4LkrVaGUfUALC29v0dXUhK79UBXxPJxfJ6ZRCw/2LmcWit5QKbAMuc6emz3ywQpzEwBU5GKwtIaNAMoo8Ltfr1TJ8AyVHFyOFeg/55KMLZktDLMh6PAix3CiV3etRoZQD/vfzrHywNiKqx2AwBu9YsmSJrFy5Qvbt2yclJWU/FG5ubtKjRw+5+uqJMmXKFPH2Zno8EREREVXtgHTPnl2yefNGw6XWSDJAELhr127chURU64qKCuXChfOGur9paWkyZ87fxcPD0/AcBHwPHTogXl5eqoZ52cBvLdXVC3XVViZnl8jpy5m+pxDwvXw/Lbe8TMWVQr1Tavzwe4oAr5bda1y/Ny0zW1p1GSQB0R3lQlpZ7d6zKQVy8HQrFfjVSfWDsz7uTirIq26XB2nTgr5RAW7i6sL6uUQNSZVb+gUL5st7770roaFhMnz4cPnLX26VkJCy0RvxY4lBPH744Xt5//335IEHHpRrr72uNrebiIiIiJqIs2fPGALBqKmJshAcEI6Iagvam4SEeEPwF/dRC9jY+fPnpX37DobHbdu2k1tu+auEh0fU6qBUJaV6FZxDoBcBX63MAx5fKjTdRlu83Z2lTbi7tAnzUP+3DnWXF39JVIFjS8nCeEcRAWUDX1HDh5MDKFfi6Vl+wgLWrl0tp06dkpTsQsku8SrL7jVk+IZITmkLydd7icTj2XFmS/Wzuj71+fB3keYhHqpmr6rdG1z2f4tgNwnwrpvB2oiojoPBv/76q3zwwYfSvXsPi/PHjBkjDz30sOzfv0/ef/99BoOJiIiIqFI4eLz66sny1VefS5cuXWXo0OHi4sJLRonI/hDwXbz4JxXoRdlDa21SZGRkhcAWgm6enpG1Us/3tNH/51KLpLi06rUdQnxdDAFfw//hHhLh71rhPWCpD317UQX2jNegPeuJyREcPM4OUO4IyXLIwkUZkW7dutfoBCfq6JfX7DXN8M3IypZSjxAZOHqWOnlwIb0sw/fQ2QhJzYuWkhpUBPVwdTLK6L2c3Xt5wLboQDfxcGsYg7UR0ZVz0uOUEqlLKAICAlTj6u/vzz1CRFQNbEOJqHqXrmZVODAuKCiokOHkKNiGEtXO9wq3Zs2amUz/5psvJDEx0WRacHDw5bIPraV58xZ2bYvsUc8XMd2YQDdDoLd1mBb49ZBA7+qdPFt7MFvmLUsyGUwuMsBVBYLHxjbO4+CG1IYiCLxy1QpJKgmRfJ2neDkXSIRrmky8eqLExnav8HuYk5Otymy6u5fX3D158oSsXr1CMnKLL2f1eptl+PpIns5L9IYwvlTr5IEq5RBUXsZBK+sQ6lfxBAIRNU1XXBAoLi5O9u37U12m0KNHT2nevLl9toyIiIiImhRkMy1b9os6+L311jtMBlpy1EAwEdlHQUG+yvjVSj8gO9PfP0DuvvsekwAX6v3m5ORcDv62Uo+vNIBor3q+ri4irUI9pA2CveHl/7cKdRcvd/tkZSLgO6qLn+w5m6cGi0ONYJSGcMEoX3RF8Jn7ZMle2XFpnOShFMNl3k75cv6XP2RmcrKqT42gtcr4zcqW3FIv6T1kkhS7h0hcerFcQImQRJ2cSx0hRXrrg7LZ+gw1CzIdoK3F5aAvsn1RPoSI6Ioyg1FH+M033zCUjkCJiEce+Ydcd931jW7PNqSziUREjQ3bUCKqzNGjR2T16pXqQBhQi3P69Gu449iGEtUIBjOPj794Ofh7RmX7Wjq0vfPOv5lciVBcXCyurjXLgEQ934sZxZeDvZezfS/X9c29gnq+bS8HfhGs40Bbjbcf+u8Fv8t/9gZcfmT8+Sr7XLZ1vyCuTiWGDN9LarC26gdnA7ycy2r1GmX2qv9D3FV5EAb2iciumcE4g+rnV15U/IMP3pf//e87ad++vXp84sQJueuuOxplMJiIiIiI7A81Dzds+FUlDWhQQ7F//4Hc3URUI6mpKfLNN1+qgLAlzs7OEhUVrTJ/3dzcTOaZP24o9XypcSvV6WX+IZ/Lj8z/tmWPTxW1qNKykKQdFYgg7+WB2kLKSzngsb8X6+oTUR0Gg2fNmin/+MdjMnbsWPUYdW1wKYQG96vy40pERERETV9ycpIsXfqLpKenGaZ17txFxo6dIB4eHvW6bUTU8GVmZqjMXyQktWnTzjAdmb5OTqYZlaGhYYbSDyhd6O7uUWf1fDG4lqG0Q3jN6/lS44WyG1lFbtXKDjcP8mr/Rwe5iZsLTxYQUQMJBn/44cfy/PP/lGXLlsrTTz8jTzzxpDz44AMSEhKi5qelpcmLL75UW9tKRERERI0ALtXeu3ePbNy4Xg2QA0gYGDNmnHTt2o0ZcURkUV5enpw/X1bzFzdc9g9t2rQ1CQa7uLioE0s6Xamh7q+vr2+jr+dLjRfqL1fF/WNC5fr+QRLk48LfQiJqHMHgtm3bytdffyPz58+Xm266Qe6++2+yZs2vcuLEcTW/Q4eOVn+EiYiIiMgxLF++RI4cOWx4HB4eIVOmTJPg4LIEAiIirX5vXNwFQ/AXVxNYcuHCeXViCUFgzfjxV5s8h/V8qT5hIL6q6NPaW4J9qxWGISKyu2q3QqhtdMMNN8jIkSPlpZdelOXLl8nzz78grVu3tv/WEREREVGj07Jla0MwuE+fvjJs2Ag1YBMRkbHDhw/KmjWrLO4UBH5jYpoZSj+gDrBxPd8z2gBul/8/y3q+VI/6tPKWiABXSc4quTxcnCkUfcB8PI+IqL5Vu1eenJwsBw8eUPefffafsnfvH/J//3e3zJx5jdx++x2sGUxERETk4GJju0lSUqK0bt1G2rYtv7SbiBwLSjRgXJmzZ8syf6+6qq80b14+iBaCvMYiIiKlRYuWarp/SLScz9CpQO+WvQj4XmA9X2qwXJyd5MnJEfLQtxdV4Nc4IKxV/31icoR6HhFRowoG//LLYvnXv15U5SAA5SGeeeY5+fHHn+TNN9+Q6667VubOnSvdu/eore0lIiIiogYENT1PnjyuMoCNryRDfWAicjy5ubmGsg+o/5uTk2OYFxwcbBIMDggIlA7dB0mhe7hccgqSs5l6WX+iSE5vRT3fM9Wu59sadXwv1/Jty3q+VMfGxvrL27NF5i1LkqSs8hrCyAhGIBjziYgaXTD4nXfeli+++EpiY2PV44MHD8oDD9wvU6dOlblzX5CdO3fK008/LUuXLqut7SUiIiKiBuLYsaOyevVKKSwsED8/f0PCQG0r1enVyO0YsAd1GnHZLbOtiOoPavqeOHFMBYBTU1MrzNfpnSRX5y2bjl2SE5JaVt4huVCVe8gtDL/8rIxK1+Pt7ixtwhHw9VD/I+CL4G+zYHdxdWHGJdU/BHxHdfHjbxQRNZ1gMOo0YcRWDYr4I/ND069fP1m48Cf7biERERERNbhBn9av/1X27//TMG379m3Svn2HWh8dfe3BbItZV7g8l1lXRLV/gkWn0xnq92qOHz8qf/yxR0r0zpJd6i+ZpX6SVeon2Xp/lfGbXuQpJTonkSwROZNS6faE+LoYAr6G/8M9JMLftdbbGKIrhe9OvzY+3JFE1DSCwQ8//Ijceecd0qpVWW0n1H56/vm5Js/x8PCw7xYSERERUYORkpIiy5YtNsn+69ixs4wbN6FOAsGox2g+OA8G7MF0XJ7LgDBR9b9XLy1JkJQcnWFamJ+zPD01Sn2fUPc3NTXFUPrhwoULct3sOyUpz80wgNvBsy3kWGaw5OgwOFbV2gE0F9GBboayDuWBXw8J9Hbhn5GIiKiWOOnx614N6enpcvjwIXW/S5euqu5TU5CdnS0BAQGq7p2/P2v5EBGxDSUiY+gy/vnnXtm4cZ2UlJRl5bq5ucmoUWOlW7futR4IRubi2NdOmmQEWxqpfc1j7RpdyQj2Q6k+A8F//zbu8iPj703ZIeLMtklSnHVRkvPcJLPUV2X7Iuu3QO9ZrXq+LUMuB3xZz5dqAdtQIqJaygy+dOmS+Pj4qODvkCFDq/RcIiIiImr88vPzZfXqFWrwYE1YWLhMmTJNQkJC62QbcAm7tUCwFrpKzCpRz+PluURVO8GCjOAy5idQ8FgvP5+KFBHcpNr1fLX/m7OeLxERUeMMBk+ePFFuvfU2mTFjhhr11VrW8OLFi+Sbb76WDRs22XM7iYiIiKierFu3xiQQ3Lt3Hxk+fJS4ular4tgVOZlUWKXnoeYpEVVux8lLl0tDWMuktzw92MelbOA21vMlIiJqlKrcg//008/ktddek3ff/bf07NlLunTpIiEhIeqSwbS0VDl48KDs27dP+vXrr55LRERERE3D8OEj5cyZ0+r+1VdPlnbt2tfZujPzSuWzTanyv9/Sq/R8DH5FRJYVl5TK8u1n5Jc96fJHEur7Vl6bd2gHHxkT68d6vkRERE1ElXvL6PT/5z+fyrFjx2TlyhWqZlxiYqI6YxwZGaEyRJ555jlp377uDg6IiIiIyP5wst+4BrCfn79Mn36NBAYGiZ+fX53s8rwinfxva7p8vjlNcgrKB7ayRqsZ3KcVAlxEpCkt1cm6vRfk5x1JsjveXfJ1GPC76t/j24eHsPQKERFRE1Lt1ImOHTuqGxERERE1PSgHsX37VrnuuhvFw6N8kKjmzVvUyfqLSvSycFeGfLw+VdJySw3T3V2dZHB7H9lwJPdyNdNyWtj6ickRjW7wOKLaoNPpZNuhePlxW4LsuOAqOaWeFQLALlIiLi4uUqS+Zpa+N3oJ93PhCRYiIqImhtfREREREZEUFxfLxo3r5c8//1B7Y82aVTJ58jSTDOHapNPpZcW+bHlvbYrEZRQbpiO2O6NPgNwzOkyiAt1k7cFsmbcsyWQwOWQEIxA8Ntaff0lyaKeTC2XFviyZ/1ucpBd5iYivyXwXKZVOQZfk6h7+cs2QDrLjTKH8/du4y6dXjL/rZadbnpoaxRMsRERETQyDwUREREQOLjU1VZYuXSypqSkmmYWlpaW1PkgcSlJsPpYr76xOkeOJpoPEjY31kwfGhkmbcA+jaf4yqouf7DmbpwaLQ41glIZgRjA5qpPx2bLxRJE6mXIsQfsOIRBcxkl00s4/V8Z29ZHrh7eV0IDyeWNjPeSd2c3kpSUJlweTK4OMYASCeYKFiIio6WEwmIiIiMhBIRC7f/8+Wb9+rZSUlGXaIvg7atQY6d69Z61nBSOg+87qZPnjbL7J9IHtfOTBcWHSrXl50MoYAr/92vjU6rYRNWRnE7Lk+01nZMPxIrmYX7H+L765LXxyZHQnT7lxRGuJDrVeI5gnWIiIiBwLg8FEREREDqigoEDWrFkpx44dNUwLDQ2TKVOmqf9r07GEAvn36hTZdCzXZHrXGE95aEK4CgYTkanE9Fz5fuNp+fVIgZzL9RW9IGO+PGseujXzlIk9AmR8Nz+JCHCr8i7kCRYiIiLHwWAwERERkYO5eDFOli1bItnZWYZpPXv2khEjRoubW9UDSNV1Ib1I3l+bIsv3ZYveaAS41mHu8sC4MBnb1a/OahQTNQYZOfnyw8bTsuZQrpzIQgAY30/T72io+yUZH+sjfxndVpoHu9fbthIREVETCwZ/8MH7VV7offfdX9PtISIiIqJalpSUZAgEe3p6yvjxE6VDh461tr6UnBL5eH2qLNyZISXlZUklMsBV7hsTJlN7BYirC4PARFBQrFN1tFfuy5b1h7KkRO8sIqaDIwa65smgVnq5bnAz6dupM3ccERER2T8YvGvXLpPRpvft+1O8vLykZcuWatq5c+ckPz9fZZXYOxh84cIFWbt2rWRkZEiLFi1k8uTJat3GcnJyZPHixergplu3bjJ+/Hi7bgMRERFRU9GrV285d+6M6rtNnjxV/P0DamU92fml8sXmNPlma7rkF5enAgd6u8hdI0LkxgFB4uGGQBeRYysoKpFlO87J7gRPWX84Vy4VamdNyr8fvi4F0q9ZiVw7MFKGdOsozs787hAREVEtBoO//PIrw/033nhdoqOj5bnn/il+fn6GYOwLL8yViIgIsacffvhBbrvtNpk0aZK0atVKvv32W3nooYdk69athkB0XFycDBkyRMLDw6VPnz7y1ltvyeDBg2XBggW81JCIiIgcXlpamoSEhBj2A0oxTJo0RVxd3WoloITMxu9+z5BPN6ZKdn55KrCXu5PcOiREbhsaLH6eLg7/dyHHVlxSKqt3nZPFu1Jlb5KHFOhQ4qHI5DmB3s4SG5Ql0/uFy7g+HcXFhQFgIiIiujJOegwjXU1jxoyS+fN/NDmogNTUVLnxxutl7dp1Yi9du3aVoUOHyscff6weFxUVSdu2beWWW26Rl156SU2bPXu2HD9+XLZt26bq3B07dky9DoHkWbNmVWk92dnZEhAQIFlZWeLvb3oZFhERsQ0laoxKSkpk06YN8scfu2XWrOuldes2tbu+Ur0s2pMpH65LleTsEsN0VxeRG/oHyV0jQiXUj0NWmGM/1HHodDrZ8OcF+XlHkuyMc5c8nekAcODn6SxjuvrJ1d39pX9bH5ZQIaoE21AiouqpUW88MzNTZQKbB4Nzc3PVPHvy9fUVV9fyzUT2Cm5aRnJpaakqD/HKK68YBjzp2LGjCiAvXLiwysFgIiIioqaWDbx06WJJSUlWj1esWCq33353hVJb9qDT6WXNwRx5d02KnEsrz2zEWHBTegbI/WNDJSaIA1uRY0LuzY4jCbJga7z8ft5ZskvwHSw7ltG4Sol0Dc2TqX1CZeaQ1uLuygxgIiIiakDB4KFDh8ljjz0qTz75lMrAhUOHDsm8eS/LsGHD7LqB//nPf+Tuu++Wv/zlL6osxG+//abWMWfOHDX//PnzkpeXJx06dDB5HR7v2LHD6nILCwvVzfhsona2HjciIkdVlUvG2YYSNezA08GDB2T9+l+lpKRYTXNxcZGBAweLu7u7Xfs5WNfvJ/PknTUpciS+vF8FIzv7ypyxodI+oizz0ZH6V5W1o2xDHcO51CJZuT9bVu7PkdMpOEniYzLfWXTSITBXJsT6yrXD2oq/j6dhniN9X4jMsQ0lIqrd4/kaBYOff/55dbvllptNpo8dO1aee+55sSdkICPbGMFaBH3xPx6jE+3j46OykQElHowFBgYa5lkyb948mTt3boXpyckJkp9v/XVERE1dVFSzSp/DNpSoYUI5rR07tquBfTXoIw0ZMlSCgoJUP8dejiSWyn+3FcqfcaUm07tHu8idgz2kS5QT8pMlKUkcTmXtKNvQputsUq4s/SNDDmcGyYmUitX4nEQvLX2yZVhbkUl9wiTEr+wYJj83XXgIQlSGbSgRUe0ez9eoZrAmISFeTp8+re63adNGoqKixZ6Ki4ulefPmcscddxjqA6P2HQaJ69evn3z66adq/aghvHr1ahk3bpzhtf/3f/8nv//+u+zbt6/KGRlYV0ZGBmsGE5FDq2lmMNtQovoVH39Rli9fKtnZWYZp3br1kJEjRxtKadnDqeRCeXdNqqw/YnryvFOUhzw4LkwGt/d2+AF8a5LVxja08YpLyZbvN56VDceL5EKeafkHTa8WntI9JEtuGN5KmoVxfBIiW9iGEhE1wMxgDYK/9g4AG0tMTJSkpCQZPny4YRrqBw8aNEh27typHrdo0ULVvjt58qRJMPjEiROqdrA1Hh4e6mZOq0lMRETWsQ0lalgOHTooK1cuU2UbtO/o+PFXS8eOne22jviMYvlgXYos+SNLdEapBC1C3GTO2DCZ0M1fnJ2RDUyVYRva+KVkXpLvN56WtYfz5EyOn+gFxxWmxxZdYzzVIHATuvtLVKD9TsgQOTq2oUREV6bGweA9e3bLokU/S1xcnHz55ddq2vz5P8ikSZPVoG/2EB0drUpBbN261RDoRf2s7du3S6dOncregKurTJkyRb755htVWxiPT506JZs3b1bTiIiIiJq66OgYlf2LMhG4P3nytAoltGoqPbdE/rMxTX7YniHFpeVR4DA/V7l3dKjMuCpQ3FwYBKamL69IJws2nVRlII5n+ohOHUqZZvkGu+fJ0NYi1w9tLj3ahtfbthIRERHZNRi8du1aeeqpJ1Tgd/fu3YbpqNH75ZdfyP33lw3udqUw2Mk777wj9913nxw7dkyVoli3bp1cvHhR5s+fb3jeq6++KoMHD5aRI0dK3759ZeHChTJhwgS57rrr7LIdRERERA0Z6gGPGzdBUlNTZfDgoXa5yim3oFS++i1dvtySroJgGn9PZ7ljRIjMHhgsXu68moqatqISnfx2/JKs2JctG4/kSH6xvkIA2N81Xwa20Ml1g6OlX6eOvMqQiIiIGrQa1Qy+5poZMmfOAzJixEiJje0iBw8eVtPPnTsrd955h6xdu86uG4mSDwgCp6WlScuWLWXatGni52dajwu1fn/88UdVVqJbt24yderUanXEUKsNGTRZWVmsGUxEVE1sQ4nqDsZP2L17p/TufZW4u7vbffmFxTqZvyNT/rMxVTIulQ8O5+nmJH8ZHCx/HRYiAV4udl+vI2Mb2rAUFZfK0u1nZMmeNDmaGSC5hRUPl7ydC6Vfs2KZ2T9cRvZszgAwUT1iG0pEVAeZwWfPnpUBAwaq+05O5ZcFhoWFSUpKithb+/bt1a2yjBiUiSAiIiJqqtLT02TZsiWSlJQomZmZMmHCRLstu6RUL0v3Zqm6wAmZJYbprs4i1/QNlHtGhUqYP+ueUtNUWqqTNXvOy+KdybInwUPyde6XM4DLA8GB3i4yLtZP+sUUyZjeHcTNlSdFiIiIyEGCwYGBQRIXd0HatWtvEgzetWu3qvNLRERERPaDC7kwSNyvv66W4uJiNe3w4YPSv/8ACQoKvuJlrzucI/9ekyKnk4tM5k3s4S/3jwmTlqH2z0Amqm8Yi2TLgYuy8PdE2RnnKrmlniJievWhu3OpTOgRrL4LA9r5sD42EREROWYwGCUYXnhhrjz//AsqGJyTkyO//fabvPrqPLnxxpvsv5VEREREDqqwsFDWrl0tR44cMkwLDg6WyZOnX3EgeMepS/L2qmQ5EFdgMn1YRx95YFy4dI5GcIyoaTmZVChfrzsp644USGaJt4iYDn7tIqXSOfiSTOwRINcM7SC+XjwZQkRERA4eDL733vtUMHj69KnqjPrAgf1VUHjGjJlyxx132n8riYiIiBxQQkK8LFv2iyoJoenWrbuMGjX2iuoFH7qYL++sTpFtJy6ZTO/Z0kseGh8uV7VGgIyo6biQXiQr92XLyv3ZcjyxUEQwtkj559xJdNI+IFfGx/rK9cPbSpCfV71uLxEREVGDCga7ubnJiy/+S+6/f44cOXJYBYQ7deok0dEx9t9CIiIiIgeD0g27du2QLVs2qX4WuLt7yLhx46Vz5641Xu6ZlEJ5b22KrD6QYzK9fYSHPDg+TEZ08jUpAUbUmJ2Kz5TvN52RjSdKJCHfNPu3jF5a+ebKmM6ecsPwNhIVYuk5RERERE1LjYLBmoiICHUjIiIiIvs5evSwbNq0wfA4KipaJk+eqsZtqInErGL5aF2qLNqTKaVlsWUlJshN5owNU/VQXZwZBKbGLz41R77beFrWHy2Uc5cQ3K1Y6qRnCy+5uru/jOjoIc1CfeplO4mIiIgafDD4s88+rfJC77zzrppuDxEREZHD69Spixw4sF/OnTsr/fsPlMGDh4qLi0u190vmpRL5bHOafLctQwpL9IbpIb4u8reRoXJtv0Bxd8Xl8kSNV1pWvvyw6ZSsOXRJTmX7il5QQsW0jEqEZ57cNLylXN3DX2KCWAOYiIiIHFeVg8Fr1qyp8kIZDCYiIiKqXlkI4/IMuD9x4hRJS0uVli1bVXtX5hXp5Jut6fL5pjTJLSxPBfb1cJa/DguRvwwOFh8PBoGp8cov0snmY7ny/ZYL8scFvZQKTpb4mzwnyC1PBrcSuW5IM+nToXO9bSsRERFRowwGL1jwY+1uCREREZEDyshIl+XLl8qIEaOkWbPmhum+vr7qVh1FJXpZuCtDPl6fKmm5pYbp7q5OctPAILlzeIgE+VxRlTCielNQWCJbT+SqDOD1h3PVSY+ygeDK+boUyIAWJXLtwGgZ1LWjODvzpAcRERGRMR4NEBHVU/AHl4BnZWVKQECgdOvWXYKCgvm3IHIwhw8flDVrVktxcZEsW7ZEbr31dvHy8qr2cnQ6vazYl60Gh4vLKDZMRxngGVcFyj2jQiUq0M3OW09U+4pLSmXFjrPyy+40+TPJQwr1FUs8+LgWS5/IApnRP0JG9+ooLi4MABMRERHZPRi8YsUK+eabr+T06dPqcdu2beWWW26VCROurukiiYgcAoLAq1evMJm2c+d2mTBhosTGdq+37SKiulNUVCi//rpGDh06aJjm6uoieXl51QoGo7zEpqO58u81KXI8sdBk3rhYPzU4XJtwD7tuO1Ft0+l08usfF2TRjiTZFe8u+Tp8hv1MnuPv6SxjY/1kYo8Auaq1t7i6cABEIiIioloLBmMwuU8++ViuuWaWzJ59s5p28OBBefbZZyQ+Pl5uv/2OmiyWiMghMoIRCEYAx9yqVSskJqYZM4SJmrjExARZtuwXycjIMEzr2rWbjBkzVtzdqx643XM2T95elSx7z+WbTB/UzkceHB8msc2qn2FMVJ8B4G2H4mXh7wmy/byL5JR6VQgAuzqVSGxIntw+oZMM7eivyp8QERERUR0Eg7/++mt59dXXZNSo0YZpkydPkX79+sncuc8zGExEZCMruLL5w4aN4P4jaoJwEmjPnl2yadMGFfgCNzd3GTduvHTpElvl5RxNKJB3V6fIpmO5JtNjm3nKQ+PDZUA7H7tvO1FtOZNSqEqcLN6VIvHZCO6a1sl2kVLpGHRJJnT3l2uHdhB/H2a6ExEREdV5MLikpFj69etfYTqmFReX16kjIiJT8fEXLWYFa1BDmIiankuXLsnKlcvkzJmy8loQGRkpkydPl6CgoCot43xakby/NkVW7M8W42akTZi7PDAuTMZ09RMnJ2ZKUsN39Hya/HokXzYcK5KjCVp5k/LPrpPopK3/JRnX1UuuH95WQgO8621biYiIiJqaGgWDe/ToIWvXrpEZM2aaTMcAKD169LTXthERNRkIAP/xx265cOG8zedhMDkianry8/NNvv99+/aXoUOHi4uLS6WvTckulo83pMnCnRlSUpZQrEQGuMp9Y8Jkaq8A1kulBu9cYpZ8t+mMbDhWLBfzTbN/Aecx2gUWyZA2IjcObyMxYaYlIoiIiIioHoPBbdq0leef/6ds3LhRYmNjVZDj0KFDsnHjBvnLX26R77771vDcm26abadNJSJqnEpKSmTt2tVy8KDtEhHQrRsHkCNqikJDQ2XUqLHy22+bZOLEKdK6dZtKX5OdXypfbE6Tb7amS35xeSpwoLeL3D0yRG7oHyQebs61vOVENZeYnis/bDotaw8XyLlcX9ELSjx4VChvMrGHv4zv5i+RAW7c3UREREQNMRi8efMmadGihZw+fUrdNJi2adNGk+cyGExEji4u7oJJILhNm3Zy5kx526mZMGEiB48jaiJQ8sXHx1dcXcu7Wt2795COHTuKp6ftgd3yi3Ty3e8Z8tmmVMnOL08F9nJ3ktuGhMhtQ4PF17PyjGKi+pCRUyALNp2SVQdz5UQWAsAI8JoGeUPdL8mQNk5y+/hO0jaSNa6JiIiIGnwweOnS5fbfEiKiJqpVq9YyaNAQ2blzu1x99STp1KmLZGSkq8HiEDBCaQhkBAcFBdf3phKRHRw5cljWrFklsbHdZPTosYbpqOdrKxBcXKqXRXsy5aN1qZKcXWKY7uoiKgv47pGhEuJbo64bUa0qKNbJlmO5snJ/tmw8kiOFJchY9zd5ToBrvgxqpZNrB8VI/86d+RchIiIiqic8oiAiqgMIBnfp0tUQ8MX/w4aN4L4nakKKiopk3bq1hisBUCe8TZs20rp1W5uv0+n0svpgjry3JkXOpRWZ1FBFPeD7xoRKTJB7rW8/kaZUp5c9Z/MkJbtEwvxdpU8rb3FxNh2csKCoRJb+fka2nNbL9nN6uVRoVND6Mh+XAunfrESuGRApw7p3FGdnljUhIiIiarTB4PT0dJX5kpWVXWHexIkTr3S7iIgaJZ1OJ1u2bFLZvj179jLJCGTmL1HTlZSUJMuWLVb9I03nzl0lOrqZ1ddgzIWtJy7JO6uT5Uh8ocm8UV185YGxYdI+0rNWt5vI3NqD2fLSkgRJySkP7ob5OcvTU6NkRCcfWb37vCzelSJ7Ez2kQFfxJEWQj4v0a1YqY7t4ybg+HcXFhQFgIiIiokYfDF65cqU8++zTUlpaKj4+Fet8MRhMRI6osLBAli1bomqpI/spJCREmjdvUd+bRUS1CAFdZABv2rRB9YvAzc1NxowZr8pEWLPvfL68vTpZdp3OM5net7W3/H18mPRs6c2/G9VLIPjv38ZdflSeCZySU6qmezgXS6EKAPuZvM7Hw0nGxvrL1d39ZUBbH3F1Mc0iJiIiIqJGHgx+++035e9/f0gNDsfLvYiIcLVEmixatNCQFYgAUUZGBoPBRE1YXl6erFq1XE6dOmmYFhERKZMnT5Xg4BCLrzmZVCjvrkmWdYdzTaZ3jvaQv48Pl8HtfdSVBET1URoCGcFlzD+DZY/LAsFlXKRUuoZckok9A2Xm4Nbi48VSJkRERERNNhiMYMfMmdcwEExEJCJnzpyWpUsXS2Fh2WXenp6eMnXqDGnZshX3D1EThUEgf/jhW8nNLQ/qXnVVPxk6dLi4ulbsXsVnFMv7v6bI0r1ZotOXT28R4iYPjAuX8bF+4mxWk5WoLqkawao0hO3PYXOfS3JNby+5dmg7CfRjGRMiIiIihwgG9+jRQ/78808ZNGiQ/beIiKiRQPbv7t27ZNOm9eo+hIaGyowZsyQwMKi+N4+IahHqgvv7B6hgsLe3t1x99SRp06Zdheel5ZbIfzakyvwdmVJcWh4FDvNzlXtHh8qMqwLFjZfUUwOAweKqYs7k9jKpZ0Ctbw8RERERNaBg8NNPPyv33vt/Mn78BGnevHmFDIJZs2bZa/uIiBqkkpISWbNmpRw6dNAwrV279jJp0hRxd/eo120jotqHMlmTJ0+TjRvXyejR48TX19dkfm5BqXz1W7p8uSVd8orKB+Ly93SWO0eEyk0Dg8TLnQNrUcMR5u9q1+cRERERUcNUo97cr7+ulbi4OPnxxwUVDn6AwWAiauqWL18qx48fNTweOHCwDB48lLU+iZqoY8eOqGzgyMgow7SAgACZNm2myfMKi3Xyw44M+c+GNMnMKxtQDjzdnOQvg4Plr8NCJMDLpU63nagq+rTyljA/ZzVYnOVSEXoJ93NRzyMiIiIiBwsGf/PN1zJ37otyzTXX2H+LiIgagQEDBsrp0ydV8BeXh3fs2Lm+N4mIakFxcbGsX/+r7N//pwQGBsott9wuHh4Vs/9LSvWqHjDqAidmlV9u7+osck3fQLlnVKiE+bvxb0QNlouzkzw9NUr+/m2cCvyaBoTLSpw8NTVKPY+IiIiIHCwYXFpaKldffbX9t4aIqJGIiIhUl4ijZmhERER9bw4R1YLk5GRZtmyxpKWlqceZmZly+PBB6dWrj+E5qBe+7nCO/HtNipxOLjJ5/aQe/nL/2DBpEeLOvw81CmNj/eWd2c3kpSUJlweTK4OMYASCMZ+IiIiIHDAY3KVLV9m1a5cMHz7c/ltERNTA6HQ62b9/n3Tv3kPVCdW0b9+hXreLiGoHArx79/6h6gHjBDi4ubnJ6NFjJTa2u+F5209dkndWJcuBuAKT1w/r6CMPjAuXztGe/BNRo4OA76gufrLnbJ4aVA41glEaghnBRERERA4cDG7durU8+ugjMmPGTGnRokWFGpk33TTbXttHRFSvCgoKZNmyX+TMmdOSnp4qo0aN5V+EqAnLz8+XVatWyMmTxw3TwsLCZcqU6RISEqIeH7qYL++sSpFtJy+ZvLZnSy95aHy4XNWaNVWpcUPgt18bn/reDCIiIiJqKMHg7dt/V5dFb9u2Vd3MMRhMRE0BLg1ftGihZGSkq8fIFOzZs7cEB5cFhIioablw4bwsX75EcnJyDNN6975Khg8fKa6urnImpVDeW5siqw+Uz4f2ER7y4PgwGdHJl4NIEhERERFR0wsGL1263P5bQkTUgGBwuKVLl0hRUaF67OXlJdOmzWQgmKiJunTpkixcOF9KSkoM3/kJEyZJu3btJTGrWD5clyCL92RKaXkZVYkJcpM5Y8NkYg9/XkJPRERERERNNxhMRNSUa4Xu3LlDNm/eYHKJ+IwZ10hAQGC9bhsR1R4fHx8ZOnS4bNiwTlq0aCkTJ06RUmcveWNFknz7e4YUlegNzw3xdZG/jQyVa/sFiburaaksIiIiIiKiJhsMzsrKlISEBCkpKRtcRRMbG3ul20VEVOeKi4tl9eoVcuTIYcO0Dh06ytVXTxZ3d3f+RYia4Mkf43EP+vTpq4LCzVt1lG+3Z8rnm+Ilt7A8FdjXw1luHx4iNw8KFh+P8sEkiYiIiIiImnQwODk5WZ588nHZsWOHxfkHD5YHUoiIGssl4j//vEASExMN0wYNGqJu5oNkElHjP/GzceM68fT0UtnAhumlIn9kRMnffj4tabnlJ7qR/Tt7YJDcOTxEAn14URURERERETVeNTqiefXVVyQgIEBWr14r48ePlY0bN8mBAwfU9FtuudX+W0lEVMs8PDzEyaks08/NzU1dIo6sYCJqWlJTU2Tp0l/U/4CSEM2at5QV+7Ll/bUpEpdRbHiui7PIjD6Bcs/oUIkMcKvHrSYiIiIiIqrHYPCuXTtlwYKFEhkZqR4HBQXLyJGj1P/PPvuM3HTTbDttHhFR3XB1dZXp06+RJUsWydix41Wd4NpUqtPLnrN5kpJdImH+rtKnlTcHoCKq5ZIQ+/f/KevX/2oYJM7FxVU2H7skPy8+I8cTywaL1Izv5qcGh2sd5sG/CxEREREROXYwOD093RAI9vf3l4yMdAkNDZOOHTtKXNwFe28jEZHd6XQ6ycu7JL6+foZpvr6+cuONN9d6WYi1B7Nl3rIkScoqC0hBRICrPDk5QsbG+tfquokcUUFBvqxevVKOHz9WPs27rRzS9ZIDG/A9LA8ED2rnIw+OD5PYZl71tLVERERERES154oL33Xs2EkWLFggd9xxp/z880+GIDERUUOVn58vS5culuzsbLn55lvF09PTMK8uAsEPfXtR9GbTk7NK1PS3ZwsDwkR2FBcXJ8uX/6K+75Be4i8n3QbK4TgEe8tPyHRr5il/nxAuA9r6cP8TEREREVGTVaNg8LBh5YOtzJkzR+6771758MMPVJ3NefNesef2ERHZVWpqqixa9KNkZmaqxytXLpMZM2bVyV5GaQhkBJsHggHTEIZ+ZVmSjOrix5IRRHbI/t++fZts2/abKhGRXeot+4ti5WR+tMnz2oS7y4PjwmR0Fz8OFklERERERE1ejYLBH374keF+7959ZO3adXLq1CmJiYmR0NBQe24fEZHdnDx5QpYvXyJFRUXqsbe3t/Tt27/O9jBqBBuXhrAUEE7MKlHP69eG2YlE1ZGaliaLNx+VhIwCiQrylMmD2qvv/KVSd9mX31FOFLYWnTrlUiYywFXuHxMmU3oFiKtL7V4RQERERERE1OjLRCC7Tgv84pLr/fv3qdrBI0aMlNqE7B5bl3EjE8jZ2blWt4GIGhe0Gzt2/C5btmwyTAsPj1ADxgUEBNTZdmCwOHs+j4jK/HfFAfl4a7Hk6YINu+STXXHSKbKX7Mt0lVJxMUwP8nGRu0aEyA39g8TDjf0FIiIiIiJyLDU6Clq4cKF88MH76n5xcbHcdtst8tVXX8qjj/5DvvvuW3tvoxw6dEgmTpwoXl5eEh4eLk888YQUFpqO+j1v3jyJiIhQpSq6desm69evt/t2EFHjgzZq2bJfTALBqHWOgeLqMhAM3h5Va3LD/K+4nDuRw1i8I17e2uIiebry2t+Qp/eUPxI8DIFgb3dnuXd0qKz6R1u5dUgIA8FEREREROSQahQM/vrrL+W2225T93ft2qX+X7VqjXzwwUfy/fff2XUDT548KYMHD5bWrVvLxYsX5fz58xIWFiZ79+41POfjjz+Wl19+Wb799lvJysqSmTNnyuTJk+XMmTN23RYialyys7Pku+++kaNHjximDRkyTKZMmS7u7u51ui27z+TJi4sTbD7H6fKl631aedfZdhE11pM8cXEXZPuO7TJvafLlqeZXDWmP9XLTwEBZ9WhbuW9MmPh6lmcJExEREREROZoapZ/Fx8dLZGSUur9z5w4ZOXKUuLq6So8ePSQhwXawo7qeeuopFQh+//33DeUhHnnkEZPnvPXWW3LHHXfImDFj1OPnn39evvjiCxUkfvXVV+26PUTUeBw/fkySk5PUfTc3d5k8eaq0a9e+TrehpFQvH65LkU83ponO0shxZmGrJyZHcPA4IjOo833ixDHV/0hIiFffa5R/SSgOldzSIZXsLycZG+svIb7MuCciIiIiIqpRZnBUVLRs3rxJ1QpevXqVDBw4UE2Pi4uT6GjTUbqvRGlpqaxYsUKuv/56FQhGPWBzaWlpcuLECRk+fLhhGp6Lx7///rvdtoWIGp8+ffpK585dJDAwUG6++ZY6DwTHpRfJrf85J59sKA8E923tLc/PiJSIANPAFB6/PTtGBa2IHFlhYYHk5uaYTNPrdbJixTL5888/JCkpUXQ6vcQXh8ruvK5VWibrcBMREREREZWpUZrM3XffLf/4xyPi4uIiHTt2lP79B6jpixb9LDNmzBR7SUlJkUuXLqnsn6uuukr+/PNPVRf41ltvVdm/uMw7Kaks6w+lI4yhtvDOnTutLhs1h43rDmdnZ6v/EXC2FHQmoobP0gCTY8dOkJKSElVzvC6/28v3Zcu/fkmS3MKydbo4i9w3OlRuHxasMn+n9/aXP87mS0pOiYT5uUrvVl5qekNof6oyCCfbULIHfN7T09MMGb+4paWlSteusTJhwiTD85DZHxISKgkpmXKyqIWcLG4n6cVVL6cS6uvSIL5b5Dgqa0fZhhIRsQ0lIqqv4/kaBYOnTJkqvXr1lsTEROnevbsqEQG9e/eWwYMru1yzeoEdeO211+SXX36RQYMGqRrFqAeMN/evf/3L8Fzzgzw8Ng8KmQ84N3fu3ArTk5MTJD8/127vgYjqBg6sf/tti3Tp0lWiosrK2BjLzs6ok+3IK9LLexsLZO3REsO0SH8neXqCl3SOLJTUlPJSOi18ym6QmpIpDUVUVLNKn8M2lGr6PcWJ3tTUVElNTVFX96D+r7kLF85LUlK84fHp1FLZU9JXfs9xl8JS0992ZycRneovWPrN10uYr7PEeGVIUlLD+Y5R01dZO8o2lIiIbSgRUX0dzzvptYhrA4QDRB8fH5WJjJrBmn/84x+qfMThw4clIyNDgoOD5ccff5RZs2YZnjN79mw14NzGjRurnJHRvHlztTx/f16mTdSYIKi0ePFPagBJT09PmT37FgkMDKrz7ThwIV8eX5AgF9LLg1uTe/rL01PCG9WgVTXNDGYbSualnnBS1vjzhHEGtmzZaPOzFxYWrspRDR02WtYdyZUftmfKH+fyKzz3qtZeckP/INGLXh77IUEsdWYQHn7rpmgZ09WPfxxq8JnBbEOJiNiGEhE12MzguuLm5iYDBgxQl3ibB4kxD4KCgqRLly6yYcMGQzAYWcF4/Ne//tXqsj08PNTN0k6ryo4joobhxInjsnz5UikuLlKPnZ1d1AF2XX6PS3V6+Xxzmry/NkVKLl+k4OPhLM9Oi5QpvQKkKWIbSuZycnIkPv6iKvWA/1Hb94YbZqvAriYmJsbkNb6+vhIdHSNRUTFqzIGIiEhJyxNZsCNDXnzjtKTllpo839vdWab08pcbBwRJ+0hPw3Q3F2eZtyxJkrKMMvIDXNWAjKzDTQ0R21AiIrahRET1pUEHg+Gpp56Sa6+9ViZNmiSDBw+WHTt2yBdffCHPPfec4TmPP/64/O1vf5NRo0apwexQViI3N1fuueeeet12Iqo9uKjh99+3ytatWwzTEEiaPv2aOs3uT8oqlicWxMvO03mGad2be8qr18dIixD3OtsOorqEk7Ko2Z+QcPFyvd+LKhhsDoFh42AwvqNXXdVPBYAR/PXz8zd8n3eczpPX5yfJhiM5UmpW3rdNuLsKAE/tFWAxyx4B31Fd/GTP2Tw1WFyYv6v0aeWt6nATERERERFRIwoGT5gwQf773//KM888I+fOnZMWLVqoWsFz5swxPOeWW25Rwd8nn3xSHZx269ZN1q5dK82aVV4ng4gan6KiIlm5cpkcP37MMK1z5y4yfvxEw1UDdWHdoRx59qcEycovy15EmfK7RoTIvaPDxM2FQShqur788r+SmWm7DndAQGCFOr4Y+HXkyNGGxzkFpbLkjyz5YXuGnE4py+7XYNDF0V385MaBQdK3tbfNcQDKnu8k/dpcLsJNRERERERE9qsZ/PLLL8nMmTOlU6fO0lSgVltAQICqOcqawUQNV1ZWpixa9JOkpCQbpg0bNkL69RtQabDIXvKLdPL6iiSZvyPT5JL0V66Llr4OGoxiG9p0FBUVSkJCgqHcA0ovzZp1vclzli5dLEePHjE8dnNzVwM3lpV8iFY31Py35nhigXz/e4Ys/TNL8otMuyGhfi5ybd8gubZfoEQE1N3JHaL6xDaUiIhtKBFRg84MxsBt3333rXTu3FlmzJgpkyZNVoFUIqLaHpBq/vzvVUAY3N09ZPLkqdK2bbs62/HHEgrk0R8uyqnk8ixGDE41d2aUBHo3nkHiiADng9PS0gzlHhD8xYCMxlB/27hWP+A7h8dard+QkNBK63QXlejl10PZKgt4z1lLA8J5q1IQo7v6MbOeiIiIiIioIWUGw5kzZ2TRop9l6dIlKpt29OgxKjCMAd8a4wBszMggahxQGuKXX36WwMAgmTlzlgpC1QU0ld9uy5A3VyWroBZ4ujmpAapm9Q2ss6zkhoptaOODwO+PP85XmcC2eHp6yo033iyhoWE1Wk9iVrH8uDNTFu7KkNQc0wHhvNydVB3gGwYESQejAeGIHA3bUCIitqFERA0+GGycqbdly2b5+eefZfPmTRIWFibTp8+Q66+/QUJD6yZIYw/shBM1HocPH5I2bdqIp6dXnawvLbdEnlkYL5uPXTJM6xjlIa/fECNtwz3qZBsaOrahDQ9+n5Hli6Avsn7bt+8gHTp0NMzPz8+T99//t8lrcFIjLCxcZftqWb9BQcHVPtmhDQiHUhDWBoS7oX+QTOtteUA4IkfDNpSIiG0oEVGjGUAOl45iBHEM4Ia6gjExzWTNmtXy+ef/lX/+c65MnTrVPltKRA4nLy9Pjhw5JH369DWZ3qVL1zrbhq3Hc+XJH+MlLbc8o/Evg4Pl4Qlh4u7a+K6CoKYrNzfHUOoB9X4TExOkpKTEMN/V1dUkGOzl5S3NmjUXLy8vQ+A3IiJSDfJW420oKJVfMCDcjgw5bVRKRRsQbhQGhBsQJP3aVD4gHBERERERETWgYPCBA/tVNvCqVSvFw8NDpk2bLs8//7y0aNFSzUf5iNdee5XBYCKqkeTkJDVQXHZ2lri4uEjPnr3rdE8Wlejk32tS5Mst6YZpIb4u8tKsaBna0bdOt4XIlh07tsuff+5RmYW2JCUlVpiG8g/2cAIDwm3PkCV7OSAcERERERFRkwsGT58+VU6fPi2DBw+RF198SUaMGKEyjoxNnjxFnnzyCXttJxE5kGPHjsrKlcvUlQewY8fv0rVrN5MBrGrTmZRCNUjckfjyWqpDOvioQHCo3xVfUEFU7ZILqM2PQd4SEhJkxIhRJrX5dbpSi4FgDOwaFRUt0dHI+o1R5R/sCbWz1x3OUQPC7T6TZ3FAONQCHt3FT9xdmQVMRERERETUENQoqjF+/AQ1WFxkZKTV5+Dyz4MHD1/JthGRAwa9tm37Td00kZFRMn36NXUSCMb6f96dJfOWJkp+cVk5dTcXJ3l4QrjcPChInJ0Z0KLaV1RUpEo8aOUe8D9KpmhiY7tJeHiE4TECvvh+4LuCoC8e4+brWzsZ7EmXB4T7kQPCEREREREROUYw+J577rX/lhCROHoAbMWKpXLixHGT2sDjxl1dJ4HgrPxSef7nBFlzMMcwrU2Yu7x2Q4x0jvas9fWTY0Nt33Xr1qrgLwZ9szW2K+oCGweDUZ7pgQceNskWtjdsz04MCLc9Q9YftjAgXJi7ygKe2jtA/DggHBERERERUeMPBn/22adVXuidd95V0+0hIgeUmZkpixYtVEEw7cqCYcNGSt++/epkkKk9Z/LksfkXJTGrfLCta/sFymOTIsTbnYPEkf3k5+dLYmI8PuXSunUbw3TUxT516qRcupRb4TUeHp5qcLfykg/RJvNrMwhclQHhEATuzwHhiIiIiIiImlYweM2aNVVeKIPBRFRVyIT86acFKkgGGJByypRp0rp121rfiSWlevlofar8Z0Oq6C4nYvp7OcsLM6NkbKx/ra+fmjadTicpKSmq1i+yefF/enrZgIQI6hoHg3HSA0HekydPSGhomCHoi/+DgoLr5KSIpQHhlu7Nlrwi0zRgDKR4bb8gdcIkMqBu6ngTERERERFRHQeDFyz40U6rJCIq5+8fIK6uCCjlS3BwsMyYMUuCg0NqfRfFpRfJ4/Pj5c/zZUFo6NvaW+ZdFy1RgQxwUc0g+Hv48EF1kgN1f7VBEM0lJSVKaWmpygjWjB49ViZOnCLu7u71svuLS/Wy7lCOCgJbGhCuTysvuXFgMAeEIyIiIiIicrSawURE9uLj4yMzZlwj27dvkwkTJqpL4mvb8j+z5IXFiZJbqDNc7n7/mDC5Y3iIuHCQOKpijd/k5CQJCgoSLy9vw/TMzAzZuXO7xdegnENEROTlkg8xFeoC+/nVTzZ6ZQPCTekZoEpBdIxi7WwiIiIiIiKHDQbv2bNbFi36WeLi4uTLL79W0+bP/0EmTZpcayOYE1Hjd+nSJRUU8/LyMkxDgGzatJm1v+7CUnlpSZKqgappFuSmBonr0aJ8e4iMIWibnZ1tKPcQH39RBYKR2Ttp0hTp0iXW8FzU9TXOejeu9YtB31xdG8Y5WG1AuB+2Z8g6DghHRERERETkMGp0VLp27Vp56qknVOB39+7dhum5ubny5ZdfyP33z7HnNhJRE4FL4xct+kmVg5g16/paHfjK3IEL+fLoDxflQnr5ZftTevrLM9Mixdez/FJ9Irh4MU6d7ETgF0FgnMSwBPONg8E4GXrNNddKeHhkgzwxigHhluzNUkHgUxYGhBvZ2U9uxIBwbb3rvE4xERERERERNdBg8Mcffyivv/6GjBgxUhYuLK8lPGbMGLnzzjsYDCaiCo4ePSwrVy5Xl9fn5GTLtm2/yZAhw2p9T+l0evl8S5q8tyZFSi6Pg+Xj4SzPTouUKb0C+JdqojIy0uXAgf2SlZUpAQGB0q1bdzUQm6UMWZzI9PPzM5m+desWOXfurNXl44QGSj20aNGqwrw2bdpJQ3MyqVC++z3d6oBws/oGynX9gzggHBERERERURNXo2Dw2bNnZcCAgeq+ceZQWFiYGjyHiMg42Pbbb5tVTWANLpvv2bN3ndRCffLHeNlxqnwwrO7NPeXV62OkRUj9DNJFtQ9B4NWrV5hMQx1f1KRu166DGtwNt7Ks33j1GZ0z5yGT3zOUddCCwR4eHuozi1tMTIxERkablDlpqLQB4ZAFvMvCgHC9MSDcgCAZ09Vf3F2ZBUxEREREROQIahQMDgwMkri4C9KuXXuTg+ddu3ar+ohERFBYWCjLly+RU6dOGnZIbGw3GTt2Qq3XTl1/OEee/SlBMvPKBsRCU3XXiBC5d3SYuLkw8NWUM4IRCDYfnA2QmS6CW0Xp6WkSEhJqeNyhQyeVUYzftODgkEZVMiE5+/KAcDszJSWnxGSel5uTyoi/fkCQdOKAcERERERERA6nRtGYqVOnygsvzJXnn39BHSDn5OTIb7/9Jq++Ok9uvPEm+28lETXKoBzqA6elparHaCtGjBglffr0rdXAWkGxTl5bniTzd2QapkX4u8or10dLvzY+tbZeajhZwdXh7e2tMn4xGJyx8PBwdWssEPxG9u/3v1seEK51mLvc0D9IpvUJED/WyCYiIiIiInJYNQoG33vvfSoYPH36VNHpdDJwYH8V3JkxY6bccced9t9KImpUzp49I0uXLpaCggL12MPDU6ZMmSatW7ep1fUeSyhQg8QZD4w1pqufzJ0ZJYHeHCTOEaBGsC2enp7SpUtXVe8XWb/I/m1MWb/mLhWWypI/suSHHZmqLrAxZyeRUV04IBwRERERERFdYTC4uLhIXnzxX2qguCNHDquAcKdOnVSNxby8S7V++TcRNWxHjx4xBIJDQkJkxoxZFgfvsmdW5He/Z8gbK5OlqKSsPICnm5M8PjlCru3buIN9VD0I7lqDz0GPHr1k2LARjX63IvD7/fYMFQi2NiDctf2CJCrQrd62kYiIiIiIiBqeGkVt+/XrKwcPHpaIiAh1szSPiBzXmDHjJDU1RQ2yNXnyNDUAV21Jzy2RZxYmyKZjuYZpHaM85PUbYqRteO2tlxqmbt26q8HibM1vrDAgHGphIwi867TlAeFQCmJsLAeEIyIiIiIiIstc7T1YVG0GfYioYUJmrnH2La4OmDXrOnF39xBnZ+daW+/W47ny1MJ4Sc0pr/f6l8HB8tD4MPFwq731UsOFDPQJEybKqlUrKszD9NrMUK8tKdqAcLsyJTm74oBwk3sFyA0cEI6IiIiIiIjsHQz+4ovPLd7XgkEHDx6Qtm3bVWeRRNTIJSYmyMqVy2Tq1JmqJITG09Or1taJUhD/XpMsX25JN7k0/qVZ0TK0o2+trZcah9jY7hIT00wNJocawigdgYzgxhQIxm/qbgwItz1D1h3KkRIrA8JN7R0g/l6sh01ERERERES1EAxetmypxftqQa5uEhMTLS+88GJ1FklEjdiRI4dUBmZJSYksWrRQbr75VjVAV206k1Ioj/0QL4fjy2oSw5AOPioQHOrHeuVUBoHfxlgbuLIB4UZ29pUbBwbLgLberIVNRERERERE1VatyMlPPy1S/9955+3y2WemmcFE5DgwaOSWLZtMarOiPnBpaXm5htrIlPx5d5bMW5oo+cVlg8S5uTjJwxPC5eZBQeKMSBlRI4XA7w8YEG5vllwqrDgg3DV9A+U6DghHREREREREV6hGaXQMBBM5rsLCAlm2bImcPn3KMK1btx5q0DjUCq4NWfmlMndRgqw+kGOY1ibMXV67IUY6R9duJjJRfQ0I16ull6oFPC7WT9xdWQObiIiIiIiIrtwVRW5QizEhIUFKSkyzAWNjY690u4ioAUpPT5NFi35S/wMGjRs1aoz06tWn1i5Z33MmTx6bf1ESs8oHzrq2X6A8NilCvN0ZICNpcgPCTepZNiAcT3QQERERERFRgwgGJycny5NPPi47duywOP/gwcNXul1E1MCcOXNali79RWUGA2oDT506Q1q2bFUr6ysp1cvH61Plkw2poiurCiH+Xs4yd2aUjIv1r5V1EtX2gHAoBfGrhQHhWoW6qwDwNA4IR0RERERERA0tGPzqq69IQECArF69VsaPHysbN26SAwcOqOm33HKr/beSiOpVVlaW/Pzzj6pWMISGhsqMGbMkMDCoVtZ3MaNIDRL35/l8w7S+rb1l3nXREhXoVivrJKqtAeGW7s1WQeATVgaEQxB4QFsf1r0mIiIiIiKihhkM3rVrpyxYsFAiIyMNo7aPHDlK/f/ss8/ITTfNtvd2ElE9wsmfIUOGyebNG6Vdu/YyadIUcXf3qJV1rdiXJXMXJUru5UG0XJxF7hsTJncODxEXDhJHTWBAuGAfF5nVN1Cu7R8k0Ty5QURERERERA09GJyenm4IBPv7+0tGRrqEhoZJx44dJS7ugr23kYgagH79BkhAQKB07NipVuoDI4PypSVJ8ssfWYZpzYLc1CBxPVp42X19RLUxINyGIzny/e8ZstPCgHA9W3rJjRwQjoiIiIiIiBrrAHKAwNCCBQvkjjvulJ9//skQJCaixishIV5SUlKke/cehmkIAHfq1LlW1nfgQr4aJO58WrFh2uSe/vLstEjx9XSplXUS2XVAuF2ZalA48wHhPC8PCIcgMAeEIyIiIiIiokYZDB42bLjh/pw5c+S+++6VDz/8QNzc3GTevFfsuX1EVMcOHTogq1evVPWBkfnfqlXrWluXTqeXz7ekyXtrUgwDavl4OKsg8JReAbW2XiJ7DAi352y+KgWx9mB2hQHhWoaUDQg3vU+A+HvxhAYRERERERE14mDwhx9+ZLjfu3cfWbt2nZw6dUpiYmLUwFJE1Pgg+Ltp0wbZvXunYdrevXtqLRiclFUsT/4YLztOlV9O362ZpyoL0SLEvVbWSXSlUP932Z9ZKgh8PLHigHAjOvuqLGAOCEdERERERERNJhj8+OOPyauvvmZ47OvrKz16lF9OTkSNS0FBgSxb9oucOXPaMK1Hj14yevTYWlnf+sM58uxPCZKZV6oeowTxXcND5N4xYeLmYv96xERX6lRy2YBwqGnNAeGIiIiIiIjIoYLB69evk8LCQvHw8LD/FhFRnUpLS5NFixaqgSDB2dlZRo0aK7169bb7ugqKdfL6imQVVNNE+LvKK9dHS782PnZfH9GVKCnVy/rKBoTrHyTjuvmJu6szdzYRERERERE1zWBwnz59ZPPmTTJ27Dj7bxER1ZnTp0/K0qVLpKio7HJ3Ly8vmTZtpjRv3sLu6zqeWCD/+P6inEouMkwb09VP5s6IlECfKx7LksjuA8It3JkpSRwQjoiIiIiIiJqQGkVg2rVrL0888bhs2bJF2rZtqwaOM3bTTbPttX1EVEv27/9TDRSnCQsLlxkzrpGAgEC7D7T13e8Z8sbKZCkq0atpnm5O8vjkCLm2b6A4oUYEUT3D5/SPs/nyfSUDwk3rEyABHBCOiIiIiIiIHCkYvGnTRomOjpa9e/9QN3MMBhM1fFFR0epETnFxsXTo0FGuvnqyuLvbd+C29NwSeWZhgmw6lmuY1jHKQ16/IUbahrPMDDX8AeGGdyobEG5gOx9xxgQiIiIiIiIiRwsGL1263P5bQkR1CpnAkyZNleTkJBk0aIjdM3S3nciVJ3+Ml9ScskHi4C+Dg+Wh8WHi4cb6qlS7SnV62XM2T1KySyTM31X6tPIWF6NgLgaEm395QLjcQtM04GAfF7mmb6Bc1y9IooNMr3whIiIiIiIiasxYqJPIQSDoGxISKi4uLoZp7dt3UDd7QimId9ckyxdbygakgxBfF3lpVrQM7ehr13URWYIyD/OWJUlSVolhWkSAqzw2MUJcnEWVgthxysKAcC28VCmI8RwQjoiIiIiIiJqoGgWDP/jgfZvz77vvfqkN27dvl//9738ycuRIueaaa0zmJSQkqHlJSUnSrVs3uemmmyrUMiZyVAcP7pc1a1ZJbGx3GTduQq2t52xKoTz6Q7wcji8wTBvc3kdevjZaQv147onqJhD80LcXpaw6dTkEhh/5/mKF56N+9aQe/ioI3CXGi38iIiIiIiIiatJcaxqUNabT6SQu7oKkpaVJ9+7dayUYnJ6ergK8mZmZ4urqahIMPn78uAwaNEj69esn/fv3l5deekm+/PJL+fXXX02yIIkcDb6bGzeulz17dqnH+/btlVatWqsawfYefGvRnix5eUmi5BeXheHcXJzk4QnhcvOgINZapTorDYGMYPNAsCUtQtxUAHh6n0AOCEdEREREREQOo0bB4G+++V+FaaWlpfLKK/MkICBAasNf//pXufPOO2XBggUV5j3++OMSGxsry5cvV3VP77jjDmnbtq18++23csstt9TK9hA1dPn5+bJ06WI5d+6sYVqvXr2lbdt2dl1PVn6pvLAoQVYdyDFMax3mrgaJ6xztadd1EdmCGsHGpSGseXhCmPx1aAhPUhAREREREZHDsdsoTsjAvffe+2TZsqVib++++65kZGTIE088UWFecXGxrFy5UmUNawNgNWvWTEaMGCG//PKL3beFqDFITU2V//3vK0Mg2NnZWZWHGDNmvF2z5RF8u+bd0yaB4Gv7BcqC+1szEEx1DoPFVUVkgBsDwUREREREROSQ7FrEs6AgXwVt7enPP/9UZR927typAlrmzp8/L4WFhdK6dWuT6W3atJGtW7daXS5eg5smOzvbcFk9bkSN1alTJ2XFiqVSVFSkHnt5ecvUqdOlWbPmdvtsl5Tq5ZMNafKfjWmiu3xNvr+Xszw/PVLGxvqpx/weNV6W2trG0IaG+rpU+Xn8fBJRfbajDbENJSJqKNiGEhHV7vF8jYLBK1asqDANndiffvpR1e21l0uXLsn1118vb7/9trRs2dLqpfDg51cWgNL4+/tLXl7F0eI18+bNk7lz51aYnpycIPn5uVe87UR1DXV7Dx06qE6gaIKCgmTEiJHi5uYiSUnxdllPYrZO5q3Ol0MJ5Qer3WNc5IlxnhLulyNJSeVZwtQ4RUU1q/Q5DbENjfHSS6ivk6TmWq8aHObrJDFeGZKUlFmn20ZEjqWydrQhtqFERA0F21Aioto9nnfSI4JUTUOGDKowDcHX3r37yEMPPSwhISFiD5988omqB3zzzTcbps2fP19iYmJkyJAhqnwEMoORFYxSERMmTDA87+6775bdu3fLH3/8UeWMjObNm6vMZrwXosYGdbt//PEHuXgxTj3GIHETJkwUNzd3u61j5f5seWFxkuQWlgWCXZxF7h0VKncMDxYX57IyLeS4mcENoQ399VCOPPxd2YkP4x837dP51k3RMqar6clDIqKGkNXWENpQIqKGgG0oEVEDzAz+7bdtUhcGDRok//rXv0ymeXh4qGzHTp06qRrBLVq0EF9fXzly5IhJMBiPu3TpYnXZWA5ulnZaVXYcUUODz+20aTNVreDu3XvIgAGDDHW0r9SlwlJ5eWmSLN6TZZjWLMhNXrshRnq08LLLOqhxaaht6LhuAfL2bCeZtyzJZDC5iABXeWJyhIyNZZCFiOpfQ21DiYgaA7ahRERXpkaZwfWpZ8+eanC4d955xzDt9ttvlz179sj27dvFy8tLXSbfp08fWbx4sUyZMqVKy0VGRkBAgGRlZTEjgxpVNrD5gHCoFezubr9s4AMX8uWx+RflfFqxYdrknv7y7LRI8fW032B01Lg1tDa0VKdXAxxiULkwf1fp08qb2etE1GA1tDaUiKgxYRtKRFQ9NUo9OHbsmLz11psVpr/55hty/PhxqWuvvPKKFBcXqwDwTTfdJKNGjZLbbrutyoFgosZo//4/5auv/muom62xVyBYp9PLfzelyc0fnzUEgr3dneWV66Ll1etjGAimBg1lS/q18ZFJPQPU/yxjQkRERERERFTDMhHz5r0s998/p8L0YcOGy6uvzpP//veLWtu3Tz75pKoZbCw8PFz27t0rq1evlqSkJHnggQdkwIABtbYNRPWdDbxhwzrZu3ePerx06WKZNet6u15WmpxdLE8uiJftp8oHYezWzFOVhWgRYr+sYyIiIiIiIiIiauDB4IMHD0iXLp0rTEeN3v3790ttuv76663WDZo6dWqtrpuovuXn58mSJYvl/PlzhmkhIaF2Xcf6wzny7E8JkplXqh6j7PBdw0Pk3jFh4ubCQeKIiIiIiIiIiBwqGIwB3A4ePCT9+vUzmX7o0EFV74yI7C8lJVkWLfpJsrIy1WNkAo8bN0G6dethl+UXFOvk9RXJ8sP2DMO0CH9XeeX6aHWZPREREREREREROWAweMqUqfLcc8/IU089LVdddZVgCLrdu3fLSy+9qOYRkX2dOHFcli9fompjg7e3j0yfPlNiYprZZfnHEwvk0R/i5WRSoWHa6C6+8sLMKAn0qVEzQUREREREREREDUyNojz33HOPJCYmyn333St6RILVpeROKhB877332XsbiRwWvl+//75Vtm7dYpgWEREp06dfY5fRxrH8737PkDdWJktRSdl32dPNSR6fHCHX9g1U32siIiIiIiIiInLgYLCbm7u8/PI8mTNnjhw5ckQFjDp16iRRUdH230IiB3bq1EmTQHCnTp1lwoRJ4ubmdsXLTs8tkWd+SpBNR3MN0zpEesjrN8RIuwiPK14+ERERERERERE1LFd0/TeCvwwAE9lHRka6HDiwX9UEDggIlG7dukvbtu0kNrabGrRx2LAR0q/fALtk6247kStP/hgvqTllg8TBXwYHy0Pjw8TDzfmKl09ERERERERERE0kGHzs2DFZvnyZPPzwIybT33zzDVUqokOHDvbaPiKHgCDw6tUrTKbt3LldJkyYKGPHTpCuXbtJixYtr3g9KAXx7ppk+WJLumFasI+LvDQrWoZ18r3i5RMRERERERERUcNVoxTAefNelmHDhleYjmmvvjrPHttF5FAZwQgEo36v+W3VqhWSk5Ntl0Dw2ZRCmf3RWZNA8OD2PvLzg20YCCYiIiIiIiIicgA1ygzGJetdunSuML1Lly6yf/9+e2wXUZNWVFQkaWmp6rZ37x+GgRitZQ2jRERNYdmL9mTJy0sSJb+4bD2uLiIPTwiXvwwKFmdnDhJHREREREREROQIahQMDgoKkoMHD0m/fv1Mph86dFACAgLstW1ETUpxcbEsWbJIBYCzsrKq/DrUEK6p7PxSmbsoQVYdyDFMax3mrgaJ6xztWePlEhERERERERGRgwSDURf4ueeekaeeelquuuoqQVLj7t275aWXXlTziBxNSUmJpKWlSVpaiqSmlmX8RkZGycCBgw3PcXV1lfj4i1JQUFCtZWMwuZrYczZPHp9/URIySwzTru0XKI9NihBvdw4SR0RERERERETkaGoUDL7nnnskMTFR7rvvXsPl7U5OTioQfO+999l7G4kalMzMTElIiFeB35QUBH5T1DTzUg8oBWEcDMZ3JDQ0TJKSkiQ0NFTdQkLCxMPDQ9asWWm1VES3bt2rtX0lpXr5ZEOqfLw+VXSXF+nv5SxzZ0bJuFj/mrxlIiIiIiIiIiJy1GCwm5u7vPzyPJkzZ44cOXJEBbk6deokUVHR9t9ConpQWlqqBnZDlm+HDh3F2bk8k/bAgX2yffu2SpdhqRTEjBmzVPAX3xljqNuLweLMTZgwUYKCgqu83RcziuSx+fHy57l8w7S+rb1l3nXREhXoVuXlEBERERERERFR01OjYLAGwV8GgKkx0+l0kpGRIampKaq0Q1mJhxRJT09X8+COO+6W4OAQw2uQ0WsM5R8wvyzbN8yQ8Wupfranp+U6vbGx3SUmppkaLA41glEaAhnB1QkEr9yfreoD5xSUbbeLs8h9Y8LkzuEh4sJB4oiIiIiIiIiIHN4VBYMRtEpISJCSklKT6bGxsQ6/Y6lhQ93e77//n8r+RRawLQgQGweDo6NjZOjQ4RISUlbqAYFb48zhmkLgd9iwEdV+3aXCUnl5aZIs3lOeidwsyE1euyFGerTwuuLtIiIiIiIiIiIiBw4GJycny5NPPi47duywOP/gwcNXul1ENYK6uzhJgQAusn21wdxat25jEmhFqYbs7GyLgWAEdrVMXwR8Q0LKA8GA4O+AAYMaxF/oYFy+PPrDRTmfVmyYNqmHvzw7PVL8PF3qdduIiIiIiIiIiKgJBINfffUVdQn86tVrZfz4sbJx4yY5cOCAmn7LLbfafyuJrMBAbufPn1elHRD4TU9Pk+Li8sCoxtvb2+QxavaGh4dLfn6eKulgPKBbUFCQuLg07ECqTqeXL7aky7trkqWkrCqEeLs7y3PTI2VKr4rlKYiIiIiIiIiIiGoUDN61a6csWLBQIiMjDZe3jxw5Sv3/7LPPyE03zeaeJbtl+ubk5Khgb1pamvTp09dk8LXjx4/Jzp3bbS4Dz7eUAXzDDbMrDOTWGCRnF8uTC+Jl+6k8w7RuzTxVWYgWIe71um1ERERERERERNTEgsEYXEsLBPv7+6u6qxg4q2PHjhIXd8He20gOEvS9dCnXpLxD2aBuaVJUVGh4Xrt2HSQwMNDqYG6YVzaIW5ihpi9KPmCQN3ONMRC8/nCOPPtTgmTmlQW38RbuGh4i944JEzeXxvd+iIiIiIiIiIiokQwgBx07dpIFCxbIHXfcKT///JMhSExkLeir0+lMyjDk5ubK559/KoWFBZXuNASIjYPBzZu3lIkTJ6vgL4K+bm5uTXLHFxTr5PUVyfLD9gzDtAh/V5l3XbT0b+tTr9tGRERERERERERNOBg8bNhww/05c+bIfffdKx9++IEKxM2b94o9t48asby8PKNB3MoHc4uN7S4jRowyPM/Hx0d0uoplHLTM87IM37K6vhERkRXmd+3aTZqy44kF8ugP8XIyqTxDenQXX3lhZpQE+lzx+RwiIiIiIiIiInIQNYokffjhR4b7vXv3kbVr18mpU6ckJiamwmX75DhOnz4pp0+fvlzeIVUFgy3BPPNyDS1btpKSkhJD0Fcr8eDu7iGOolSnlz1n8yQlu0TC/F2ld0svmb8jU95YmSxFJXr1HE83J3l8UoRc2y+wUZa5ICIiIiIiIiKi+mOXtEJfX1/p0aOHPRZFDVhBQYEhyxd1o5HdaxyQPHfunOzdu8fmMnx8fMXLy6vC9BkzZokjW3swW+YtS5KkrBLDNHdXJ0MQGDpEesjrN8RIuwjHCZATEREREREREZH98BpzqqCwsFBl75YP4lZ2Pzc3x+R5ffr0VWUaNMZZ4d7e3iaDuGn3LQWCHR0CwQ99e1HKw75ljAPBNw8KkocnhIuHm3Odbx8RERERERERETUNDAY7sKKiIlWr19OzPECbmZkpn35aXgbEFmQIGweDW7duKzfcMFsFfREMpqqVhkBGsHkg2FiQt4s8NilCXJxZFoKIiIiIiIiIiGqOwWAHUFxcLOnpaZKSomX5lv2flZUl/fsPlGHDRhiei+Cuq6urqt9rzNPT02QgN9yPjIyqUC4EN7JNr9dLcnaJHIkvUFnBxqUhLMnIK1W1hPu18eGuJSIiIiIiIiKiug8Go2yAVhYAQcZVq1ZK8+bNZcSIkTXfGjLIyEiXAwf2S1ZWpgQEBEq3bt0lKCi4ynsIrz158rgK/CLb1xrzwdycnZ2lY8fO4uLibBL8Ra1fDlhWs8DvhfRiFfjF7fDFAjmaUCBpuaXVWg4GlSMiIiIiIiIiIqrzYPDChQvl0KGD8s9/Pq+yTm+77RZVZxaZpg899LDcdNPsK9ooR4dA7urVK0ym7dy5XSZMmCixsd2ltLRUZfpqg7llZmbJpElTTIK1ycmJcvLkCavrcHNzl9DQEBXsNTdx4mQ7vyPHUFKql7OpRSrgqwV/EfjNKdBd8bLD/JnET0REREREREREV6ZGEaavv/5S3nvvfXV/165d6v9Vq9bIH3/8IS++OJfB4CvMCEYgGBml5lauXC7btm2V7OysCvNHjBhlUqIhJKQsyOvm5iYhISHqcdlAbijxEKbKQTDTt+aKSnRyIqnQJPB7LKFQCo0GfbMmyMdFOkd5SucYT+kU6SGvLk9SmcKWXonwfkSAq/RpxRrMRERERERERERUD8Hg+Ph4Q73YnTt3yMiRo1Sd2R49ekhCQsIVbpJjQ1awLSgbYa3cg3EwuGPHjtKqVStVYoJB3ytzqVAnxxLKg76H4wvkVFKhlFQh4TcywFU6R3ua3DDN+G/i5uokD317UQV+jQPC2jOemMzB44iIiIiIiIiIqJ6CwVFR0bJ58yYZMmSorF69Sp555lk1PS4uTqKjo+2wWY7LWrBXgyCi8SBu2n0EfY15eXmrG1VPZl6pHL0c8NWCvyj9YCFRu4IWIW7SJdpTOkV7qv8R+A32rfwrNjbWX96eLTJvWZLJYHLICEYgGPOJiIiIiIiIiIjqJRh89913yz/+8Yi4uLioDNT+/Qeo6YsW/SwzZsy84o1yZOZBXfNAcN++/WX4cA7Sd6VQZiMlp8QwqFtZ4LdQ4jOLK32ti7NImzAPQ6ZvlxhP6RjlIX6eLjXeHgR8R3Xxkz1n89RgcagRjNIQLs7lGcRERERERERERER1HgwePXq09OrVWxITE6V79+6qRAT07t1bevXqdUUb5Oi6deuuBouzpnv3HnW6PU0l8BuXUVwW8L1YnvWLOr2VcXd1kvYRHirgqwV/O0R6iKebs923E4Hffm187L5cIiIiIiIiIiKiGgeD+/XrKwcPHpZmzZqZTB81arTExnZR86hmgoKCZcKEibJq1YoK8zAd88m6Up1ezqQUmdT3PRZfINkFlRf49XZ3lk7RHialHtqEe4ibC7NziYiIiIiIiIjIQYPB1hQWFoqHh4c9F+mQYmO7S0xMMzWYHGoIo3QEMoYZCDZVVKKTk0mFlzN9C1XW7/HEAskvrrzAb6C3i0mZh85RHtIixF2cWZaBiIiIiIiIiIiaqGoFg7/44nOL97VL8Q8ePCBt27az39Y5MAR+hw0bUd+b0WDkFenkWEJZfd+jl/8/mVwoJZVXepAIf1dDpi8Cv7gfFeCqajATERERERERERE5imoFg5ctW2rxvlqQq5vExETLCy+8aL+tI4eUlV9qqO+rlXs4k1ok+soTfqV5sFt5tu/lzN8QX7smwBMRERERERERETVK1YqS/fTTIvX/nXfeLp99ZpoZTFQTKdkY2E0r9VB2u5hRXOnrUM0B9XzL6vuW1/n183ThH4KIiIiIiIiIiMiCGqVMMhBM1YUyIgjyaoO6qazfhAJJzam8zgMGcOsQ6VFe4zfaU9pHeoiXuzP/EERERERERERERFVU4+vnt279Tfbu3StZWVkV5j399DM1XSw1AaU6vZxNLTIEfFWd3/gCyS7QVfpaL3cn6RRVFvBVwd8YT2kT5iHurqzvS0REREREREREVOfB4Pfff08+++xT6dmzp/j7+1/RBlDjVlSil1PJhSrgq5V5wEBv+cWVF/gN8HKRztEeKuDbGQHgGE9pEeIuLqgBQURERERERERERPUfDP7xxwXy0Ucfy8CBg6SuZGdni6urq3h7e1t9TkFBgWRmZkp4eLg4O7OEgL3lFenkODJ948syffH/iaRCKam80oOE+7uqgC8Cv1rWb1Sgqzg5MfBLRERERERERETUYIPBJSUl0qNHT6kLX331lbzxxhty4cIFKS4ulk6dOskHH3wgAwYMMDxHp9PJQw89JJ988ol4eHiIl5eXvP/++zJr1qw62camKCu/VAV8tWxfBH7PphSJrvKEX2ke7KYGczOUeoj2lFC/GlckISIiIiIiIiIiIjuoUYSud+/esnPnDhkxYqTUptLSUtmwYYP88MMP0rVrVykqKpIHH3xQJk2aJCdOnJDg4GD1vNdff12+/fZb2b17t3reRx99JDfeeKN07txZPSbbUnJKDJm+Kvh7sUDiMoor3W2o5tA6zL18YLcYT1Xv19/LhbuciIiIiIiIiIiogXHS6/VVyPU09eabb8gPP3wvM2deIy1atKhwqf9NN82W2hIfHy8xMTGycuVKmTBhgprWsmVLFfx95ZVXDM9r3769Chq/8847VS5DERAQoAbEa6p1kPGnjs8sLsv0NdT4LVTB4Mq4uoh0iCgr89A5ykO6xHhJh0gP8XJnOQ4icow2lIiotrANJSJiG0pE1KAzgzdu3CCRkZGybdtWdTNXm8FgZARDdHS0+j85OVnOnz8vgwaZ1i8ePHiw7Nq1SxqrUp1e9pzNk5TsEgnzd5U+rbyrNbAaXn8utcikzAP+z87XVfpaLzcn6WhW5qFtuIe4u7K+LxERERERERERkUMFg5cuXS714dKlSzJnzhwZM2aMdO/eXU1LSUlR/4eEhJg8NzQ0VLZt22Z1WYWFhepmnJGh1R/GrT79eihHXlmWLEnZ5Rm7Ef6u8sTkcBnT1a/C84tL9HIquVBl+R5JKAv6HksslPyiypO+/b2cywZ2i/ZQdX7xf8sQdwuBZ73oqlIwmIgavaoMwNmQ21AioobejrINJSJiG0pEVF/H841mVC90mmfOnKnqBqM+sPmbxKB2xjDYnIuL9dq18+bNk7lz51aYnpycIPn5uVJftpwslrkrCipMR2D4oe/i5anxnhLp7ywnUkrlZIpOTiaXytk0nRRXIfYS4uMkbcOcpX2Yi7TD/+EuEuHndLnMB/ZfroguV1LL4utE5KCioppV+pyG2oYSETWGdpRtKBER21Aiovo6nq9yzeDPPvtU/X/nnXcZ7luD59gTAsAzZsxQJSI2btxoKBEBOTk5qj4lBpm7/vrrDdNxPy0tTX799dcqZ2Q0b95cMjIy6q3eJUo7jH/9tElGcE3FBLmpLF8t6xelHkL9Gk3sn4gaYWZwfbehRESNOTOYbSgREdtQIqLa7odClaODa9asMQR6tft1EQxGIBgZwZYCweDn5ye9e/eW1atXG4LByApet26dPPjgg1aX6+HhoW6WdlpVdlxt2H32UrUDwUjqbR3mroK+XTC4W7SnKvcQ4GU9K5qI6Eo1xDaUiKixYBtKRMQ2lIiovlQ5GLxgwY8W79em0tJSufbaa9VAcIsWLVKB4bNnzxpqAvv6+qr7zz33nMyaNUv69OkjAwcOlDfffFOViLjnnnukMcFgcVXRt7WXjOvmrwZ46xDlKd7uDLwQERERERERERGRbQ26bgAumdu3b594eXnJTTfdZDLv1VdfNWQCT5s2TZWJ+Pe//y3vvvuudOvWTTZv3qwCxo1JmH/V/hz3jgmTfm18an17iIiIiIiIiIiI/r+98wCTonjaeBFEckZAgkSJR5QsGclJJYgIiEgGQUByjgpKEP2DgCIoIhJVQJQgIigZBEQyioIc+cjhYL/nLb4ZZvd2b3fn7ry92/f3PPfAzs529/R0V1dXV1eT+EPiqBhqly5dIidOnBCEHc6bN6+8+GKzaI0VmS5dOtMT2Bsvvvii/sVlSudKLpnTJJZzYeHiLpAzjnnD97iPEEIIIYQQQgghhBBC/MFWfIHff/9d6tWrI/Pnz9ND2nBgEP5fv35dOXjwoJ0kiYgkSphABjXMbBp+rRifBzbMrPcRQgghhBBCCCGEEEJIjHsGT5r0jtSpU1cGDRosjz32mHlo24QJ42XixLfl00/n20mWiMhzRVPLlNYiE1aGSmjYoxjC8AiGIRjfE0IIIYQQQgghhBBCyH9iDN63b59MmTLNNAQD/L9nzzekVq0adpIkFmDwrVE4lez686YeKodYwggNQY9gQgghhBBCCCGEEELIf2oMxoFuly5d1Ji+Vi5cuCBJkya1XRjyCBh+eUgcIYQQQgghhBBCCCEkVmMG16r1nLz11luyfft2uXXrlv5t375N+vfvp98RQgghhBBCCCGEEEIIiQeewf37D5BRo0ZKhw7txeFw6LUECRJIvXr19TtCCCGEEEIIIYQQQgghcdwYfO3aNdm/f780adJUOnbsJOfOhcIULHny5JGsWbPGTCkJIYQQQgghhBBCCCGE/HdhIg4d+kMaNWognTq9Lp07d5SOHTtIhgwZpVKlSjQEE0KizLRp02TmzJkBU5Pjxo2TkiVLyoQJE/7Tso8fP15KlCjhU74GyBtl8FS22bNnR0vZCCGEEEIIIYQQEiSewVOnTpEiRYpKr1699fOUKe/J1KmTZebMWTFVPkJIgHH58iXZv3+fhIVdkTRp0kpISDFJly59tKR9/vz5aD2E8oMPPtB/e/To4fdvDx06JJ988oksWbJEsmXL5jXt6Cr7kSNH5OOPPzbzHTZsmJQqVUqef/75SH+HAzxv377t9juULWXKlFEuGyGEEEIIIYQQQoLIGHzgwAFZunS5ZM6cWT8PHz5SWrRoFlNlI4QEGDACf//9aqdr27dvlbp160vRosUk0ICB1C7Hjx+X4sWLq2dwdKcdGUePHnXKt3v37pIsWbIYyYsQQgghhBBCCCHBhV9hIq5cuWIaggFiBF++fDkmykUICUCPYBiCcWik69+aNav1++ggLCxMXnvtNSlXrpyMGDFC7t+/r9eRz4wZM6R69epSsWJFefvtt+XBgwf63d69e6VRo0ZSpEgRKViwoHz77bfy22+/qfcu/nBt8uTJEfIKDw/XUBAVKlSQ2rVr6+/Ar7/+Kp07d5Z169bpbzdu3Oj0O09pI6Z6p06dpEyZMjJw4ECzfJGV3YprvvirVq2abNiwwa907t27J4MHD9Y6RHrXr1+PhjdDCCGEEEIIIYSQoDtA7tSpv7xey5nzqaiVihASK+zYsV127tzu9rs7d+6oMdITS5YskvDwh4ZbdzzzTFkpU6as1zLMmTNH49926NBBevfuLWnSpJE+ffrI9OnTZevWrWoABTAUp02bVrp06aJ/bdu2lapVq0qiRInkySeflCRJkshLL71khnLIkCFDhLyQFgzAMOaePn1a01i/fr165g4aNEi++eYbjbebI0cOp98VKFAgQtq479NPP1VjLYzZHTt2VGMswjtEVnYrrvkChImAgRz4mg5iDm/atEmmTp2qHs5du3aVIUOGeK17QgghhBBCCCGExG/8NgbXr1/P67UDBw5GrVSEkFjh7t07cv36NVu/vX37jty+fSvStH2hVatW0rJlS/0/DlAbOXKkGoPnz58vFy9elN27d+t3V69eVSMsDKHp0qWTnTt3qtEWXrNGfNyMGTPqv/CwdQfi8sLoikMwwbZt22T58uUyZswYjdebKlUqt79FbGB3acOY/MILL+j/mzdvLvv371djcGRlt5I8efII+cIYbuBrOsuWLZNZs2apMRpez/A0JoQQQgghhBBCCPHLGDx//mesMULiMUmSPC4pU6by6Bl8795dj79NmvRxSZw4caRp+0Lq1KnN/8Pr9ebNm2YIhokTJ0pISEiEexcuXKgexR9++KF65c6dO1caNmzoNS+kbTW2Ir+ohL6xpgXPZCM8Q2Rl9wdf07l161aE5yKEEEIIIYQQQgjxyxhcqlRp1hgh8RiEcfAUygExgT/+eJbHUBHNmrWUdOnSR7kMK1askAEDBqgBEwZeeLcCxM6FJy9iA8Mz1wru7devn/7BWArvXhiD4SGM8A+eKF++vOaB8Avwsl20aJEMHz7cp3J6S9tKZGX3B1/TQZ3hud599105f/681qmr9zAhhBBCCCGEEEKCD78OkCOEBC8w9NatW18SJEgQ4Q/Xo8MQbMTjLVGihGTJkkUPVENcXIA4ufB4zZQpk96DMAoImwAQCgGf8+TJo2EfcIgbwKFw8+bNk/z587s9QA6xdRGDFwdjZs+eXdNBeAdf8Ja2lcjK7g++poND8VavXq11CMOw1ZOYEEIIIYQQQgghwUsCR2QnQgUR8ArEtmoc1GRn+zYhwQI8hPfv3ydhYVckTZq0EhJSLNoMwRcuXFDjMmIAnz17Vg+CcwWhF+CRC9EFIy7uPXbsmISHh0uyZMnUqItD5AxgPMX96N8worojNDRUUqRIYcYaNvKBXHBXBndpG4Zx46C6S5cuyYMHD8zYwp7K7u75rPmiHvBc1rAP7tJBLGF8tuZ35swZNQijLAkTJpT06aPnPbmDMpQQQihDCSEkNqAeSggh/kFj8P/DAYQQQuxDGUoIIZShhBASG1APJYQQ/2CYCEIIIYQQQgghhBBCCAkCaAwmhBBCCCGEEEIIIYSQIIDGYEIIIYQQQgghhBBCCAkCaAwmhBBCCCGEEEIIIYSQIIDGYEIIIYQQQgghhBBCCAkCaAwmhBBCCCGEEEIIIYSQIIDGYEKIX9x/4JDtJ27Iqr1h+i8+xxbjx4+Xo0ePxmr+x48fj7X8CSGEEEIIIYQQQvyBxmBCiM+sPXBVnpt4TNrPPiX9F53Rf/EZ12OD1atXS2hoaLSl9/bbb8uhQ4f8yv/8+fO285s0aZIcPHjQ9u8JIYQQQgghhBBC/IHGYEKIT8Dg++aC0xIaFu50/VxYuF6PLYNwdLJmzRo5e/bsf5Zf8eLFJV26dP9ZfoQQQgghhBBCCAluEsd2AQghgQ9CQUxYGSruAkLgWgJ41a4MlRqFU0mihPhkj2XLlkmiRInkwoULsn37dvnoo4/kwYMHMm/ePNm1a5fkzp1bOnfuLClTpjR/c/nyZRk3bpxcuXJFXn31VSlSpIheHzp0qHTv3l2yZs2qn8eMGSNt2rSRXLlyqTcu0jx37pw4HA6ZMmWK/PLLL+oVDO/gTz/9VPr27SshISFO5QsPD5eZM2dqaIhGjRq5Lf9PP/0kqVKlkvbt20vevHn1urv8YAT+7bffJHv27FrGe/fuadonTpzQtLdu3SotW7bUNBCOok6dOrJ27Vr1hG7Xrp2UKFHCdj0TQgghhBBCCCEkOKExmBCitPjgpFy45uz1a3A3/IFcvvnAY03BIHw2LFyqjjsiSRJ73nCQMVVi+apHbo/f7969W+bMmaNG2woVKui1rl27qtH0lVdekfXr18uiRYvUUJow4cN8YLTt0KGDJE6cWKpUqWIaWFesWKG/MYzBq1atknr16smTTz4pNWrUkG7duknVqlX1u8cff1xy5swpadOmVSNrwYIFJX369BHKB0P0kSNH1EgLg+6BAwfM7wYPHix//PGH1K1bVw221atX13JmzJjRbX7g+++/l5IlS0rhwoWlY8eOcvLkSWnevLlMnTpVNm3apL+DMRjhKL744gs1AsMQXqtWLb0XRmdCCCGEEEIIIYQQX6ExmBCiwBAcetW9MdhXHhqMPRuNfQHGVMTSBbdv35a5c+fKmTNn1KgKg2r+/Pll27ZtprEYxmAYacHVq1dl/vz5apj1xK1bt+T+/ftSvnx5qVSpkqRIkUKvwws4S5Ysmn+1atXc/m7hwoVaFhiNO3XqpEZncPfuXTUOt2jRQn799Ve9liRJElm3bp00adLEbX5Wbt68KV999ZWGqEidOrVT2gZDhgyRVq1a6f83bNighmijDgghhBBCCCGEEEJ8gcZgQojptesJb57BBumSJ/TqGewNI7QCQFgFeL/CEAzgDZwvXz6nuL7W+/EdPGZBggTO4SoQngGkSZNGZs2aJRMmTFBPZHjZIiyENy9bHBSH0A4wBBvG3hw5cuj/4QmM/OANbACDctmyZX3KD2nDExmGYNe0Dayf8dsbN254rUtCCCGEEEIIIYQQKzQGE0KUyMI3IGbwcxOP6WFx7uIGw+yaOU1i+aF/vijFDHY14mbLlk3j9O7bt0+KFSumcYFhUC1QoIB5D2L0wsAKNm7cqLF1AQy3f//9t4Z8wO8Q3sHg+eef1z94Hjds2FCWL18ubdu21fAN8PJ1B8JLwAB7+PBhzR8GacQYNsqZLFkyjUfszqvYU37W57x27ZocO3ZMDdowgiMfQgghhBBCCCGEkOiExmBCiFdg4B3UMLO8ueC0Gn6tBmHDdDuwYeYoG4Ij5JsokUycOFFq1qyp8XZ37twpzZo10xi7Boi7i+thYWEaJgJxdQFCKiD2MH536tQp0xP39OnTGnIB4Df79+83wy0888wz0qdPH/3X9QA5xCQeO3asVK5cWWMT46A3q8fy7Nmz5YUXXtBQEBkyZNDro0eP1mfwlJ817REjRuhvjbRhzIaHMCGEEEIIIYQQQkh0kcBh7J0OcmBEwnZuGGuMrdqEEGfWHrgqE1aGSmjYo9jCWdIkVkPwc0Wj3m/27NmjxlN4AVs5evSoHgwHz1sYag2+++47PYDt+PHjcvnyZQ3TYI3Ju2PHDo3xCwMuYvkibi/Sx+Fy8EBGn4fx1Tgs7sGDB3pIHX4Db2N47LoCL2UYa2G4hREa5cmUKZMZLmL79u1y8eJF/dy4cWM1FHvK74cfflCDs3HIHZ4RYS6KFi2qBmN4B+NePGfp0qXliSeeePge1q7Ve4zfBQKUoYQQQhlKCCGxAfVQQgjxDxqD/x8OIIT4BkJG7Przppy/Gi6ZUieW0rmSR7tHcDACw/AXX3whd+7ckc2bN6sHNA6liytQhhJCCGUoIYTEBtRDCSHEPxgmghDiFzD8ls3zyPuWRA/Zs2fXeMMIDfHWW29JqVKlWLWEEEIIIYQQQgiJVmgMJoSQAABxkK2xkAkhhBBCCCGEEEKim4TRniIhhBBCCCGEEEIIIYSQgIPGYEIIIYQQQgghhBBCCAkCaAwmhBBCCCGEEEIIIYSQIIDGYEIIIYQQQgghhBBCCAkC4s0BcocOHZLZs2dLaGiohISESPfu3SVlypSxXSxCCCGEEEIIIYQQQggJCOKFZ/Du3buldOnScunSJalcubIsWbJE/71z505sF40QQgghhBBCCCGEEEICgnhhDB40aJBUq1ZN5s6dK507d5Y1a9bI4cOH9TMhhBBCCCGEEEIIIYSQeGAMhvfvhg0bpFmzZua1DBkySM2aNWX16tWxWjZCCCGEEEIIIYQQQggJFOJ8zOBTp05JeHi45MyZ0+k6Pv/000+RGpGtYSTCwsL03ytXrsiDBw9isMSEEBLYJEyYUFKlSiUJEiTweA9lKCGE2JejlKGEEEIZSgghsTWfj/PGYMOgmzx5cqfrODzu9u3bHn83YcIEGTVqVITrTz31VAyUkhBC4hZYIEudOrXH7ylDCSHEvhylDCWEEMpQQgiJrfl8AofD4ZA4zN9//61ewKtWrZL69eub119//XXZu3ev7Ny50yePDHgD4wA6hJiIzHr+X3L16lXJkSOHPmNkL5HEH/jOg4tAft/+egZThpJAIJD7FAm+9+2PZzBlKAkEAr1PkeB635ShJK4R6H2KBNf7ThXfPYOzZ88u6dKlk3379jkZg/G5WLFiHn/3+OOP65+VtGnTSiCChhWIjYvEHHznwUVcfN+UoSSQiYt9igTX+6YMJYFMXOxTJLjeN2UoCWTiYp8iwfe+4/wBcrB0t27dWj7++GON9wsQK3jHjh3yyiuvxHbxCCGEEEIIIYQQQgghJCCI857BYNy4cbJ7924pVKiQ/m3btk0GDx4sNWrUiO2iEUIIIYQQQgghhBBCSEAQL4zBcMnevHmzegOHhoZK0aJFJXfu3BLXwfaXESNGRAhnQeIvfOfBBd8365ewTxHK0ECFY1TwwXceXPB9s34J+xQJXhka5w+QI4QQQgghhBBCCCGEEBIEMYMJIYQQQgghhBBCCCGEeIfGYEIIIYQQQgghhBBCCAkCaAyORfbv3y+nTp2KzSKQGOaPP/6QEydOsJ6DmKNHj8qRI0diuxjxEvav+A/7Dzl58qQcPHiQFcH+RWzA/kMw18Sck0Q/7F/xH/YfcubMGdmzZ0+8rAgag6OZCxcu6GF2+NcbPXv2lFmzZkV3EUgM8++//8revXvl8uXLXu8dNGiQTJ48me8kDnH9+nXZsmWL/PPPPx7v+euvv1Sxvnnzptf0xo0bJ6NHj47mUsZfrly5ovV/9uxZr/eyf8VNzp07p0rVxYsXvd7L/hP3uHXrlvzyyy8qJz0B+bpv3z65ceOG1/SmTZsm/fv3j+ZSBvcYZsD+FTeB7Ny9e7ecP3/e673sP3GPO3fuyK+//irHjx+PdC7y22+/ybVr17ym98knn0jXrl2juZTBPYYZsH/FTTCHhwz1Za7B/hP3CA8Pl61bt8rhw4cjnYvs3btXwsLCvKb31VdfSZs2bSQ+QmNwNHqotW3bVooVKyaVK1eWdevWRVfSJECAUClfvryUK1dOXn31VXnyySfltddek3v37sV20Ug0gIlz9+7dJX/+/FK9enX5/PPP3Q4GBQsWlCpVqkirVq0kc+bM8u6777L+owF40L/++utSuHBhrd8VK1awXuMZULqqVasmJUuWlA4dOkiOHDmkZcuWOvEicR8o1m+++abkzZtXatasKTNmzIhwz7fffishISE6lr7yyisqQ3EKM/lvxjAStzl06JDUrVtXihYtquNlrly5pFGjRnL16tXYLhqJpsXwgQMHqgx97rnnZNKkSRHuwfzymWeekdKlS+u8M0uWLNK3b1/hefD/zRhG4r4nd9OmTaVAgQLSsWNHHS9r1arlkxMfCXzgYDB8+HDJkyeP1K5d261+icXySpUqqS7avn17yZo1q3Tp0kXu378vwQiNwdFoDIYwsbMd/MGDB3Ls2DH9Lf7vDny/c+dOtwofPKzgvu6qMFpXlI2QFDBcwhvn999/97ucwQ5WiGfPnq31CKMGVuRhHPzoo4+8/hZKGoxdaCeehA0GqB07dqgy6EtIEbQJ64qXsWUe6R84cEDLZ4B2g3YCTwLiHvQXGCJRp0888YTbe/AOYMxAW0AdL1q0SD3WfvjhB5+qFb9D38OKpaf00QbceUximzTaiJU///zTqS8bW+ohR3D/rl27nLzF0CZ88RaLDVDvWGjBMyRLlsyv38Z2/yK+gfaKxZPTp0+rRwbqd/369fLee+/59Hv2n8AG7wcGfvQPTKY99cMvv/zS9AxevXq1TJgwQcdSX8DvkP7du3fdfo+2tX37dp3UuwLZCPli5e+//9ZyWMsH2QmZAj0KaRlgJwju9cVbLFDHsEDtX8Q3UMfDhg1TXQ4yFJ+hj/q6+4j9J7CB/EqbNq2+2xIlSnjs59hVinkf9JBNmzap0RLzE19A24Ecu337ttvv4SkJueduvmDoWa7pobzuttSjz8PD2QB5Qn4jnUA0XvsyhgVq/yK+gXEJO7PxDjAGob2inrEI4wvsP4ENdsskSpRIHfjgWOQO9DPMRUJDQ9U2gnaA+byvcxG0HcheT44sKAP6prv5truQI8b97kJSQFZil4JhH4RsgV6FZ4g2Geog0cq9e/fwZhwLFy70em/VqlUd9erVcxQoUMBRvHhxR/r06R1ly5Z1XL161bznn3/+0Wtp06Z1FC5c2JE8eXLHpEmTnNIpUqSIY8qUKU7XXnzxRUfnzp0j5JU3b17Nq3fv3tHyvMHO008/7Rg4cKDH75s0aeKoUaOGo2jRoo6QkBBHpkyZHMWKFXOcO3fOvOf8+fP6flKnTq3vMmnSpI7hw4c7pVOpUiXHiBEjnK516NDB0bJlywh5FSpUSPPC92Dy5MmOFClSOEqUKOHIkSOHo3bt2pon8Uy2bNkcEyZM8KmKcuXK5Rg2bJjH79u1a+eoWLGio1SpUvp+s2TJou3m1KlT5j1hYWHaP/Ge0FbQBt58802ndBo0aODo1auX07W+ffs66tSpEyEv9HHkZbSP2bNnO1KlSqXtInfu3I7KlSs7Tp8+HbBNAPUwY8YMr/cFQv8iUQPjW5cuXTx+z/4TN0FfGzBggE/3Ymzq2bOnx+8h9yA/IdvQ/7Jnz+546qmnHIcPHzbvuXnzpuo90JHQP9HPO3bs6AgPDzfvad26tbYnK2PGjHGUK1cuQl5olwULFlS5C7788kvVw/Bc+fLlc5QpU8Zx/PhxR1wfwwKhf5GoAZ3upZde8vg9+0/cBHqJdR4XGdWqVXO0adPG4/fQbyA7ocNgzgn5mTVrVseePXvMe+7evat9FP0bMjRZsmSOVq1aOW7fvm3e0717d9WFrEyfPl3TtOYF2VmlShWVJdC/wMqVKx0ZMmTQ73A/dLXff//dEdfHsEDoXyRqtGjRwlG3bl2P37P/xE3QP3zVM5o2bepo1KiRx+9hZ0O/RprQAWFPy5gxo2PLli3mPffv33d069ZN+zd0JfT3xo0bO65fv27eM2TIEFMmGnz22WeOzJkzR8gLbTJPnjw6FkCG/Pjjj3of8odNEHJ0586djqhCz+BYBtZ+bIfGyj6s/1hxmjlzpvk9tvwlSZJEVxewErB48WL1RNy2bZvfef3000+ybNkyzWvKlCnR/CTBE8cLMaHhCfrGG2/o586dO0f6G6yKz5s3T1d3sSIJ7+ypU6ea3/fr1089dw1vU6SNOH7ff/+93+WDhwBiGyGvOXPmqDco0kcbwyoTVqTQfrAaRqIOVu/wly9fvkjvw4of3jneL9pAmjRp5O233za/x5YW9H/8YcUQW1jg6YGVSn9Be8PWQuQFDzx4svbq1ctsF8gDebvuJoirxGb/Iv6D9ggZiq2u8MTA2AYvjchg/4nfcfvg6eZNhmL8GjJkiOmBivtHjRplfv/OO++o1yq8YtE/4akGb2M7/RS/feutt9QDbuXKlXoN470hV+GRAT0NXl7xgdjsX8QekKHYVYE+AJ0eYQIig/0n/oIdC5CL3mQo5Bm2xcOjFH0ZO7EgUw0+/PBD3amBPm7sIN2wYYOTPuUryAMhLCCPN27cqNf69OmjYz7Kge8XLlwYb2RobPcv4j/wHEX7xrvBv948g9l/4i/37t1TT19vMhTzyIYNG6oOiN2jDRo00L5oMH/+fA3Phb4OOYr70N/Hjh3rd5mQFyIOQD/GeI8dswMGDNDwUEgX8hnyOjp2fNMYHMu0aNFCY5ACKOCIp2i4j1+6dEm+/vprVcRTpEih1+rXry9Vq1ZVg4S/PP/88xrTmERt4ooBAwamjz/+2Ix7GRkQHKVKldL/J0+eXDu38Y4hgCA4cBAWtoYBxJxGDDg777hOnToai9HA2O5p3bKEOFhFihTxO20S0aiFmNG5c+fWfhwZiN+I9woef/xxjfln3SYyd+5cncwZW3vRXl566SVbbaBixYoaa84AW0tQVmsbwD2IORcfiM3+RfwH26oMGTp9+nSdMCJmW2Sw/8RPsMWtU6dOki5dOmnXrl2k90JeQf8BiRMn1v9bZSj6c48ePSR79uz6uVChQhoLzk4/x/jYrFkzp2sYS60yFDLHkOlxndjsX8QekKGYhE6cOFHfhTedjv0n/oKFKshSb44pGGfRVkDChAlVD3KVoTAWGwYR6LY4dM5OP4ccxvwoMhmKkDbxRRbEdv8i/gNjPWTomDFjpEmTJuY8whPsP/GXQYMGafgryNLIyJQpk8YWNmjcuHGEfo6zMBDTH+Bsqd69e9vq56lTp9bfuspQ6zlViIuMOXBUoTE4lnGN6wZjBlZ5AVZugWEsNsAgEtkJs57ImTNnlMpKRA9qwAqNsbILY4a3FZ/I3jFWfmCoi6l3DAMYvHBgrISygoHPGtuL2AMGVhiCsZKIGMJJkya13QZwaAE8V2OqDTz22GPaTjGAFS9eXAcXrIjHF2KzfxH/SZkypcpQeLPBi+aLL77Q3QqRwf4TP4HiDY+cb775RhfD7bYBGBjgYR6T/fyDDz6QoUOHqgEDk3rstIovxGb/IvaADIUuh3eAXS7dunWL9H72n/gJ4kfDQx+OQziM024bMOac7vo5PF39jU3pzkkGHsb4e/rpp1UftbM7K1CJ7f5F/Oe7777TWLGYJ8CzG44JkcH+Ez957733dFfEkiVL9EDWmGgDiDGMndr+kC1bNo19bAX2HDg4YaEOHsKwP0QHNAYHMFgVAK4N6Nq1a04TpwQJEkQYqN0Fr8dKMIk+cBIpVhMxoATyO8bWLAQnxyE9+E2FChVk6dKltssc7OA9QAgj3MCPP/7o1avRG6lSpdL3FpNtAN4eaANQxBF2Bp5g8PaK71CGBjZPPfWULlRFRYay/8RNcGL7ggULZO3atbpIFRUg07CFLiZlaKtWrTS8Eg6MRZrwxgiGcFv/Rf8iUXNQaNOmTZRkKPtP3GTkyJGq0+HdQ6+PDn3JXT+HDED/jmo/hycytjQjrFfWrFlVpo4YMULiO/9F/yL2yZAhgzr3REWGAvafuAfk59ChQ2X58uXRskvBUxuAU5ZxMHpU+nmNGjX0sEOEmIFXMGwRCAMZVShRAhhY/iGk1qxZ49Rg4ElTpkwZJ2UQjcN6D7yuSPRy48aNCNcQMwbvyC5YZcIqr/Udw+sUhsbI3jHu2blzp9f0cXIvPCMhhCDopk2bJrVr13bKj/hvCEacHvRD1xVAO2BbLraUuL4TfI6sDQBfThKGPMAf8oERGNtKscUMzxDfien+RWJfhrL/xD2wQAmDAAzB3rZm+gp2vrjKUEzuokOGYgxFeBMo9AingJjjr776alDI0JjuXyT2ZShg/4lbjB49Wj3aIIOeffbZaEkT/TmmZCiAkQSebjBcwwiMM3GCQYbGdP8igSFD2X/iFu+//76Gh1i2bJmGxooOPLUB6LmGl29UZSiMxMhn8ODBuqsyOmRo4iinQJQrV67ogRiYNAAEicc2Lqx+5s2b11YtYeKBSQcmTlhJQBwnuLIjHhG2KRq88MILGj8MCjuMH/BcwdY+Er1AWCBmKDo1jGs4zA+HoeAgpKgA4xziJcJgGxISorFlEJsYMTWt7xjxt8qWLavGLUyksbXFWwxo3APDHzxDsb0VW5KwvXX27NlRKnN8BJN9bBkCeL+oO/RhxLM04vFhBe6zzz7Tfoj4QvjeEO7eAs9HBg7rgZc58sI7xsEaCBCPQcraBnAPVjLhlY6VQcQq8ha3EuXEaiLaANoXtqthcIJsCSSweoqwG4Yx1giajxhNeN5A7F/EPyCLUMdQZPCOscUJB6AgTEBUYP8JDBDLzDjcFlvnIGvQh+EtYfQlnIGARUl41ULmGjI0Y8aMUVpcGz9+vMo5yGKcvYBt0xifDZlunJswefJkbS8lSpTQ9vfzzz+rXIgMlBPjPmQEfoddFpDN3uLLBeIYFmj9i/gHxjLsRoJBDZNCLGxCJ0G4najA/hM4Dgc4oBEgPMvZs2e1D2M7srFwBhkGYyreGeaGhgxFWDgjVqVdAzPORIBcq1evni7WYXw20gfo45DhyB/xvzH/wT1GLNzIgOzEIhoMo5gzo816O28jEMewQOtfxD9gP0mfPr0uomCxEwccIgzU//73vyhVJftP4PDLL7/oHANzPTjFoQ/DQx/6C8CZT5jP49DHVKlSmTIO/4/KTjXIRvRdOI1BJ4Isx6Fy1pA4OHQOdj2cwwCbEvo4dCrDczgy0GYhg3H4JxY1MJ/FOTlRhcbgaALGX+MkykqVKukgir+mTZs6GR2sQMBjm6wVGJRg/DDAgQD4jO2UGBjQSPHyEXfRALGXoEBAMUdDhrKIxmjdfuIuL+Ifq1at0sECp4hDAUMcGLz3yOoVBljr+wSISXPnzh3zc8uWLVXRwLZ9KPaYtOEkSkyODbCdCgJtxYoVOnhhuxUUQ0z+IssLkzLEwUG5obDheyhg0RFwPL6BCb7RhxHTDBNZfIZy/O677+p1xP3BYAJjoRW8D5zy6Q6kZSwSWeOpoY8aQPHGYAEj/aZNm/Q3WCm0xl3DPRhUEB8OgwcGkdKlS+vp75HlhQUprBzCgI08MKHHSfDNmzeXQAIrpUb9o21DUcYfBjpshwzE/kX8A+FpID9xgjYUNbRXxA2OLNQK+0/cAQs6Rh/GwRmQTfiMPodFanDmzBk1ZMFYiD8D7FrAQS7uwHY49EtXuWY9BBN6FxY6IecQVw07qxAb3WpghvEC2wEhvzHhx+Qck0BrDHV3eUHfQkggxF6HERvyBBN2HBQS18awQOtfxD8wF8B7QBvGOIc5AxZRIzP2s//EHWCMNPow5Awce/AZ8wy8e0NXgrzDnAR/Blhk9RS6BovcrsZM6DPWA3Exv4QRBR5zkKHo3zCSWOWssUsAbRA7UGGcwHhujV3pLi+AtCFDsRgI4zaeC9vz49oYFmj9i/jHrFmzdD6AuTAM/ngXqO/Idimx/8S9WOoYH2GrwdwOfRie31iEAejX6JNYCNi4caP5O/RHyDNPMXxd2wjm09adGXD+hG6ERR3oXJAD2EVsvQdz1PXr16ssgKyFPowFXRioI8sLQA+FTMBvIQdwwCcOYY4qCRz+RoUnhBBCCCGEEEIIIYQQEudgzGBCCCGEEEIIIYQQQggJAmgMJoQQQgghhBBCCCGEkCCAxmBCCCGEEEIIIYQQQggJAmgMJoQQQgghhBBCCCGEkCCAxmBCCCGEEEIIIYQQQggJAmgMJoQQQgghhBBCCCGEkCCAxmBCCCGEEEIIIYQQQggJAmgMJvGKv/76UzZt+ilg0olrefvKgwcPZPfu3bJmzXdy/Phxn36D+7Zs2RKD5dkl3333sDxHjx6VrVt/jfZ6/+eff2Tjxh+jWFpCApczZ07Lhg3rAyaduJa3P/z2228qQw8fPuzT/adOnZKffoq5sWHv3r1mef7880/ZvPnnaK/30NBQWbt2bRRLSkjgcu7cOfn++zUBk05cy9sfDhw4oOXEv77w779nZN26df9JeaAv/vjjhmiv94sXL8rq1aujWFJCApfLly9rG8fcLhDSiWt5+8OhQ3/IDz98r/qfL1y4cF71xJgsD2QgyvNQX/wh2uv96tWres+9e/eiocRxHxqDgwgY4tD48QdlaNeunXLt2jWJb884adJEv37jbtJrJx07xGbeUaFr1y4yfPhQndSfOvWXT88FpXjatKkxUp7u3bvJ8OHDZN26h+XBwPbhhx/6lYYv9b5z5w4ZP35cFEtL4irbt283ZSja/o4dOyQs7IrEJ3bt2iWjRo306zfuJr120rFDbOYdFfr27SMDBryl7ej48WM+Pdevv/4ib789PkbKg7IMHNjfLM/PP2+Sd9+d5FcavtT7gQP7dewgwQkWkR/J0B9k+/ZtcunSJYlPHDx4UAYNGujXb9xNeu2kY4fYzDsqjBo1Qnr3fkP1PXcLau6ea8+evTJy5PAYKc/YsWOcygN9Edf8wZd6h8ND//79olhaElfZv3+/kwzdtm2rGujiEydPntA27o+xzlgkcTgcUUrHDrGZd1SYMmWydOnSWY270M18ea5Dhw7JgAH9Y6Q8sBGgPA8X1Pbr3+DBg/xKw5d6h+MC7rl161Y0lDrukzi2C0D+O9DJbty4LoUKFZb79+/LuXOhqrBUrlxFBg4cJJkzZw7K14FJ79KlS+TZZyub1556KpdUqVIlXudtFwjRLVs2y5o1P0j27Nl9fq6YAp4eyM9ankAefEncZdasmeqdWaxYcZWh58+f11XssmXLyeDBQzz2h/gOJr3Tp78v1avXMK9ly5ZNatSoGa/ztgsWYaHsLl68RMdjX58rprh+/bqsWrXKqTyQqf+F/CbBxWefzZffftsrpUqVlgcP7utkEwaw4sVLqAzNkyePBCPGpPe552qb1zJnfkLq1Kkbr/O2C8bf5cuXy6xZs3X89fW5YrI8S5YsdioPFov/C/lNgovFi7/SheJy5cqLw/FALl26LL//fkAKFSokgwYNloIFC0kwYiyS1K5dWxInfmjeSpcuvdStW08SJkwYb/OOalsaPXqs1KpVy+fnikkWLfrSqTzYYVG7dp0YzzfYoTE4yKhYsZIMGfLIK+fs2bPSr19fad++nSxZslSSJ09hfgeD2r59v+nEFQp6zpxPRUgP92CVEi73RYsWkYwZMzl9f+PGDdm7d4/cvXtXQkJCInyPLaUFCxaUhAkTycGDv0uWLFnlqaee0q2wNWrUkL/++ks9PUNCikmWLFn0N3///bccPXpEBW3hwoXl8ccf9/i8eD54ooDkyZNJ7ty51dhqNWz+8ccfcu3adXPbVZEihSV79mw60Lryxx8H5Z9/TkuWLJmlaNEQSZAggZPQRH5ly5ZVIzsmOShfpkzOz+xv3o/SLSOHDh3WFWDUR8aMGbVejfqFgSp16tQR8vGnvrw9JwxhxhY2ePTs27dPqlWrJsmTJ/f6XNY2461+fC2zu/IYlC5dOsp1gW0me/bs1tVDtFNCSpYsJe+888iDHO0Yq+Tt2rWRpUuXS9q0aZ0miGiTV65cVrnjztCBe6DwXLp0UQ1xhpwzQNvbs2eP3Lp1U4oUKRrhe4Q2gcxMkSKFpoO2jba6fv16qVy5si76nThxUq/lyJHDXEBBH02TJo3mae2/rly4cEE9okHSpI/rc+TNm9dpWyue8fbt22Z/L1DgaS0n8ncFIVwg1zNkyCDFihWTRIkSOfXnkydPyrPPPitHjhyW0NBzWm7XZ/Y3byPdSpUqyZEjRyQ09KwULlxEF0Ahj7AdDfULGWp9fwb+1Je353y4TflhKAWMTSdP/qnPa5Xdnp7L2ma81Y+vZXZXHoPy5ctHuS7gUYJwGFevhsnTTxfwWm8k/gNjxbvvvmd+xu6KYcOGqgxdvHipU3vGGAyjHuRQjhw5JX/+/G7b2O+//y7nz5/TNobFICt37txRPQmLHgUKFIywaAeP+yeeeELSp8+g/S5lyhQq59esWSMVKlTQtnv06DGVe9AhjT4KA0zKlKlUl4D89URYWJgZIitJkiQqr63PgW2t6Hvo10Z/z5Mnt2TIkFH1K1dOnDihf+nSpVUjunWSjv75++8HVX+GDPr33381L9c68TdvI93q1aurDnXmzBmVPU8+mU1/+7CPYx5QVHVTV/ypL2/PCR1448afJDw8XOcfFy5clHLlyqms9fZc1nblrX58LbO78hhgzImOukC68KDPnz+f13tJ/CdXrtxOMhSybcyY0fLqq+1k0aKvnOa5kI9YcDt79l/Jli27x7kM5n3oD/ny5Ysw3zf0JMgytEFr+sbCR6pUKSVr1ifVbvDYY49J+fIVdH4GWYrfw3ECMvzpp582dWe062TJkqou4W7+anDz5g3tYwBpQ5ctUKCAOTeFnQJzQIA8EyRIqPdA1sMxwKpnGjoh5FiqVKmlZMkS8thjSZz6886dO9WQe+zYUZ0LQ3a4s4H4k7eRLhbZIHtOn/5HxxSkC3mEurh8+ZLqphiPXPGnvrw955UrV9SpCzIb7wU2BMyZrU6Bnp7Lirf68bXM7spj4G4MtFMXaN/QmYN1wTkyaAwOcqB0v/feZKlT5zlZtmyZvPJKG72OCfMbb/SQlClTqoEWnhwQaiNHjjKFL7YK9O7dC0ON5M6dRyZMOC7dunWXJk2a6vcQIvgeShaUnv3790mfPn3l5Zdbm/ljSymUd8RrxQQBimbSpEl1Japq1Wry99+nVFGDgIJwHD16lKxfv06NoRCsEBzTpk3XQcEdMIQYMQxv3ryphj2sMo0aNVqvwcgKQYmBxrgPk1yUZ+HCL6RKlarmZKJXr55qbIFRG5Ph7NlzyP/+N8MUQlipxaoWjDEYFDH44b73358uFSpUjFA2X/NGul9+uVCSJUsmmTNn0YkJDBsw6n/88RwdfC9evKDK74IFX+hngMHF3/ry9pwYvDDog02bNqlyDoOB1SDg6bkABrrWrV/2WD/+ltldeYwBCoMflBG7dQEjXJcundQ4AmM2DNgcRIgrmIBChtaqVUP7bdeu3fQ6FrG6d+8uiRIl1D4Eg8Yzz5RRQ7KhHCKcCuQsZFP+/E/r9qa2bduZMhIys0eP7mqkyJAhvSrjnTt3kY4dO5n5I7QJZCMWOtCWseCXLduTKkMhQyBPcD1NmtSqyE2c+I6sWLFcJ9eQJeivU6ZMVUOoOyBXjH6MPgGjCvrrpEnv6lgA2QMlC7LDuA8GDxhXEWbA8NDFpPytt/rK1q1b1TgK4wom+TNnzjKNBzDKfPjhBzpheOyxxKp8YmLxzjuT3Hou+Jq3kS7eFeTznTu3VfYMHjxUFiz4TK9j8QoLWfPmfebUz/2tL2/PCWUU5QG//PKLyvUSJZwX8jw9l7HA2rZtm0jrx58yuysPQLuBjLZ6B/tbF/h9z57dzfHkyJGjTgsJhIA0adJqG65du5bMnz9P+vcfoNdhmED7QT+A8QF9FrJs6tRpZn+AkfKNN3qqsRg65J9/npSmTZ9XOQkw6e7atbMkS5Zc9V3IL8jXN9/sY1Y+PPCRHgyckMOYFGMRHDIUO+egb8HrDrotjMGQJQsWfK79G7L7zz//kkmTJrl1IADQNYx+DNnz22/7pEiRIqr7wLCBiTBkPfQU474HD6pJypShGjLA6qE7dOgQ3RpeokRJ7aOY3M+aNcvU+4wwCCg/JtTQpxESbuTI0dKkSZMIZfM1byNd6PpYFAQwAGNXIeYO0AFhDEWImTlzPtHnM/C3vrw9J4yt2LkAsFCZKlUqXSyzGoM9PRccT1Avr7/eIdL68afM7spj6Kcw/Fq9g/2tC5S/X78+8uuvv0rx4sXVOYQylLiCufrYseOkQYN6Mnv2bP2/YTSDfMS/MOJibg+D8PTpH5iLEJCdmKvDcIi5DnRJ6E6YrwNcx1wIRmUY/HA+S+PGTWTYsEfhVubMma0GaegukBFYFML8CzIEDlKQoZDP9erVU2Pwp5/OlY8+mqnzMegJWNweN268VKtW3e3LvXnzltmP0W+hT6MsM2bMVJ0FepHh+LVhwwbVTbFAdO/eXZXjNWvWNJ1/3nnnbfXih5EafRRyC/qZsdAH20b//m/JN998owswmL/CnvHWW/2d7BcGvuZtpIt5Qnj4fZWjmL/27dvPjGOOuQEWimbM+EieeeYZMw9/68vbc0J/Q1kByo65SM6cOZ2MwZ6eK2vWrNoWunXrGmn9+FNmd+UxbDgY9627O+zUBRabjYUJjCfGuyb/j4MEDc2bN3OMHTvG7XetWrV09Or1hv7/3r17jrp1azs++eRj8/vLly87atSo5vjmm6/18927dxzPPVfTMWBAf70f3Llzx/Hzz5vM/9euXcvx9tsTzDS+/fYbR/HiIY6//vrTvFalyrOORo0aOK5du2ZeO378uKNIkUKOgQMHOB48eGBenzfvU0eTJo0cV69eNa9NnvyePpfBggWfOxo2rO+xDkJDQx2VKlVwbN78s3lt/vx5mq4V13TmzJntqFatiuPcuXP6+cqVK44GDeo53nnnbfOe2bNnabmNOgCjRo10tG79ssfy+JK3ke6WLVvMa6++2s5RtGhhx86dO/Tz/fv3HS1btnC8++4kv+rLFV+ec//+/VqesLAwv57Ll/qxU2Z35fngg+mOV15p7Ve6rvX+0UcztY1funRJP58/f85RtWplvUaCkw4d2jv693/L7XedOnV0vPbaq/p/yK0XXmjqmDZtqvn99evXHfXr19V2ZvRZtMmePburvASQpRs3btT/h4eH6/dDhgw25SC+Cwkp4vjjj4NmumiztWrVUBltgLaKPoG0kY7BsmVLVS5fvHjRqc/Xq1fH/AwZD7nsiYdjQXXH6tWrzWvLly/T8cGKazqLFn3pqFChnOOff/7RzzduXHc0a/aCPp/Bl18u1HJb00Y/bdy4ocfy+JK3ke73368xr6FucO3HH380r3Xo8JpjxIjhftWXK748J8ZA5G3c4+tz+VI/dsrsrjyuMtxO21m48AtH5cqVdNwFV65cdtSp85yjfPmyHstC4je9e/dydO3axe13ffv2cTRv/qL5uV27No5x48aY8u/WrVval2bOnGHeA/0BcvnmzZumXLX26ZdfbqV54jrYtWun6k7bt2930n+ffbaiqfeA27dva5+ATIe+a7B27VrVA/7991+nPl+9elXzPuRfsmRxj3WAsQB6FX5nsG7dWsczz5Ryus81HfT70qVLqo4MMG60adPa8cYbPc17Vq1apeW2po1+ivJ5wpe8jXQXL15sXhs8eJBeM+YFAHXdp09vv+rLFV+eE3oZ8raOhb48ly/1Y6fM7srjKsPttJ2VK791lClT2vH333+bbadp08aaFwlOhg0b6jS/sTJy5AhHnTq1zc89enRzDBo00NQD0c4gVydOfMe8p0uXTioDrfOjDRvWm//v3Lmjo2PH1x13797Vz2jjmMtb74H+a22nBmjLmJsa8hls3fqr6kh//nnSqc9XrFjetAVATqONQw67A9cxFqDvGmzbtk1/Y9gk3KWzefNmR7FiRR0HDhzQz7gXz9++/UPdHWCOit9Y00Y/xfMZ44grvuRtpGu1rUyYMF6vGfMC4/2+/noHv+rLFV+eE9eQN8ruCXfP5Uv92Cmzu/K4ynA7beennzY6SpQo5jh69Ih+xvWXX37Jqx0jmAjcQCbkPwUeS/DaBFglx+E1uIaDELCasnXrr+qtZWwX3rFjp3pRwLvC8MaEZ4XhRQSPgdOnTzt5sDVs2EhXnVxP8oUXB1Y1XXn55ZedwjAgPhi8iOHFhDIh4Dm8qRBeAiuSnsAqIrZZw8sAWzRQBmwv8Ifvvlut5TRCGmAlrGXLVnrdCraFWD2pypQpq54qUQWehRUrPvIuhlcBvNdKl364coiYRMWKheiKV1Tqy9fntP8ckdeP3XfsDTvp4j7URbp06fQzQpxgNZwQd0BeInYbwEo2PMmffPJJU4bCcwgr74YMxbbmY8eOyRtv9DK93CBLq1atanq04fuOHTuachDfwasC25etNGjQ0G14A/Rd6/Y4eHXi94hHa/QDeFXA8wNeeJ6ARwFkOg4Xg/coPOwOHHgUksUXvvvuO6lfv4G5HRchibATxfXkdPRLeI8YwKsE4RasB1jYAbLMGnsM3q3wqLZuQYPnleGRYLe+fH1Ou3irH7vv2Bt20kU7Rds0tjzCA/TFF5vZLgMJBhn6UA+Fdxr0Neid0N3Q5jZu/FF3NxhbV6HvwNO3W7cepkc7dCGjT8PTH7vaXnutgxm3EbGKsUPD9TR0yAZ3IauaN2/htIUY/SBfvvzqkW/0A3j3wgPUGmLFFWMbMPRfhEHDjjs7eii8zIydCxg3Xn21vXrMwXvaAOOItZ+VKVNGy4fdWlEB6T7//PNO8hL13qhR40hlqL/15etzRuU5Iqsfu+/YG3bSxX2I12mENoE3J8Z1QrzN5eEdv3HjRg1Lg12RaEsIH4bQLjt2PNRDIW9//vln6dy5q+nRDgxvdsyPNm/erP0PbRXAwxe7zqDrWIFnprtzM1588UVTPj/sByvUexg6stEPEPsYYQkOHz7k8cUa4S7wLHgO6KH+y9BVunvO2LkAWfDaa6/rmALvaSstW77kNFeFJz/6alTBmGLVQzE2NWvW3OmadS5vp778eU67RFY/dt+xN+yk+/333+sOH8heAC/t1q1fsV2G+AjDRBBzO4AhrGHEhQEBCqvrIGO41mPy9zBsgftD52Aoxrax9OnTO12HIo/vnNN1H1PX9ToUe8SH+eEH59OBEdcHsRXdGZSxTaxnzx4aMgADIraEYYBEfE5/QJlhkHV9Fhwgha0gxmQhdeqH4RAMkiR5LFqUV9d4OFCOXfNCGe7cuRul+vL1Oe0/R+T1Y6fMvmAnXbRx1zhynuLuEQIZirjkhgwFCBVgJUWKlKYMRfw24Bp77VH7eygnsaXPCowjxncGnuKSu15HuaCwuesHMPi6AyFXcLovZA6UMMh9hFm5ePHhhMNXUGbD0P3oWXJo6AlMSIyxwggpYwCZg7Ih/EJUDrBwL0MjXrt7906U6svX57SLt/qxU2ZfsJMu2njNms7hPVzbMyHOemhyc8wGu3btcur32OZvHHJoLELkyuVehp458/B71ziH7vRQf2QoQqO56wdW5wUrcK7o1Ol17aN58uRVgx76hi/nN7jKFiN82KNnyalGEqRnjCXQZ6yLgMZiI/RD67kg/uIuXfcy9G6U6svX54zO57DWj50y+4K9uvg3woFgOFeEEHdgQcOYy0PGoc/AYArnAitGaKdHMtR9PFxDl3U18kKGwkHASqZMEWOFP7wecS6POPGu/QALcobB2RXonAjtgnBeTz+dX3VpLBj6EivWOW/ERHYOVWWMD6gvI9QM5IN1XmjICKt+aIeI6T6m44CRvqd5sb/15etzRt9zONePnTL7gp100cZdw0FSD3WGxmCiihs82YzVKnRwTO5GjBjptFJoJXXqVGpEwx8MrK4gRiImv0jbKuQQfN7Vg82TbuWqHKFcWN0xYnL6wpQpU6RWredk6NBh5rU2bV4Rf53M4B0KAWQFz4IyRdVAGlPYqa/Yfk47ZY6pdNFOEevPiutnQqxeX4YREAcQgb59+5qxHF0xZCv6m7sFsbRp05ltzmpAfHiAh/MhSp4mku5kKFbwjZicvjB9+nT1pps4cZJ5DbHC/PXUxfOg7FbwGUqlp3EmtrFTX7H9nHbKHFPpwhMYseCsUIYST8Bj0jjcCJN9gDHbU1x/LPIDLPC7W2SBHmrIWKveif5o7PixI0PhWGDE5PSFmTNnqAET8S0NcOgovJn8wZNsMb4LROzUV2w/p50yx1S6D2Uo9VDiG3v3PpKhhh4Kr15r/Fkrhk5y5UqYPOXGHmzISXf90ZCvj/C0UOJ8HbId/dh6AJ43PvnkEzX8Llu2wtzlMW7cWI3D6w8osyfZ4jomBAp26iu2n9NOmWMq3bRp07iRoc51E+wwTASR//3vQzXcYisHwBY6rFQtXvyVU+3AqwGB5gHCE2AV5ttvv3G6x9jih9MwkQa2chhg2wNc+2FYsEOlSs/K119/rQZoK6GhoR5/g9VEq9cIVjkRnN0KPFG8ee8i6DiexWoAwdZFXI8KvuRtFzv1FV3Pafe57JQ5ptItVephXRigTqyfCTGYO/cTlTUtWrQwt8pCyV60aJFTJaENwcveCPWCySEOqXAnQ7ElH2msW7fW/A5bsLAtGm3Tbj9YvXpVBCNE5DL0gtNhC9hihgNErGAXiLf+jjLjMEwYzq3bt3AIRFQ8BXzJ2y526iu6ntPuc9kpc0zWBbb2W8cTa3smxOCrrxbJiRMnzK2nMABjNxquu2JsRYWMhIfTN9987VaGIiwP0rCGJsOEeNu2rbZl6LPPPqvblF232kbWDx4eqvRIhmLrNQ4Ec+3vOAwnskU2lPmnnzbqLi2DH35YoweKue4Y8Adf8raLnfqKrue0+1x2yhzTdWHdfUEZStyBsA0Ii/PSSw/DiOCANchAdzLUaHP4Hh6jnmQoQjxht6i1zcFegLBndue/6Adbtmw2vY4NoENb9Sbn7y7o8xiGYOhGmzY57142DjKPzHsXZd6yZYvucjJAKDeEnMDBaHbxJW+72Kmv6HpOu89lp8wxlW7JkqX1N1Z92jVcabBDz+AgA7EFV69eLffvh6tR4scff9RtwJMmvaeCFsDDYtCgITJ27GiN/YX4NTjREfEie/TooaeM4h6cHDl+/DiNawlPNWwZgXFjwICBqoB36tRZRowYpkZgXP/ss/nqOWeNfesPiK3Zrl0badWqpTz//As6sd67d696hXz00Sy3v0FZZ8+epZ7AiCvz+eefRdiaV7RoERUsn3zyscZxw2mqrnTv3l2aN2+mIScQjw5xPxF75/PPv7D1LP7kbRc79RVdz2n3ueyUOabS7dSpi7Ro0UzefLO3tlmETcGJrNbYVyT4wBZWyNAHDx4ujkEp3rdvn4wZM87czomtpsOHj5TBgwfK2bNndYENBgEsJiB+bOPGjfWewYOHyvDhQ3W7W5EiReWPPw7qbooxY8bqVuJevXrricAwfsDo8cUXC3R7nzX2rT907txFjRAvvdRCY5Rh0QaxfxGvcMEC930csRtxUjR2gGCXB05CNhRyAzw3jIRYWMyVK7ee7O4K4scjvlfnzp00BiLqDAtNH38819az+JO3XezUV3Q9p93nslPmmEoXsVpXrvxWPclr1KihYVOiEi+OxA/Onz+nMhQ6GYwOv/yyRXWNIUOGmR5sGKNHjx6j4y9iYCL+4eXLlzUGZoMGDfTUctyDHWx9+/bRyWCJEqVUn0X67703RXcz9ev3lp4kDiMwYmUuXrxIdV2cB2CHtm3bqREC/QBGFyzYIY4ljDDLlzsbVKx66KRJE9UjC7rwV199JeHh95zuyZ//aZWrU6ZM1r6fJ0/E087btWuni9odOrymZ3AcOXJET4v/8MMZtp7Fn7ztYqe+ous57T6XnTLHVLrQF5YuXSKdO3fUcBLQW3fs2GG7DCR+cOXKZVOGQi5inobYv3369NXYvQajR4+Vbt26SPfu3XT+jYWoTZs2SYUKFXRMB5ChPXp0V+/JcuXK6bz/+PFjMmPGR/r9wIEDpXfvXmpMw6LW11+v0JB/kMF2aN68uWzYsEFat26lacCeAA9fnOmyYsU3EfRLAP1h8OBBGqoP9+McGOhHTzzxKFQlHL+gN0+dOkVKlCipoWVcadGipfan9u1flRdeeEFOnfpLFixYIJMmvesUOsZffMnbLnbqK7qe0+5z2SlzTKWL3yxcuEDHE8y9cD/iz5NH0BgcRFSqVEmNDugEmNRj2xw82RAo3jVmarNmzaRo0aJ6kAMOlEO8ILjlGwc6gFatXlYPYATxxhZpKPHWgyRgDC5QoKB6Bj2MmdZFO6KrkuwahxVlgdKDGK9WYGBevHipetLBuxdGuapVq0ndunXNe7AVr0qVKubnnj3f0FVNeNPh/lGjRqt3stW7AEritGnv60CKcBn4zjUdbPVeunS5eksjhh1W1pYsWWoa0AG8FlDHVjJnzhKp4caXvN2l67pNHBQqVMhp+4cv9eWKL8+JMuL9RObl5u65fKkfO2V2Vx7X+rHTdrBi/uWXX+mqOhR29JO2bdvSKyOIwTZ5xF6DDEV7Q9vDZHXy5Cm6ndMKDvmC59qqVSvVkxaHycG4YWzhA5CH+fPnk1WrVumEEN7CWKwwwIQRyhhWsRH3qnXrNqrYWbcuo826xlB8/PGk2idcwxJgm93ChV/KypUrNT+MA2XLlpcRI0aZ90AeQy4btG//msZ8wwQUz9yvX381cGMSYu0rmDigXk6ePKnpuqYD2YQ+iEn97t27/9/rb7HkzZvPKR30SysZMqTXZ/GkPPqSt7t0Ua/WwywBymKNd+lLfbniy3NiIeDhGOd5Ycndc/lSP3bK7K48rvVjp+2g3UCGYgEBByai/7Rp01YnKSQ4gacjJqNo14gFjHZVs+ZzMnbs+AhxDBE3FkYy7EBDX8IZFTBMwMveAO0NOgrGduh5hQsX1vA8BpDPkL04zBBhKJo2fUF3wVnjEFeoUNGpfwL0J/SJdOmcw0+gj3z66Xw1xOzZs1vvQ3kGDx5i3pM58xNSp84j3QIh2PCcOHwzYcIE0q1bN/XYsnqIQk7Mnj1HdxE83FlQVXUmazrop4sWfaX6GQ5FhqxBnzRiKAM8K0KjWUHeeBZryDYrvuTtLl3EXTQOmvKkR/lSX6748px4FjxTZDFD3T0X5gPe6sdOmd2Vx7V+7LSdh3J3kSxY8LnOs6Dn4/AjOFqQ4CQkJETlB2QoZCnaSMWKz8rQocPNw1oNMC//+utv1fMXCwkYk3v27GkePg7Kl68gy5Yt18O5IENx2Hb37j3M72FchkMQdFk4faH/QKZZQ0TiEEZ4nbqCtow2bQWLdHDCQb/EQXZwsMCcsW/ffuY8DnLXqtfg/8gPXvLQP9u0aaMyHM5oVtvBnDmfaDmxaIgywRHDmg76KZ4F+hmeBTryvHmf6W4+A4Rtc51zou8iHU8x133J21267mwErnqUL/Xlii/PaYxx0CE94e65ILO81Y+dMrsrj2v92Gk7aDcLFiw0ZSjGtrlzP5WZM2dGaVdifCKBIyb2BRFCCCGEEEIIIYQQQggJKBgzmBBCCCGEEEIIIYQQQoIAGoMJIYQQQgghhBBCCCEkCKAxmBBCCCGEEEIIIYQQQoIAGoMJIYQQQgghhBBCCCEkCKAxmBBCCCGEEEIIIYQQQoIAGoMJIYQQQgghhBBCCCEkCKAxmBBCCCGEEEIIIYQQQoIAGoMJIYQQQgghhBBCCCEkCKAxmBBCCCGEEEIIIYQQQoIAGoMJIYQQQgghhBBCCCEkCKAxmBBCCCGEEEIIIYQQQoIAGoMJIYQQQgghhBBCCCFE4j//B2bjEQdR6+OSAAAAAElFTkSuQmCC", + "text/plain": [ + "
" + ] + }, + "metadata": {}, + "output_type": "display_data" + } + ], + "source": [ + "from tatc.tradespace import COLORS, GRAY\n", + "\n", + "fig, axes = plt.subplots(1, len(robust_design), figsize=(14, 3.6), sharey=True)\n", + "for ax, (limit, best) in zip(axes, robust_design.items()):\n", + " within = by_field[by_field.satellites <= limit]\n", + " ceiling = within.groupby(\"scenario\")[\"accurate\"].max()[list(FIELDS)]\n", + " ax.plot(range(len(FIELDS)), ceiling, color=GRAY, lw=2, ls=\"--\", marker=\"o\", ms=5, label=\"best of the field\")\n", + " ax.plot(\n", + " range(len(FIELDS)),\n", + " traced.loc[best, ACCURATE],\n", + " color=COLORS[0],\n", + " lw=2,\n", + " marker=\"o\",\n", + " ms=6,\n", + " label=\"robust design\",\n", + " )\n", + " ax.set_xticks(range(len(FIELDS)), list(FIELDS))\n", + " ax.set(xlabel=\"Decorrelation time of the field\", ylim=(0, 105), xlim=(-0.3, len(FIELDS) - 0.7))\n", + " ax.set_title(\n", + " f\"At most {limit} satellites\\n{traced.loc[best, 'description'].replace(', 60 deg FOR', '')}\", fontsize=8\n", + " )\n", + "axes[0].set_ylabel(\"Points accurately sampled (%)\")\n", + "axes[0].legend(loc=\"lower right\")\n", + "plt.show()" + ] + }, + { + "cell_type": "markdown", + "id": "4b370add", + "metadata": {}, + "source": [ + "The robust choice depends on how many satellites the mission can afford. Four satellites in two sun-synchronous planes, crossing the equator at 09:00 and 15:00, are the best in the fields of 1 and 3 hours, and fall 5 points behind the best in the field of 12 hours: a mission that does not know its field loses little by choosing them. Two or three satellites fall 10 or 11 points behind somewhere. Six satellites in three Walker planes (at 700 km) fall at most 0.4 points behind the best in any field, though they are efficient in none: a robust design need not be the best in any scenario. Regrets of a point or two are within the sampling error of the means of five replicates." + ] + }, + { + "cell_type": "markdown", + "id": "a4abb242", + "metadata": {}, + "source": [ + "## Search for Robust Designs\n", + "\n", + "A search needs one value of each objective for each design, not one for each field. Criteria `across` the fields (`Across`) combine the statistics of each design over the fields: by their mean (`rule=\"mean\"`), or by their worst (`rule=\"worst\"`).\n", + "\n", + "Here, pymoo searches for the designs most accurate on average over the three fields, with as many proposals as in `SearchTradeSpace`. It evaluates each design that it proposes in every field. Every design was evaluated above, so the results come from the store, and the search can be compared with the true front of the mean." + ] + }, + { + "cell_type": "code", + "execution_count": 6, + "id": "2050e0b0", + "metadata": { + "execution": { + "iopub.execute_input": "2026-11-15T04:33:48.240517Z", + "iopub.status.busy": "2026-11-15T04:33:48.240373Z", + "iopub.status.idle": "2026-11-15T04:33:49.427820Z", + "shell.execute_reply": "2026-11-15T04:33:49.427022Z" + } + }, + "outputs": [ + { + "name": "stdout", + "output_type": "stream", + "text": [ + "156 designs evaluated (in 3 fields each): 94.8% of the hypervolume of the true front, and 7 of its 12 designs\n", + "the field in which each design is least accurate: {'1 hour': 1028, '3 hours': 68}\n" + ] + } + ], + "source": [ + "from tatc.tradespace import Across, hypervolume, hypervolume_progress, optimize_pymoo\n", + "\n", + "FIELD_MEAN = Criteria(ACCURACY, across=Across(rule=\"mean\"))\n", + "REFERENCE = {\"satellites\": MAX_SATELLITES + 1, \"planes\": 5, \"accurate\": 0} # worse than every design\n", + "mean_summary = summarize(fields, FIELD_MEAN)\n", + "true_front = set(mean_summary.design[mean_summary.pareto])\n", + "true_hypervolume = hypervolume(mean_summary, FIELD_MEAN, REFERENCE)\n", + "\n", + "search = optimize_pymoo(field_study, FIELD_MEAN, seed=1) # NSGA-II: 10 generations of 20, 200 proposals\n", + "found = 100 * hypervolume_progress(search.results, FIELD_MEAN, REFERENCE).iloc[-1] / true_hypervolume\n", + "evaluated = set(search.results.design)\n", + "print(\n", + " f\"{len(evaluated)} designs evaluated (in {len(FIELDS)} fields each): {found:.1f}% of the hypervolume of the true \"\n", + " f\"front, and {len(evaluated & true_front)} of its {len(true_front)} designs\"\n", + ")\n", + "least = traced[ACCURATE].idxmin(axis=1).str.removesuffix(\" accurate\")\n", + "print(\"the field in which each design is least accurate:\", least.value_counts().to_dict())" + ] + }, + { + "cell_type": "markdown", + "id": "13af5d5e", + "metadata": {}, + "source": [ + "The search finds 94.8% of the hypervolume of the true front of the mean with 156 designs, and 7 of its 12 designs. Each design costs three times as much as in a search of one field, as it is evaluated in each field.\n", + "\n", + "A worst case (`rule=\"worst\"`) suits scenarios that are hardest for different designs. Here, the field that varies within an hour is the hardest for 1,028 of the 1,096 designs, so a search by the worst would mostly search that field alone." + ] + }, + { + "cell_type": "markdown", + "id": "2d4c4ff6", + "metadata": {}, + "source": [ + "## Summary\n", + "\n", + "* The `scenarios` of a study compare designs under conditions rather than averaging over them. A scenario sets values of the design space (here, a `Fixed` decorrelation time of the field), and the study evaluates each design in each scenario, with the same replicates.\n", + "* Criteria `by` the scenario give the front of each scenario, and `robustness` the share of the scenarios in which each design is efficient (its Pareto trace) and its regret in each. The design of least maximum regret is a robust choice, whether or not it is efficient in any scenario.\n", + "* Criteria `across` the scenarios (`Across`) judge each design once, by its mean or its worst over them, as a search for robust designs needs.\n", + "\n", + "The next notebook, `TradeCostAndUtility`, replaces the numbers of satellites and planes with costs." + ] + } + ], + "metadata": { + "kernelspec": { + "display_name": "Python 3 (ipykernel)", + "language": "python", + "name": "python3" + }, + "language_info": { + "codemirror_mode": { + "name": "ipython", + "version": 3 + }, + "file_extension": ".py", + "mimetype": "text/x-python", + "name": "python", + "nbconvert_exporter": "python", + "pygments_lexer": "ipython3", + "version": "3.14.10" + } + }, + "nbformat": 4, + "nbformat_minor": 5 +} diff --git a/docs/examples/tradespace/EvaluateTradeSpace.ipynb b/docs/examples/tradespace/EvaluateTradeSpace.ipynb new file mode 100644 index 0000000..203ab21 --- /dev/null +++ b/docs/examples/tradespace/EvaluateTradeSpace.ipynb @@ -0,0 +1,686 @@ +{ + "cells": [ + { + "cell_type": "markdown", + "id": "affa1f88", + "metadata": {}, + "source": [ + "# Evaluate a Trade Space\n", + "\n", + "This is the first of eight notebooks on trade studies with the `tatc.tradespace` module (installed with `pip install tatc[tradespace]`). Together they follow one trade from start to finish, and each adds one idea to the notebooks before it.\n", + "\n", + "The trade is that of a pre-Phase A study of an imaging constellation: **how many satellites, in how many orbit planes, observe the Earth often enough?** Each orbit plane needs its own launch, so fewer planes cost less. A point on the Earth is **sufficiently sampled** if it is observed at least four times a day.\n", + "\n", + "This notebook takes the four steps of every trade study:\n", + "\n", + "1. declare the **design space**: the decisions and their options;\n", + "2. define the **study**: how each design is built and evaluated;\n", + "3. **evaluate** the designs;\n", + "4. find the **Pareto-efficient** designs, and plot the trade." + ] + }, + { + "cell_type": "markdown", + "id": "17309571", + "metadata": {}, + "source": [ + "## Configure the Analysis\n", + "\n", + "Each design is analyzed over one day, at 100 points on the Earth, and may have at most 10 satellites." + ] + }, + { + "cell_type": "code", + "execution_count": 1, + "id": "bc7b296c", + "metadata": { + "execution": { + "iopub.execute_input": "2026-11-15T04:33:07.226541Z", + "iopub.status.busy": "2026-11-15T04:33:07.226413Z", + "iopub.status.idle": "2026-11-15T04:33:09.053417Z", + "shell.execute_reply": "2026-11-15T04:33:09.052892Z" + } + }, + "outputs": [], + "source": [ + "from datetime import datetime, timedelta, timezone\n", + "\n", + "import matplotlib.pyplot as plt\n", + "from tatc.tradespace import use_style\n", + "\n", + "use_style() # the style of the plots of trade studies\n", + "\n", + "START = datetime(2026, 7, 1, tzinfo=timezone.utc)\n", + "DURATION = timedelta(days=1) # the period of the analysis\n", + "N_POINTS = 100 # points sampled in each replicate\n", + "N_REPLICATES = 5 # replicates (samples of points) of each design\n", + "SAMPLES_PER_DAY = 4 # observations a day of a sufficiently sampled point\n", + "MAX_SATELLITES = 10" + ] + }, + { + "cell_type": "markdown", + "id": "493b062b", + "metadata": {}, + "source": [ + "## Declare the Design Space\n", + "\n", + "A `DesignSpace` names each decision and its options. Every design here has:\n", + "\n", + "* an **altitude**: 500 to 800 km, in steps of 100 km (`Real`);\n", + "* an imager's **field of regard**: 30 or 60 degrees (`Categorical`);\n", + "* a **layout** of its orbits, one of two alternatives (a `Choice`):\n", + " * a **Walker** constellation (`walker_space`): an inclination, a number of planes, a number of satellites in each plane, and the phasing of the satellites between planes; or\n", + " * one or two **sun-synchronous** planes (`sso_planes_space`), each with an equator crossing time and one or two satellites.\n", + "\n", + "Each alternative has its own decisions: only Walker designs have an inclination. A constraint limits a design to 10 satellites. It returns the number of satellites over the limit, and a design is feasible if that number is zero or less.\n", + "\n", + "The last entry, `points_seed`, is not a decision. It is an `Uncertain` parameter, which the next section explains." + ] + }, + { + "cell_type": "code", + "execution_count": 2, + "id": "c05d366a", + "metadata": { + "execution": { + "iopub.execute_input": "2026-11-15T04:33:09.054803Z", + "iopub.status.busy": "2026-11-15T04:33:09.054558Z", + "iopub.status.idle": "2026-11-15T04:33:09.114516Z", + "shell.execute_reply": "2026-11-15T04:33:09.114062Z" + } + }, + "outputs": [ + { + "name": "stdout", + "output_type": "stream", + "text": [ + "1096 feasible designs\n" + ] + } + ], + "source": [ + "from tatc.tradespace import (\n", + " Categorical,\n", + " Choice,\n", + " DesignSpace,\n", + " Integer,\n", + " Real,\n", + " Uncertain,\n", + " count_satellites,\n", + " sso_planes_space,\n", + " walker_space,\n", + ")\n", + "\n", + "space = DesignSpace(\n", + " altitude=Real(500e3, 800e3, step=100e3),\n", + " field_of_regard=Categorical([30, 60]),\n", + " layout=Choice(\n", + " walker=walker_space(\n", + " inclination=Real(45, 75, step=15),\n", + " planes=Integer(1, 4),\n", + " per_plane=Integer(1, 4),\n", + " ),\n", + " sso=sso_planes_space(\n", + " crossing=Real(6, 18, step=3),\n", + " planes=Integer(1, 2),\n", + " per_plane=Integer(1, 2),\n", + " ),\n", + " ),\n", + " points_seed=Uncertain.seed(),\n", + " constraints=[lambda d: count_satellites(d.layout) - MAX_SATELLITES],\n", + ")\n", + "designs = space.enumerate()\n", + "print(f\"{len(designs)} feasible designs\")" + ] + }, + { + "cell_type": "markdown", + "id": "84b51cbc", + "metadata": {}, + "source": [ + "## Define the Study\n", + "\n", + "A study evaluates each design in three steps:\n", + "\n", + "1. **build** its satellites: an imager in each orbit of its layout (`build`, with `build_constellation`);\n", + "2. **observe** points on the Earth for a day (`Observations` of `Targets`);\n", + "3. **measure** the observations: the share of points observed at least four times (`count_samples`).\n", + "\n", + "The points are a random sample of the Earth, so a share is an estimate, with sampling error. The study therefore evaluates each design five times, in five **replicates**. Each replicate draws its own sample of points from the uncertain `points_seed`, and every design sees the same five samples, so that differences between designs are not differences between their samples. The points of a sample are a Fibonacci lattice in a random orientation (`generate_points_fibonacci_lattice` with `rotate=True`), which covers the Earth evenly.\n", + "\n", + "`ObservationStudy` combines the three steps, and counts the satellites and planes of each design's `layout`. Its other arguments:\n", + "\n", + "* `n_jobs=-1` evaluates designs in parallel, on every processor;\n", + "* the `directory` of the `Observations` caches the observations of each satellite on disk, as many designs share satellites;\n", + "* `describe` describes each design in a few words, in a column `description` of the results (a function from the module `trade_space_example.py` beside the notebooks);\n", + "* `store` keeps the results in a file: running the notebook again reads them rather than evaluating the designs again (unless the study changes)." + ] + }, + { + "cell_type": "code", + "execution_count": 3, + "id": "374124d4", + "metadata": { + "execution": { + "iopub.execute_input": "2026-11-15T04:33:09.115786Z", + "iopub.status.busy": "2026-11-15T04:33:09.115598Z", + "iopub.status.idle": "2026-11-15T04:33:09.178395Z", + "shell.execute_reply": "2026-11-15T04:33:09.177898Z" + } + }, + "outputs": [], + "source": [ + "import tempfile\n", + "from pathlib import Path\n", + "\n", + "from trade_space_example import describe\n", + "from tatc.generation import generate_points_fibonacci_lattice\n", + "from tatc.schemas import Instrument\n", + "from tatc.tradespace import ObservationStudy, Observations, ResultStore, Targets, build_constellation\n", + "\n", + "\n", + "def build(d):\n", + " \"\"\"The satellites of a design: an imager in each orbit of its layout.\"\"\"\n", + " imager = Instrument(name=\"imager\", field_of_regard=d.field_of_regard)\n", + " return build_constellation(d.layout, imager, epoch=START, altitude=d.altitude)\n", + "\n", + "\n", + "def count_samples(observations, duration=DURATION):\n", + " \"\"\"The share (%) of points observed at least SAMPLES_PER_DAY times a day.\"\"\"\n", + " if len(observations) == 0: # no satellites\n", + " return {\"sufficient\": 0.0}\n", + " samples = observations.groupby(\"target_hash\").size()\n", + " threshold = SAMPLES_PER_DAY * duration / timedelta(days=1)\n", + " return {\"sufficient\": 100 * (samples >= threshold).sum() / N_POINTS}\n", + "\n", + "\n", + "CACHE_DIRECTORY = Path(tempfile.gettempdir()) / \"tatc-trade-space\"\n", + "# the points of each replicate: a lattice in a random orientation, from its seed\n", + "TARGETS = Targets(generate_points_fibonacci_lattice, count=N_POINTS, rotate=True, seed=\"points_seed\")\n", + "OBSERVATIONS = Observations(TARGETS, START, DURATION, directory=CACHE_DIRECTORY)\n", + "\n", + "study = ObservationStudy(\n", + " space,\n", + " build,\n", + " OBSERVATIONS,\n", + " count_samples,\n", + " replicates=N_REPLICATES,\n", + " n_jobs=-1,\n", + " store=ResultStore(CACHE_DIRECTORY / \"results.sqlite\"),\n", + " describe=describe, # a description of each design, in the results\n", + ")" + ] + }, + { + "cell_type": "markdown", + "id": "90858c7f", + "metadata": {}, + "source": [ + "## Evaluate Every Design\n", + "\n", + "The design space is small enough to evaluate every design: 1,096 designs in five replicates each, which takes a few minutes the first time. `study.run` gives a row per evaluation (a design in a replicate), with the design's values and its metrics. The rows of the last design show how its share differs between its five samples of points:" + ] + }, + { + "cell_type": "code", + "execution_count": 4, + "id": "8967e528", + "metadata": { + "execution": { + "iopub.execute_input": "2026-11-15T04:33:09.179594Z", + "iopub.status.busy": "2026-11-15T04:33:09.179434Z", + "iopub.status.idle": "2026-11-15T04:33:09.661432Z", + "shell.execute_reply": "2026-11-15T04:33:09.660991Z" + } + }, + "outputs": [ + { + "name": "stdout", + "output_type": "stream", + "text": [ + "5480 evaluations: 1096 designs x 5 replicates\n" + ] + }, + { + "data": { + "text/html": [ + "
\n", + "\n", + "\n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + "
designreplicatealtitudefield_of_regardlayoutsatellitesplanessufficient
5475e571197c9cb90800000.060sso4256.0
5476e571197c9cb91800000.060sso4252.0
5477e571197c9cb92800000.060sso4253.0
5478e571197c9cb93800000.060sso4250.0
5479e571197c9cb94800000.060sso4258.0
\n", + "
" + ], + "text/plain": [ + " design replicate altitude field_of_regard layout satellites \\\n", + "5475 e571197c9cb9 0 800000.0 60 sso 4 \n", + "5476 e571197c9cb9 1 800000.0 60 sso 4 \n", + "5477 e571197c9cb9 2 800000.0 60 sso 4 \n", + "5478 e571197c9cb9 3 800000.0 60 sso 4 \n", + "5479 e571197c9cb9 4 800000.0 60 sso 4 \n", + "\n", + " planes sufficient \n", + "5475 2 56.0 \n", + "5476 2 52.0 \n", + "5477 2 53.0 \n", + "5478 2 50.0 \n", + "5479 2 58.0 " + ] + }, + "execution_count": 4, + "metadata": {}, + "output_type": "execute_result" + } + ], + "source": [ + "results = study.run(designs)\n", + "print(f\"{len(results)} evaluations: {len(designs)} designs x {N_REPLICATES} replicates\")\n", + "results[[\"design\", \"replicate\", \"altitude\", \"field_of_regard\", \"layout\", \"satellites\", \"planes\", \"sufficient\"]].tail()" + ] + }, + { + "cell_type": "markdown", + "id": "a1a7b153", + "metadata": {}, + "source": [ + "## Find the Efficient Designs\n", + "\n", + "The objectives are fewer satellites, fewer planes, and more points sufficiently sampled. A design is **Pareto-efficient** if no other design is as good in every objective and better in one.\n", + "\n", + "`summarize` averages the replicates of each design by the objectives, given whether each is minimized or maximized: a row per design, with the mean of each metric, its standard error (`se`, the uncertainty of the mean), and whether the design is efficient (`pareto`). The rows keep the values of the designs, from which `space.designs_of` rebuilds them, and their `description`." + ] + }, + { + "cell_type": "code", + "execution_count": 5, + "id": "9e23a64a", + "metadata": { + "execution": { + "iopub.execute_input": "2026-11-15T04:33:09.662621Z", + "iopub.status.busy": "2026-11-15T04:33:09.662461Z", + "iopub.status.idle": "2026-11-15T04:33:09.687214Z", + "shell.execute_reply": "2026-11-15T04:33:09.686685Z" + } + }, + "outputs": [ + { + "data": { + "text/html": [ + "
\n", + "\n", + "\n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + "
descriptionsatellitesplanessufficientsufficient se
1054800 km, 60 deg FOR, SSO: 1 at 18:001.01.03.20.9
960800 km, 60 deg FOR, Walker 45 deg: 1 x 2 (spac...2.01.016.61.2
963800 km, 60 deg FOR, Walker 45 deg: 2 x 1 (spac...2.02.030.22.2
961800 km, 60 deg FOR, Walker 45 deg: 1 x 3 (spac...3.01.038.01.2
962800 km, 60 deg FOR, Walker 45 deg: 1 x 4 (spac...4.01.068.21.8
965800 km, 60 deg FOR, Walker 45 deg: 2 x 2 (spac...4.02.069.60.8
1025800 km, 60 deg FOR, Walker 75 deg: 2 x 3 (spac...6.02.097.80.2
\n", + "
" + ], + "text/plain": [ + " description satellites planes \\\n", + "1054 800 km, 60 deg FOR, SSO: 1 at 18:00 1.0 1.0 \n", + "960 800 km, 60 deg FOR, Walker 45 deg: 1 x 2 (spac... 2.0 1.0 \n", + "963 800 km, 60 deg FOR, Walker 45 deg: 2 x 1 (spac... 2.0 2.0 \n", + "961 800 km, 60 deg FOR, Walker 45 deg: 1 x 3 (spac... 3.0 1.0 \n", + "962 800 km, 60 deg FOR, Walker 45 deg: 1 x 4 (spac... 4.0 1.0 \n", + "965 800 km, 60 deg FOR, Walker 45 deg: 2 x 2 (spac... 4.0 2.0 \n", + "1025 800 km, 60 deg FOR, Walker 75 deg: 2 x 3 (spac... 6.0 2.0 \n", + "\n", + " sufficient sufficient se \n", + "1054 3.2 0.9 \n", + "960 16.6 1.2 \n", + "963 30.2 2.2 \n", + "961 38.0 1.2 \n", + "962 68.2 1.8 \n", + "965 69.6 0.8 \n", + "1025 97.8 0.2 " + ] + }, + "execution_count": 5, + "metadata": {}, + "output_type": "execute_result" + } + ], + "source": [ + "from tatc.tradespace import summarize\n", + "\n", + "OBJECTIVES = {\"satellites\": \"min\", \"planes\": \"min\", \"sufficient\": \"max\"}\n", + "summary = summarize(results, OBJECTIVES) # a row per design, and whether it is efficient\n", + "front = summary[summary.pareto].sort_values([\"satellites\", \"planes\"])\n", + "front[[\"description\", \"satellites\", \"planes\", \"sufficient\", \"sufficient se\"]].round(1)" + ] + }, + { + "cell_type": "markdown", + "id": "e1fd9d7d", + "metadata": {}, + "source": [ + "Each mean averages five replicates, which differ by their samples of points. The figure shows the share of each replicate of the efficient designs (dots) and their mean (bar):" + ] + }, + { + "cell_type": "code", + "execution_count": 6, + "id": "6f877e2d", + "metadata": { + "execution": { + "iopub.execute_input": "2026-11-15T04:33:09.688290Z", + "iopub.status.busy": "2026-11-15T04:33:09.688127Z", + "iopub.status.idle": "2026-11-15T04:33:09.801760Z", + "shell.execute_reply": "2026-11-15T04:33:09.801195Z" + } + }, + "outputs": [ + { + "data": { + "image/png": "iVBORw0KGgoAAAANSUhEUgAAAysAAAGHCAYAAACwFs3gAAAAOnRFWHRTb2Z0d2FyZQBNYXRwbG90bGliIHZlcnNpb24zLjExLjIsIGh0dHBzOi8vbWF0cGxvdGxpYi5vcmcvgI3uAAAAAAlwSFlzAAAPYQAAD2EBqD+naQAAWbFJREFUeJzt3Qd4FNX6x/E3CU26UkJRisAFpUlverFQxHrtXZSr4l9FELBwLYDlYgdE7I0iYgW7AooNpQjSQRFUpAhIDyWQZP/P7+js3SS7IWWTzCbfz/Pkyc7s7OzZmd2Zec95z5m4QCAQMAAAAADwmfjCLgAAAAAAhEOwAgAAAMCXCFYAAAAA+BLBCgAAAABfIlgBAAAA4EsEKwAAAAB8iWAFAAAAgC8RrAAAAADwJYIVAEXShx9+aAMHDrRY8+CDD9orr7wScbqo+eCDD+zaa6+1888/33799ddsvWbo0KE2efJkK8wyX3fddcEyJycn28MPP2yXXnqp9e3b1/bu3eueW7NmTbbX6bf9PGrUKHvuueeitj6/fT4AsaNEYRcAAHJCF6rLli2L+HyVKlXs2WeftVWrVtm0adNibuN+88031rBhw4jT0fDAAw/YUUcdZVdeeaUVprlz59p5551njz76qNWsWdMOP/zwbJX1yy+/tNTUVCsM8+bNy1Tm//73v/b666/bXXfdZUcccYQdOHDA3n77bbvjjjvs6KOPztZ682M/52Vfz5492ypXrhy1cuTX5wNQ9BGsAIgpJ598sjVv3tw93rJli91www12zz33BOeVLVvWipIhQ4ZY+fLlo7rOr7/+2po1a2aFbdasWa4c/fr1831ZQy+6M5ZZ8y666CK7/PLL3fTBgwftzTfftAYNGhTqfvbT9suvzweg6CNYARBTunbtGnzspQ2dcMIJ1q1bt7DLL1261CZNmmQbN260zp0727///W+Lj/9fBuyuXbvshRdesB9++MGqVq1qZ599tp144olZppd99tln1rt3b3vxxRftjz/+sPHjx1uZMmVs5cqV9vLLL9uGDRtcjbrSm4488sh0rULHHHOMxcXF2RdffGFpaWnWp08f69ChQ5YXmzVq1LCWLVsG5/34448upWbdunVuvgI2L0h75plnbMaMGe6xPk+nTp3siiuuCH7mJ554whYuXGi//PJLcPs9+eST7j0OVX4Fh88//7x7/9q1a7tt0Lhx4yyDkddee8127NhhLVq0sOuvv94qVqzonlPalLab9otSprS+0aNHp3t9pLJ6pkyZ4vaFtuMll1zivgehDvV5wsnqNRnL7FEZN23alKnFr3Xr1ulai7Lab+H2c3a/T6VLlw67HbLa1xl9/PHH9sYbb7j9c8YZZ+R42xzq+xHu873//vv2zjvvBN9T20/bQyl22fl8h3pPAEUDfVYAFFm6QNPFjS5idOF45513ulYYz59//mlt27a1b7/91rXYKK3nwgsvtKeffjriOpVeplz+iy++2Bo1auSWL1mypEs569Kli1umR48ebt1q7fnpp5/SpS/deOONbv1634SEBHfhpQu5SFRrrwvO0IvK4447zl0wqsybN292n9HTrl07Vzb9qUZdKUpXX3118HkFL/qcuqDzlqtQocIhy5+SkmLHH3+821annHKKuwhXH43Vq1eHLbcufE866SR38akA86233nLBovp3iD631q+0PZXh9NNPz7SOSGX1gjJd+Gs76j0UYCqtzJOd/ZHRoV6Tsczen6Y135s+66yzXBrYtm3bsr3fMu7n7H6fbrrppojbIavtF2rChAn2r3/9y/1Ojj32WNfXK2MKZV6/Hxk/nwJ9BXwKdvSegwcPtnvvvdcWLFiQ7c+X0+8kgBgVAIAY9csvvwR0GJs+fXqm50aOHBkoUaJE4LfffgvOe+KJJwL16tULTvfr1y9w+umnp3vd1KlTAxUrVgykpqaGfU+tNy4uLrBy5crgPC1bt27dwPPPP59u2auuuipw2WWXBae7du0aqF27diA5OTk4r0+fPoEuXboEp1We/v37h53W+xx55JGBW265Jd37/PnnnxG30Zo1a9w2WrduXXBez549A4MGDcpR+VesWOHWs23btuDz+/fvD+zevTvTe6akpLjPOWzYsOC8Xbt2BY444ojAqFGjgvPuu+++QIcOHSKWPVxZve3Yvn37dPNOPvnkwIABA7L9eTLK7mvClVnTmu/Zvn2721bz5s3L9n7LuJ+z+33KajtE2n6hDh486PbVQw89FJy3YcOGQOnSpQN9+/aN2vcj9PPpPWvWrJnuPTdt2hQoU6ZM8D2z8/ly8p0EELtIAwNQZNWrV8/q1KkTnFYfgvXr1wenP/nkEzvssMNcjXMgEHB/SUlJLjXst99+s/r164ddr2qDQ1NNlB6j5ZWWpBQsb12qddb/UL169bJSpUoFp8855xz3pw7jamnJyvLly10KUcbO0qrZ96hzt9LeVPus2m+lzigFTC1CqjkPJzvlVydtpZX179/fpS+1adPGpefoL1yLlrazOqJ7VKPfs2dPlxqmdeTVP//5z3TTofs2J/sjJ9sgt7Kz33Jblqy2Q3Z4+0rpjx61xnTs2DFfvx9KpQt9z+rVq4dNh8zq8+XkPQHELoIVAEVWxosWXbTr4t2jvhRKIznttNPSLad+JJEuJMXrdxG6HlHefbVq1dI9l7FTccYRljStdBYFSOFGwwq1c+dO9z+rsimd5/fff3epX0pbUora1KlTXRAWSXbKX65cOfvuu+9s5MiRrl+A+uoojenxxx/PNKjB1q1b3f+Mn0cjZa1YscLye9/mZH94cvOa7MrOfsttWQ71HT8UL1Ut3Pcyv74f2XnP7Hy+nLwngNhFsAKg2FLNrDq7h3aWzg2v9UYtLmeeeWaWy6qzcyjdi0MXfIcKVKRu3bruv2q0VfaM1MlbfSPUUVn9AEQ1+hmH+dVnzk35NfTs2LFj3WN1aFafFHW0vu222zK1aIn6DoS25mjaey67MpY12vsjL6/JrkPtt/wsy6G2n1c2fS8TExPTfS+9jvjR/n5468v4nmpxCdf5PyvZfU8AsYsO9gCKLY0MNnHiRNdB17N///4c37xOF3Hdu3d3nfeVeuVZu3atffTRR5luKOiNGqWbB2rEJqWhZfd91Dl7+PDhtnv3bjdPtcxqORG1oog6cXvPDRs2LNN6lDqjUZRyUn5daGtEptCLRK1HnyEjpfSonI888ohrNRKlpU2fPj1dp/LsyFjWaO+PvLwmJ+XJar/lZ1kOtf0ULGgABO0rr8VCI94tWbIk374fCkjUoqkWEO899d1YtGhRjj5bTt4TQOwiWAFQbP3f//2fu1+GRhLSSFW6oNQFjy7CckojKik9TCOEabQkjcqlCzwvgPBovvpu6LkmTZq4C6v77rsv2++joXMVUKmcWo/eb/HixcE0q0GDBrm+AOobo2Ff1VclYxk0gpnuA6Jl1Kqk9JlDlV99TkaMGGH/+Mc/XDqQNwSztmE4Gq1LKV/6jBpWWjXet9xyS8QhpiMJV9Zo7o+8viYa+y0/y5Kd7afhjBWwqzVO++nmm29ON8RwdsqT0++H3lOjfTVt2tT97rScRhc7VL+tUDl9TwCxKU697Au7EACQG7rQV82uOuGqNj/Uzz//7NJMdEEVmialDt7nnntuumU1jOz8+fNdnrsu0rK6c3e49WbsTO2lP+niK/TiUsOuqkZZw7SqFlnpWZoO7XCv8iktzLtYzDgtOmzrvjDqpKz7l2RMLVIZVE5vyGbV4GsY29AUGwVkugeNtqEuZJX/f6jyi4If/WldrVq1yjLNSDdH1J3Q1edB68qYAqaO2/oMukDOSsayfv/9964GXRe6Hm0PDYsc2jE8O58nnKxeE67MM2fOdJ3SFZh5n/vdd98NDqebnf0Wbj8fqiy62M/Odoi0r0Pt2bPHDaGtgERDLKtlRd9L7eOcbM9I349wn0/9qDSksfee2l6nnnqqu79KTj5fTr6TAGIPwQoAFBAvWLn//vvZ5ijWlAqpIMUL2BTwKVhR8KJWTgDw0MEeAAAUKI3ypXQy9ZlRvya1lqlPD4EKgIxoWQGAAhIurQUorpTOpTvWKz2tWbNm6UYGAwAPwQoAAAAAX2I0MAAAAAC+RLACAAAAwJcIVgAAAAD4EsFKyPj3u3btcv8BAAAAFD6Clb/t3r3bKlWq5P4DAAAAKHwEKwAAAAB8iWAFAAAAgC8RrAAAAADwJYIVAAAAAL5EsAIAAADAlwhWAAAAAPgSwQoAAAAAXyJYAQAAAOBLBCvF2PLly90fAAAA4EclCrsAgUDAPvvsM1u5cqWdc845Vrt27UzLJCcn27Rp02zTpk3WvHlz69ChQ66WQXpvvPGG+z9s2LBg0HLsscfmajMtW7bMEhISrEmTJmxmAAAAxH7LyrvvvmuNGze2O++80/r162erVq3KtMzmzZutVatWdvvtt7ugplevXnbNNdfkeBlkbenSpe4vt1577TV766232MwAAAAoGi0r5cqVsw8//NAOO+wwO+qoo8Iuc8cdd1jJkiVt9uzZbrmFCxdamzZt7Oyzz7Yzzzwz28sUFWo5UlDXrFkzmzdvnrVu3dqqVKli+/bts/nz59uBAwdcq5K2rSgA0bYpU6aM/fTTT9a2bVs7/PDDM61X6wu1f/9+t74//vjDKlasaN27d7eff/7ZbVu1oNSrV88FiLJ161bXMqb3UcByzDHHWNOmTSOWCQAAAPB9sNKtWzf3f926dWGfT0tLcxe/w4cPd0GIHHfccda5c2d7/fXXXSCSnWUKw8+bku3TJbtsw46DVqtySevZvKI1TCyd5/X+8MMP1r9/fytbtqzVrVvXHnzwQdu2bZv961//cil02h4KZmbOnGlHH320TZw40b788kvbs2ePC2pWrFjhptWiFSkl7Mcff3StU1WrVrU6deq4PwUrmj958mT3HnrcokUL16KyZcuWYBrYwYMH7fzzz7dSpUpFLBMAAAAQE31WsvL777/b7t27XU19KE1///332V4mHPVx0Z9n165d7r8urPWX10Dliel/WlpawE1vT0qxFRv2283dq+Y5YFHZ1JLx3XffWeXKld288847zwUX7du3d9NTpkyxMWPG2GOPPeb6BJUoUcK1cCiYeOCBB+z++++3cePGuee8dYY+vvXWW61379529913p3tfvYdaYNRak5SUZDfffLPb/v/4xz/s3HPPda03Suk7VJkAAACA+Pj42A5WFISId1HuURqTF1xkZ5lwRowY4VpjMtq8eaPt25eUp3K/MzvZ9u1LDTN/g/XumLdgZceOrXbMMU0sOXmvbdq0181TILJz5w5buXJFcLljjmlsmzZtsD17kqxdu7b255+b3Pw2bY6zN9980z2XlPTXtsv4WK03Awf2d49DjRs33h555DFr0aK5S+k6cCDZli9fYiVKxNmePbstJeVA8DVZlQkAAACoWfPI2A5WvLQuLyDxKAhRGlR2lwlnyJAhNnDgwHTLq99M9eo1XR+NvNiVstFKl84crOxKSbDExJp5WnflylWsbNlylphYKzivZs2a1rfv9XbBBRdkWr5cufKun4u3/O7ds6xGjRpuunz5Cm5exse1atWyHTt2p3sPee21110fI7WWpKSkuDS0ww+v6parUKGS67PivSarMgEAAADZ4etgRX0l1Pfhl19+STd/zZo11qhRo2wvE07p0qXdX7jmqOw0SWWl9uGlbMfe/WHn53Xden1cXFy69Sht64YbbrBff/3V9QnR8+r83qBBA/f4gw8+sHvvvdcFEEoBe/zxx4PrCV2n9/iWW25x69M2VQBXqVIl12dFneqfeOIJl96lfkIKEL3tpedefPFFN3SxOtdnVSYAAAAg5oMV1dTrwnjSpEl27bXXugtedcb/4osv7Lnnnsv2MgVNnelXbtxvqSFdXxLi/5qfV2oVOeGEE9LNU4d2tYaok7z66aj/Sfny5YOBwYABA1x/kjlz5tioUaNcf5KM91QJfXzxxRdb9erVXUDy7bffuoBFwYq258MPP2xff/21XX311S4oOeKII9xrLrvsMrfd33nnHde/RevIqkwAAADAocQFvJ7VhUDD3c6YMcN27NjhOnOrw7ZaQ5Rm5HXM1qhTGtmrY8eObvhbjW6lEaamT5/uOo5nd5lDURqYWhB27tyZ5zSw/BwNLKc0rLP68+g/AAAACl6k68JozS/KCjVYUU3/hAkTMs0/7bTT3J9n48aNbjnv7vSqxVeLSqjsLFOQwYpfvPrqq64zvIYRBgAAQMFSgDF62uZMGTfntKlsU+bvyPP8/j2qF+mApVCDFT8pqsEKAAAAsm/cuFds/PhxUdtkSfvT7GBq5sttXYJ7fYbzMr9kQpyVL5OzPtFXXtnbeve+ymKBr/usAAAAAAVJ95JTpk6sOGBme3bm/DPGCoIVAAAA4G8aECgxMTHH2yMlNeBaUULbUNQOogFcQ1O3/NCyUr58eYsVpIH9jTQwAAAA5NbYGVts2frMt66oWamEbd6dQp+VXKJlBQAAAMgjjdAVzv6UgOsEH24UrzpVSkVlflFGsAIAAADkkYKH7XtSw85XQNEwsVqm56I1vyjL2+3UAQAAALhWDg0lHCpaNwUvzuiz8jf6rAAAACAviuNNG/MbaWAxJjk52Xbv3m1Vq1Z1AZZu+JiQkOBGiNi+fbsdccQRmV6TlpbmltWd7D0HDx50w/JpVAmtq3Tp0mHfQ/81YkS40ScAAABQvNO08htpYDFm5syZ1qtXL+vcubPVq1fPGjRoYDNmzLCmTZta/fr1rXXr1unGzr7zzjtd0NGwYUNr0qSJLV682M1ftWqVdezY0Tp06GBVqlSxiy++2FJTU4Pvcfrpp9spp5zi3qNWrVq2aNGiQvvMAAAAKJ5oWfHBnU1zejfRlStX2pw5c+zYY4+1Pn362NVXX23fffedCypOO+00e/PNN928N954wxYuXGjz5s1zLSfvvvuu9e/f3wUjeu26detsz549tnnzZvv3v/9tH374oZ111lnuPZYtW+bW2bx5c/vvf/9rjz/+uI0bF/3PDAAAAERCsOKjO5tm926i7dq1c8GGdOrUyVJSUuzII49002op+f33391jtbgo4OjatWvwtTVq1HD/N2zYYOecc44tXbrUpYcp3Wv16tXB5dq3b+8CFTn++OPdugAAAICCRLBSgHc2zc56s6NUqVLBx+pLknFafVRErSk333yzDRs2LNM6Ro8e7dLAvv32W9fn5dprrw2mgWV8j/j4+OA6AQAAgIJCsJILStXKTrpWYVM/FKV1qRVGLSUlSpSwsmXLuk74JUuWdC0pa9ascalir732WtigBgAAACgsdLCPMWXKlLFq1f43yoRGAwsdAaxixYruT7p06WITJ060Z5991k488UTXkjJkyBD33IABA1xryZlnnmlTp061vn37WoUKFcK+h1poQqcBAACAgsB9Vv7GfVYAAAAAf6FlBQAAAIAvEawAAAAA8CWCFQAAAAC+RLACAAAAwJcIVgAAAAD4EsEKAAAAAF8iWAEAAADgSwQrAAAAAHyJYAUAAACALxGsAAAAAPAlghUAAAAAvkSwAgAAAMCXCFYAAAAA+BLBCgAAAABfIlgBAAAA4EsEKwAAAAB8iWAFAAAAgC8RrAAAAADwJYIVAAAAAL5EsAIAAADAl0rk9AX79u2zb775xubP/942bdrk5tWoUcPatGlrXbp0scMOOyw/ygkAAACgmIkLBAKB7CyYlJRkzz//nL355huWmppqxxxzjFWpUsU9t3XrVlu+fLmVKFHCLrjgQrv22uusfPnyFkt27dpllSpVsp07d1rFihULuzgAAABAsZftYOXkk090rSfnn3++tW3bzhISEtI9rwBm3ry59vbbb7tWl88//yKmNi7BCgAAABCjwcrPP6+yhg0bWbSX9QuCFQAAACBGg5WijmAFAAAAiPEO9qE2bFhvDz/8sC1YMN8U87Ru3cbuuOMOq1mzVvRKCAAAAKBYytPQxbfddpvVqlXLXn75FXvllXFWu3Ztu/3226JXOgAAAADFVo6ClVGjRlpycnJwetWqn6xv3+utQYOG7q9v3772008/5Uc5AQAAABQzOUoD27t3r51//nl2zz1DrV27dnbiiSdZv3432mmnneGe/+ijD6xr1xPzq6wAAAAAipEcd7BftGiRDRs21Fq0aGH9+vWzjz/+xPVZkdatW9uFF15kpUuXtlhDB3sAAACgCIwGdvDgQXvxxRdsypR3bPDgW6179x4W6whWAAAAgCI0dPGaNWts+PChVqlSZbvzzrssMTHRYhXBCgAAABDDfVY2bdpkI0c+bj/8sMBNa6jihx9+1L74YqZddtklds0119lFF11kcXFx+VVeAAAAAMVEjlpWrrqqt9WvX8/OPfc8N/3OO2/bb7+ttZdeetk2b95sDzxwv23fvs3Gj59osYaWFQAAACCGW1ZWrFhuTzwxxipWrOim69atZ927n+IeV69e3UaPfsKmT5+WPyUFAAAAUKzkKFjp0qWLDR48yM4440w3/cEH77t5oYpCZ3sAAAAAMXZTyPvvf8DatGljH374gfvTY83LT7q3y7Bhw6x9+/bWqFEjO+WUU+zNN9/MtNwbb7zhAqeGDRvaOeecYytWrMjXcgEAAADwUctK2bLl3B3rC9JNN91kn3/+uT3//PNWr149++STT+ziiy9293I566yz3DJTpkyxyy67zMaMGWOdOnWyxx57zLp27WrLli2zatWqFWh5AQAAABRwy4pGAVMn9EPZuXOnWzZaZs6caVdddZV1797dtazoRpTNmjVz8z333Xef9e7d266//npr2bKlvfTSS6ZxA55++umolQMAAACAT4OV3bt3W8+e3W3o0Hts5szP3TDGujmk/jZu3GjTp0+3O+/8j1smO0FNdilImTZtmu3YscNNz58/31avXm09evzVN0bv9cMPP7jlPCVKlHDpYl999VXUygEAAADAp2lg99wz1C655FIbN+4Vu+OO223Pnj3pni9fvrz16NHTJkx41bWARMtTTz1lV1xxhUvnqlSpkiUlJdkzzzxjvXr1cs+vX7/e/a9Ro0a61+kGlYsWLYq43uTkZPfn8QKstLQ09wcAAAAg/8THx0e3z4qCEHWoHz78Xvvppx/tjz/+cDeAVGDwj380toSEBIu22267zWbPnm3vvfeeNWjQwLWyqB/LUUcd5VpPvMBCrSmhSpYsaampqRHXO2LECBs+fHim+Zs3b7R9+5Ki/jkAAAAA/E/NmkdaVG8KWdCU+lWlShWbMGGCXXrppcH5F1xwgW3bts0+++wzdzNKBUtTp061s88+O7iM+rmsWrXKZs2ale2WFQVA27dvD95HBgAAAECMtKwUNPWHUctJhQoV0s1XMLFhw4bgzSjr1q3rgpLQYOWbb76xM8/8634w4Wg0Mf2F22jZ2XAAAAAA8pevr8rVT6VVq1b2yCOP2NatW92877//3t566y079dRTg8vdeOON9uKLL7o+KgpunnjiCVu7dq1dd911hVh6AAAAAHnh65YV0Q0gb7jhBqtdu7aVLVvWtbZcc801dscddwSXGTRokBuRrGPHjq7fjFpeJk+e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+RvBCgAAAFAE0sDkiy9m2qeffmobN250/VdCTZgwMRplAwAAAFCM5Wo0sMmTX7P//GeIVapUyb7/fp61bt3aSpYsaT/8sMDq1asX/VICAAAAKHZy1bLy6qsT7fHHR1rHjp1s4sQJdsstA93855571pYuXRrtMgIAAAAohnLVsvL7779b69Zt3ONSpUrZ3r17gvdfmTt3TnRLCAAAAKBYylWwkpKS4oIUSUxMtJUrf3SPt2/fnumeKwAAAABQoB3sPaeffobdeutg++c//2nfffed/fOfXS0/bNmyxWbNmmVly5Z171WmTJlMAdTXX39tmzZtsubNm1vTpk3zpRwAAAAAfDx08dq1v1mdOnXd47S0NHv11Vdt0aKFVr9+fbv66j4uoIimxx57zO655x47/vjj3bp/++03e/fdd+2oo45yz2/bts26d+/u/jdr1sy+/PJL69Onj40aNSrb78HQxQAAAEARvc+KWjZKlMhzQ00m77zzjl144YU2bdo0O/nkk928VatWWUJCgh199NFu+vrrr7evvvrK5s6da+XLl7c5c+ZYp06d7OOPP7aePXtm630IVgAAAIAi0GdFLStPPjkmOD1q1Ehr27a19erV01av/jma5bMHH3zQzj333GCgIo0aNQoGKoq1Jk+e7FpSFKhIhw4d3N+kSZOiWhYAAAAABSdXTSEPPfSQXXzxxe7x2rVr3fDFI0Y85EYCe/TRR+3pp5+JSuH27dtn8+fPt2uvvdZ+/PFHW7hwodWqVcs6duzo7uvijUy2c+fOTH1UlA62YMGCiOtOTk52f6EtK15am/4AAAAA5J/4+Pj8CVYWLJhvjzzyiHv87bez7MQTT7JevXpZ586drFevUy1atm7d6gKH999/3x5++GFr1aqVC0CUbvbJJ5+4G1AqUJHKlSune+0RRxwRfC6cESNG2PDhwzPN37x5o+3blxS1zwAAAAAgs5o1j7R8CVYULGzfvsPKli1n33zzjXXt+tcIYGlpAdeXJFq8Eb/UoV43myxdurQdPHjQOnfubAMHDnT9WQ477DC3zJ49f93rxbN79+7gc+EMGTLErSO0ZUUd9qtXr2kVK1aM2mcAAAAAkDu5ClY6d+5it946yJo1a25z5sy2oUOHufnz5s219u07WLRUrVrVDj/8cNdJXoGKKP3r1FNPtYkTJ7rpOnXquHm//vprutdq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FvF1v//+u2u11O9E29UbLl2f3aud13FGvxXdL8uj77dqibVNvP3yz3/+02rVqpWjcu/cudMuv/xyl+KY3ePQ999/746/xx13nCuj1qH39vPQ+E899ZRt27bNTjnllGwtr22rfaDtqc/pnT/02X/++Wf3uEqVKu47XL169eDrdD7Qdzv0OHb66afneNtomw4ZMsSVNz4+e8keX3zxhfse6Xui/ZKamur2i5+H4L/zzjvtmGOOyXbas34rOiYcffTRwXOTKOVQrQFxcXGWmJjo9lnlypWDz3/++edum2q7ePvlwgsvzPa2FW1PndN0v7qSJUu6eWPGjLFrr73WunXr5q4jwlGaqn5bOubqOFamTBk7/vjjg98pP3nkkUfsueeec9dW3vlZ3ysd3w477LCIx3adPzdv3mzHHnusNWjQIN1n17lD21nbR+dVnWc8ugbTb0XnIB0z9dxZZ52VozLv2bPHLrroIncM0/6XAQMGuHkqk64Dw9H3QOcWHct03td5Rdc4sYRgpYDlNI1DJ4sTTzzRfbl0YNYFab9+/eyWW25xBxSl/3gXrrrQ0gFcF8paXl9MLzVIeaL6AeoiITfBSk7LrYOsUrx69eplv/zyix155JGuyfK2226z4cOHm5/o4BtKJ9vu3bu78kaiA44u+HXyqVSpkq1cudJdjJ5//vnuROHtl/3797uDoU4oOliVKlXKNad/99136fbfaaedluNgRQe7m2++OUevUVnU3KsbpurAV65cOTfv6aeftquvvtr85F//+le6aV1M6QI+qxQKHcSvueYaF6TowK3v3osvvuguZHSC97a3ThZKkVEw7QWkCmaU0qQTjrec9m1Og5XclFsX/6NHj3a/X72nfrvLli1zlRGnnnqq+UnXrl3TTevCRJ9R2y2rC4P77rvPunTp4ioHdDHtBQ2qyPC2twJ9/e6UKnL33Xe7ebqQVn8d7TNvOQX3OQ1W9PvK6W/shRdecN8TlVmVQQqYFAwrGG3RooX5jS5w77//fndBdf311x9y+RtuuMFdyOiCUhc7utBSmq/OH/ot6HOK7l+mihldvF511VVuns43mu+loUpuArnsBlWh9BmV/qIAuGnTpu47omOr0pVy+r0oCDr/vvPOOy6A0LEgKzovnHvuuW576zitz6igRNtYwZjOHTqW6MJZFSz67JMmTQoeJ/T70W9RF6U6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", + "text/plain": [ + "
" + ] + }, + "metadata": {}, + "output_type": "display_data" + } + ], + "source": [ + "import numpy as np\n", + "\n", + "from tatc.tradespace import COLORS, INK\n", + "\n", + "fig, ax = plt.subplots(figsize=(8, 3.8))\n", + "for k, row in enumerate(front.itertuples()):\n", + " shares = results.loc[results.design == row.design, \"sufficient\"].to_numpy()\n", + " spread = np.linspace(-0.12, 0.12, len(shares)) # separates equal shares, for legibility\n", + " ax.scatter(k + spread, shares, s=24, color=COLORS[0], alpha=0.7, lw=0, label=\"replicate\" if k == 0 else None)\n", + " ax.hlines(row.sufficient, k - 0.28, k + 0.28, color=INK, lw=2, label=\"mean\" if k == 0 else None)\n", + "ax.set_xticks(range(len(front)), [f\"{row.satellites:.0f} sat., {row.planes:.0f} pl.\" for row in front.itertuples()])\n", + "ax.set(ylabel=\"Points sufficiently sampled (%)\", ylim=(0, 105))\n", + "ax.set_title(\"The replicates of the efficient designs\")\n", + "ax.legend(loc=\"upper left\")\n", + "plt.show()" + ] + }, + { + "cell_type": "markdown", + "id": "2f039119", + "metadata": {}, + "source": [ + "The replicates of the designs in the middle of the trade spread by up to 12 points (two satellites in two planes sample 24 to 36% of the points), and those of six satellites by 1 point, as they sample nearly every point of every sample. The standard error of each mean (`se`) measures this uncertainty, with which `RankUncertainDesigns` ranks designs." + ] + }, + { + "cell_type": "markdown", + "id": "517a6fd4", + "metadata": {}, + "source": [ + "## Plot the Trade\n", + "\n", + "`plot_designs` plots every design by two metrics, colored by a third, with the efficient designs ringed. The color is the number of planes, with three and four planes together: a scatter of more than three colors is hard to read for readers with color vision deficiencies." + ] + }, + { + "cell_type": "code", + "execution_count": 7, + "id": "523cddaa", + "metadata": { + "execution": { + "iopub.execute_input": "2026-11-15T04:33:09.802897Z", + "iopub.status.busy": "2026-11-15T04:33:09.802729Z", + "iopub.status.idle": "2026-11-15T04:33:09.926054Z", + "shell.execute_reply": "2026-11-15T04:33:09.925387Z" + } + }, + "outputs": [ + { + "data": { + "image/png": "iVBORw0KGgoAAAANSUhEUgAAA48AAAHNCAYAAAC+Zk5BAAAAOnRFWHRTb2Z0d2FyZQBNYXRwbG90bGliIHZlcnNpb24zLjExLjIsIGh0dHBzOi8vbWF0cGxvdGxpYi5vcmcvgI3uAAAAAAlwSFlzAAAPYQAAD2EBqD+naQABAABJREFUeJzsnQWYVPX3xt+pnZ3toJbulA5FVBCUElTADjDAwO78mX9bEQO7wC5CQEpRLJQGRSnp2l22Y2Z26v+c73LH2dnZns15Pzz7zNyYO3fuXO5833vOeY/O4/F4QAghhBBCCCGElIK+tIWEEEIIIYQQQgjFIyGEEEIIIYSQcsHIIyGEEEIIIYSQMqF4JIQQQgghhBBSJhSPhBBCCCGEEELKhOKREEIIIYQQQkiZUDwSQgghhBBCCCkTikdCCCGEEEIIIWVC8UgIIaRC3HLLLVixYkXQjtq1116LH3/8kd8CCQq7d+/Geeedh/z8/IDThBBCKo+xCq8lhBBSQW6//Xbs37+/2PzTTz8dN9xwQ704nsuWLUO3bt1w5plnBmV7ixcvxuDBg4OyLVLzPPvss1izZk2Reb169cJDDz1UK19Heno6vv76a7zzzjuIiIgoNh0Mdu7cifvuuw8fffQRwsPDg7JNQgipD1A8EkJIDbJ8+XK0b98ekydPLjK/bdu2Ifs9vPXWW+jRo0dt7wapJL/99hvsdjuuvvpq77ymTZvWmePZoUMHfPnll4iMjAzaNtPS0pQg/eCDD4K2TUIIqQ9QPBJCSA3TuXNnlUYXiBdffBEej0dFKH2599570b17d6/o/Pnnn/HFF18gJydHCa/rrrsO0dHR3vWnTJmCqVOnYtOmTfjjjz8wcuRIZGRkwOl04o477iiy7XvuuQcnnHACLr/88mL743a71QD5hx9+QIsWLXDxxRcH3O+y9mfXrl149913cejQIXTp0gXXXHMNGjdurJYtWLBARYTatGnjfU9Z96effvK+53vvvYdx48Z5o53y+aZNm4a///5bRb1iYmLUe8qxrQiyHfn7559/sGHDBrXPN954o3rf119/HRs3bkTr1q3VMUtISKjQZ5bj+u+//0Kn06F58+YYPXo0xowZU+z9K/M55s6di2+//RYFBQUYOnSo2o7RaKz2c8j/poevQCvpnC7puAfatpyfEs1btWqViugNGzYMF154ofd1W7duxcMPP4wXXnhBnROSkipRTvnOLBZLwPeS8/6zzz7D2LFjYTKZ1Dx5n08++cT7PpdccgmGDBmilkmkUs5PQdaXmz1XXnklOnbsqOYdPXoU999/v3ou/2cMBgNOO+003HzzzWXuv7BkyRIsWrRICW55TzkWej2riAgh9QNerQghpA7RqFEjPP7442pgqXHkyBE899xzSsQIL7/8Mi644AIlSCTdVSI//fr1Q25urvc1IsgmTJigBucyaO7bty9atmyJRx99FHl5ed719u7dq7bdqVOngPtz11134e6771avb9asGcaPH48DBw4UWaes/ZH1BwwYgMzMTCUSHA4Hhg8fXiRtVfbDt6ZSBufynklJSTj77LNVyqEIMd/PN3HiRCX4Tj31VBw+fBgnnngijh075l1HRO/06dNLPd6yHRE9Ih5FAIg4Ofnkk5VIlfTiESNGKJHlL/rK8x2MGjUKF110kVpPjp2IIxF2/u9f1ufw54EHHsBVV12lvrNBgwap71TepybOoZKQ11922WW47bbb1PdZFoG2LcJLnksk+qSTTvKmvoqo1UhNTVURP/mORHDJ49tvv622VRJa2qoIbUHOPxHysm0R0yKcJQVVblYIIkLleMqf3LAQ8dm7d28l8AUR2NpNjEmTJqn1JO26PPs/Z84cJVTlRskpp5yC1atX15t0dUIIUXgIIYTUGD169PB07tzZM2nSpCJ/y5cvV8tzcnI8ERERnrlz53pf88ILL3hatWrlcbvdniNHjnjCwsI8a9eu9S6X+X379vU899xz3nmxsbGeSy65pMh7FxQUeJo0aeJ5//33vfMeeughT7du3QLu6/79+z0mk8mzbNky77yVK1d65Kfj9ddfV9Pl2Z9PP/3U07p16yLbTk1N9T5v0aKFd5/27t3rMRqNRd5z1apVRd5T+3zXXHONd9rhcKjP9sEHH3jn3XLLLZ42bdoE/Gy+27n22mu904cOHVLvJa/V2L59u5q3c+fOcn/mQMh32rhx42LvX9bn8P9O5L3nz5/vnffnn396dDqd58cff6z2cygQF1xwgTqG8h3ef//9nqioKM91111X6msCbfvdd9/1tG/f3mOz2bzz9uzZoz6bdux/+OEH9V3MmjXLu87u3bs9BoPBs2LFCjUtn0vWycjICDj95ptveiIjIz2HDx/2bsPlcnnS09NL3N/Jkyd7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", + "text/plain": [ + "
" + ] + }, + "metadata": {}, + "output_type": "display_data" + } + ], + "source": [ + "from trade_space_example import PLANE_GROUPS\n", + "from tatc.tradespace import plot_designs\n", + "\n", + "ax = plot_designs(\n", + " summary,\n", + " \"satellites\",\n", + " \"sufficient\",\n", + " by=summary.planes.clip(upper=3), # 3 or 4 planes share a color\n", + " annotate=lambda row: f\"{row.satellites:.0f} sat., {row.planes:.0f} pl.\",\n", + " names=PLANE_GROUPS,\n", + " jitter=0.18, # spreads the designs of each number of satellites, for legibility\n", + " legend=\"upper left\",\n", + ")\n", + "ax.set(\n", + " xlabel=\"Satellites\", ylabel=\"Points sufficiently sampled (%)\", xticks=range(1, MAX_SATELLITES + 1), ylim=(0, 105)\n", + ")\n", + "ax.set_title(\"Every design: mean over 5 replicates\")\n", + "plt.show()" + ] + }, + { + "cell_type": "markdown", + "id": "cb408eb2", + "metadata": {}, + "source": [ + "Seven of the 1,096 designs are efficient. All of them fly at 800 km with the wider field of regard (60 degrees), which observe the most points per satellite, so the trade is in the numbers of satellites and planes:\n", + "\n", + "* one satellite samples only 3% of the points sufficiently;\n", + "* two satellites in two planes sample 30%, nearly twice as many as two in one plane (17%);\n", + "* four satellites sample about two thirds of the points, in one plane or two (68% and 70%);\n", + "* six satellites in two planes sample 98%, and no design of more satellites is efficient.\n", + "\n", + "Designs with the same number of satellites differ widely (the vertical spread in the figure): their layout matters as much as their number." + ] + }, + { + "cell_type": "markdown", + "id": "9cac71e8", + "metadata": {}, + "source": [ + "## Summary\n", + "\n", + "* A `DesignSpace` declares the decisions of a trade, with choices between alternatives (`Choice`), constraints, and uncertain parameters (`Uncertain`) drawn for each replicate.\n", + "* An `ObservationStudy` builds, observes, and measures each design in replicates, in parallel, with a cache of observations and a store of results.\n", + "* `summarize` averages the replicates of each design and finds the efficient designs, which `plot_designs` shows.\n", + "\n", + "The next notebook, `ExplainTradeSpace`, measures sampling by its purpose and explains why designs differ. The notebooks after it search larger spaces (`SearchTradeSpace`), rank designs with the uncertainty of their replicates (`RankUncertainDesigns`), compare them across scenarios (`CompareScenarios`), trade their cost and utility (`TradeCostAndUtility`), and plan their deployment (`PlanDeployment`) and failures (`PlanForFailures`)." + ] + }, + { + "cell_type": "markdown", + "id": "8b8ce5a7", + "metadata": {}, + "source": [ + "## Notes\n", + "\n", + "* `trade_space_example.py` repeats the design space and study of this notebook, and the parts of later notebooks that the notebooks after them use, so that each notebook can import them.\n", + "* The building blocks of the layouts declare more than this notebook needs to say: the phasing of a Walker constellation depends on its number of planes, and sun-synchronous planes are unordered and must cross the equator at different times. See `walker_space` and `sso_planes_space`." + ] + } + ], + "metadata": { + "kernelspec": { + "display_name": "Python 3 (ipykernel)", + "language": "python", + "name": "python3" + }, + "language_info": { + "codemirror_mode": { + "name": "ipython", + "version": 3 + }, + "file_extension": ".py", + "mimetype": "text/x-python", + "name": "python", + "nbconvert_exporter": "python", + "pygments_lexer": "ipython3", + "version": "3.14.10" + } + }, + "nbformat": 4, + "nbformat_minor": 5 +} diff --git a/docs/examples/tradespace/ExplainTradeSpace.ipynb b/docs/examples/tradespace/ExplainTradeSpace.ipynb new file mode 100644 index 0000000..e697733 --- /dev/null +++ b/docs/examples/tradespace/ExplainTradeSpace.ipynb @@ -0,0 +1,813 @@ +{ + "cells": [ + { + "cell_type": "markdown", + "id": "3d867713", + "metadata": {}, + "source": [ + "# Explain a Trade Space\n", + "\n", + "`EvaluateTradeSpace` counted samples: a point is sufficiently sampled if it is observed at least four times a day. But four samples minutes apart say less than four spread over the day. This notebook measures sampling by its purpose, then explains why designs differ.\n", + "\n", + "It covers:\n", + "\n", + "* a second objective, from the **sampling error** of each point;\n", + "* **revisit statistics**, which explain the difference between the two objectives;\n", + "* **sensitivity**: which decisions drive each objective.\n", + "\n", + "It imports the design space and study of `EvaluateTradeSpace` from `trade_space_example.py`, beside the notebooks." + ] + }, + { + "cell_type": "markdown", + "id": "da1dfaee", + "metadata": {}, + "source": [ + "## Measure the Sampling Error\n", + "\n", + "Suppose that the observations estimate the daily mean of a field that varies within hours, such as convective precipitation. A point is **accurately sampled** if the mean of its samples estimates the daily mean with an error of at most half the field's standard deviation. Samples closer together than the field's **decorrelation time** (here, 3 hours) repeat each other, so they add little. `estimate_sampling_error` estimates the error at each point from the times of its samples.\n", + "\n", + "The new metrics function (`sample`) gives both shares. `study.replace` copies the study with the new metrics. The copy is a new study, which evaluates every design again, from the cached observations." + ] + }, + { + "cell_type": "code", + "execution_count": 1, + "id": "99a62858", + "metadata": { + "execution": { + "iopub.execute_input": "2026-11-15T04:33:11.599761Z", + "iopub.status.busy": "2026-11-15T04:33:11.599589Z", + "iopub.status.idle": "2026-11-15T04:33:14.062109Z", + "shell.execute_reply": "2026-11-15T04:33:14.061547Z" + } + }, + "outputs": [], + "source": [ + "from datetime import timedelta\n", + "\n", + "import matplotlib.pyplot as plt\n", + "import pandas as pd\n", + "\n", + "from trade_space_example import (\n", + " DURATION,\n", + " N_POINTS,\n", + " PLANE_GROUPS,\n", + " SAMPLES_PER_DAY,\n", + " START,\n", + " designs,\n", + " space,\n", + " study,\n", + ")\n", + "from tatc.analysis import estimate_sampling_error\n", + "from tatc.tradespace import summarize, use_style\n", + "\n", + "use_style() # the style of the plots of trade studies\n", + "\n", + "DECORRELATION_TIME = timedelta(hours=3) # of the field whose daily mean is estimated\n", + "MAX_RELATIVE_ERROR = 0.5 # of an accurate sample, in standard deviations of the field\n", + "\n", + "\n", + "def sample(observations, decorrelation_time=DECORRELATION_TIME):\n", + " \"\"\"The shares (%) of points sampled sufficiently and accurately.\"\"\"\n", + " if len(observations) == 0: # no satellites\n", + " return {\"sufficient\": 0.0, \"accurate\": 0.0}\n", + " samples = observations.groupby(\"target_hash\").size()\n", + " end = START + DURATION\n", + " error = estimate_sampling_error(observations, START, end, decorrelation_time)\n", + " return {\n", + " \"sufficient\": 100 * (samples >= SAMPLES_PER_DAY).sum() / N_POINTS,\n", + " \"accurate\": 100 * (error.relative_error <= MAX_RELATIVE_ERROR).sum() / N_POINTS,\n", + " }\n", + "\n", + "\n", + "accuracy_study = study.replace(metrics=sample)\n", + "results = accuracy_study.run(designs)\n", + "summary = summarize(results, statistics=[\"satellites\", \"planes\", \"sufficient\", \"accurate\"])" + ] + }, + { + "cell_type": "markdown", + "id": "bce8a673", + "metadata": {}, + "source": [ + "The figure compares the two shares of every design. A design on the dashed line samples as many points accurately as sufficiently." + ] + }, + { + "cell_type": "code", + "execution_count": 2, + "id": "7326121b", + "metadata": { + "execution": { + "iopub.execute_input": "2026-11-15T04:33:14.064848Z", + "iopub.status.busy": "2026-11-15T04:33:14.064078Z", + "iopub.status.idle": "2026-11-15T04:33:14.184895Z", + "shell.execute_reply": "2026-11-15T04:33:14.184235Z" + } + }, + "outputs": [ + { + "data": { + "image/png": "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gQMHxH0+n0+/4orL9Z/97J7E9kuXLtVPP31GYvmVV17Rx48fp7/11uLEur/85WH9wgvnJZYXL35TnznzjBbHcd111+p//etfEsuNjY36p5+ubfOYO9r2ySefEMeYzLvvvqNPnz41sXzo0CFxjPv370use/755/T58y9o8bjvf/97+gMP/C6x/Nprr+pTpkzSv/rqq8S6zZs361VVVW2eizfffFM/99zZek1NTWLd00//U5879zxdVdVuna/Wz0WPaf26L7nkohbnqbPnsDVut1u8juRjjB83HUecO+/8sVhH5zvObbfdot977y+OeNxjjz2aWEfX7IwzTtObmpqO+Ty+/PJL4jEVFRWJY543b26L696aJUveOuJ+ej+sXLkycax0/NFoVL/iim/pa9Z8pNfUVOsffviBXllZecT+Fiy4pN3zzTCDFW7UYZhBBqUkKbW6aNEb+MlP7sTevXtx/fU3YvnyZZg3b56IKhEU1bv++utFxzRFMdvD4XBg/vyLEssnnXSSeA5VVdt9DEXLKGoUCATEMqViTznl1G5v25MsXvwmLrjgAowfPz6xjmoyc3Nz29yezielYSniSeeM6jYtFisOHTqE8vLybp2v1lx22bdENI1SygSl+6kUYMGCS4/pHFLUjfbxzjvviMgupeO3bNnSYh903HQ+4lAUMTMzC+ecczhSO3HiJBH9S4bKDK6//obE8nXXXS9S+J999ukxn0daT8dC6XeCoqeXX35Fh+eMaonT0tJarJs370I88shfRa3lP/7xBC68cD7+/e9/YfjwEcjIyMRll12K559/Hpdffpk4P8m4XGlwu90dPifDDDY4/c0wg4yyskMi3Wk2m0XKkOrCSkpKhbXLjBkzWmw7ZEiJSHVS3V17dXCtP6hNJpMQSCRUkusxk7nnnntw3333YebMMzBp0mSRQrziiivFMXVn256EUq6nn35Gl7q2SXhROj6Z88+fB01Tu3W+WlNUVCRE4RtvvI6f/ezn4pZS1sXFxW1u39E5pLTw9753q3huSsvTl4nq6hrk5dW32Edbx03CqvU66rBOhmosKWUfh56TfpeShXZXzyNdm9b1rO299jj0uuKiOs51110n1pNgvOOOHwlR/N3v3oiXX34Vv/nNr4UYXrjwFvzrX0+L+su//OVvicf6/YE2a1cZZjDDopJhBnGjTjLUiOLxeI5o7qA6OIoE9SQjR47C88+/IGxc1q37DI8++ijWr1+Phx/+S5e2pWPT9ZZR1FAo3CPHSNG8rkSiSGBQVzHVGfYGl19+OX7729+IRpMVK1Z0+LwdnUOK1FE9IdVQxvnRj34o6kd7ArJvon3Fu+wJqpNMbujp6nkkpwLaRzKtl1szdOhQsQ39jif/Pn/rW98SP8TChTfjRz/6sTi2/fv3iYgwQY1NVLPaWvzSPhmGOQynvxmGEUydOlU0viSnYVeufFukfykCdaxQJIiina07qons7GxccMGFuOGGG45IL3ZmW0pFU8QrEokktl+/PtbJ3F1OO+108fqpeSUO/d/v97W5PUXOKFXbWtzEj78756stzjknZjn0y1/GxBc1JrVHR+eQhOawYcNapIk///xz9BQUuaTmrziffrpWRAwpKnis53HKFPpdfb9FWca7777T4XFQ6QIJVnIBaC/tTtHaiy66OCFc496VNTU1LSy3KLpL4vTUU49/GQbD9Cc4UskwjGDhwoWi1vLWWxeKVCNNHaHlf/zjqW6dobFjxwkRQZYtVKtGFjm//vWvUFw8RNTlkSCkruX2uoHvvvu/2t2WLF8efPAB0dk8c+ZMYcdDwrgnoLTnhx9+gGuuuRqXXnqZ8LVctmypiO61ZSNDVjVkVXTVVVfgyiuvEuKQ6hLJUoc8MrtzvtrCaDQJa5t///vf4vksFku7++zoHJIf5uOPPyaOl1LTL774InoSOi5KvV977bUiWvnPfz4ljjdeu3ss5/HGG28SNa+33/49UdO5bt06bN26tcPjiJ2vS8Q1JNulZMhaiyyE/vWvZ1rUWz7++KPCz/XZZ5/Bd75zXeI+Er0zZpwmPCsZhjkMi0qGGUTQB2FhYVGb97lc6XjllVfxyisv48svv0RWVhZeeumVFqKmteF3ScmQIyxVqMGBRGncjobq/x577HGsWrVKCD6yyPnnP/8lBCvZ11B06Cc/uavdSFtH21Kd34svviwaLWjyCVn/kACk5ThUz0fHkywEyYuRRGgyrc3Pad8kYiiCRTY4dN9DD/0xcf5anwuqA3z++f9gyZK3hH+i0WgUTTjJpQbHer7aM1onQUiikl5zR3R0DqlukK41CTOyOKIaW4rQJddGtnXcbZ1D8rdMtneK21Y9+ujjwoCeLJ7uvPMuXHrp4YaiYzmPFHF96aWXhZ0Riclp06aJ+siXXupYvN900024/PJviahnXl5eYj3ZTVHam859HEqJ03OTQfrNNy9MNEHReXnttdfw+9+3NEVnGAaQqAWcTwTDMEz/489//j/hQfnaa28gFXn11VfxxBOPYeXK1Jlb/uqrr4h62blzj/Tz7AzUlU7+m9///u09fmwM09/hSCXDMEw/g2a2k2n6Cy88j9/85rd9fTj9iqNZDx0NaiKKj3lkGKYl3KjDMAzTz6BpR5Qa/vnPf9HhZJq+pq20OcMwAxdOfzMMwzAMwzDdhiOVDMMwDMMwTLdhUckwDMMwDMN0GxaVDMMwDMMwTLdhUckwDMMwDMN0GxaVDMMwDMMwTLdhUckwDMMwDMN0GxaVDMMwDMMwTLdhUckwDMMwDMN0GxaVDMMwDMMwDLrL/wfEd8oPKc/MAwAAAABJRU5ErkJggg==", + "text/plain": [ + "
" + ] + }, + "metadata": {}, + "output_type": "display_data" + } + ], + "source": [ + "from tatc.tradespace import GRAY, plot_designs, style_axes\n", + "\n", + "fig, ax = plt.subplots(figsize=(6.5, 5))\n", + "groups = summary.planes.clip(upper=3) # 3 or 4 planes share a color\n", + "plot_designs(summary, \"sufficient\", \"accurate\", by=groups, names=PLANE_GROUPS, legend=\"upper left\", ax=ax)\n", + "ax.plot([0, 100], [0, 100], color=GRAY, lw=1, ls=\"--\")\n", + "ax.set(xlabel=\"Points sufficiently sampled (%)\", ylabel=\"Points accurately sampled (%)\", xlim=(0, 102), ylim=(0, 102))\n", + "style_axes(ax, grid=\"both\")\n", + "ax.set_title(\"Two measures of sampling, for every design\")\n", + "plt.show()" + ] + }, + { + "cell_type": "markdown", + "id": "6a8c3ad5", + "metadata": {}, + "source": [ + "Designs in one plane (blue) fall far below the line: they sample many points four times a day, but few of them accurately. Designs in two or more planes lie near the line or above it." + ] + }, + { + "cell_type": "markdown", + "id": "6f075262", + "metadata": {}, + "source": [ + "## Find the Efficient Designs by Accuracy\n", + "\n", + "With the share accurately sampled as the third objective, in place of the share sufficiently sampled, the efficient designs change:" + ] + }, + { + "cell_type": "code", + "execution_count": 3, + "id": "715976e0", + "metadata": { + "execution": { + "iopub.execute_input": "2026-11-15T04:33:14.186107Z", + "iopub.status.busy": "2026-11-15T04:33:14.185932Z", + "iopub.status.idle": "2026-11-15T04:33:14.196128Z", + "shell.execute_reply": "2026-11-15T04:33:14.195640Z" + } + }, + "outputs": [ + { + "data": { + "text/html": [ + "
\n", + "\n", + "\n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + "
descriptionsatellitesplanessufficientaccurateaccurate se
1050800 km, 60 deg FOR, SSO: 1 at 12:001.01.03.04.20.6
1047800 km, 60 deg FOR, SSO: 2 at 06:002.01.011.610.40.9
963800 km, 60 deg FOR, Walker 45 deg: 2 x 1 (spac...2.02.030.234.21.8
1019800 km, 60 deg FOR, Walker 75 deg: 1 x 3 (spac...3.01.026.217.01.1
1075800 km, 60 deg FOR, SSO: 1 at 09:00, 2 at 15:003.02.028.860.61.3
1001800 km, 60 deg FOR, Walker 60 deg: 3 x 1 (spac...3.03.034.261.03.8
1020800 km, 60 deg FOR, Walker 75 deg: 1 x 4 (spac...4.01.049.228.62.1
1081800 km, 60 deg FOR, SSO: 2 at 09:00, 2 at 15:004.02.057.685.40.7
758700 km, 60 deg FOR, Walker 75 deg: 3 x 2 (spac...6.03.089.096.40.5
1045800 km, 60 deg FOR, Walker 75 deg: 4 x 2 (spac...8.04.097.896.60.5
1035800 km, 60 deg FOR, Walker 75 deg: 3 x 3 (spac...9.03.097.897.80.2
1036800 km, 60 deg FOR, Walker 75 deg: 3 x 3 (spac...9.03.097.897.80.2
1037800 km, 60 deg FOR, Walker 75 deg: 3 x 3 (spac...9.03.097.897.80.2
\n", + "
" + ], + "text/plain": [ + " description satellites planes \\\n", + "1050 800 km, 60 deg FOR, SSO: 1 at 12:00 1.0 1.0 \n", + "1047 800 km, 60 deg FOR, SSO: 2 at 06:00 2.0 1.0 \n", + "963 800 km, 60 deg FOR, Walker 45 deg: 2 x 1 (spac... 2.0 2.0 \n", + "1019 800 km, 60 deg FOR, Walker 75 deg: 1 x 3 (spac... 3.0 1.0 \n", + "1075 800 km, 60 deg FOR, SSO: 1 at 09:00, 2 at 15:00 3.0 2.0 \n", + "1001 800 km, 60 deg FOR, Walker 60 deg: 3 x 1 (spac... 3.0 3.0 \n", + "1020 800 km, 60 deg FOR, Walker 75 deg: 1 x 4 (spac... 4.0 1.0 \n", + "1081 800 km, 60 deg FOR, SSO: 2 at 09:00, 2 at 15:00 4.0 2.0 \n", + "758 700 km, 60 deg FOR, Walker 75 deg: 3 x 2 (spac... 6.0 3.0 \n", + "1045 800 km, 60 deg FOR, Walker 75 deg: 4 x 2 (spac... 8.0 4.0 \n", + "1035 800 km, 60 deg FOR, Walker 75 deg: 3 x 3 (spac... 9.0 3.0 \n", + "1036 800 km, 60 deg FOR, Walker 75 deg: 3 x 3 (spac... 9.0 3.0 \n", + "1037 800 km, 60 deg FOR, Walker 75 deg: 3 x 3 (spac... 9.0 3.0 \n", + "\n", + " sufficient accurate accurate se \n", + "1050 3.0 4.2 0.6 \n", + "1047 11.6 10.4 0.9 \n", + "963 30.2 34.2 1.8 \n", + "1019 26.2 17.0 1.1 \n", + "1075 28.8 60.6 1.3 \n", + "1001 34.2 61.0 3.8 \n", + "1020 49.2 28.6 2.1 \n", + "1081 57.6 85.4 0.7 \n", + "758 89.0 96.4 0.5 \n", + "1045 97.8 96.6 0.5 \n", + "1035 97.8 97.8 0.2 \n", + "1036 97.8 97.8 0.2 \n", + "1037 97.8 97.8 0.2 " + ] + }, + "execution_count": 3, + "metadata": {}, + "output_type": "execute_result" + } + ], + "source": [ + "from tatc.tradespace import pareto_front\n", + "\n", + "ACCURACY = {\"satellites\": \"min\", \"planes\": \"min\", \"accurate\": \"max\"}\n", + "summary[\"pareto\"] = pareto_front(summary, ACCURACY)\n", + "summary[summary.pareto].sort_values([\"satellites\", \"planes\"])[\n", + " [\"description\", \"satellites\", \"planes\", \"sufficient\", \"accurate\", \"accurate se\"]\n", + "].round(1)" + ] + }, + { + "cell_type": "markdown", + "id": "5ae36ead", + "metadata": {}, + "source": [ + "Thirteen designs are efficient by accuracy, against seven by sufficiency, and the designs that spread their samples over the day join the front:\n", + "\n", + "* two satellites in two Walker planes sample 34% of the points accurately, three times as many as two in one plane (10%);\n", + "* three satellites in two sun-synchronous planes, or in three Walker planes, sample 61%, against 17% for three in one plane;\n", + "* four satellites in two sun-synchronous planes, crossing the equator at 09:00 and 15:00, sample 85%, against 29% for four in one plane;\n", + "* six satellites in three planes sample 96%, nearly as many as nine (98%)." + ] + }, + { + "cell_type": "markdown", + "id": "099aefac", + "metadata": {}, + "source": [ + "## Explain the Difference\n", + "\n", + "Why do designs in one plane sample so few points accurately? Two designs of four satellites show why: the one in a single plane that samples the most points sufficiently, and the one that samples the most points accurately. For the points of the first replicate (`observations_of` and `targets_of` the study):\n", + "\n", + "* `compute_revisit_statistics` gives the times between the samples of each point, and the longest gap of the day;\n", + "* `compute_local_time_coverage` gives the number of the eight 3-hour intervals of local time in which each point is sampled." + ] + }, + { + "cell_type": "code", + "execution_count": 4, + "id": "92827f66", + "metadata": { + "execution": { + "iopub.execute_input": "2026-11-15T04:33:14.197231Z", + "iopub.status.busy": "2026-11-15T04:33:14.197070Z", + "iopub.status.idle": "2026-11-15T04:33:14.286669Z", + "shell.execute_reply": "2026-11-15T04:33:14.286118Z" + } + }, + "outputs": [ + { + "data": { + "text/html": [ + "
\n", + "\n", + "\n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + "
sufficient (%)accurate (%)median revisit (h)median longest gap (h)median 3-h intervals sampled
design
800 km, 60 deg FOR, Walker 45 deg: 1 x 4 (spacing 0)68.226.80.413.82.0
800 km, 60 deg FOR, SSO: 2 at 09:00, 2 at 15:0057.685.45.97.64.0
\n", + "
" + ], + "text/plain": [ + " sufficient (%) \\\n", + "design \n", + "800 km, 60 deg FOR, Walker 45 deg: 1 x 4 (spaci... 68.2 \n", + "800 km, 60 deg FOR, SSO: 2 at 09:00, 2 at 15:00 57.6 \n", + "\n", + " accurate (%) \\\n", + "design \n", + "800 km, 60 deg FOR, Walker 45 deg: 1 x 4 (spaci... 26.8 \n", + "800 km, 60 deg FOR, SSO: 2 at 09:00, 2 at 15:00 85.4 \n", + "\n", + " median revisit (h) \\\n", + "design \n", + "800 km, 60 deg FOR, Walker 45 deg: 1 x 4 (spaci... 0.4 \n", + "800 km, 60 deg FOR, SSO: 2 at 09:00, 2 at 15:00 5.9 \n", + "\n", + " median longest gap (h) \\\n", + "design \n", + "800 km, 60 deg FOR, Walker 45 deg: 1 x 4 (spaci... 13.8 \n", + "800 km, 60 deg FOR, SSO: 2 at 09:00, 2 at 15:00 7.6 \n", + "\n", + " median 3-h intervals sampled \n", + "design \n", + "800 km, 60 deg FOR, Walker 45 deg: 1 x 4 (spaci... 2.0 \n", + "800 km, 60 deg FOR, SSO: 2 at 09:00, 2 at 15:00 4.0 " + ] + }, + "execution_count": 4, + "metadata": {}, + "output_type": "execute_result" + } + ], + "source": [ + "from tatc.analysis import compute_local_time_coverage, compute_revisit_statistics\n", + "\n", + "four = summary[summary.satellites == 4]\n", + "# the design of four satellites in one plane that samples the most points sufficiently, and the design of four that\n", + "# samples the most points accurately\n", + "chosen = pd.concat([four[four.planes == 1].nlargest(1, \"sufficient\"), four.nlargest(1, \"accurate\")])\n", + "rows, observed = [], {}\n", + "for design, row in zip(space.designs_of(chosen), chosen.itertuples()):\n", + " observations = observed[row.description] = accuracy_study.observations_of(design)\n", + " points = accuracy_study.targets_of(design)\n", + " revisits = compute_revisit_statistics(observations, START, START + DURATION, targets=points)\n", + " local = compute_local_time_coverage(observations, targets=points)\n", + " sampled = revisits[revisits.samples > 0]\n", + " rows.append(\n", + " {\n", + " \"design\": row.description,\n", + " \"sufficient (%)\": row.sufficient,\n", + " \"accurate (%)\": row.accurate,\n", + " \"median revisit (h)\": sampled[\"revisit p50\"].dt.total_seconds().median() / 3600,\n", + " \"median longest gap (h)\": revisits.max_gap.dt.total_seconds().median() / 3600,\n", + " \"median 3-h intervals sampled\": local.local_bins_sampled.median(),\n", + " }\n", + " )\n", + "pd.DataFrame(rows).set_index(\"design\").round(1)" + ] + }, + { + "cell_type": "markdown", + "id": "8450fac9", + "metadata": {}, + "source": [ + "The local times at which each design samples a dozen of the points (spread from south to north) show the difference:" + ] + }, + { + "cell_type": "code", + "execution_count": 5, + "id": "5555b886", + "metadata": { + "execution": { + "iopub.execute_input": "2026-11-15T04:33:14.287955Z", + "iopub.status.busy": "2026-11-15T04:33:14.287791Z", + "iopub.status.idle": "2026-11-15T04:33:14.442913Z", + "shell.execute_reply": "2026-11-15T04:33:14.442323Z" + } + }, + "outputs": [ + { + "data": { + "image/png": "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36WXXurbuHFj0ONff/21L126dL65c+fGOo8GDRr4HnzwQV+4brnlFl+3bt3897X+ffr0cdv2xIkT7jHtKx3m1q9f7/vrr798d955p7t16NDBN3r0aN/p06f9r//yyy99xYsX99/XPg9cxp07d7rtp3XxaH20rTp27Oh79913gz4HvXr18s2aNcu9j97vhx9+CLkeWlbt7xkzZrhl1f7zdO/e3depUydfQmi/a3m0LZYvX+7muWXLlrCWWT744AP/61etWuW21969e91zX331la9z587xLsN3333n3jdw+8akz/8999zjvnOe6dOn+x5++GHfqVOnYn1dXNsrJn0/n3jiiaDH1qxZ4+vZs6fv/vvv9w0dOtR3/PjxoH02c+ZM3xtvvOH22YABA4K+K6+++qrbHq1atfL95z//8S1atOi899T356mnnnKfZS2jR9+/b7755rzPx1tvveXe65lnnnGfsXD3RUzXX3+9+w54Zs+e7cuQIYNv27Zt/sd0rLrmmmti3V5AJNBnXseGpUuX+h975ZVXfJUqVXJ/79mzx5cpU6agY7nOPerUqRPW8zHt3r3bvd/27dvdfR339P3W8cJrw/XdXbJkiTsOtGvXzjdmzBjXxuuYqu/4o48+6lu7dm3Y66jjdqlSpVx7Hsg7PiR0HeTw4cNufjoe6bxn7Nix7lzCo+UdP368O0Y/9thjvh9//DHo9VrPF154wb3+tdde833//feurYmNjk9qd2M6cOCAL3fu3G4bBtKxumbNmr6WLVvGOg9tT+0LnaOFY8qUKe6cIWZb5R0343s+Icuq9ii28wB9drxzPq+d0/vqHDSUDRs2+M9nHnjgAddmee2m5lWvXj1ftmzZ/NP8/vvv581D7Y8+I4HtTt26dd2+Fa2T1iFQ9erV3TlqqHWKb37xPR+flNhGga6++mpf37594/zuh3IxtxFSBzJXkKpceeWVLkvFy9JQhPzQoUP+K74//fSTuyLlpb0qgq0rBV7x1viej4syIW6++Wa79957/dkBSkHUFWB1b1CXFS2PosnNmjWzjBkzur91BT0wKyM+mpeurKjbjDJYnnnmGbfOSiVMzDooeq/l1pUpLbeKsuoKg0dXs5RRoO2orgmKvCsS7vUP1xWZpk2bWoECBdwVl8cee8ylgSamZovSYpUiWbx48aDHtT664qHnY6sNom2QkPRO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bz4ffvihbd682Ro3bpygZQEAAAAAAJEhVQZXUjN1E1IWjIaCPnLkiK1Zs8beeust1zUIAAAAF0b2zOntz8EV2LwXaLuxfSMX+xYp+fnJHkXHboIrCVSjRg3XZWnp0qV29uxZVyhX3ZcAAAAAAEB0IriSCNmyZbNrr702+fcGAAAAAABIc1LVUMwAAAAAAABpDcEVAAAAAACAJCC4AgAAAAAAkAQEVwAAAAAAAJKA4AoAAAAAAEASEFwBAAAAAABIAoIrAAAAAAAASUBwBUCcjp06Z5V6rXI3/R3bNFV6r7HGIw7HOU0480nqNBfrfbxptM5a95Re73CnAYC0hOMa2xx8n5C6cFyOXVQHVzZs2GC7du1K6cUAAAAAAABpWKoOrhw7dsxWrFhhO3bsCPn89u3bbffu3Ymef4cOHWz06NFJWEIAAAAAABDtUnVwRcGPKlWq2JAhQ4IeHzVqlJUsWdJq1apl5cuXd7cff/wxxZYTAAAAAABEr1QbXHn77bddxoqCK4HOnj1rq1atcsGUbdu2uW49t956q912223xZrH4fD7XFejw4cNxTnfgwAFbv369nTlzJtb56HlvPnQvAgAAAAAgeqXK4Mqff/5p/fr1swkTJlj69MGLmCFDBhs5cqQVL17cf//JJ5+0Q4cO2aJFi2Kd57p166xy5cpWtWpVK126tN1yyy0uiBJo//791rJlSytatKg1btzYcufObQMHDgyaZvXq1VahQgWrVq2afz56Dd2LAAAAAACITqkuuHL8+HG755577NVXX7VixYqFHYwRBUVi07FjRytVqpTt2bPHdu7c6boULVu2LGia++67z7Jly+YyZpSZsnjxYhsxYoRNmTIlqKtSuXLlbO/evW4+V1999XnzienkyZMu+BN4AwAAkY32HwCA6JHqgiuPP/64Va9e3QU6wnHw4EF79NFHXdegSpUqhZxG2SY///yzDR482LJkyeIee+6551xmimfNmjU2c+ZM69Spk23ZssV1PTp9+rTLYPn888/dNHpswYIF9uKLL1rmzJndY71797Y8efLEuYx635w5c/pvcQWBAABAZKD9BwAgemS0VGTWrFkuS+Srr75yowTJiRMnXJaI7qtbT8zRhFq0aOECJuPHj491vn///bfrXqSME49eo249HgVOpHv37ue9Xlkusc0nU6ZMLiMmLr169bIePXr47ytzhQALAACRjfYfAIDokaqCK/v27bMiRYrYww8/7H9s06ZNrivPkiVLXPcb1Vjxug81a9bMvWb27NlxZo9kz57dzp0759JzM2bMGBSc8XiZKJpXgQIFEjQfLUtcFMjxMmYAAEB0oP0HACB6pKpuQffee6/LUAm8KUukbdu27u+YgRWNDqRgSP78+eOcr7oLKcMkcLjmrVu32l9//eW/f9VVV7kAS2B9Fc+pU6eC5jNnzhz/c6rPEjgfAAAAAAAQXVJV5ko4NDyyhl1WsGXy5MmuqKxuoqyXwDoqHmWidOnSxd1ef/11y5Url6uVEihfvnzWt29f69mzpx09etTq16/vAieffvqp1a5d23UXKliwoD344IPWtWtXe+2111z9FL1GQzOnS5fuom0DAAAAAACQeqT64Irqolx++eX++0eOHLFt27a5bJXHHnssaNoBAwbYHXfcEXI+Q4cOdV2HhgwZ4gIpCrQokyWwC9Czzz7rslPGjRvnMlg03HOrVq2sdevW/mkUVMmbN68rUqf5KNiiTBqNMgQAAAAAAKJPqg+uTJ06Nei+sk68YrcJoe48/fr1czdP+/btz5tOWTG6xUYFbV944QV3E9V86datm1WsWDHBywQAAAAAANK+VB9cSW0mTpzohnZu2rSpy6IZNGiQG/mnSZMmKb1oAAAAAAAgBaTzqWAIElTzRV2DvvnmGzt79qwrhKv6Laq/Ei4Nxazp9+/f7zJxooFGWdq5c5sVLFjYZf9EumhbX2Gd2c+Ris929Hy2L/TxOtraf7470fPd4Zwn8rGf+T5HqnPJ2P6TuZLQDZYxoz355JPuBgAAAAAAEB0hOAAAAAAAgAuE4AoAAAAAAEASEFwBAAAAAABIAoIrAAAAAAAAFzu4MmjQwEQ9BwAAAAAAEGkSFVyZNOmjkI9rVOfJkycldZkAAAAAAACir1uQAitLly61PHnyJNcsAQAAAAAAUr2MCZm4WrUqIf/2givnzp2zzp0fTr6lA3CeY6fOWZ2+a9zfC/uXs+yZ0ydqGuBifM74LALQceDq/rRJaQHHbAAcLy5ScGXUqNHu/y5dHvb/7Z9RxoxWuHARK1asWBIWBwAAAAAAIIKDK/XqXe/+nzx5ilWuXNnSur59+1qlSpXs7rvvTulFAQAAAAAA0RBc8XiBlWPHjtmhQ4fOe75QoUKJXqCTJ0/a5MmTbf78+S4bpl69enbPPfdY+vT/l27erl07O378+Hmvbdy4sXXp0iXs95ozZ46lS5cu0csKAAAAAACQqODKmjVrrHfvXrZ69eqQz69YsTJRW1Y1WypWrGg33HCDXXvttS5489RTT9nHH39s06ZN8wdC7rzzTjtz5oz/dRs2bLCePXta8+bN2aMAAAAAACD1B1f69Xveihcvbn36PG85cuRItoVR8OSnn36yIkWK+B+7+uqrrW7durZo0SKrXbu2e+z2228Pel2fPn0sZ86c1qpVqzjnP2XKFJsxY4bly5fPBWhCWbx4sX344Ye2Z88eK1u2rHXt2tXy5s0bNM1HH31kM2fOtPz587v5zJo1i+5FAAAAAABEqUQNIbJu3Trr27e/Va9e3a688srzbkkJrgQGVuSKK65w/+/fvz/ka86ePWvvv/++tWnTxrJnzx7rvF955RXr2LGjlStXzi3j/fff74aODjRp0iRr0qSJXXbZZa6L0dq1a13QZOfOnf5pBg0aZA8//LCVL1/ezeeBBx6w119/3VauTFy2DgAAAAAAiMLMlcsvv9yOHj2SrFkrsXnjjTcsV65cLoMlFGWNbN261R566KFY56G6MAMHDrTRo0e7oIo0bNgwqCjv0aNH7ZFHHrEJEyZYs2bN3GOa9pZbbnGBmVdffdUOHjxoQ4YMsVGjRvnn06hRI9eVKb46MroFLg8AAIhstP8AAESPRGWutG/fwQUrdu/ebReSuvEMHTrUxowZE2sg591333XdhZRFE5s//vjDBTRuu+02/2MKiKjbj+fXX3+1AwcO2Lhx46x169auiK5GEVI9l+XLl7tp9P+RI0eC5qMMlsD5hDJ48GDXbcm7FS1aNEHbAQAApD20/wAARI9EZa4MGfKiG62nYcP6li1btvOeX7hwUZIXbPr06W5UIGWJxDZU8q5du+yrr76ykSNHxjmvffv2udGG1N0nkDJiPAqsyF133WWZMmXyP673Vo2WcOcTSq9evaxHjx7++wr0EGABACCy0f4DABA9EhlceckupC+//NJljgwfPjzOoZXHjx9vmTNntnvvvTfO+an4rkYi2rx5s5UoUcI9pvsbN270T+MFO0qXLm116tQJOZ9ixYqdNx+fz2ebNm2K8/2zZMnibgAAIHrQ/gMAED0SFVxp1KixXSgazUej/gwbNszVQInL2LFjXReemJkk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mmWVKlWyu+++O1nWDQAAAAAARGC3oEaNGvtvCxYsCLof87mLYcCAAXbZZZe54Ec4XnnlFevYsaOVK1fOrrzySrv//vtt6dKlQdNMmjTJmjRp4ubbuHFjW7t2rQua7Ny50z/NoEGD7OGHH7by5cu7+TzwwAP2+uuv070IAAAAAIAolajRgiZN+sh69+5z3uM+n88mT54U8rnk9NNPP9k777xjS5YsCWv6Q4cOuRoxo0ePdkEVadiwoVWuXNk/zdGjR+2RRx6xCRMmWLNmzdxjmvaWW25xgZlXX33VDh48aEOGDLFRo0b559OoUSOrWLFinO+vbku6BS4PAACIbLT/AABEj0QFV0JRYEWZIHny5LELae/evda2bVsXXClQoEBYr/njjz9cQOO2227zP6aAiLr9eH799Vc7cOCAjRs3znUL0vrotmHDBtcFSZYvX25HjhwJmo8yWALnE8rgwYOtf//+iVhbAACQVtH+AwAQPRIUXKlWrUrIv0WBCAUhOnd+2C6kjz/+2AVKxo4d626yceNGV0vln3/+cXVV0qcP7u20b98+95i6+wTKlSuX/28FVkQjD2XKlMn/uOqoqEZLuPMJRXVhevTo4b+v5S9atGgi1h4AAKQVtP8AAESPBAVXRo0a7f7v0uVh/9/+GWXMaIULF7FixYrZhXTzzTefl7GyaNEiV0uldevWli5duvNeU7x4cRf42bx5s5UoUcI9pvsKyni8YEfp0qWtTp06Id9b6xZzPgoqbdq0Kc5lzpIli7sBAIDoQfsPAED0SFBwpV69693/kydPCapXcjGVKlXK3QKpnoqCIso6CaVKlSquG9BLL71kb775pntM3X8CC9XWrl3bqlatak8//bRNnz7dn52yZs0a2759uzVo0MDNR0Ec1V8ZOXKke15diHbs2HEB1xgAAAAAAERczZWUCqwklrryaLjm5s2b2/z58y1nzpyudosCMh5lvEybNs0FaBS8qVmzpguaKFPl3XffddNkyJDBzadFixY2d+5cy5Ejh5uPRg3ScwAAAAAAIPokW0HblKRMkvz588c5Tb169VxxWgVXVEOlWrVqbtjowNcpSKIuRsuWLbMtW7a47kQaijkwcFK/fn3XneiXX37xz0dFbcMtrgsAAAAAACJLRARXGjduHNZ0KjzbtGnToEBJTMpgqV69uruF8vvvv7t6K958Jk+e7GqwaEhmAAAAAAAQfcIOrvTu/awNGvSi+3vu3J/99VeijYIvV199tQuwaFhmDc+s+iuBXYyQNmXPnN7+HFwhydMAuPj4/gIAkHraXCAahR1c+fLLL+yFFwa6+iUaLWjFipUWjWrVquUCKuo+dPbsWVfkNm/evCm9WAAAAAAAILUHV6644gqbMGG8Vav2v+4yqksSG9UhiWTZs2e366+PzswdAAAAAACQyOBKz55P2wsvDLCdO19299u0uTfWaaM1qwUAAAAAAESfsIMrDRo0dLeTJ09arVo17LffFl7YJQMAAAAAAIjE0YKyZMliY8e+b9mzX3JhlggAAAAAACDSh2K+6qqr3P+nT5+2bdu2ms9nVqRIEcuUKVNyLx8AAAAAAEDkBVcUVBk9epQrcHvixAn3WNasWa1du/vtkUe6EWQBAAAAAABRI1HBlTfeGGFfffWlPfPMs25koHTpzJYuXWajR490wxP36PGf5F9SAAAAAACASAmufPHFdBs+/HWrUaOG/7HSpcvYlVdeaT16PE5wBQAAAAAARI30iXnRwYMHrVSpUuc9rsf0HJDSjp06Z5V6rXI3/Z3YaQCkbRwLAODiHlMBIFolKrhSpkwZmzLl4/Me//jjye65tGLDhg22a9eulF4MAAAAAAAQbd2CHn+8h3Xr1tVmz/6vVa5cxT22fPkftnr1ahs16k270LZt22b79u0LekwFdUuXLp2g+XTo0MEaNGhg/fr1S+YlBAAAAAAA0SJRwZW6deva9Olf2IQJE2zt2rWWLl06F2R56aWXrVix4nahDRgwwCZNmmRFixb1P6aMmWnTpl3w9wYAAAAAAEhycEUUROndu4+llJtuusmmTp2aoNf4fD7buHGj5cuXzy677LJYpztw4IDLjClWrJhlzJgx5HzUpSh//vxuPvr7kksusQIFCiRqXQAAAAAAQJTVXEkNzp07Z+vXr7e9e/eGNf26deuscuXKVrVqVdd96JZbbnFBlED79++3li1buoyYxo0bW+7cuW3gwIFB06jrU4UKFdwQ1N589JrRo0cn6/oBAAAAAIC0Ic0GV9QFSPVSFAipWLGi/fTTT3FO37FjRzea0Z49e2znzp1Wq1YtW7ZsWdA09913n2XLls127NjhAjeLFy+2ESNG2JQpU4LqtJQrV84FdTSfq6+++rz5xHTy5Ek7dOhQ0A0AAEQ22n8AAKJHmgyu3HDDDS74sXnzZpdtUr9+fWvevLlt2bIl5PTKNvn5559t8ODBliVLFvfYc8895zJTPGvWrLGZM2dap06d3HxWrVplp0+fdhksn3/+uZtGjy1YsMBefPFFy5w5s3usd+/elidPnjiXV++bM2dO/y2wVgwAAIhMtP8AAESPVB1cUd2TFStW+G9Hjx71Z5iULFnS/a1gyeuvv+7qoHz22Wch5/P3339b+vTpXcaJR68LHF1IgRPp3r273XXXXdaqVSu7++677Y8//rBMmTLFOh89p4yYuPTq1csOHjzov8UWBAIAAJGD9h8AgOiR6IK2XnHYf/7ZYtdff4NdCLNmzbJBgwb577/77rt2zTXXnDedskhUTDa2oEX27NldjRal5wYWqD127FjQPGT27NmxFqaNbT7Hjx+Pcz0UyPEyZgAAQHSg/QcAIHokKnNF9Ubat29nzZvfal27dvE/3rnzQ7ZgwS/JtnD33ntvUOaKAisK6qi7TqBNmza5W2BGSaBKlSq5DJMff/zR/9jWrVvtr7/+8t+/6qqrXIAlsL6K59SpU0HzmTNnjv851WcJnA8AAAAAAIguiQquvPzyS5Y/fwGbN29+0OMPPdTZ3n77bbuQFFipU6eOjR071n799Vf75JNPrGnTpla2bFlr06ZNyNcoE6VLly7upq5Dyk5R159AGp65b9++1rNnT3vppZdcbRXVWmnXrp29+eabbpqCBQvagw8+aF27dnUFdTUfdR9SwCddunQXdL0BAAAAAEAEdQv65Zf59tln0yxnzlxBj2uI4mXLltqFpOySqVOn2rBhw+ydd95xRWnbtm3raqWo205shg4d6grPDhkyxAVSFGhRJktgF6Bnn33WZaeMGzfOZbAUL17cBU9at27tn+a1116zvHnzuiJ1mo+CLeoWpFGGAAAAAABA9ElUcEW1SrJkyer+DszYOHDggL92yYWkQrSjR49O0GvUnadfv37u5mnfvv150912223uFhsVtH3hhRfczSu6261bNzccNAAAAAAAiD6J6hZUvXp1++qrL4OCK2fOnLGRI9+wWrVqWySbOHGiq/6voZ2/+eYba9GihRtauUmTJim9aAAAAAAAIK1krvTo8aR16tTBdQ9SvZEBA/rbr78ucIVuJ0yYaJFMdV3UNUgZMGfPnrW6deta7969L0rGDsKXPXN6+3Nw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tU8//dQ/TYcOHVx3Jc1H2TXVq1c/bz4xnTx50g4dOhR0AwAAkY32HwCA6JHkMR1vueUW69nzSRsyZLB16/aIf7jm5KDuOY899ph7j9hGKHr//fctW7Zs1rp161jns2bNGpszZ47LQsmaNaurFaMitspMCcxImTFjhnXt2tUFVxQwUqDl5ptvts8++8xNoy5I8+fPD5rPc889F7LobqDBgwdbzpw5/TcFeQAAQGSj/QcAIHokarSgadOm+//u1u1Ru/TSS23ZsqV2442N7KGHOoc1D3XBURDDo6462bNn999X7RZ1t1GAY8KECSHn4fP5bOzYsa7ArZYhNuvWrXPzUdFbjzJvVDg3ZoZMly5dznt97dq13f9///23m4+6BHkyZ85spUuXjnNde/XqZT169PDfV+YKARYAACIb7T8AANEjUcGVwKCE6qJ06vSg//7mzZviDHR4lCXywgsv+O+PGzfOrr32Wvf3iRMnXBHbnTt32g8//GB58+YNOY8ff/zRBTwmTZoU53sps0XdlU6dOuWW1xNY2Fa1Y0QjExUoUCBB84mviK8COV43KgAAEB1o/wEAiB5J7hYUU9Omt4Q1XZs2bYJG/IkZWNm6davNnj071kCHV8i2WrVqVqfO/4rrxkZdihQ8UdegwFot6grkUUFcZaFomOmYTp8+7f6vWLGiC6oEDg2tAFDgfAAAAAAAQHRJVObKhaKhmFu2bGnLli2zKVOm2P79+91NNIKP6pUEditSLZRXXnkl3vkqQKOCt+ry88Ybb7haK88++6zrVuTJnz+/9enTx5566imXiVK/fn3XbUnFbFW0tnv37laoUCFXGFd1WUaMGOGW5/nnn3fZLKq/AgAAAAAAok+qCq6ogO2GDRtcgdiHH3446LmBAwfaXXfd5b//3//+16688kqXAROO4cOHu/mqkG2+fPncqD96vf72qDitslPURWn8+PFuqGUNzRz4HgqqaB59+/Z1r9Xw00eOHHEFbgEAAAAAQPRJVcEVZZSoi1A47rzzTncLl7r8KECjm6dTp04Jnq+6Ban6v26izBpltSgoAwAAAAAAok+Cgisanjjaffjhh270oaZNm7qMFQVrihQp4oZsBgAAAAAA0SdBwZWWLW+zaKcuQq+++qo988wzrkaMCuGqO5EyY6Jd9szp7c/BFZI8DQBEA46ZACIN53mRvW+///dlVrBgYUufPtnHRAGiL7gyefIUi3bqFqTAim4AAAAAAAAJCq5oSGMAAAAAAAD8H3K6AAAAAAAAkoDgCgAAAAAAQBIQXAEAAAAAAEgCgisAAAAAAABJQHAFAAAAAAAgCQiuAAAAAAAAJAHBlVTk2KlzVqnXKnfT32lhGgBA6pNa2wralbSDfQU+Q+AYEXk4tl9YBFcAAAAAAACSIKqDKwMGDLCpU6em9GIAAAAAAIA0LFUHV7777jtr3bq1jR8//rzn1q5da08//bQ98MADNnToUDt69GiC5z979mxbsWJFMi0tAAAAAACIRqk2uLJ9+3br1KmTC4AsXrw46LmlS5dajRo1bNu2bVanTh2bOHGi3XDDDXbq1KkUW14AAAAAABCdMloqdO7cOWvTpo317NnT3n333fOef+aZZ+z666+3CRMmuPv33HOPFStWzMaNG2cPP/xwrPP97LPPbMaMGZYvXz674447Qk6zbNkyF6zZs2ePlS1b1jp37mx58uQJmmbKlCk2c+ZMy58/v5vPrFmzrGLFinbXXXcled0BAAAAAEDakiozVwYNGmRZs2a1Rx999LznTp48af/973+tVatW/scULLnxxhtd4CQ2w4YNs3bt2lnx4sWtcOHCdt9997lASsygieaTKVMmq1evni1fvtwqV65su3bt8k8zZMgQ69Chg5UoUcLNR0Gg4cOH070IAAAAAIAoleoyV+bNm2dvvvmmLVmyJOTzmzdvtjNnzrhMlUAKmsyZMyfkaw4dOuSK144aNcrVaJFGjRpZ1apV/dMcO3bMunTpYu+//761aNHCPdaxY0e7+eab7ZVXXnG3gwcP2osvvhg0n5tuuskFYOKigJBugcsDAAAiG+0/AADRI1UFV/bv3+8ySsaMGWMFCxYMOc2JEyfc/5deemnQ47rvPReTMlAUGLn99tv9jykgUqZMGf/9X3/91b2/ugQpg8Xn87nbli1bguZz+PBha9mypf8xdQdS96G4DB482Pr37x/v+gMAgMhB+w8AQPRIseDKt99+a2PHjvXf79Onj/30008uCKIAh26yadMm++abb2zHjh320UcfWc6cOd3j+/btC5rf3r17LVeuXCHfS8+lT5/e/1pP7ty5/X9782vWrJnrFuRRFotqq3jTaD45cuSIdT6h9OrVy3r06BGUuVK0aNE4XwMAANI22n8AAKJHigVXSpYsGZRJogCGutjELB67YMECK1WqlJs2Xbp0LiihIIqGUG7atGlQVkmVKlVCvpe6EKlIrroUqfuQKCtFgRuPF+yoUKGC1a5dO+R8NE188wklS5Ys7gYAAKIH7T8AANEjxYIr6pIT2C1H1BUo5mMqIKtuN61bt/Y/pq5D7733nquRoiySuXPn2m+//ebqoYSioEv58uVd3ZSRI0e6xz744AOXDeNRQEVdhTQS0fTp0+2SSy5xj69bt862bt1q9evXdzVatHwqjvv666+75ydNmuSGjQYAAAAAANEpVdVcSchoQosWLXL1TnSbP3++G7ZZRWpDyZAhg7311luui4+mVeaLAiLKiPGou8+0adPc0MqlS5e2WrVqueCL6rh4w0F781EWjQI66makaZSFo+cAAAAAAED0SfXBlZdeeskKFCgQ9JiCIwqSqMvQzp07bfTo0S4gEhdlnqxfv96NRqShm2vWrOnmEThvzUPDMytwo0K26vqjbJWMGf9vM2moZs1Hr/XmowCPV5cFAAAAAABEl1QfXNFQyKEo06Ru3boJmlfevHn9wyx7gZKYVNdFXYRiq7uyePFiK1GihH8+U6dOtY0bN8aaNQMAAAAAACJbOp8qsiJsCxcudPVflOVy5MgRW7Jkib388sv26KOPhj0PjRakLkUa+jm2EY4ijQoB79y5zQoWLOwCY5Eu2tZXWGf2c6Tisx09n+0LfbyOtvaf7070fHc454l87Ge+z5HqXDK2/6k+cyW1qVOnjus6pCDL2bNnXbehmN2WAAAAAABA9CC4kgiXXnqpNWzYMPn3BgAAAAAASHOiI78JAAAAAADgAiG4AgAAAAAAkAQEVwAAAAAAAJKA4AoAAAAAAEASEFwBAAAAAABIAoIrAAAAAAAASUBwBQAAAAAAIAkIrgAAACDIsVPnrFKvVe6mv4GLic9f5GLfXvhtxzZOOVEdXNm8ebPt2bMnpRcDAAAAAACkYRktldm5c6ft378/6LEsWbJYyZIlQ06/Y8cOy5o1q+XKlSvB73X//fdbgwYNrF+/foleXgAAAAAAEN1SXXClb9++9tFHH1nhwoX9j5UtW9a++OKLoOlmz55t3bp1c8GYbNmy2fXXX29jxoyxnDlzpsBSAwAAAACAaJUquwU1adLEVq9e7b/FDKwsWrTIbrnlFuvQoYPr1rN161Zr1aqVbdiwId55b9myxY4dOxbnNIcPH3Zdhs6di70vm5735kP3IgAAAAAAoleqDK74fD4XsDh48GDI55977jm7+uqrrWfPnpY+/f9W4c4777Tq1avHOs/169db1apVrVy5clasWDFr3rz5efM/cOCAC9JcfvnlVq9ePdfVaMiQIUHT/PXXX1apUiUrX768FS9e3M3ntttus5EjRybLugMAAAAAgLQlVQZXPvvsM7vmmmusYMGCLiAyb948/3OnT592XYJatmxpZ86csU2bNtnJkyfjnWfHjh2taNGitm/fPtu9e7dVrlzZli5dGjRN27ZtXbBGdVwU3Pntt99s6NCh9umnn/qnUbaM6r9oPrt27XIBnZjziUnLd+jQoaAbAACIbLT/AABEj1QXXLnuuutcdsi2bdtcJomCLLfeeqv9888/7nl1A9LJiroClShRwtVayZEjh913332uO08oa9assTlz5rgsFBW/TZcunStiG1gEV+85Y8YM69q1qwuurF271gVabr75ZhfsEXVRmj9/ftB8lEWTO3fuONdp8ODBrhaMd1OQBwAARDbafwAAokeKBVcUOAmsq+LVL2nXrp2VKVPG/a0AhrrbnD171h/g8LoBqejtzz//7DJMFAiZO3euPfPMMyHfa926de51FSpUCBqByHsfWblypfu/S5cu1qxZM9fdp0WLFvb777+7IIr8/fffbj7qEuTJnDmzlS5dOs517dWrl+uC5N1U9wUAAEQ22n8AAKJHio0WpCyRF154wX9/3Lhxdu211543nYIXhQoVckEUyZcvnwu63HPPPf7hmVVDpU2bNkHddwJpNCEVpz116pRlzPh/qxxY2DZTpkzu/59++skKFCiQoPkcP348znVVIEc3AAAQPWj/AQCIHimWuaJgSGDmigIrKmSrOiqBlOWxceNGNxyzZMiQwRo0aOBqngTau3dvrMMwq76KgifqGuRRtyN1BfJcddVVLpAzderU816vOi9SsWJFF1RRAMajoaAD5wMAAAAAAKJLimWuhKIghmqsPP74425EHmWrPP/881aqVCkXjPGoXkqjRo2sdu3arkbLr7/+ah988IG98847IeerTJSHHnrIdfl54403XK2VZ5991gVzPPnz57c+ffrYU0895TJR6tev72qvKBtGRWu7d+/uMmhUGFd1WUaMGOGCOVo+ZbN4XYcAAAAAAEB0SVXBFWWOTJo0yY3QoyCICsXefffd1qNHD7vkkkv802kY5lmzZtnLL79s7733nusW9Mknn7gaKbEZPny4m58CM+papFF/rrzySve3R8VplZ2iLkrjx493Qy1raObAwI6CKppH37593WtVI+bIkSOuqxIAAAAAAIg+qSq4IuXKlbO333473umUsTJ9+vQEBW4GDhzobp5OnTqdN92dd97pbrFRtyBV/9dN9u/f77JaFJQBAAAAAADRJ9UFV1K7Dz/80I0+1LRpU5exomBNkSJF3JDNAAAAAAAg+hBcSSB1EXr11VfdsM8aIlqFcNWdSJkxAAAAkSB75vT25+AKKb0YiFJ8/iIX+/bCbzu2ccohuJLQDZYxowus6AYAAAAAAJBiQzEDAAAAAABEAoIrAAAAAAAASUBwBQAAAAAAIAkIrgAAAAAAABBcAQAAAAAASBlkrgAAAAAAACQBwRUAAAAAAIAkyJiUFwMAACBhrhmw1jJkudQW9i9n2TMn/DrXsVPnrE7fNe7vxM4DiETJ8d1IDfNIDcsQcx6/9i2T4NdfiOVIjnkkdj6pZR6R+hlbGAFtIq0xAAAAAABAEkR1cGXAgAE2derUlF4MAAAAAACQhqXKbkHff/+9ff3117Z//34rVqyYtW/f3q688sqgaf755x979913bfXq1fb8889bxYoVE/w+s2fPtnPnztldd92VjEsPAAAAAACiSarLXBk8eLDddtttdtlll9kNN9xga9asscqVK9vixYv90wwbNszq1atne/futY8//th27dqVossMAAAAAACiV6rLXBk7dqw9+uij1r9/f3e/Q4cOVq5cOZs0aZLVrFnTPdayZUvr3r27bd++3UaOHBn2vD/77DObMWOG5cuXz+64446Q0yxbtswmTpxoe/bssbJly1rnzp0tT548QdNMmTLFZs6cafnz53fzmTVrlsucIQMGAAAAAIDok+oyV9T9Z9OmTf77Bw8etH379lnp0qX9j5UsWdIyZMiQoPkq26Vdu3ZWvHhxK1y4sN13330ukBIzaHLjjTdapkyZXGbM8uXLXdZMYGbMkCFDXMCnRIkSbj5t2rSx4cOH24oVK5K03gAAAAAAIG1KdZkrH3zwgXXp0sVq1KjhAiFLly61J554wh566KFEz/PQoUOueO2oUaPsgQcecI81atTIqlat6p/m2LFj7n3ff/99a9GihXus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znny5LErrrgizvZf66x1L1++vOXLly/8N1FBW1wczz//vC9Lliy+ihUruv87derkO3v2bMRu/jlz5vhq1qzpK1GihK9q1aq+rFmz+rp27eo7c+aML5J9+umnvkKFCvmuvPJKX+XKlX2NGzf27d692xepvvnmG98VV1zhK1mypK98+fK+ggUL+r7//ntfpNixY4eve/fuvssvv9x9hnv37n3eNJ9//rmvUqVKbjtUqVLFd8kll/j69+/vS6v+/vtvd3zSOqdPn9735ptvnjfN8OHDfdmzZ/ddd911/lv9+vV9adWyZct8rVu3dp9fNY1ffvnledOsXr3a7d/8+fP7atWq5fZz06ZNfYcPH/alNadOnfL16dPHly9fPv9nV9/h//73v0HTzZ0719esWTM3nbbLkiVLfGnVwYMHfY8++qgvV65crk0qUKCA+3/p0qUhp9d+1TFN6z1u3LgkvffTTz8d1P4/8sgjvnPnzvki1bfffuu+K6VKlXLtYLZs2XxPPPFERK+zTJw40X1XSpcu7fb1rbfe6jtw4IAvUk2bNs0dM7W+ZcuW9RUpUsQdMyLF1q1bfd26dXNtYebMmX0vvPDCedN88skn7jhRrFgx91m/9NJLfUOGDPGlVWrn7r//frfOOvZNmDDhvGm0HS677LKg9v9f//qXL61auHCh784773Rtu9b5hx9+CHmO4J3j6reNzn/uuOMO37Fjx3xpzfHjx309e/b05cmTx31mCxcu7L6/8+bNC5pO5wM333yzL2/evG67rF271pdW7du3z9elSxd/+6/jtPbjn3/+GXJ6HbfVfmm9J02alKD3olvQRTJ9+nQbPHiwzZ49210JVgR86tSpNnLkSItUiuJPnDjRRXm1vgsXLrT33nvPJkyYYJHqp59+slatWtmgQYNc9Hv58uXWu3dv27lzp0UiXYm955577IEHHnBXd3WVY+DAgXbnnXe6qx6RQJ9fXdHX9za2q5CKbH/yySfuas4ff/xhX375pb3wwgv22WefWVqkqP7VV19ta9eutWzZssU6na5Gz50713/78ccfLa3S/m3RooXbf7H597//7bIddDXj999/t3Xr1rnj2quvvmppzfHjx92QgzpOrVixwl2FvP322+2OO+6wQ4cO+afTMeyhhx6y77//3tI6HYd1FVZXJ9Um6fuq+y1btgw5/SOPPGK33XZbkt/3448/ttdee81+/vln9znTZ+eDDz6wd955xyKVviPTpk1z3xF9htQ2vv766/bpp59apJo5c6a1a9fO3njjDXfs1L5+7LHHbPfu3Rap+/i+++6zxx9/3K2v2o0nn3zSfZ8OHz5skUDHRx0jdG5z+eWXh5xGx06d4+t/fdZ1bv/ss8/a119/bWmR1rVhw4Zu3eNSsWLFoPb/m2++sbRKbaDOZX/99ddYp+natas7B9TnftGiRW47/fe//7VRo0ZZWqMMq7x58/o/s/q91qBBA9feKbMzcLt0797dvvjiC0vrtm/fbtWqVXPnAWr/tR+VuXLXXXeFnL5z586xPhevZAoIIR4tWrQ4L6r74IMP+qpVqxZV205XNQYOHOiLVA0bNvQ1adLEFy2+/vprF9Xdtm2b/zFdmVSGx6hRo3yRply5ciEzV0LR1QBdqU3rlJ0RW+aKruLoas7KlStdJkQk2L9/f6yZKzVq1PA9/vjjQY9dffXVLgshEuiKpdY95tUrWb58eZrPXAll5syZbr10hTrQ+PHj3VUtfa6TmrmiNuH2228Peqxt27busxMt1C7oiuFrr73mi1R16tRxV7KjxZQpU9x349ChQ/7HTpw44UuXLp3vgw8+8EWa4sWLh8xcCUWZPL169fKldXFlrih7U1l/ajdOnz7tiwRbtmyJNXOlTJkyLtszkLI+lQESCX7//Xe37jqni+mXX35J85kroSjrXOu1d+/eoMfHjBnju+aaa1z2KpkrqZhqNdSqVSvosauuuspFBdXnLVKpToUi2rNmzXJXP9UPtUOHDhaJFO3VujZv3txdtVFkW5HSSKY+i7J169agbBZtC61/tFLWjjJeSpcubZFMVypbt25tN998s+uTHclX4qVv3742efJkGzNmjMvkeO6551xNDl3ZiQTKwlH/42ioExW4zpdeemlQDRRdhdcVeGVeJkf9qNja/6VLl7o+/JFK7aDaRGV0tG/f3goXLmxt2rSxSKQrwcpIUvuvv9X+RWrGalztv8559JmO5vZf+11ZcZHe/uu4psylRo0audpjkZyVLgMGDLBx48a5DHy1/z179nS/cZThGCltoeolKVM7WixcuNAdxwLr661cudKd23344YeujlBiUND2Itm3b59LwQqk+yp8qhTsmM9FUiPzzDPPuMKYSj97/vnnY02tTOsUVFCgTN0KlEaq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/kN755233TDKHg33G7PWRaC2bdu691RdDQU0dJyO+ZpQbYuyE5V5EUhtsgqreq666mr74gu1HdNdRqKW8d//fjzOLJRwtovqkXk1SmITznuHs/3i2wehto2GIY5Z28SjYrLjx0+wzz//3H7//XfXxn/00WQrV65c2MuU2P0hd9xxpwvgLFz4mwueaFmqVv2/+mkx931i9uH/hoV+0LX/XnAlnO2k4sGnT5+2W29tFuu8gQspnYYMuqDvAACIKI880tWKFStmzzzT64K/lwrhDho00I38EG5/dQWRdLXSK+4LAACS7sEHO1qlSpXtiSd6XPDNqe5NAwe+YF26dLVChf4vMBSXsWPfcxdcdFEISAlkrgAAUq306dPbc889n6DXtGt3/wVbHgAAcOGpK3y/fv0T9BrVnwNSEsEVAECChOqaAwAAIluorjkA/g/dggAAAAAAAJKAoZgBAAAAAACSgOAKAAAAAABAEhBcAQAAAAAASAKCKwAAAAAAAElAcAUAAAAAACAJCK4AAAAAAAAkAcEVAAAAAACAJCC4AgAAAAAAkAQEVwAAAAAAACzx/h8+XMHaPI/ZugAAAABJRU5ErkJggg==", + "text/plain": [ + "
" + ] + }, + "metadata": {}, + "output_type": "display_data" + } + ], + "source": [ + "import numpy as np\n", + "\n", + "from tatc.tradespace import COLORS\n", + "\n", + "sampled = pd.concat(observed.values()).drop_duplicates(\"target_hash\")\n", + "sampled = sampled.assign(latitude=[point.y for point in sampled.geometry]).sort_values(\"latitude\")\n", + "shown = sampled.iloc[np.linspace(0, len(sampled) - 1, 12).round().astype(int)]\n", + "fig, axes = plt.subplots(1, 2, figsize=(11, 4), sharey=True)\n", + "for ax, (name, observations) in zip(axes, observed.items()):\n", + " times = []\n", + " for point in shown.itertuples():\n", + " samples = observations[observations.target_hash == point.target_hash]\n", + " longitude = np.array([p.x for p in samples.geometry])\n", + " hours = (samples.epoch - START).dt.total_seconds().to_numpy() / 3600 + longitude / 15 # local solar time\n", + " times.append(np.sort(hours % 24))\n", + " ax.eventplot(times, colors=COLORS[0], lineoffsets=range(len(times)), linelengths=0.6, linewidths=1.5)\n", + " ax.set(xlim=(0, 24), xticks=range(0, 25, 3), xlabel=\"Local time of each sample (h)\")\n", + " ax.set_title(name, fontsize=9)\n", + " style_axes(ax, grid=\"x\")\n", + "axes[0].set_yticks(range(len(shown)), [f\"{latitude:.0f} deg\" for latitude in shown.latitude])\n", + "axes[0].set_ylabel(\"Latitude of the point\")\n", + "plt.show()" + ] + }, + { + "cell_type": "markdown", + "id": "575ddea4", + "metadata": {}, + "source": [ + "Satellites that follow each other in one plane pass over a point minutes apart, on one or a few consecutive orbits, then leave it for the rest of the day; the Walker plane, inclined 45 degrees, also never samples points beyond about 50 degrees of latitude. The two sun-synchronous planes sample most points two to four times, spread over the day. The four satellites in one Walker plane sample 68% of the points at least four times a day, but only 27% accurately: half of their revisits are 0.4 hours apart, and they leave a gap of 13.8 hours. The four satellites in two sun-synchronous planes sample fewer points four times (58%), but 85% accurately: their samples are 5.9 hours apart, in four of the eight 3-hour intervals of the day." + ] + }, + { + "cell_type": "markdown", + "id": "1305deb2", + "metadata": {}, + "source": [ + "## Find What Drives the Objectives\n", + "\n", + "`sensitivity` estimates the share of the variance of each objective, over the designs, that each decision explains. The summary keeps the decisions of each design as columns, named by their paths (such as `layout.walker.planes`). A decision of one alternative is judged among the designs that have it (their share is `active`): the Walker decisions among the Walker designs. The shares are adjusted for what a decision would explain by chance." + ] + }, + { + "cell_type": "code", + "execution_count": 6, + "id": "40126ee8", + "metadata": { + "execution": { + "iopub.execute_input": "2026-11-15T04:33:14.444051Z", + "iopub.status.busy": "2026-11-15T04:33:14.443895Z", + "iopub.status.idle": "2026-11-15T04:33:14.461577Z", + "shell.execute_reply": "2026-11-15T04:33:14.461057Z" + } + }, + "outputs": [ + { + "data": { + "text/html": [ + "
\n", + "\n", + "\n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + "
sufficientaccurateactive
variable
field_of_regard0.250.251.00
layout.walker.per_plane0.220.180.64
layout0.190.121.00
layout.walker.planes0.120.290.64
layout.sso.planes.count0.100.190.36
altitude0.030.031.00
layout.walker.relative_spacing0.030.060.64
layout.walker.inclination0.000.000.64
\n", + "
" + ], + "text/plain": [ + " sufficient accurate active\n", + "variable \n", + "field_of_regard 0.25 0.25 1.00\n", + "layout.walker.per_plane 0.22 0.18 0.64\n", + "layout 0.19 0.12 1.00\n", + "layout.walker.planes 0.12 0.29 0.64\n", + "layout.sso.planes.count 0.10 0.19 0.36\n", + "altitude 0.03 0.03 1.00\n", + "layout.walker.relative_spacing 0.03 0.06 0.64\n", + "layout.walker.inclination 0.00 0.00 0.64" + ] + }, + "execution_count": 6, + "metadata": {}, + "output_type": "execute_result" + } + ], + "source": [ + "from tatc.tradespace import sensitivity\n", + "\n", + "decisions = [\n", + " \"altitude\",\n", + " \"field_of_regard\",\n", + " \"layout\",\n", + " \"layout.walker.inclination\",\n", + " \"layout.walker.planes\",\n", + " \"layout.walker.per_plane\",\n", + " \"layout.walker.relative_spacing\",\n", + " \"layout.sso.planes.count\",\n", + "]\n", + "shares = sensitivity(summary, decisions, [\"sufficient\", \"accurate\"])\n", + "shares.round(2)" + ] + }, + { + "cell_type": "code", + "execution_count": 7, + "id": "b1adf213", + "metadata": { + "execution": { + "iopub.execute_input": "2026-11-15T04:33:14.462929Z", + "iopub.status.busy": "2026-11-15T04:33:14.462770Z", + "iopub.status.idle": "2026-11-15T04:33:14.553390Z", + "shell.execute_reply": "2026-11-15T04:33:14.552788Z" + } + }, + "outputs": [ + { + "data": { + "image/png": "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QT4RERERkc0wyCeiFCU0lPcbYF0SEdkf18knCgDBwWyPJ1Y95soVlij7Sun8tS6jYwwJCQ5K7mIQESU7BvlEAWDkknA5dfVccheDyK8Vy51aJnbMn9zFICLyCwzyiQLA0cjbcuiCkdzFICIiogDBHAAiIiIiIpthkE9EREREZDMM8omIiIiIbIZBPhERERGRzTDIJyIiIiKyGQb5REREREQ2wyCfiIiIiMhmGOQn0GeffSanT59OnE/DZvURFRWljyMjI5O7WLJmzRrZvXt3cheDiIiI6J5gkJ9AzzzzjOzdu1f8jWEYGmCfOXMm2erj5s2b+vjvv/+W5DZ27FhZuXJlcheDiIiI6J5gkG9T0dHRGmDv378/uYtCRERERPdY6L0+oN0tXLhQbty4IcHBwVKwYEGpXr26ZMiQwfE6epMLFSoklStXdnrfsmXLpFixYlKpUiV9jJSXn3/+WfdTt25dyZUrl2Pbq1evypdffimPP/64ZMqUyfH83LlzpUGDBlKgQAFZsGCBPvfNN9/I0aNHJUuWLNKmTRunY/7www+SLl06qVGjhj4+dOiQbNq0SVq2bCk5cuRwvD9v3rxarrjOzRv//POPfPXVV3pOxYsX1+d27typjREcB2VJmzatY/tff/1VLly4IDVr1pQff/xRLl++LE888YTTPlesWCElS5bUc9yxY4ekSpVKGjVqJKlTp/ZYjg0bNsjx48clKChIcufOLVWqVNH/3e03e/bsWg7s96GHHtI6s7pz547WG86tVKlScv/99991PLz/8OHDUqRIEalatarWIREREVFSYZCfyDZv3iyXLl3SnvQ///xTA7+vv/5a7rvvPn39p59+ki1btmgAbzp27JgG7OZzs2bNkj59+kidOnU0r71r166aetO+fXt9/ezZs9pLj9etQf6zzz6rwT+CfHNfCKCRsoMA2jXI//777zVwRrAPU6ZMkffee08+/fRT6datm6b84NhTp07VID+uc4sLGhsPP/ywBvjYLxoMnTp1kt9++00efPBBfR37X716tQbLgMYKGkYIikuUKKENJNcgf/jw4ZI1a1atx2rVqun+MmfOrOeFAN2dPXv26HZw4sQJ2b59u543PgfrfvF+NLjQKNu1a5eWA9ua9X7w4EFp0aKFHg+Nlq1bt0rFihVl6dKl2ihAXbVu3Vo/h1q1aumx8DwaOr42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ASA4OHB+VKNjjOQuAhERUYrHm2ERBYCRS8Ll1NVz4u+K5U4tEzvmT+5iEBERpXgM8okCwNHI23LoAnvIiYiIyDuBkwNAREREREReYZBPRERERGQzDPKJiIiIiGyGQT4RERERkc0wyCciIiIishkG+URERERENsMgn4iIiIgoJQf577//vsyZMyfpShNgXOvjrbfekoULF4q/GjNmjKxYscJv9hNIUuI5ExERUQoJ8n/44QfZtm2b+KN3331XPv/883t6TNf6WLdunfz+++/ir7755hv5448/fHrPqFGjZPXq1QneT6BLiedMREREgcs26Trff/+9/Prrr8ldDNv56quvZM+ePU7Pvfbaa9K6dWtJSVLiORMREVHgCk3Imz/99FNZv369fp8jRw558MEHpVOnThIUFOQIENG7/d577931vvDwcBk+fLg+3rFjhyxYsEDOnz8vFStWlB49ekjGjBkd22O72rVrS/PmzR3PffTRR5I2bVrddvr06bJz5075+++/pUuXLvr622+/LXnz5nVsv337dpk1a5ZMmTJFH1+8eFH69u2r+3zyySf1uVWrVslvv/0mo0ePjvPcvHH27FkZNmyYNGjQQJ544gmJiYmRL7/8UhskadKkkXr16kmbNm0c2x88eFBef/11mThxop7T0aNH5dVXX5WyZcs6tsH7Dxw4II888oiOXFy6dEk++eQTfe3PP/+UL774Qv755x8pVaqU9OzZU7JlyxZruhEaRjin3Llza3kee+wxx+uowyNHjmgKkhnoo1xbtmyR+++/X+677z49HuodPf5WH3zwgQQHB0u/fv3iVTYrvAef3eHDh6VIkSLSrVs3yZcvn742dOhQLTc+z82bN0uqVKnk2WeflTJlynh9nqZ9+/bJvHnzJCIiQqpVqybPPPOMhIb++yNiPWfzuPXr15dr167JTz/9pMd96qmnpEKFCk77XL58uXz99deSM2dOadWqlWzYsEFKlCgh7dq18+rciYiIiO55T3758uWlWbNm+lWoUCEN9BB0m0qXLq0B1q5duxzPRUdHy8iRIx1B/MqVK6VmzZpy48YNqVy5ssyePVtq1aolt27dcrxnzZo1GiRabdy4UQMvQGCVK1cuKVy4sKM8GTJkcNoewd3UqVM1aAUEZvPnz5dp06Y5tkFgf+7cOa/OLS4nTpyQunXrys2bN6V9+/Ya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", + "text/plain": [ + "
" + ] + }, + "metadata": {}, + "output_type": "display_data" + } + ], + "source": [ + "from tatc.tradespace import plot_shares\n", + "\n", + "LABELS = {\"sufficient\": \"Points sufficiently sampled\", \"accurate\": \"Points accurately sampled\"}\n", + "ax = plot_shares(shares, list(LABELS), labels=LABELS, horizontal=True, legend=\"lower right\")\n", + "ax.set(xlabel=\"Share of the variance of the designs' means explained\")\n", + "plt.show()" + ] + }, + { + "cell_type": "markdown", + "id": "7d66f14c", + "metadata": {}, + "source": [ + "The field of regard explains the most of both objectives (25%), as it sets the swath of every satellite. The layout matters next, but differently for the two objectives. The number of satellites in each Walker plane explains more of sufficiency (22%) than of accuracy (18%), and the number of Walker planes the reverse (12% and 29%), as more planes spread the samples in time. The altitude explains little of either (3%), and the inclination nothing." + ] + }, + { + "cell_type": "markdown", + "id": "b1a15cd6", + "metadata": {}, + "source": [ + "## Summary\n", + "\n", + "* What a design achieves depends on how it is measured: counts of samples favor satellites that follow each other in one plane, and the sampling error of a daily mean favors samples spread over the day (`estimate_sampling_error`).\n", + "* `study.replace` copies a study with other parts, such as other metrics.\n", + "* Revisit statistics and local time coverage (`compute_revisit_statistics`, `compute_local_time_coverage`) explain why designs differ, and `sensitivity` finds the decisions that drive each objective.\n", + "\n", + "The next notebook, `SearchTradeSpace`, finds the efficient designs without evaluating every design." + ] + }, + { + "cell_type": "markdown", + "id": "55fc0d34", + "metadata": {}, + "source": [ + "## Notes\n", + "\n", + "* The sampling error here is that of a model of the field: an exponential correlation in time with a decorrelation time of 3 hours. With a simulation of the field (a nature run), `tatc.analysis.sample_field` and `compare_sampled_means` measure it directly (see `AssessSamplingSufficiency`)." + ] + } + ], + "metadata": { + "kernelspec": { + "display_name": "Python 3 (ipykernel)", + "language": "python", + "name": "python3" + }, + "language_info": { + "codemirror_mode": { + "name": "ipython", + "version": 3 + }, + "file_extension": ".py", + "mimetype": "text/x-python", + "name": "python", + "nbconvert_exporter": "python", + "pygments_lexer": "ipython3", + "version": "3.14.10" + } + }, + "nbformat": 4, + "nbformat_minor": 5 +} diff --git a/docs/examples/tradespace/PlanDeployment.ipynb b/docs/examples/tradespace/PlanDeployment.ipynb new file mode 100644 index 0000000..d9f059a --- /dev/null +++ b/docs/examples/tradespace/PlanDeployment.ipynb @@ -0,0 +1,609 @@ +{ + "cells": [ + { + "cell_type": "markdown", + "id": "c31c602b", + "metadata": {}, + "source": [ + "# Plan the Deployment\n", + "\n", + "The shares of points sampled so far are those of each design's full constellation, as if all of its satellites flew for the whole mission. In fact, they are launched over months or years, and fewer satellites sample the points meanwhile. This notebook accounts for the deployment of each design, then asks whether to commit to its whole constellation at once.\n", + "\n", + "It covers:\n", + "\n", + "* the **phases** of a deployment, and what a design achieves over its mission;\n", + "* **staged** deployments, whose later stages are deployed only if a rule decides to.\n", + "\n", + "It builds on `TradeCostAndUtility`, whose mission plan dates the launches of each design, and on `CompareScenarios`, whose fields the rules of the staged deployments respond to." + ] + }, + { + "cell_type": "markdown", + "id": "1aa0f625", + "metadata": {}, + "source": [ + "## Account for Deployment\n", + "\n", + "The launches of a design divide its mission into phases, in each of which some of its satellites fly. With `phases`, the study evaluates each phase with the observations of its satellites (over the same day, from the cache) and combines the phases over the mission:\n", + "\n", + "* `sufficient mission`: the share of points sufficiently sampled, on average over the five years from the first launch;\n", + "* `sufficient time`: the years from the start of development until a requirement is met, here that half of the points are sampled sufficiently.\n", + "\n", + "The phased study evaluates the efficient designs of `EvaluateTradeSpace`: the most sufficient design of each number of satellites and planes." + ] + }, + { + "cell_type": "code", + "execution_count": 1, + "id": "6bc87f54", + "metadata": { + "execution": { + "iopub.execute_input": "2026-11-15T04:33:55.747657Z", + "iopub.status.busy": "2026-11-15T04:33:55.747134Z", + "iopub.status.idle": "2026-11-15T04:33:58.254783Z", + "shell.execute_reply": "2026-11-15T04:33:58.254272Z" + } + }, + "outputs": [ + { + "data": { + "text/html": [ + "
\n", + "\n", + "\n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + "
descriptionsatellitesplanesdeployedsufficientsufficient missionsufficient timelost
design
8b0cd1e48b0e800 km, 60 deg FOR, SSO: 1 at 18:001.01.03.23.23.2inf0.0
f7413b1f8466800 km, 60 deg FOR, Walker 45 deg: 1 x 2 (spac...2.01.03.516.616.6inf0.0
33b006848799800 km, 60 deg FOR, Walker 45 deg: 2 x 1 (spac...2.02.03.830.227.3inf2.9
d5d3fa915ca7800 km, 60 deg FOR, Walker 45 deg: 1 x 3 (spac...3.01.03.838.038.0inf0.0
1af5f2707be3800 km, 60 deg FOR, Walker 45 deg: 1 x 4 (spac...4.01.04.568.263.54.54.7
6ba50f2632cd800 km, 60 deg FOR, Walker 45 deg: 2 x 2 (spac...4.02.04.069.664.34.05.3
6bef11e40977800 km, 60 deg FOR, Walker 75 deg: 2 x 3 (spac...6.02.04.597.887.14.510.7
\n", + "
" + ], + "text/plain": [ + " description satellites \\\n", + "design \n", + "8b0cd1e48b0e 800 km, 60 deg FOR, SSO: 1 at 18:00 1.0 \n", + "f7413b1f8466 800 km, 60 deg FOR, Walker 45 deg: 1 x 2 (spac... 2.0 \n", + "33b006848799 800 km, 60 deg FOR, Walker 45 deg: 2 x 1 (spac... 2.0 \n", + "d5d3fa915ca7 800 km, 60 deg FOR, Walker 45 deg: 1 x 3 (spac... 3.0 \n", + "1af5f2707be3 800 km, 60 deg FOR, Walker 45 deg: 1 x 4 (spac... 4.0 \n", + "6ba50f2632cd 800 km, 60 deg FOR, Walker 45 deg: 2 x 2 (spac... 4.0 \n", + "6bef11e40977 800 km, 60 deg FOR, Walker 75 deg: 2 x 3 (spac... 6.0 \n", + "\n", + " planes deployed sufficient sufficient mission \\\n", + "design \n", + "8b0cd1e48b0e 1.0 3.2 3.2 3.2 \n", + "f7413b1f8466 1.0 3.5 16.6 16.6 \n", + "33b006848799 2.0 3.8 30.2 27.3 \n", + "d5d3fa915ca7 1.0 3.8 38.0 38.0 \n", + "1af5f2707be3 1.0 4.5 68.2 63.5 \n", + "6ba50f2632cd 2.0 4.0 69.6 64.3 \n", + "6bef11e40977 2.0 4.5 97.8 87.1 \n", + "\n", + " sufficient time lost \n", + "design \n", + "8b0cd1e48b0e inf 0.0 \n", + "f7413b1f8466 inf 0.0 \n", + "33b006848799 inf 2.9 \n", + "d5d3fa915ca7 inf 0.0 \n", + "1af5f2707be3 4.5 4.7 \n", + "6ba50f2632cd 4.0 5.3 \n", + "6bef11e40977 4.5 10.7 " + ] + }, + "execution_count": 1, + "metadata": {}, + "output_type": "execute_result" + } + ], + "source": [ + "from trade_space_example import OBJECTIVES, cost_study\n", + "from tatc.tradespace import Requirement, summarize\n", + "\n", + "summary = summarize(cost_study.run(), OBJECTIVES, statistics=[\"accurate\"])\n", + "front = summary[summary.pareto]\n", + "leaders = front.sort_values(\"sufficient\", ascending=False).drop_duplicates([\"satellites\", \"planes\"])\n", + "\n", + "phased_study = cost_study.replace(phases=[Requirement(\"sufficient\", \">=\", 50)])\n", + "phased = phased_study.run(leaders)\n", + "PHASED = [\"deployed\", \"sufficient\", \"sufficient mission\", \"sufficient time\"]\n", + "deployed = summarize(phased, statistics=PHASED).set_index(\"design\")[PHASED]\n", + "leaders = leaders.set_index(\"design\")[[\"description\", \"satellites\", \"planes\"]].join(deployed)\n", + "leaders[\"lost\"] = leaders[\"sufficient\"] - leaders[\"sufficient mission\"]\n", + "leaders.sort_values([\"satellites\", \"planes\"]).round(1)" + ] + }, + { + "cell_type": "markdown", + "id": "14ec3893", + "metadata": {}, + "source": [ + "The phases of three of these designs over their missions, from the start of development, for the points of the first replicate (`mission_of(design).phases()` gives the metrics of each phase of a design's planned deployment, as the study evaluates them):" + ] + }, + { + "cell_type": "code", + "execution_count": 2, + "id": "c7af361b", + "metadata": { + "execution": { + "iopub.execute_input": "2026-11-15T04:33:58.256178Z", + "iopub.status.busy": "2026-11-15T04:33:58.255956Z", + "iopub.status.idle": "2026-11-15T04:33:58.764620Z", + "shell.execute_reply": "2026-11-15T04:33:58.763942Z" + } + }, + "outputs": [ + { + "data": { + "image/png": "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", + "text/plain": [ + "
" + ] + }, + "metadata": {}, + "output_type": "display_data" + } + ], + "source": [ + "import matplotlib.pyplot as plt\n", + "\n", + "from trade_space_example import SCHEDULE, cost_space, planes_name\n", + "from tatc.tradespace import COLORS, GRAY, style_axes, use_style\n", + "\n", + "use_style() # the style of the plots of trade studies\n", + "\n", + "fig, ax = plt.subplots(figsize=(8, 4))\n", + "for color, (satellites, planes) in zip(COLORS, [(4, 1), (4, 2), (6, 2)]):\n", + " key = leaders[(leaders.satellites == satellites) & (leaders.planes == planes)].index[0]\n", + " (design,) = cost_space.designs_of(summary, keys=[key])\n", + " phases = cost_study.mission_of(design).phases() # the metrics of each phase of the planned deployment\n", + " edges = [*phases.start, phases.end.iloc[-1]]\n", + " ax.stairs(\n", + " phases.sufficient,\n", + " edges,\n", + " color=color,\n", + " lw=2,\n", + " baseline=None,\n", + " label=f\"{satellites} satellites, {planes_name(planes)}\",\n", + " )\n", + "ax.axvline(SCHEDULE.development_years, color=GRAY, lw=1, ls=\"--\")\n", + "ax.annotate(\n", + " \"end of development\",\n", + " (SCHEDULE.development_years, 2),\n", + " xytext=(-4, 0),\n", + " textcoords=\"offset points\",\n", + " ha=\"right\",\n", + " fontsize=8,\n", + " color=GRAY,\n", + ")\n", + "ax.set(\n", + " xlabel=\"Years from the start of development\",\n", + " ylabel=\"Points sufficiently sampled (%)\",\n", + " xlim=(0, None),\n", + " ylim=(0, 105),\n", + ")\n", + "ax.legend(loc=\"center right\")\n", + "plt.show()" + ] + }, + { + "cell_type": "markdown", + "id": "2e115925", + "metadata": {}, + "source": [ + "Deployment costs the designs of several planes or launches. Six satellites in two planes sample 98% of the points once deployed, but 87% on average over the mission: the first plane flies alone for three quarters of a year while the second is produced, and half of the points are sampled sufficiently only 4.5 years after development starts. Four satellites lose about 5 points of their 68 or 70%, in one plane (which takes two launches of up to three satellites) or in two, and two satellites in two planes lose 3 points of their 30%. The designs launched at once lose nothing, and the designs of fewer than four satellites never sample half of the points (an infinite `sufficient time`). A shorter mission, slower production, or rarer launches would weigh deployment more, and could reorder the front." + ] + }, + { + "cell_type": "markdown", + "id": "55853e86", + "metadata": {}, + "source": [ + "## Stage the Deployment\n", + "\n", + "A deployment need not commit to every plane at once. A `Stage` is a set of planes that is produced and launched only if a rule decides to, at given times of the mission. The rule decides from what is known then (a `Decision`) and from the values of the design. A stage that is not deployed is not produced, launched, or paid for. Staging saves the cost of a stage where the mission does not need it, and loses what the stage would have achieved while it waits, where the mission does.\n", + "\n", + "Here, the robust design of four satellites of `CompareScenarios` (two sun-synchronous planes of two) stages its second plane in one of five ways, a new decision of the design (`staging`):\n", + "\n", + "| staging | the second plane is deployed |\n", + "|---|---|\n", + "| at once | with the first |\n", + "| first plane | never |\n", + "| decided at launch | if the field decorrelates within 6 hours, decided at the first launch |\n", + "| decided a year later | if the field decorrelates within 6 hours, decided a year after the first launch |\n", + "| measured at launch | if the first plane samples fewer than half of the points accurately, measured at its launch (`Decision.capability`) |\n", + "\n", + "The rules that read the field read the scenario, which a mission would not know; the last rule reads only what the first plane achieves. The `stages` of the plan are a function of the design. Each staging is evaluated in each field of `CompareScenarios`, for the share of points accurately sampled on average over the mission, and the present value of the cost (`cost present`, discounted at 3% a year):" + ] + }, + { + "cell_type": "code", + "execution_count": 3, + "id": "eec3e4ab", + "metadata": { + "execution": { + "iopub.execute_input": "2026-11-15T04:33:58.765902Z", + "iopub.status.busy": "2026-11-15T04:33:58.765713Z", + "iopub.status.idle": "2026-11-15T04:33:58.822545Z", + "shell.execute_reply": "2026-11-15T04:33:58.822090Z" + } + }, + "outputs": [ + { + "data": { + "text/html": [ + "
\n", + "\n", + "\n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + "
accurate missioncost present
scenario1 hour3 hours12 hours1 hour3 hours12 hours
staging
at once62.677.790.8156.4156.4156.4
first plane5.08.471.4118.8118.8118.8
decided at launch62.677.771.4156.4156.4118.8
decided a year later49.862.371.4154.5154.5118.8
measured at launch62.677.771.4156.4156.4118.8
\n", + "
" + ], + "text/plain": [ + " accurate mission cost present \\\n", + "scenario 1 hour 3 hours 12 hours 1 hour 3 hours \n", + "staging \n", + "at once 62.6 77.7 90.8 156.4 156.4 \n", + "first plane 5.0 8.4 71.4 118.8 118.8 \n", + "decided at launch 62.6 77.7 71.4 156.4 156.4 \n", + "decided a year later 49.8 62.3 71.4 154.5 154.5 \n", + "measured at launch 62.6 77.7 71.4 156.4 156.4 \n", + "\n", + " \n", + "scenario 12 hours \n", + "staging \n", + "at once 156.4 \n", + "first plane 118.8 \n", + "decided at launch 118.8 \n", + "decided a year later 118.8 \n", + "measured at launch 118.8 " + ] + }, + "execution_count": 3, + "metadata": {}, + "output_type": "execute_result" + } + ], + "source": [ + "import dataclasses\n", + "from datetime import timedelta\n", + "\n", + "from trade_space_example import DECORRELATION_TIME, FIELDS, PLAN, cost_space, sample_field\n", + "from tatc.tradespace import Categorical, Fixed, Stage\n", + "\n", + "STAGING = [\"at once\", \"first plane\", \"decided at launch\", \"decided a year later\", \"measured at launch\"]\n", + "staging_space = cost_space.extend(decorrelation_time=Fixed(DECORRELATION_TIME), staging=Categorical(STAGING))\n", + "\n", + "\n", + "def stages(d):\n", + " \"\"\"The stages of a design's deployment: its second plane, by its staging.\"\"\"\n", + " if d.staging == \"at once\":\n", + " return []\n", + " if d.staging == \"first plane\":\n", + " return [Stage(1, 0.0, lambda decision: False)]\n", + " if d.staging == \"measured at launch\":\n", + " return [Stage(1, 0.0, lambda decision: decision.capability[\"accurate\"] < 50)]\n", + " when = 0.0 if d.staging == \"decided at launch\" else 1.0 # years after the first launch\n", + " return [Stage(1, when, lambda decision: d.decorrelation_time < timedelta(hours=6))]\n", + "\n", + "\n", + "staged_study = phased_study.replace(\n", + " space=staging_space, metrics=sample_field, plan=dataclasses.replace(PLAN, stages=stages), scenarios=FIELDS\n", + ")\n", + "(four,) = cost_space.designs_of(summary[summary.description == \"800 km, 60 deg FOR, SSO: 2 at 09:00, 2 at 15:00\"])\n", + "staged = staged_study.run([staging_space.design(four, staging=option) for option in STAGING])\n", + "staged.groupby([\"staging\", \"scenario\"], sort=False)[[\"accurate mission\", \"cost present\"]].mean().unstack(\n", + " \"scenario\"\n", + ").round(1)" + ] + }, + { + "cell_type": "markdown", + "id": "36fe7a03", + "metadata": {}, + "source": [ + "Each staging in each field, by what it samples over the mission and what it costs:" + ] + }, + { + "cell_type": "code", + "execution_count": 4, + "id": "37d6f8ba", + "metadata": { + "execution": { + "iopub.execute_input": "2026-11-15T04:33:58.823820Z", + "iopub.status.busy": "2026-11-15T04:33:58.823645Z", + "iopub.status.idle": "2026-11-15T04:33:58.946765Z", + "shell.execute_reply": "2026-11-15T04:33:58.946118Z" + } + }, + "outputs": [ + { + "data": { + "image/png": "iVBORw0KGgoAAAANSUhEUgAABFcAAAFfCAYAAACLNSM3AAAAOnRFWHRTb2Z0d2FyZQBNYXRwbG90bGliIHZlcnNpb24zLjExLjIsIGh0dHBzOi8vbWF0cGxvdGxpYi5vcmcvgI3uAAAAAAlwSFlzAAAPYQAAD2EBqD+naQAAb3VJREFUeJzt3Qd4FFXbxvEndKV3qQKKiKKADaTYEFGx94aIir0gKjZE8RXhFX1VRGwgAoIFe0HpigWwgAVBQAWpUoVQpITMd93Hb9bNZrPZZJNsyf93XSHszGT2zOzszJlnznlOmud5ngEAAAAAACBfSuTvzwAAAAAAAEBwBQAAAAAAIEa0XAEAAAAAAIgBwRUAAAAAAIAYEFwBAAAAAACIAcEVAAAAAACAGBBcAQAAAAAAiAHBFSQEz/MsPT3d/QYAAPHB9RgAgPwhuIKEsGXLFqtcubJt3rw53kVJeZmZmbZ69Qr3G+zrVMFxzb5ORfE4T/vXY/2Ol1T+PqfytqX69rFtyYnPLTllJum5hOAKAAAAAABADAiuAAAAAAAAxIDgCgAAAAAAQAwIrgAAAAAAAMSA4AoAAAAAAEAMCK4AAAAAAADEgOAKAAAAAABADErF8scAACSb3Xu8wP9Ll0yLa1kAAACQGvU8gisAgGIhY49nutxOnpduS9fvskY1yljnFpVMl91SBFkAAACSVkYC1PMIrgAAisUFd+HqHXbDqOW2fuuewPQaFdbYsO4NrFmdcgRYAAAAklBGgtTzyLkCAEh5epIResEVvdb0fxuQAgAAIJl4CVLPI7gCAEj5vrdqIhp6wfVpuuYH99EFAABA4tudQPU8gisAgJSnvrexzAcAAEBiWpog9TyCKwCAlKekZrHMBwAAQGJqlCD1PIIrAICUpmH4lC2+RoWSYedruuYzLDMAAEByKZ1A9TyCKwCAlKfLqbLFh1549VrTi2aAPgAAAKRqPY+hmAEAKU/D72kYvil3N3VJzdT3Vk1E9SRDF9yiGJ4PAAAAqVvPI7gCACgW/AurLrQ+ugIBAAAkv1IJUM8juAIAKFYIqAAAAKSm0nFsjUzOlSQ1adIkmzVrVryLAQBIAd6eDPMydrvfAAAAycqLY52GlitJasiQIbb//vtb27Zt410UAECSchUPz7Odc6dZ5tplVqJWQyt7WCc3L60kVQQAAJAcvASo01BzSkBffvmlLViwwP2/evXqdvjhh1vDhg0D82fMmGHLly+3nTt32vDhw920888/3ypXrpxtXdu3b7fp06fbxo0b7dBDD7WWLVtmmf/xxx9bjRo1rFGjRjZ79mzbs2ePHXvssValSpUsy2m6yqX3PeSQQ9y6Qud//vnntmLFCmvSpIkL+pQoQcMoAEjkSkjGisWWPuw289I3BKZve/MJq3TDE1aqflMCLAAAIOF5CVKnIbiSgJYsWRLo8rNmzRrr1q2bDR482K6//no37bfffrO//vrLBTT85U477bRswZX58+db586dXfBErVxuvvlmO/vss23kyJGBZR5//HFLT0936zvssMNs0aJFtnbtWvv666+tXr16bplly5a59W/evNnatGnjynL88cfbE0884eYroHLqqadaWlqaHXzwwTZ37lyrWrWqC9yEC/gAABKA52WrhLjJ6Rvc9GqPfBi3ogEAACRbnYbgSgK67LLL3I9v2rRpLrhx0UUXuaBFjx497K233nIBkyeffDLH9SgYc9RRR7ll1Yrk559/ttatW9sZZ5zhgiw+BUd++ukn10omMzPTLTNs2DAbMGCAm3/55Ze7AI1atuy1115u2pQpUwJ/f8UVV1jHjh3tmWeeca8zMjLspJNOsoceesgFb8JRqxv9+BTgAQAU3RMeNZsNrYQE5qdvsJ1zprrmtHQPSm1cjwEAycxLoDoNwZUEtXLlSvvuu+9s/fr1LuCxa9cu1xKlffv2Uf39unXrXPehzz77LNA9R61K1MJEwZbg4IqCLQqsiJZV65Rff/01UA6tQ8EUP7AiJ554ovu9evVqmzp1qivXyy+/bJ7nuZ+aNWu698/JwIEDrX///vncOwCAmHie648ciZvveezoFMf1GACQ1LzEqdMQXElAjz32mD344IN29NFHW926da106dKuy40CLdFSbhTZd999s0xXbpU5c+ZkmRaaX6VMmTKBViVq1SL77bdfxPdRdyIFYnwVK1a0Tp3+SSAUzj333GO9e/fO0nKlQYMGUW8fACAGaWku0Vskbn5a/IYzRNHgegwASGppiVOnIbiSYP7++2+7++677b333rOuXbsGktK+9NJLrkVItGrVquV+KyATHGDR69q1a0e9nmrVqrnfysOiwEwoPzBzww03uK5B0Spbtqz7AQAUPTWLVfNYJXoL14w2rVJ1ugQVE1yPAQDJ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a03/t6EmAAAAUDT1z7333jvpdjXBFQAoxn1c1RQz9MLm03TND+4LCwAAABR2/bN0WYIrAIAkoj6uscwHAAAACrr+WYJuQQCAZKLkYbHMBwAAAAq6/pnpZVqyoVsQABRTGu5OWdlrVCgZdr6ma36yD4sHAACA5Kp/7t653ZINwRUAKMYUNlFW9tALnF5rOmEVAAAAFHX9c/v25AuuMBQzABRjpUqmueHuptzd1CUPUx9XNcXUE4O0/58PAAAAFFX9s0SaZ14SdgsiuAIAxZwfQNEFzUdXIAAAAMSj/pmZmZwjVcbcLejVV1+18ePHW0F6+eWX7d133y2S9y2M8ieaaPYnAOiC5v8AAAAAha10CtU/Yw6ufPTRRzZx4kQrSAoETJkypUjetzDKn2ii2Z+hXnrpJXv//fcLrUwAEA/engzzMna73wAAAIgvL4XqZgnZLahHjx5WoUKFeBejWHv77bdt//33tzPOOCPeRQGAmLkLtufZzrnTLHPtMitRq6GVPayTm5dWMiEvhQAAAMWybmZpyTnuTp5rlPPmzXM33hUrVrQTTzwx7DIbN260N954w1asWGFNmjSx888/3y0f7K+//nLdcZYvX26HHHKInXfeeVaiRInAPM/zCuV9o1lPsLfeestmzpzp/l+9enVr27atHX/88TkuP23aNPvmm2/srrvuytZ6ZOXKlXbjjTdGVdZo3veFF16w+vXru/lqfVOrVi277rrrYt6m119/3RYsWGCrV6+2O+64w03T9tSsWTPXcue3TABQmBfvjBWLLX3YbealbwhM3/bmE1bphiesVP2mBFgAAAASqW6WlnwBljyVeNKkSXbYYYfZwoULbe3atXbmmWfajBkzsizz/fffW/PmzV2QoUyZMvbOO+/YQQcd5G7GfXPmzLEDDjjAxo4da2lpae5m/8ILL8yxG0tBvW806wlVuXJl22effdyPAgsXXXSR9enTJ8fla9eubXfffbctWrQoME2Bottvv93S09OjLms076sgx0033WTXXnutZWZmWtWqVSNuS7Tr1vyyZcta+fLlA8uVLFkyqnLnt0wAUGg8L9vF201O3+CmAwAAILHqZnvvvXfSfSRpXmgTkRxosRYtWtgpp5xijz32mJv266+/upvt7t272/Dhw920Vq1a2QUXXGD33ntv4G/1Wq0bRowY4V5rPWqtMm7cOBdc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K+y8v/76y95///18laV79+6BsoTTs2dPV1797Ny5M8f1qAzvvvtuvsoAAAAAAMVdqXgXAChoGXs8Uzhl8rx0W7p+lzWqUcY6t6hkaTrgS+rf2MyZM8c+/PBDK1eunK1evdoOPfRQi5e5c+fahAkTXFnCOeaYY2zHjh12zTXX2NChQ61s2bJFXkYAAAAASHUEV5BygZWFq3fYDaOW2/qtewLTa1RYY8O6N7BmdcrFFGC5+eabbfPmzXbttddaWto/6znkkEOsc+fOgRYgL7zwgi1btswFXa688korXbp0tvUsXrzYhg8fbhUqVLAOHTrk2vVnxIgRtmnTJuvSpYudcsopgbKoRYzK0r59exdACdWtW7dAcCUas2bNsvHjx1utWrXslltusb322itiGbQdapFz9913u9fa7pEjR9oDDzzguho9++yzduqpp7plLrjgAmvTpk1U5QAAAACAZEK3IKQUtVgJDayIXmt6rB2EFMQoUaKEHXvssXbccce5IMTkyZPdPAU6NH3btm3WsmVLmzRpkguuhFq3bp3rxpORkeGCFzfddFOO76dljzjiCNu4caPtu+++rpvPiy++mK0szZs3j3HL/gmMDBo0yPbbbz+bOHGiy+WSWxnWrFljn3zySWAdWuaDDz4IBJqeeuopt85mzZq5fQUAAAAAqYiWK0gZyq2irkChgRWfpmu+ugiVzmfrlYsuusjlL7n88sutVKlSNmXKFPvxxx/dvLFjx9ru3btdkEI/e++9t7399ts2evToLOsYN26ca83h52qpV6+e/fe//w37fq+++qoL4gwZMsS9VhBFiXEV4AgtS6zKlCnjWq2opU3Hjh3tsssuy7UMuSlZsqRbJ92RAAAAAKQygitIKcqxEsv8WEcRatKkiQtE+Dp16pRtObX22H///QOvg/8f6s8//8wyXy1ANK0w7LPPPoEuTBUrVnQtcHIrg981yud5WdsGKXBEYAUAAABAqqNbEFKKktfGMj8Wyr2iAMvFF18cGKFHP6EBCAUnPvvss0Ag4tNPP81xnQceeKDNmDHDMjMz3eupU6e6aUUpUhmqVq3qttnfltmzZ2f529BtBwAAAIBURMsVpAx19VGXHyWvDdc1qEaFkjF1CcqNEra++eabLvBw9NFHu242yl9y//33Z1lOwZenn37ajjrqKKtdu7Zt2LAhx3Vq2eeff94OP/xwa9iwoX3xxRd5GjK5X79+tmTJEvf/6667zrWsefDBB/O0XZHKoG2tVKmSy/9So0YNl/AWAAAAAIobgitIKQqbaFSg7KMFlXTTCyKsomSuyiUiBx98sN1+++3u/0ouq+CKhkf+5ZdfbOfOnVazZk03T0GURx991P1fQRcFKKZNm+ZGC9I6vvzyy7DvpW46auXy+eefu8CFRiLSusKVJRwlolVAxe+eVK1atbDL1a9f3wYMGBB4rUCJX95IZdA2a7pyz+hvFGyZOXNm2HUCAAAAQKpK80KTJABxoJF2Kleu7EaYqVKlSszDMeugVvJa5VhRVyC1WFFgJZZhmFOFuvesWbPKateu64IjYF+nAo5r9nWqHtdFfZ72r8ebN292LRPjIZW/z6m8bam+fWxbcuJzS06ZSXouoeUKUo4fQFFAxVdYXYEAAAAAACC4gpRFQAUAAAAAUBSSp40NAAAAAABAAiK4AgAAAAAAEAO6BQEAipXde/7N4073QQAAgNSxO471PIIrAIBigZHEAAAAUlMi1PMIrgB5tHv3bpswYYJt27bNLrnkkqiHtpw4caKdf/752eZp+OlPP/3Uzj777CIpSzgqw/Tp0+2cc87J9zqARL/gLly9w24YtdzWb90TmF6jwhob1r2BNatTjqHaAQAAklBGgtTzyLkC5NG1115rjz/+uH333Xe2atUqFzTJzdq1a+2ee+4JO2/lypXWv3//fH0OV199daAs4XieZ5999pm98cYbtnTp0hzXozL069cvX2UAkoGeZIRecEWvNf3fBqQAAABIJl6C1PNouYKU5e3JUHTBLC3N0koW3KH+0Ucf2aJFi6xy5cq2YMEC99OlSxeLh48//tgWL17syhJq+/btduqpp1qpUqWsatWqds0119jTTz9tl156aVzKCsSz762aiIZecH2arvlqOkoOFgAAgOSxO4HqeQRXkLJBlZ1zp1nm2mVWolZDK3tYJzcv1iDLK6+8Yhs3brTXX3/dSpT4p+FX8+bNsyzz5Zdf2rJly+yQQw6xFi1ahF3P33//bVOmTLEKFSpYtWrVIr5nRkaG6za0adMma9eundWtWzdQFnXnUVkOOOAAO+6447L83Z49e+yJJ56w1q1bu9fPPvusvfrqqxGDK9o2tXSpVauWtW/fPtcyrFmzxr799lvr2rVr4O8///xzO/PMMwNdjY499libMWOGtWzZ0po0aWK//vqrff311y7407BhQzvppJMibj9QENT3Npb5AAAASExLE6SeR3AFKRdYyVix2NKH3WZe+obA9G1vPmGVbnjCStVvGlOARd1v1NVm9uzZlpaW5roFZWZmupYr+n3GGWe4oEH9+vXt/vvvd12I7rzzzizr2LlzpwtQlC1b1vbZZx+3jpzs2rXLjjnmGBfc2HfffV3rk3feeccFLILLUrJkyWzBlYoVK7rAyqhRowIBobvuuivH91q/fr2ddtpp1qhRIxcg6d27t912220Ry6BWM4MHDw4EVxRU+s9//uOCK+pqdMMNN7i/adasmdsnmn/BBRdY586dba+99nJBJoIrKApKahbLfAAAACSmRglSzyO4gtTiedkCK25y+gY3vdojH8a0erUEUQuQ559/3nW3UeuTxx57zM0bP368y62i4IOopcYjjzySLbii1iM1a9a0SZMmudfKmTJmzJiw76dlFYSZOXOmC+aMGDHC+vbt64IfoWXJyTfffOMCHUqqG6mVzJYtW+z999+3GjVq2BdffBEIrkQqQ27U0uX77793QSQZMGCAS7z75JNP5vq3QEFRE1A1BVVSs3BNRmtUKEmXIAAAgCRUOoHqeSS0RUq1WlFXoNDASmB++gbbOWfqP92GCsFPP/3kWnfMmjXL/SgXi0YAUouWYMrXopYgvuD/h1q4cKF17NjRBTXkhBNOcNPyYujQoa6liVqUXH/99TkupxYrCqyIWpmoW0+sZWjcuHEgsCKXXXaZa2mj4NJ5553nAj9AUdDRq2zxusAG02tNL5oB+gAAAJCq9TxariB1eJ7LsRKJm68kt4WgXr16LlfJ8OHDIy6nYIPylAQHW3JSp06dLC1EfvnlFzctGmpFU716dddlSBQ42bFjR47L+8ETn7oc5VaG8uXLuxYxvtARifz39qmLkFrAKFfLhx9+6BLurlu3LqrtAWKh4fc0DN+Uu5u6pGbqe6smonqSoSO/KIbnAwAAQOrW8wiuxMhvleAnN03290nqsqWlueS1kbj5IUGEgqJWGeric/7559vxxx9vZcqUccEW5WEJpm4xDz/8sPXq1csFWtQlqHTp0mHXefHFF7uuNDfeeKNrWfLUU0/ZQw89FFV5FLS599577fTTT3d5Xl544QWXAyWvIpXhwAMPdF2O1PVJrVHUhSg0oBJMgZWff/7ZBW7UXchPjAsUBf/Cqgutj9GBAAAAkl+pBKjnJd6depK5/PLLAzk2YglOhHYdCXXOOefYLbfcYolICUl1Ex9vSlSrUYHSKlUPP79S9X/mxzhiUI8ePQKBJLVWOfnkkwMJZBUwUDcfBRDUNUi/RUMlK5Gr34JEQYa9997bfe7jxo1zn284WlaJaxWE+fPPP+2ll16yK6+8MmxZQnXo0MENvaxkttu2bbORI0fa3XffHXZZ5WI599xzA6+1LcHlzakMSko7bdo0938FTEaPHm1nnXVW2HXKkiVL3H7R+tT1yM87AxQlXWj9H/xD3SW9jN2F1m0SAACgKJSyPVbKy3C/i1qa57f9R75bK5QrVy7XriCRaISW/fffP2KST92w6mZU+TMSzYknnmhHHHGEDRo0KN/rUNcSBSCU56NKlSoFPlqQAisFMVpQKlBAZ82aVVa7dt34tzZKcexr9nUqDl3PcV10tK+L+jztX483b95slSr9+/SvKKXyMZbK25bq28e2JSc+t+LzuXn5qNMUtDy/i2Ix2thITf/zS+ves+efCJPWH5oDIjcql9YRXLbQ8oa+LuyKS3CrlHAjuvhl1o+Soea0XF7XK9qX2rbg/RjahSdhuvQUEH1xFECpNuCDuH6xAKC4D10PAABQnOo0eb6jfuaZZ1yehbvuusuNBKK8Eho95I8//rA+ffq4vAtKcnnRRRe5rgjB1H2gTZs27m/UxeDaa691T0Z8kydPdq1A9KPuBi1atLA333wzyzr0Pl27dnVPU5SsU/kr1FVBlAfi2GOPzbL866+/brVr185S/ubNm7uRUzRdQ8yqDApuPProoy6nhPJfHHDAAfbcc89lWdfff//tumGoO4fKr64RGr42kptvvjmwTWqR0aVLlywjrfTs2dM+/vhj133DXy6akVhyW68cfvjhLgdIMO2v4G5M6tKjMiivhrp/VK1a1eXl8AM9on0zePBga9KkifvsDjvsMPv000+zrFdJSSOtoyjpi5NWqrQLqOzV5YpAVyBuEgAg+qHrAQAAkoKXGHWafDVX+PXXX133jTlz5thvv/3mElq2bNnSBR8WL15s8+bNc3kVhgwZEvibr7/+2nVt6d27twtmaAhW5V/QjX3wjb5uyPWzadMm69evn3Xr1s1+/PHHwDJKqqnghv5WI5NonW+//Xaeyq8yasQTDZ27e/du1/z1wQcfdIlFtS4/P8UDDzzg8mH4lK/iyy+/dEPJKpChIML7778f8b0UzPG3SftK3X9UZj/wMGLECDdiivKp+Ms1a9Ys123Ibb15MWrUKBewWr58uU2dOtVt88svvxyYf99997ngigJA+lxU5rfeeitP6wilBKtqehz8U1hBFoIqAJBYQ9cjcRTF9RgAgOJQp8lXcEXBDd1oK7jQoEEDl/hSXU+eeOIJ14pCLVrOPvts++qrrwJ/o3wc3bt3twsvvNC1tlAiULUUGT9+fNjWH2pRoiSfnTp1snfffTcwfdmyZda+fXvXasVPupnXEVDU+uLZZ591I7mIgkKPPfaYy3miVhlquXL00Ue79Sp5p7/M888/70ZNOeSQQ1xA5r///a/LgxIt7Rtts4I78+fPz1OZC3O9Csood4xaC2n7lQNGQSTZvn27+1y13Qqe6LNv3bq1+/yjXUc4AwcOdPvQ/9FxBAAoHkPXI3FwPQYAJDUvceo0+QquKKCg4IdPN8cNGzbMkvvDT07q0+ggw4YNc8soeKEAh5KgKveJuvqIWozcdNNNbv1aRkGYCRMmuIBKcMuVe+65xwVpXnzxRVuxYkW+yh+cpE2tWBREUNea4PKp65BaYsjvv//unu6ozD4tq0BDJGodo5YpGjlF69V+US6U4G3Kj4Jc73777ZctWON/dto3O3bssI4dO+Z7HeHoM1QLJv/H388AgNQfuh6Jg+sxACCppSVOnSZfwZVwiWZzSz6rvB3KieJ3ZQn+UW4VUR4XDVGrgIoCLZqnFjDBXV2Up0WtM3Sz/9FHH1nTpk1dK5SchBviWMGI0LLJDz/8kK1soXlMQgdXijTYkuaptYdylfhdkHbt2uXeP5Z8JLGsN9z+iCZxcG6DSuU1+bCCcwpwBf8AAFJr6HokPq7HAIBklpZAdZoiGyJGXUWUuDUS5WlRUtRDDz3UXewVKFCLl1DqdqQWLuoudP/99weStqqb0saNG7Msu2jRolzLpgS96s4SqXwKZKgljXLF+BTUUN6ZnCgXjVpk9OrVy3WDUisdLa+/C6agiD9KUjSiXW9+90e4fTNjxow8/V2qUxLlaBIP+xT8UretcNQiSnlz8mvNmjV5KkteqXzKswQg9SiDfmhlxB+6HgAAIFlUSoA6TZEFV/r27esCE7feeqvrBqTRZT788EPXMsV30EEHuUSp6tqyatUqu/766wNdhnzK5aGWLRs2bHBdgpTXRa1X5JhjjnHdWF577TWXkE3BkuCkujlRHhE1i1XLGiW1VUBCN7vKK6JpogCDyqPltB1r16612267zZUzJxqNSN121H1JXV/mzp1rV111VbblNEKR5ilZbDQtWqJdr0ZOGjt2rEswrP2lbVHrnLzQvrnjjjvc5/fOO++4rj4KggWPOFTcKL+NWlupFZVaWIUeo+HomD7llFPCzlPQ5dxzz81XWZTL6OCDD3ZlCUetvPT56ydcqyV9nv5oWzlR+ZRTB0BqCR66vsKVD9vep13jfld75EOGYQYAAEkjLUHqNHkOrpQoUSJLbpVopylXyWeffeaCHxpZSElhhw8f7m7ag29aNZSz5rVq1cq15tBNnVpm+NRSRblbNFTykUce6XKN+Elnlf9k6NChLgCilib6/+23356lHOHK6q9XSW31o+SqJ598ssuzEpws95FHHrHOnTu7UY20PSqfboqDyxfaIkVDSX/yySdWt25dO//88+3qq692ZVY5fAo4qUz77rtvjkMx6z3894l2vXfeeacbJvv44493wzLrRlrBrODyBq83p2n9+/e3e++9142WpNw6CrZoSOq8rCMedmfuCfwUJI3U9P3337vhqNUtS8kA40XfBb8s4Wi0LeUn0ndKeYV8CrYpGbQCk5p31FFH5RpkAZB6GLoeAACkgrT/HylWXYD26nJFoCtQUXZxTvNyS6YBFAG1NPKTICsZbiwyMjMt0zybsHKeLdm2wRqXr25d67WwNEuzUkHBp/xQcFCBPw3H7QePNGqVAmM+JQBevXp1IDGzqFuNAnbB3WvUekstojSkuEZaUpAkJ/7wmMGjUwWXRaNn5TRylcqj99GoXBUqVHAtWD788H3buXO3nXfeeS5IqECL/j5cSy+1ernooovcb22Xtlfrya18Cuaoy5K68fnlUJc2JT9WVyN1bdMQ4lqnWkjp81fLLbXy0d8qD4+CeclM+3rNmlVWu3bdLIFPsK+TGcd10e7roj53+NdjtYyNVz60VD7GUnnbUn372LbkxOeWnDKT9FySPCUFogyszN+82tpMfNRu+u4Ne/yXqe73URMfddM1PxY9e/Z0+VMuvfRSF3A4/fTTs3TJUdcrtXzSyFP6rS5s4VxxxRUuyKCcNmqxFYlGyFJunTZt2rguQH5+luCyqDVNXhx55BGu1ZUSEavVlFqThebsCeaPpqVh0NVaSsmkcyuf8gAFt3BSMEitaPyuRmoFduKJJ7rua0pkrfnqIqfp2rca6hwojgqr1R0QLxzTAIDigOAKUoparHSfNdrW7dyaZbpea7pnsTXU+vzzz90w3WplopYcynvjmz59ugs6TJo0yd5++22Xsye4W5nvgw8+cImalTNIrTfUaiMnyks0ZcoU15pDrT40/La6ZYWWJZauSSrHyJEj7brrrstxGZVzwIABrqucuuENHjw41/LlRn/z8MMPuyTLatWjfEuXX365C85o3+Y1YAQkOwV/d2XusY9WzrOhiz5zv3VTGmtQGIgXjmkAQHHCGItIGboJUVeg0MCKT9N1s6IuQqVLFHw+GOUUUhcf5TnxqQtNaCLZr7/+2rUa8ZtbqxWLkgSHo2WVJ0cjP4kSCaulR0HxAyLqDqTWKzlRKxvlGRLl7/ETOcdSPnUXatu2beC1WrGcccYZLumy8gSp1Yu6OwHFqdVdaHC4/7wJNqrt5XZQ5Toxd2sEihLHNACguKGmhpSiHCuxzI9F+fLlXQsMf3Qe/SjhbWg/QS2nkaF8yjMTaZ2hy4bmO8kvBYIU0FCLFAU1IglOAq2uRH7AKFL51KpG3ZZ8wcuJkjcHU7ci5aRRgEatWTp27BjjFgLJo7Bb3QFFjWMaAFDc0HIFKUXJa2OZHwuN2qQRpR5//HHX8kLBBXX50chVwTQCVrt27VyrjX322ceNVJUTLavllOtE+Ujuuusul4Q2Wupio6SEsmDBAjeEt1qMqCvQuede4Lot6bUCQaGJeaMRqXwaiUhDQau7j0YBi7SdosS2GsVI+6tDhw72/vvv56ksQLKKd6s7oKBxTAMAiiOCK0gZuunQzYea0Ye7SalZtkKB3Jwoaatab4haaSioIPo9Y8YMGzRokI0bN86NiKOuNmPHjrWyZcu64cNFSWxHjx5t//vf/9zf9+nTx954442w79WsWTM37LaWVcsPtYzRkNjhyhKOgh1KFKvl1M1G7633WrDgF9ct6ZVXXnE/ooDGc889l20damGiQIlPQSN/WyKVT12FlJPmySeftBo1alivXr1s/PjxYdcpyvui/eYPS/7uu+9G/ZkAyS6ere6AwsAxDQAobhiKGSk1FHNOfbwVWCFvQXIPbZaM2Nfs62if8qtlikY2y8nQwy9ImJYrHNdFu6+TcSjmWI/pVD7GUnnbUn372LbkxOeWnDKT9FxCyxWkFCV8VOLH2V36uGb2enKmrkCqwKVZGgkhARTbVndAUeGYBgAUR8kTBgLyEGAp8/83KzcdcGzgpoSRNgAkKgV/1bpOgZRgfqs7zQeSCcc0AKC4oeUKUhZPeQEkC1rdIdVwTAMAihuCKwAAJAC/dZ1a2/kIEiOZcUwDAIoTgisAACQQAipINRzTAIDigJwrAAAAAAAAMSC4AgAAAAAAEAOCKwAAAAAAADEguAIAAAAAABADgisAAAAAAAAxYLQgJATP89zv9PR0K/H/w5GicGRmZtqWLVtsr73Y14WNfV102Nfs61Q9rnVNrFixoqWlpRX59TheUvn7nMrblurbx7YlJz635JSZoOeS3K7HBFeQEDZs2OB+77vvvvEuCgAACWXt2rVWs2bNInkvVWalQYMGRfJ+AAAki82bN1ulSpVynE9wBQmhWrVq7veyZcuscuXK8S5OStPTSFWaly9fHvHkAPZ1MuG4Zl+n8nFdpkyZInvPunXruutDUbaWKU7f51TetlTfPrYtOfG5Jaf0BD2X6NoYCcEVJAS/uZcCK4n0BUpl2s/sa/Z1quG4Zl+noqIMcuh6XL9+fUsEqfx9TuVtS/XtY9uSE59bcqqUZOeSxOnABAAAAAAAkIQIrgAAAAAAAMSA4AoSQtmyZe2BBx5wv8G+ThUc1+zrVMRxzb7mGOP7UxzPD2xbcuJzS05lk/Rckub5Y+4BAAAAAAAgz2i5AgAAAAAAEAOCKwAAAAAAADEguAIAAAAAABCDUrH8MVAQ0tPTbdGiRVarVi1r2LAhO7WA7Ny50xYuXGhVqlSxBg0aWFpaWtjltMy2bdusRYsWVqZMGfZ/DJYtW+Z+DjroIKtWrVqWeUpv9csvv7jP5eCDD7bSpUuzr/Npy5YttnjxYmvUqFG2/ezv6/nz51tGRoY7rkuWLMm+zoe///7bfvvtN7c/99tvP9t7772zLZOZmWk///yzW0bHNfs6Ohs3bnTH6AEHHOCufeGsWbPGnU8aN25sNWrUyPcyiWblypW2ZMkSa9mypVWsWDHb/D179rjrkq5H+o6XKhW+qvrHH3/YunXrrFmzZmHXEw9r16519Rl9F6pWrRr2+6JzlzRp0iTbdWDp0qW2YsWKLNPKlStnRxxxhMXbhg0bbMGCBW5/16xZM+wyKvv69evd8Vi5cuWwy/z555+2fPlyt/3Vq1e3RKmH/vTTT67cdevWzbHcq1evtn333TfbdUfzfv3112x/06FDB4u37du329y5c109MFIdW+fwmTNn2l577WWtW7fONv+vv/5y14M6depYvXr1LBGoPjVnzhx3DtU1KpKvv/7a/T7qqKMC0zZv3uw+91CHHXZY2OtdUVL95dtvv3XnEX3ngqnOrs801KGHHmqVKlXKtqzqnlqPvnOJIDMz07777jt3rKmOFmzXrl2BzypYcL06mmXiSgltgXh55plnvL322ss78MADvb333ts788wzve3bt/OBxOCvv/7ybrjhBq9KlSreoYce6tWsWdNr1aqV99NPP2VZbsWKFV7r1q29atWqeY0bN/Zq1KjhTZw4kX2fTxs2bPD23XdfJQj33nnnnSzzfvvtN69FixZuH2uZffbZx/vss8/Y13m0Z88er0+fPu6coWNa+/Luu+/OssyCBQu8Aw44wKtdu7ZXv3599zN79mz2dR49++yzXuXKld25+aCDDvIqVqzoPfXUU1mW+fHHH7399tvPq1OnjlevXj33ecyZM4d9HcGiRYu8K664wu0znStGjhyZbZnMzEx3Di9btqzb9/p911135XmZRDNr1ix3jdd5UNs+c+bMbN/vBx980KtVq5bXvHlzr2HDhu7nk08+ybLctm3bvNNOO83VGfy6w/PPP+/F0w8//OBddNFF7ryjbfvggw+yLTN48GCvbt26XrNmzbwmTZq4ZcePH59lmdtvv91du9u3bx/4Oe+887x4+uWXX7zLL788cMyOGTMm2zK6nh122GFeo0aNXL2jXLly3vXXX+9lZGRk+XyvueaaLMfsvffe68XT0qVLXZl0TS5VqpT3xBNPZFvmm2++cZ+DriW67mjbLr30Um/Hjh1ZzpeaHvy56Sd4+4van3/+6d16663uc1PZ7rvvvojLP/74416JEiW8gw8+ONu8QYMGuXXoe6nfl1xyibdr1y4vnvVcne903Slfvrx37bXXRlx+9OjRbtv0nQs2ffp0d0yHfm6///67Fy9bt2717r//fq9BgwbuunvhhRdmW2bu3Lmu3G3atMlSbl2Tg40dO9atQ3Ui/T7++OO9TZs2efGyc+dO75FHHnH3HKpfdOrUKdsyy5cvd9um80nwts2YMSNPy8QTwRXEjS5YaWlp3ttvv+1er1692l287rzzTj6VGCtCClr5F379Puecc7ymTZtmWe7EE0/0OnbsGFhOF16d7BQkQN7ppkEX+3DBlaOPPto76aSTvN27d7vXqvDoBmLLli3s6jxQIEXBwnnz5gVuMIcNGxaYr9eq2J911lmuIi9XXXWVq6QEV4QRmQKvOjfrhsE3fPhwd2z7lU7tX93YquKn/S6XXXaZu2n0j3Nk995773kjRoxwDxFKliwZNrjy3HPPuYqwf5wrOFimTBnv9ddfz9MyiebFF19013sFQMMFV7RPHnjgAXfjJDqu9J2vUKGCt379+sByvXr1cjfxa9asca9fffVVd7zqhiNexo0b535UppyCK3379g2U2Q+26DMLvpFTcKVLly5eItH1TMepPp+cgiuaps/Vp4c52rbg43vo0KGujuEv99VXX3mlS5f23nrrLS9eJk+e7M5zuhZXr149bHBFAbDgY0ufl7ZDn59P61CgOZHo+6Xt2bhxowvoRQqufPvtty6QqSBaaHBlypQpLjCh37JkyRIXIB0wYIAXLzrvDRw40H2fdFMdKbiigLaCMNddd12OwZVEumZp/yrIvHLlSq9r164Rgyvr1q3LcT2LFy92368XXnjBvdZ5VcdBjx49vHjZuHGjO6drG7t37x4xuBJ8PsnPMvFEcAVxo6duepofTCcUnbT9yjoKxocffuhORH7FbtmyZe61pvs2b97sniSpAoy80RP9Y445xgWmQoMr8+fPd9M+/fTTwLS1a9e6GyvdFCA62rd6YjZkyJAcl/n666/dvlZFMfjJZE43O8j5Kbz22ffffx+Y5t8Qax+LnhDptX9zLwsXLnTTdMOC3OUUXDnqqKNc65ZgaqkRfNMdzTKJSpX+cMGVcPzv79SpUwNBvapVq7on6cH08EBB63jTDUy05xs9odaywQExBVf0dFktwLSf4tnyIZycgivh6Ib24YcfDrzWU+arr746yzInn3yyu4FMBDkFV8JREF9BvuDgip7Gq+XAzz//7J7QJ5JIwZX09HT3/fn444/d8RcaXFErlQ4dOmSZpm1PlGBSpOCKHqqohfYrr7zigjE5BVd0HdN1T63iEkluwRW1BtT/wz2o69evn2u1FHw/pQCn6lGJ0EOgey7BFbVY/O6779y9SX6WiScS2iJu1F/w8MMPzzJNfSHVXze0zzFi880337j+z36ffL+vZvD+Vz9N9esM148TOfv+++/tkUcesTFjxliJEtlPqeH2tfqrq982+zp6X375pe3YscNOP/10l7NB+0795EP3tT6D4P7i2s/qj82+jp76bV966aV200032QcffGAffvihXXfddXbBBRcEcj9of5YtW9bllvApf4jOI+zr/NP96w8//BD22ujv12iWSaVrl/j5FJSTRLkfQrf9yCOPTLpt97dt//33zzJ9xowZdvnll1vHjh2tfv369vbbb1syUG6PL774wiZOnGg9e/Z0OSt69OgRyKOj3BbJeszu3r3bbdvkyZPt9ttvdzmTbrjhhizL6Ng8//zz7dRTT3V1rWeeecaSgc7tJ598svvJS11d+VeU/yyR9enTxw488EB3PYvktNNOs/POO8/lJbn77rtdTpBkoDJffPHFLs/IzTff7I7T4M9NuWOC8y3qc1M9SjlYEt0VV1zhzoP6Luk8otwx+VkmHkhoi7jRxSk0mZn/WvOUfAuxU7KvRx991Pr37x+4+df+Dd7fwfvfn4fc6UR+0UUX2RNPPOESxW3atCnbMtqfSsxYoUIF9nUMVq1a5Y5f7es333zTXUyVOPK2225zwS1/XyuBc2iQi+M676655hq7+uqr7Y477nD7UwnkHnjggUBFLdz5m31dMOcUJWmMdG6OZplUoCShvXr1cpVnBUlzu3b9+OOPliyUSFM3tboR1w2Q79hjj3U370oaqhu8//znP+7mSdfx4EBmIlJyZd2Y6jqoZMP9+vVz2yG6CdeNX7Iesyq/tk2/lbhWn5GS3/qaN2/uElTrRl70sEXHrRKInnLKKZaoRo4c6QK1Spya37p6oiSTDqUHA++9957bvpzowcvnn38eSDys/5900klWu3ZtV7dIVHpYqiCmyipKDnvCCSe4IIvq+v5nE5rkN/hzS1TlypVzdbxzzz3XvVYS7eOPP94FyvyAZTTLxBMtVxA3ypKvCGro6BTCqDUFQyMuqPJ24YUXupuk4H0v4fY/+z56999/v7vIKRCop1qzZs0KnOj9DPTa16pU6skd+zr/tB91s6GWbaq4q8I0adIkFzh86623AsuEHtMc13mnp1onnnii3Xvvve4couP54YcfdhW54OOafV3wojk3F4fztyr/Xbp0cTenzz77bGB6Kmy7gmN6Uq6RMl555ZUs89Qyzw9IKKipAIVuiJKh9YqC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1w26H1hXcDdecvo+6aGA6gfhaPobb7zhzkM+1REUUPFb5igHiz630OO2qKn1p+qKwRTw88uua6/yNanllwKEOiZVzwl9sKEu0v/9739dQENdEBWMVwA7ns4555wsrWlE9TOdQ0XfMQVKVIfTeUXnCZ1LgnMaRbNMPBFcAQAAAAAAiAE5VwAAAAAAAGJAcAUAAAAAACAGBFcAAAAAAABiQHAFAAAAAAAgBgRXAAAAAAAAYkBwBQAAAAAAIAYEVwAAAAAAAGJAcAVIcl9++YUtWbIk3sUoNlJ5fxfUts2aNdN+++1XS2afffaZLVu2zFLtsynK49fzPJs0aaJt37493+uYOnWKbd68uUDLBQCFZeXKlfb111/HtA6d8yZMmGC7d+/O1+tEt3DhQps8eZLNmfNdVMtv27bNbd/OnTujfo947aO1a9fal19+WajvgcRGcAWIow0bNriTvX4+/vhjmz17lm3cuDFP6/jf/x63Tz+dnqe/+eKLz23p0qVWnOV3H+RnfyeLgtq2Z555xqZMmWLJfCwMGvSIzZz5laXaZ1OUx+/7779nY8aMsb333tu9zszMdJXp77771v0/1OTJk10lOti3335rQ4Y8VSTlBVLV/PnzA3UNBTx/+OEH27VrlyWDTZs2uXJnZGQkRRnuvfduW7VqZUzvt3z5cuvT5w77+++/8/U6kQ0d+rT17Hm1ffzxBPvxxx+j+ps1a9a47duyJT3q94nXPqpYsaL17XuvzZs3r1DfB4mrVLwLABRnv/32mzvZH3vscbbXXnvZ6tWr7ZdfFlivXr2tW7duUa2jQ4eO1rhxkzy972OPDbZzzz3PGjVqZMUV+wDJdCzk53temOvJjW5ChgwZYg8++GBg2h139Lbff//dBVaaNTvQBg9+LDDvvffes48++tA6d+6cZT09elxpXbp0dr/r169f6OUGUtE777ztvl/t2rW3PXv22IIF89338Kmnhljz5gdZIvvjjz9cPem4476xUqVKJXQZPv30U9dy5Ywzzozp/SpXrmwnn3yKlS5dulCWj6c33xxvd999t516aldLRarLX3zxJe6hwAsvvBjv4iAOCK4ACeDee++zevXquf+PGDHcHnvsUevU6QSrW7eea1L//fff244df9vBB7ew2rVrZ/nbo446yi0X3J2hcePGLnq+YMECK1u2jB16aMvARVetY7Zs2erm6UmMnHzyyVaiRAnXVFNPXOrXb2BNmzbNsbzffPONrVu3ztLS0qx69ep24IEHWqVKlbItp0qcovcbN26wgw46OFvZI83XU+xDDjnE9tlnn8A0tSSoVauW7bff/lm2VRezefN+cmXRtuZWvkj7QDeFepqyefMma9SosVt/TvT0b8+eDDvssMOzTJ87d655Xma26b6c9nM0+9Xf5vLly9svv/ziPtfDDz/cSpYs6Z7uzJ//c2A/hPs7tSJYuPAXK1OmrB122GHu7yKJZn/oqd7cuXOsWrV/yhyNSMd1TvtVy2dm7glMz61sOR0fwXI6Fnx//fVX2O9RXvZPQXx+od9zifR9zWleuPXkdo7J7ZwSzrRpU91npZs5vzxqKj916nT3ve/cuZMtWrTIDjjgANdab+jQITZy5Khs69H3/cgjj7Lx49+w227rHXHfAsiZzgWPPfa4+//u3busR48e9vDD/7GxY18NXG913VIrF9VHDjyweeAcqHOcvvcKxOhGPphaAvz004+uJYyu49WqVcsyP9Lfq/Xu7Nmz7ZRTTrHff//Nli9f4YLcfqB7+/ZtrpupqIylS5dxZWvZMuv50afz8D/vVdZatmzlfgdbsWKFu/7pXNaqVWsrU6ZMrtuSlzK8+uo4O/30M1xdInj7dE35Z/uWu+C2tk/dJnVdWr9+vdsvwXUdXfdPOKFT1MGknJaPtL257ftI+ySSnN4zPT3dvvjiC3e+1/XALM1at25lderUDbseLbN69aqI19TcPs9IduzYYdOmTXP/L126lAve65hX/St0H+nz+/nnn115dD2qWrVqxP2iY+Dpp4fYH38stX33TdyHNigcBFeABKML5BNP/M8WL/7V1q1bbzfffKPVqFHTqlat4m46b7jhRrvyyquyNPM/7bTTAxcgdWfQhX/FipW23377uQuPTvpjxox1FY05c+a4ysLixYsCzYJPOOEEu/PO212go0WLFvbnn3+6G7whQ4aGvVj98MP37sZQlYM//1ztcjg8+uhg91TcpyfUt956s7uA7b9/U1uy5He74oor7aKLLopqfr9+fa1//4eyVDh0sVIrHz+44m+rcmPopr5duw7upi+38oXbB3pirqdT2t+6aaxXr767cLZt29YGDvxvoLIUTGV+/PHHbNq06a7CJbpx7N27l119dc9swQHN69Xrlhz3czT7VdtcvXoNW7t2jTVteoAroyoFemo1btxYt2++/36uHXfc8TZgwCNZ/q5u3bpunc2aNXM3ydp3L7ww3N3oh6Nlc9sfCghpmYYNG1r58hVcoGznzsjNzXUcRzqudcw+88xQmzbt00DwR/vk9tt72+WXX+72azRly+n4CJbTsSDqEz5y5Miw36No90+o/H5+wd/zSMeR9lekYyz0fJHbZxHNOSUcBWSOOOLIwOe3bNkf7m/95fV/fd8UXBk0aKBddlm3HFumtGnTxj744H2CK0AB0fWqY8eO9sILzweut4cccqgtXbrE3ejrHKgbTZ2TdN1V0FWBF103dF3u3Pkk93e6Xl1zzdUuYKtzgnJt9ex5rZ133nlufm5/77fenTDhI5erolq1qi4Ie8stt9oVV/Sw7dv/dtcYv1WIzicKRocLbIwd+4o9+eQT7pxStmw5++uvja5lTsOG+7r5qlepPLoJ1/VVN8fPPfe8q39E2pbjjjsuqjJofV9/PdsFrXz+9r3xxuu2c+cOd43UMr163Waff/65u+bonPjjjz/Y008PtaOPbpelC8tXX82KqjVKuOVz297c9n00n2+oSO+5desWF3TXtVzXGbXwUZ0kXHBFQb/33nvXWrc+zF2/GzfOHqDIbftyo89D5RF9Dgqe1KlTx55//oVAncjfRx9++IG7ZitQouu2HoRE2i9aT4MGDWzGjBnWrRvBlWLHAxA3s2fP9g4+uLm3YsWKwLTp06e7aT/++KN32mldvQce6BeYN3XqFO+QQw72Fi5cGJh2zjlneS+9NCLw+uSTT/LOOOM0b8uWLe61frdvf7T39ttvBZY588zTvdGjRwVef/fdd17r1i29TZs2BaZ9+eWX3rZtW6PajldfHed16nS8l5mZ6V7v2bPHlf3WW2/xdu3a6abt2rXL++yzT6OaL23bHuVNnPhJlve5+OILveeeezbLtnbp0jlLuaMpX7h9oHlnnXWGN3To04Fp6enp7j1ee+3VsPt7+/bt2co5ffq0/9+Xf2UrR173c7hyqzwqu/83S5cu8Vq0OMg7//xzXXlkwYL57hhasmRJlr/r2LG9t2bNGvda5dO+e/rpIWG3LZr9kZGR4XXteoo3cOAjgWXGjx/v3jv4cwq2e/fuXI9rla1Vq0O9L774PMt35dBDW3hr166N+rOK9vgIPRai+R5FW4ZQ+f38gj+bSMdRbsdY8Hqi+Syi2RfhnHXWmd6zzw7L8vmdeurJWdb59ddfe59/PsO74ILzXVnmzp3rpum4CqbzgvbH33//neP7AcjZww//xzv//POyTLv33nvc+VF0HdO5IfhaNGfOHK9NmyO9X3/9Ncv5QdP869t9993j9elzR2D+zp07A9fxaP7erwM988zQwDLvvvuOd/jhrQN1g++//94tE6k+ovOGzqNTpkwOTPvjjz+8xYsXBebrvKZzjOgcc/PNN3mXXnpJYPlI2xJNGX788Qe3jK5RPn/7gq+H//vf425acL1Nn8/ll18WeP3TTz+5ZTZv3pyv19FsbzT7PtI+CfcZ5Paeouu4zvs5mT17ltey5SHuOigqS/fu3VxZ161bG/V75baPQul9VMcM3h/+Pnr00f9mWTaa/XLLLTdnWQbFBwltgQSgBJPqkjBy5Ev24IP93NMLNU1Uywi1gAhu1aInvkpIF0nXrqdZhQoV3P/1W0+gIiVvLVeunHsaHjzCS7t27WzvvcO3aBA96fjqq69cIl7RE3I1bxU1y1XZb721V6BFh56mHHPMsVHNzws9hQ9tppxb+cJR89zFixfbPvvUcft34sRP3MgqeuqVU+Z/dTc55ZRTXX9239tvv+0+p8qVq+RrP0dTbn2+/t/oSUqVKlXcflB5RJ+33iv0M9ffqZuFqHzKMzJx4sR87w89hdR7KB+G75xzzonYbFhNfXM7rlU2PVX98MMPA8soX8BRR7WxmjVr5umzyun4iEak71F+jpdYP79ojqO8fJej+Syi2RfhbNr0V5YubWr+rVEaBg9+1B599L/u6aWeMA8Y8LD179/fHnqov91//32ulcwtt9ycZV2VKlUOdC8AkD/qlqF6hp7CP/LIANcaLLiF2tlnn5PlPKGWAzo/6Vyi89snn3zsWiVqxJaff57vllELEV2j1B1H1DrOv45H8/e+Cy/8p8WqHHnkka5Fq3LQ5SV5duvWra1TpxMD09Sa0m/FoOSpWm+rVq3ca7U+ufrqq10rQXX1yG1bouGfn8J1kT7//AsC//dbvFxwwYVZphXkIAPRbG80+z4v+yQv7xm57B+7FqB+tzTVES+77PJCeS9R/iG1YJk8eYrVrr2P/fTTT9mWueyyy7K8jma/6Dj4669/5qN4oVsQkAB0M61cGLrJUl4B3chMnz7ddS1Qs8lgamq4alXki0fozaRO/JGGsDvooINcV4Cbb77JKlas5Jrhn3vuudm6UPieeupJe+WVMXbwwQdb1arVAiN/qH+qbn51YVZwSJWbcHKbnxfqzpDX8oWjJqoqU+gIMerLu//+/3RDCkcBiksuucg1E1WAaMaMz+yZZ57N136OttyhlTd9vqHTVJZdu7J+5qG5NtSVJaeKSDT7Q5+j+ngH5+jQMauAQ0507EZzXOs7cP/9fV1TX1Wc1EXnrrvuibpskY6PaEX6HuX3eInl84vmOMrLdznazyK3fRGOzmfBozKogvzyy6PslVdeMXVpV36VZ58dZied1MU1ldfNl7qBlSlT2rp0Ock1G/dvQv7++5+hnHPqvgYgd+npm91NpM6nCrKPGjXGBSR8oddGneP0N5MmTcoyXQGMcuX+6d533XXXuy5FJ5xwvMs70aFDB5fMU+ezaP4+3PnF74qcW/fSYLoWRcptoeuccs4Ea9Dgn/qHznXqmhJpW6LhB6Z03gvtLhm8Dm2fPoPg85mmFeToTdFsbzT7Pi/7JC/vGYm6+ITWVerXr1fg76XcLz17XuWCYuoqreuQuqqG64YVWo+IZr/oOOCaVTwRXAESLKGtTwmzdHO9ZcuWLBe/zZs3u5ufgnbttde5J9hqjaCn1t26XWajR7+SrV+x+va++OILNn78m4FRBpQ/ZepUDb3rudeVKlV0T6b1pEzbESq3+aIb19DhWsPdzAXlHou6fOHoabzK1KfPXYHWHdFQIERP4PWUThUTVVCPPvroPO9ntfbIT7nzQhXdrK/TXUAvv/tDf6uErspZEvzEU+vNSbTHtXKOqAKqIKP2q1o9dO58Yp4/q9Djo6Dk93gpiu9rtN/lwjzH6EZHyQaDqcKs/SXKNaOWPm+++bZ9++03/5+z559jSN8nPcX1y6ubNCVLjvYmB0DkhLbhBCfy9M9xSm4a6W90vXv22efdOV/f45deesk++eQTe+edd6P6+4KiOoXfiiCcKlWquvNaMP+15uW2LdFo1Oif3C467+V0XS0q0WxvNPKyTwrqPdVyNbQOEfq6IN5r9OhRrm4xadKUQCJgtaz08+tE+m5Es19WrlxhbdvmXBdE6qJbEJCgdIOhysmUKbq5/vfpjLrUtG4dfhSaaOmpcnCgQi0jdJOsm1klwezd+3YX+dcNUCh1UdGFJvgpkVoVBFOWfr2HmuqGPimIZr6oNYQSmfk0ik40zWajKV+4faCkaLq5U+K5YLqB1ntHotYr7777jvs588yzckxmGmk/R1vuWLufaXt8U6ZMdgnjwolmf+hpj/bj1Kn/JIUTDSW+YsXymI9rPfnTE051B9LP8cefEAjgxPJZhRN6LESjoMuQF5GOo7x8lwvzHKNm3WqiHY4CZQ888IDdf38/9zmrMq1y+8em9l/wzYlG3zr66LYxlQdA3rRv38FmzZrlRjwJpu+qvsOiFpvBo9XccsstLjm4RiCL5u+jPT/n1pJFo5LNnDkzy7lXgWM/4KKR8f4ZGW5LYL5ay9WoUcMaNmyQ67ZEUwa1blCXSp2v4i2a7Y1GpH1SWO+p9Wh0puD3UF2loN9LdS61dvEDKzomVUcqiP2iVitKBhzpQRtSFy1XgASlk/ZNN91sAwcOcE0g1bJBmdGVpf7EE//tV5wfytyvG1ZF39Vcv3LlSi4Pgproa8QONclXpv3gUWp8GnVFmdA1Io6W1wVE2eaD6YZNrXEefPABFyBRS4yff57nWmA88ED/XOf7Q9kNH/6ia6KppwtvvfVWVFnzoylfuH2gofb69XvA7rvvXtesVCPSbNiw3rUc6d79CtdNJSeap1GD1Fc5py5Bfo6L//53YNj9rGBSNOWOhfoI33DD9W50KFV6NULBa6+9EXZZfUa57Q8do9dcc63Ll6FlFPwYO3aM6xpTEMf16aefbtdee40LVj355FN5KltehDsWclPQZciLSMdRpHlFeY7R91fd3JSXJnSY6JdeGuECP8qhI82bN3eBKuWB0E2MgqzqziRqKj99+rQsnz+AwnfWWWe585lavl1yyaUueLBo0UL74ovP7a233nHXY43Os23bNvd91WsNmd6x4zHuexzN30dD5zGdq4YMecrl2VB31tBWeHqooZwu6qKr7hkK2qolQa9evezww49w+WRUth49utt5513gWhWMGTPajcjm532LtC3RlEHOO+98+/jjj6xbt24WT9FsbzQi7ZPCes+zzz7bdY++6qoedtZZZ7ucPfosC/q9VA/q3fs212pS1/7333/fdRFS96BY94uOe9XnNGwzih9argBxVL16NTcEq5/IMpSGJ9UQqjrhz5//s3XrdrkNG/ZclmV009S4cZPAaw1VHJrL5Igjjgh0NRElklUCTSXeVB9s3eRoGEC1nFCTSA3dqub6atIbSmXVEKxKNqZl1Z1Ar7Udwc32dVEcO/ZVl2BTQwzrBrZv335Rz1eivXvuude1VtHTqIEDB9mll14WGIY5p22Ntnyh+0BJQHVD/NZbb7tAx5w537knGQ8//EiWG+XQ/S0KJmjY2aOOOipb965gSiya036OttzhtlmtOlTZC3biiZ2zDGMtN954s3Xp0sV1F1Fl4tVXX7cmTZrkuG3R7A91P/nPfx523bHWrVtrgwc/7o7b4M8pP8e1qGJy2mmnWZcuJ7snk8GiKVu4fRVOuGMhmu9RNGUIld/PL/iziXQcRZoXup5oP4to9kUodTlSokRVkoMpAKluPrfffkdgmlrZjBgx0t0QqQWRckHovCCq8OpY8gMxAPJOuZjat896Ds3teqEn+s88M8z69r3fJVpXEm9dL958861AnUXXZQVRlKtC15WLLrokEAiN5u/9OlBwa08lC9U0P0ivZUeMeMmdEzQUss5ToXSD+9xzL9hNN93i6gw6x/Tp08cFVvyyvPzyaDvzzLPdQwWdZ1566eUs5+pI2xJNGUT5rfQQQ++R0/YpyBQawNe+12fg0/Vff+cHoPL6OprtjWbfR9onoaJ5T9G2R8qFpuDImDGvuGuVkssqh5vWq3KpfNG+V277SC1OdK1USyoNw6wEww899HCW70m4fRTNfnn11XHWs+c12boToXhI05BB8S4EACQz5RxRYrN+/R60U0891RLRKad0sSuu6JFlZACgMKnJ9qBBA+2++/qGfdIZjcceG+wCX2qRBgCJTl1LFNzRwyAUP8uW/WFjxoxxrbMJrhRPBFcAIJ8Um9aQgJMnT7Zff11s77zzXqD/bqIhuAIAAAAUHroFAUAMwZVp06ZZzZo1XFeKRA2s5KWLDAAAAIC8o+UKAAAAAABADGi5AgAAAAAAEAOCKwAAAAAAADEguAIAAAAAABADgisAAAAAAAAxILgCAAAAAAAQA4IrAAAAAAAAMSC4AgAAAAAAEAOCKwAAAAAAADEguAIAAAAAAGD59380XplWAUwveAAAAABJRU5ErkJggg==", + "text/plain": [ + "
" + ] + }, + "metadata": {}, + "output_type": "display_data" + } + ], + "source": [ + "import numpy as np\n", + "\n", + "means = staged.groupby([\"staging\", \"scenario\"], sort=False)[[\"accurate mission\", \"cost present\"]].mean()\n", + "fig, axes = plt.subplots(1, 2, figsize=(11, 3.4), sharey=True)\n", + "for k, (color, field) in enumerate(zip(COLORS, FIELDS)):\n", + " part = means.xs(field, level=\"scenario\").reindex(STAGING)\n", + " rows = np.arange(len(STAGING)) + (k - 1) * 0.2 # offsets the fields, whose values may be equal\n", + " for ax, column in zip(axes, [\"accurate mission\", \"cost present\"]):\n", + " ax.scatter(part[column], rows, s=46, color=color, edgecolor=\"white\", lw=1, zorder=3, label=f\"field of {field}\")\n", + "axes[0].set_yticks(range(len(STAGING)), STAGING)\n", + "axes[0].invert_yaxis()\n", + "axes[0].set(xlabel=\"Points accurately sampled over the mission (%)\", xlim=(0, 100))\n", + "axes[1].set(xlabel=\"Present cost (millions of dollars)\")\n", + "axes[0].legend(loc=\"lower left\")\n", + "for ax in axes:\n", + " style_axes(ax, grid=\"x\")\n", + "plt.show()" + ] + }, + { + "cell_type": "markdown", + "id": "9d9352fa", + "metadata": {}, + "source": [ + "Deciding at the first launch is worth the most. Where the field varies within hours, the second plane is produced and launched as if it were deployed at once: 63% and 78% of the points are accurately sampled on average over the mission, for 156 million dollars. Where the field varies slowly, the second plane is not deployed, which saves 38 million dollars (24%) for 19 points of the mean (71% against 91%): a trade that the rule makes, and that a mission might not.\n", + "\n", + "Deciding a year later costs the fields that need the second plane 13 to 15 points of the mean (50% and 62%), as the first plane flies alone a year longer, and saves only 2 million dollars, by discounting the later production. The earlier the need is known, the more staging saves, at less loss.\n", + "\n", + "The rule that measures makes the same choices as the rule that reads the field, in every field. The first plane alone samples 5% and 8% of the points accurately where the field varies within hours, so the second plane is deployed, and 71% where it varies over 12 hours, so it is not. A mission knows what its satellites achieve, not the field, so this is a rule it could follow." + ] + }, + { + "cell_type": "markdown", + "id": "03b23bc6", + "metadata": {}, + "source": [ + "## Summary\n", + "\n", + "* A `DeploymentSchedule` divides each design's mission into phases of the satellites that fly, which the study evaluates (with `phases`) for what the design achieves on average over its mission, and the time until it meets a requirement.\n", + "* A `Stage` of a deployment is produced and launched only if a rule decides to, from what is known then (a `Decision`, such as what the satellites in orbit achieve, `Decision.capability`) and the values of the design. A study measures what the option is worth.\n", + "\n", + "The next notebook, `PlanForFailures`, simulates the failures of satellites and launches over each mission." + ] + }, + { + "cell_type": "markdown", + "id": "39198653", + "metadata": {}, + "source": [ + "## Notes\n", + "\n", + "* Each phase is evaluated over the same day of July, as if the geometry of the satellites and the season were those of that day throughout the mission (quasi-static phases, see `evaluate_phases`). This misses the drift between planes of different inclinations or altitudes, and seasons. The planes of these designs share an altitude and an inclination, and the shares do not depend on the sun, so the day should represent the mission. An `Uncertain` start of the observations, drawn for each replicate over a year, would average over the drift and the seasons, at the cost of analyzing the satellites again for each day.\n", + "* The rule that measures the first plane reads its capability at once, as the study computes it. A real measurement takes time, and a rule that waits a year to measure loses what deciding a year later loses.\n", + "* A rule may also read the satellites still operating (see `Decision`), for a reserve plane launched only if satellites fail." + ] + } + ], + "metadata": { + "kernelspec": { + "display_name": "Python 3 (ipykernel)", + "language": "python", + "name": "python3" + }, + "language_info": { + "codemirror_mode": { + "name": "ipython", + "version": 3 + }, + "file_extension": ".py", + "mimetype": "text/x-python", + "name": "python", + "nbconvert_exporter": "python", + "pygments_lexer": "ipython3", + "version": "3.14.10" + } + }, + "nbformat": 4, + "nbformat_minor": 5 +} diff --git a/docs/examples/tradespace/PlanForFailures.ipynb b/docs/examples/tradespace/PlanForFailures.ipynb new file mode 100644 index 0000000..7468033 --- /dev/null +++ b/docs/examples/tradespace/PlanForFailures.ipynb @@ -0,0 +1,1214 @@ +{ + "cells": [ + { + "cell_type": "markdown", + "id": "3e52904d", + "metadata": {}, + "source": [ + "# Plan for Failures\n", + "\n", + "Satellites and launches fail, and what failures cost depends on how the mission responds to them. This notebook simulates failures over each design's mission, and compares ways to restore failed satellites as decisions of each design.\n", + "\n", + "It covers:\n", + "\n", + "* a **failure model** of satellites and launches;\n", + "* **restoration policies**, as decisions of the design;\n", + "* choosing a design and its policy together;\n", + "* **attributing** the spread of the replicates to their uncertain parameters.\n", + "\n", + "It builds on `PlanDeployment`: the study evaluates each history of failures by the phases in which its satellites operate." + ] + }, + { + "cell_type": "markdown", + "id": "466f7b9b", + "metadata": {}, + "source": [ + "## Model Failures\n", + "\n", + "A `FailureModel` gives the life of a satellite from its launch, and the probability that a launch fails. The life here is a bathtub curve (`Bathtub`) of infant mortality, random failures, and wear-out (illustrative), and 5% of launches fail:" + ] + }, + { + "cell_type": "code", + "execution_count": 1, + "id": "e20ee309", + "metadata": { + "execution": { + "iopub.execute_input": "2026-11-15T04:34:00.788084Z", + "iopub.status.busy": "2026-11-15T04:34:00.787934Z", + "iopub.status.idle": "2026-11-15T04:34:02.611928Z", + "shell.execute_reply": "2026-11-15T04:34:02.611440Z" + } + }, + "outputs": [ + { + "name": "stdout", + "output_type": "stream", + "text": [ + "37% of the satellites fail within 5 years\n" + ] + } + ], + "source": [ + "from tatc.tradespace import Bathtub, Exponential, FailureModel, Weibull\n", + "\n", + "FAILURE_MODEL = FailureModel(\n", + " life=Bathtub(infant=Weibull(shape=0.5, scale=100), random=Exponential(0.03), wear_out=Weibull(shape=4, scale=9)),\n", + " launch=0.05,\n", + ")\n", + "print(f\"{1 - FAILURE_MODEL.life.survival(5):.0%} of the satellites fail within 5 years\")" + ] + }, + { + "cell_type": "markdown", + "id": "c498cbd0", + "metadata": {}, + "source": [ + "The share of satellites still operating at each age, and the rate at which those that operate fail, whose bathtub shape gives the curve its name: failures are frequent just after launch (infant mortality), least frequent after about two years, and more frequent again as satellites wear out." + ] + }, + { + "cell_type": "code", + "execution_count": 2, + "id": "7c437e44", + "metadata": { + "execution": { + "iopub.execute_input": "2026-11-15T04:34:02.613340Z", + "iopub.status.busy": "2026-11-15T04:34:02.613080Z", + "iopub.status.idle": "2026-11-15T04:34:03.063793Z", + "shell.execute_reply": "2026-11-15T04:34:03.063133Z" + } + }, + "outputs": [ + { + "data": { + "image/png": "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", + "text/plain": [ + "
" + ] + }, + "metadata": {}, + "output_type": "display_data" + } + ], + "source": [ + "import matplotlib.pyplot as plt\n", + "import numpy as np\n", + "\n", + "from tatc.tradespace import COLORS, GRAY, INK, style_axes, use_style\n", + "\n", + "use_style() # the style of the plots of trade studies\n", + "\n", + "age = np.linspace(0.02, 10, 500) # years since launch\n", + "fig, axes = plt.subplots(1, 2, figsize=(11, 3.6))\n", + "axes[0].plot(age, 100 * FAILURE_MODEL.life.survival(age), color=COLORS[0], lw=2)\n", + "axes[0].set(ylabel=\"Satellites operating (%)\", ylim=(0, 102))\n", + "axes[1].plot(age, FAILURE_MODEL.life.hazard(age), color=COLORS[0], lw=2)\n", + "axes[1].set(ylabel=\"Failures a year, of those operating\", ylim=(0, 1))\n", + "for ax in axes:\n", + " ax.axvline(5, color=GRAY, lw=1, ls=\"--\")\n", + " ax.set(xlabel=\"Years since launch\", xlim=(0, 10))\n", + " style_axes(ax, grid=\"both\")\n", + "axes[1].annotate(\"infant mortality\", (0.3, 0.2), xytext=(8, 14), textcoords=\"offset points\", fontsize=8, color=INK)\n", + "axes[1].annotate(\"wear-out\", (8.5, 0.5), xytext=(-60, 10), textcoords=\"offset points\", fontsize=8, color=INK)\n", + "plt.show()" + ] + }, + { + "cell_type": "markdown", + "id": "ec2f68a0", + "metadata": {}, + "source": [ + "## Respond to Failures\n", + "\n", + "A `RestorationPolicy` responds to failures. Here, five policies:\n", + "\n", + "* **degrade**: fly the satellites that remain;\n", + "* **produce**: replace each failed satellite by producing a new one, after half a year of procurement, and launching it;\n", + "* **spare in orbit**: launch a spare with each plane, which takes a failed satellite's place within months;\n", + "* **spare on ground**: store a spare, which is launched at the next opportunity;\n", + "* **spares in orbit and on ground**: both.\n", + "\n", + "The policy is a decision of each design: `policy_space` declares whether to restore failed satellites, the numbers of spares in each plane and on the ground (none or one of each), and the policy's other fields (here, half a year of procurement, and a spare produced again once it is used). `space.extend` adds the policy to the design space, with the seed of the failures (`failure_seed`, drawn for each replicate).\n", + "\n", + "`Failures` simulate 20 histories of the failures of each replicate, restored by the design's policy (which the mission plan reads from the design's value `policy`). The study evaluates each history by the phases in which its satellites operate, and gives the means over the histories and other `statistics` over them: here, two quantiles (`Quantile`), the share accurately sampled in the worst 10% of the histories (`accurate mission histories p10`), and the cost at 70% confidence (`cost histories p70`). The designs are the efficient designs by accuracy of `ExplainTradeSpace`, each with each policy (`failure_space.enumerate` extends each with every policy)." + ] + }, + { + "cell_type": "code", + "execution_count": 3, + "id": "35efa3e2", + "metadata": { + "execution": { + "iopub.execute_input": "2026-11-15T04:34:03.065253Z", + "iopub.status.busy": "2026-11-15T04:34:03.064964Z", + "iopub.status.idle": "2026-11-15T04:34:03.867962Z", + "shell.execute_reply": "2026-11-15T04:34:03.867436Z" + } + }, + "outputs": [ + { + "name": "stdout", + "output_type": "stream", + "text": [ + "65 designs and policies x 5 replicates x 20 histories\n" + ] + } + ], + "source": [ + "from trade_space_example import ACCURACY, cost_space, cost_study\n", + "from tatc.tradespace import (\n", + " Failures,\n", + " Integer,\n", + " Quantile,\n", + " Uncertain,\n", + " pareto_front,\n", + " policy_space,\n", + " summarize,\n", + ")\n", + "\n", + "summary = summarize(cost_study.run(), ACCURACY)\n", + "efficient = summary[summary.pareto]\n", + "\n", + "# the policy of each design: its spares, and its other fields (half a year of procurement, and spares produced again)\n", + "POLICY = policy_space(orbit_spares=Integer(0, 1), ground_spares=Integer(0, 1), replenish=True, procurement_years=0.5)\n", + "failure_space = cost_space.extend(failure_seed=Uncertain.seed(), policy=POLICY)\n", + "FAILURES = Failures(\n", + " FAILURE_MODEL,\n", + " seed=\"failure_seed\",\n", + " histories=20,\n", + " statistics=[Quantile(\"accurate mission\", 0.1), Quantile(\"cost\", 0.7)],\n", + ")\n", + "# the plan configures the policy (and spares in orbit) of each design from its values `policy`, by default\n", + "failure_study = cost_study.replace(space=failure_space, failures=FAILURES)\n", + "\n", + "# the efficient designs, each with each policy\n", + "with_policies = failure_space.enumerate(cost_space.designs_of(efficient))\n", + "trades = failure_study.run(with_policies)\n", + "print(f\"{len(with_policies)} designs and policies x 5 replicates x 20 histories\")" + ] + }, + { + "cell_type": "markdown", + "id": "8905ad94", + "metadata": {}, + "source": [ + "The table gives four of the designs, each with each policy: two satellites in two planes, four in two, six in three, and nine in three. Its columns are the means over the replicates of the share accurately sampled over the mission (`accurate mission`, on average over the histories, and `accurate p10`, in their worst 10%) and of the cost at 70% confidence (`cost p70`). The first column is the share of the full constellation, without deployment or failures, from `ExplainTradeSpace`." + ] + }, + { + "cell_type": "code", + "execution_count": 4, + "id": "4c9a47e8", + "metadata": { + "execution": { + "iopub.execute_input": "2026-11-15T04:34:03.869200Z", + "iopub.status.busy": "2026-11-15T04:34:03.869025Z", + "iopub.status.idle": "2026-11-15T04:34:03.897198Z", + "shell.execute_reply": "2026-11-15T04:34:03.896609Z" + } + }, + "outputs": [ + { + "data": { + "text/html": [ + "
\n", + "\n", + "\n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + "
accurate missionaccurate p10cost p70
descriptionfull constellationpolicy
800 km, 60 deg FOR, Walker 45 deg: 2 x 1 (spacing 0)34.2degrade17.70.6136.5
produce26.119.5159.4
spare in orbit28.225.1192.7
spare on ground28.925.6175.2
spares in orbit and on ground28.525.6206.4
800 km, 60 deg FOR, SSO: 2 at 09:00, 2 at 15:0085.4degrade50.611.4170.4
produce68.356.3218.3
spare in orbit68.460.5246.8
spare on ground72.362.1235.4
spares in orbit and on ground69.163.1261.3
700 km, 60 deg FOR, Walker 75 deg: 3 x 2 (spacing 0)96.4degrade64.238.9209.5
produce78.070.1278.8
spare in orbit74.267.3316.7
spare on ground79.671.5294.4
spares in orbit and on ground74.466.9329.5
800 km, 60 deg FOR, Walker 75 deg: 3 x 3 (spacing 0)97.8degrade79.366.4253.5
produce82.878.1340.0
spare in orbit76.871.6394.6
spare on ground82.878.2355.7
spares in orbit and on ground76.971.6405.9
\n", + "
" + ], + "text/plain": [ + " accurate mission \\\n", + "description full constellation policy \n", + "800 km, 60 deg FOR, Walker 45 deg: 2 x 1 (spaci... 34.2 degrade 17.7 \n", + " produce 26.1 \n", + " spare in orbit 28.2 \n", + " spare on ground 28.9 \n", + " spares in orbit and on ground 28.5 \n", + "800 km, 60 deg FOR, SSO: 2 at 09:00, 2 at 15:00 85.4 degrade 50.6 \n", + " produce 68.3 \n", + " spare in orbit 68.4 \n", + " spare on ground 72.3 \n", + " spares in orbit and on ground 69.1 \n", + "700 km, 60 deg FOR, Walker 75 deg: 3 x 2 (spaci... 96.4 degrade 64.2 \n", + " produce 78.0 \n", + " spare in orbit 74.2 \n", + " spare on ground 79.6 \n", + " spares in orbit and on ground 74.4 \n", + "800 km, 60 deg FOR, Walker 75 deg: 3 x 3 (spaci... 97.8 degrade 79.3 \n", + " produce 82.8 \n", + " spare in orbit 76.8 \n", + " spare on ground 82.8 \n", + " spares in orbit and on ground 76.9 \n", + "\n", + " accurate p10 \\\n", + "description full constellation policy \n", + "800 km, 60 deg FOR, Walker 45 deg: 2 x 1 (spaci... 34.2 degrade 0.6 \n", + " produce 19.5 \n", + " spare in orbit 25.1 \n", + " spare on ground 25.6 \n", + " spares in orbit and on ground 25.6 \n", + "800 km, 60 deg FOR, SSO: 2 at 09:00, 2 at 15:00 85.4 degrade 11.4 \n", + " produce 56.3 \n", + " spare in orbit 60.5 \n", + " spare on ground 62.1 \n", + " spares in orbit and on ground 63.1 \n", + "700 km, 60 deg FOR, Walker 75 deg: 3 x 2 (spaci... 96.4 degrade 38.9 \n", + " produce 70.1 \n", + " spare in orbit 67.3 \n", + " spare on ground 71.5 \n", + " spares in orbit and on ground 66.9 \n", + "800 km, 60 deg FOR, Walker 75 deg: 3 x 3 (spaci... 97.8 degrade 66.4 \n", + " produce 78.1 \n", + " spare in orbit 71.6 \n", + " spare on ground 78.2 \n", + " spares in orbit and on ground 71.6 \n", + "\n", + " cost p70 \n", + "description full constellation policy \n", + "800 km, 60 deg FOR, Walker 45 deg: 2 x 1 (spaci... 34.2 degrade 136.5 \n", + " produce 159.4 \n", + " spare in orbit 192.7 \n", + " spare on ground 175.2 \n", + " spares in orbit and on ground 206.4 \n", + "800 km, 60 deg FOR, SSO: 2 at 09:00, 2 at 15:00 85.4 degrade 170.4 \n", + " produce 218.3 \n", + " spare in orbit 246.8 \n", + " spare on ground 235.4 \n", + " spares in orbit and on ground 261.3 \n", + "700 km, 60 deg FOR, Walker 75 deg: 3 x 2 (spaci... 96.4 degrade 209.5 \n", + " produce 278.8 \n", + " spare in orbit 316.7 \n", + " spare on ground 294.4 \n", + " spares in orbit and on ground 329.5 \n", + "800 km, 60 deg FOR, Walker 75 deg: 3 x 3 (spaci... 97.8 degrade 253.5 \n", + " produce 340.0 \n", + " spare in orbit 394.6 \n", + " spare on ground 355.7 \n", + " spares in orbit and on ground 405.9 " + ] + }, + "execution_count": 4, + "metadata": {}, + "output_type": "execute_result" + } + ], + "source": [ + "import pandas as pd\n", + "\n", + "\n", + "def describe_policy(row):\n", + " \"\"\"The name of a design's policy.\"\"\"\n", + " if not row[\"policy.restore\"]:\n", + " return \"degrade\"\n", + " orbit, ground = row[\"policy.orbit_spares\"] > 0, row[\"policy.ground_spares\"] > 0\n", + " return {\n", + " (False, False): \"produce\",\n", + " (True, False): \"spare in orbit\",\n", + " (False, True): \"spare on ground\",\n", + " (True, True): \"spares in orbit and on ground\",\n", + " }[orbit, ground]\n", + "\n", + "\n", + "POLICIES = [\"degrade\", \"produce\", \"spare in orbit\", \"spare on ground\", \"spares in orbit and on ground\"]\n", + "# the means over the replicates of the mean share over the histories, the share in their worst 10%, and the cost at\n", + "# 70% confidence over the histories\n", + "ROBUST = {\n", + " \"accurate mission\": \"accurate mission\",\n", + " \"accurate p10\": \"accurate mission histories p10\",\n", + " \"cost p70\": \"cost histories p70\",\n", + "}\n", + "traded = summarize(trades, statistics=ROBUST).set_index(\"design\")\n", + "traded[\"policy\"] = pd.Categorical(traded.apply(describe_policy, axis=1), POLICIES)\n", + "# the share accurately sampled by the design without failures (of the same description)\n", + "traded[\"full constellation\"] = traded.description.map(efficient.set_index(\"description\").accurate)\n", + "\n", + "# four of the designs, with each policy: two satellites in two planes, four in two, six in three, and nine in three\n", + "shown = efficient.drop_duplicates([\"satellites\", \"planes\"]).set_index([\"satellites\", \"planes\"])\n", + "shown = shown.loc[[(2, 2), (4, 2), (6, 3), (9, 3)], \"description\"]\n", + "table = traded[traded.description.isin(shown)].sort_values([\"satellites\", \"policy\"])\n", + "table.round(1).set_index([\"description\", \"full constellation\", \"policy\"])[list(ROBUST)]" + ] + }, + { + "cell_type": "markdown", + "id": "00f2c896", + "metadata": {}, + "source": [ + "The shares over the mission fall short of those of the full constellation under every policy, by the phases of deployment and the failures of launches as well as of satellites:\n", + "\n", + "* **Degrading** is cheapest, but loses the most, above all in the worst histories: two satellites in two planes keep 18% on average, and 1% in their worst 10% of histories, as both can fail. Nine satellites keep the most of what they would sample (79% of 98%), as a failure leaves eight.\n", + "* **Producing replacements** restores most of what degrading loses, at 17 to 34% more cost.\n", + "* **A spare on the ground** restores as well or better, for about 16 million dollars more than producing replacements, and pays off in the worst histories of the small designs: two satellites in two planes keep 26% in their worst histories with it, against 20%.\n", + "* **A spare in orbit can hurt.** Each plane waits for its spare to be produced, and a spare in a plane of three satellites takes a second launch, which delays the deployment. Six satellites in three planes then sample less on average than by producing replacements (74% against 78%), and nine satellites less than by degrading (77% against 79%), at a higher cost. Spares both in orbit and on the ground cost the most, and sample about as much as a spare in orbit alone." + ] + }, + { + "cell_type": "markdown", + "id": "884f27fc", + "metadata": {}, + "source": [ + "## Choose a Design and its Policy\n", + "\n", + "The front of cost at 70% confidence against the share accurately sampled in the worst 10% of the histories chooses designs and policies together:" + ] + }, + { + "cell_type": "code", + "execution_count": 5, + "id": "a41c39e2", + "metadata": { + "execution": { + "iopub.execute_input": "2026-11-15T04:34:03.898629Z", + "iopub.status.busy": "2026-11-15T04:34:03.898442Z", + "iopub.status.idle": "2026-11-15T04:34:03.904828Z", + "shell.execute_reply": "2026-11-15T04:34:03.904302Z" + } + }, + "outputs": [ + { + "data": { + "text/html": [ + "
\n", + "\n", + "\n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + "
descriptionpolicyaccurate missionaccurate p10cost p70
design
c58eba60fcc8800 km, 60 deg FOR, SSO: 1 at 12:00degrade3.20.4110.2
4098dd5b042f800 km, 60 deg FOR, SSO: 2 at 06:00degrade7.02.1128.9
bb0be3483708800 km, 60 deg FOR, SSO: 1 at 12:00produce3.93.5130.6
638697713902800 km, 60 deg FOR, Walker 75 deg: 1 x 3 (spac...degrade10.94.6146.2
8aca273a3613800 km, 60 deg FOR, SSO: 2 at 06:00produce9.27.3153.4
ad99c42082ab800 km, 60 deg FOR, Walker 45 deg: 2 x 1 (spac...produce26.119.5159.4
cc2e14e787ff800 km, 60 deg FOR, Walker 45 deg: 2 x 1 (spac...spare on ground28.925.6175.2
77d5dc1d8f4f800 km, 60 deg FOR, SSO: 1 at 09:00, 2 at 15:00produce46.435.9193.5
525acda84c60800 km, 60 deg FOR, Walker 60 deg: 3 x 1 (spac...produce44.937.7201.0
3a902b976460700 km, 60 deg FOR, Walker 75 deg: 3 x 2 (spac...degrade64.238.9209.5
d1a143db2a62800 km, 60 deg FOR, SSO: 1 at 09:00, 2 at 15:00spare on ground50.240.9211.7
7b247cdf0711800 km, 60 deg FOR, Walker 60 deg: 3 x 1 (spac...spare on ground48.142.4216.8
170ca99f7e10800 km, 60 deg FOR, SSO: 2 at 09:00, 2 at 15:00produce68.356.3218.3
e84f662c5ca8800 km, 60 deg FOR, SSO: 2 at 09:00, 2 at 15:00spare on ground72.362.1235.4
46932f795a5a800 km, 60 deg FOR, Walker 75 deg: 3 x 3 (spac...degrade79.569.0253.5
6e4564d2ae2c700 km, 60 deg FOR, Walker 75 deg: 3 x 2 (spac...produce78.070.1278.8
570a452fdb8f700 km, 60 deg FOR, Walker 75 deg: 3 x 2 (spac...spare on ground79.671.5294.4
2b499d154a98800 km, 60 deg FOR, Walker 75 deg: 4 x 2 (spac...produce81.273.8326.4
a37619256b26800 km, 60 deg FOR, Walker 75 deg: 3 x 3 (spac...produce83.078.7340.0
\n", + "
" + ], + "text/plain": [ + " description \\\n", + "design \n", + "c58eba60fcc8 800 km, 60 deg FOR, SSO: 1 at 12:00 \n", + "4098dd5b042f 800 km, 60 deg FOR, SSO: 2 at 06:00 \n", + "bb0be3483708 800 km, 60 deg FOR, SSO: 1 at 12:00 \n", + "638697713902 800 km, 60 deg FOR, Walker 75 deg: 1 x 3 (spac... \n", + "8aca273a3613 800 km, 60 deg FOR, SSO: 2 at 06:00 \n", + "ad99c42082ab 800 km, 60 deg FOR, Walker 45 deg: 2 x 1 (spac... \n", + "cc2e14e787ff 800 km, 60 deg FOR, Walker 45 deg: 2 x 1 (spac... \n", + "77d5dc1d8f4f 800 km, 60 deg FOR, SSO: 1 at 09:00, 2 at 15:00 \n", + "525acda84c60 800 km, 60 deg FOR, Walker 60 deg: 3 x 1 (spac... \n", + "3a902b976460 700 km, 60 deg FOR, Walker 75 deg: 3 x 2 (spac... \n", + "d1a143db2a62 800 km, 60 deg FOR, SSO: 1 at 09:00, 2 at 15:00 \n", + "7b247cdf0711 800 km, 60 deg FOR, Walker 60 deg: 3 x 1 (spac... \n", + "170ca99f7e10 800 km, 60 deg FOR, SSO: 2 at 09:00, 2 at 15:00 \n", + "e84f662c5ca8 800 km, 60 deg FOR, SSO: 2 at 09:00, 2 at 15:00 \n", + "46932f795a5a 800 km, 60 deg FOR, Walker 75 deg: 3 x 3 (spac... \n", + "6e4564d2ae2c 700 km, 60 deg FOR, Walker 75 deg: 3 x 2 (spac... \n", + "570a452fdb8f 700 km, 60 deg FOR, Walker 75 deg: 3 x 2 (spac... \n", + "2b499d154a98 800 km, 60 deg FOR, Walker 75 deg: 4 x 2 (spac... \n", + "a37619256b26 800 km, 60 deg FOR, Walker 75 deg: 3 x 3 (spac... \n", + "\n", + " policy accurate mission accurate p10 cost p70 \n", + "design \n", + "c58eba60fcc8 degrade 3.2 0.4 110.2 \n", + "4098dd5b042f degrade 7.0 2.1 128.9 \n", + "bb0be3483708 produce 3.9 3.5 130.6 \n", + "638697713902 degrade 10.9 4.6 146.2 \n", + "8aca273a3613 produce 9.2 7.3 153.4 \n", + "ad99c42082ab produce 26.1 19.5 159.4 \n", + "cc2e14e787ff spare on ground 28.9 25.6 175.2 \n", + "77d5dc1d8f4f produce 46.4 35.9 193.5 \n", + "525acda84c60 produce 44.9 37.7 201.0 \n", + "3a902b976460 degrade 64.2 38.9 209.5 \n", + "d1a143db2a62 spare on ground 50.2 40.9 211.7 \n", + "7b247cdf0711 spare on ground 48.1 42.4 216.8 \n", + "170ca99f7e10 produce 68.3 56.3 218.3 \n", + "e84f662c5ca8 spare on ground 72.3 62.1 235.4 \n", + "46932f795a5a degrade 79.5 69.0 253.5 \n", + "6e4564d2ae2c produce 78.0 70.1 278.8 \n", + "570a452fdb8f spare on ground 79.6 71.5 294.4 \n", + "2b499d154a98 produce 81.2 73.8 326.4 \n", + "a37619256b26 produce 83.0 78.7 340.0 " + ] + }, + "execution_count": 5, + "metadata": {}, + "output_type": "execute_result" + } + ], + "source": [ + "chosen = traded[pareto_front(traded, {\"cost p70\": \"min\", \"accurate p10\": \"max\"})]\n", + "chosen.sort_values(\"cost p70\")[[\"description\", \"policy\", \"accurate mission\", \"accurate p10\", \"cost p70\"]].round(1)" + ] + }, + { + "cell_type": "markdown", + "id": "eb715b9d", + "metadata": {}, + "source": [ + "Each policy's designs (blue) among every design and policy (gray), with those on the front ringed:" + ] + }, + { + "cell_type": "code", + "execution_count": 6, + "id": "58d5e989", + "metadata": { + "execution": { + "iopub.execute_input": "2026-11-15T04:34:03.906370Z", + "iopub.status.busy": "2026-11-15T04:34:03.906192Z", + "iopub.status.idle": "2026-11-15T04:34:04.172772Z", + "shell.execute_reply": "2026-11-15T04:34:04.172204Z" + } + }, + "outputs": [ + { + "data": { + "image/png": "iVBORw0KGgoAAAANSUhEUgAABksAAAFzCAYAAACepT7dAAAAOnRFWHRTb2Z0d2FyZQBNYXRwbG90bGliIHZlcnNpb24zLjExLjIsIGh0dHBzOi8vbWF0cGxvdGxpYi5vcmcvgI3uAAAAAAlwSFlzAAAPYQAAD2EBqD+naQABAABJREFUeJzs3Qd4U9X7B/C3m9XBKKVsFFQQBASUvUH2FtkoQ0DEASpbhqKg7CEiQ5ApW1GQ7WAv2YiAbEppgZYCHbTN//ke/je/tLQlSdMmufl+nidPcjNuTm6Tt+fc9ww3g8FgECIiIiIiIiIiIiIiIhflbu8CEBERERERERERERER2ROTJURERERERERERERE5NKYLCEiIiIiIiIiIiIiIpfGZAkREREREREREREREbk0JkuIiIiIiIiIiIiIiMilMVlCREREREREREREREQujckSIiIiIiIiIiIiIiJyaUyWEBERERERERERERGRS2OyhIiIiIiIiIiIiIiIXBqTJaRrW7dulb1799q7GA5fJiIizdy5cyUkJIQHhIjIShcvXpQlS5bw+BERWWjhwoVy5coVHjciHTh06JBs3LhRHN3atWvl1KlT9i6Gw3j06JHMnDlToqKixFUxWUK6tmjRIvnpp5/EkThimYiINB9//LFcuHCBB4SIdAEn3XDyLTMdO3ZMRo8e7VBlIiJyBiNGjJDTp0/buxhEunP06FHZsGFDpr7nb7/9Jt99951DlSklkydPlr/++svexXAYsbGxMmDAALl9+7a4KiZLiIiIiIhIlx48eOBwCeDkZbp06ZL88MMPdi0TERER6RdOfF+9elUcuUxHjhyRX3/91a5lIgImS4iIiIiISJdKliwpn332mThymU6ePCmffvqpXctERERE+lWvXj155513xJHLtGXLFpk9e7Zdy0QEnjwMpCfR0dGyfft21WOvevXqKT7nwIEDcubMGcmfP7/UqVNHPD3/9zN4+PChej2uq1Wrpp6XI0cOqVKlivz777/y999/y2uvvSa7du1S71W1alVZt26deq2/v79UrFhRNYBtWSYiIvjnn3/k+PHjUr9+ffnjjz8kISFBVTBz5syZ5PEGDRqoGBUXFydt27aVO3fuqGHF9+/fl1dffVWKFy+e5IDeuHFDfv/9d7WfWrVqJXkMUwY+88wzUqZMGeN9GErdsmVLCQoK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iIiIiIgoE3FkCRERUQbz9w9QI0oGDHhXTp48IYsX/6AuyXXq1Ek++WSIGmlCREREREREREROmiyZNWummou9YsWKttwtERGR08OC7cuWLZfdu3fJihUr1ILvWJMpICBA6tWrL2+88YY8+2xxexeTiIiIiIiIiMgl2TRZsmTJYpkz51t10mfKlKm23DUREZHTc3d3lxo1aqoLERERERERERHpNFmyd+9+uXv3ruza9Zctd0tERERERERERERERJRh3G29w5w5c0rz5i1svVsiIiIiIiIiIiIiIiLHGFkSFxcn+/btlcOHD8vNmzfVffny5VPrlFSuXFm8vLwzopxERERERERERERERET2TZY8fPhQvv9+gfz44wp58OCBPPfcc5I7dx712IED+2Xx4h8kR44c0qFDR3nrrR6SNWvWjCkxERERERERERERERGRPZIlLVo0k1KlXpTPPx8nVapUeWIEyaNHcbJnz15Zs2a1NG/eVLZt22HLchIREREREREREREREdk3WTJ9+kwpVapUqo8jeVKrVi11OX36tK3KR0RERERERERERERE5BgLvKeVKEnPc4mIiIiIiIiIiIiIiJxqgXdToaGhMnnyRLXYu8EgUqFCBRk06CMJCgoy6/VLliyR33//Pcl9BQoUkDFjxiS578qVK7Jo0SL1fmXKlJE333xTfHx80lN0IiIiIiIiIiIiIiIiy0aWpGTw4I/F19dPTdE1Y8ZM8fPzk8GDPzH79bt27ZKjR49K5cqVjZeyZcsmeQ6m9MJ9R44ckUKFCsn06dOlbt268ujRo/QUnYiIiIiIiIiIiIiIyPKRJbNnfyO9evUWLy8vtX3mzBmVKEGSRBsV0rBhfUt2KUWLFpVevXql+vjgwYPl5ZdflrVr14qbm5t069ZNihUrJosXL5YePXpY9F5ERERERERERERERETpGlmCabDat39djh07prarV68hAwd+IOvWrVWXQYM+lBo1alqySzl79qy89957MnLkSNmyZUuSx+Li4mTz5s3SoUMHlSiB4OBgqVOnjmzYsMGi9yEiIiIiIiIiIiIiIkr3yJLRo8fIwYMHZcSI4VKlSmUZOnSY/PTTetm6dat6vHLlKtKpU2ez94cEyDPPPKNGl1y/fl3atm2rLgsXLjSuVYLptvC4KYws+euvv1Ldb2xsrLpo7t27p64TExONF23bWbDMPNb8fujvt+jubvlMiIxvjoNxmceZ3w/bxjg9xjdwxnKzzDzW/H6kjXU4xorMxrjM45xZ3w/GN+f9zTlruVlmHuvM/H6YE+PcDAYszW4ZjPjAlFybNm1SCZNatWpZVcCQkBA1UkSzZ88eqV69umzcuFEaNWokJ06ckJdeekn27t2r1jMxnZprzZo1cv78+RT3O3r06CcWiYezZ0+Lr6+vVWUlIrK14OCCFr+G8Y2I9BrjGN+IyFmwDkdEesX4RkSuHuOsSpZo/v33Xxk1aqQUKFBQJU1y584t6VWkSBHp3r27jB07Vi5fvqxGlSB50rhxY+NzevfuLYcPH1aLvpvbMxGLw9+9e1etr4JsVFjYTQkMzGdV1tweWGYea34/9PdbtFWvHcY3+2Bc5nHm9yPjR5Y4e3wDZyw3y8xjze9H2liHY6zIbIzLPM6Z9f1gfHPe35yzlptl5rHOzO+HOfuwaBqu8PBwmTFjujFJUaFCBbXA+2+/bZIOHdrLO+/0l9at21hfYhGJjo4WLX+DBjIax6dPn06SLDl16pSULl061X34+PioS0oHxPSgJN92BiwzjzW/H679W2R8czyMyzzO/H7Yhp7jm7OWm2Xmseb3w3b0HONYZh5rfj8cA9uo+jmmrlhulpnH2lG+Hxa9y5Ahn6g1REaNGq0uuD1s2FDp2rWbLFr0g2zZsll69eph1r7i4+Pl119/TXLf3LlzJSwszJgYwUF44403ZMGCBfLgwQN1H9ZM2bdvn3Ts2NGSohMREREREREREREREaV/ZAnWENm6daoa7QHPPfecNGhQT93On7+AzJ49R375ZYPZi7vPnz9fhg0bJqVKlVKLuR87dkymTJkiVatWNT7viy++kHr16knZsmXV+iXbt2+Xfv36JRlpQkRERERERERERERElCnJkldfraxGkjRv3lxtb9iwQd1nqlmzx489jYeHh6xdu1bOnj0rR48elZw5c8rLL78sefLkSfI8bB86dEh27twpoaGh8umnn0q5cuUsKTYREREREREREREREZFtkiVffPGlLFgwX5YvX662kdzo0aOnpMfzzz+vLmnx8vKShg0bput9iIiIiIiIiIiIiIiI0p0syZEjh7z33vuWvISIiIiIiIiIiIiIiMihmb3A+zffzJKHDx8vsp4WLMSO5xIREREREREREREREelqZMmNG9elQYP60rRpU6lVq468+OKL4u/vrx67e/eunDx5Qq0rsnnzb1KnTt2MLDMREREREREREREREVHmJ0s+//wLOXXqlCxatFDee+9diY2NFU9PTzEYDJKQkCBZsmSRevXqy7x5C6RUqVK2KyEREREREREREREREZGjrFmC0SRfffW1xMXFyenTp+XmzRBxc3OToKB88uKLpcTLyzvjSkpERERERERERERERGTvZInG29tbypUrJyK4EBERERERERERERERucAC70RERERERERERERERHrEZAkREREREREREREREbk0JkuIiIiIiIiIiIiIiMilMVlCREREREREREREREQuzewF3mNjY83eqY+Pj7XlISIiIiIiIiJyCDgXsnnzZvnjj50SGRkpWbNmlYoVK0mrVq3E3z/A3sUjItI9g8Eg92ISxS+Lu7i5udm7OKRzZidLKlQob/ZOT548bW15iJxCRMRdiYmJkSxZskhAQE57F4eIyGYY34hIzxjjiMgSa9askSlTJklERESS+3fu3CnTp0+TLl26ynvvvS8eHh52P7CMb0SkR+dDY2XG1jAJiXgkwQFeMqBBoBQPYid9coBkydKly423jx79W+bM+Va6d39TSpcure47efKkLFq0UPr06ZsxJSVyEKiEhoeHq9v3799X10yYEJEeML4RkbP2NMzh/fTnMsYRkSW+/36BTJo0Ud3Oly+ftGnTVgoXLix37tyRn35aL2fPnpX58+dJSEiIjB8/Qdzd7TfLOeMbEem1nqclSgDX2J7auQBHmJD9kyVly5Y13h4//guZPHmKVK5cxXhftWrV5aWXXpIZM6arJAqRs9F64nh7p52hxnPS2iYicjSMb0Sk956G+fw9pWP5RAkKSv35rMMRkbmOHj1qTJT07dtPXTw9/3f6pGvXbrJp0yYZNmyIbNz4q5QvX146duxk8wPMOhwR6ZU58Q0dYrREiQbbUZiSK6v9R/SRPlnV9eH8+fPy4ouPR5SYKl26jJw7d84W5SKyS08cjBS5fTtcoqKiUn0upt5Ka5uIyJEwvhGRq/Q0XLgvTt2fGtbhiMhcCxbMV9c1atSUbt26GxMliDGR0QnqdpMmTWTgwEHq9pIliyUxMdGmB5h1OCLSK3PjG9YowdRbprDtm8V+I/lI/8weWWIqT548sn79OtWbwhTuCwwMtFXZyMVl5pyryXsa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kpBT0qbc4polROTsOnTooJIlWMgd65YUKVJUBjQINE7FhUQJtlesWC43b96UgIAAqVWrlr2LTURkFdbhiEjPGOOISK8Y34gcMFlCZIprlBCRHtSsWUvKlCkjJ06ckDff7C4jRoyU2rXryNTOBSQqJlESYu7J0qXfyZw536rn9+rVm9NuEZFTYx2OiPSMMY6I9IrxjcjBkiV3796V2bNnyZEjR+TevXtPPL5lyzZblI2IiCjTeHh4yIwZs6R3755y7tw5ef/99yQ4OFhKliwlcXGxauotrGkCXbp0la5du8mtWyH8CxERERERERERuWqyZPjwYRIaelOaNWsuvr5+ti8VERGRHeTJk0d++GGJzJ37naxdu0ZCQkLURfPCCy/Im2++JU2bNhODwcC/ERERERERERGRKydLDh48IL/8slGCgoJsXyIiIiI78vX1lYEDB0n//u+qNUxu3QoTLy8vee65ElK6dBlxc3NTz2OyhIiIiIiIiIjIxZMl/v7+4u7ubvvSEBEROQgfHx+pW7eevYtBRERERERERESZwKqMR+fOXWT8+C8lMjLS9iUiIiIiIiIiIiIiIiJy9JEltWrVVvO5V69eVfz8/IxTkmh27dpjq/IRERERERERERERERE54gLvQ6Vo0aLSsmUrLvBORERERERERERERESulyw5e/asbNmyTfLkyWP7EhERERERERERERERETn6miXBwcGSkJBg+9IQERERERERERERERE5w8iSdu1el88/HyuffjpaAgMD01WAjRs3yubNm+X+/fvy4osvyltvvSU5c+ZM8px//vlH5s6dK6GhoVKmTBnp37+/5MiRI13vS0REREREREREREREZHWy5JtvZkl0dLTs3LlTsmbN+sTjBw8eNms/PXr0kHv37km9evXE09NTFi5cKNOnT5eDBw8akzBHjhyRGjVqSPv27dX1vHnzZMWKFbJv3z7x8fHhX5GIiIiIiIiIiIiIiDI/WTJ+/IT0vatxP+Mlb968xu1OnTpJQECAbNq0Sbp166buGzp0qNSuXVu+//57td2uXTspVKiQ2u7bt69NykFERERERERERERERK7LqmRJvXr1bfLmpokSuHTpksTHx0vRokXVdmxsrOzYsUO+++4743Ny586tRqJg+i4mS4iIiIiIiIiIiIiIyC7JEls6evSofP7552o6rpMnT6qp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8+mnn5jfftto3njj9YTl//rrL9H3duzYkW11VBRFyQy//fabeffdd0Vm/fvvv+att94y69evT/g3H3ywwPzwww/a4HmQA3K6AkrOOKJWrvza7Nnzrzn++OPNiSeeaAoUKBDKd//+++/mo48+MnXr1s3Sdwb5np9++sl88cUXMT+75JJLTOHChb3Xf/zxhwQWDjroIFOpUiVTqFChqPKbNm0yX375hTn11FNNyZLHRn22bt1a8/PPa815551ncgOjRo0006a9YipXrmwqV65ifv/9N9OrV09Tu3aduH/DPXTv3tV8+OEic+CBB2ZrfRUlO/nnn3/M8uVfypg/5pgS5uSTT84w3rPCO++8bcqWLWuOPfa4tH7P7t27zZw5sYOgp5xyijnttNOiyiLftm7dYs4440xTsmTJqPIESZcu/dQcfPDBpnz5ClGf7dmzR4KtNWrUFPmY0+A4bNu2jci2Qw891NSrV8/07Hm3efDBkaZ48eJx/27YsKHmppuayZymKPsqkUjEfPvtt+ann340hx12mClTpowpVuzo0L5/xYqvzN9//22qVDkn7d/zySdLzK+/ZgyCMu4vu+yyqPe+++47+TnmmGPMWWedlUEvXL36WzFW0e8OOeTQqM8+/fRTU6xYUXP88SeYnAZZ3KTJDfL7iSeeJLJ6ypSXRIZXqBAtm11wPC5evNicf37VbKytouSMIwobddeu3aZ06dIi48KyUdELP/zwQ1OnTh1zwAEHpPV7sLuWLYsdBL3ooovM4Ycf7r3esmWL6HAHHLC/qVSpsjnkkEOiym/evFls1DJlTjbHHRetM/7yyy9mzZofTNWqF5jcwNixj5nnn3/enHNOFdE3mQd69Ohurriibty/YdEfNuq7775nChYMbz5TlNwGAUFs1E2bNos+g43qH+9Z4d1355mTTz5FZGc6vwddlAUfsShT5iRTtuwZUXbmZ58tEznG+34Zhv6zdOlS8U9VrFgxw3WwUS+99DKxYXMadNtWrVqKrnnooYeZ2rVrm3vu6WP69x9gSpQoEffvHnxwhKlfv4H4XJW8hQZL8hEod/3732vmz39fFBiEMwY3DrJ77ulnzj67fJavsXr1alF4sqqIBvkeVuThcPQLsbVr15p3333fe4+Ib+/ePc3pp5c1f/65TdrhscfGeoKcayH4cFx+9dVyM3z4CE/pJGLcrVtX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", + "text/plain": [ + "
" + ] + }, + "metadata": {}, + "output_type": "display_data" + } + ], + "source": [ + "from tatc.tradespace import plot_designs\n", + "\n", + "on_front = traded.index.isin(chosen.index)\n", + "fig, axes = plt.subplots(1, len(POLICIES), figsize=(16, 3.6), sharex=True, sharey=True)\n", + "for ax, policy in zip(axes, POLICIES):\n", + " mine = traded.policy == policy\n", + " # the designs with the policy, over the others in gray, and the front ringed\n", + " plot_designs(traded, \"cost p70\", \"accurate p10\", highlight=mine, front=on_front & mine, legend=None, ax=ax)\n", + " ax.set_title(f\"{policy}\\n{(on_front & mine).sum()} on the front\", fontsize=9)\n", + " ax.set(xlabel=\"Cost at 70% confidence\", ylabel=\"\")\n", + " style_axes(ax, grid=\"both\")\n", + "axes[0].set_ylabel(\"Accurately sampled (%), worst 10%\")\n", + "plt.show()" + ] + }, + { + "cell_type": "markdown", + "id": "07a354e0", + "metadata": {}, + "source": [ + "Along the front, degrading is the cheapest policy of a design, and restoring buys robustness. Two satellites in two Walker planes keep 20% of the points accurately sampled in their worst histories if they produce replacements (159 million dollars), and 26% with a spare on the ground (175 million). Six satellites in three Walker planes keep 39%, 70%, and 72% if they degrade, produce replacements, or keep a spare on the ground, for 210, 279, and 294 million. Nine satellites in three planes degrade gracefully (69% in their worst histories, for 254 million), and producing replacements raises them to 79%, for 340 million. A spare on the ground is efficient for designs of two to six satellites, but a spare in orbit is not efficient for any design. The policy that a design deserves depends on the design, which is why it is a decision of the design." + ] + }, + { + "cell_type": "markdown", + "id": "cc00b8b1", + "metadata": {}, + "source": [ + "## Find What Spreads the Results\n", + "\n", + "The replicates of a design differ by its uncertain parameters: the sample of points (`points_seed`), the histories of failures (`failure_seed`), and the growth of the cost of development (`cost_growth`). Which of them spreads an objective says what would sharpen it. The sample of points and the histories are noise of the estimates, which more points or more histories reduce; the growth of costs is a risk of the mission.\n", + "\n", + "`attribute_variance` evaluates each design again with one parameter drawn as in other replicates and the others held. The **total share** of a parameter is the share of the variance between replicates that it causes, alone or with others (near 0 if it does not matter), with its standard error (`se`). Here, for the designs and policies of the front, from 20 replicates, 20 more, and 20 with each parameter drawn as in the second 20:" + ] + }, + { + "cell_type": "code", + "execution_count": 7, + "id": "c687c0ed", + "metadata": { + "execution": { + "iopub.execute_input": "2026-11-15T04:34:04.174001Z", + "iopub.status.busy": "2026-11-15T04:34:04.173827Z", + "iopub.status.idle": "2026-11-15T04:34:04.490658Z", + "shell.execute_reply": "2026-11-15T04:34:04.490076Z" + } + }, + "outputs": [ + { + "name": "stdout", + "output_type": "stream", + "text": [ + "1900 evaluations in 0 s\n" + ] + }, + { + "data": { + "text/html": [ + "
\n", + "\n", + "\n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + "
accurate missionaccurate mission histories p10cost histories p70accurate mission seaccurate mission histories p10 secost histories p70 se
parameter
points_seed88.235.60.08.54.50.0
cost_growth0.00.078.70.00.019.0
failure_seed3.765.537.20.76.97.6
\n", + "
" + ], + "text/plain": [ + " accurate mission accurate mission histories p10 \\\n", + "parameter \n", + "points_seed 88.2 35.6 \n", + "cost_growth 0.0 0.0 \n", + "failure_seed 3.7 65.5 \n", + "\n", + " cost histories p70 accurate mission se \\\n", + "parameter \n", + "points_seed 0.0 8.5 \n", + "cost_growth 78.7 0.0 \n", + "failure_seed 37.2 0.7 \n", + "\n", + " accurate mission histories p10 se cost histories p70 se \n", + "parameter \n", + "points_seed 4.5 0.0 \n", + "cost_growth 0.0 19.0 \n", + "failure_seed 6.9 7.6 " + ] + }, + "execution_count": 7, + "metadata": {}, + "output_type": "execute_result" + } + ], + "source": [ + "import time\n", + "\n", + "from tatc.tradespace import attribute_variance\n", + "\n", + "began = time.perf_counter()\n", + "attribution = attribute_variance(failure_study, list(ROBUST.values()), chosen, sample_size=20)\n", + "print(f\"{len(attribution.results)} evaluations in {time.perf_counter() - began:.0f} s\")\n", + "attribution.summary.mul(100).round(1)" + ] + }, + { + "cell_type": "markdown", + "id": "30400392", + "metadata": {}, + "source": [ + "The total shares of each objective, with one standard error:" + ] + }, + { + "cell_type": "code", + "execution_count": 8, + "id": "608307dd", + "metadata": { + "execution": { + "iopub.execute_input": "2026-11-15T04:34:04.491869Z", + "iopub.status.busy": "2026-11-15T04:34:04.491714Z", + "iopub.status.idle": "2026-11-15T04:34:04.565050Z", + "shell.execute_reply": "2026-11-15T04:34:04.564583Z" + } + }, + "outputs": [ + { + "data": { + "image/png": "iVBORw0KGgoAAAANSUhEUgAAAysAAAGbCAYAAADEAg8AAAAAOnRFWHRTb2Z0d2FyZQBNYXRwbG90bGliIHZlcnNpb24zLjExLjIsIGh0dHBzOi8vbWF0cGxvdGxpYi5vcmcvgI3uAAAAAAlwSFlzAAAPYQAAD2EBqD+naQAAYBxJREFUeJzt3Qm8jOX///HPse+yk50siYTIWoo2koqIigrtKiJEixZaUdnKVvkqCRUttlIoWZItUklaZC37fsz/8b76zfznzJlzzpw545w55vV8POacmfu+576v+56577k+97XFeTwejwEAAABAlMmS0QkAAAAAgGAIVgAAAABEJYIVAAAAAFGJYAUAAABAVCJYAQAAABCVCFYAAAAARCWCFQAAAABRiWDl/2i4mf3797v/AAAAADIewcr/OXDggBUsWND9BwAAAJDxCFYAAAAARCWCFQAAAABRiWAFAAAAQFTK0GAlPj7ePvzwQ7vqqqusQoUK9u233wZdbsaMGXbJJZdY9erV7cYbb7RNmzaFtQwAAACAzCNDg5X+/fvbpEmTrGPHjrZ161Y7evRoomU++ugju+mmm1wAMmXKFMuRI4ddfPHFtnv37lQtAwAAACBzifNkYF+9J0+etGzZstmff/5pZcuWtYULF1rz5s0TLFOvXj2rXbu2TZw40b0+ceKElSpVyh566CEbNGhQyMukRN0Wqzewffv2WYECBSK+rwAAAAAyUcmKApXkqBvhVatW2ZVXXumblj17dmvRooV9+eWXIS8DAAAAIPNJPlrIYCpxkZIlSyaYrtdr164NeZlgjh075h7+JSty6tQp9wAAAABw+mTJkiVzByveoCGwBEYlJ2qcH+oywQwdOtQGDx6caPrOnX/bkSMHI5J+AAAAAMGVKlXGMnWwUrRoUfd/z549Caar4XyxYsVCXiaYAQMGWO/evROUrKjdTPHipWizAgBR5rXXXrMLLrjAmjVrFtH1jh071hYtWmS33367XX755RFdNwAg7aI6WClRooSVK1fOvvnmG7v22mt907/++mtr3bp1yMsEkzNnTvcIVhwVSpEUACD9rFixwooUKRLR6/MXX3xho0aNsscee8yqVKkSsXW/+uqrVqdOnRQDqxEjRlj9+vWtSZMmEdkuAJyJoj5Xfu+999r48eNt/fr1po7LRo8ebb/99pv16NEjVcsAQGYX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Fi2y7777znbs2O6mlSxZ0urVu9CaNbvY8uTJczrSCQAAACDGhBys7N+/315/fazNmDHd4uLirEaNGlakSFE3b/PmzTZ79mz3vF279nbnnXdZgQIFTl+qAQAAAJzxQg5Wrr32GmvYsJGNHDna6tata1myJKxBdurUKVfaomCmbds2tnDhV6cjvQAAAABiRMjBysSJb1qlSpWSnK/gpX79+u7x66+/Rip9AAAAAGJUyA3skwtU0rJsaqj0JhLLAAAAADjDewP7888/rWfP+6xx44bucf/999lff/0VudSZ2a5du+yWW26xwoULW86cOa18+fI2dOjQRMtpWokSJSx79uxWq1Yt++KLLyKaDgAAAACZKFjp1+8RK1++gr3zzlT3qFChgpsWSd27d7f169e79jBHjx61sWPH2pNPPmlvvvmmbxlNGzJkiE2ZMsX27dtnN9xwg11zzTW2ZcuWiKYFAAAAQJQGKy+//JILGLx++eVn69GjhwtS9NBzTYuktWvX2nXXXWcVK1a0rFmz2tVXX23Vq1d3072GDRtm3bp1s5YtW1q+fPlcMFO0aFEXxAAAAACIgWAlPj7e2re/wb79dql73aJFS7v33nttypT/uYeeX3ZZi4gmsGvXrjZt2jRbs2aN7d271z3/7bffrGPHjm7+nj177Oeff7ZLLrnE9x51razXS5f+l04AAAAAZ/igkI880s+uvrqVPfnk43buuedar169bcGC+a6KlrRu3drat78xogkcOHCgbdq0yS644AIXhKhNikpMLrroIjd/x44d7n+xYsUSvK948eK2fPnyJNd77Ngx9/AfR8bbQD8jG+kHdgkdi+gkAQAAnOn5nIzOc0aDUPK9qR7BXo3X33vvfZs0aaLdfHMn69XrYXvppZftdOnUqZNre/LTTz+5qmALFiywdu3aWa5cudw8r8APW68V3CRFDfIHDx6caPrOnX/bkSMHLSNky5bdihUrYbFuz55ddvLkiYxOBgAAQMT9888u3/8dO7bF9BEuVapM5IMV96Zs2axHjzvtiiuucO1DZs+eZY899riVKlXKIt0T2IwZM2zmzJlWpUoVN+2qq66y9u3b28iRI12w4t3mzp07E7xXr0uWLJnkugcMGGC9e/dOULJStmxZK168lBUoUMBiUq5C5qnawf3PSEWKJCwlAwAAOFPs2bPX/S9cuJiVKHF2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qE7lz2VHL63u/mekIpkkvxVWsOI/jomKbzp16uwekaZ1X3bZZbZz584E0/W6cOHC7rmqhqm9yqeffuoa1nvT9/nnn7uAJCk5c+Z0j2DbjPViwYzG8QeQ2XDdAhAqj4KVFudm+AHLkknyu2EFK23btrEaNWrYNde0sVatWlnRoqcvMlNVrUsuucRefPFFa9KkievK+O2337a33nrLt8xTTz3legg799xzrVGjRm6Mlfz589tdd9112tIFAAAA4PQKK6SaMeMDN7bK22+/ZS1aXGZ33tnDZs2a5esVLJLq1atnCxcutJUrV7pqW0uXLrWPP/7YVQXzuuKKK1zJigIZlaZoYMglS5a4BvgAgDNXkRxx1rVcdvcfAHDmifN4PJ5w36y3Koj45JOP3Wj2Gkle1baef/5Fy2zUZkXBzb59+zK8zUr717bYxm3/v6pdrDj37Fw2vWfFjE4GgDD8O+QWi/9jU8wdu6xlq1mhR/+X0ckAEKarFo6y9fu2xdTxq1nwbJtz6X2WWaSpspoattevX9+efHKwjRs3wcqVK2effPJJ5FIHAAAAIGalqeti9cD12WefumpZP/20yWrWrGX9+yfdqB0AAAAATmuwMn36+y5A+e67la6731atWtvw4cOtfPkK4awOAAAAACITrLz66it21VVXWa9eva127drhrAIAAAAAIh+sfPHFl5YtW5pqkAEAAABA5BvYE6gAAAAAON0yx9CVAAAAAGIOwQoAAACAqESwAgAAAODMClbi4+Pthx9+sLlz5/imHT58OFLpAgAAABDjwgpWduzYYZ06dbSbb+5kDz/c2ze9b98+tnjxokimDwAAAECMCitYeeGF56xKlaq2dOmyBNO7detm48a9Eam0AQAAAIhhYQ2Wsnz5cvvww1mWO3fuBNOrVatu69evj1TaAAAAAMSwsEpWjh496htrJS4uzjd9z57dlitXrsilDgAAAEDMCitYqVu3ns2cOSNBsHLs2DEbPny4NWhwUWRTCAAAACAmhVUNrE+fvnbbbV3s66+XmMfjsf79+9mKFSvs2LGjNnnylMinEgAAAEDMCStYqVKlis2c+aFNnfquZcmS1Xbv3m2tW7e2zp1vtpIlS0Y+lQAAAABiTljBipQoUcIefPChyKYGAAAAANIarMiePXts3759iaZXqlQpLasFAAAAgPCClXXr1ln//o/Y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aUwOAAAAAKRxnBVRcJIeAcqyZcvsm2++sWzZslnTpk2tTp06iZb5999/bfr06bZjxw6rVauWXXvtta6kBwAAAECMBCvbt29PcZmSJUtaJJw6dcouueQSO3nypDVq1MgOHz5sAwYMsHvvvddeeOEF33Jbt261Jk2aWMWKFe3CCy+0nj172oQJE+zDDz+0LFnCapYDAAAAILMFKy1bXpbiMuvXb7BIUMnIc8895wIRr2uuucbatGljt912m9WoUcNNe+SRR6xs2bK2cOFCV/py//33W/Xq1W3atGl20003RSQtAAAAAKI8WNEI9elFwYp/oCL169f3laYoWFGpy+zZs+2ll15ygYpUrlzZLr74Yps5cybBCgAAABArwUpGd008ZcoUy5kzp9WrV8+9/v333+3IkSN2zjnnJFiuSpUqtnTp0iTXo3Fi/MeK2b9/v6/qmR4ZhWpr/30GQGbDuRvbuG4hM+K6FdtORUF+K5TvYJoa2Kc3BR8DBw60Z555xooXL+6mHTp0yP0vUKBAgmULFizomxfM0KFDbfDgwYmm79z5tx05ctAyQrZs2a1YsRIW6/bs2WUnT57I6GQAIePcBdctZDZct7AnCvJbpUqViWywUqRIEcsoq1atslatWtk999xjffr08U3Ply+f+79v374Ey+/du9c3Lxg11O/du3eCkhW1eylevFSiwAfpq0iRYhxyAJkK1y0AmU2RTJLfSlWw8tVXiy0jfP/999ayZUvr2rWrDRs2LMG8cuXKWZ48eeynn36yK6+80jddr9XIPimqSqZHsOIoikUzFscfQGbDdQtAZpMlk/SYG/WpXL16tQtUunTpYiNGjEg0P2vWrNa2bVt7++237cSJ/4qyNm3aZIsXL7b27dtnQIoBAAAAREJUt1lRm5PLL7/c9fKlKl2DBg3yzbv++ut9jeyff/55a9asmes5TOOsaHyV6667ztq1a5eBqQcAAABwxgYrKp568MEHg85TiYqX2pqsW7fOPvjgAzeC/cSJE12VMEawBwAAADKvqA5WcufOnaA0JTn58+d3VcUAAAAAnBmivs0KAAAAgNhEsAIAAAAgKhGsAAAAAIhKBCsAAAAAohLBCgAAAICoRLACAAAAICoRrAAAAACISgQrAAAAAKISwQoAAACAqESwAgAAACAqEawAAAAAiEoEKwAAAACiEsEKAAAAgKhEsAIAAAAgKhGsAAAAAIhKBCsAAAAAohLBCgAAAICoRLACAAAAICoRrAAAAACISgQrAAAAAKISwQoAAACAqESwAgAAACAqEawAAAAAiEoEKwAAAACiEsEKAAAAgKhEsAIAAAAgKhGsAAAAAIhKBCsAAAAAohLBCgAAAICoRLACAAAAICoRrAAAAACISgQrAAAAAKISwQoAAACAqESwAgAAACAqEawAAAAAiEoEKwAAAACiEsEKAAAAgKhEsAIAAAAgKhGsAAAAAIhKBCsAAAAAohLBCgAAAICoRLACAAAAICoRrAAAAACISgQrAAAAAKISwQoAAACAqESwAgAAACAqEawAZrZr1y4bNWqk+w8AAIDoQLAC/F+wMmbMaIIVAACAKEKwAgAAACAqEawgahTNl9U8p+ItVsXyvgMAAASTLehUIAPkz53V4rJktQMTH7OT27ek67b3/3P4v/8TB9m/hfNYestWsqLlv+PpdN8uAABANCNYQdRRoBL/x6Z03Wah46esa7nsVujfrRZ/iAJHAACAaECwAphZkRxZ7PbyOTgWAAAAUYRbyAAAAACiEsEKAAAAgKhEsAIAAAAgKp0xbVZ++OEHe+ONN2zHjh1Wq1Yt69mzpxUoUCCjkwUAAAAglktWVq5cafXr17dDhw7Z5ZdfbrNmzbKmTZva0aNHMzppAAAAAGI5WBkwYIC1aNHCxo8fb926dbM5c+bY5s2bbeLEiRmdNAAAAACxGqyo9GThwoXWrl0737RChQq54OWzzz7L0LQBAAAAiOE2K3/88YfFx8db2bJlE0zX66+++irJ9x07dsw9vPbt2+f+7927106dOmUZJUuWLFY63zE7UeiExZqiOY/a/v377XDBs+3k0dja/2wFz7as+/dn6HcPaROr524sn7fCuYvMft2K1XP3RJ5CZvv3W/m4vHYyWyGLJeXj8rrrdjTkOfQdzJ8/v8XFxSW5TJzH4/FYJrZ+/XrXoP6bb76xRo0a+ab369fPZsyYYb/88kvQ9z355JM2ePDgdEwpAAAAAH8qMEiuU6xMX7JSsGBB9//ff/9NMH3Pnj2uOlhy7Vx69+7te63o8p9//rEiRYokG93hzKQ7DCqNU0kdvcgBmQfnLpA5ce7CSyUrycn0wUqZMmWscOHCtmbNGmvVqpVv+urVq6127dpJvi9nzpzu4e+ss846rWlF9FOgQrACZD6cu0DmxLmLM76BvUpBbrnlFpswYYKvdOWLL76w7777zm699daMTh4AAACAMGX6khV55plnXElKtWrVrHr16m7clccff9yaN2+e0UkDAAAAEMvBiuq6ffnll/b999+7Eexr1qyZqHcwIDmqEvjEE08kqhoIILpx7gKZE+cuQpXpewMDAAAAcGbK9G1WAAAAAJyZCFYAAAAARCWCFQAAAABRiWAFAAAAQFQiWEFMufbaa+3tt9+2M1Gk9u2mm26ycePGRSRNQCT8/PPPrlv63bt3n3EHNFL79tdff7n16D9wOmzfvt31vPr111/brl27Irru33//3RYuXBg160F0IViJUXv37nVdPF999dWWGbVq1cqmTJmS6vf9+uuv9s8//9iZKFL79ttvv9mePXsikiZE3rRp01ym9LXXXst0h/fHH390adf1JzWOHTtmmzZtspMnT9qZJlL7duLECbce/Qci6Y8//nB5hcqVK9ugQYNswIABdv7551vbtm3dvEj49NNPrUePHlGzHkSXM2KcFaTeO++8Y/v377cFCxbYihUrrH79+pkuY/7vv/9mdDKAdDdy5EiXIX3llVfs/vvvt7i4uEzzKRw9evSMDTqAM5FugDVr1szOPfdcV2pRpEgR37xPPvnElbD4j2u3efNm9zj77LPdDdFAynesW7fOcuTI4QIejbWiEhtNO3z4sH388cduuRo1alilSpUSvHfnzp22fPly9zxPnjxuIPDSpUv75oe6HmQ+lKzEqPHjx7uMTps2bdzzYFSl6Morr7R69eq5ZQPv2ic3X9M+//zzBMu3b98+QfWiFi1a2MSJE+2BBx6wunXr2mOPPeam33HHHe7uqy6OzZs3t6efftplcrxuvvlm27Jliz3zzDNuOT3i4+PdvLfeestatmzp1te5c2f74YcfkjwGzz//vFsmkKY9++yzQd+zaNEiu/766936b7zxRvv2229981JKt3efR48e7fa5cePGbrnZs2e7wUzvvvtuq1Onjis1+u677xK9b8KECfbggw9ao0aN7LLLLnM/FClJ6Xjoru6jjz7q5uvO2ZlaRe5M8dNPP7kqGDNmzLBt27a5KhmBFMTrzmfDhg3t4osvtjFjxpj/cFrJzdf6ateunWB9yqD4Vy9as2aNe71kyRJ3/VCGZOnSpa60xHs+1qpVy83zZhhE33GdO6LvsJbT99mbpn79+lmDBg2sadOm7jt58ODBoMdAadV5E1iy+vfff7tzT4MDB3vPiBEj3Psuuugie+ihh3ylhyml23+f58yZYx06dHDni6pL6tjomF1zzTVu2j333OMyY4Hv++qrr9z1QsvccsstKd6NDuV46Luga6qutZ06dbINGzYku04gHMOHD3dVFCdNmpQgUJHWrVu777ToN1i/zRdccIH77dO5pod/Kap+s8qXL+/OPz107dD1TMHN4sWLbd++fTZ27Fj30LkTaOvWrb75Tz31lDu37r33Xt/8UNeDTEiDQiK2rFq1ypM9e3bPjh07PJ999pmnQIECnkOHDiVYpl+/fp5ChQp5Xn/9dc/y5cs9o0aN8tx1110hz8+bN6/ngw8+SLDOevXqeYYOHep7Xb58eU/OnDk9Q4YM8Xz//feev//+203//fffPRs3bvRs2LDBpa9OnTqe22+/3fe+rVu3eipWrOgZNGiQW04PGThwoKdatWqeGTNmeL777jvPs88+69Lxyy+/+N573nnneYYPH+47DnFxcZ4tW7b45v/6669u2rfffpvouClduXLl8rzwwgsuvR9++KGnWbNmnv3794eUbu8+586d26Vh5cqVnl69enmyZcvmqVmzpue1115z0+6++25PyZIlPYcPH07wPn1m2sdly5Z5nn76aff6m2++CbpvoR6P7t27u2M5e/Zsz8KFCz0NGjRw6fH/nBA9HnnkEc+VV17pnnft2tVz8803J5h/8OBB9z1o2LCh59NPP/UsXrzYc88997jvQCjz9T3QOenv559/ViTjO0+WLl3qXleuXNm9T993XT9OnjzpOx/XrFnjrg36vs2dO9e978SJE+6aoPdqHVrur7/+cu+tVauWp1OnTi49S5Ys8Vx11VWeiy++2HPq1Cn33nXr1rn3ea8ROg7aB3/6zuq77H2Pv1dffdVTpkwZt386x0aOHOk7N1NKt/8+16hRw/Pxxx97vv76a0/dunU9lSpV8lxwwQW+Y6lj26NHj0TvK1WqlOe9995zy2jfqlat6jl+/HjQfQvleBw4cMCts2PHju4aMGnSJHc99v+cgEjQ73arVq1SXG706NHuO+j9fdm9e7f7nj/44IO+ZXTOPPPMM77X27Zt88yfP989HzNmjLumpMYff/zhKVq0qOeTTz7xTQtnPYh+BCsx6N577/W0b9/ePY+Pj/dUqFDB/dh5/fnnn56sWbN6pk2bluB9ymyEMj81wcott9ySYnoVVGTJksVz9OhR3zRlwpW599IPvTLZq1evTvDe66+/3vPQQw8lmaHXxfPxxx/3vX7sscdchiQYb2DnnxnS8dMj1HRrn5U59FKGJUeOHC5o8VJGRJkO/0BE7wv8wVBGpXXr1kH3LZTjoQu9PscvvvjCN18ZHU0jWIk+Or9KlCjhmT59unutDLOC53///de3zIgRIzyFCxf27N27N9F7Q5mfmmBFmfaUKKho166d77WCfL13165dvmkKHHTO+Z9HOgd0XnhvGgRm6H/66Sd3U0GBkpcyRk899VTQdCiwU2AebJ9DSbd3n7/66ivftKlTp7ppunngNX78eE+5cuUSve/tt9/2Tdu3b5+7jkyePDnovoVyPIYNG+Y5++yzfQGPvPjiiwQriDgFxcozpKRJkyYJAhPvd7lIkSK+1/Xr1/fcd9997gZBoFCDDJ0Xa9eu9cyZM8ddry666CJ3Yy6160HmQpuVGHPkyBHXXuW9995zr7NkyWLdu3d3VcFuu+02N23ZsmWuSFdFvP6yZcsW0vzUUDWHQCrKfemll1zxrapDqH77qVOnXJWLKlWqBF2PqmNpORVDy/8F4q7qiaq7JEX7/txzz9kTTzzhqzalKlrBqF1Prly5XHUpVeW49NJLE9SXDTXd/tVssmfPboUKFUowLV++fJY3b15XP9ffJZdckuC1t6pZuMdj7dq1bpqqmXhVqFDBPRB9VF3Q2+ubqBrhOeecY//73/9cNUxRlYomTZpYwYIFg56bKc1P67mr6lOqrqjqGqo3rvOgTJkyya5H1Tb+/PNPV3/d+z0VnTuq6qRqW4F0PqkevaqRvvjii65K2i+//OK7hgXStapr167u3NL5q/fmzp071en2P09LlCgRdFrgeRt47hYoUMBV91R1NV1Hwjkeeq8+R10//K8HQKSpbUgoHbeoaraqRvqrWrWqq2554MABy58/v7366qt2++23u/NE31c10Ff15KxZs4aUFlV11PVP1at1DdDvpKpU6ncNZzaClRijuu6qQ9qzZ09fw1z9OOuEV8NXNVhTOwZdPNTwLZiU5qeGf4ZBVC9bP+xqZzFkyBArVqyY+/FXGw1tN7kgTIHXu+++m+AHXHRBS4oy83369HHta5QpUL33W2+9Neiyqq+7fv16mzx5stuO2pgoYFHvTAreQk13sAtzsGn+7QxEgVLgj4j2O9zjoWWUSQ3MqGq9iD7KTOv8ULsKL/1Ia7o3WNF3LbnPL6X5aTl31QtPx44dXfCvDLUy5UrbZ599lux69D1UGxa1KQlUqlSpJN+nHn907g4dOtQFLTr3/Bv6+lN7kYoVK7pzVe0/1CuZzlPdmEhNukM5dwPP23DO3ZSOh5YJPP6ctzgdLrzwQlu1apULlvWbkhTddFNbEX96rXyC9zdHN8o2btzouuueP3++DRw40LUDDbWrfLXj0jr0G+zNv1xxxRVBzzmcWQhWYoxKUHr16mV33nlngumapnm6S+ltsK4SAm/jOX8pzRfdwQxsEBpK//+6Y6iAQRcvbyY7WGNUZRD8L1AKsnQxVSCmu6ahUsZEGRlldrQ+3YEtXrx4kssrCOndu7d7KBjRdlVSpTtIoaQ7LQIbxytw0p31YEI5Hnrv8ePH3R1pb8mPAlf1tIboonNHjbv18L/jrzuMymCrQwY1tNa5+dFHH7nvcrBewlKar/NW3wn1Nub9HusufyjUeFbnj26EeAWOxeDN2Aeeuwoi9H1MTQmPGpdrWyolfv/995PsKMQ/06WHKLOjUhjd5Q0l3ZE4d73XFZ2XukOs4CqYUI6H5s2bNy/R9QCINJ0X+g3Rb9tdd92VYJ5K71VqokBFAbZKfxWAeH344YeuBNYb5KihftGiRd3vjR66fqkRvCigSe6GpPdapJuC3muXfoNVi6BcuXK+ZUJZDzIfegOLIcqU6i5Gly5dfL3feB/q4UY9QSmToioKqhqki5S3eFWZJfViJSnNFwUxykR4uyhV9Sh1K5gSFQ/rx1zVOkTvUc9Fwe4wqtjZf3sqVtYdZu90bVslSbpgJkdVwbSMHt26dUtyublz57pMjnccA11oFbSpSk2o6U4L9X6kbqZF3TMqc5ZUf/KhHA9VX9EPie5WKYOqDKT60D906FCirnKDVflB+nnzzTddBlUZXP/zVj3v6HNWSYD3u6xqh6rW6O0hT3cw1RtVKPPPO+8816Wot6ct3RlNqqphIJ0DuoHhvbuqzLQCeX8lS5Z0//3PXWWAlInRDRN9D0XVsNQ7YHLj/ai0QiWj+o4rzdddd12Sy77wwgvu7rCXvuO646tHKOlOq8cff9xl6ry9KykY8lbRDBTK8VDPg0qzrkei9QX7nNSz4JNPPhnRfUFsUXVDjemkUkgF+Lo2qMRe3yv15qXfIu93XCUmuvmn8+e+++6z6dOnu143vXT9Ug+Amq/gZ9SoUa73PdG1TD0cqqqYqmUGu2mm7/PLL7/s3qtrnmo2BJaqhLIeZD4EKzFEJ7e6DdTJHEgXDP0QeuvFz5w501V70l1cPVQ/3r/dRUrzVUKj4l7dTdRDJSbKXKVEJRTKSF111VXubonWqYtlIF3wtD+q2uEt6VFGXF2X6rXSpLs9ukOZVOmPlwIvradw4cLJDpKpzL3GpdFyWl79t+vifcMNN4Sc7rTQnWT9EKj/egWMeq1MS1JCOR7KBOtz0j6p1EgDQmq/Au8KB1Y5QfrRj7FK/pLKjGu6fvxVNUjfO53Dykyo1FDnnn7cdbdeUpqv74CqH6kLXlWp0vfaWxqREmVm9H59P3UzQaW3qpPuT/OVGVeApW3qPNZAcyox0o0UpUnfVW1X37nAtjWBFKyr9FAZ/+SqpSrY1nb1PVf61O25Ml0KckJJd1rp+qjjqe1o22ob523zEiiU46HPUXek9TlpPZqvbuT96eaJ2hcmtR0gVAo8VHKn9oyzZs1ypZEq9dMNPHV/Lvp+64aAllGQIvr+qcTF65tvvnE3XfR+dXc+ePBgdyNBVL116tSptnLlSnv99deDdjms5VVyo99hnR96rSDev91YKOtBJpTRLfyRftTlr3rySoq6HNy5c2eCaeo1SL1GJSWl+drekSNH3PPffvvNs2fPngTbC+yVyEtdrG7evNm919u16LFjxxIso9fqocjbdbGXuv5UF8T+PeV4afo///yTaLq6GVZ3zKHQdrUv/r18hZruYPus3pbUQ5C/TZs2uR6A/HsDGzdunHuuXoOC7UNS+5bc8RD1bqb98XZfHfg5qXtWdU+NjOH9HgV+R7zUxbXme88z/3PPv6ewQMnN13dW57W+G/reaP3e74+2o9fBugiW7du3+64J+j7quxdI54C+4+q62J+uP8GuUUqPthnYi5DWoZ8x9TIWCqVH3aUGS3ty6Q62zzpfAq89Ov+VpsDewHQuK+3BrhtJ7Vtyx8P/s9d1XT0kBX5O2va5556bbK9nAJAZxOlPRgdMQEZS43qViKianEqeopHuVqmKlqrxpCddHlRlhxGAEY1UsqKOQXSXNRqpPr3uLKsKmNoDpSdVa1M1MpXmAEBmRgN7xCz9kKvIWN2Vqjg5WgOVjKSGjAQqiDYffPCBGwFbQYCqhCCxlKrQAUBmQckKYpZKDTRugXonUfubaKYxXJROMiDAf6UG6glI9eQDuwWOJuqEQ+3A1D4nWO9rAICUEawAAAAAiEr0BgYAAICooR4+1e2wd/wgjU3k7f47Keo6Wd1848xDsIJMTf2pq+tRdTmsroNDoa4M1d+7uvaMpFDWq2pnWiZwLJP0kJHbBiJNbVXUZfHll19uX375ZUjveeWVV+ypp56KeFpCWe8bb7wR8bGXQpWR20b49FuizHqwh6pBBtLwA6oy7B3fLJDG49m/f3/QeQoGvGOIZTTtg7rwvuyyy+ymm25y09Tlvnc8qKRoCAaN74YzD8EKMjUNcKmR4tXYtl27donmawwRZdBVd9xLd17UA1ikg5VQ1qsfCi0Tyo9CsLSnRWq2jTPHmDFjXE9yKdFAps8++6zL/GuA2GD+/vtv69OnjxvxXeOWeAeE8/+Oab7GA/KO2RQ4XoPGXkgrDUJ7zTXXWL169dygphpPKJT91jm1du1ai7RQ1qubBRpvKpKfWahSs21ED43Ersy6/0PjKqljmP/973++5Q4fPuzG+9JYQRrTR/8Dzz+NyaO2Uxq3R4M8+tP4W5qvsVOigQaL1Dmt9l7ekhUNWKtxhxCbouObCYRJGR8NcBc4IJp/Q1xl0JO605Te9GOhEcND6cY00mlPzbZx5lDXvuqWOzn6nmmA01tuucUNAhps1Od//vnHGjZs6DINt99+uxvpXa81uNv555/vltEgpcrwXHvtte5Ggko/FFCIBq788ccf7aKLLkrzPq1evdptp3fv3mna7/Sk4C7UUs1Ipz0120b00ECg3sy6f0ZeN+c6derkm6YbBAqWf//9dzcIqAZa7NChg/seaZBiDZCoHvTUDb1uOGig186dO7uOZXSTTQG/BngMtRMIXQt0Y0I9aAZ7z59//ul629TgyYHzFdiXLl3aBR5aLn/+/Ak6jlFgrVIezfffdw2kGthjp24Map80mGuePHmSTO/u3bvt4MGD7lhkyZIlVelJzX4ntx2kUUYP9ILTb/Xq1Z4WLVq4gdMeeughT5s2bTyPPPKIG5htzZo1nh49erhpzz33XKIBxDTo2PDhwz3XXXed56abbvKMHTvWDUDmtWvXLrduPa666irPvffe67YXbPsa/LBXr16etm3buu0nN2Cd7N692zNo0CBP69atPZ07d/Z89NFHCQZX1Drj4uI8F1xwgXu+cOHCBO/XgHP169d3g7I1b97cLTN06FC3nKb99NNPyaYnpX0PFMp6NWCc0qHB47zeeecdt3/t2rXzDBs2zA0Sl1TaUzou/sdb27rzzjs9V155pWfdunVBtx3KPgZLH1KmQQVbtmzpG8xRAwpec8017rPz/87ceOONvtfLli3zdOvWzXP11Vd77r//fnfO+BsxYoRn8ODBnpkzZ3o6dOjg6dSpk28Qw6eeesp9jnfccYdnzpw5bvr//vc/T9myZT1Fixb1nafffvttorTqO+odTLBy5cqeJ554ItEymlayZMkEgxpefPHFbpuiQQ2zZcvmBl2U++67zzNgwADfd1YDm+q8DUVyx2H8+PGeWrVquW159ylQUvt91113ue/xrFmz3HHS8wkTJiR6v9Kpa6XOMZ1DX3/9dbLpDWW9r7/+uqd///6+1+F8ZuF+PwK3Hco+JpU+ZCwNYOw957wDlubNm9fz2muv+abpXNT35+mnn3avNaCwfo+8qlat6lmyZIl7rs/22WefDWnbGjRV17QcOXJ4ypUr56lQoYLnq6++8s1fv369Ozfz58/vtq/v8YIFCxKso2DBgi7PoeuB3p89e3bPPffc45t/xRVXeAoUKOApVKiQ57zzzvM99Fs/e/Zs33Lfffede/9ZZ53lKVKkiPv9UprGjBnjW0a/ozp/tD4tq22PGjUqVekJZb9D2Q7ShmAlBngz0VWqVPG88cYbnqlTp3oqVqzoufDCC90Ix/pRnTJliqd06dKegQMH+t6nTGnjxo3dxUPvUaZVgYEyrl7KuMyfP989Pv74Y5c5yZkzp2fVqlWJtl+tWjV3IZk+fbqnXr16nssuuyzJNGu9uqA2a9bM895777lAKleuXL4LkUaE1jazZMniMvF6rhGo/Skj/uqrr7pt6yKnZXQxDSU9oex7Usc5ufWuWLHCLeMNYBQcFC9e3GUmPvjgA0/fvn3dhTOptKd0XPzToZHnR44c6Zk3b54LTAO3Hco+JpU+pEwZBv146bwQ3SzQD2GxYsV8I6E/+OCDvkzEokWL3HwFuvru6MdXP3oa9dw/U5wvXz4XwE6bNs2zePFiN12vL730Uve+yZMnuwzoJ5984tmyZYvnhhtu8Fx00UW+81Q3GJKTVLDSqFEjz+23355gmgJdZZS0PwrK9P3yBjNah25eSJcuXTzPP/98SF+blI6DMuiPP/642653nwIltd/e46fv/Pvvv+/OD73W99s/E1S4cGF3o0E3Al588UW3/Q8//DDJNIey3ocfftjdOPBK7WeWlu9H4LZD2cek0oeMo99VnWP+n4OuK5q2fPnyBMsqoPUGNQqA/YP6s88+263riy++8Jx//vnuRoVuKCR3A1E3sbTs5Zdf7ltu69atnokTJ/qudzVr1vR07NjRd+NDAbK+Z/7r1ffsnHPO8fz+++++fcqaNavnyy+/9C2jYF/fZX/KV3iDFW2revXq7nqkdOmh3yUdB+9voa5JdevWdUG99wbbypUr3fnhH2iklJ6U9jvU7SBtCFZigDfzqguTl4IWTfvmm29803TXXMGL1+jRo13G27+0RXcQdIdjw4YNSW6ve/fuCTI13u3732HRdjVtz549QdfxyiuvuLslhw4d8k17+eWX3YVPd5K8dFH57LPPkkzL0qVL3XYU3KQmPeHseyjrDQwYdGF/4IEHEqxn//79SaY9lOPiTUdgiUvgtkPZx+TSh5Qpw6CMojdjr0yoPj+VdEnt2rXd9KSCgQYNGrg7n176AdcdS//PXz/cCtr9z2X/z0kBkTKaoUoqWClVqpTnscceSzBNGXN9p3bu3OnLBH3++efuuTJH3mBZd4MVzCjzooyIMtJJCeU4aLvKZCQn2H7r+JUpUyZB6ZC+38qI+JcW+d+08V4b9VklJZT1+gcM4Xxm4X4/Arcdyj6mlD5kDJVW6numz8dLvzc6Bzdv3pxg2VtuucXTtGlT33VdpR067/R7odIB3cDS9V+ldTovVUKhmytDhgwJum2d19qOSoyDUeZe87UtL50P+m3yD9p13up3zJ+CHJUKhhqs6DdOv1Pe6463JFD5AW+wovToO6zAfOPGje437YcffnDnpAL+UNMTyn6Hsh2kDW1WYoh/XXE1slOdy/r16yeYpka2/vXYVT9TDVn/L7B1j6xZs7o6pd5GrWo3oga5qi975MgR1yhODfwCNWrUyPe8QoUK7r+2V7hw4UTLap3qCcS/HqrqwT/88MOuLnfNmjXTfDySS0+o+57a9QZq0qSJDR482C2nHs2qV6/u6swmJTXH5eKLL052/0PZx9SmDwk1b97cNV4V9Vilxus6xnquetJqoK5l1E3nd9995+qeB/ZuM3Xq1ATT1AbE//PX56W2I/oO6HHJJZe4AUQj/TmpDrrq0PvzpkPz5Pnnn7f27du7a4nqbKuhfdOmTV27MtWzV53vjh07uob2JUuWtGbNmiVYX2qOQ7jq1KljOXPm9L3Wd3vhwoW+Bs1ff/21q3euev7ec0J10VW3Xc+Tqtef3HoDpfYzS8v3I1Ao+5he3ymETh2tqN2Xer/U5+PlbRTvPQf9P+fs2bO75/o9Vi9ZL774ovtuzJo1y4YOHequ6WqrMXbsWPf7oXZNNWrUcO3NdH3yp/YvasuhdijB6P2FChVK8Nuv86Fq1aqJ2l8F5g/y5s2bYrfEgb2FFStWzD28Aret77KuQdqXQOqgINT0pLTfqdkOwkewEkNy5Mjhe64fXJ1g/r1/aJp/T1bKyCrzG/gDqcZ43kyxMrzqGUg/aC1atHAXvilTpiTqJSjY9iWpnrP27t3rGs358zZ607xISC49oex7OOsN1LNnT/ejoB+S5557zmUGhw8fbtdff32aj0tKDelD2cfUpg8JKRBRl7HKpC9evNiGDBniMp7KxCpDr89OjdOVSVBmI7C3G80P5XOdM2eOjR492kaOHGm33nqr6xFowoQJiRqkpoUyA9qPwK5S5ayzznL/1UBfwbS6FNd+Pfroo9a2bVuXgZ4+fbrLcFepUsU1Bn7//fcTBSvq1SjU4xAu//Mz8Lqnz0GfjwIu/xs5aV1vMKn5zFJzXFI670Pdx/T4TiF0M2fOdJ2uqBMLf2XLlnX/1XBeN5O89LpSpUq+1wpM9PB2UKHzUd3tq9cwnZ9qbK+HOmJRw/bAYCVXrlwuYEoqYFcGXzcrg313NS+SFHAltS3/81F5HPWC5w3awpHSfkdqO0gewQqSpDsJ6ulH3ecmRXeN1WWiujz18u9SMVy6yOpC6k93OLzpClW4PXKEsu+RouOnhy6Gysxq7Aj9KAVLe6SOS2r2Man0cWFOmTIByjwqw6cbA7prqd7dNCaHghWVfulz1h1r3bn2joXj/9mG8rnq/Qoy9dBn06pVK9f17eTJkyPWK80FF1xgq1atSjBNrxV8+GdGdJdSDwUmuoOrjJH2WXfyvaWLyhQpoAm2H2k5Dv7C2W8FXXooyDjd535qPrNIHpdQ9zG59CH9KVBUr5fqaSrwN0EB5KeffmqXXnqp7yaCSuG7deuWaD0KVHv06OG6L9Z5qxtQOje9VKIQrGROwapKa9Sj5BVXXOGbrq7w9Vug64Pmf/PNN25Zbxfj6gFQpY6RpG0pnbrGeHsb1A0Q780TUa0Ape2jjz5ygbk/Bf6BNxeSktJ+R2o7SB59qyFJ3bt3d9WBXn75Zd80ZTqU8fJ2g6mLnf8gVCtWrIjIoEwqUlVVBXWPKrpYPP300+7HNfCOT3K8xcT+1dsite+RMG7cOF/adNdGP0QKCpJKe6SOS6j7mFz6kDJV19CP2YgRI1wpi3/VAGX6vNOka9eu9uqrr7rqON6MqJZRl8LJ0Z11VePwnoO6265SEP/vUWq//8EoHYsWLXKZEVG1T92YCJY+pUUZInWzqoyPAjUFNfruikqZFLgFE+5xCBTOfitIuPPOO23YsGEJxk1RYDVx4kSLlHA+s0gdl1D2MaX0IX2pe16VxuqcCkY3P/TdUEmYllP1y3POOSdB98Zeuhapapa3lEWlm6rKpHNZ4/soMPUGAP5U4qIusPUbpO+JbnSpWln//v3dfJXqqARO83WTQt2Wa+wzBSqqrhhJqqKsfdSNMwVpKgVUV8z+NUWU3vvvv98dM/2mKXhTaZLGqVEpVahS2u9IbQfJo2QFSVIVAVXp0omouzCqY67ARBdAb91s1UPXHQWNNqsfWGVgdCdCF7y0blvVjlTdSBdB/ZDqbqwugqmhu45qJ6A72LrA6bnqYkdi3yNBwZ7aEulOp+7AqG6vMni6YxMs7bpARuK4hLqPyaUPoVFA8tlnn/kCEwV9+kw17oF/sPLEE0+46pPKZCgzofFONAicxjRJjoIBZTpVPVABgTK5+vy8g8Lpbp9+XJVp0HdFpaCBY53s2LHD/fCLvlNqg7ZkyRKrXbu2L5hVdU99/1TdU4GGMsvK8PTt2zdRmvQeBWX6znqpjrwy1gp4dcfxzTffDLo/4R6HQMH2OxQK/nX90jHSOaa7pgreta5ICeczi9RxCWUfU0of0pcy/vrdSirTr4y0qivp5pIy1Lq2q51Y4G+VxlTRZ6gqmF4q7fzwww9dqblurmh+Um2eFMzoO6m2M/q+qC2T2jR6afv6Dqntmr5Tus4NHDgwQfUpXTsCxzFR/qF48eK+17pGKDj2Fzgo5KRJk9w5oYdKcp955hm37/5tQxXANWjQwB0LXW+0HZU2+R/HUNKT0n6Hsh2kTZxa2adxHYhyukCpuFSZDO9FQ8Wlqk6k+uVeO3fudHdYdCL600VHP1wqPtaJHVgnWnf39SOqu3Cqp75r1y6X+dHJm9T2lVnRXVo1Rk+uPqvqyOtHWRcTtaMIrB7xxRdfuAyVftCToq+4ShCUJg2Y5a2iEkp6Utr3lI5z4HpVdK07L8qkeu8C6bgpfVpWGQf/bQSmXRfslI5LsHRIsG2Hso/JpQ8p051wVYXS3UrvD7CCQt0t1fkX+J3++eefXX1z/eAFlpapSoU+r2ANN5X51OekwFKfk/9nr2oemqd2SqpCoSpF/lQnW8FJIKU38C6rMq5Ko9LmXyfen0pQ9L0MzAToe6wbGrpOpBT0J3cckrpWBQrcb30Wgcfvjz/+cNVVAm9i6BqpbejaouDAv1FzoGCfS+B6tT/K6CgdafnMwvl+BNt2KPuYXPoAIL0QrAAAAACISrRZAQAAABCVCFYAAAAARCWCFQAAAABRiWAFAAAAQFQiWAEAAAAQlQhWAAAAAEQlghUAAAAAUYlgBQAAAEBUIlgBAAAAEJUIVgAAAABEJYIVAAAAAFGJYAUAAABAVCJYAQAAAGDR6P8BTjUmqvG3KAQAAAAASUVORK5CYII=", + "text/plain": [ + "
" + ] + }, + "metadata": {}, + "output_type": "display_data" + } + ], + "source": [ + "PARAMETERS = {\n", + " \"points_seed\": \"sample of points\",\n", + " \"failure_seed\": \"histories of failures\",\n", + " \"cost_growth\": \"growth of costs\",\n", + "}\n", + "LABELS = {\n", + " \"accurate mission\": \"Accurately sampled,\\nmean of the histories\",\n", + " \"accurate mission histories p10\": \"Accurately sampled,\\nworst 10% of the histories\",\n", + " \"cost histories p70\": \"Cost at\\n70% confidence\",\n", + "}\n", + "from tatc.tradespace import plot_shares\n", + "\n", + "shares = attribution.summary.mul(100).loc[list(PARAMETERS)]\n", + "# a group of bars of each column, one of each parameter, with error bars of their standard errors\n", + "ax = plot_shares(shares, list(LABELS), groups=\"metrics\", names=PARAMETERS, labels=LABELS, legend=\"upper center\")\n", + "ax.set(ylabel=\"Total share of the variance (%)\", ylim=(0, None))\n", + "plt.show()" + ] + }, + { + "cell_type": "markdown", + "id": "da3c8d4e", + "metadata": {}, + "source": [ + "The sample of points spreads the mean shares accurately sampled (88% of their variance between replicates), and the failures hardly do (4%), as each replicate averages 20 histories. The share in the worst 10% of the histories is spread mostly by the failures (66%, and 36% by the points), as a quantile of 20 histories is a noisy estimate. Both are noise of the estimates, with different remedies: more points would sharpen the means, and more histories the worst 10%, which is cheap.\n", + "\n", + "The cost at 70% confidence is spread by the growth of the cost of development (79%), a risk of the mission, and by the failures (37%), which cost replacements and spares. These shares are the least certain, with standard errors of 19 and 8 points. The total shares of each objective sum to about 100% within their errors, so the parameters hardly interact." + ] + }, + { + "cell_type": "markdown", + "id": "5bc51596", + "metadata": {}, + "source": [ + "The order of designs on the front depends on their differences, in which the parameters that act alike on two designs cancel. `differences` attributes the variance of the differences between pairs of designs from the same evaluations: here, between the designs and policies adjacent along the front, by cost:" + ] + }, + { + "cell_type": "code", + "execution_count": 9, + "id": "d53fe0cc", + "metadata": { + "execution": { + "iopub.execute_input": "2026-11-15T04:34:04.566350Z", + "iopub.status.busy": "2026-11-15T04:34:04.566189Z", + "iopub.status.idle": "2026-11-15T04:34:04.766270Z", + "shell.execute_reply": "2026-11-15T04:34:04.765745Z" + } + }, + "outputs": [ + { + "data": { + "text/html": [ + "
\n", + "\n", + "\n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + "
accurate missionaccurate mission histories p10cost histories p70accurate mission seaccurate mission histories p10 secost histories p70 se
parameter
points_seed95.642.50.09.77.20.0
cost_growth0.00.00.00.00.00.0
failure_seed2.572.7105.90.58.64.4
\n", + "
" + ], + "text/plain": [ + " accurate mission accurate mission histories p10 \\\n", + "parameter \n", + "points_seed 95.6 42.5 \n", + "cost_growth 0.0 0.0 \n", + "failure_seed 2.5 72.7 \n", + "\n", + " cost histories p70 accurate mission se \\\n", + "parameter \n", + "points_seed 0.0 9.7 \n", + "cost_growth 0.0 0.0 \n", + "failure_seed 105.9 0.5 \n", + "\n", + " accurate mission histories p10 se cost histories p70 se \n", + "parameter \n", + "points_seed 7.2 0.0 \n", + "cost_growth 0.0 0.0 \n", + "failure_seed 8.6 4.4 " + ] + }, + "execution_count": 9, + "metadata": {}, + "output_type": "execute_result" + } + ], + "source": [ + "ordered = chosen.sort_values(\"cost p70\").index\n", + "attribution.differences(list(zip(ordered, ordered[1:]))).summary.mul(100).round(1)" + ] + }, + { + "cell_type": "markdown", + "id": "a7a0fb65", + "metadata": {}, + "source": [ + "The growth of the cost of development cancels in every difference. All of these designs fly the same imager, whose development grows alike for each, so the growth is a risk of each mission but not a reason to prefer one design to another; the failures alone spread the differences of their costs. The shares differ by what spreads them: the sample of points for the means (96%), and mostly the histories for the worst 10% (73%). More points would settle the order of neighbors by their means, and more histories their order by the worst 10% and by cost." + ] + }, + { + "cell_type": "markdown", + "id": "f78af606", + "metadata": {}, + "source": [ + "## Summary\n", + "\n", + "* A `FailureModel` draws the failures of satellites and launches, and a `RestorationPolicy` restores them (by producing new satellites, or by spares in orbit or on the ground) or not. `Failures` simulate histories of each replicate's mission, for both the cost and the capability of each policy.\n", + "* The policy is a decision of each design (`policy_space`), which the front chooses with the design.\n", + "* `attribute_variance` finds the uncertain parameters that spread the replicates of each design, which says what would sharpen each objective, and `Attribution.differences` those that spread the differences between designs.\n", + "\n", + "This is the last notebook of the tutorial." + ] + }, + { + "cell_type": "markdown", + "id": "ae99eb83", + "metadata": {}, + "source": [ + "## Notes\n", + "\n", + "* Simulating failures is cheap, but evaluating each phase's satellites is not, and most phases repeat the same sets of satellites. The histories of a replicate are therefore evaluated together, with a cache that evaluates each set of satellites once (`evaluate_histories`, `PhaseCache`).\n", + "* The histories are stratified: each satellite's life and each launch is drawn from its own stratum of its distribution, which estimates means several times more precisely than independent histories (`Deployment.simulate_many`).\n", + "* Without restoration (degrading), satellites fail independently, so the mean share over the failures is computed exactly, from the probability that each set of satellites operates (`exact_expectations`); its worst 10% and its cost still come from the histories.\n", + "* A design life does not retire a satellite, and a replacement whose launch fails is not flown again (see `DeploymentSchedule`)." + ] + } + ], + "metadata": { + "kernelspec": { + "display_name": "Python 3 (ipykernel)", + "language": "python", + "name": "python3" + }, + "language_info": { + "codemirror_mode": { + "name": "ipython", + "version": 3 + }, + "file_extension": ".py", + "mimetype": "text/x-python", + "name": "python", + "nbconvert_exporter": "python", + "pygments_lexer": "ipython3", + "version": "3.14.10" + } + }, + "nbformat": 4, + "nbformat_minor": 5 +} diff --git a/docs/examples/tradespace/RankUncertainDesigns.ipynb b/docs/examples/tradespace/RankUncertainDesigns.ipynb new file mode 100644 index 0000000..96b6439 --- /dev/null +++ b/docs/examples/tradespace/RankUncertainDesigns.ipynb @@ -0,0 +1,1486 @@ +{ + "cells": [ + { + "cell_type": "markdown", + "id": "51020379", + "metadata": {}, + "source": [ + "# Rank Uncertain Designs\n", + "\n", + "Each design's share of points sampled is a mean over five replicates, each of its own sample of points. The means are uncertain, and so is the front of the means: a design just behind another might be ahead with other samples. This notebook ranks designs with that uncertainty.\n", + "\n", + "It covers:\n", + "\n", + "* the **probability** that each design is efficient;\n", + "* **refining**: adding replicates only where they change the ranking;\n", + "* **confirming** the chosen designs with new replicates;\n", + "* judging designs by **statistics other than the mean**, with **requirements**.\n", + "\n", + "It imports the design space and study of `EvaluateTradeSpace` from `trade_space_example.py`, beside the notebooks (with the study's results from its store, if that notebook was run). The objectives are the same: fewer satellites, fewer planes, and more points sufficiently sampled." + ] + }, + { + "cell_type": "code", + "execution_count": 1, + "id": "cc653395", + "metadata": { + "execution": { + "iopub.execute_input": "2026-11-15T04:33:23.769368Z", + "iopub.status.busy": "2026-11-15T04:33:23.769164Z", + "iopub.status.idle": "2026-11-15T04:33:26.588267Z", + "shell.execute_reply": "2026-11-15T04:33:26.587582Z" + } + }, + "outputs": [ + { + "name": "stdout", + "output_type": "stream", + "text": [ + "5480 evaluations: 1096 designs x 5 replicates\n" + ] + } + ], + "source": [ + "from trade_space_example import OBJECTIVES, designs, study\n", + "\n", + "results = study.run(designs)\n", + "print(f\"{len(results)} evaluations: {len(designs)} designs x {study.replicates} replicates\")" + ] + }, + { + "cell_type": "markdown", + "id": "a83bcd9c", + "metadata": {}, + "source": [ + "## Estimate the Probability of Efficiency\n", + "\n", + "`pareto_probability` estimates the probability that each design is efficient by a bootstrap: it resamples the five replicates many times, and counts how often each design is on the front of the resampled means. It resamples the same replicates for every design, as the designs share their samples of points." + ] + }, + { + "cell_type": "code", + "execution_count": 2, + "id": "4aef9718", + "metadata": { + "execution": { + "iopub.execute_input": "2026-11-15T04:33:26.589701Z", + "iopub.status.busy": "2026-11-15T04:33:26.589494Z", + "iopub.status.idle": "2026-11-15T04:33:27.738671Z", + "shell.execute_reply": "2026-11-15T04:33:27.737770Z" + } + }, + "outputs": [ + { + "data": { + "text/html": [ + "
\n", + "\n", + "\n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + "
descriptionsatellitesplanessufficientparetopareto_probability
1017800 km, 60 deg FOR, Walker 75 deg: 1 x 1 (spac...1.01.02.8False0.38
776700 km, 60 deg FOR, SSO: 1 at 12:001.01.03.0False0.20
1048800 km, 60 deg FOR, SSO: 1 at 09:001.01.03.0False0.12
1050800 km, 60 deg FOR, SSO: 1 at 12:001.01.03.0False0.10
1052800 km, 60 deg FOR, SSO: 1 at 15:001.01.03.0False0.12
1054800 km, 60 deg FOR, SSO: 1 at 18:001.01.03.2True0.54
960800 km, 60 deg FOR, Walker 45 deg: 1 x 2 (spac...2.01.016.6True0.98
963800 km, 60 deg FOR, Walker 45 deg: 2 x 1 (spac...2.02.030.2True1.00
961800 km, 60 deg FOR, Walker 45 deg: 1 x 3 (spac...3.01.038.0True1.00
972800 km, 60 deg FOR, Walker 45 deg: 3 x 1 (spac...3.03.037.6False0.32
971800 km, 60 deg FOR, Walker 45 deg: 3 x 1 (spac...3.03.037.8False0.29
962800 km, 60 deg FOR, Walker 45 deg: 1 x 4 (spac...4.01.068.2True1.00
965800 km, 60 deg FOR, Walker 45 deg: 2 x 2 (spac...4.02.069.6True0.92
1026800 km, 60 deg FOR, Walker 75 deg: 2 x 3 (spac...6.02.097.6False0.32
1025800 km, 60 deg FOR, Walker 75 deg: 2 x 3 (spac...6.02.097.8True1.00
\n", + "
" + ], + "text/plain": [ + " description satellites planes \\\n", + "1017 800 km, 60 deg FOR, Walker 75 deg: 1 x 1 (spac... 1.0 1.0 \n", + "776 700 km, 60 deg FOR, SSO: 1 at 12:00 1.0 1.0 \n", + "1048 800 km, 60 deg FOR, SSO: 1 at 09:00 1.0 1.0 \n", + "1050 800 km, 60 deg FOR, SSO: 1 at 12:00 1.0 1.0 \n", + "1052 800 km, 60 deg FOR, SSO: 1 at 15:00 1.0 1.0 \n", + "1054 800 km, 60 deg FOR, SSO: 1 at 18:00 1.0 1.0 \n", + "960 800 km, 60 deg FOR, Walker 45 deg: 1 x 2 (spac... 2.0 1.0 \n", + "963 800 km, 60 deg FOR, Walker 45 deg: 2 x 1 (spac... 2.0 2.0 \n", + "961 800 km, 60 deg FOR, Walker 45 deg: 1 x 3 (spac... 3.0 1.0 \n", + "972 800 km, 60 deg FOR, Walker 45 deg: 3 x 1 (spac... 3.0 3.0 \n", + "971 800 km, 60 deg FOR, Walker 45 deg: 3 x 1 (spac... 3.0 3.0 \n", + "962 800 km, 60 deg FOR, Walker 45 deg: 1 x 4 (spac... 4.0 1.0 \n", + "965 800 km, 60 deg FOR, Walker 45 deg: 2 x 2 (spac... 4.0 2.0 \n", + "1026 800 km, 60 deg FOR, Walker 75 deg: 2 x 3 (spac... 6.0 2.0 \n", + "1025 800 km, 60 deg FOR, Walker 75 deg: 2 x 3 (spac... 6.0 2.0 \n", + "\n", + " sufficient pareto pareto_probability \n", + "1017 2.8 False 0.38 \n", + "776 3.0 False 0.20 \n", + "1048 3.0 False 0.12 \n", + "1050 3.0 False 0.10 \n", + "1052 3.0 False 0.12 \n", + "1054 3.2 True 0.54 \n", + "960 16.6 True 0.98 \n", + "963 30.2 True 1.00 \n", + "961 38.0 True 1.00 \n", + "972 37.6 False 0.32 \n", + "971 37.8 False 0.29 \n", + "962 68.2 True 1.00 \n", + "965 69.6 True 0.92 \n", + "1026 97.6 False 0.32 \n", + "1025 97.8 True 1.00 " + ] + }, + "execution_count": 2, + "metadata": {}, + "output_type": "execute_result" + } + ], + "source": [ + "from tatc.tradespace import pareto_probability\n", + "\n", + "probability = pareto_probability(results, OBJECTIVES, n_resamples=1000)\n", + "candidates = probability[probability.pareto_probability >= 0.1].sort_values([\"satellites\", \"planes\", \"sufficient\"])\n", + "candidates[[\"description\", \"satellites\", \"planes\", \"sufficient\", \"pareto\", \"pareto_probability\"]].round(2)" + ] + }, + { + "cell_type": "markdown", + "id": "03afabef", + "metadata": {}, + "source": [ + "The single satellites show why: the means of their five replicates are within a few tenths of a percentage point of each other, and their 95% confidence intervals (two standard errors either side) overlap." + ] + }, + { + "cell_type": "code", + "execution_count": 3, + "id": "19cf5721", + "metadata": { + "execution": { + "iopub.execute_input": "2026-11-15T04:33:27.740851Z", + "iopub.status.busy": "2026-11-15T04:33:27.740534Z", + "iopub.status.idle": "2026-11-15T04:33:28.244008Z", + "shell.execute_reply": "2026-11-15T04:33:28.243354Z" + } + }, + "outputs": [ + { + "data": { + "image/png": "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", + "text/plain": [ + "
" + ] + }, + "metadata": {}, + "output_type": "display_data" + } + ], + "source": [ + "import matplotlib.pyplot as plt\n", + "\n", + "from tatc.tradespace import COLORS, GRAY, INK, style_axes, use_style\n", + "\n", + "use_style() # the style of the plots of trade studies\n", + "\n", + "single = candidates[candidates.satellites == 1].sort_values(\"sufficient\")\n", + "fig, ax = plt.subplots(figsize=(8, 3))\n", + "rows = range(len(single))\n", + "ax.errorbar(single.sufficient, rows, xerr=2 * single[\"sufficient se\"], fmt=\"o\", color=COLORS[0], ms=6, lw=2, capsize=0)\n", + "for k, row in enumerate(single.itertuples()):\n", + " ax.annotate(\n", + " f\"efficient in {row.pareto_probability:.0%}\",\n", + " (row.sufficient, k),\n", + " xytext=(0, 8),\n", + " textcoords=\"offset points\",\n", + " ha=\"center\",\n", + " fontsize=8,\n", + " color=INK,\n", + " )\n", + "ax.set_yticks(rows, single.description.str.replace(\", 60 deg FOR\", \"\"))\n", + "ax.set(xlabel=\"Points sufficiently sampled (%): mean and 95% interval\", ylim=(-0.6, len(single) - 0.3))\n", + "style_axes(ax, grid=\"x\")\n", + "plt.show()" + ] + }, + { + "cell_type": "markdown", + "id": "cfd847c6", + "metadata": {}, + "source": [ + "Four of the seven efficient designs are efficient in every resample, and two more nearly so: two satellites in one plane (98%) and four in two planes (92%). The single satellite is not settled. One crossing the equator at 18:00 is efficient in 54% of the resamples, one in a Walker orbit inclined 75 degrees in 38%, and others in 10 to 20%. Likewise, three satellites in three planes (29% and 32%) sample about as many points as three in one plane, and six satellites in two planes with another phasing (32%) as many as the efficient design. Given five replicates, these designs are equally good candidates." + ] + }, + { + "cell_type": "markdown", + "id": "c0c4e63c", + "metadata": {}, + "source": [ + "## Refine Uncertain Designs\n", + "\n", + "More replicates of every design would settle the front, at the cost of evaluating every design again for each. `refine` adds replicates only to the designs whose efficiency is uncertain (efficient in more than 5% and fewer than 95% of the resamples), five at a time, until none is uncertain or a design has 40 replicates.\n", + "\n", + "Some differences are too small to matter, and too small to settle: a tenth of a percentage point between designs that sample nearly every point. A **tolerance** treats the designs within it of the front as efficient. Here, differences of less than 1 percentage point do not matter. The tolerance is part of the `Criteria` by which designs are judged. `refine` also stops refining a design once its share is known to within half the tolerance (a standard error of 0.5 points): the design is then **indifferent**." + ] + }, + { + "cell_type": "code", + "execution_count": 4, + "id": "104737eb", + "metadata": { + "execution": { + "iopub.execute_input": "2026-11-15T04:33:28.245498Z", + "iopub.status.busy": "2026-11-15T04:33:28.245214Z", + "iopub.status.idle": "2026-11-15T04:33:41.571948Z", + "shell.execute_reply": "2026-11-15T04:33:41.571317Z" + } + }, + "outputs": [ + { + "name": "stdout", + "output_type": "stream", + "text": [ + "215 evaluations added, 0.6% of those of 40 replicates of every design\n" + ] + }, + { + "data": { + "text/html": [ + "
\n", + "\n", + "\n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + "
rounduncertainindifferentrefinedevaluations
0031130150
111610630
221311210
331311210
44131215
55131215
66141315
77131200
\n", + "
" + ], + "text/plain": [ + " round uncertain indifferent refined evaluations\n", + "0 0 31 1 30 150\n", + "1 1 16 10 6 30\n", + "2 2 13 11 2 10\n", + "3 3 13 11 2 10\n", + "4 4 13 12 1 5\n", + "5 5 13 12 1 5\n", + "6 6 14 13 1 5\n", + "7 7 13 12 0 0" + ] + }, + "execution_count": 4, + "metadata": {}, + "output_type": "execute_result" + } + ], + "source": [ + "from tatc.tradespace import Criteria, refine\n", + "\n", + "CRITERIA = Criteria(OBJECTIVES, tolerances={\"sufficient\": 1.0}) # percentage points that do not matter\n", + "refinement = refine(study, CRITERIA, results, step=5, max_replicates=40, n_resamples=1000)\n", + "added = refinement.evaluations\n", + "print(f\"{added} evaluations added, {added / (len(designs) * 35):.1%} of those of 40 replicates of every design\")\n", + "refinement.rounds" + ] + }, + { + "cell_type": "code", + "execution_count": 5, + "id": "355e4987", + "metadata": { + "execution": { + "iopub.execute_input": "2026-11-15T04:33:41.573221Z", + "iopub.status.busy": "2026-11-15T04:33:41.573061Z", + "iopub.status.idle": "2026-11-15T04:33:41.579685Z", + "shell.execute_reply": "2026-11-15T04:33:41.579251Z" + } + }, + "outputs": [ + { + "name": "stdout", + "output_type": "stream", + "text": [ + "39 designs are efficient within the tolerance; the designs refined:\n" + ] + }, + { + "data": { + "text/html": [ + "
\n", + "\n", + "\n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + "
descriptionsatellitesplanessufficientreplicatesparetopareto_probabilityindifferent
224500 km, 60 deg FOR, SSO: 1 at 06:001.01.01.4010False0.01False
226500 km, 60 deg FOR, SSO: 1 at 09:001.01.01.4010False0.01False
228500 km, 60 deg FOR, SSO: 1 at 12:001.01.01.6010False0.02False
743700 km, 60 deg FOR, Walker 75 deg: 1 x 1 (spac...1.01.01.6010False0.04False
232500 km, 60 deg FOR, SSO: 1 at 18:001.01.01.7010False0.03False
500600 km, 60 deg FOR, SSO: 1 at 09:001.01.01.8010False0.12True
230500 km, 60 deg FOR, SSO: 1 at 15:001.01.01.9010False0.14True
498600 km, 60 deg FOR, SSO: 1 at 06:001.01.01.9010False0.19True
504600 km, 60 deg FOR, SSO: 1 at 15:001.01.02.1010False0.18True
502600 km, 60 deg FOR, SSO: 1 at 12:001.01.02.2010True0.40True
506600 km, 60 deg FOR, SSO: 1 at 18:001.01.02.2010True0.32True
1017800 km, 60 deg FOR, Walker 75 deg: 1 x 1 (spac...1.01.02.4010True0.57True
774700 km, 60 deg FOR, SSO: 1 at 09:001.01.02.5010True0.76True
780700 km, 60 deg FOR, SSO: 1 at 18:001.01.02.5010True0.79True
778700 km, 60 deg FOR, SSO: 1 at 15:001.01.02.5315True0.70True
776700 km, 60 deg FOR, SSO: 1 at 12:001.01.02.8010True0.95False
772700 km, 60 deg FOR, SSO: 1 at 06:001.01.02.9010True0.98False
1052800 km, 60 deg FOR, SSO: 1 at 15:001.01.02.9010True0.98False
1046800 km, 60 deg FOR, SSO: 1 at 06:001.01.03.1010True0.98False
1054800 km, 60 deg FOR, SSO: 1 at 18:001.01.03.1010True0.99False
1048800 km, 60 deg FOR, SSO: 1 at 09:001.01.03.2010True0.99False
1050800 km, 60 deg FOR, SSO: 1 at 12:001.01.03.2010True0.99False
686700 km, 60 deg FOR, Walker 45 deg: 1 x 2 (spac...2.01.013.3010False0.01False
1030800 km, 60 deg FOR, Walker 75 deg: 3 x 1 (spac...3.03.034.7010False0.03False
698700 km, 60 deg FOR, Walker 45 deg: 3 x 1 (spac...3.03.034.9010False0.01False
1001800 km, 60 deg FOR, Walker 60 deg: 3 x 1 (spac...3.03.035.2715False0.02False
972800 km, 60 deg FOR, Walker 45 deg: 3 x 1 (spac...3.03.037.0240False0.19False
971800 km, 60 deg FOR, Walker 45 deg: 3 x 1 (spac...3.03.038.4825True0.89True
966800 km, 60 deg FOR, Walker 45 deg: 2 x 2 (spac...4.02.067.6010False0.02False
981800 km, 60 deg FOR, Walker 45 deg: 4 x 1 (spac...4.04.065.9010False0.00False
980800 km, 60 deg FOR, Walker 45 deg: 4 x 1 (spac...4.04.067.1315False0.02False
\n", + "
" + ], + "text/plain": [ + " description satellites planes \\\n", + "224 500 km, 60 deg FOR, SSO: 1 at 06:00 1.0 1.0 \n", + "226 500 km, 60 deg FOR, SSO: 1 at 09:00 1.0 1.0 \n", + "228 500 km, 60 deg FOR, SSO: 1 at 12:00 1.0 1.0 \n", + "743 700 km, 60 deg FOR, Walker 75 deg: 1 x 1 (spac... 1.0 1.0 \n", + "232 500 km, 60 deg FOR, SSO: 1 at 18:00 1.0 1.0 \n", + "500 600 km, 60 deg FOR, SSO: 1 at 09:00 1.0 1.0 \n", + "230 500 km, 60 deg FOR, SSO: 1 at 15:00 1.0 1.0 \n", + "498 600 km, 60 deg FOR, SSO: 1 at 06:00 1.0 1.0 \n", + "504 600 km, 60 deg FOR, SSO: 1 at 15:00 1.0 1.0 \n", + "502 600 km, 60 deg FOR, SSO: 1 at 12:00 1.0 1.0 \n", + "506 600 km, 60 deg FOR, SSO: 1 at 18:00 1.0 1.0 \n", + "1017 800 km, 60 deg FOR, Walker 75 deg: 1 x 1 (spac... 1.0 1.0 \n", + "774 700 km, 60 deg FOR, SSO: 1 at 09:00 1.0 1.0 \n", + "780 700 km, 60 deg FOR, SSO: 1 at 18:00 1.0 1.0 \n", + "778 700 km, 60 deg FOR, SSO: 1 at 15:00 1.0 1.0 \n", + "776 700 km, 60 deg FOR, SSO: 1 at 12:00 1.0 1.0 \n", + "772 700 km, 60 deg FOR, SSO: 1 at 06:00 1.0 1.0 \n", + "1052 800 km, 60 deg FOR, SSO: 1 at 15:00 1.0 1.0 \n", + "1046 800 km, 60 deg FOR, SSO: 1 at 06:00 1.0 1.0 \n", + "1054 800 km, 60 deg FOR, SSO: 1 at 18:00 1.0 1.0 \n", + "1048 800 km, 60 deg FOR, SSO: 1 at 09:00 1.0 1.0 \n", + "1050 800 km, 60 deg FOR, SSO: 1 at 12:00 1.0 1.0 \n", + "686 700 km, 60 deg FOR, Walker 45 deg: 1 x 2 (spac... 2.0 1.0 \n", + "1030 800 km, 60 deg FOR, Walker 75 deg: 3 x 1 (spac... 3.0 3.0 \n", + "698 700 km, 60 deg FOR, Walker 45 deg: 3 x 1 (spac... 3.0 3.0 \n", + "1001 800 km, 60 deg FOR, Walker 60 deg: 3 x 1 (spac... 3.0 3.0 \n", + "972 800 km, 60 deg FOR, Walker 45 deg: 3 x 1 (spac... 3.0 3.0 \n", + "971 800 km, 60 deg FOR, Walker 45 deg: 3 x 1 (spac... 3.0 3.0 \n", + "966 800 km, 60 deg FOR, Walker 45 deg: 2 x 2 (spac... 4.0 2.0 \n", + "981 800 km, 60 deg FOR, Walker 45 deg: 4 x 1 (spac... 4.0 4.0 \n", + "980 800 km, 60 deg FOR, Walker 45 deg: 4 x 1 (spac... 4.0 4.0 \n", + "\n", + " sufficient replicates pareto pareto_probability indifferent \n", + "224 1.40 10 False 0.01 False \n", + "226 1.40 10 False 0.01 False \n", + "228 1.60 10 False 0.02 False \n", + "743 1.60 10 False 0.04 False \n", + "232 1.70 10 False 0.03 False \n", + "500 1.80 10 False 0.12 True \n", + "230 1.90 10 False 0.14 True \n", + "498 1.90 10 False 0.19 True \n", + "504 2.10 10 False 0.18 True \n", + "502 2.20 10 True 0.40 True \n", + "506 2.20 10 True 0.32 True \n", + "1017 2.40 10 True 0.57 True \n", + "774 2.50 10 True 0.76 True \n", + "780 2.50 10 True 0.79 True \n", + "778 2.53 15 True 0.70 True \n", + "776 2.80 10 True 0.95 False \n", + "772 2.90 10 True 0.98 False \n", + "1052 2.90 10 True 0.98 False \n", + "1046 3.10 10 True 0.98 False \n", + "1054 3.10 10 True 0.99 False \n", + "1048 3.20 10 True 0.99 False \n", + "1050 3.20 10 True 0.99 False \n", + "686 13.30 10 False 0.01 False \n", + "1030 34.70 10 False 0.03 False \n", + "698 34.90 10 False 0.01 False \n", + "1001 35.27 15 False 0.02 False \n", + "972 37.02 40 False 0.19 False \n", + "971 38.48 25 True 0.89 True \n", + "966 67.60 10 False 0.02 False \n", + "981 65.90 10 False 0.00 False \n", + "980 67.13 15 False 0.02 False " + ] + }, + "execution_count": 5, + "metadata": {}, + "output_type": "execute_result" + } + ], + "source": [ + "refined = refinement.summary\n", + "print(f\"{refined.pareto.sum()} designs are efficient within the tolerance; the designs refined:\")\n", + "refined[refined.replicates > 5].sort_values([\"satellites\", \"planes\", \"sufficient\"])[\n", + " [\"description\", \"satellites\", \"planes\", \"sufficient\", \"replicates\", \"pareto\", \"pareto_probability\", \"indifferent\"]\n", + "].round(2)" + ] + }, + { + "cell_type": "markdown", + "id": "5801af83", + "metadata": {}, + "source": [ + "Refinement adds 215 evaluations, 0.6% of those that 40 replicates of every design would take, to 31 designs. One round of five replicates settles most of them, as efficient or not, and a few take more. With the tolerance, 39 designs are efficient candidates, among them every design of six to nine satellites that samples about 98% of the points: they differ by less than matters.\n", + "\n", + "The single satellites that refinement leaves indifferent sample 1.8 to 2.5% of the points, about one tolerance below the best (3.2%). More replicates would settle only whether they fall within the tolerance, which does not change the trade, so refinement stops once their shares are known to within half the tolerance. Three satellites in three planes vary more between replicates: one design is indifferent after 25 replicates, and another remains uncertain at 40." + ] + }, + { + "cell_type": "markdown", + "id": "853c9fb7", + "metadata": {}, + "source": [ + "## Confirm the Front\n", + "\n", + "The efficient designs were chosen for their means, and so in part for luck: among a thousand designs, those that look best are likely to have drawn favorable samples of points. `confirm` evaluates the chosen designs (by default, the front of the results it is given) with new replicates, which played no part in choosing them. The difference between the means of the replicates that chose a design and those of the new ones is the **optimism** of the choice." + ] + }, + { + "cell_type": "code", + "execution_count": 6, + "id": "807da56f", + "metadata": { + "execution": { + "iopub.execute_input": "2026-11-15T04:33:41.580774Z", + "iopub.status.busy": "2026-11-15T04:33:41.580611Z", + "iopub.status.idle": "2026-11-15T04:33:41.671547Z", + "shell.execute_reply": "2026-11-15T04:33:41.670833Z" + } + }, + "outputs": [ + { + "name": "stdout", + "output_type": "stream", + "text": [ + "39 designs confirmed, of which 35 are efficient by the new replicates\n", + "mean optimism: -0.02 percentage points\n", + "mean optimism by number of satellites: {1.0: -0.39, 2.0: 0.85, 3.0: 2.09, 4.0: 2.45, 6.0: -0.18, 8.0: -0.34, 9.0: -0.34}\n" + ] + }, + { + "data": { + "text/html": [ + "
\n", + "\n", + "\n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + "
descriptionsatellitesplanessufficient selectedsufficientsufficient optimismpareto
17800 km, 60 deg FOR, Walker 45 deg: 1 x 2 (spac...2.01.016.6016.150.45True
20800 km, 60 deg FOR, Walker 45 deg: 2 x 1 (spac...2.02.030.2028.951.25True
18800 km, 60 deg FOR, Walker 45 deg: 1 x 3 (spac...3.01.038.0036.701.30True
22800 km, 60 deg FOR, Walker 45 deg: 3 x 1 (spac...3.03.038.4835.602.88False
19800 km, 60 deg FOR, Walker 45 deg: 1 x 4 (spac...4.01.068.2066.501.70True
21800 km, 60 deg FOR, Walker 45 deg: 2 x 2 (spac...4.02.069.6066.403.20True
\n", + "
" + ], + "text/plain": [ + " description satellites planes \\\n", + "17 800 km, 60 deg FOR, Walker 45 deg: 1 x 2 (spac... 2.0 1.0 \n", + "20 800 km, 60 deg FOR, Walker 45 deg: 2 x 1 (spac... 2.0 2.0 \n", + "18 800 km, 60 deg FOR, Walker 45 deg: 1 x 3 (spac... 3.0 1.0 \n", + "22 800 km, 60 deg FOR, Walker 45 deg: 3 x 1 (spac... 3.0 3.0 \n", + "19 800 km, 60 deg FOR, Walker 45 deg: 1 x 4 (spac... 4.0 1.0 \n", + "21 800 km, 60 deg FOR, Walker 45 deg: 2 x 2 (spac... 4.0 2.0 \n", + "\n", + " sufficient selected sufficient sufficient optimism pareto \n", + "17 16.60 16.15 0.45 True \n", + "20 30.20 28.95 1.25 True \n", + "18 38.00 36.70 1.30 True \n", + "22 38.48 35.60 2.88 False \n", + "19 68.20 66.50 1.70 True \n", + "21 69.60 66.40 3.20 True " + ] + }, + "execution_count": 6, + "metadata": {}, + "output_type": "execute_result" + } + ], + "source": [ + "from tatc.tradespace import confirm\n", + "\n", + "confirmation = confirm(study, CRITERIA, refinement.results, replicates=20) # 20 new replicates of the front\n", + "confirmed = confirmation.summary\n", + "print(f\"{len(confirmed)} designs confirmed, of which {confirmed.pareto.sum()} are efficient by the new replicates\")\n", + "print(f\"mean optimism: {confirmation.optimism['sufficient']:.2f} percentage points\")\n", + "print(\n", + " \"mean optimism by number of satellites:\",\n", + " confirmed.groupby(\"satellites\")[\"sufficient optimism\"].mean().round(2).to_dict(),\n", + ")\n", + "# the middle of the front: two to four satellites\n", + "confirmed[confirmed.satellites.between(2, 4)].sort_values([\"satellites\", \"planes\"])[\n", + " [\"description\", \"satellites\", \"planes\", \"sufficient selected\", \"sufficient\", \"sufficient optimism\", \"pareto\"]\n", + "].round(2)" + ] + }, + { + "cell_type": "markdown", + "id": "a37460f8", + "metadata": {}, + "source": [ + "The optimism of every confirmed design, by its number of satellites (designs that are no longer efficient by the new replicates are hollow):" + ] + }, + { + "cell_type": "code", + "execution_count": 7, + "id": "99289e48", + "metadata": { + "execution": { + "iopub.execute_input": "2026-11-15T04:33:41.672900Z", + "iopub.status.busy": "2026-11-15T04:33:41.672729Z", + "iopub.status.idle": "2026-11-15T04:33:41.745212Z", + "shell.execute_reply": "2026-11-15T04:33:41.744748Z" + } + }, + "outputs": [ + { + "data": { + "image/png": "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", + "text/plain": [ + "
" + ] + }, + "metadata": {}, + "output_type": "display_data" + } + ], + "source": [ + "import numpy as np\n", + "\n", + "positions = {n: k for k, n in enumerate(sorted(confirmed.satellites.unique()))}\n", + "x = confirmed.satellites.map(positions).to_numpy() + np.random.default_rng(0).uniform(-0.15, 0.15, len(confirmed))\n", + "still = confirmed.pareto.to_numpy(dtype=bool)\n", + "optimism = confirmed[\"sufficient optimism\"].to_numpy()\n", + "fig, ax = plt.subplots(figsize=(7.5, 3.6))\n", + "ax.axhline(0, color=GRAY, lw=1, ls=\"--\")\n", + "ax.scatter(x[still], optimism[still], s=32, color=COLORS[0], lw=0, label=\"efficient by the new replicates\")\n", + "ax.scatter(\n", + " x[~still], optimism[~still], s=32, facecolor=\"none\", edgecolor=COLORS[0], lw=1.5, label=\"no longer efficient\"\n", + ")\n", + "ax.set_xticks(list(positions.values()), [f\"{n:.0f}\" for n in positions])\n", + "ax.set(xlabel=\"Satellites\", ylabel=\"Optimism (percentage points)\")\n", + "ax.legend(loc=\"upper right\")\n", + "plt.show()" + ] + }, + { + "cell_type": "markdown", + "id": "f37149ff", + "metadata": {}, + "source": [ + "The designs of two to four satellites sample up to 3.2 points fewer with the new replicates (2.5 points on average for four satellites): four satellites in two planes sample 66.4% rather than 69.6%. The three satellites in three planes, which refinement left as good as three in one plane, sample 35.6% and are no longer efficient.\n", + "\n", + "The single satellites and the designs of six to nine satellites sample slightly more with the new replicates instead (by 0.2 to 0.4 points on average): the new samples of points happen to be easier to sample. The designs share their samples, so this difference applies to every design alike, and is not optimism. The mean optimism over all the designs (-0.02 points) mixes the two, so compare designs one by one. 35 of the 39 designs remain efficient: the shape of the front holds, but its middle is up to 3 points less good than it looked." + ] + }, + { + "cell_type": "markdown", + "id": "6e83a018", + "metadata": {}, + "source": [ + "## Require Reliable Sampling\n", + "\n", + "A mean does not say how reliably a design performs, as its share differs between samples of points. Other statistics over the replicates judge designs by their reliability:\n", + "\n", + "* `Quantile(\"sufficient\", 0.2)`: the share that a design exceeds in 80% of the samples;\n", + "* `Probability(\"sufficient\", \">=\", 50)`: the share of the samples in which a design samples at least half of the points sufficiently.\n", + "\n", + "A `Requirement` on a statistic rules out the designs that do not meet it. Here, the objective is the 0.2 quantile, and a design must sample half of the points sufficiently in at least 80% of the samples. The `Criteria` hold the objectives, the statistics that they name, and the requirements." + ] + }, + { + "cell_type": "code", + "execution_count": 8, + "id": "419f7f85", + "metadata": { + "execution": { + "iopub.execute_input": "2026-11-15T04:33:41.746646Z", + "iopub.status.busy": "2026-11-15T04:33:41.746465Z", + "iopub.status.idle": "2026-11-15T04:33:42.854613Z", + "shell.execute_reply": "2026-11-15T04:33:42.854193Z" + } + }, + "outputs": [ + { + "name": "stdout", + "output_type": "stream", + "text": [ + "209 of 1096 designs meet the requirement\n" + ] + }, + { + "data": { + "text/html": [ + "
\n", + "\n", + "\n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + "
descriptionsatellitesplanessufficient p20reliabilityreplicatespareto_probability
962800 km, 60 deg FOR, Walker 45 deg: 1 x 4 (spac...4.01.065.01.051.00
965800 km, 60 deg FOR, Walker 45 deg: 2 x 2 (spac...4.02.068.01.050.94
1025800 km, 60 deg FOR, Walker 75 deg: 2 x 3 (spac...6.02.097.81.051.00
1026800 km, 60 deg FOR, Walker 75 deg: 2 x 3 (spac...6.02.097.01.050.50
\n", + "
" + ], + "text/plain": [ + " description satellites planes \\\n", + "962 800 km, 60 deg FOR, Walker 45 deg: 1 x 4 (spac... 4.0 1.0 \n", + "965 800 km, 60 deg FOR, Walker 45 deg: 2 x 2 (spac... 4.0 2.0 \n", + "1025 800 km, 60 deg FOR, Walker 75 deg: 2 x 3 (spac... 6.0 2.0 \n", + "1026 800 km, 60 deg FOR, Walker 75 deg: 2 x 3 (spac... 6.0 2.0 \n", + "\n", + " sufficient p20 reliability replicates pareto_probability \n", + "962 65.0 1.0 5 1.00 \n", + "965 68.0 1.0 5 0.94 \n", + "1025 97.8 1.0 5 1.00 \n", + "1026 97.0 1.0 5 0.50 " + ] + }, + "execution_count": 8, + "metadata": {}, + "output_type": "execute_result" + } + ], + "source": [ + "from tatc.tradespace import Probability, Quantile, Requirement\n", + "\n", + "RELIABLE = Criteria(\n", + " {\"satellites\": \"min\", \"planes\": \"min\", \"sufficient p20\": \"max\"},\n", + " statistics={\n", + " \"sufficient p20\": Quantile(\"sufficient\", 0.2),\n", + " \"reliability\": Probability(\"sufficient\", \">=\", 50),\n", + " },\n", + " requirements=[Requirement(\"reliability\", \">=\", 0.8)],\n", + ")\n", + "reliable = pareto_probability(refinement.results, RELIABLE, n_resamples=1000)\n", + "print(f\"{reliable.meets_requirements.sum()} of {len(reliable)} designs meet the requirement\")\n", + "reliable[reliable.pareto_probability >= 0.1].sort_values([\"satellites\", \"planes\"])[\n", + " [\"description\", \"satellites\", \"planes\", \"sufficient p20\", \"reliability\", \"replicates\", \"pareto_probability\"]\n", + "].round(2)" + ] + }, + { + "cell_type": "markdown", + "id": "da1a6745", + "metadata": {}, + "source": [ + "The replicates of these designs, and of the most reliable design of three satellites, against the threshold of half of the points (dashed): a design meets the requirement if at least 80% of its replicates lie right of the threshold, and its objective is the share that 80% of them exceed (its 0.2 quantile, the tick)." + ] + }, + { + "cell_type": "code", + "execution_count": 9, + "id": "da41d282", + "metadata": { + "execution": { + "iopub.execute_input": "2026-11-15T04:33:42.856153Z", + "iopub.status.busy": "2026-11-15T04:33:42.855969Z", + "iopub.status.idle": "2026-11-15T04:33:42.943777Z", + "shell.execute_reply": "2026-11-15T04:33:42.943175Z" + } + }, + "outputs": [ + { + "data": { + "image/png": "iVBORw0KGgoAAAANSUhEUgAAAysAAAFLCAYAAADWPBMvAAAAOnRFWHRTb2Z0d2FyZQBNYXRwbG90bGliIHZlcnNpb24zLjExLjIsIGh0dHBzOi8vbWF0cGxvdGxpYi5vcmcvgI3uAAAAAAlwSFlzAAAPYQAAD2EBqD+naQAAgHdJREFUeJztnQeUFEXXhi8557AICEoUQQRRUQRJKgYkKCZUEHPAHDBnMUf0M4sEFQFFETGBiWACwYBEQZC05Jyh//MUf489szO7s8suM7v7PucMvdNT011dVT3ct+691QU8z/NMCCGEEEIIIZKMgomugBBCCCGEEEJEQ2JFCCGEEEIIkZRIrAghhBBCCCGSEokVIYQQQgghRFIisSKEEEIIIYRISiRWhBBCCCGEEEmJxIoQQgghhBAiKZFYEULkenhc1IYNG9xWCCGEEHkHiRUhRK5n48aNVq5cOVu/fn2iq5Jv2bNnjy1btththdo/s2zatMkmTZrgtrkRjX+1f35mTw7//kusCCGEECKhbN68ySZPnui2QggRRGJFCCGEEEIIkZRIrAghhBAioZQqVdpatWrttkIIEaRw2DshhBBCiP1M6dKl7bjj2qjdhRBpkGdFCCGEEAll+/bttmDBfLcVQoggEitCCCGESCjr1q21kSPfd1shhAgisSKEEEIIIYRISiRWhBBCCCGEEEmJxIoQQgghhBAiKZFYEUKIXMqdd95pc+fOTXQ1hNhnChUqZOXLl3dbIYQIIrEihBC5lK+//tpWr16dLcKlX79+Nn/+/GysnRDxU7lyFbvssqvcVgghgkisCCFEHuDEE0+0SpUqZfn748ePtzVr1mRrnYQQQoh9RQ+FFEKICBau2mETZm+yFRt3WdUyha1Nw9JWu3LRbGmnt99+24W7zJs3z/766y976623bM+ePTZw4ECbNGmS++zKK6+0Bg0auPK33nqrdevWzUaPHm0bN250nzVt2jTNcb/66iurWbOmVaxY0R2P80ycONE2bNhgXbp0sV69etkjjzxi06ZNs+LFi1uzZs3s6quvtpIlS9qwYcOcVwXvSoUKFezhhx92549VJyGymxUrVtjw4e/a2Wf3tKpVq6qBhRAh5FkRQogIoTJo4mqbt2K7bdi62215z/7sYPr06XbVVVe5h98hIuDyyy+3H374wTp27GjVqlVzXhKMN1+E8PnBBx/sjLj27dvbsmXL0g0Ju/jii+21116z1q1b27nnnmvNmzd3+9u2beven3rqqU60XHfddW7/YYcd5kRKp06d3OdVqlRJt05CZDeet8e2bt3qtkIIEUSeFSGECIBHZY8X3iS8nzhnk9WuXDFb2urss8+2u+66y/29bt06GzJkiJ1++uk2atQot2/37t32/fffW48ePdz7e++918455xz397///us8ITfeeGPUYxPKNXz4cFu6dKnziASpUaOGjR071hYsWGCbNm1yXhNo3LixEysdOnSwI488Mq46CSGEEPsDiRUhhAhA6Fc0UjdE358V8JL4LF++3EqVKuU8Gj78fdRRR4Xe16pVK/R37dq1bdWqVTGPjfejcuXKaYTKrl277Pjjj7eePXta586dbdu2bc5zEo146iSEEELsDyRWhBAiADkqhH9FklI2Z34u69Sp43JMCPFCTESDULBjjz3WlSMR/oorrkhXCJHb8vPPP9vRRx8dJkB27Nhhjz76qBUsWNAGDx4c9j3yWAhNi7dOQgghxP5AYkUIIQKQTD9/5fawULCCBcxaNyidI+1UtGhRe/PNN6179+4u6Z1wLHjxxRddrgiMGzfO5aSsXLnSfU4YWSyKFStmL7/8sp188skupKts2bIuN+bCCy90QuaII45wq4Zt2bIl7HutWrWySy65xJo0aeIS7DOqkxDZSYUKFa1nzwvdVgghghTwPC8iOlsIIXIXrHhVrlw5W7t2bZrwp6xAMj05KoR+4VFBqGTXamC//fabC7GqV69emlwTkt65BjjllFNcOcQCq3LxU02eCR6WIkWKuDLffPONHX744W4FsODfkJqa6o7Hdxo2bOiS6PGcTJgwwbUVogQRRF4KcPzJkyc7D0y7du2coIlVp2jgiUlNXWopKdWd50bsX9T+iUXtr/bPz+zJ4d9/iRUhRK4nu8VKMoFYYRlitsmMjDW1/76wceMG++WXn+2oo462MmXKWm5D41/tn5/Zk8NiRWFgQgiRxDz11FNhCflC5EUIS5w69Rdr3LhJrhQrQuQFBg1623njS5cubb17X2TJgsSKEEIkMSeccEKiqyCEECIfMHjwIBdCnJKSklRiRYHFQgghhBBCiKREnhUhhMhF7nAhhBAiP5FrPCszZ850T27OK/zzzz82Z86c0Pu///7bvfISrC70448/OoNPhLN582b7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7Morr3FbIYTYp5yVn376yT744ANbsWKFVa9e3Rk4TZs2DSuzZMkSe/XVV53hU79+fbv66qutYsWKmS4T5JtvvnEG1XnnnWf7i08//dQ+/PBDe/PNN8P2X3LJJe7aH3roodC+devW2ZVXXmm33nqrtWjRIsNjT5061RYvXmw333xzqF1ZtvGaa66xnGT27Nl23333Rf3spptusqOPPtr9fe2119rKlSvDPj/99NPt/PPjXwd/9+7d9v7779sNN9xg9erVs/0N9R86dKjNmDHDqlSpYmeeeaYdeeSR2XqO7du327vvvuv6r1ixYtamTRvr3r27FSpUKOZ39uzZY1dddZXdcccdlixwHfTV7bffbrVr187x83311Vfu3mLMd+rUyXr06BH6rEKFCk6oPP7443b//ffneF2EEImH38wyZcomuhpCiNzuWRkyZIgdd9xxbh30du3a2Zo1a+yII46wzz//PFRm0aJFbt+0adPsmGOOsXHjxjkDkbKZKZMMlC1b1t566y2bM2dOmLH/zjvvOK8IBp7Pd99954y9GjVqWDJTqVIl69atW9irQIECNnLkSCfAfD755BMrV65cWLnGjRtbbgHxgPD6999/7dhjj3VeHsYuAjm7QHQ0b97cnYvxe8ABB9h1113nBHx60LarVq0KM9CTYazjuTzooINy/FwvvviidenSxSXsMVFx+eWX2y233BJWBrH83HPP2ebNm3O8PkKIxLNu3Vr7+ONRbiuEEFn2rGC4n3POOfbkk0+694RqYMgPGjTITj75ZLfvwQcfdEbbRx995GZKKMOs+rPPPhvyRMRTJp5Z8379+tmJJ57ovC2EiR188MFWpEgRmzhxou3YscN69+5tLVu2dCICQYTxfcUVV1iDBg3iOgffLVmypPPq+N/h77Zt29r8+fNdKA9/+/sbNWpk1apVs1GjRrlzAudEmF188cWubvHCUnFcH8fs27ev2/fxxx+HhCF169WrlxUsWDDUHhh4tB/npl8wAlu3bh123MqVK6cxphFe9F/NmjXD9h911FEZGt5Btm3b5kLZ/vzzT6tbt65dcMEFUculdx2wZcsWd5y//vrLHYd+xGP18MMPx+2h4Xt4VOg/nxIlStjdd9/txkA0EGzUC2O6ePHibt8XX3zhxOmAAQNcXwZB5H399deuz30OOeQQ51nB81i1atWo53njjTfs7LPPDrvmn3/+2fXbhg0b3HjBe1e0aNFQv3LP0G6zZs1yggJRFKwPHi88WdxPeEa4Tw8//PCoQolrZMKha9euzqsBCG/uR4Rd+fLlQ+elzUePHm0zZ85044Pz4vnIal8xrvEoPfbYY3b99deH+or2wKvIPQyMW5ZKpE84phAib8Nv0Jw5s+yYY45NdFWEyJcsXLXDJszeZCs27rKqZQpbm4albfP2Pe6z1A07rV3/OXb+sRXssvZVktuzUqdOHTdT7T9hFkGwbNmyMKNk7NixdsYZZ4TCYDAQCR8ipCozZdKD0DGMGeqBkeOLBYydwYMH22GHHeaMKEJyMMiGDx/uPDhLly61Vq1a2fr16+M6D8Yis/Ec24e/8SohUiL3d+jQwf3dsGHDkDcCg/H1118Pibl4WL16tXXs2NH++ecfZ7QCwgPxgmhq1qxZaHbahxlojF3qxvVxvgMPPDDDc/3+++82ZcoUu+yyy9J8NmLECCck77nnHucFywjq89prr7kwOMJ4aLtIMroOOO2001zoHcdBAGFAc214I3ww3oM5P5EgyoJCBTDiEQOEHkWDNvv222/ttttuc++XL19uF154oROMkULFFytBoQL0GcZ8mTJlop6Dc3OOYNt8//33bjxxHzA+EQZnnXVWWL8ylgkbxIODqKB88DoY54y3U045xf2nz3EQUkEYSxj+iCjuESYHCGELhoGRLxI8L+MQ4YKoRLgxxvEoZaavgnCtCBb/+oB7H3H42WefhZWljb788suoxxFCCCFE9gmVQRNX27wV223D1t1u22/4Ytu0bffeAp7Zui277aXxq+z1b8JTBPYLXiZYv36916dPH++QQw7xunXr5tWpU8e76aabvG3btrnPt2zZgorxBg4cGPa9/v37e+XKlYu7TDQ6duzo9evXz5sxY4ZXo0YN7+abb/b27NkT9vkRRxwR2rd7925XrlWrVqEyO3fu9CpUqOANGzYs7mumXikpKaH3VatW9SZPnuwNHjzYO/74492+VatWeQUKFPBGjhwZs91KlizpvudzzTXXeF27dg297927t3f++ed7//77r9eoUSOvZ8+err7w9ddfe2XKlPFWrlwZKr9u3TqvbNmy3rhx49z7BQsWuHZ97LHHvMxw3XXXeQcccEDoXD7NmjVzbfz66697l156qVekSBHvlVdeiXmczz//3CtcuLC3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3ukVL17cmzFjRqbKRNKxY0evX79+7u9//vnHO+igg7wLL7zQ2717d5rPfY477jjvvvvuC9t3+OGHe08++WTo/ZAhQ7DWvFWrVsU897vvvuvqy2vhwoWh/V988YVXokQJ9/1ff/017Bxnnnmm9/fff3s//vijd+SRR7oyAwYMCJW55pprvK5du4be9+7d2zv//PPd39SFY3Tq1MnbunWrt23bNq958+Zu3/jx4931c+7TTz/d++2339x3FixY4M4xd+5cLzMsW7bMfe+zzz4L7fvkk0+8K664wps0aZI717Bhw7yqVat6Z511VszjUMdatWp555xzjjdz5kzvm2++8WrXru2O/cMPP4TKZHQdXG+NGjW8nj17erNmzfK+++47r27dumHHgbZt24a1X7TratCggXf88cd7S5Ys8VauXBl6+WMmEtr9gAMOCI0Z6leuXDnv+eefz7ZzwAsvvODawefGG2/0+vfv702fPt2dk/uB827cuDHUr1WqVHH9Qv9effXVXtmyZUNjdtSoUW4c8jnln3nmGTdWK1WqFDoH7dqkSRN3T9CvHIf74LXXXnOfU2fOM23atHTHU7Fixdx5MtNXkfTp08fdvxMmTPCmTp3q2qJDhw5hZbh3uAZ+Z+Jh/fr17rxr166Nq7zIfhjzS5f+m+7YFzlHbm//1atXeUOGvO22uZFkbf8OHdp5jRs3ctu8TLK2f35hdw63f6bECsbJww8/7LVo0cKrWbOm17JlS++5557zdu3aFVYOY+aYY47xqlev7oxKjJhI4ikT5IwzzvAefPDB0HuMqUMPPdS76aabon4Op512mvf444+H7WvXrp330ksvhd7fdddd3rHHHpvuuTFKK1eu7DVr1ixs/6ZNm5x4q1OnTlgHYayffPLJzpBr2rSp9+yzz7prfeONN0JlEFaILZ++ffs6MeiDIcp3EDC077p167xbbrnFa9SokRMFHB/R6INRh3E6f/58LzOkpqa67yEefLiWQYMGOSOcc2HgYrDv2LEj3WNx3QgsxgZ9+tFHH7ljT5kyJVQmo+uAP//80zvxxBNDx3nnnXfCDGno0qVLWPtFMmLECHfuaK+lS5dG/c6ll17qtW/f3tu5c2do33vvvefqgfGcHeeADRs2OPHx008/ufcY2AgURBxGPNfmt5kvGoYOHera5MADD/TatGkT+q7Po48+6jVs2NDVtXv37m7cI6SCMKYQOggKyt52223eli1b3GerV6929f7jjz/SHU+MaQRmZvoq2u8I56YeCNrLL7/cW7NmTViZ22+/3TvvvPO8eJFYSTwyFtT++8Ly5cu8J57o77a5kWQd/xIrIi+M/wL8Y/kY8mDIESFMRiQnhEWRvM5iAHklN4GliAk1i1zeOZJ//vnHrWBHMnu0hQnyYl8REsZzlwgVizdpngR7VgXjuyzPLPY/hCempi61lJTqGS6WItT+kaSmLrfBgwdar159cmXeSrKO/44d27ucYJ4hNn78f49hyGska/vnF/bkcPvn+2UcIpf+FYnntttus2OPPdYtGczKan379rVzzjknzwgVIBcmvQUN8nNfkesVzNcRQgghRP5F8lMkHVdccYW99957LnH9zjvvdM93YTnh/Agrh/FclHhWMUsE6ishhBBC5CT53rMikg+Wxh4+fHiiq5EUEAbFqm3JivpKCJEdlC1bzk499XS3FUKIIBIrQgghhEgoPLusceO9y7GL7KNXr97uYdqZfSCwEMmExIoQQgghEgrPa5o1a6Ydckgj9zwqkT307n2RmlLkepSzIoQQQoiEsnHjBhs//ku3FUKIIBIrQgghhBBCiKREYkUIIYQQQgiRlEisCCGEEEIIIZISiRUhhBBCJJSiRYvaQQcd7LZCCBFEq4EJIYQQIqFUqFDRzjrrXPWCECIN8qwIIYQQIqHs2bPHtm/f7rZCCBFEYkUIIYQQCWXlyhX2wgvPuK0QQgSRWBFCCCGEEEIkJRIrQgghhBBCiKREYkUIIYQQQgiRlEisCCGEEEIIIZISLV0shBBCiIRSuXIVu+aa661YsWLqCSFEGBIrQgghhEgohQoVspIlS6oXhBBpUBiYEEIIIRLK2rVr7cMPR7itEEIEkVgRQgghRELZsWO7/f33PLcVQoggEitCCCGEEEKIpERiRQghhBBCCJGUSKwIIYQQQgghkhKJFSGEEEIklNKly1i7dh3dVgghgmjpYiGEEEIklFKlStlRRx2tXhBCpEGeFSGEEEIklG3bttrs2TPdVgghgkisCCGEECKhrF+/3kaP/shthRAiiMSKEEIIIYQQIimRWBFCCCGEEEIkJRIrQgghhBBCiKREYkUIIYQQCaVw4cJWtWqK2wohRBD9KgghhBAioVSqVNl6975YvSCESIM8K0IIIYQQQoikRGJFCCGEEAklNXW5PfPME24rhBBBFAYmhBBCiISze/fuRFchaRk06G3btGmTlS5d2nr3vijR1RFivyKxIoQQQgiRxAwePMhSU1MtJSVFYkXkOxQGJoQQQgghhEhKJFaEEEIIIYQQSUmuEStvv/22ffnll5ZXGDNmjL377ruh9x9++KGNHDnS8hK7du2yu+++2xYvXpzoqiQdc+bMsZdeesmShS1btri+Wr488cmta9eutYceekjx60LkIypWrGR9+lzqtkIIsU85K0uXLnWG9ooVK6x69erWtWtXq1SpUhrDB8N74cKFVr9+fTvzzDOtSJEimS4TZOjQoXbkkUfaSSedZPuLCRMm2MSJE+2OO+4I29+/f3+rUqWKXXbZZWHXw/6ePXvaoYcemuGxP//8c2fEUx5Gjx7tjPsePXrY/oQ+mD59uvXu3dv1g8/TTz/tjMYgrVu3tpNPPjnuY3M9jzzyiHXu3Nlq1qxpiQDjG1G4ceNGu++++xLSltG4+uqr93tfpwfjl76iTtWqVdsvYu2TTz5xY+TEE0+0I444IvRZhQoV7Pvvv3fbvn375nhdhBCJh///K1eukuhqCCFyu2cFz0adOnXss88+s23bttl7771nBx10kE2ZMiVUZs2aNU5UPPvss7Zu3TpnIB5//PG2devWTJVJBqjPnXfeaf/++29o36JFi+yee+6xW265JWzmF1GDsVeiRAnLLfz00092zTXXuHr//fffYZ8NGDDAZsyYYcWLFw+90hOTyciVV15pRx11lI0aNcoeffTRhLVlJN99951NmzbN+vTpY8lCqVKlnDfjgAMOyPFz4UVs2rSpawPa6rjjjrMXXnghrMyNN97o2nLnzp05Xh8hROJZv369ff75WLcVQogse1aeeuop69SpkzP+fI4++mhnaAwePNi9x8DYsWOH/fLLL84Auv32261hw4Yu5AUDP94y8QgJxA5ejG7durkwMTw9lStXtkmTJrnjM0tcu3Ztd57x48dbuXLl7JxzzrGKFSvGdQ48CUWLFrVvvvnGevXq5fbxN8bVggULbOrUqe76/f0It4MPPtgZo1999ZXbzzmZNe7YsWNmmtoJIdqVujJTD3/88UcoFK5ly5aufj6IPvrn+uuvd9fKzDVer8MPPzzq8fkP4fzzz7fnn3/ezjvvvKhlTjvtNLv00kvjrrPnec5D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EUIIIURC2bhxo33//bduK4QQQSRWhBBCCJFQtmzZbD/99IPbCiFEEIkVIYQQQgghRFIisSKEEEIIIYRISiRWhBBCCCGEEEmJxIoQQgghEkrx4iXssMMOd1shhAiipYuFEEIIkVDKlStnJ598qnpBCJEGeVaEEEIIkVB27txpq1atdFshhAgisSKEEEKIhLJmzWobOPANtxVCiCASK0IIIYQQQoikRGJFCCGEEEIIkZRIrAghhBBCCCGSEokVIYQQQiScQoUKJboKQogkREsXCyGEECKhpKRUs5tuuk29IIRIgzwrQgghhBBCiKREYkUIIYQQCWX16lU2aNBbbiuEEEEkVoQQQgiRUHbt2mUrVqS6rRBCBJFYEUIIIYQQQiQlEitCCCGEEEKIpERiRQghhBBCCJGUSKwIIYQQIqGUK1fOunTp5rZCCBFEz1kRQgghREIpXryENWzYSL0ghEiDPCtCCCGESCibN2+2X3752W2FECKIxIoQQgghEsqmTRvt22/Hu60QQgRRGJgQQgiRBAwa9LZt2rTJSpcubb17X5To6gghRFIgsSKEEEIkAYMHD7LU1FRLSUmRWBFCiP9HYWBCCCGEEEKIpERiRQghhBAJpWjRYla3bj23FUKIXClWunXrZg888IDlFW677TY7//zzQ++vvvpqu+KKKywvsX37ditfvrxNmTIl0VVJOt544w0799xzLVlYs2aN66s//vgj0VWxtWvXWt26dW3RokWJrooQYj9RoUIFO+OMs9xWCCGyLFZ27tzpBEPTpk2tWrVqdsQRR9jTTz9tnueFlfv444/t6KOPdnG3rVu3tm+//TbNseIpE4Skw61bt9r+5K233rIaNWrYrl27Qvv4m33UOcg///zjjL2MrsNny5YtYUs0Rr7fH+zevdtOPPFEV+/x48eHfUYfsz/4uueeezJ1fMbF+vXrw9pvfzJ16lQ755xz7KCDDrKGDRvapZdeav/++2+2nmPp0qX24IMPWp06ddw9EQ8bN260O+64w2699VZLFvbs2eP6ijGR02zbts1uvvlmO/jgg+3AAw90/YJY8sFYOfvss61fv345XhchRHLAbw//D+6P3yAhRB4WK3fffbe99NJL9uyzz9r06dPt3nvvtfvuu8+ee+65UJnvvvvOevToYRdccIH9+OOP1qFDBzv55JPtzz//zFSZZOCYY45x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vdq9R6gUKlTI++uvvxJdtTzHuHHjvOHDhztjADDQEC3du3cPldm+fbtXu3Zt75JLLnHvd+/e7T7HqPO/J/adnj17ev369YsqVk444QSvTZs23rZt29z7u+66yxl1/j0iss6XX37pFSxY0Bs6dGho31dffeXNnj079P6GG27wDjrooJAB/d5773kFChTwpk2bpqbfR3r16uUEyKZNm9z7devWucmQK664IlTmjTfe8EqXLu39/vvvockTBMs777yj9s8kjz/+uPvdHzt2bEyxgjBv2bKlt2XLFvf+oYcecu0fFJDxlMkIiRUhRK5kx44d7gfvueeeC9vPrD6GnMh5HnvsMTfL7OP/p4YXxmfKlClu3w8//KAuyQbefPNN76ijjvK2bt2aRqwsWrTI7QvOWq5fv94Za6+//rrafx859thjvS5dusT8HHHOrD/3RRAmVK6//nq1/z6CF+vcc88N29e1a1fvjDPOCL1v1aqVd8EFF4SV6datm9exY0e1fxb57LPPooqV5cuXOyE+cuTI0D4ECREOAwYMiLtMPChnRQiRK5k7d67LUWnRokXY/iOPPNLlVIich5jwevXqhd7T7pUqVbKDDjootO+II46wQoUKqU+ygVmzZtkdd9xh77zzjhUuXDjN5/64D94TZcuWtYYNG6r99xF+a3766Sc7/fTTbcOGDTZ16tQ0eVvksKxduzbNb9JRRx2l9s8GGPvffPONPffcczZ+/Hh74oknXJ/cfvvtYfdAZPsfffTRav8cgLxEnB7B9i5RooQ1btw41N7xlImHtL92QgiRC1izZo3bYhwH4f2iRYsSVKv8w4gRI+zDDz+0MWPGhPVJZH8UKFDAKlasGOovkTVISj333HPtkUcesfr160dNdk3vnlD77xupqalusQhEyj333GMHHHCAmzA5/vjjnXgsX758uu3/+++/72MNBAbvGWecYQ888IDVqVPHJX5fdNFFdthhh7nG2bZtm23dujVq+yMiMZr5PRLZQzy/N9n1myTPihAiV1KkSJHQf1BB+M+qaNGiCapV/oBZzV69etnjjz9up556alifRPYHqE/2HUQKq6wdcsghbmWeSZMmhVbYmT59eqj9QfdE9uO3LWOfVe5Y1Qhj+a+//nIz/mr/nKd3795uFTBWWkM04sn69ttv7corr8yw/fFESqhkL/H83mTXb5LEihAi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", + "text/plain": [ + "
" + ] + }, + "metadata": {}, + "output_type": "display_data" + } + ], + "source": [ + "import pandas as pd\n", + "\n", + "three = reliable[reliable.satellites == 3].nlargest(1, \"sufficient p20\")\n", + "shown = pd.concat([three, reliable[reliable.pareto_probability >= 0.1]]).sort_values([\"satellites\", \"planes\"])\n", + "fig, ax = plt.subplots(figsize=(8, 3.2))\n", + "ax.axvline(50, color=GRAY, lw=1, ls=\"--\")\n", + "for k, (_, row) in enumerate(shown.iterrows()):\n", + " shares = refinement.results.loc[refinement.results.design == row.design, \"sufficient\"].to_numpy()\n", + " ax.scatter(\n", + " shares, np.full(len(shares), k), s=24, color=COLORS[0], alpha=0.6, lw=0, label=\"replicate\" if k == 0 else None\n", + " )\n", + " ax.scatter(row[\"sufficient p20\"], k, marker=\"|\", s=200, color=INK, lw=2, label=\"0.2 quantile\" if k == 0 else None)\n", + "ax.set_yticks(range(len(shown)), shown.description.str.replace(\", 60 deg FOR\", \"\"))\n", + "ax.set(xlabel=\"Points sufficiently sampled (%)\", xlim=(0, 102), ylim=(-0.6, len(shown) - 0.4))\n", + "ax.legend(loc=\"upper left\")\n", + "style_axes(ax, grid=\"x\")\n", + "plt.show()" + ] + }, + { + "cell_type": "markdown", + "id": "530b6fa1", + "metadata": {}, + "source": [ + "209 of the 1,096 designs meet the requirement, none of them with fewer than four satellites. Among them, four satellites in one plane and six in two planes are efficient for sure, sampling at least 65% and 98% of the points in 80% of the samples. Four satellites in two planes sample more than four in one (at least 68%), and are efficient in 94% of the resamples: these are the alternatives to weigh against the cost of a second plane." + ] + }, + { + "cell_type": "markdown", + "id": "74d48a91", + "metadata": {}, + "source": [ + "## Summary\n", + "\n", + "* The front of the means of the replicates is uncertain: `pareto_probability` finds the designs whose efficiency the replicates settle, and those that are equally good candidates.\n", + "* `refine` adds replicates only to the designs whose efficiency is uncertain, ignoring differences within a tolerance (part of the `Criteria`).\n", + "* `confirm` evaluates the chosen designs with new replicates, which measures the optimism of choosing the best of many nearly equal designs.\n", + "* Statistics other than means (such as a `Quantile`, or the `Probability` of meeting a threshold) judge how reliably a design performs, and `Requirement`s on them rule out designs.\n", + "* Each of these steps takes the study, the criteria, and the results of the step before (or of a search, see `SearchTradeSpace`), and gives its own results and a summary of its designs.\n", + "\n", + "The next notebook, `CompareScenarios`, compares designs under conditions that are not known in advance." + ] + }, + { + "cell_type": "markdown", + "id": "8e4c7da5", + "metadata": {}, + "source": [ + "## Notes\n", + "\n", + "* A `budget` of `refine` limits its evaluations, refining the least settled designs first.\n", + "* An absolute tolerance suits a share near 100% better than a share near 0%; a tolerance proportional to the objective would treat both alike." + ] + } + ], + "metadata": { + "kernelspec": { + "display_name": "Python 3 (ipykernel)", + "language": "python", + "name": "python3" + }, + "language_info": { + "codemirror_mode": { + "name": "ipython", + "version": 3 + }, + "file_extension": ".py", + "mimetype": "text/x-python", + "name": "python", + "nbconvert_exporter": "python", + "pygments_lexer": "ipython3", + "version": "3.14.10" + } + }, + "nbformat": 4, + "nbformat_minor": 5 +} diff --git a/docs/examples/tradespace/SearchTradeSpace.ipynb b/docs/examples/tradespace/SearchTradeSpace.ipynb new file mode 100644 index 0000000..6a941d0 --- /dev/null +++ b/docs/examples/tradespace/SearchTradeSpace.ipynb @@ -0,0 +1,497 @@ +{ + "cells": [ + { + "cell_type": "markdown", + "id": "5124dfb0", + "metadata": {}, + "source": [ + "# Search a Large Trade Space\n", + "\n", + "`EvaluateTradeSpace` evaluated all 1,096 designs. A larger design space, or a longer analysis, cannot afford that. This notebook finds the efficient designs while evaluating only some of them, and compares each method with the true front of `EvaluateTradeSpace`.\n", + "\n", + "It covers:\n", + "\n", + "* the **hypervolume**: one number for how close a set of designs comes to the true front;\n", + "* **screening** every design with a cheaper study;\n", + "* **searching** with optimizers (Optuna and pymoo).\n", + "\n", + "It imports the design space and study of `EvaluateTradeSpace` from `trade_space_example.py`, beside the notebooks. If that notebook was run, the study's results come from its store." + ] + }, + { + "cell_type": "markdown", + "id": "b51ff879", + "metadata": {}, + "source": [ + "## Measure a Front by its Hypervolume\n", + "\n", + "The hypervolume of a set of designs is the volume of the objective space that its efficient designs dominate, bounded by a reference point worse than every design. A set that finds the whole true front has the hypervolume of the true front; a set that misses efficient designs has less. Below, each method's designs are compared by their hypervolume, as a percentage of that of the true front." + ] + }, + { + "cell_type": "code", + "execution_count": 1, + "id": "01692fbc", + "metadata": { + "execution": { + "iopub.execute_input": "2026-11-15T04:33:16.312337Z", + "iopub.status.busy": "2026-11-15T04:33:16.311948Z", + "iopub.status.idle": "2026-11-15T04:33:18.460744Z", + "shell.execute_reply": "2026-11-15T04:33:18.460174Z" + } + }, + "outputs": [ + { + "name": "stdout", + "output_type": "stream", + "text": [ + "the true front: 7 designs\n" + ] + } + ], + "source": [ + "from trade_space_example import MAX_SATELLITES, OBJECTIVES, designs, space, study\n", + "from tatc.tradespace import hypervolume, summarize\n", + "\n", + "results = study.run(designs)\n", + "summary = summarize(results, OBJECTIVES)\n", + "true_front = set(summary.design[summary.pareto])\n", + "REFERENCE = {\"satellites\": MAX_SATELLITES + 1, \"planes\": 5, \"sufficient\": 0} # worse than every design\n", + "true_hypervolume = hypervolume(summary, OBJECTIVES, REFERENCE)\n", + "print(f\"the true front: {len(true_front)} designs\")" + ] + }, + { + "cell_type": "markdown", + "id": "e736bd35", + "metadata": {}, + "source": [ + "## Screen Designs with a Cheaper Study\n", + "\n", + "`screen` evaluates every design with a cheap study, keeps the best of them (whole fronts, until it has kept a share `keep` of the designs), and evaluates only those with the full study. It works if the cheap study ranks designs as the full study would.\n", + "\n", + "Here, a cheap study analyzes one replicate rather than five, over a shorter period, with the threshold of sufficient sampling scaled to the period (`count_samples` with a `duration`): two observations in 12 hours, or one in 6 hours. The table compares each screening with the true front, and its cost (the satellites analyzed, times the days of their analyses) with that of evaluating every design." + ] + }, + { + "cell_type": "code", + "execution_count": 2, + "id": "35495471", + "metadata": { + "execution": { + "iopub.execute_input": "2026-11-15T04:33:18.462112Z", + "iopub.status.busy": "2026-11-15T04:33:18.461888Z", + "iopub.status.idle": "2026-11-15T04:33:19.142843Z", + "shell.execute_reply": "2026-11-15T04:33:19.142420Z" + } + }, + "outputs": [ + { + "data": { + "text/html": [ + "
\n", + "\n", + "\n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + "
cheap studykeep (%)designs keptefficient designs kepthypervolume (%)cost (%)
012 h, 1 replicate5.0744 of 798.816.9
112 h, 1 replicate10.01406 of 799.222.0
26 h, 1 replicate5.0621 of 783.010.6
36 h, 1 replicate20.02315 of 796.625.1
\n", + "
" + ], + "text/plain": [ + " cheap study keep (%) designs kept efficient designs kept \\\n", + "0 12 h, 1 replicate 5.0 74 4 of 7 \n", + "1 12 h, 1 replicate 10.0 140 6 of 7 \n", + "2 6 h, 1 replicate 5.0 62 1 of 7 \n", + "3 6 h, 1 replicate 20.0 231 5 of 7 \n", + "\n", + " hypervolume (%) cost (%) \n", + "0 98.8 16.9 \n", + "1 99.2 22.0 \n", + "2 83.0 10.6 \n", + "3 96.6 25.1 " + ] + }, + "execution_count": 2, + "metadata": {}, + "output_type": "execute_result" + } + ], + "source": [ + "from datetime import timedelta\n", + "from functools import partial\n", + "\n", + "import pandas as pd\n", + "\n", + "from trade_space_example import CACHE_DIRECTORY, START, TARGETS, count_samples\n", + "from tatc.tradespace import Observations, screen\n", + "\n", + "\n", + "def cheap_study(hours):\n", + " \"\"\"A cheaper study: one replicate over a shorter period.\"\"\"\n", + " duration = timedelta(hours=hours)\n", + " return study.replace(\n", + " observations=Observations(TARGETS, START, duration, directory=CACHE_DIRECTORY),\n", + " metrics=partial(count_samples, duration=duration),\n", + " replicates=1,\n", + " )\n", + "\n", + "\n", + "full_cost = results.satellites.sum() # satellite-days of evaluating every design (one day each)\n", + "rows = []\n", + "for hours, keep in [(12, 0.05), (12, 0.1), (6, 0.05), (6, 0.2)]:\n", + " screening = screen([cheap_study(hours), study], OBJECTIVES, designs, keep=keep)\n", + " days = screening.history.stage.map({0: hours / 24, 1: 1.0}) # of each analysis, by the cheap or the full study\n", + " kept = {d.key for d in screening.designs}\n", + " rows.append(\n", + " {\n", + " \"cheap study\": f\"{hours} h, 1 replicate\",\n", + " \"keep (%)\": 100 * keep,\n", + " \"designs kept\": len(kept),\n", + " \"efficient designs kept\": f\"{len(true_front & kept)} of {len(true_front)}\",\n", + " \"hypervolume (%)\": 100 * hypervolume(screening.summary, OBJECTIVES, REFERENCE) / true_hypervolume,\n", + " \"cost (%)\": 100 * (screening.history.satellites * days).sum() / full_cost,\n", + " }\n", + " )\n", + "pd.DataFrame(rows).round(1)" + ] + }, + { + "cell_type": "markdown", + "id": "0f837469", + "metadata": {}, + "source": [ + "The 12-hour study ranks designs nearly as the full study does. Keeping the best 5% of the designs finds 99% of the hypervolume of the true front at 17% of the cost of evaluating every design, although it misses three of the seven efficient designs, whose places designs with nearly the same objectives take. Keeping 10% finds six of the seven, at 22% of the cost.\n", + "\n", + "The 6-hour study is cheaper, but ranks designs differently: one observation in 6 hours separates designs less than four in a day do. Keeping 5% of the designs keeps only one of the seven efficient designs (83% of the hypervolume), and keeping 20% still misses two of them, at more cost than the 12-hour study that keeps 10%." + ] + }, + { + "cell_type": "markdown", + "id": "d236f23e", + "metadata": {}, + "source": [ + "## Search with Optimizers\n", + "\n", + "Larger spaces cannot even be screened. An optimizer searches them instead: it proposes designs, learns from their results, and proposes better ones.\n", + "\n", + "* `optimize_optuna` uses an Optuna sampler, which proposes designs of the design space directly.\n", + "* `optimize_pymoo` uses a pymoo algorithm, which proposes numbers between 0 and 1 that encode designs.\n", + "\n", + "Both evaluate each design once, however often it is proposed, and evaluate the designs proposed together in parallel. Each search here may propose 200 designs, about a fifth of the space, and a Latin hypercube sample of 200 designs (`DesignSpace.sample`) is the baseline. `hypervolume_progress` gives the hypervolume of the designs evaluated so far, after each evaluation. The designs were all evaluated above, so their results come from the store." + ] + }, + { + "cell_type": "code", + "execution_count": 3, + "id": "01e8217c", + "metadata": { + "execution": { + "iopub.execute_input": "2026-11-15T04:33:19.144181Z", + "iopub.status.busy": "2026-11-15T04:33:19.144044Z", + "iopub.status.idle": "2026-11-15T04:33:21.033385Z", + "shell.execute_reply": "2026-11-15T04:33:21.032872Z" + } + }, + "outputs": [ + { + "data": { + "text/html": [ + "
\n", + "\n", + "\n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + "
designs evaluatedhypervolume (%)
Optuna (NSGA-II)143.092.1
pymoo (NSGA-II)157.099.5
Latin hypercube sample176.079.3
\n", + "
" + ], + "text/plain": [ + " designs evaluated hypervolume (%)\n", + "Optuna (NSGA-II) 143.0 92.1\n", + "pymoo (NSGA-II) 157.0 99.5\n", + "Latin hypercube sample 176.0 79.3" + ] + }, + "execution_count": 3, + "metadata": {}, + "output_type": "execute_result" + } + ], + "source": [ + "import optuna\n", + "from pymoo.algorithms.moo.nsga2 import NSGA2\n", + "\n", + "from tatc.tradespace import hypervolume_progress, optimize_optuna, optimize_pymoo\n", + "\n", + "optuna.logging.set_verbosity(optuna.logging.WARNING)\n", + "BUDGET = 200 # proposals of each search\n", + "searches = {\n", + " \"Optuna (NSGA-II)\": optimize_optuna(\n", + " study,\n", + " OBJECTIVES,\n", + " n_trials=BUDGET,\n", + " sampler=optuna.samplers.NSGAIISampler(population_size=20, seed=1),\n", + " batch_size=20,\n", + " ).results,\n", + " \"pymoo (NSGA-II)\": optimize_pymoo(\n", + " study, OBJECTIVES, algorithm=NSGA2(pop_size=20), termination=(\"n_gen\", BUDGET // 20), seed=1\n", + " ).results,\n", + " \"Latin hypercube sample\": study.run(space.sample(BUDGET, method=\"lhs\", seed=1)),\n", + "}\n", + "# the hypervolume (% of the true front's) of the designs evaluated so far, after each evaluation\n", + "progress = {\n", + " name: 100 * hypervolume_progress(search, OBJECTIVES, REFERENCE) / true_hypervolume\n", + " for name, search in searches.items()\n", + "}\n", + "pd.DataFrame(\n", + " {\n", + " name: {\"designs evaluated\": search.design.nunique(), \"hypervolume (%)\": progress[name].iloc[-1]}\n", + " for name, search in searches.items()\n", + " }\n", + ").T.round(1)" + ] + }, + { + "cell_type": "code", + "execution_count": 4, + "id": "ce572cad", + "metadata": { + "execution": { + "iopub.execute_input": "2026-11-15T04:33:21.034557Z", + "iopub.status.busy": "2026-11-15T04:33:21.034396Z", + "iopub.status.idle": "2026-11-15T04:33:21.458279Z", + "shell.execute_reply": "2026-11-15T04:33:21.457700Z" + } + }, + "outputs": [ + { + "data": { + "image/png": "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vn179OvXD5988gnq1auH119/vVDbXRT9sO0mohL0arl3I0/UDnQp7CYREREREZGdsPueR3d3dxw8eBBeXqapImS5SZMmKlDs06eP2iaBovQ4njhxAt7e3vjnn3/QqVMndOnSRd3o9iLi0vDDdlOvo0znOK57WV42IiIiIiIqOj2PQ4YMsQSOQnoeHRwcEB0dbUlXXbx4MZ588kkVOIqOHTuiefPmajvlztzN4UhMMarlwS18EFTaiZeOiIiIiIiKTs+jkF7Fbdu2qfTUhQsXokePHhg8eLDaFxwcjMjISDRs2NDmMbIuvZQ5SU5OVjczObeQdFjrlNiS4GpkqiqUI1wdNXi6k2+JuwZEREREdGe0Wrvvl6KSEDxev34dy5YtQ3h4OI4fP44JEybAycnUM2bugfTx8bF5TOnSpREVFZXjOWfMmIHp06dn2R4Wdh2JiXEoST7ekIg001BHDGzsCH1CGEITCrtVRERERFSUBAZmLWpJxUuRCB4bN26MFStWqOWjR4+iZcuWKFu2rEpVdXZ2VtsTEmyjHanM6uKSc8GXqVOnqiDUuuexYsWK8PMLhKenJ0qK0yHJ2Hjqolr2ctViXM8geLjoCrtZRERERERkZ4pE8GhNpuG47777VFEcCR4l4JMxkJcvX7Y5TtarVq2a43kk6DQHnpm720tSl/vnf4fDaBrqiNGdysDLzbGwm0RERERERHbIrqMkvV6Pmzdv2myLj4/HmTNnLHM9Su9i586dLT2TIiIiAhs3bkSvXr3ueZuLkv0XE7DlhClF19/TAcNb26b+EhERERERmWmMUq7UTiUlJalpOfr374+6deuqMYwy76Pc79ixAwEBAeq4/fv3q3kehw4ditatW2PevHlITU3F7t27s+1dzI6krUpVVxlDWRLSVuXH/ujcS9h/MVGtTx8UgMHNGTwSEREREVER7HmUXsU9e/agXLly2Lx5M06fPo3nnntOFc0xB46iadOm2LdvnyqaI+msDz74oKrOmtvAsSTadireEjhWKeuEAU1N05wQEREREREVuZ7He6kk9TwaDEY8+PkFVSxHzB5RHj3qF+/XTERERERExbjnke6OPw/FWALHeuVd0L2eBy81ERERFUmSkfb999+jKHn99dfV8CyioobBYwmTkmbE53/dsKxP6OkHjUZTqG0iIiIi+8nE+uyzz/D000+rac2krkRuzZ8/H9u3b8e99sorr6jaGGLp0qWqGn9sbKxl/08//YSVK1daijH++OOPGD9+PN555x1cuHAhS2FGqZ3x7LPPYvLkyfj111+zfc4FCxZgypQpt23bm2++iSNHjmRZ9vDwwBdffHEHr5qocDB4LGFW7I1EcGSqWm5d3R2tqrsXdpOIiIjIDly9ehWNGjXC+vXrUa9ePVV8sEOHDrnu1ZPA8ezZs7iXzp07h4sXL6o5wIXUyli8eDE++eQTyzF79+61BMEyx/fbb7+NKlWqqHUpyihziItr166pucUlAK1cubKaU1wKNY4cOdLmOdPS0vDGG2+o55Fez1v57bff1HXNvPzYY4/h66+/hsFgKNDrQXS3Fbl5Hin/4pMN+GZTuGX9xfvL8nISERGRpQevVatWqmfOrFu3bqoQoQRZvr6+mDt3LmrUqIEDBw7gypUrGDJkCNq0aaMq3JuDxy1btqjg6NChQ+jatSsaNGigziXBUvPmzdV83XKeWrVqqWPkMYMGDUKnTp0sPYVr166Fo6Ojeq4xY8bA2zv7wn6///47unTpYrPt8ccfx1dffaWKLEoAaE0CuEWLFqFdu3ZqfeLEiUhISLC8fmmb9euX/ZnnEv/jjz/Ua5LA+rvvvsPHH3+c598gKfzo7u6uXr/MLEBUVDB4LEEW77iJiDi9Wr6/gQfqV3At7CYRERERgKFfXEB4bNpduxZlPBywfJypty0nErCtWrXKZlvPnj1VACbV7AcOHIitW7eqnjtJDS1Tpgz69u2LdevWwc/PTwVEtWvXVoGZVMqX3j9ZNwePcg45lwRocp6ZM2eqIFOOHTBggApIpUewWrVqKpCUFFOppt+vXz91fHYOHz6MZs2a2WyrWLGi6i1877338Omnn9rsa9GihQr4SpcujZo1a8LV1VXdxJ9//pnl9YugoCCbdXn8qFGj0LZtW9XjKa/DwSHvH6kl1fbgwYMMHqlIYfBYQkTFp+G7fyLUsk4LPN+dvY5ERET2QgLH0Ji7FzzmhsyjLUFgZv7+/oiMjLSsS2A2ffp0tezk5KTGCEpPYvXq1VXgKD1/uTF69Gg1rlLIWMBdu3ap4FGCun///RcnTpxQRWUk7VTGIkpPXWZxcXHZbn/11VdRp04dlaZqbeHChWpspoxXlPPL/OASYMp0b5lfv4x5DA0NhU6nU2McRVhYmJprXHpHZUo5CQDXrFmjgt+dO3fi22+/Vcf16tULDz300C1fv7TbemwmUVHAMY8lxLx/IhCXbMqrH9jMG1XKcg5MIiIieyE9g/6ed+8m57+dChUqqDm1rUnv3/nz51Vvnpn0DJpJwBgSEpLt+TIX5Ms8O5z1OaWAjASIQoIuma9bxl9KD6Skr+YUZEnvp3VgayY9i1IUZ9q0aTbbZQ5wSWeVQjgSPMqYQylkY379Z86csRwrvYqSUvq///3PJviUc4wdO1YFyfLc0hNpDrKlvXKzvkY5uXnzZrbBOpE9Y89jCXA9KhVLd5reWJ0dNHima5nCbhIRERFZuV1K6b0wYsQIvP/+++jcubNlzuuPPvpI9bDJ+D4zST996qmn1LKMb5TUVCFBVUpKiuU46c2TcZFCiu9I0RoZI3k70oMnQZykuB47dkz1LuZE0lClPdl56aWXVC+mBKFNmzZV23755ReVfqvValWPogRvwcHBat8jjzyCd999F+3bt1dtl3GYEhi//PLLlnNK8SDpMa1UqZJa79ixI1544QV1XNWqVdUtt2S84+zZs3N9PJE9YPBYAny98YaaokM83MYHAV6Ohd0kIiIisjPSSyfVQyUYlHROKRQjgdXq1atVYGgmPXYSNEnK6smTJ1W6qZCxjBJ8Ssqp9MpJD6IEZH/99RcuXbqkehBzQ1I+pfdOUkLl/OZANjtSyEdSaKWHVILBzGmhkhb7/PPPW4JHaZuko0pV1fDwcDWmUtJOza9fivdIkR4pHFSqVCn1Wh999FG1X4oCSWqrVFqV4NNsw4YNqkdSCu7klgTFEhxLVVeiokRjzJxDUILnNfLy8kJ0dPQt36SKmvNhyej/6XkYjICHixbrJlWHt5vtmysRERGRmRRxkSBSqqtKj6Obm5tlnwSDUkRHAjsJLmW/HGcmFVdl7kTpEZRqqhIknTp1SgWjkhIrwZL02klaavny5S09ddLbKCmoErhJICgBp3xElaI0MnVInz59LIVtMpP0VOktlF5NmapDekobNmxo6fGUqTdk3VzVVNot4yjldUm7MldylXZK8R4JPqXX0pxeK+MyJdVUAufMx0tw3L179yxtk+quUtBHXqv18rhx41SAPHjwYP7iUZHC4LGYB48vLgnGX0djLVNzjO7ElFUiIiLKH3PwKPf2QgI6qbpqnuqjKFi5cqVKiyUqahg8FuPg8fCVRAz/6qJaLuOhw9qJ1eHmxBpJRERElD+ZewyJqGThmMdiSlI9Zq8Ls6w/06UsA0ciIiK6I5IeSkQlF7uhiqmdZ+Ox53yCWq7o64gHm9vm8xMREREREeUFg8diyGAw4tP1Nyzrz3cvC0ed7VxLREREREREecHgsRj661gsjl1NUsu1A53Rq2HxGMNJRERERESFh8FjMZOqN+Izq17HF+/3g1bLXkciIiIiIrozDB6LmVX7onApIkUtN6/ihnY13Qu7SUREREQFLjw8HJs2bSpSV3b58uWF3QSiO8LgsRhJTDHg643hlnWZ11GjYa8jERERFT/Tpk1DVFSUWt61axe+//576PV6y/49e/Zg3759lvULFy6o4G3z5s1ITU3Ncr4TJ05g6dKl+P3333H9+vVsn3Pnzp1YvXr1bdu2atUqBAcHZ1mWqU5+/vnnfLxaIvvA4LEYWbozEmExaWq5S91SaFzJrbCbRERERFTgbt68iT///BP9+/dX68uWLcMTTzyBRYsWWY6RQFECNzF37lw0btwYP/30E2bOnImWLVviypUral9ycjKGDh2KDh06qPMsWLAAbdu2xQcffJDleZ988kk89thjCA0NvWX7pk+fjqNHj2ZZHjt2LD766KMCvBJE9xbneSwmohP1mL/F1OsonY0v9PAr7CYRERFREbJlyxZUrFgRERERKrDq1KkTSpcurQKlHTt2YODAgZZjZb1UqVJo2LChelyFChVUL+DZs2dx//33w8vLCxs3bkRsbCx69eoFV1dXy2MvXbqE3bt3w8/PTwVsWq02V/us/frrr6p9Op3Osq1v37546623MHz4cDg7O9sc//HHH6vAsl+/fmr95MmTlt5HeczFixdx5swZeHubpjaTfRs2bMjS6yjnffzxx7Fw4UJMmjQpz9e4Xr16Kt32/PnzqFq1ap4fT1TYGDwWE99vjUBMkkEt92viher+tm+aRERERLcyf/58HD9+HD4+PnBycsL48eMtgdy4ceNUb125cuVgNBpVAGXu1ZPHHThwQAWeKSkpKp30vvvuQ3x8PEJCQvDNN99YAjEJ+qSHsGvXruq5ypcvj3Xr1qlhNrfal9nevXtV4GqtRYsWcHR0xNdff40XX3zRZp+/v79KW5W2y/lq165t2bd48WJ89dVXlsBRyHl69+5t+1nr++/V627fvj0eeeSRfAWPQnpA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", + "text/plain": [ + "
" + ] + }, + "metadata": {}, + "output_type": "display_data" + } + ], + "source": [ + "import matplotlib.pyplot as plt\n", + "\n", + "from tatc.tradespace import GRAY, plot_progress, use_style\n", + "\n", + "use_style() # the style of the plots of trade studies\n", + "\n", + "ax = plot_progress(progress)\n", + "ax.axhline(100, color=GRAY, lw=1, ls=\"--\")\n", + "ax.annotate(\"true front\", (0, 100), xytext=(2, 4), textcoords=\"offset points\", fontsize=8, color=GRAY)\n", + "ax.set(ylabel=\"Hypervolume (% of true front)\")\n", + "ax.set_title(\"Progress of the searches\")\n", + "plt.show()" + ] + }, + { + "cell_type": "markdown", + "id": "04a68fe0", + "metadata": {}, + "source": [ + "Where each search looked: the designs that it evaluated (blue) among every design of the space (gray), with the true front ringed." + ] + }, + { + "cell_type": "code", + "execution_count": 5, + "id": "d8c9d612", + "metadata": { + "execution": { + "iopub.execute_input": "2026-11-15T04:33:21.459515Z", + "iopub.status.busy": "2026-11-15T04:33:21.459276Z", + "iopub.status.idle": "2026-11-15T04:33:21.643244Z", + "shell.execute_reply": "2026-11-15T04:33:21.642747Z" + } + }, + "outputs": [ + { + "data": { + "image/png": "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h+y77378qkjcQh0kJPZAXaHTTz9VfvnlF7W93Xbbq5pKCQkJ8u2338qnn34iH330kfz66xR58smnZMCAgeFuMiFhI6ItPjj0DjjgAFU8DANcUFpaKu+//74qmBboPqHGN2XF5tdze3xsDOwxm6XJz89XHRyA4xMF4/D5f/zxR5Xb96ijjlLvDR06VG6++WZ5++23ZenSpVscF05XOGIRTY18vbien376qff94cOHyzHHHKOKyBlTXZx33nly3HHHqWMOGjRI7r77btlmm23Ue4jC1G2Dw/aFF15QjmQ45h566CFV7G1rx/Btd2ftRBqAV199VVasWKGK0CEyBs5xEh/89ttvcv31/1KO4KOOOlree+8DmTPnBjnjjBly+eVXyJIlS70O4Mcee1TeeOP1cDeZEEIICRoLFjynHMGY0Ln22uvkrbfekUsuuVTp4H/+819577335YADDhSHwyGXXXaprFmzhlefEEJIzABbEI5gpJ58/PEnZcGC5+Wcc86VmTPPkgcffEheffV15ddAgNCsWeeJ0+kMd5MJCRsmt/aghgE47T788EO1jA1pAi699FLlBBwzZox6APyY4TTcd999VfQnHJyIfP3ggw9URHCg+2wNLJFF5ERdXV1QlsiiiBw+FyKE4bCGIzgjI6PHxyWE+Ofaa69WEwR7772P3HPPvR1GN951153y8MMPybbbbisvvOAptkgCB5JR3+qSzGTPKgUSGwRbAwkhoQUG7cEHT1aFcy+99DKZPv1Uv302HMFnnHGafP3113LyyaeoyVISHB2MBn30bWM0tDlUUAcJiW4wwQkdRL/27LMLZPTo0X7327ixUg4//DA15r333vtkn33+EfK2EiLxniYCMzIo8AROP/105TzFNpJ7a2cwCl0gyvWJJ55QRcxmzZql0g0YnbyB7BNqMjIy1YMQEpoB/Jtvvqn+njHjzHaO4NpaFC9sValFsrNz5JRTpsuTTz6hIomXL/9JRo/egV9RgPxZbpN73q2U0lq7lGRb5LxJ+WKVJrG4bd4c7ejXkasrLS1NrQ7IysqOGEMT9wLaB9A23A++9wchhEQjn3/+mXIEY+w5+fBjlTH8V0Vbuz571v4FMqzIKqeddrpyBr/00oty4YUXqaAFErgO3v1OhayvsUvfHIscOyZJhuU6pbQxUZ78ok3WVrVIQZpJThqbIMOLk5W2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ZLriiivk8ccfl5tuukkGDRokb731luy5556ydOlS2XvvvdU+H330kUyaNEkuvvhiOe644+Tee++ViRMnyvfffx+RyakJISRWCuMYRR74cxTHY0J+Qggh8aODW1teSh0khBASC1AH47CA3FdffeX9GyHfnTmCjfv2lMWLF8s555wjM2bMkP33319uv/122XbbbeWVV17x7nPNNdfIEUccoRzGhx9+uLz00ktSUVEhDz30UNDaQQgh8c7WjFkYv8XFJVsYwfGYkJ8QQkh86WBHGgiog4QQQmIB6mAcOoPnzLlezjjjdHn33XekpaVli/ebmppUKofTTz9V7RssxowZI998842KRgbr1q1Tj1122UVtNzc3qxQRhx12mPd/0tLSVKTwu+++G7R2EEJIvNNdYxaGMZYKYaWGv6WzhBBCSDRAHSSEEBLPUAfjME3Eiy++JM8++6zcfPNNctlll8rgwYMlLy9PFUPAcqmVK1eqHL3Tpp0sJ554YtAa+MQTT6gcwShU17dvX/nrr7/kxhtvlClTpqj3165dKy6XS71nBNvvvfdeh8e12WzqodEVD3EsPAghhLQnMzNLXC632GytYrUmb9oOrL/EvnjofpZ0D7M54DncTqEGEkJI16EOhh/qICGEhA/qYOzoYMDOYIslSU4++RSZOvUk+e677+S7776VsrIylTt4woTdVATvTjvtHPQ8wkj1AKcuCtcNHTpU3nnnHfnXv/4lEyZMkJ133lnsdrvfGYqUlBSVnLoj4FDGMX2pqCiVlhZPDjBCCCH+sdmapby8mZcnxJSU9AvKcaiBhBDSM6iD4YE6SAghkQF1MLp10ORGaG+EgsIMiD5GQTjkDNYcdNBBygn9+uuvy4YNG1QU8KuvviqHHHKId5/TTz9dli9fLl988UXAUVGIPq6pqZHMzMxe/mSEEEJIZEVEUQMJiT9gBtS3uiQz2azG1oREOtRBQggh8Yw51JHB4aChoUFF9/br197zje0ff/xR/d2nTx+VngJ5hY3O4C+//FImTpzY4bGtVqt6+Luwwbq4hJDIr4baUeVvQmIZaiAh5M9ym9zzbqWU1tqlJNsis/YvkGFFW46NCYlFqIOEENqCJJ6JaK9nSUmJDBkyRB5++GFvygfkCEYU8B577OHd79RTT5VHHnlESktL1fZLL72kooLxOiGEdCT+yHeOFQh4xjYh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", + "text/plain": [ + "
" + ] + }, + "metadata": {}, + "output_type": "display_data" + } + ], + "source": [ + "from tatc.tradespace import plot_designs\n", + "\n", + "fig, axes = plt.subplots(1, 3, figsize=(14, 4), sharey=True)\n", + "for ax, (name, search) in zip(axes, searches.items()):\n", + " evaluated = summary.design.isin(search.design)\n", + " plot_designs(\n", + " summary,\n", + " \"satellites\",\n", + " \"sufficient\",\n", + " highlight=evaluated, # the designs the search evaluated, over the others in gray\n", + " label=\"evaluated\",\n", + " others=\"not evaluated\",\n", + " front_label=\"true front\",\n", + " jitter=0.18, # spreads the designs of each number of satellites, for legibility\n", + " legend=\"upper left\" if ax is axes[0] else None,\n", + " ax=ax,\n", + " )\n", + " ax.set(xlabel=\"Satellites\", ylabel=\"\", xticks=range(1, MAX_SATELLITES + 1), ylim=(0, 105))\n", + " ax.set_title(f\"{name}: {evaluated.sum()} designs\")\n", + "axes[0].set_ylabel(\"Points sufficiently sampled (%)\")\n", + "plt.show()" + ] + }, + { + "cell_type": "markdown", + "id": "d796b1b2", + "metadata": {}, + "source": [ + "Both optimizers find more of the front than a sample of as many designs. pymoo's proposals gather at the top of each column of designs, near the front, while the sample's spread over the space. pymoo finds 5 of the 7 designs of the front and 99.5% of its hypervolume with 157 designs, 14% of the space (its other 43 proposals violate the constraint on the number of satellites). Optuna finds 92% of the hypervolume with 143 designs, and the sample 79% with 176. The searches stop at their budget, not when they converge: a larger budget, or screening first, would bring Optuna's closer to the true front." + ] + }, + { + "cell_type": "markdown", + "id": "c8c5a7fe", + "metadata": {}, + "source": [ + "## Summary\n", + "\n", + "* The hypervolume measures how close a set of designs comes to the true front (`hypervolume`, and `hypervolume_progress` as a search proceeds).\n", + "* `screen` evaluates every design with a cheap study and only the best with the full one, which finds the front at a fraction of the cost if the cheap study ranks designs as the full one does.\n", + "* `optimize_optuna` and `optimize_pymoo` search spaces too large to enumerate, and find most of the front with a fraction of the designs.\n", + "\n", + "A search chooses its front from the mean of each design's replicates, which favors designs whose replicates were lucky. The next notebook, `RankUncertainDesigns`, ranks designs with the uncertainty of their replicates, for the results of a search as for those of every design." + ] + }, + { + "cell_type": "markdown", + "id": "2174a6c1", + "metadata": {}, + "source": [ + "## Notes\n", + "\n", + "* How many designs to keep depends on how well the cheap study ranks designs. Check it on a sample of designs evaluated with both studies before screening a large space.\n", + "* The results of a search depend on its seed: over eight seeds, pymoo's search here finds 88 to 100% of the hypervolume (96.5% on average). Compare several seeds before relying on one.\n", + "* Many encoded points decode to the same design (those in the same level of each variable, or that differ only in the variables of an alternative not chosen). `optimize_pymoo` eliminates proposals of designs proposed or evaluated before, which pymoo's own elimination of equal points does not see." + ] + } + ], + "metadata": { + "kernelspec": { + "display_name": "Python 3 (ipykernel)", + "language": "python", + "name": "python3" + }, + "language_info": { + "codemirror_mode": { + "name": "ipython", + "version": 3 + }, + "file_extension": ".py", + "mimetype": "text/x-python", + "name": "python", + "nbconvert_exporter": "python", + "pygments_lexer": "ipython3", + "version": "3.14.10" + } + }, + "nbformat": 4, + "nbformat_minor": 5 +} diff --git a/docs/examples/tradespace/TradeCostAndUtility.ipynb b/docs/examples/tradespace/TradeCostAndUtility.ipynb new file mode 100644 index 0000000..f5e3811 --- /dev/null +++ b/docs/examples/tradespace/TradeCostAndUtility.ipynb @@ -0,0 +1,834 @@ +{ + "cells": [ + { + "cell_type": "markdown", + "id": "4e611495", + "metadata": {}, + "source": [ + "# Trade Cost and Utility\n", + "\n", + "So far, the numbers of satellites and planes have stood in for cost. This notebook estimates the life-cycle cost of each design, and trades it against what the design achieves.\n", + "\n", + "It covers:\n", + "\n", + "* **costs**, from a cost model and the schedule of each design's deployment;\n", + "* **uncertain cost growth**, and the cost at a confidence level as an objective, within a **budget**;\n", + "* **utility**, which weighs several objectives by a stakeholder's preferences.\n", + "\n", + "It builds on `ExplainTradeSpace`, whose study measures both shares of points sampled." + ] + }, + { + "cell_type": "markdown", + "id": "f679f58b", + "metadata": {}, + "source": [ + "## Estimate Costs\n", + "\n", + "Three parts describe the mission of each design (with illustrative costs, in millions of dollars):\n", + "\n", + "* A `DeploymentSchedule`: three years of development; production on one line, at four satellites a year; launches of up to three satellites, at most one every half year; and five years of operations from the first launch.\n", + "* A `CostModel`: the costs of developing a satellite of each imager and of producing its first unit (later units cost less, on a learning curve), a cost per launch, and the costs of operations. TAT-C has no cost-estimating relationships: the study gives these costs.\n", + "* A `MissionPlan` combines them. It plans each design's deployment by the schedule, and estimates its cost for the satellites of its imager (`kind=\"field_of_regard\"`).\n", + "\n", + "The growth of the cost of development is uncertain: an `Uncertain` parameter (`cost_growth`) from 0.9 to 1.6 times the estimate, most likely 1, drawn for each replicate. `space.extend` adds it to the design space, and the plan multiplies the costs of development by it (`growth`)." + ] + }, + { + "cell_type": "code", + "execution_count": 1, + "id": "216ec565", + "metadata": { + "execution": { + "iopub.execute_input": "2026-11-15T04:33:51.182542Z", + "iopub.status.busy": "2026-11-15T04:33:51.182353Z", + "iopub.status.idle": "2026-11-15T04:33:53.363002Z", + "shell.execute_reply": "2026-11-15T04:33:53.362553Z" + } + }, + "outputs": [ + { + "data": { + "text/html": [ + "
\n", + "\n", + "\n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + "
satellitesplanesfield_of_regardcost_growthdeployedcostcost developmentcost productioncost launchcost operations
011301.053.2579.6542.1512.08.017.5
111301.083.2580.8243.3212.08.017.5
211301.243.2586.9349.4312.08.017.5
311301.013.2577.9740.4712.08.017.5
411301.173.2584.3546.8512.08.017.5
\n", + "
" + ], + "text/plain": [ + " satellites planes field_of_regard cost_growth deployed cost \\\n", + "0 1 1 30 1.05 3.25 79.65 \n", + "1 1 1 30 1.08 3.25 80.82 \n", + "2 1 1 30 1.24 3.25 86.93 \n", + "3 1 1 30 1.01 3.25 77.97 \n", + "4 1 1 30 1.17 3.25 84.35 \n", + "\n", + " cost development cost production cost launch cost operations \n", + "0 42.15 12.0 8.0 17.5 \n", + "1 43.32 12.0 8.0 17.5 \n", + "2 49.43 12.0 8.0 17.5 \n", + "3 40.47 12.0 8.0 17.5 \n", + "4 46.85 12.0 8.0 17.5 " + ] + }, + "execution_count": 1, + "metadata": {}, + "output_type": "execute_result" + } + ], + "source": [ + "from trade_space_example import PLANE_GROUPS, accuracy_study, space\n", + "from tatc.tradespace import (\n", + " CostModel,\n", + " DeploymentSchedule,\n", + " LaunchCost,\n", + " MissionPlan,\n", + " OperationsCost,\n", + " SatelliteCost,\n", + " Uncertain,\n", + ")\n", + "\n", + "SCHEDULE = DeploymentSchedule(years=5, development_years=3, production_rate=4, launch_interval=0.5, launch_capacity=3)\n", + "COST_MODEL = CostModel(\n", + " satellites={ # by field of regard\n", + " 30: SatelliteCost(development=40, first_unit=12, learning_rate=0.9),\n", + " 60: SatelliteCost(development=60, first_unit=18, learning_rate=0.9),\n", + " },\n", + " launch=LaunchCost(per_launch=8),\n", + " operations=OperationsCost(per_year=3, per_satellite_year=0.5),\n", + " discount_rate=0.03,\n", + ")\n", + "PLAN = MissionPlan(SCHEDULE, COST_MODEL, kind=\"field_of_regard\", growth={\"development\": \"cost_growth\"})\n", + "cost_space = space.extend(cost_growth=Uncertain.triangular(0.9, 1.0, 1.6))\n", + "cost_study = accuracy_study.replace(space=cost_space, plan=PLAN)\n", + "results = cost_study.run() # every design of the design space\n", + "COSTS = [\"cost\", \"cost development\", \"cost production\", \"cost launch\", \"cost operations\"]\n", + "results[[\"satellites\", \"planes\", \"field_of_regard\", \"cost_growth\", \"deployed\", *COSTS]].head().round(2)" + ] + }, + { + "cell_type": "markdown", + "id": "23876394", + "metadata": {}, + "source": [ + "Each evaluation now has the cost of the design and its parts, and the years from the start of development to the design's last launch (`deployed`).\n", + "\n", + "## Trade Cost against Sufficiency\n", + "\n", + "Budgets are often set at a confidence level: a cost within which a design stays with a probability of 70%, the 0.7 `Quantile` of its cost over the replicates (`cost p70`). The criteria:\n", + "\n", + "* minimize the cost at 70% confidence, and maximize the share of points sufficiently sampled;\n", + "* require the cost at 70% confidence to be within a budget of 150 million dollars (a `Requirement`).\n", + "\n", + "`summarize` gives the statistics of the criteria for each design, and whether it is efficient among those that meet the requirement (`pareto`)." + ] + }, + { + "cell_type": "code", + "execution_count": 2, + "id": "80fc3006", + "metadata": { + "execution": { + "iopub.execute_input": "2026-11-15T04:33:53.364678Z", + "iopub.status.busy": "2026-11-15T04:33:53.364478Z", + "iopub.status.idle": "2026-11-15T04:33:53.800712Z", + "shell.execute_reply": "2026-11-15T04:33:53.800185Z" + } + }, + "outputs": [ + { + "name": "stdout", + "output_type": "stream", + "text": [ + "520 of 1096 designs cost at most 150 at 70% confidence\n" + ] + }, + { + "data": { + "image/png": "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iIiIiIhopxg8EhERERER0U4xeNxO1gqTdYq47CUREREREVFjDB63q66uRlZWlmqJiAioqanBN998pVoiIiIiBo9ERNSk2toafPvt16olIiIiYvBIREREREREO8V1HreT+Y4ybLWyshKZmZk733NEREkuEAjA4/HAarXCaDR29OYQERFRBzN19AYQEVF8koDR4XB09GYQERFRnOCwVSIiatK2bdvw1lszVUtERETE4JGIiJrk9Xrwxx+rVEtERETE4JGIiIiIiIh2isEjERERERER7RSDxxRVWlqKL774oqM3g4iIiIiIEgSrrSYYr9eLd999V523WCyYMmVKRI/zyy+/4KabbsLnn38e5S0komSRnp6BceMmqJaIiIiIwWOCkTXXXn31VdTW1mL+/PmoqKjo6E0ioiSVlpaG0aPHdPRmEBERUZyIm+DR7/erNcU0TUMyqHQF8NN6FyqcAWQ7jBjS3Y4se9sX2c7IyMAbb7yBVatWYdSoUS3etri4GCtXrsTuu++OxYsXo1+/fujVq1fjba2sxNy5c9W+LygowF577aUWBa//GEOGDMHChQvV/eVxQnRdx5IlS9Tthg8fjs6dO7f5NRJRfHC7XVi7dg169uwFm83e0ZtDREREqTznsaysDP/73/9UMGI2m5udg3f33XejqKhI3WbPPfds8natuU2s/LLRhSc/34r5q2rx2ya3aqUvl8fSjz/+iLPOOgsHHnig2s+yX2bOnNnodrKGm2QzX3nlFdxwww0qCKyurg4/xtlnn43x48fj3nvvxejRo/Hee++Fs6CHHnooLrzwQjz88MPq8WfNmhXT10hE7Ud+WHr33bdVS0RERNShweNDDz2EzZs348knn2z2Nk888QRuvvlmPP3009i6dSsmT56sTmvWrNml28Qy4/jRsiroesPLpS+Xy/WxtGXLFnz66aeYPXu2CvquuOKKRreRbKLsOwkC//GPf6CwsDA8r1LI0NjPPvsMH374IR588EE8//zz6vLHH39cBevymGeccQYuvvhi3HrrrTF9fURERERElALBoxRsueeee9C/f/9mbyPXS/Zs0qRJyMrKwm233Ybc3Fw89thju3SbWJGhqjsGjiFyuVwfS5JFlKGoYr/99lPZ3lBWMWTRokUq+ysB+Msvv6wCegk6Q4YOHYrMzEx1vnfv3uoxQlnJkpISlbWUk/RH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iJok67/W1FSrloiIKFmL1sQiA+kwWlSwKsVxzAajaqXPYatEO5g/fz6OO+447hciIiIi6vCiNfXFqmiNpmkqyykBowhlPROp0qpg5jEBvfrqqxg7diz22GMPXHrppXA6G34J2sMZZ5yBAQMGRHRfj8eD0tLSqG8TEREREdGuZv/qi2X2r8iRrZbmuGLgBNUm2hqPgsFjO6nwuvB58UrMWr9UtdKPhh9//BGffPIJ7r//frz44otYunQpbrvtNrR3sFpTU4ONGze26/MQEREREbV79s9shy/oV22ss3+apqk5jomWcQxh8NgOllVsxMMrvsBXpavwc+Um1UpfLm+r4cOH46mnnsLo0aMxdOhQ9O3bF0ajsdnby2332msvdb9bbrkFfr9fXf7555/jpJNOwjXXXIPdd98dCxcubPL+xcXFeOihh3Drrbe2uF2hx7vyyitVRlSGqcp9d/Trr7+iW7du6N69O0aMGKGC4PqPcfLJJ+O6665Tj3HkkUc2eIx33nkHBx54IAYOHKgyoaFs5ubNm3HssceqfSGPLfcnorbLycnBCSecrFoiIqJkUTfDUQsXPqXWY/AYZZJhfHfDT9B3+DhKXy5vawZSfqWoqqpSQVJWVhZWr16N//u//2vytnPmzMFNN92EO+64A08//TTeeustPPjgg+o6t9uN119/XQVcH3zwAYYNG9bkY1x44YX43//+B7vd3uJ2yeO99tpr6NmzJ9544w3k5eXhrLPOanS7/v3747vvvlPzIJ988km89NJL+Prrr8OPMXPmTLVNsq3Z2dm4/fbb1XXffvut2o677roL77//vnr9F19ct/6cXFZUVIS5c+eqx5aAmIjazmKxokePnqolIiJKloI5FT6XKlojbawK5iQLBo9RtmTbhkaBY4hcLte3VUZGhgqS5s2bh0AggP/85z9N3k4ydRJgjR8/HiNHjlSZx3fffTd8vVx27rnnolevXrBYGpcIfuGFF9CnTx/ss88+rdouCUAvueQSlRmUjKIMr/X5Gk5Alu29++67MXnyZPz973/H8uXL1VDcEMmSnn322dhtt91UdlEylaGhsz///DOOOeYYjBs3TgXDEoCKLl26YMGCBSp4lPmVEnQSUdtVV1fjyy8/Vy0REVGi68iCOcmCwWOU7fiB3FGFr+3FbST7KJk3Gbp61VVX4cMPP2zydpLJczj+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", + "text/plain": [ + "
" + ] + }, + "metadata": {}, + "output_type": "display_data" + } + ], + "source": [ + "import matplotlib.pyplot as plt\n", + "\n", + "from tatc.tradespace import GRAY, Criteria, Quantile, Requirement, plot_designs, summarize, use_style\n", + "\n", + "use_style() # the style of the plots of trade studies\n", + "\n", + "BUDGET = 150 # millions of dollars, at 70% confidence\n", + "COST = Criteria(\n", + " {\"cost p70\": \"min\", \"sufficient\": \"max\"},\n", + " statistics=[Quantile(\"cost\", 0.7)], # named cost p70\n", + " requirements=[Requirement(\"cost p70\", \"<=\", BUDGET)],\n", + ")\n", + "costed = summarize(results, COST, statistics=[\"cost development\"]) # and whether each design is efficient\n", + "print(f\"{costed.meets_requirements.sum()} of {len(costed)} designs cost at most {BUDGET} at 70% confidence\")\n", + "\n", + "groups = costed.planes.clip(upper=3) # 3 or 4 planes share a color\n", + "ax = plot_designs(costed, \"cost p70\", \"sufficient\", by=groups, names=PLANE_GROUPS, legend=\"upper left\")\n", + "ax.axvline(BUDGET, color=GRAY, lw=1, ls=\"--\")\n", + "ax.set(xlabel=\"Cost at 70% confidence (millions of dollars)\", ylabel=\"Points sufficiently sampled (%)\", ylim=(0, 105))\n", + "ax.set_title(\"Every design, with the efficient designs within the budget ringed\")\n", + "plt.show()" + ] + }, + { + "cell_type": "markdown", + "id": "32e5e476", + "metadata": {}, + "source": [ + "The efficient designs, with the years until they are deployed and some parts of their costs. A summary keeps the values that are the same in every replicate of a design, such as the cost of launches; the cost of development grows by a different factor in each replicate, so its mean is added:" + ] + }, + { + "cell_type": "code", + "execution_count": 3, + "id": "c732c5b8", + "metadata": { + "execution": { + "iopub.execute_input": "2026-11-15T04:33:53.801943Z", + "iopub.status.busy": "2026-11-15T04:33:53.801696Z", + "iopub.status.idle": "2026-11-15T04:33:53.808125Z", + "shell.execute_reply": "2026-11-15T04:33:53.807686Z" + } + }, + "outputs": [ + { + "data": { + "text/html": [ + "
\n", + "\n", + "\n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + "
descriptionsatellitesplanesdeployedcost developmentcost launchcost p70sufficient
0700 km, 30 deg FOR, SSO: 1 at 06:00113.244.48.083.61.0
1800 km, 30 deg FOR, SSO: 2 at 06:00213.544.48.096.92.6
2800 km, 30 deg FOR, Walker 45 deg: 2 x 1 (spac...223.844.416.0104.76.2
3800 km, 30 deg FOR, Walker 45 deg: 1 x 3 (spac...313.844.48.0109.67.8
4800 km, 30 deg FOR, Walker 45 deg: 3 x 1 (spac...334.244.424.0124.811.2
5800 km, 30 deg FOR, Walker 45 deg: 2 x 2 (spac...424.044.416.0129.322.2
6800 km, 60 deg FOR, Walker 45 deg: 2 x 1 (spac...223.866.716.0139.230.2
7800 km, 30 deg FOR, Walker 45 deg: 4 x 1 (spac...444.844.432.0144.331.0
8800 km, 60 deg FOR, Walker 45 deg: 1 x 3 (spac...313.866.78.0149.138.0
\n", + "
" + ], + "text/plain": [ + " description satellites planes \\\n", + "0 700 km, 30 deg FOR, SSO: 1 at 06:00 1 1 \n", + "1 800 km, 30 deg FOR, SSO: 2 at 06:00 2 1 \n", + "2 800 km, 30 deg FOR, Walker 45 deg: 2 x 1 (spac... 2 2 \n", + "3 800 km, 30 deg FOR, Walker 45 deg: 1 x 3 (spac... 3 1 \n", + "4 800 km, 30 deg FOR, Walker 45 deg: 3 x 1 (spac... 3 3 \n", + "5 800 km, 30 deg FOR, Walker 45 deg: 2 x 2 (spac... 4 2 \n", + "6 800 km, 60 deg FOR, Walker 45 deg: 2 x 1 (spac... 2 2 \n", + "7 800 km, 30 deg FOR, Walker 45 deg: 4 x 1 (spac... 4 4 \n", + "8 800 km, 60 deg FOR, Walker 45 deg: 1 x 3 (spac... 3 1 \n", + "\n", + " deployed cost development cost launch cost p70 sufficient \n", + "0 3.2 44.4 8.0 83.6 1.0 \n", + "1 3.5 44.4 8.0 96.9 2.6 \n", + "2 3.8 44.4 16.0 104.7 6.2 \n", + "3 3.8 44.4 8.0 109.6 7.8 \n", + "4 4.2 44.4 24.0 124.8 11.2 \n", + "5 4.0 44.4 16.0 129.3 22.2 \n", + "6 3.8 66.7 16.0 139.2 30.2 \n", + "7 4.8 44.4 32.0 144.3 31.0 \n", + "8 3.8 66.7 8.0 149.1 38.0 " + ] + }, + "execution_count": 3, + "metadata": {}, + "output_type": "execute_result" + } + ], + "source": [ + "front = costed[costed.pareto].sort_values(\"cost p70\")\n", + "front = front.drop_duplicates([\"cost p70\", \"sufficient\"]).reset_index(drop=True) # one of the designs that tie\n", + "front[\n", + " [\"description\", \"satellites\", \"planes\", \"deployed\", \"cost development\", \"cost launch\", \"cost p70\", \"sufficient\"]\n", + "].round(1)" + ] + }, + { + "cell_type": "markdown", + "id": "2c1834ed", + "metadata": {}, + "source": [ + "520 of the 1,096 designs cost at most 150 million dollars at 70% confidence. Along the front, money buys sufficiency in steps:\n", + "\n", + "* one satellite with the narrower imager costs 84 million dollars, of which 44 million develop it, and samples 1% of the points sufficiently;\n", + "* a second satellite costs 97 million in the same plane (3%), and 105 million in a second plane (6%), as each plane needs its own launch;\n", + "* four satellites cost 129 million in two planes (22%), and 144 million in four planes (31%): two more launches buy 9 points, as more planes spread the samples in time;\n", + "* the wider imager joins the front only near the budget, where its development (67 million against 44) is worth its swath: two satellites with it sample 30% of the points for 139 million, and three of them 38% for 149 million, the most within the budget.\n", + "\n", + "The designs that sample nearly every point (six to nine satellites) cost more than the budget. The deployment of each design follows from its satellites and planes: one satellite is launched 3.2 years after development starts, and four satellites in four planes 4.8 years after, as launches are at least half a year apart. The mean cost of development is the same for every design of an imager, as the growth of each replicate is drawn alike for every design." + ] + }, + { + "cell_type": "markdown", + "id": "31bb12ff", + "metadata": {}, + "source": [ + "## Trade Utility against Cost\n", + "\n", + "Sufficiency and accuracy are separate objectives, each in its own units. A stakeholder who values both must weigh them, and a `Utility` makes the weights explicit:\n", + "\n", + "* a utility of each share, from 0 at its worst value to 1 at its best: linear in the share sufficiently sampled (`LinearUtility`), and concave in the share accurately sampled (`ExponentialUtility`), as the first points accurately sampled matter most;\n", + "* weights, which combine the utilities of the shares.\n", + "\n", + "Two stakeholders weigh the shares differently: one mostly sufficiency (0.7 against 0.3), as a center that counts samples for forecasts might, and the other mostly accuracy (0.3 against 0.7), as one that estimates daily means might. A design's utility is that of its mean shares. The figure plots each stakeholder's utility of every design against its cost at 70% confidence, with the front of each stakeholder ringed:" + ] + }, + { + "cell_type": "code", + "execution_count": 4, + "id": "ae075375", + "metadata": { + "execution": { + "iopub.execute_input": "2026-11-15T04:33:53.809265Z", + "iopub.status.busy": "2026-11-15T04:33:53.809093Z", + "iopub.status.idle": "2026-11-15T04:33:53.975889Z", + "shell.execute_reply": "2026-11-15T04:33:53.975244Z" + } + }, + "outputs": [ + { + "data": { + "image/png": "iVBORw0KGgoAAAANSUhEUgAABFcAAAHNCAYAAADbm5R/AAAAOnRFWHRTb2Z0d2FyZQBNYXRwbG90bGliIHZlcnNpb24zLjExLjIsIGh0dHBzOi8vbWF0cGxvdGxpYi5vcmcvgI3uAAAAAAlwSFlzAAAPYQAAD2EBqD+naQABAABJREFUeJzsnQd4G3Xy/t9d9ebuxOm9kCOFQEIJEAik0Hs/COU4ernwvzva/TjugCtA6L33Tmg5Qgsk1ECABEhICOnVcS/q0u7/mZFXyI6d2LJsydZ8IM94ZJXVStZ3NN+ZdxRd13UIgiAIgiAIgiAIgiAISaEmdzNBEARBEARBEARBEARBkiuCIAiCIAiCIAiCIAjtRCpXBEEQBEEQBEEQBEEQ2oEkVwRBEARBEARBEARBENqBJFcEQRAEQRAEQRAEQRDagSRXBEEQBEEQBEEQBEEQ2oEkVwRBEARBEARBEARBENqBJFcEQRAEQRAEQRAEQRDagSRXBKGb8MEHH+Cyyy5r023efvtt/PnPf075/aaLX375BbNmzcLJJ5+M1157jS+bM2cOzjnnHJx44olYt24d/va3v+Hll19u9X12pecvCIIgCJ0Nra8//vhjq68fCAT4NqtWrUrp/QqCIKQbSa4IQify2Wef8Rf/YDDY6PLLL78cF110UaPLIpEITj31VHz44Yetuu/Vq1fj3XffbdPxrFy5kpMHqb7fdBAOh3HIIYfA6/XipJNOwu9+9zt88803fA7Hjx/PNj8/Hx9//DGWL1/e6vvtKs8/XcybNw9XXHFFug9DEARB2AlnnXUW3nnnnUaXkU8JjO+//77R5Q899BD+8pe/tPp80mZGaWlpq69P8Q3dpqKiIqX3K3RtNE3j9+OyZcvSfSiCkDSSXBGETqSkpASvvPIKvvrqq/hllZWVuP/++/H4449j27Zt8csXL16Ml156CT169GjVfU+bNg333ntvyo+5o+431VBVyqZNm/D3v/+dkysjR47kZNbuu+/OlSe0YOfm5uKmm27iBFd3e/7p4tdff8V7772X7sMQBEEQdsKWLVvw3HPPNbrs2Wefxdy5c/HWW281uvyBBx5AfX19q88nxTVjxoxJ+fnvqPsVMje5Qgm1srKydB+KICSNOfmbCoLQVoYOHYp+/fpx9cTkyZP5sgULFnACICcnB5988glXWBB0naKiIowePZr9mpoaPPLII1i6dClfftxxx+HAAw9sVGFBQdKMGTPil/3888948MEHuZpjr732wogRI/Diiy/yrlQiP/zwA1544QVO7kyaNAnnnXceFEVp9n6plWjhwoU488wzW7xNWx47cSeLAr3PP/8cNpsNhx9+OP8jKCCk4/i///u/+PXpXNHj0/199NFH+Pe//82XX3DBBbBarfzzihUrsHXrVk6sJELJlVGjRsX92tpaPPbYY7x716tXL5x//vn8WrV0Xnf1WrT2HLX0uJQkuvLKK3HXXXehT58+8et//fXXmD17Np588knY7fZGz8l4zOOPPx5vvvkmB9IHHXQQt0RRMo/OLZVi07EeeeSRjW5Lj0ev1Zo1a/jx6DgpObWr14Z8On56LOMc0+MdccQRzb7GgiAIQnqYMmUK7rnnnkaX0TpK6w7FGzfccEN8w4diguuuuy5+vf/973+cgAmFQlwJ+sc//jG+zhK0ttMab2wGUXUubRp99913GDBgAK8LtPFB69qee+4Zv53f78edd97Jj0e3pSre3r17N3u/tH79/ve/5zhg/vz5Ld6mtY+dCJ2DqqoqqKrKMRqtk/vvv3+zlZq01tKxHHbYYTvEFi39npIFVJ1MGzW0yWZw+umn46qrruLjMp4ftS7T+f7pp5/497Setvf46JwNGjSIz0XT5033ZcRaBsaxUNs4bVLRsdC5pnNIscd9993Hlc/02lArttPpjN82Go1yzEavER3v9OnTOeZKjH2WLFmCZ555BuXl5RzjXnjhhXC73Tj33HP59/ReLC4u5niE4iBB6EpI5YogdDIHH3wwBzIG9DN9CaZkS3OX04JECzMtvvTlmlpfaHE+4YQT+At+S+0rVFGw9957c3Jhv/3244WOFlpKFCRCt6MkAC3Ye+yxB6655hrceOONLd4vLaj0RXxnt2ntYydCC/Qtt9zC90c7VfQYDz/8MP+Oeq4pcdC0UsW4vyFDhvACTlCgQAkq+keLdmFhYdynf1RumtgWRIkPekyqEtp33305WULHapQrN33+rXktWnOOdva4ffv25WN86qmnGj1nCoxpN7FpYsV4TNptpOQSBVGUPLrkkktw1FFH4eKLL8bYsWMxcOBAPtb333+/UWKFjoMC1UMPPZRLsCl4psB0V68NBa50LjweT/z8UrAlCIIgZF7sQesObXwQtMbQ5gd9vlMCnr5QGwkX4/oEtQddeuml/Nl+wAEH4PXXX+fNBEq6t9S+Q2sBfSneZ5994HK5OJahjQaKCRI544wzsHnzZo5/6As3xQvGcTS9X6OViDY6dnab1j52IscccwzfjtZHug0lG5pqs1EShJIEtFbTY9LvE7/47+z3dJ7p2JtWA9G5NI7LeH5ULbt9+3Zeu431tL3HR3EQxR+6rsevT5sjVDFNLdRNMY6FjoFiHnq9KY6jc05JOjrfZOkxKAmTCCVIrr76ao4X6L4p/vjTn/4U/z29ZhTzmM1mTJ06lWMeY8OH4jeC7puer2zUCF0SXRCETuWJJ57QrVar7vP52N999931OXPm6B988IE+bNgwviwUCulOp1O/77772L/ooov0Y445ptH9vPrqq3p+fr6uaRr7DzzwgD5kyJD4788++2z9wAMPbHSbAw44QO/Tp0/cv/XWW3WLxaJv3Lgxftns2bP1oUOHxv2m99ua27TmsZtCj/H00083uqysrIztX//6V/2QQw7Z4Twm3t/3339PUUP8NsQ///lPfe+99250u0mTJuk33HBD3D///PP1UaNG6eFwOH5ZfX297vf7m33+rXktWnOOdvW4t99+e6Pr19TU6A6HQ3/ttdeaPX/0mPS+2rRpU/yyc845h29TWloav+ykk07SZ86cGff/8Ic/6BMmTIgfO3Hsscfqhx56aKtem3vuuUcfMWJEs8ckCIIgZAa01rjd7nhcce+99+rTp0+Pf8Z/9NFH/POll16qjx49mn9esmQJr2UbNmyI308gEOC194UXXohfRmsvxTDEV199pSuKov/000/x3z/33HN8nbfffpv9uro69v/xj380WuPMZrP+4YcfNnu/rblNax67Ndx99936HnvsEfe//fZbvg/jHBmUl5e36vdr167l369atarR72022w7n5C9/+UvKj6+iooIfyziXxLnnnqtPnTq12fs3joViKINFixbxZRRrGNDj0fk24tlvvvmGr7N48eL4debNm6ebTCZ95cqV7NPt99tvv2bjCXqP0u0//vjjXZ4DQchUpC1IEDoZ2g2i0tovv/ySqwBoF4l2BagagaoxaEeGrM/n4+y9UepJeiGUyad4g/7V1dVxmShVHlB1RFPo/qnkM5Gjjz6aS3AToaoPqpRI9OkYdsaubtPax06EqiXuuOMOfp60O0KWdmA6Gqri+MMf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998PRx55OL766kusXbsGq1atwquvvorx48fh5JNPRDQaRVZprrSFDRs2cPvPwIEDG11O/qefftri7YLBIP8zMKaikEJxd1Qpbg3G887W50/IOYjh9wewefMmttn6fpD3gpwDeR907N/DJ598gu++W8w72JMmHYC99toLqUZV07dfJHHGjsjnqpwDA4kz5L0gnwnyuZjIypUrcPfdd+KLL75slPxQFAUHHHAgLrzwQuy++2jsjM8++wwXX3xho8scDgevPcb3fpIR2XfffbBw4acpqWJpTZzRpZIrfr+frcvlanS5x+OJ/645/vWvf+HGG2/c4fLy8lIEgz5kM2Vlu9a56e5k+zmoqqposOVQVR3ZTLa/Fwg5B3IOCK/Xi7feepgDH9qQoNbB3XffHUcccThXjLYGCphuvvnmHYKnxx57DBaLBYcffjguvfSSlL13e/Xqi3QhcUbLyGeKnAOJM+TvQT4T5HPR4LvvvscNN9yAQCDAPg2zobiioqKCtVUXLlyAL7/8Atdddy0mTZqE5qDv/ZdcclHcnzFjOq688sq4xMHWrVtx/fV/48IMn8+LI444jKtjOiPO6FLJlZycHLbV1dWNLq+srERubm6Lt7vmmmswa9asuE+BYr9+/VBU1BN5eXnIRiirRwFPcXFJWnf70omcA+M8KGzz84vQs2cvZCPyXpBzIO+D33j++edw11137rBp8eOPP+Kll17C0Ucfjeuu+xtsNluLf1N020MOmYL6+rpmf09VqG+++Sa++WYx5s17D10diTN2RD5X5Rz89l6QOEP+HuTvQT4XwdooVPBAiZU99tgD1113PYYPH9Ho93fcMRsffzwft9zyLzz99LMYNWrUDuvLVVf9Cboe2xD+97//jcMPP5J/po2cjf5qjB49Du+88z+cddaZWLLke24/CoUi6NevPzqaLpVcoYQIJVGWLVuGww47LH45ZbloR60lKABsLgikpEK2JhYM5BzIOVBVJW7l70E+E+QzIbs/Ex5++CHcffdd/POgQYNw0kkno3//Aaipqcbbb7+Fr776Cm+88Qa2by/DfffdzxUozXHYYdPjiZXCwiJcc821mDFjBvvPPfcs7rnnbtTX12PLls046aQT8Nprc9CVkTijZbL578kg28+BxBmJ5yK73wuEnIPsPQfPPPMUfD4fxo/fEzfd9A/07TuAzwMlSnzR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CnAOPHAy22z4e+Dxi9++D3hrYsGCtwbh7z4Axhya9r8H0hwhjZWv/etZxd+smrBbTgnCig6LqnIrUGmwDtUhf7xthoRvqyOBlAncpvscGK+Roit8HOnQxMmEc5AJyHloPRJnyPtI/pZahuKLY445FocddiSee+45vPXWmzwRiP4RAwcO5FagE044kcVv26ohUh32N1oryA/qUW4R2hnuZgTj243dBdXphl7vjI2LNlnYV+1OoK427Z+rPPVHBxL7Bqho2Wm2IaBH+PI98vvGYwzyW3Mu20K6z0EmIOeg+56HtLYF0XSgs88+m0Vt9913X9x6662cOLnooovi17nsssvw1VdfcabbmBZE45qnTp2KSZMmsT7LE088gZtvvjmNz0QQui7cW+v17qDr0W0J+psfAxlOv0A29YKv81VAhcJBDVnyqRecKLQ4EYxGOOghyJKfb2nflJ5MYrOvGnM2LY2PyDyu71gesykIgiB07ThjwIDBuPba63DllX/C6tW/wl9bg/weJRg6dGjSiXT60k9rRVMNlXSJsCqhANTcYkQrtlIPDleukK9kQIxBFNvcoLmQldS1RMerAzkKUGhzcWWRcS5pWmG6z6UgdEXS+k3qtNNOwwMPPMDtPJRcIYFaqlzp1atX/DqUwc7J+W087KGHHspZbxrVTP2a1Oc8e/ZsXH755Wl6FoLQtSkvL2OFfrJZAU0IaphSYMA+7eakGapMCURJd6phmpEC9isbgkbaVRqT17vRNB3yaVepO0AVK0ZihSBLfqKooSAIgtC14wxboBZDtnyH3237Fn3WfA6tqrFEQFugtZKS8LTJENZimw3k7ypZQ+sKVb2ken3RrXbovloorjwoOUVsydczIMYg/P46FOkKqD6IalHIkh8I1P92Lhs03owNjkyaqigImU7aBW3PPfdc/tcSd9999w6XHXPMMfxPEAShrRhjIANfvwu9phxKbhGse00HwulXLHeaLDCR1krDlAQK+cg3do1oh2633F7oYfPweGJKrhTa3d1mV8kYkZmIMSIzW8ZRC4IgdGdobQt+My9eQUqWfMe0me36Eh9LkSgNNn0VklS5ojhzoG1ZG59sZO7ZP2MqV2CzwwoFjkgUFugwQ4HVbObjJOg8XDLswLTonglCdyALegAEQRB2RCEVN6oOIZshuMw2FFqdiELnlh+y5BuJBWNXiRIq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", + "text/plain": [ + "
" + ] + }, + "metadata": {}, + "output_type": "display_data" + } + ], + "source": [ + "from tatc.tradespace import ExponentialUtility, LinearUtility, Utility, pareto_front, style_axes\n", + "\n", + "CURVES = {\"sufficient\": LinearUtility(0, 100), \"accurate\": ExponentialUtility(0, 100, risk=2)}\n", + "STAKEHOLDERS = {\n", + " \"sufficiency\": Utility(CURVES, weights={\"sufficient\": 0.7, \"accurate\": 0.3}),\n", + " \"accuracy\": Utility(CURVES, weights={\"sufficient\": 0.3, \"accurate\": 0.7}),\n", + "}\n", + "means = summarize(results, statistics=[\"sufficient\", \"accurate\", Quantile(\"cost\", 0.7)])\n", + "means = means.set_index(\"design\")\n", + "\n", + "fig, axes = plt.subplots(1, 2, figsize=(11, 4.5), sharey=True)\n", + "judged = {}\n", + "for ax, (name, utility) in zip(axes, STAKEHOLDERS.items()):\n", + " judged[name] = means.assign(utility=utility(means))\n", + " judged[name][\"pareto\"] = pareto_front(judged[name], {\"utility\": \"max\", \"cost p70\": \"min\"}) # of the utility\n", + " legend = \"lower right\" if ax is axes[0] else None\n", + " groups = means.planes.clip(upper=3) # 3 or 4 planes share a color\n", + " plot_designs(judged[name], \"cost p70\", \"utility\", by=groups, names=PLANE_GROUPS, legend=legend, ax=ax)\n", + " ax.axvline(BUDGET, color=GRAY, lw=1, ls=\"--\")\n", + " ax.set(xlabel=\"Cost at 70% confidence (millions of dollars)\", ylabel=\"Utility\", ylim=(0, 1.02))\n", + " ax.set_title(f\"Weighing {name} most\")\n", + " style_axes(ax, grid=\"both\")\n", + "plt.show()" + ] + }, + { + "cell_type": "markdown", + "id": "9c9af0ac", + "metadata": {}, + "source": [ + "The stakeholders' fronts share most of their designs. Those efficient for one stakeholder and not the other:" + ] + }, + { + "cell_type": "code", + "execution_count": 5, + "id": "ab147572", + "metadata": { + "execution": { + "iopub.execute_input": "2026-11-15T04:33:53.977109Z", + "iopub.status.busy": "2026-11-15T04:33:53.976977Z", + "iopub.status.idle": "2026-11-15T04:33:53.983429Z", + "shell.execute_reply": "2026-11-15T04:33:53.983029Z" + } + }, + "outputs": [ + { + "name": "stdout", + "output_type": "stream", + "text": [ + "18 designs are efficient for both\n" + ] + }, + { + "data": { + "text/html": [ + "
\n", + "\n", + "\n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + "
descriptionsatellitesplanessufficientaccuratecost p70utility (sufficiency)efficient (sufficiency)utility (accuracy)efficient (accuracy)
design
aa335914661d800 km, 30 deg FOR, SSO: 1 at 09:00, 2 at 15:00326.615.4117.100.14True0.23False
d724deb26c78800 km, 30 deg FOR, SSO: 1 at 12:00, 2 at 18:00324.416.2117.100.13False0.24True
87addc291d43800 km, 60 deg FOR, SSO: 1 at 09:00, 2 at 15:003228.860.6156.650.45False0.66True
6ba50f2632cd800 km, 60 deg FOR, Walker 45 deg: 2 x 2 (spac...4269.665.4173.730.74True0.80False
904a205f7cd9800 km, 60 deg FOR, SSO: 2 at 09:00, 2 at 15:004257.685.4173.730.69False0.84True
7d5b745cf8f6800 km, 60 deg FOR, Walker 45 deg: 4 x 1 (spac...4468.671.2188.730.74True0.82False
64cf6542c326800 km, 60 deg FOR, Walker 75 deg: 3 x 2 (spac...6390.295.8213.530.93False0.96True
\n", + "
" + ], + "text/plain": [ + " description satellites \\\n", + "design \n", + "aa335914661d 800 km, 30 deg FOR, SSO: 1 at 09:00, 2 at 15:00 3 \n", + "d724deb26c78 800 km, 30 deg FOR, SSO: 1 at 12:00, 2 at 18:00 3 \n", + "87addc291d43 800 km, 60 deg FOR, SSO: 1 at 09:00, 2 at 15:00 3 \n", + "6ba50f2632cd 800 km, 60 deg FOR, Walker 45 deg: 2 x 2 (spac... 4 \n", + "904a205f7cd9 800 km, 60 deg FOR, SSO: 2 at 09:00, 2 at 15:00 4 \n", + "7d5b745cf8f6 800 km, 60 deg FOR, Walker 45 deg: 4 x 1 (spac... 4 \n", + "64cf6542c326 800 km, 60 deg FOR, Walker 75 deg: 3 x 2 (spac... 6 \n", + "\n", + " planes sufficient accurate cost p70 utility (sufficiency) \\\n", + "design \n", + "aa335914661d 2 6.6 15.4 117.10 0.14 \n", + "d724deb26c78 2 4.4 16.2 117.10 0.13 \n", + "87addc291d43 2 28.8 60.6 156.65 0.45 \n", + "6ba50f2632cd 2 69.6 65.4 173.73 0.74 \n", + "904a205f7cd9 2 57.6 85.4 173.73 0.69 \n", + "7d5b745cf8f6 4 68.6 71.2 188.73 0.74 \n", + "64cf6542c326 3 90.2 95.8 213.53 0.93 \n", + "\n", + " efficient (sufficiency) utility (accuracy) \\\n", + "design \n", + "aa335914661d True 0.23 \n", + "d724deb26c78 False 0.24 \n", + "87addc291d43 False 0.66 \n", + "6ba50f2632cd True 0.80 \n", + "904a205f7cd9 False 0.84 \n", + "7d5b745cf8f6 True 0.82 \n", + "64cf6542c326 False 0.96 \n", + "\n", + " efficient (accuracy) \n", + "design \n", + "aa335914661d False \n", + "d724deb26c78 True \n", + "87addc291d43 True \n", + "6ba50f2632cd False \n", + "904a205f7cd9 True \n", + "7d5b745cf8f6 False \n", + "64cf6542c326 True " + ] + }, + "execution_count": 5, + "metadata": {}, + "output_type": "execute_result" + } + ], + "source": [ + "compared = means[[\"description\", \"satellites\", \"planes\", \"sufficient\", \"accurate\", \"cost p70\"]].copy()\n", + "for name in STAKEHOLDERS:\n", + " compared[f\"utility ({name})\"] = judged[name][\"utility\"]\n", + " compared[f\"efficient ({name})\"] = judged[name][\"pareto\"]\n", + "print(\n", + " f\"{(compared['efficient (sufficiency)'] & compared['efficient (accuracy)']).sum()} designs are efficient for both\"\n", + ")\n", + "compared[compared[\"efficient (sufficiency)\"] != compared[\"efficient (accuracy)\"]].sort_values(\"cost p70\").round(2)" + ] + }, + { + "cell_type": "markdown", + "id": "ed863e18", + "metadata": {}, + "source": [ + "Within the budget, the stakeholders nearly agree, as more satellites in more planes buy both shares: they part only on two designs of three satellites in two sun-synchronous planes with a 30-degree field of regard, which cost the same (117 million dollars), of which the stakeholder of sufficiency prefers the planes crossing at 09:00 and 15:00 and the stakeholder of accuracy those crossing at 12:00 and 18:00. Beyond the budget, they part more. For 174 million dollars at 70% confidence, the stakeholder of sufficiency prefers four satellites in two Walker planes (70% of the points sufficiently sampled, and 65% accurately), and the stakeholder of accuracy four satellites in two sun-synchronous planes crossing at 09:00 and 15:00 (58% and 85%), whose planes spread the samples over the day. The stakeholder of accuracy also finds three satellites in two sun-synchronous planes efficient for 157 million, and six satellites in three Walker planes for 214 million, which the stakeholder of sufficiency passes over." + ] + }, + { + "cell_type": "markdown", + "id": "181031eb", + "metadata": {}, + "source": [ + "## Summary\n", + "\n", + "* A `CostModel` estimates the life-cycle cost of each design from the costs of its satellites, launches, and operations, and a `DeploymentSchedule` dates them by the deployment that it plans from rates of production and launch. A `MissionPlan` combines them in a study.\n", + "* Uncertain growth of costs makes the cost at a confidence level (a `Quantile` over the replicates) an objective, and a budget a `Requirement`, in place of the numbers of satellites and planes.\n", + "* A `Utility` weighs metrics by a stakeholder's preferences into one objective, to trade against cost.\n", + "\n", + "The next notebook, `PlanDeployment`, accounts for the years over which each design is deployed." + ] + }, + { + "cell_type": "markdown", + "id": "0323bd05", + "metadata": {}, + "source": [ + "## Notes\n", + "\n", + "* Cost risk has more structure than one factor of growth: the components of satellites grow by their maturity, their growths are correlated, and designs that share components share their growth. `ValidateCostVarianceNSOSA` (in the validation notebooks) models these with `Component`, `Triangular`, and `risk_space`, and compares designs by the probability that one costs more than another (`exceedance`).\n", + "* Five replicates make the 0.7 quantile of each design's cost a coarse estimate. An evaluation of the cost alone, which costs little more than the cost model, could draw many more replicates.\n", + "* The results also give the present value of each design's cost (`cost present`, discounted at 3% a year) and the cost of its most expensive year (`cost peak annual`), for annual budgets.\n", + "* A utility is a metric of any statistic, such as `Quantile(utility, 0.1)`: the utility that a design exceeds in 90% of the replicates. A multiplicative utility (`form=\"multiplicative\"`) makes the shares complements, both of which a design must serve, or substitutes." + ] + } + ], + "metadata": { + "kernelspec": { + "display_name": "Python 3 (ipykernel)", + "language": "python", + "name": "python3" + }, + "language_info": { + "codemirror_mode": { + "name": "ipython", + "version": 3 + }, + "file_extension": ".py", + "mimetype": "text/x-python", + "name": "python", + "nbconvert_exporter": "python", + "pygments_lexer": "ipython3", + "version": "3.14.10" + } + }, + "nbformat": 4, + "nbformat_minor": 5 +} diff --git a/docs/examples/tradespace/index.rst b/docs/examples/tradespace/index.rst new file mode 100644 index 0000000..25bac19 --- /dev/null +++ b/docs/examples/tradespace/index.rst @@ -0,0 +1,46 @@ +==================== +Trade Space Tutorial +==================== + +These notebooks follow one trade study with the ``tatc.tradespace`` module +from start to finish: how many satellites, in how many orbit planes, an +imager needs to observe the Earth often enough. Each notebook adds one idea +to those before it, so read them in order: + +#. :doc:`EvaluateTradeSpace`: declare a design space and a study, evaluate + every design, and find the Pareto-efficient designs. +#. :doc:`ExplainTradeSpace`: measure sampling by its error, explain why + designs differ, and find the decisions that drive the objectives. +#. :doc:`SearchTradeSpace`: find the efficient designs of larger spaces by + screening with a cheaper study and by searching with optimizers. +#. :doc:`RankUncertainDesigns`: rank designs with the uncertainty of their + replicates, refine and confirm the front, and require reliable + performance. +#. :doc:`CompareScenarios`: compare designs under conditions that are not + known in advance, and find designs robust to them. +#. :doc:`TradeCostAndUtility`: estimate life-cycle costs with uncertain + growth, trade them within a budget, and weigh objectives by utility. +#. :doc:`PlanDeployment`: account for the phases of each design's + deployment, and stage it. +#. :doc:`PlanForFailures`: simulate failures, choose restoration policies + with the designs, and find what spreads the results. + +The notebooks import the design space and the study of the first notebook, +and the parts of later notebooks that the notebooks after them use, from +``trade_space_example.py`` beside them. Each study keeps its results in a +store, from which a notebook takes the evaluations of the notebooks before it +where their studies are the same. The notebooks require:: + + pip install tatc[tradespace] + +.. toctree:: + :hidden: + + EvaluateTradeSpace.ipynb + ExplainTradeSpace.ipynb + SearchTradeSpace.ipynb + RankUncertainDesigns.ipynb + CompareScenarios.ipynb + TradeCostAndUtility.ipynb + PlanDeployment.ipynb + PlanForFailures.ipynb diff --git a/docs/examples/tradespace/trade_space_example.py b/docs/examples/tradespace/trade_space_example.py new file mode 100644 index 0000000..d88b98c --- /dev/null +++ b/docs/examples/tradespace/trade_space_example.py @@ -0,0 +1,179 @@ +""" +The trade space of the trade space tutorial, which its notebooks import: the +parts that a notebook defines and later notebooks use, under the name of the +notebook that defines and explains them. + +@author: Paul T. Grogan +""" + +import tempfile +from datetime import datetime, timedelta, timezone +from pathlib import Path + +from tatc.analysis import estimate_sampling_error +from tatc.generation import generate_points_fibonacci_lattice +from tatc.schemas import Instrument +from tatc.tradespace import ( + Categorical, + Choice, + CostModel, + DeploymentSchedule, + DesignSpace, + Integer, + LaunchCost, + MissionPlan, + ObservationStudy, + Observations, + OperationsCost, + Real, + ResultStore, + SatelliteCost, + Targets, + Uncertain, + build_constellation, + count_satellites, + layout_of, + sso_planes_space, + walker_space, +) + +# EvaluateTradeSpace: the design space, and the study of sufficient sampling + +START = datetime(2026, 7, 1, tzinfo=timezone.utc) +DURATION = timedelta(days=1) # the period of the analysis +N_POINTS = 100 # points sampled in each replicate +N_REPLICATES = 5 # replicates (samples of points) of each design +SAMPLES_PER_DAY = 4 # observations a day of a sufficiently sampled point +MAX_SATELLITES = 10 + +space = DesignSpace( + altitude=Real(500e3, 800e3, step=100e3), + field_of_regard=Categorical([30, 60]), + layout=Choice( + walker=walker_space( + inclination=Real(45, 75, step=15), + planes=Integer(1, 4), + per_plane=Integer(1, 4), + ), + sso=sso_planes_space( + crossing=Real(6, 18, step=3), + planes=Integer(1, 2), + per_plane=Integer(1, 2), + ), + ), + points_seed=Uncertain.seed(), + constraints=[lambda d: count_satellites(d.layout) - MAX_SATELLITES], +) +designs = space.enumerate() + + +def build(d): + """The satellites of a design: an imager in each orbit of its layout.""" + imager = Instrument(name="imager", field_of_regard=d.field_of_regard) + return build_constellation(d.layout, imager, epoch=START, altitude=d.altitude) + + +def count_samples(observations, duration=DURATION): + """The share (%) of points observed at least SAMPLES_PER_DAY times a day.""" + if len(observations) == 0: # no satellites + return {"sufficient": 0.0} + samples = observations.groupby("target_hash").size() + threshold = SAMPLES_PER_DAY * duration / timedelta(days=1) + return {"sufficient": 100 * (samples >= threshold).sum() / N_POINTS} + + +def describe(d): + """A short description of a design: its altitude, field of regard, and layout.""" + return f"{d.altitude / 1e3:.0f} km, {d.field_of_regard} deg FOR, {layout_of(d.layout).describe()}" + + +CACHE_DIRECTORY = Path(tempfile.gettempdir()) / "tatc-trade-space" +# the points of each replicate: a lattice in a random orientation, from its seed +TARGETS = Targets( + generate_points_fibonacci_lattice, count=N_POINTS, rotate=True, seed="points_seed" +) +OBSERVATIONS = Observations(TARGETS, START, DURATION, directory=CACHE_DIRECTORY) + +study = ObservationStudy( + space, + build, + OBSERVATIONS, + count_samples, + replicates=N_REPLICATES, + n_jobs=-1, + store=ResultStore(CACHE_DIRECTORY / "results.sqlite"), + describe=describe, # a description column in the results +) +OBJECTIVES = {"satellites": "min", "planes": "min", "sufficient": "max"} + + +def planes_name(planes): + """The name of a number of planes.""" + return f"{planes:.0f} plane{'s' if planes > 1 else ''}" + + +# the groups of numbers of planes that color the designs of plots (by +# `planes.clip(upper=3)`): at most three colors, which readers with color vision +# deficiencies tell apart in a scatter of designs +PLANE_GROUPS = {1: "1 plane", 2: "2 planes", 3: "3 or 4 planes"} + + +# ExplainTradeSpace: the study of accurate sampling as well + +DECORRELATION_TIME = timedelta(hours=3) # of the field whose daily mean is estimated +MAX_RELATIVE_ERROR = 0.5 # of an accurate sample, in standard deviations of the field + + +def sample(observations, decorrelation_time=DECORRELATION_TIME): + """The shares (%) of points sampled sufficiently and accurately.""" + if len(observations) == 0: # no satellites + return {"sufficient": 0.0, "accurate": 0.0} + samples = observations.groupby("target_hash").size() + end = START + DURATION + error = estimate_sampling_error(observations, START, end, decorrelation_time) + return { + "sufficient": 100 * (samples >= SAMPLES_PER_DAY).sum() / N_POINTS, + "accurate": 100 * (error.relative_error <= MAX_RELATIVE_ERROR).sum() / N_POINTS, + } + + +accuracy_study = study.replace(metrics=sample) +ACCURACY = {"satellites": "min", "planes": "min", "accurate": "max"} + +# CompareScenarios: fields of other decorrelation times + +FIELDS = { + "1 hour": {"decorrelation_time": timedelta(hours=1)}, + "3 hours": {}, + "12 hours": {"decorrelation_time": timedelta(hours=12)}, +} + + +def sample_field(observations, design): + """The shares (%) of points sampled sufficiently and accurately (of its field).""" + return sample(observations, design.decorrelation_time) + + +# TradeCostAndUtility: the deployment and cost of each design + +SCHEDULE = DeploymentSchedule( + years=5, + development_years=3, + production_rate=4, + launch_interval=0.5, + launch_capacity=3, +) +COST_MODEL = CostModel( + satellites={ + 30: SatelliteCost(development=40, first_unit=12, learning_rate=0.9), + 60: SatelliteCost(development=60, first_unit=18, learning_rate=0.9), + }, + launch=LaunchCost(per_launch=8), + operations=OperationsCost(per_year=3, per_satellite_year=0.5), + discount_rate=0.03, +) +PLAN = MissionPlan( + SCHEDULE, COST_MODEL, kind="field_of_regard", growth={"development": "cost_growth"} +) +cost_space = space.extend(cost_growth=Uncertain.triangular(0.9, 1.0, 1.6)) +cost_study = accuracy_study.replace(space=cost_space, plan=PLAN) diff --git a/docs/validation/ValidateCostVarianceNSOSA.ipynb b/docs/validation/ValidateCostVarianceNSOSA.ipynb new file mode 100644 index 0000000..4871a99 --- /dev/null +++ b/docs/validation/ValidateCostVarianceNSOSA.ipynb @@ -0,0 +1,2015 @@ +{ + "cells": [ + { + "cell_type": "markdown", + "id": "0c531f02", + "metadata": {}, + "source": [ + "# Cost Variance Validation: NSOSA Constellations\n", + "\n", + "Architecture studies of satellite constellations compare alternatives whose costs are uncertain and correlated: alternatives that share a satellite design share its cost risk. Maier, Yeakel, and Wendoloski (\"Cost Variance Analysis in Constellation Architecture Studies,\" *IEEE Systems Journal* 17(2), 1928–1938, 2023, [doi:10.1109/JSYST.2022.3218598](https://doi.org/10.1109/JSYST.2022.3218598)) model the uncertain cost of each satellite configuration from the growth of its components by their maturity (the formal risk assessment of system cost estimates, FRISK). They extend it to constellations whose configurations are produced in blocks over decades, and work through two constellations of the NOAA Satellite Observing System Architecture (NSOSA) study that share a geostationary configuration, whose order of cost depends on what they share. TAT-C's `tradespace` module models the same structure: the growth of components by maturity (`Triangular`, `Component`), correlated within a cost model (`CostModel.correlation`); types of satellites produced in blocks (`SatelliteCost.block_size`); deployments from launch schedules (`DeploymentSchedule`); and scores of the cost risk drawn as uncertain parameters (`risk_space`, `CostModel.draw`), which common random numbers share between the designs of a `Study`, compared with `exceedance`. This notebook reproduces the paper's example and asks:\n", + "\n", + "1. **Growth by maturity.** Do `Triangular` growths reproduce the cost growth factors of Table I, and does `CostModel.correlation` reproduce the variance of a configuration of correlated components (eq. 2)?\n", + "2. **Production blocks.** Does `DeploymentSchedule` reproduce the launches and production blocks of the configurations from their launch schedules (Tables II and III), and does `CostModel.estimate` count the developments, first units, and later units of each constellation over the study period (matrix *B* of eq. 5)?\n", + "3. **Constellation costs.** Do the replicates of a `Study` reproduce the means, variances, and covariance of the costs of the two constellations (eqs. 6 and 8, Fig. 2)?\n", + "4. **Order of costs.** Does `exceedance` reproduce the probability that one constellation costs more than the other (eqs. 9 to 15, Fig. 3), and how much of it comes from the configuration they share?\n", + "\n", + "The paper's other results are not reproduced. Its efficient frontier and rank-swap matrix of NSOSA constellations (Figs. 1 and 4) need costs of constellations that were not published, and its comparison with the GOES-R and JPSS programs (Figs. 5 and 6) needs the Aerospace Concept Design Center's cost models and the programs' historical costs. Costs are relative, as in the paper: multiples of the annual cost of the least expensive NSOSA constellation." + ] + }, + { + "cell_type": "markdown", + "id": "fb98d147", + "metadata": {}, + "source": [ + "## Reference Data\n", + "\n", + "The reference values are those published in the paper:\n", + "\n", + "* **Table I** gives the cost growth factors of components by maturity (new, major modification, modified, minor modification, and existing): the lowest, most likely (1), and highest growth of a triangular distribution, and its mean.\n", + "* **Table II** gives the configurations of the two constellations. C1 flies the geostationary configuration G4c (an advanced GOES-R) on a 48-month launch schedule from April 2029, and the large low Earth orbit (LEO) configuration L3e every 54 months from July 2032. C2 flies G4c every 32 months from April 2029, and the smaller LEO configuration L4f \"46 (x2) months\" from July 2028, read here as two satellites every 46 months. Each configuration is produced in blocks of four satellites.\n", + "* **Eq. (5)** gives the matrix *A* of the shares of a block's cost in its development (Dev), the production and launch of its first unit (T1), and of each later unit (Ta), and the matrix *B* of the number of each in each constellation from 2020 to the end of September 2050 (Table III shows how G4c's numbers in C1 are counted).\n", + "* **Eqs. (6) and (7)** give the expected cost of a block of each configuration, E[*Q*], and its variance (*R*), uncorrelated between configurations. The variances are in millionths of the squared relative cost: the standard deviation of a block of G4c is 0.0997.\n", + "\n", + "From these, the expected costs of the constellations are E[*C*] = *BA* E[*Q*] (eq. 6) and their covariance *BARA*ᵀ*B*ᵀ (eq. 8). The probability that C2 costs more than C1 is the integral of their bivariate normal distribution above the line *y* = *x* (eq. 15), computed here both numerically and in closed form (the normal probability of the mean difference over the standard deviation of the difference). The published results are the expected costs and standard deviations (eq. 6 and Fig. 2), the covariance matrix (eq. 8), and the probability (Fig. 3)." + ] + }, + { + "cell_type": "code", + "execution_count": 1, + "id": "713ba549", + "metadata": { + "execution": { + "iopub.execute_input": "2026-11-13T19:42:53.191079Z", + "iopub.status.busy": "2026-11-13T19:42:53.191079Z", + "iopub.status.idle": "2026-11-13T19:42:54.678456Z", + "shell.execute_reply": "2026-11-13T19:42:54.677459Z" + } + }, + "outputs": [ + { + "name": "stdout", + "output_type": "stream", + "text": [ + "P(C2 > C1): 0.9779 by eq. (15), 0.9779 in closed form; 0.9491 if the costs were independent\n" + ] + }, + { + "data": { + "text/html": [ + "
\n", + "\n", + "\n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + "
publishedfrom the published inputs
E[C1]8.2708.2592
E[C2]8.9308.9275
std C10.3400.3408
std C20.2300.2253
var C1 (millionths)116118.000116118.1421
cov C1, C2 (millionths)28260.00028260.8967
var C2 (millionths)50757.00050757.8163
P(C2 > C1)0.9780.9779
\n", + "
" + ], + "text/plain": [ + " published from the published inputs\n", + "E[C1] 8.270 8.2592\n", + "E[C2] 8.930 8.9275\n", + "std C1 0.340 0.3408\n", + "std C2 0.230 0.2253\n", + "var C1 (millionths) 116118.000 116118.1421\n", + "cov C1, C2 (millionths) 28260.000 28260.8967\n", + "var C2 (millionths) 50757.000 50757.8163\n", + "P(C2 > C1) 0.978 0.9779" + ] + }, + "execution_count": 1, + "metadata": {}, + "output_type": "execute_result" + } + ], + "source": [ + "import math\n", + "\n", + "import matplotlib.pyplot as plt\n", + "import numpy as np\n", + "import pandas as pd\n", + "from scipy import integrate, stats\n", + "\n", + "BLUE, ORANGE, GRAY, INK = \"#2a78d6\", \"#eb6834\", \"#8a8a86\", \"#2b2b29\"\n", + "\n", + "# Table I: the lowest and highest cost growth factors of components by maturity (most likely 1), and their mean\n", + "TABLE_I = pd.DataFrame(\n", + " {\n", + " \"low\": [0.827, 0.864, 0.904, 0.943, 0.981],\n", + " \"high\": [2.274, 1.993, 1.708, 1.423, 1.140],\n", + " \"mean\": [1.367, 1.286, 1.204, 1.122, 1.041],\n", + " },\n", + " index=pd.Index(\n", + " [\"new\", \"major modification\", \"modified\", \"minor modification\", \"existing\"],\n", + " name=\"maturity\",\n", + " ),\n", + ")\n", + "# eq. (5), matrix A: the shares of the cost of a block in its development, first unit, and each later unit\n", + "SHARES = {\n", + " \"G4c\": (0.309, 0.132, 0.115),\n", + " \"L3e\": (0.290, 0.126, 0.110),\n", + " \"L4f\": (0.217, 0.054, 0.047),\n", + "}\n", + "# eq. (6): the expected cost of a block, E[Q]; eq. (7): its variance, R (published in millionths)\n", + "MEAN_Q = {\"G4c\": 3.33, \"L3e\": 3.14, \"L4f\": 1.61}\n", + "VARIANCE_Q = {\"G4c\": 9930e-6, \"L3e\": 71900e-6, \"L4f\": 5260e-6}\n", + "# eq. (5), matrix B: the developments, first units, and later units of each configuration of each constellation\n", + "PUBLISHED = {\n", + " \"C1\": {\"G4c\": (2, 2, 4.37), \"L3e\": (2, 2, 3)},\n", + " \"C2\": {\"G4c\": (3, 3, 6.37), \"L4f\": (2.9, 2.9, 10.8)},\n", + "}\n", + "CONSTELLATIONS = list(PUBLISHED)\n", + "CONFIGURATIONS = list(MEAN_Q)\n", + "\n", + "\n", + "def exposures(counts):\n", + " \"\"\"The matrix BA: the multiple of the cost of a block of each configuration in each constellation.\"\"\"\n", + " return np.array(\n", + " [\n", + " [np.dot(counts[name].get(c, (0, 0, 0)), SHARES[c]) for c in CONFIGURATIONS]\n", + " for name in CONSTELLATIONS\n", + " ]\n", + " )\n", + "\n", + "\n", + "def moments(counts, correlated=True):\n", + " \"\"\"The expected costs of the constellations (eq. 6) and their covariance (eq. 8), or only their variances.\"\"\"\n", + " ba = exposures(counts)\n", + " mean = ba @ np.array([MEAN_Q[c] for c in CONFIGURATIONS])\n", + " covariance = ba @ np.diag([VARIANCE_Q[c] for c in CONFIGURATIONS]) @ ba.T\n", + " return mean, covariance if correlated else np.diag(np.diag(covariance))\n", + "\n", + "\n", + "def probability_exceeds(mean, covariance):\n", + " \"\"\"The probability that the second cost exceeds the first: eq. (15) integrated numerically, and in closed form.\"\"\"\n", + " sx, sy = np.sqrt(np.diag(covariance))\n", + " rho = covariance[0, 1] / (sx * sy)\n", + " sigma = sy * math.sqrt(1 - rho**2) # eq. (12)\n", + "\n", + " def integrand(x):\n", + " mu = mean[1] + sy / sx * rho * (x - mean[0]) # eq. (11)\n", + " return stats.norm.pdf(x, mean[0], sx) * stats.norm.sf(x, mu, sigma)\n", + "\n", + " numerical = integrate.quad(integrand, mean[0] - 12 * sx, mean[0] + 12 * sx)[0]\n", + " spread = math.sqrt(covariance[0, 0] + covariance[1, 1] - 2 * covariance[0, 1])\n", + " return numerical, stats.norm.cdf((mean[1] - mean[0]) / spread)\n", + "\n", + "\n", + "mean, covariance = moments(PUBLISHED)\n", + "numerical, closed = probability_exceeds(mean, covariance)\n", + "independent = probability_exceeds(*moments(PUBLISHED, correlated=False))[1]\n", + "reference = pd.DataFrame(\n", + " {\n", + " \"published\": [8.27, 8.93, 0.34, 0.23, 116118, 28260, 50757, 0.978],\n", + " \"from the published inputs\": [\n", + " *mean,\n", + " *np.sqrt(np.diag(covariance)),\n", + " covariance[0, 0] * 1e6,\n", + " covariance[0, 1] * 1e6,\n", + " covariance[1, 1] * 1e6,\n", + " numerical,\n", + " ],\n", + " },\n", + " index=[\n", + " \"E[C1]\",\n", + " \"E[C2]\",\n", + " \"std C1\",\n", + " \"std C2\",\n", + " \"var C1 (millionths)\",\n", + " \"cov C1, C2 (millionths)\",\n", + " \"var C2 (millionths)\",\n", + " \"P(C2 > C1)\",\n", + " ],\n", + ")\n", + "print(\n", + " f\"P(C2 > C1): {numerical:.4f} by eq. (15), {closed:.4f} in closed form; \"\n", + " + f\"{independent:.4f} if the costs were independent\"\n", + ")\n", + "reference.round(4)" + ] + }, + { + "cell_type": "markdown", + "id": "b2d91888", + "metadata": {}, + "source": [ + "The published inputs reproduce the published results, within the rounding of *A*'s shares: expected costs of 8.26 and 8.93 (eq. 6 gives 8.27 and 8.93, and Fig. 2 gives 8.27 and 8.94), standard deviations of 0.34 and 0.23, the covariance matrix of eq. (8) within one millionth, and a probability of 97.8% that C2 costs more than C1 (eq. 15, equal to the closed form). If the costs of the two constellations were independent, the probability would be 94.9%: the shared configuration G4c makes the order more certain.\n", + "\n", + "## Test 1: Growth by Maturity\n", + "\n", + "FRISK models the growth of the cost of each component as a triangular distribution from a low to a high multiple of its point estimate, most likely the estimate itself. The spread and skew grow as the component's maturity falls (Table I). The variance of each component is that of its triangular distribution (eq. 1), and the variance of a configuration is the sum of the covariances of its components, correlated by 0.5 (eq. 2). In TAT-C, `Triangular(low, high)` gives the distribution (most likely 1), and a `Component` grows by it. A `CostModel` with `correlation=0.5` draws the growths of its components from standard normal scores mixed with a common score (`CostModel.draw`): the growth of each component is the quantile of its distribution at the normal probability of `sqrt(0.5) * common + sqrt(0.5) * own`, so that the scores of every pair of components are correlated by 0.5. The scores are uncertain parameters of a design space (`risk_space`), drawn in each replicate of a `Study`.\n", + "\n", + "The paper gives no component costs of its configurations, so eq. (2) is checked for a configuration of one component of each maturity with equal point estimates (1), in 20,000 replicates. The correlation of the growths themselves is computed exactly (by Gauss–Hermite quadrature over the bivariate normal scores) as well as from the replicates. The standard deviations of Table I's distributions are compared with SciPy's triangular distribution, an independent implementation." + ] + }, + { + "cell_type": "code", + "execution_count": 2, + "id": "bee8a3c4", + "metadata": { + "execution": { + "iopub.execute_input": "2026-11-13T19:42:54.680457Z", + "iopub.status.busy": "2026-11-13T19:42:54.680457Z", + "iopub.status.idle": "2026-11-13T19:43:00.311731Z", + "shell.execute_reply": "2026-11-13T19:43:00.310738Z" + } + }, + "outputs": [ + { + "name": "stdout", + "output_type": "stream", + "text": [ + "correlation of growths: 0.4862 to 0.4862 exactly, 0.488 to 0.502 in the replicates (10 pairs)\n", + "variance of the configuration: 0.5075 by eq. (2), 0.5008 in the replicates (-1.3%), 0.4994 by eq. (2) with the exact correlation\n", + "correlation of scores that correlates growths by 0.5: 0.5139\n" + ] + }, + { + "data": { + "text/html": [ + "
\n", + "\n", + "\n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + "
lowhighmeanTAT-C meanmean of replicatesstd (SciPy)TAT-C stdstd of replicatesmode (share of range)
maturity
new0.8272.2741.3671.36701.36360.32260.32260.32190.1196
major modification0.8641.9931.2861.28571.28420.25160.25160.25150.1205
modified0.9041.7081.2041.20401.20280.17930.17930.17890.1194
minor modification0.9431.4231.1221.12201.12200.10710.10710.10720.1188
existing0.9811.1401.0411.04031.04000.03550.03550.03550.1195
\n", + "
" + ], + "text/plain": [ + " low high mean TAT-C mean mean of replicates \\\n", + "maturity \n", + "new 0.827 2.274 1.367 1.3670 1.3636 \n", + "major modification 0.864 1.993 1.286 1.2857 1.2842 \n", + "modified 0.904 1.708 1.204 1.2040 1.2028 \n", + "minor modification 0.943 1.423 1.122 1.1220 1.1220 \n", + "existing 0.981 1.140 1.041 1.0403 1.0400 \n", + "\n", + " std (SciPy) TAT-C std std of replicates \\\n", + "maturity \n", + "new 0.3226 0.3226 0.3219 \n", + "major modification 0.2516 0.2516 0.2515 \n", + "modified 0.1793 0.1793 0.1789 \n", + "minor modification 0.1071 0.1071 0.1072 \n", + "existing 0.0355 0.0355 0.0355 \n", + "\n", + " mode (share of range) \n", + "maturity \n", + "new 0.1196 \n", + "major modification 0.1205 \n", + "modified 0.1194 \n", + "minor modification 0.1188 \n", + "existing 0.1195 " + ] + }, + "execution_count": 2, + "metadata": {}, + "output_type": "execute_result" + } + ], + "source": [ + "from scipy import optimize\n", + "\n", + "from tatc.tradespace import (\n", + " Component,\n", + " CostModel,\n", + " DesignSpace,\n", + " SatelliteCost,\n", + " Study,\n", + " Triangular,\n", + " risk_space,\n", + ")\n", + "\n", + "GROWTH = {name: Triangular(row.low, row.high) for name, row in TABLE_I.iterrows()}\n", + "CORRELATION = 0.5 # of the scores of the components (eq. 2 assumes it of their costs)\n", + "REPLICATES = 20_000\n", + "\n", + "# a configuration of one component of each maturity, with equal point estimates\n", + "mixed = CostModel(\n", + " SatelliteCost(\n", + " components=[\n", + " Component(name, development=1.0, growth=g) for name, g in GROWTH.items()\n", + " ]\n", + " ),\n", + " correlation=CORRELATION,\n", + ")\n", + "mixed_space = DesignSpace(cost_risk=risk_space(mixed))\n", + "\n", + "\n", + "def growths(_, design):\n", + " \"\"\"The growth of each component, drawn from the replicate's scores, and of the configuration.\"\"\"\n", + " drawn = mixed.draw(design.cost_risk)\n", + " values = {c.name: c.growth for c in drawn.satellites.components}\n", + " return {**values, \"configuration\": sum(values.values())}\n", + "\n", + "\n", + "draws = Study(mixed_space, lambda d: None, growths, replicates=REPLICATES).run(\n", + " mixed_space.enumerate()\n", + ")\n", + "\n", + "\n", + "def growth_correlation(a, b, rho, nodes=200):\n", + " \"\"\"The correlation of the growths of two components whose scores are correlated by rho (Gauss-Hermite).\"\"\"\n", + " z, w = np.polynomial.hermite_e.hermegauss(nodes)\n", + " w = np.outer(w, w) / w.sum() ** 2\n", + " za, zb = np.meshgrid(z, z, indexing=\"ij\")\n", + " ga = np.vectorize(a.ppf)(stats.norm.cdf(za))\n", + " gb = np.vectorize(b.ppf)(stats.norm.cdf(rho * za + math.sqrt(1 - rho**2) * zb))\n", + " return np.sum(w * (ga - a.mean()) * (gb - b.mean())) / (a.std() * b.std())\n", + "\n", + "\n", + "table1 = TABLE_I.assign(\n", + " **{\n", + " \"TAT-C mean\": [g.mean() for g in GROWTH.values()],\n", + " \"mean of replicates\": draws[list(GROWTH)].mean().to_numpy(),\n", + " \"std (SciPy)\": [\n", + " stats.triang((1 - g.low) / (g.high - g.low), g.low, g.high - g.low).std()\n", + " for g in GROWTH.values()\n", + " ],\n", + " \"TAT-C std\": [g.std() for g in GROWTH.values()],\n", + " \"std of replicates\": draws[list(GROWTH)].std().to_numpy(),\n", + " \"mode (share of range)\": [\n", + " (1 - g.low) / (g.high - g.low) for g in GROWTH.values()\n", + " ],\n", + " }\n", + ")\n", + "pairs = [(a, b) for i, a in enumerate(GROWTH) for b in list(GROWTH)[i + 1 :]]\n", + "exact = [growth_correlation(GROWTH[a], GROWTH[b], CORRELATION) for a, b in pairs]\n", + "sampled = [draws[a].corr(draws[b]) for a, b in pairs]\n", + "sigma = np.array([g.std() for g in GROWTH.values()])\n", + "off_diagonal = sigma.sum() ** 2 - (sigma**2).sum() # twice the sum of products of pairs\n", + "eq2 = (sigma**2).sum() + CORRELATION * off_diagonal\n", + "eq2_exact = (sigma**2).sum() + np.mean(exact) * off_diagonal\n", + "matching = optimize.brentq(\n", + " lambda rho: growth_correlation(GROWTH[\"new\"], GROWTH[\"existing\"], rho) - 0.5,\n", + " 0.4,\n", + " 0.7,\n", + ")\n", + "print(\n", + " f\"correlation of growths: {min(exact):.4f} to {max(exact):.4f} exactly, \"\n", + " + f\"{min(sampled):.3f} to {max(sampled):.3f} in the replicates (10 pairs)\"\n", + ")\n", + "print(\n", + " f\"variance of the configuration: {eq2:.4f} by eq. (2), {draws.configuration.var():.4f} in the replicates \"\n", + " + f\"({draws.configuration.var() / eq2 - 1:+.1%}), {eq2_exact:.4f} by eq. (2) with the exact correlation\"\n", + ")\n", + "print(f\"correlation of scores that correlates growths by 0.5: {matching:.4f}\")\n", + "table1.round(4)" + ] + }, + { + "cell_type": "markdown", + "id": "65f2a574", + "metadata": {}, + "source": [ + "`Triangular` reproduces Table I: its means equal the published means to the table's three decimals for four of the five maturities. The fifth, existing components, is 1.0403 against the published 1.041; the mean of (0.981, 1, 1.140) is 1.0403, so the table's last digit is rounded up. Its standard deviations equal SciPy's, and the replicates drawn through `CostModel.draw` reproduce the means and standard deviations within their sampling errors (at most 0.0023 for the means).\n", + "\n", + "`CostModel.correlation` correlates the scores of components, not their growths: the quantile transform of a skewed distribution lowers the correlation of the growths to 0.486 for every pair. Table I's distributions all have the same shape (the most likely growth at 12% of each one's range), so all pairs are lowered alike. The replicates give 0.488 to 0.502, within their sampling error of about 0.006. The configuration's variance is 1.3% below eq. (2), as eq. (2) with the exact correlation predicts. A correlation of the scores of 0.514 gives growths correlated by 0.5, as eq. (2) assumes. This difference is small next to the uncertainty of the correlation itself, which the paper puts at 0.5 as \"generally appropriate.\"\n", + "\n", + "## Test 2: Production Blocks\n", + "\n", + "The paper costs each configuration over 2020 to 2050 in blocks of four satellites. Each block is a new design, whose development (Dev) and first unit (T1) are paid again, followed by three later units (Ta). In TAT-C, a type of satellite with `block_size=4` (and `redevelopment=1`, a full redesign) develops each block after the first before the production of the block's first unit, over the type's development time (see `CostModel.estimate`).\n", + "\n", + "A `DeploymentSchedule` plans the deployment of each constellation, with the design life, development time, and production rate of each configuration (mappings by kind):\n", + "\n", + "* **Launches.** A design life equal to a configuration's launch interval launches a replacement at that interval from its first launch.\n", + "* **Production.** Each launch's satellites are produced over the four years before it, as Table III's later units are.\n", + "* **Development.** Development runs from the start (1 March 2020, when Table III begins G4c's first development) to the production of the first unit.\n", + "* **Study period.** The mission ends at the end of September 2050, and the constellation is `sustained`: replaced after the end as before it. The units in production at the end are then produced (though not launched in the mission), and the costs of the deployment are those incurred by the end, which count each development and each unit by the share done (see `CostModel.estimate`).\n", + "\n", + "The layout of a configuration is its slots: a subclass of `Layout`, which needs only its planes to be deployed and costed (the orbits matter only to build the satellites)." + ] + }, + { + "cell_type": "code", + "execution_count": 3, + "id": "1a3450b1", + "metadata": { + "execution": { + "iopub.execute_input": "2026-11-13T19:43:00.313930Z", + "iopub.status.busy": "2026-11-13T19:43:00.312735Z", + "iopub.status.idle": "2026-11-13T19:43:00.340975Z", + "shell.execute_reply": "2026-11-13T19:43:00.340975Z" + } + }, + "outputs": [ + { + "name": "stdout", + "output_type": "stream", + "text": [ + "C1 G4c: launches in Apr 2029, Apr 2033, Apr 2037, Apr 2041, Apr 2045, Apr 2049\n", + "C1 L3e: launches in Jul 2032, Jan 2037, Jul 2041, Jan 2046, Jul 2050\n", + "C2 G4c: launches in Apr 2029, Dec 2031, Aug 2034, Apr 2037, Dec 2039, Aug 2042, Apr 2045, Dec 2047, Aug 2050\n", + "C2 L4f: launches in Jul 2028, May 2032, Mar 2036, Jan 2040, Nov 2043, Sep 2047\n" + ] + }, + { + "data": { + "text/html": [ + "
\n", + "\n", + "\n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + "
paper developmentTAT-C developmentpaper productionTAT-C productionpaper launchTAT-C launchpaper countedTAT-C counted
unit
block 1, unit 1Mar 2020Mar 2020Sep 2023Apr 2025Apr 2029Apr 20291.001.000
block 1, unit 2NoneNoneApr 2029Apr 2029Apr 2033Apr 20331.001.000
block 1, unit 3NoneNoneApr 2033Apr 2033Apr 2037Apr 20371.001.000
block 1, unit 4NoneNoneApr 2037Apr 2037Apr 2041Apr 20411.001.000
block 2, unit 1Mar 2036Mar 2036Sep 2039Apr 2041Apr 2045Apr 20451.001.000
block 2, unit 2NoneNoneApr 2045Apr 2045Apr 2049Apr 20491.001.000
block 2, unit 3NoneNoneApr 2049Apr 2049Apr 2053Apr 20530.370.375
\n", + "
" + ], + "text/plain": [ + " paper development TAT-C development paper production \\\n", + "unit \n", + "block 1, unit 1 Mar 2020 Mar 2020 Sep 2023 \n", + "block 1, unit 2 None None Apr 2029 \n", + "block 1, unit 3 None None Apr 2033 \n", + "block 1, unit 4 None None Apr 2037 \n", + "block 2, unit 1 Mar 2036 Mar 2036 Sep 2039 \n", + "block 2, unit 2 None None Apr 2045 \n", + "block 2, unit 3 None None Apr 2049 \n", + "\n", + " TAT-C production paper launch TAT-C launch paper counted \\\n", + "unit \n", + "block 1, unit 1 Apr 2025 Apr 2029 Apr 2029 1.00 \n", + "block 1, unit 2 Apr 2029 Apr 2033 Apr 2033 1.00 \n", + "block 1, unit 3 Apr 2033 Apr 2037 Apr 2037 1.00 \n", + "block 1, unit 4 Apr 2037 Apr 2041 Apr 2041 1.00 \n", + "block 2, unit 1 Apr 2041 Apr 2045 Apr 2045 1.00 \n", + "block 2, unit 2 Apr 2045 Apr 2049 Apr 2049 1.00 \n", + "block 2, unit 3 Apr 2049 Apr 2053 Apr 2053 0.37 \n", + "\n", + " TAT-C counted \n", + "unit \n", + "block 1, unit 1 1.000 \n", + "block 1, unit 2 1.000 \n", + "block 1, unit 3 1.000 \n", + "block 1, unit 4 1.000 \n", + "block 2, unit 1 1.000 \n", + "block 2, unit 2 1.000 \n", + "block 2, unit 3 0.375 " + ] + }, + "execution_count": 3, + "metadata": {}, + "output_type": "execute_result" + } + ], + "source": [ + "from tatc.tradespace import DeploymentSchedule\n", + "from tatc.tradespace.constellations import Layout, Plane\n", + "\n", + "BLOCK_SIZE = 4\n", + "PRODUCTION_YEARS = 4 # the production of each launch's satellites (Table III)\n", + "MONTHS = \"Jan Feb Mar Apr May Jun Jul Aug Sep Oct Nov Dec\".split()\n", + "\n", + "\n", + "def year(y, m):\n", + " \"\"\"The start of a month, in years from 1 March 2020.\"\"\"\n", + " return y - 2020 + (m - 3) / 12\n", + "\n", + "\n", + "def month(time):\n", + " \"\"\"The month of a time, in years from 1 March 2020.\"\"\"\n", + " months = round(time * 12) + 2\n", + " return f\"{MONTHS[months % 12]} {2020 + months // 12}\"\n", + "\n", + "\n", + "END = year(2050, 10) # the end of September 2050\n", + "# Table II: the first launch, the months between launches, and the satellites of each launch\n", + "SCHEDULES = {\n", + " \"C1\": {\"G4c\": (year(2029, 4), 48, 1), \"L3e\": (year(2032, 7), 54, 1)},\n", + " \"C2\": {\"G4c\": (year(2029, 4), 32, 1), \"L4f\": (year(2028, 7), 46, 2)},\n", + "}\n", + "\n", + "\n", + "class Slots(Layout):\n", + " \"\"\"Orbital slots, whose satellites are launched together (one plane, for deployments).\"\"\"\n", + "\n", + " def __init__(self, count):\n", + " self.count = count\n", + "\n", + " def planes(self):\n", + " return [Plane(self.count)]\n", + "\n", + "\n", + "def plan(name, sustained=True):\n", + " \"\"\"The deployment of a constellation: each configuration launched at its interval from its first launch.\"\"\"\n", + " configurations = SCHEDULES[name]\n", + " schedule = DeploymentSchedule(\n", + " years=END - min(first for first, _, _ in configurations.values()),\n", + " design_life={c: months / 12 for c, (_, months, _) in configurations.items()},\n", + " development_years={\n", + " c: first - PRODUCTION_YEARS for c, (first, _, _) in configurations.items()\n", + " },\n", + " production_rate={\n", + " c: satellites / PRODUCTION_YEARS\n", + " for c, (_, _, satellites) in configurations.items()\n", + " },\n", + " sustained=sustained,\n", + " )\n", + " return schedule.plan(\n", + " {c: Slots(satellites) for c, (_, _, satellites) in configurations.items()}\n", + " )\n", + "\n", + "\n", + "DEPLOYMENTS = {name: plan(name) for name in SCHEDULES}\n", + "for name, deployment in DEPLOYMENTS.items():\n", + " for c in SCHEDULES[name]:\n", + " launches = [l.time for l in deployment.launches if l.kind == c]\n", + " print(f\"{name} {c}: launches in\", \", \".join(month(t) for t in launches))\n", + "\n", + "\n", + "def shares_produced(deployment, configuration):\n", + " \"\"\"The share of each unit of a configuration produced by the end, in the order of production.\"\"\"\n", + " shares = []\n", + " for batch in deployment.production:\n", + " if batch.kind == configuration:\n", + " done = (END - batch.begin) / (batch.end - batch.begin)\n", + " shares += [min(max(done, 0.0), 1.0)] * batch.satellites\n", + " return shares\n", + "\n", + "\n", + "# Table III: G4c in C1 (the start of development of each block, and of production and launch of each unit)\n", + "TABLE_III = pd.DataFrame(\n", + " [\n", + " (\"Mar 2020\", \"Sep 2023\", \"Apr 2029\", 1.0),\n", + " (None, \"Apr 2029\", \"Apr 2033\", 1.0),\n", + " (None, \"Apr 2033\", \"Apr 2037\", 1.0),\n", + " (None, \"Apr 2037\", \"Apr 2041\", 1.0),\n", + " (\"Mar 2036\", \"Sep 2039\", \"Apr 2045\", 1.0),\n", + " (None, \"Apr 2045\", \"Apr 2049\", 1.0),\n", + " (None, \"Apr 2049\", \"Apr 2053\", 0.37),\n", + " ],\n", + " columns=[\"development\", \"production\", \"launch\", \"counted\"],\n", + ")\n", + "c1 = DEPLOYMENTS[\"C1\"]\n", + "developed = c1.development[\"G4c\"]\n", + "# the units of G4c in production by the end, including the one launched after it\n", + "batches = [b for b in c1.production if b.kind == \"G4c\" and b.begin < END]\n", + "table3 = []\n", + "for unit, (batch, share) in enumerate(zip(batches, shares_produced(c1, \"G4c\"))):\n", + " first = unit % BLOCK_SIZE == 0\n", + " table3.append(\n", + " {\n", + " \"unit\": f\"block {unit // BLOCK_SIZE + 1}, unit {unit % BLOCK_SIZE + 1}\",\n", + " # each block's development ends as the production of its first unit begins\n", + " \"TAT-C development\": (\n", + " month(max(batch.begin - developed, 0)) if first else None\n", + " ),\n", + " \"TAT-C production\": month(batch.begin),\n", + " \"TAT-C launch\": month(batch.end), # each unit is produced until its launch\n", + " \"TAT-C counted\": share,\n", + " }\n", + " )\n", + "table3 = pd.DataFrame(table3).join(TABLE_III.add_prefix(\"paper \")).set_index(\"unit\")\n", + "table3[[f\"{side} {column}\" for column in TABLE_III for side in (\"paper\", \"TAT-C\")]]" + ] + }, + { + "cell_type": "markdown", + "id": "f90da62e", + "metadata": {}, + "source": [ + "TAT-C's deployment of G4c in C1 reproduces Table III's launches, the production of its later units, and the starts of development of both blocks (March 2020 and March 2036). With development ending as production begins, the second block's development takes the 5.1 years before its first unit's production (April 2041), which starts it in March 2036, as Table III does. Table III's Phases B and C start the first unit's production earlier (September 2023, 5.6 years before launch), where TAT-C produces every unit over four years: the dates of the first units' costs differ, not their amounts. The sustained deployment produces the unit launched in April 2053 from April 2049: 18 of its 48 months by the end of September 2050, or 0.375 of it (Table III's 0.37).\n", + "\n", + "TAT-C's estimate counts the developments and units of a configuration as costs. A model that costs 1 for each development and each unit of one configuration (and nothing for the others) gives the number of developments, *D*, and of units, *U*, each counted by the share done by the end. With each block's first-unit premium (T1 − Ta) charged with its development, as Test 3 costs the configurations, these cost as *D* developments and first units and *U* − *D* later units, the form of *B*. The counts of each constellation are below, together with two alternatives: TAT-C's dates counted as Table III counts them (each block's development with the share of its first unit produced), and a mission that is not sustained, whose costs are those of the units it launches by its end." + ] + }, + { + "cell_type": "code", + "execution_count": 4, + "id": "57810fa2", + "metadata": { + "execution": { + "iopub.execute_input": "2026-11-13T19:43:00.342785Z", + "iopub.status.busy": "2026-11-13T19:43:00.342785Z", + "iopub.status.idle": "2026-11-13T19:43:00.436893Z", + "shell.execute_reply": "2026-11-13T19:43:00.435865Z" + } + }, + "outputs": [ + { + "data": { + "text/html": [ + "
\n", + "\n", + "\n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + "
DevT1Taexpected cost
constellationconfigurationcount
C1G4cTAT-C's dates, counted as Table III2.00002.00004.37504.6125
TAT-C, mission2.00002.00004.00004.4689
TAT-C, study period2.00002.00004.37504.6125
paper2.00002.00004.37004.6106
L3eTAT-C's dates, counted as Table III2.00002.00003.00003.6487
TAT-C, mission2.00002.00003.00003.6487
TAT-C, study period2.00002.00003.00003.6487
paper2.00002.00003.00003.6487
C2G4cTAT-C's dates, counted as Table III3.00003.00006.37506.8469
TAT-C, mission3.00003.00006.00006.7033
TAT-C, study period3.00003.00006.37506.8469
paper3.00003.00006.37006.8450
L4fTAT-C's dates, counted as Table III3.81253.81259.81252.4059
TAT-C, mission3.00003.00009.00001.9900
TAT-C, study period4.00004.00009.62502.4736
paper2.90002.900010.80002.0825
\n", + "
" + ], + "text/plain": [ + " Dev \\\n", + "constellation configuration count \n", + "C1 G4c TAT-C's dates, counted as Table III 2.0000 \n", + " TAT-C, mission 2.0000 \n", + " TAT-C, study period 2.0000 \n", + " paper 2.0000 \n", + " L3e TAT-C's dates, counted as Table III 2.0000 \n", + " TAT-C, mission 2.0000 \n", + " TAT-C, study period 2.0000 \n", + " paper 2.0000 \n", + "C2 G4c TAT-C's dates, counted as Table III 3.0000 \n", + " TAT-C, mission 3.0000 \n", + " TAT-C, study period 3.0000 \n", + " paper 3.0000 \n", + " L4f TAT-C's dates, counted as Table III 3.8125 \n", + " TAT-C, mission 3.0000 \n", + " TAT-C, study period 4.0000 \n", + " paper 2.9000 \n", + "\n", + " T1 \\\n", + "constellation configuration count \n", + "C1 G4c TAT-C's dates, counted as Table III 2.0000 \n", + " TAT-C, mission 2.0000 \n", + " TAT-C, study period 2.0000 \n", + " paper 2.0000 \n", + " L3e TAT-C's dates, counted as Table III 2.0000 \n", + " TAT-C, mission 2.0000 \n", + " TAT-C, study period 2.0000 \n", + " paper 2.0000 \n", + "C2 G4c TAT-C's dates, counted as Table III 3.0000 \n", + " TAT-C, mission 3.0000 \n", + " TAT-C, study period 3.0000 \n", + " paper 3.0000 \n", + " L4f TAT-C's dates, counted as Table III 3.8125 \n", + " TAT-C, mission 3.0000 \n", + " TAT-C, study period 4.0000 \n", + " paper 2.9000 \n", + "\n", + " Ta \\\n", + "constellation configuration count \n", + "C1 G4c TAT-C's dates, counted as Table III 4.3750 \n", + " TAT-C, mission 4.0000 \n", + " TAT-C, study period 4.3750 \n", + " paper 4.3700 \n", + " L3e TAT-C's dates, counted as Table III 3.0000 \n", + " TAT-C, mission 3.0000 \n", + " TAT-C, study period 3.0000 \n", + " paper 3.0000 \n", + "C2 G4c TAT-C's dates, counted as Table III 6.3750 \n", + " TAT-C, mission 6.0000 \n", + " TAT-C, study period 6.3750 \n", + " paper 6.3700 \n", + " L4f TAT-C's dates, counted as Table III 9.8125 \n", + " TAT-C, mission 9.0000 \n", + " TAT-C, study period 9.6250 \n", + " paper 10.8000 \n", + "\n", + " expected cost \n", + "constellation configuration count \n", + "C1 G4c TAT-C's dates, counted as Table III 4.6125 \n", + " TAT-C, mission 4.4689 \n", + " TAT-C, study period 4.6125 \n", + " paper 4.6106 \n", + " L3e TAT-C's dates, counted as Table III 3.6487 \n", + " TAT-C, mission 3.6487 \n", + " TAT-C, study period 3.6487 \n", + " paper 3.6487 \n", + "C2 G4c TAT-C's dates, counted as Table III 6.8469 \n", + " TAT-C, mission 6.7033 \n", + " TAT-C, study period 6.8469 \n", + " paper 6.8450 \n", + " L4f TAT-C's dates, counted as Table III 2.4059 \n", + " TAT-C, mission 1.9900 \n", + " TAT-C, study period 2.4736 \n", + " paper 2.0825 " + ] + }, + "metadata": {}, + "output_type": "display_data" + }, + { + "data": { + "text/html": [ + "
\n", + "\n", + "\n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + "
E[C1]E[C2]E[C2] - E[C1]P(C2 > C1)
count
paper8.25928.92750.66830.9779
TAT-C, study period8.26119.32051.05930.9991
TAT-C's dates, counted as Table III8.26119.25280.99170.9984
TAT-C, mission8.11758.69330.57570.9590
\n", + "
" + ], + "text/plain": [ + " E[C1] E[C2] E[C2] - E[C1] P(C2 > C1)\n", + "count \n", + "paper 8.2592 8.9275 0.6683 0.9779\n", + "TAT-C, study period 8.2611 9.3205 1.0593 0.9991\n", + "TAT-C's dates, counted as Table III 8.2611 9.2528 0.9917 0.9984\n", + "TAT-C, mission 8.1175 8.6933 0.5757 0.9590" + ] + }, + "execution_count": 4, + "metadata": {}, + "output_type": "execute_result" + } + ], + "source": [ + "def counted(deployment, configuration):\n", + " \"\"\"The developments and units of a configuration that TAT-C's estimate costs, as (Dev, T1, Ta).\"\"\"\n", + " each = SatelliteCost(development=1.0, first_unit=1.0, block_size=BLOCK_SIZE)\n", + " model = CostModel(\n", + " {\n", + " c: each if c == configuration else SatelliteCost()\n", + " for c in deployment.development\n", + " }\n", + " )\n", + " estimate = model.estimate(deployment)\n", + " return (\n", + " estimate.development,\n", + " estimate.development,\n", + " estimate.production - estimate.development,\n", + " )\n", + "\n", + "\n", + "def counted_as_table_iii(deployment, configuration):\n", + " \"\"\"The developments, first units, and later units by the end, as Table III counts them.\"\"\"\n", + " shares = shares_produced(deployment, configuration)\n", + " first = sum(\n", + " shares[::BLOCK_SIZE]\n", + " ) # each block's development is counted with its first unit\n", + " return (first, first, sum(shares) - first)\n", + "\n", + "\n", + "COUNTS = {\n", + " \"paper\": PUBLISHED,\n", + " \"TAT-C, study period\": {},\n", + " \"TAT-C's dates, counted as Table III\": {},\n", + " \"TAT-C, mission\": {},\n", + "}\n", + "for name, configurations in SCHEDULES.items():\n", + " ending = plan(name, sustained=False)\n", + " COUNTS[\"TAT-C, study period\"][name] = {\n", + " c: counted(DEPLOYMENTS[name], c) for c in configurations\n", + " }\n", + " COUNTS[\"TAT-C's dates, counted as Table III\"][name] = {\n", + " c: counted_as_table_iii(DEPLOYMENTS[name], c) for c in configurations\n", + " }\n", + " COUNTS[\"TAT-C, mission\"][name] = {c: counted(ending, c) for c in configurations}\n", + "rows = [\n", + " {\n", + " \"constellation\": name,\n", + " \"configuration\": c,\n", + " \"count\": key,\n", + " **dict(zip([\"Dev\", \"T1\", \"Ta\"], values)),\n", + " \"expected cost\": MEAN_Q[c] * np.dot(values, SHARES[c]),\n", + " }\n", + " for key, counts in COUNTS.items()\n", + " for name, configurations in counts.items()\n", + " for c, values in configurations.items()\n", + "]\n", + "counts = (\n", + " pd.DataFrame(rows)\n", + " .set_index([\"constellation\", \"configuration\", \"count\"])\n", + " .sort_index()\n", + ")\n", + "totals = []\n", + "for key, table in COUNTS.items():\n", + " mean, covariance = moments(table)\n", + " totals.append(\n", + " {\n", + " \"count\": key,\n", + " \"E[C1]\": mean[0],\n", + " \"E[C2]\": mean[1],\n", + " \"E[C2] - E[C1]\": mean[1] - mean[0],\n", + " \"P(C2 > C1)\": probability_exceeds(mean, covariance)[1],\n", + " }\n", + " )\n", + "display(counts.round(4))\n", + "pd.DataFrame(totals).set_index(\"count\").round(4)" + ] + }, + { + "cell_type": "markdown", + "id": "9ce2ecf4", + "metadata": {}, + "source": [ + "Over the study period, TAT-C's estimates reproduce the published numbers of G4c in both constellations (2, 2, 4.375 and 3, 3, 6.375 against 4.37 and 6.37) and of L3e (2, 2, 3), and so C1's expected cost (8.2611 against 8.2592, the difference being the rounding of 4.375). The published numbers of L4f (2.9 developments and first units, 10.8 later units) cannot be derived from its schedule. Its six launches of two satellites before the end (12 units, 3 blocks), and the 0.81 of the next two produced, give about the same units (13.6 against 13.7) but more developments. TAT-C counts 4, as the fourth block is developed from March 2043 until its first unit's production begins in July 2047, before the end. Table III's count, which counts that development with the 0.81 of its first unit, gives 3.81. Two satellites per launch every 46 months is one reading of Table II's \"46 (x2)\". Other readings, such as two slots with blocks of their own (4 developments) or one launch every 23 months (3.81), do not give 2.9 either. With TAT-C's counts, L4f costs 0.39 more than with its published counts, and the probability that C2 costs more than C1 is 99.9% (99.8% with Table III's count).\n", + "\n", + "A mission that is not sustained costs the units it launches by its end. It leaves out the 0.375 of a G4c unit in production at the end in both constellations (0.14 of each one's cost) and L4f's fourth block, whose units are launched after the end. Both constellations then cost less (8.12 and 8.69), and the probability that C2 costs more is 95.9%: nearer the paper's 97.8%, but only because its cost of L4f (1.99) happens to be nearer the published one (2.08). The tests below evaluate the costs of the published numbers, to test TAT-C's cost risk on the paper's inputs, and also TAT-C's own estimates of the deployments over the study period.\n", + "\n", + "## Test 3: Constellation Costs\n", + "\n", + "The paper's cost of a block of a configuration is a random variable *Q* (normal, from its FRISK estimate), of which fixed shares are its development, first unit, and each later unit: every element of every block grows with *Q*. In TAT-C, each configuration is a type of satellite with one component (named after it) whose growth is normal, with mean 1 and the standard deviation of *Q* relative to its mean. The growth is a SciPy distribution, which has the `ppf` and `mean` that a `Component` needs. Without learning (the default learning rate of 1), each unit costs the component's `first_unit`, here the cost of a later unit (Ta). The first unit's premium (T1 - Ta) is charged with each block's development, so that a block costs Dev + T1 + 3 Ta, as in the paper. (A learning curve would also give the premium: Ta/T1 is about 0.87 for all three configurations, the mean of units 2 to 4 on a 91% curve, but the paper charges every later unit the same.) The growths of the configurations are uncorrelated (`correlation=0`, the default), as the paper assumes, so the scores of the cost risk are those of G4c, L3e, and L4f (`risk_space`).\n", + "\n", + "The design space has one design variable, the constellation (C1 or C2), and the scores. Two evaluations of the replicates are compared:\n", + "\n", + "* **Published counts.** The cost of the published numbers of developments and units (*B*): each block costs the `total_development` and each unit the `total_first_unit` of the configuration drawn from the replicate's scores. This tests TAT-C's cost risk on the paper's inputs.\n", + "* **TAT-C deployments.** TAT-C's own estimate (`CostModel.estimate`) of the sustained deployments of Test 2, over the study period.\n", + "\n", + "Each runs 20,000 replicates with common random numbers (the default), in which both constellations draw the same scores, and 20,000 with independent draws (for Test 4)." + ] + }, + { + "cell_type": "code", + "execution_count": 5, + "id": "f2a83d51", + "metadata": { + "execution": { + "iopub.execute_input": "2026-11-13T19:43:00.438893Z", + "iopub.status.busy": "2026-11-13T19:43:00.437893Z", + "iopub.status.idle": "2026-11-13T19:44:43.282295Z", + "shell.execute_reply": "2026-11-13T19:44:43.281821Z" + } + }, + "outputs": [ + { + "name": "stdout", + "output_type": "stream", + "text": [ + "scores: ['cost_risk.G4c', 'cost_risk.L3e', 'cost_risk.L4f']\n", + "C1: blocks begun {'G4c': 2, 'L3e': 2}, units begun {'G4c': 7, 'L3e': 5}, expected cost 8.2611 (8.2611 from the counts of Test 2)\n", + "C2: blocks begun {'L4f': 4, 'G4c': 3}, units begun {'L4f': 14, 'G4c': 10}, expected cost 9.3205 (9.3205 from the counts of Test 2)\n" + ] + }, + { + "name": "stdout", + "output_type": "stream", + "text": [ + "standard errors of the means of the replicates: 0.0024\n" + ] + }, + { + "data": { + "text/html": [ + "
\n", + "\n", + "\n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + "
E[C1]E[C2]std C1std C2cov (millionths)correlation
paper (eqs. 6 and 8)8.27008.93000.34080.225328260.00000.3681
published counts: expected8.25928.92750.34080.225328260.89670.3681
published counts: replicates8.26228.92690.34010.224127968.41920.3669
TAT-C deployments: expected8.26119.32050.34080.233228280.54210.3558
TAT-C deployments: replicates8.26419.32000.34020.231927992.95330.3548
\n", + "
" + ], + "text/plain": [ + " E[C1] E[C2] std C1 std C2 \\\n", + "paper (eqs. 6 and 8) 8.2700 8.9300 0.3408 0.2253 \n", + "published counts: expected 8.2592 8.9275 0.3408 0.2253 \n", + "published counts: replicates 8.2622 8.9269 0.3401 0.2241 \n", + "TAT-C deployments: expected 8.2611 9.3205 0.3408 0.2332 \n", + "TAT-C deployments: replicates 8.2641 9.3200 0.3402 0.2319 \n", + "\n", + " cov (millionths) correlation \n", + "paper (eqs. 6 and 8) 28260.0000 0.3681 \n", + "published counts: expected 28260.8967 0.3681 \n", + "published counts: replicates 27968.4192 0.3669 \n", + "TAT-C deployments: expected 28280.5421 0.3558 \n", + "TAT-C deployments: replicates 27992.9533 0.3548 " + ] + }, + "execution_count": 5, + "metadata": {}, + "output_type": "execute_result" + } + ], + "source": [ + "from tatc.tradespace import Categorical\n", + "\n", + "TYPES = {\n", + " c: SatelliteCost(\n", + " components=[\n", + " Component(\n", + " c,\n", + " development=(dev + first - later) * MEAN_Q[c],\n", + " first_unit=later * MEAN_Q[c],\n", + " growth=stats.norm(1, math.sqrt(VARIANCE_Q[c]) / MEAN_Q[c]),\n", + " )\n", + " ],\n", + " block_size=BLOCK_SIZE,\n", + " )\n", + " for c, (dev, first, later) in SHARES.items()\n", + "}\n", + "MODEL = CostModel(TYPES)\n", + "space = DesignSpace(\n", + " constellation=Categorical(CONSTELLATIONS), cost_risk=risk_space(MODEL)\n", + ")\n", + "designs = space.enumerate()\n", + "print(\"scores:\", space.uncertain_paths())\n", + "# the expected costs of TAT-C's deployments (with the components' mean growth), against the counts of Test 2\n", + "for name, deployment in DEPLOYMENTS.items():\n", + " estimate = MODEL.estimate(deployment)\n", + " expected = moments(COUNTS[\"TAT-C, study period\"])[0][CONSTELLATIONS.index(name)]\n", + " print(\n", + " f\"{name}: blocks begun {estimate.blocks}, units begun {estimate.units}, \"\n", + " + f\"expected cost {estimate.total:.4f} ({expected:.4f} from the counts of Test 2)\"\n", + " )\n", + "\n", + "\n", + "def build(design):\n", + " return design.constellation\n", + "\n", + "\n", + "def published(constellation, design):\n", + " \"\"\"The cost of the published numbers of developments and units, drawn in the replicate.\"\"\"\n", + " drawn = MODEL.draw(design.cost_risk)\n", + " cost = 0.0\n", + " for c, (developments, first, later) in PUBLISHED[constellation].items():\n", + " configuration = drawn.satellites[c]\n", + " # developments and first units are counted alike: each block costs Dev + T1 - Ta, and each unit Ta\n", + " cost += developments * configuration.total_development\n", + " cost += (first + later) * configuration.total_first_unit\n", + " return {\"cost\": cost}\n", + "\n", + "\n", + "def deployed(constellation, design):\n", + " \"\"\"TAT-C's estimate of the cost of the constellation's deployment, drawn in the replicate.\"\"\"\n", + " drawn = MODEL.draw(design.cost_risk)\n", + " return {\"cost\": drawn.estimate(DEPLOYMENTS[constellation]).total}\n", + "\n", + "\n", + "EVALUATIONS = {\n", + " \"published counts\": (published, PUBLISHED),\n", + " \"TAT-C deployments\": (deployed, COUNTS[\"TAT-C, study period\"]),\n", + "}\n", + "results = {\n", + " (name, draws): Study(\n", + " space,\n", + " build,\n", + " evaluate,\n", + " replicates=REPLICATES,\n", + " common_random_numbers=draws == \"common\",\n", + " ).run(designs)\n", + " for name, (evaluate, _) in EVALUATIONS.items()\n", + " for draws in (\"common\", \"independent\")\n", + "}\n", + "wide = {\n", + " key: frame.pivot(index=\"replicate\", columns=\"constellation\", values=\"cost\")\n", + " for key, frame in results.items()\n", + "}\n", + "\n", + "\n", + "def statistics(mean, covariance):\n", + " std = np.sqrt(np.diag(covariance))\n", + " return {\n", + " \"E[C1]\": mean[0],\n", + " \"E[C2]\": mean[1],\n", + " \"std C1\": std[0],\n", + " \"std C2\": std[1],\n", + " \"cov (millionths)\": covariance[0, 1] * 1e6,\n", + " \"correlation\": covariance[0, 1] / (std[0] * std[1]),\n", + " }\n", + "\n", + "\n", + "rows = {\n", + " \"paper (eqs. 6 and 8)\": statistics(\n", + " [8.27, 8.93], np.array([[116118, 28260], [28260, 50757]]) * 1e-6\n", + " )\n", + "}\n", + "for name, (_, table) in EVALUATIONS.items():\n", + " rows[f\"{name}: expected\"] = statistics(*moments(table))\n", + " sample = wide[name, \"common\"]\n", + " rows[f\"{name}: replicates\"] = statistics(\n", + " sample.mean().to_numpy(), np.cov(sample.to_numpy().T)\n", + " )\n", + "print(\n", + " f\"standard errors of the means of the replicates: {wide['published counts', 'common'].std().max() / math.sqrt(REPLICATES):.4f}\"\n", + ")\n", + "pd.DataFrame(rows).T.round(4)" + ] + }, + { + "cell_type": "markdown", + "id": "6a6ea60a", + "metadata": {}, + "source": [ + "With the published counts, the replicates reproduce the expected costs, standard deviations, and covariance of eqs. (6) and (8) within their sampling errors: 0.0024 for the means, 0.0017 and 0.0011 for the standard deviations, and about 580 millionths for the covariance (whose correlation is 0.37). TAT-C's estimates of its deployments, with the components' mean growth, match the expected costs of their counts exactly, and their replicates match their own expectations as closely. C1's statistics are the paper's, and C2's standard deviation is 0.233 against 0.225, from L4f's larger count. Most of C1's variance is L3e's (its less mature payload makes its block the most uncertain), and most of C2's is G4c's.\n", + "\n", + "The distributions of the costs of the replicates (Fig. 2 of the paper) with the normal distributions of eqs. (6) and (8):" + ] + }, + { + "cell_type": "code", + "execution_count": 6, + "id": "2404d5e2", + "metadata": { + "execution": { + "iopub.execute_input": "2026-11-13T19:44:43.282295Z", + "iopub.status.busy": "2026-11-13T19:44:43.282295Z", + "iopub.status.idle": "2026-11-13T19:44:43.469621Z", + "shell.execute_reply": "2026-11-13T19:44:43.468976Z" + } + }, + "outputs": [ + { + "data": { + "image/png": "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", + "text/plain": [ + "
" + ] + }, + "metadata": {}, + "output_type": "display_data" + } + ], + "source": [ + "fig, ax = plt.subplots(figsize=(8, 3.6))\n", + "x = np.linspace(7, 10, 400)\n", + "paper = {\"C1\": (8.27, 0.34), \"C2\": (8.93, 0.23)}\n", + "for name, color, side in zip(CONSTELLATIONS, [BLUE, ORANGE], [-1, 1]):\n", + " sample = wide[\"published counts\", \"common\"][name]\n", + " ax.hist(\n", + " sample,\n", + " bins=72,\n", + " range=(7, 10),\n", + " density=True,\n", + " color=color,\n", + " alpha=0.35,\n", + " label=f\"{name}, TAT-C replicates\",\n", + " )\n", + " ax.plot(\n", + " x,\n", + " stats.norm.pdf(x, *paper[name]),\n", + " color=color,\n", + " lw=2,\n", + " label=f\"{name}, paper (normal)\",\n", + " )\n", + " peak = stats.norm.pdf(paper[name][0], *paper[name])\n", + " # labeled on the outer side of each peak, clear of the other distribution\n", + " ax.annotate(\n", + " f\"{name}: mean {sample.mean():.2f}, std {sample.std():.2f}\",\n", + " (paper[name][0] + side * 0.6 * paper[name][1], 0.85 * peak),\n", + " xytext=(side * 6, 0),\n", + " textcoords=\"offset points\",\n", + " ha=\"left\" if side > 0 else \"right\",\n", + " color=INK,\n", + " fontsize=9,\n", + " )\n", + "ax.set(xlabel=\"Relative total program cost\", ylabel=\"Probability density\", xlim=(7, 10))\n", + "ax.spines[[\"top\", \"right\"]].set_visible(False)\n", + "ax.legend(frameon=False, fontsize=8, loc=\"upper left\")\n", + "plt.show()" + ] + }, + { + "cell_type": "markdown", + "id": "231d9a3c", + "metadata": {}, + "source": [ + "## Test 4: Order of Costs\n", + "\n", + "The probability that C2 costs more than C1 is, for the replicates, the share of replicates in which it does (`exceedance`, which counts ties as half). With common random numbers, both constellations draw the same scores in each replicate, so their costs are correlated by the configuration they share, as in eq. (15). With independent draws, they are not. The share of the variance of each constellation's cost, and of the difference of their costs, that each configuration's score causes is estimated with `attribute_variance` (by redrawing each score in turn, in 10,000 replicates of each design) and `Attribution.differences`, against the exact shares of the linear model (the square of each configuration's exposure, times its variance, over the variance of the cost)." + ] + }, + { + "cell_type": "code", + "execution_count": 7, + "id": "47356024", + "metadata": { + "execution": { + "iopub.execute_input": "2026-11-13T19:44:43.470651Z", + "iopub.status.busy": "2026-11-13T19:44:43.470651Z", + "iopub.status.idle": "2026-11-13T19:45:17.110548Z", + "shell.execute_reply": "2026-11-13T19:45:17.110548Z" + } + }, + "outputs": [ + { + "name": "stdout", + "output_type": "stream", + "text": [ + "paper: P(C2 > C1) = 0.978 (Fig. 3)\n" + ] + }, + { + "data": { + "text/html": [ + "
\n", + "\n", + "\n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + "
P(C2 > C1), expectedP(C2 > C1), replicatesstandard errormean difference
costsdraws
published countscommon0.97790.97820.00100.6647
independent0.94910.94750.00160.6690
TAT-C deploymentscommon0.99910.99920.00021.0559
independent0.99480.99590.00051.0601
\n", + "
" + ], + "text/plain": [ + " P(C2 > C1), expected P(C2 > C1), replicates \\\n", + "costs draws \n", + "published counts common 0.9779 0.9782 \n", + " independent 0.9491 0.9475 \n", + "TAT-C deployments common 0.9991 0.9992 \n", + " independent 0.9948 0.9959 \n", + "\n", + " standard error mean difference \n", + "costs draws \n", + "published counts common 0.0010 0.6647 \n", + " independent 0.0016 0.6690 \n", + "TAT-C deployments common 0.0002 1.0559 \n", + " independent 0.0005 1.0601 " + ] + }, + "metadata": {}, + "output_type": "display_data" + }, + { + "data": { + "text/html": [ + "
\n", + "\n", + "\n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + "
exact shareTAT-C sharestandard errorexact variance (millionths)
costconfiguration
C1G4c0.1640.1640.00319035.599
L3e0.8360.8410.01097082.544
L4f0.0000.0000.0000.000
C2G4c0.8270.8340.01041957.088
L3e0.0000.0000.0000.000
L4f0.1730.1720.0038800.728
C2 - C1G4c0.0410.0410.0014470.893
L3e0.8800.8850.01097082.544
L4f0.0800.0790.0018800.728
\n", + "
" + ], + "text/plain": [ + " exact share TAT-C share standard error \\\n", + "cost configuration \n", + "C1 G4c 0.164 0.164 0.003 \n", + " L3e 0.836 0.841 0.010 \n", + " L4f 0.000 0.000 0.000 \n", + "C2 G4c 0.827 0.834 0.010 \n", + " L3e 0.000 0.000 0.000 \n", + " L4f 0.173 0.172 0.003 \n", + "C2 - C1 G4c 0.041 0.041 0.001 \n", + " L3e 0.880 0.885 0.010 \n", + " L4f 0.080 0.079 0.001 \n", + "\n", + " exact variance (millionths) \n", + "cost configuration \n", + "C1 G4c 19035.599 \n", + " L3e 97082.544 \n", + " L4f 0.000 \n", + "C2 G4c 41957.088 \n", + " L3e 0.000 \n", + " L4f 8800.728 \n", + "C2 - C1 G4c 4470.893 \n", + " L3e 97082.544 \n", + " L4f 8800.728 " + ] + }, + "execution_count": 7, + "metadata": {}, + "output_type": "execute_result" + } + ], + "source": [ + "from tatc.tradespace import attribute_variance, exceedance\n", + "\n", + "key = {d.key: d.constellation for d in designs}\n", + "rows = []\n", + "for name, (_, table) in EVALUATIONS.items():\n", + " for draws in (\"common\", \"independent\"):\n", + " compared = exceedance(results[name, draws], \"cost\", designs)\n", + " row = compared[\n", + " (compared.design.map(key) == \"C2\") & (compared.other.map(key) == \"C1\")\n", + " ].iloc[0]\n", + " p = row.exceedance\n", + " rows.append(\n", + " {\n", + " \"costs\": name,\n", + " \"draws\": draws,\n", + " \"P(C2 > C1), expected\": probability_exceeds(\n", + " *moments(table, correlated=draws == \"common\")\n", + " )[1],\n", + " \"P(C2 > C1), replicates\": p,\n", + " \"standard error\": math.sqrt(p * (1 - p) / row.shared_replicates),\n", + " \"mean difference\": row[\"cost difference\"],\n", + " }\n", + " )\n", + "print(\"paper: P(C2 > C1) = 0.978 (Fig. 3)\")\n", + "display(pd.DataFrame(rows).set_index([\"costs\", \"draws\"]).round(4))\n", + "\n", + "# the shares of the variance of each cost, and of the difference, that each configuration's score causes\n", + "attribution = attribute_variance(\n", + " Study(space, build, published, replicates=10_000), [\"cost\"], designs\n", + ")\n", + "c1, c2 = (\n", + " next(d for d in designs if d.constellation == name) for name in CONSTELLATIONS\n", + ")\n", + "difference = attribution.differences([(c2, c1)])\n", + "ba = exposures(PUBLISHED)\n", + "variance = np.array([VARIANCE_Q[c] for c in CONFIGURATIONS])\n", + "exact = {\n", + " \"C1\": ba[0] ** 2 * variance,\n", + " \"C2\": ba[1] ** 2 * variance,\n", + " \"C2 - C1\": (ba[1] - ba[0]) ** 2 * variance,\n", + "}\n", + "rows = []\n", + "for label, shares in [\n", + " (\"C1\", attribution.shares[attribution.shares.design == c1.key]),\n", + " (\"C2\", attribution.shares[attribution.shares.design == c2.key]),\n", + " (\"C2 - C1\", difference.shares),\n", + "]:\n", + " for c, part in zip(CONFIGURATIONS, exact[label]):\n", + " share = shares[shares.parameter == f\"cost_risk.{c}\"].iloc[0]\n", + " rows.append(\n", + " {\n", + " \"cost\": label,\n", + " \"configuration\": c,\n", + " \"exact share\": part / exact[label].sum(),\n", + " \"TAT-C share\": share.total,\n", + " \"standard error\": share[\"total se\"],\n", + " \"exact variance (millionths)\": part * 1e6,\n", + " }\n", + " )\n", + "pd.DataFrame(rows).set_index([\"cost\", \"configuration\"]).round(3)" + ] + }, + { + "cell_type": "markdown", + "id": "03b50728", + "metadata": {}, + "source": [ + "`exceedance` reproduces the paper's probability: with the published counts and common random numbers, C2 costs more than C1 in 97.8% of the replicates (97.82% against 97.79% expected, with a standard error of 0.10%). With independent draws, it does in 94.8% (94.9% expected). With TAT-C's own deployments, C2 costs more in 99.92% of the replicates with common draws and 99.59% with independent ones (99.91% and 99.48% expected; the larger gap is 2.2 standard errors), higher than the paper's for L4f's counts (Test 2). The shares of variance that `attribute_variance` estimates match the exact shares within about one standard error (0.001 to 0.010).\n", + "\n", + "The shares show why sharing G4c settles the order. G4c is 16% of the variance of C1's cost and 83% of C2's, but 4% of the variance of their difference: of its variance in C1 (19,000 millionths) and in C2 (42,000 millionths), 4,500 remain in the difference, since a costlier G4c raises both. The variance of the difference (110,000 millionths, against 167,000 if the costs were independent) is mostly L3e's, which only C1 flies. The joint distribution of the costs of the replicates (Fig. 3 of the paper), with the ellipse that holds 95% of the normal distribution of eqs. (6) and (8):" + ] + }, + { + "cell_type": "code", + "execution_count": 8, + "id": "4cc9a667", + "metadata": { + "execution": { + "iopub.execute_input": "2026-11-13T19:45:17.110548Z", + "iopub.status.busy": "2026-11-13T19:45:17.110548Z", + "iopub.status.idle": "2026-11-13T19:45:17.282746Z", + "shell.execute_reply": "2026-11-13T19:45:17.282440Z" + } + }, + "outputs": [ + { + "data": { + "image/png": "iVBORw0KGgoAAAANSUhEUgAAA90AAAGuCAYAAACN52XAAAAAOnRFWHRTb2Z0d2FyZQBNYXRwbG90bGliIHZlcnNpb24zLjEwLjEsIGh0dHBzOi8vbWF0cGxvdGxpYi5vcmcvc2/+5QAAAAlwSFlzAAAPYQAAD2EBqD+naQABAABJREFUeJzsnQV8U2f3x0+buheHFnd3BkPHhsOGy9y3V+a+/9y3933nwt53bjgMNtjYgA3ZcHfXlrbUNWma5P/5nfTJbi9Jmhpp2vPdp6Oxe597c3uPn+Nns9lsJAiCIAiCIAiCIAhCpeNf+ZsUBEEQBEEQBEEQBAGI0S0IgiAIgiAIgiAIVYQY3YIgCIIgCIIgCIJQRYjRLQiCIAiCIAiCIAhVhBjdgiAIgiAIgiAIglBFiNEtCIIgCIIgCIIgCFWEGN2CIAiCIAiCIAiCUEWI0S0IgiAIgiAIgiAIVYQY3YIgCIIgCIIgCIJQRYjRLQg+RIsWLejtt9/29jIED/j999/Jz8+PMjMzvb0UQRAEBvek77//nnyB5557jnr06EHVheq2HsE9oi8J1Q0xuoVqR1JSEt1zzz3UqlUrCg4OpqZNm9KECRNo9erV3l6aUAF+++03Gjt2LNWtW5fCwsKoU6dO9NBDD1FCQoLDSL3mmmuocePGFB4ezsrNt99+e0nWtmjRIho2bBhFR0dTREQEdevWjV544QVKT0/n18+fP0/XXnsttWvXjvz9/en+++8vdZuXX345fw7brAi47rGtyMhIatSoET322GNUVFRUQhGEIq3/wTl0x9atW+nKK6+kmJgYio2NpVGjRtHu3bsdr586dYqGDBnC28G/eKxl/PjxfN4EQah6br75Zpo4caK3l+HzfPHFF3zPq22UpldB1uH19u3bU2hoKDVr1ozuvfdeysrKqvK1HTt2jG655RaKj4/ntbVs2ZJmzZpF27Ztc7zn5ZdfZjkI3cHT7w8y7s4776zQ2pKTk/lvr0mTJrzv0aNH09GjR52+12az0ZgxYzxybOXm5tI///lPPmacb+hDs2fPLvGeBx98kOrUqcPflV4XWrBgAX9/gm8hRrdQrYBi37t3b1qzZg3961//or1799LPP/9MV1xxBf3jH//w9vKqPWazmaojH3/8MV111VVsNMJQO3DgAAsYCPT//Oc//J4///yTjV28vmfPHhbCN954I/34449ut33mzJkKre3//u//aMaMGdS3b1/66aefaN++fbwmGKBff/01v8dkMlH9+vXpqaeeou7du3u03aCgID5eCODygjXAUQFBv3PnTpo3bx4tW7aMHn/8ccd7Hn74YTbutT8Q4NOmTXMr8LFNKFabN2+mDRs2sFEPw1tdQ3CIxMXF0a5du9gRgv0osA44H6ZMmVLuYxMEQahJFBYWkq/qVYmJifzz73//m2UgnBN4z2233eZ22+fOnWNjs7zAsMbajhw5wnoCdIMlS5ZQhw4dWAZpzy1k2t/+9jePtw2ZDUO5vOC44Og6ceIELV26lGVw8+bNWZfJy8u76P2Iqnsq72FQ4/x+8803dPDgQXbkwwiHfAc//PADfffdd/TLL7/QG2+8Qbfffjulpqbya9CboLd88MEH5T42wUvYBKEaMWbMGFtcXJwtNzf3otcyMjIcv58+fdp29dVX28LDw22RkZG2adOm2ZKSkhyvP/vss7bu3bvbPv30U1vTpk35fX/7299sRUVFttdff93WsGFDW/369W0vvfRSiX3gT2L27Nm2cePG2UJDQ20dOnSw/fnnn7ajR4/ahg4dagsLC7MNGDDAduzYsRKf+/DDD22tWrWyBQYG2tq1a2f76quvLtru//73P9vEiRN5u23atLEtXbrU7blITk62jR8/3hYSEmJr0aKF7ZtvvrE1b97c9tZbb5XYLvY9YcIEXhuOG8d466238mfwWazn7bffdnxm7969Nj8/P1tKSgo/TktL48czZsxwvOfFF1+0DRw4kH9PT0+3XXvttbZ69erx9rD2zz77zOYpZ8+etQUFBdnuv/9+p69rv1c9Y8eOtd1yyy1ut+/v72+78sor+Zzn5eXZysLmzZv5HGrPT2lrw3Vw3333lbrt3377jbettvH555/boqOjbT///DNfV7gmR40aZUtMTHS5jSeeeMLWp0+fEs8tW7aMv4fs7Gynn9m1axfvd926dS63u3XrVn7PmTNnHM/t2bOHn8O1Djp27Gj76aef+PcVK1bYOnXqxL/jeHANaD8rCELVctNNN9muueaaEvehe+65x/bII4/YYmNjWabh/q/lyJEjtsGDB9uCg4P57/mXX37hv/ElS5Y43oO/Y8hP3JuwHcjVkydPXrTf5557jmUA5O1dd91lM5lMjvdYLBbbK6+84pA53bp1sy1YsOCie+GqVatsvXv3ZhkIOXro0KES63311VdtDRo0sEVERLAMe+yxx1iOa4Ecxf0Tx9S+fXvbBx984HgN68Z+Fi1aZBs2bBjvB2uBDNeuQ/ujP2dlWY86N9AjGjduzMcPIItwnPgcvpdZs2axPFfgtX/961+Ox9hGQECALScnxyEztfdiHCPuuThmrGfKlCm2qtCr9MyfP59lt9lsdvmem2++mY/7mWeesR0/frxM67JarbbOnTvz+cA15MnalBz1BGf6Uln0sMOHD/Nn9u3b53gO64TuiO1o2blzJ5/j8+fPX/Q35gwc9wsvvFDiuV69etn+7//+j3+HnqrVyfC9b9myhX+/8847bW+++aZH50CoXojRLVQblPEH4e0O3PR69OhhGzRokG3btm22TZs28U0bSogCghQCb+rUqbb9+/ezoQLhASMHigqEPQxH3BzxeQUe48Y5b948vuHi5gyBMnz4cDaWDhw4YOvfv79t9OjRjs8sXryYjW0IRnzmP//5j81gMNjWrFlTYrvx8fG27777jgXpvffey+vDMbsTlBDwGzdu5OO8/PLLWVDohQhuxjgWCDw4IwoLC1kAwrA6ceIEG+swyHFMStBBeVJK0ffff8+PGzVq5NjuVVdd5bj5/+Mf/+Dzje1Bqfn111/5fCpw3qF8uALCAet0Z1y6Aob/Qw895PY9+C5hnDZr1ozPKYz033//nY+zNNT3gHPmKRUxunGd4NziXG7fvp0VYTg0XPHggw/yda4F5x/bxfad8c9//pMdLe6AwV63bl3+O4HynJ+fz8eE9SgFa+bMmXzu8fcGhwkeg9tvv73ENSgIgneM7qioKDaGYVx/+eWXLD9hWAP83Xbp0oUdknDErV271tazZ88SBgHue/ibh0EJpxvkG+5HMGaVUY394h4JAwDGx48//shGx5NPPulYC4xOGMKQkZBDuNfBQMR9WHsvvOyyy/g5yGQ4AyDTFJBP+Mwnn3zC93TIHxj4WiMXsgzGLYxqyDb8W6dOHdsXX3xRwujGWrBOyGPoADC+cF/DMcHBivMG4wg/ytDV48l61Lm54YYb+Nwo4wzOfjgqcS4gv+FggDzX3tfh2AeQUzgGyGDl5MRxQg8BkBXQJ6A7nDp1yrZjxw7bO++849gWzrW7+JmnepUzYFhiXaXJEhwvrkc4wPG94rErp7AWHAvWjmPzlIoa3WXRw5QjWh9kwTa0Og+c/fg7gi6l9lOa0X3HHXewQ/3cuXN8DUBfxFrwdwrwt9S6dWsOekD/w7WH39evX8+fQ3BF8D3E6BaqDSrqCCPWHVAqIIS0kTYIcXxWeQJhTMDQ1N74YXDDgNZ6VKFcwJutwDaeeuopx2MITDwHIaKYM2cOe/MVUBxwA9WCyAGitK62C48znlNC1pWHVR0POHjwID+nFyKuIshaYDhrveOTJ0/m5wA+r6Il2AcUMZw7pbwhiu4u2gyF4/HHH3f5OjIMoOSUFSg9cJRovczuUIILnncIqJYtW/J1AOXMFVCEEAkpCxUxuvUCHI4aREJcsXLlSlZkoCRAyEJAQ6lxpagUFBTw9wgveWkg4wFCHdvHD/4WoNQpsC8ohsgUwb94DIUAAh9KCq5xnGN91EsQhEtjdOsdcn379uVorLp3IHqakJDgeB3yRmsQfP311/x3r3VQ4m8Zzl18Xu0XRqE2i+ijjz5iAwGy1Gg0srxQ0WTFbbfdxhFefaRbsXz5cn4O9ywAw/Tvf/97iW3ASNcaubhf6e97yMrCZ7VGNwxlvW4A2VYWo82T9eDc4P5d2v1PZRYpAx9Oa6wB93Q4RODwhkxR3x0cm8oZC8cC5KcrIxb6Er7DiupVei5cuMCObK1zpTQgP/B9wOmLa+K6665jPcKVAxwyHmuD8X2pjO6y6GHQhXAOIOtg8OJ7fu211/gzI0eOdLwPkWdc79r9lGZ04+/mxhtv5Pfi7xS6DhxnWqC/4JqH8wzfH/aP32GEv/fee3yeoX96qiMJ3kdquoVqg6d1Qah/QWMJ/ChQw4rmGnhN27kSdaqKhg0b8vtQi6p9LiUlpcT2UVesfR107dq1xHNGo5Gys7Md6xk4cGCJbeCxdi367aI5VVRU1EX71h5jQEAA1zopUOPkrIFInz59LnoOtT74LGqa0Bjsv//9b4na56FDh3LjMrB27VoaPnw4N8vCc2g+grpedUyooZo7dy43Nnv00Ue59lrLV199Ra+++iq5+17LWteMpmuo6f7f//5HnTt39ugz2Adq1D7//HOuMxswYAA9//zz9MADD7hd26UE9WWtW7d2PEattKtrAIwcOZJr8O6++25uMINGbqjxBtrrWIFauJycHLrpppvcrqOgoIBr9fAdb9q0if744w/q0qULjRs3jl8DqOdGPT2uG/xbr149+vvf/861+C+99BL/bR0+fJibyqAWTxCES4tWpujvJ0pOogGUAvdEfc8INLHC3zLkBH7QuAny7fjx4473oY+FtjYW20FfiLNnz/Ln8/PzacSIEY5t4AdyQbsN/XqxVqBd72WXXVbi/dr1ooYW28N9S7sf3IvKsh9PKW09CugG6N+hZfv27dzkCj0zcG4hb4GSwYMHD+b7NGqEIX/xOhp5amUyHgOcV9QRowHaDTfcwA21cL4VkyZNokOHDlWqjINuA1kAfQmNOj0F60TfE8iFDz/8kOugIcNcNWO71PK3rHpYYGAgLV68mOvN8XeBvwHoJmiWpuQvarBRK1/WLunvvfcey158HtcL+sigvn7VqlWO9+Dc4+8LNfj4nqFnoZ4c68J1j14sqPVG7xvBNxCjW6g2tG3blg0ndwKkLODGpAXbdvac1Wp1+TllLDp7Tv+58qynrNtwhr5LNQxkNL2CcoImHGiEBQNW2+QFAh0NS2Aw4d9BgwY5hD4EPgx5pWRBwJw+fZqNVzRaQcdrbVOt0oChCKGLBl+egP1DYXnrrbfKLEx27NjBDUlwLaErK5qVuHMIYG1oknKpGtA5uwZKUzxwDBg7BoUNjVTQ4R1ACdPzySefcFdx5SxyBRq0oLkOHBRoINe/f39+7uTJk6woOeOVV15hBQrOHFwnaKKG45k8ebJDWRQE4dJRUZkCwxl/z5AR2h8YGZjW4Ok2wPLly0tsA3Jl4cKFLtdbVjmq9gNHrHY/aPoF46Wy9lNR+QvnABpSwpiDgQwnNpyhQMlgOM/hyFDyFrIXTm8Y4Tj3kMvKUIfRDrk2Z84cdiA888wz/FlPR1GWVa+CMwBNNrFfrFt/jbkD8gnGZL9+/eiOO+5gZz4ao7qa4AH5CypL56uKvxn194HzDR0Gzc/S0tIc8hcGN5w++E4RKMEPgHxUjhM9cGw/+eST9Oabb7KuA0cAmqihoSsa2TkD5whN11588UW+bnC9IKgyffp0vj7wvQnVHzG6hWoDPIkQVojSOusMqYRMx44d2cOOHwUEPF6HZ/ZSg/UgUqgFjyuyFkS1MRYKHlAFvMeeCFrsG6M1EJXs2bMntWnT5qJIALzzGBMFbyki2IgYQEBAAcANXS8scHNH9BQ3fXh0ETn3lKlTp3IkAB04naE9JuwbHvbXX3/d41EfiGq/9tprHBHHcWME2aeffsrPw3uM78cVUCyhzMErX9ravAkUA0SsMFoEyhciWL169SrxHhjM8MKX1m0WIFICT702A0E9dqaAIOoDoxwCH1gsFoejAv/isSAI1QclJ7XOTr1xinsIDLwGDRqwnND+aA0lRMRVBozaDmQG7kOQc8jCgVNQvw1tNpon68UkBS3a9cKRiHsgnKT6/WDElKdAFnlyvyptPa6AcQSjDDIJEW3IcmeRVBjVuF+vW7eO5S30H+wTo7FgXCuDFMCQQ4QTMhSTPeAwhbFXmXqVinDDsYpzhAhsSEhIqdvHZA+Mr7r66qv5+/nss8/ouuuuYzkMBy6csq4y3aB74PqBnHYmd6qL/AX4e4AehL8XdFxXzm9MEsF3onUEAQQN4NR2BmQmfvTZagaDwel5gGP+rrvuYiMdf3d6+QtEBvsGYnQL1QoIBtw84CmFhxQ3OCj87777riO1C8IHRiNu7PDwbdmyhSOiEGLOUq2rmkceeYTHa3z00Ue8XtwYkZJUlmiwHszKhLcZN1oIfhjfSCOC0eWJZxtCYeXKlew1f/rpp9nbrgVCEJ5SeOKVgQ1vKwQoIsTKyw7gWYfwRJrT/v37OdVYa8ji3D/xxBMu1wPFCwLonXfeYYMQhj0i53AO4PiUIQcFBAY3ZoPCS4y5ovhRs7LdpbTBI4/ULCiYUAAQ7VUeZ3cgfRAp8xhNgn83btzIa8M5wHiSL7/80vFeJVBhpF+4cMERzalq1IgXnHucKyhz+HuAgNYCZQfKGjIT9KgRLAqkLGZkZPA5w98Xto1sCJwzpOjrBT4cIPgOVVQHaemIOOGzSCPVl1cIguBdICdhuMFZCqN5/fr1PGZIC2QoykZgQOB1OO7g+MQ9GE5LBSK0uHfjfrdixQp69tlnOTIHowERUcg6ZELhfgkHL+QyIp7a+2dp3HfffXwPg6ECuYV94L6kBeVCyFzC/Q/vwX0R74fM9RSUneEejns8IrPaVO2yrscZSCmH0Yrjh4MAxquScVogdyGjcc9V92Y8B5mslb+QtzheyBvIJtxvYZhBR3B2by+vXqUMbhjmcFrjsZLB7gw6OPcx31vpHYjW49zBQC0N6CHq/MJBgWsL5wxGLJwPyrAFcOrgHOBfrEcrj6sS6BP4m1BjwyA7MUYM5wpgLChKs7Q/6jrQOoPwHamMB2RB4DuG7oht4+8OOiS+W6SRO8tgw/lUc7khb+F0gRMIclmVVwo+gLeLygVBD7pco8kXmmCguQS6eGKMibZbs6cjw9w1onHWFEvfAEM1ZsE4CFcNsjwdGaZvrIFmIGgK4gp0VkUDK3RQRTMPbNNZYxD9dtGgA83EsP2YmBhuZIZGZ/rzge3om4joR5cANEZBZ04010FDHbxH25ystO7l2q7baGaHRl9oRIcOsw8//LCjqzm2oR/ngh9tV3pnqAY5FQENXYYMGcLXEq4pNFfDOA/td+xsbfg+yjoyTAu+u9Juw1dccQV/DucMjXzQFVcPGhqho6qrpjfOOtyiwQ26w6tRQejQj8aBejBCTz+iBuNv0BVZ/e2VdVSbIAgVb6Smb+iI17X3YjTkRLM1yFHIJXRE1ssMyBk0dEKXasgayDE0Bs3KyiqxX0zEwMQDNFDD65AzCjTKQldwNPSCDER3c9zrVSdmZzITMhXPaceTvfzyy7wO7AP7ffTRRy+SW99++y1P08Ax4b6F+7ZqEuZMXmOf+mkPd999Nx9LaSPDSluPM50CoNkbmrbifKIhGxqn6dflbFSnkge45yrQrRrfNY5VjUBTk0g86V7uqV7lbJya+tF+R3rQBdzdSDFPwHWKa7BJkya8NqwRTfi0DdZc6QeupngAT/Sl0vQwdIqHbMV1DT0MjdhKa5znbD94Trsf/N1BT8MxQ7bjbweTb/RN56DX4ji0DRHB888/z/oY9Cg0yxN8Az/8z9uGvyAIgiAIglC9uPnmmznN9/vvv/f2UgRBEHwaSS8XBEEQBEEQBEEQhCpCjG5BEARBEARBEARBqCIkvVwQBEEQBEEQBEEQamKkG6MS0I0PYwbQxVBfMwR/ADonoyMvujajGye6LroDw+SxLe1PaZ0dBUEQBEEQBEEQBKHGGd0YTdC9e3ceZ+AMzCTESIPZs2fz2CSMq8G8QaPR6Ha7mNeL0UHqZ8OGDVV0BIIgCIIgCIIgCILgmtIH2VYhmCfrbKasinK//fbb9NRTTzlm9WGGXcOGDTkiPnPmTJfbxdxDzM4TBEEQBEEQBEEQBG9SbRupYVh8UlISp5QroqOj6bLLLqONGze6/SxS0JGy3qpVK7ruuuvozJkzbt9vMpkoOzvb8ZOVlUUXLlxgw18QBEEQBM8QeSoIgiAIPmR0w+AGiGxrwWP1mjNglH/xxRf0888/00cffcTG++DBgyknJ8flZ1599VU26NVPTEwMNWjQwO1nBEEQBMEbwIBdv34tffPNl1TdEHkqCIIg+JI8XbNmFc2d+23tNbrLC9LVp02bRt26deP67xUrVlBmZibNnz/f5WeeeOIJ9sarn7Nnz17SNQuCIAhCWRWFdu2qX5NQkaeCIAiCr8nT9u071Oyabneomuzk5GTuXq7A4x49eni8HXjZ27VrR8eOHXP5nuDgYP4RBEEQhOqK1WqlxMREio+PpyFDhlF1ROSpIAiCUN2xWCyUlHSe4uLi6corR1ySfVbbSHfLli3Z8F69erXjOdSHoYv5gAEDPN5Obm4uHT9+vIThLgiCIAi+piD8+OMymj//O0nVFgRBEIRyUlRURMuWLaEFC+ZSfn4+XSq8anTDIN61axf/ANRf43c0PsN87fvvv59eeuklWrZsGe3du5duvPFGbpA2ceJExzauvPJKev/99x2PH374YVq7di2dOnWK/vzzT5o0aRIZDAaaNWuWV45REARBECqqICxdupiOHj1M48dfQ5GRkd5ekiAIgiD4HIWFhbRo0QI6deokXX31JAoLC7tk+/Zqevm2bdvoiiuucDx+8MEH+d+bbrqJm6E9+uijPMv7zjvv5LrsQYMGcYO0kJAQx2cQxU5NTXU8PnfuHBvYaWlpVL9+ff7Mpk2b+HdBEARB8DUFYcmShZSYmECTJ0+jli1beXtJgiAIguBzGI1GWrRoPk/UmDp1BjVt2uyS7t/PJnM8LgJp7Oi6iiYwUVFR3l6OIAiCUEuB43nx4vk0bNiVl1xBqAxEngqCIAjVAZRmwYl91VUjqUmTuEu+fzG6nSBKgiAIguBNUGeGxmkRERHcWRUlV76IyFNBEATBm+Tm5pC/v4FTyb0pT6ttIzVBEARBqK3e+Llzv6Hly3/gx75qcAuCIAiCN8nKyqTvvvuGVq5c4XV5Kka3IAiCIFQT0L9kzpxvqLDQTCNGjPT2cgRBEATBJ0lPT2N5Cjt7+PCrvL0cMbp9HTSW69OnD3Xr1o369+9Pu3fvdrw2bNgwHr2Gueb4eeuttxyv3XXXXdS1a1caPnw4p/0BpFyMGTOGm9OVh6VLl1LHjh15X+g2r+X333/ntSrQXR4z1GsaN998M7399tsevbdevXp8HsDYsWPp8OHDbt//3HPPcRMId+Dcq3FCLVq0cEwGKAtoYnjo0CHHY0wPeOCBB+hS8fHHH1OHDh34WNAQ0ZtgMsJrr73meIzrGn9XuM7xs3jxYn5+z549/LdzKdaDa8wVmN4wd+5c/r2goIAnPnTp0oV/rr76am4ecinXK5QNXO92BcGPZs26nurUqevtJQmCIAiCz5GSksLyNCgomOVpdLT3bQ4xun2YjIwMuu666+jLL79kJfpf//oXP9YCQ1uNZVOG0759++jo0aMOA+Lrr7/m5z/55BPuJt+6detyrWf27Nn0zDPP8L5g0LszuqvbOB5vs2LFCmrfvr3b9zz//PMujW51DDj3FR0npDe6YaxpHTZVDZwWn3/+OR9L3breMzpgtL755pt0zz33OGpsr7nmGh5jePDgQf47Gjx4ML8Gp1dwcDCtWbPGa+tNSEjg62jGjBkO5wXWjL9zrLVhw4Z8j6gu6xUuJjU1hUJDQ4sVhGhvL0cQBEEQfJKUlCSKjIyimTOvo4iI6jFmU4zucoKoMBTaqvwprccdItIwSjp37syPYQBgxvmOHTvcfi4wMJBMJhM36UFn3KCgIDp//jzNmTPHMbbNFceOHaOrrrqKlXZEIr///nt+/t5776X169fTk08+SZdffnmJz8B4gkH+7bff8mdeeOEFx2vPPvss9e7dm9q0acMGg2Lr1q0chUcUv2fPnrRgwQKn60HUD1F7zGtv164dTZ48mUfsqDnwt956qyPSB6NVAWcD1jxgwAAaOXIkG5o4Loyb69SpEx/DgQMHeM47Ipp4D7YHVq9ezZ/DunDuP/30U/IERIyxLZw7jMPToo1Kw6hTGQP4OX36NN19992O7xjPwYOHY8fxDRkyhI8PIEKG9FQFzrk6v8rg0u8P4DzDMQLHC0b5wUGD/eA7wbmZOHGi473YDo4bjhU4eVSmBCLxMPgmTJjA5xDfX3p6utNzgX3gHONc9OvXj/744w9+furUqXxd49jwux5E8e+44w7+DD6LcYLq+4ajANvE2rBe9b0CHBfWhGPCujdv3lzq97Vw4UIaOHAghYeH8+PvvvuOs0kwhhAYDIYSowhx7cDQdYa7a8bdNYzjxTmFQwb71WeQaPnss89oypQpjnol/Iv7iNlsZqcMrt/4+HiP1itcWvA3hPt9+/Yd6YYbbubmaYIgCIIglA2lk3bp0o2uu+7GSzqHu1TQvVwoSVZWFqxd/tcVeXl5ts6dO1bpD/bhjszMTFudOnVsf/zxBz9eunQpr3vRokX8eOjQobb27dvbunTpYps+fbrt+PHjjs/+3//9n6179+62qVOn8n5mzJhh27ZtW6nnpl+/frbZs2fz70eOHOH9nzp1yrG/JUuWOP3cs88+a7vvvvscj0+ePMlrXbhwIT/+6aefbO3atePfMzIybD169LAlJiby4wsXLtiaNm1qO3fu3EXbvemmm3hNOIaioiLb5Zdfbvvuu+/4tUcffdR27bXX2iwWiy03N5e3OXfuXMdaR40aZSssLOTHn3/+uS0qKsp2+vRpfnz99dfbWrVqZUtKSuLH48aNs73//vv8e3p6Ou8LpKWl2Zo1a2Y7e/asYz1vvfXWRetMTk7mc7V//35+/PHHH/Px4zyA5s2b23bu3Mnbjo6OtuXn5/PzOK6CggL+He/HudEee7du3WzZ2dmO57TvwTZvuOEGm9VqdZxDda2o/Sl69+5t++2335x+jzg311xzDf++YsUKW4cOHRz7uOOOO2x333234zvGdlNTU/kxrqlXXnnlonNhMpl4LT///DM/Xr9+va1hw4a2nJwcp2vTgv19+eWX/DuO67bbbrO98cYb/LhPnz62Tz75hH/fs2ePLSgoiNcO8N2q6wnfudqXO2699Vbbe++953j8wAMP2G6++Wa+FvC3g3ObkpLieB3XTt26dZ1uq7RrxtU1/PDDDzu+Q/y949zj/c4YPny47YcffnA8xnWDv3tcT7j2xowZw38LnqxXuHScPn3K9tZb/7Lt3r3LVlvlqSAIgiBUlOPHj9nefPMN28GDdl27uiGRbh8G6YeIxj3xxBMczfzll184mhcQEMCvI20c0T+kniNCOn78eMdnEU1FpBMR5F9//ZWaNm3K0c9bbrmFo2Xz5s27aH+IuiGKftttt/Hjtm3bcvQNEe7yEBISwlE9gCigqiX/888/6cSJE1xzisgkItDAVc0zotHwZCHyiAio2s6qVas4Kurv78/RStS34lgV119/PUf9FVhDs2bNHJHfvn37ckouwO9IyVd1l9OmTePoMqK5eIz0XXds2rSJI7P4fgDOITIM9GCkDs4r1oYoJCLFOE+uwDrcpZNjP4h4on4c5xrnpCLg84i8qnr8v/3tbyXO6ejRox0p4drvVAu+R3wno0aN4se4hnCePak/R2YFIu24LhA1xrWH7AuMJcLnVb0zotkqIg0QRb7hhhvonXfeoZMnT3oUSTx37pzj+weIFuP48b3s3LmT4uLi+PgVjRo14mvBWQlAadeMq2sYEXL1HeLv/dprr/V4vbgfIJslKSmJM1nwnaH8w5P1CpeGEyeO0aJF83leaIcOHb29HEEQBEHwSQ4fPsQzuFu0aElt2rSj6ojdOhPKDOrutmzZVuX7KA3UYOMHIGUcirQy7GBIAyjs//znP7nJEpRsbZ0sjJV///vftHLlSnr11Vdp6NChbPB1796da3lLW0NFWu+jplR9HsaGxWLh3xGwRQoujG9P0Bql2I6rGm39WvWGl347rraLVG80Plu0aBFvs1evXmU2XFydN+wHBjqOHeneSGdG2r+qHdZT1jRUtV84ZtT5BuU1vPTH4el3Udp2XIFrA+cdadhacB272yY+s337dj6n+O7gdJo5c6bbfcEI1p4XOGTwtwZjG+DvRDkOAN6LY3bmTCntminvNexuvf/973/ZSFfbRinAK6+84tF6harn8OGD9OOPy6hVq9Y0YcJEh7NUEARBEATP2bdvD/388wp2Xo8ZM551m+qIRLrLCZRfKLlV+eOJIYIIluLFF1/kKBrqd6G0JycnO16Dso8omL4x1eOPP87RL+wP9d3YJ35QB6rqShWIqMJYQJMrgAjjhg0buKa4NBDBVXUWpYG6XEQjtVFZRDH16ykNRMhROwtDDceGyD/qfCujgV3z5s35PK1bt65Ex3hXIOqLjAPVoAz1t86OB9kE+N5gZD/99NMcrUVUVZ1/T8+hQtU0I2K+ZMkSjvgCXCOqrnnLli0lsgjcfVc4p/Pnz3cYuYj6lvWcoj4ZEVgVIYeDAdFYRK9LA7Xar7/+usMoxXeB6xBrRuT7q6++4uf379/P1ybAexE5RvYCHE+oFccxlwYyE7TnZfr06dxrQB076t3hnFKguRoi2YjiV8Y1o843/t5wDWO/cMB4ut5WrVpxtBufxc/y5csdtf+lrVeoWvB97Nu3l9q370BXXz1JDG5BEARBqIA87dq1G40dO6HaGtxAtC0fBwYzxivBiELDLdWgCVHvcePGcZotDIMPP/yQG3lpQfMqdGgeMWIEP/7HP/5BH3zwAX8GqbjOuueiMRdSz7FNGC9oUKVSst2B9FkYzvpGas6IjY1lAwFROewHkXs4B2ColQUYrUgfx/FcdtllHLmH4VRRMEIK68GxwHjGtksDDbfwXpwHHBNS1Z115oaxizRwrBlGFJwfN910E7/20EMP8XelGql5AvaL0gOkLCPbQTW5Q6QX3zXWgnWpZnwAzclw7lUjNS1I+UcJApwIWCMMQWRIlAVEVjFqC030cIz3338/l0l4ErVHF3VkX2Bt+CycCGrsGgxuRHdhSD711FMOZxAi+qqhHj6HiLdqGIi/HzT5cwaub2SAKHCdq0aB2Dc6f2s/i+78zpq/lfeaUdcw/kbxN45IuTZlvrT1orEdmqepRoJw5rz88sserVeoOtDcDs6Xa66ZXO0VBEEQBEGo7vJ0ypTpNHLkmGofRPBDYbe3F1HdgCEBgxMGECJogiD4HjAo0cfA3Vzr0oDjCsYravrdgawFRNJhiKN+3hvAKQXnCuretV3Kq+t6ayObN2+kLVs20S233F5tRphUNSJPBUEQhMoEpusff9izBm+99XYKDa1GHcrdUL1dAoIgCF7k3XffLVGm4QqUQyCa7U0DFh5epPuryH91X29tUxDWr19L69b9Tr169aHwcBkJJgiCIAjlkae//baaNm78k/r06eczBjeQSLcTxDMvCIIgVAYQsWvWrKIdO7bR0KHDqV8/z0oLagoiTwVBEITKwN4P6Gfas2c3XXXVSOrZszf5EtK9RRAEQRCqiKysTNq/fx+NGDGKevTo5e3lCIIgCIJPkp6eTocOHeQO5V26dCVfQyLdThDPvCAIglAR0MAP4hWdyQsK8n0qBa4yEXkqCIIgVARMoUHDNDQe9WV5KjXdgiAIglDJCsLSpYvpp59+5Me+qiAIgiAIgjcpLCykxYsX0K+/rvR5eSpGtyAIgiBUooKwaNF8On36FHXp0s3byxEEQRAEn8RkMtLChfMoMTGROnfuQr6O1HQLgiAIQiVgNBrZ4E5NvUDTps2k+Pim3l6SIAiCIPjkDO6FC+dxX5QZM2ZR48ZNyNeRSLdQKTz88MM0d+5cr+wbc5Tvv//+Kt0HxjDNnj3bI6W7d+/eXL8oCELtYt++PZSenkbTp88Sg1sQBEEQysnu3TspJyebZsy4rkYY3ECMbqHCJCQk0IoVK2jGjBlUU/HU6A4JCaEbbriB/vOf/1ySdQmCUD2apoHevfvSTTfdVmMUBEEQBEHwhjzt3/9yuvHGW6hBgwZUUxCj24f597//TXfeeafjcWZmJtWrV49b6leUw4cPU3x8PJ04ccKxr9GjR/OMPD2fffYZTZkyhTsLArPZTI8//jj169ePevToQdOnT6eMjAx+7fz58zRq1Cjq1KkTXXXVVTRz5kyOVDuLWL///vt088038+979+6lQYMGUa9evfizL730kkfHcfDgQd5ft27d+EcZzseOHeP94zms8fvvv+fnCwoK2HmAfXTv3p1GjhzJz9999918TvDeq6++ms/DP//5T+rYsSO/D9FtRLkBjul///sfdy4WBKFmg/vu559/QsePH+N7oHToFgRBEISyk56eRp9++l/uiQJ5GhlZs+Sp1HRXkNzcXMrLyy3xXHBwCMXExHAH27S01Is+07BhI8fFBQNVS1RUNIWGhnq079tvv53atWtHb7zxBu/v888/p2uuuYbq1Klz0XsfeOAB+u2335xu5+OPP6bLLrusxHPt27enf/3rX2www+D+4IMPaMuWLeTvf7Gf5vfff+ftK/C58PBwfj948cUX6amnnuJt3HvvvWyMr1y5kiPkMGI7dOhQ6rG2aNGCVq9eTcHBwWwYX3755Ww09+/f3+VncP5xPp5//nmaNWsWP5eaav8+rrvuOrr11lvprrvuoqNHj/J2evbsSTt27GAl+sCBA/w+5cCAsQ6HwK5du/jxzp07eT379+/nc4J08qCgIH6tUaNG/B3itS5dfL/xgyAIzklLS6P58+fwWLB69ep7ezmCIAiC4JOkpKTQggVzKCwsjOrWrUc1ETG6K6Hm4M8/N5R4rmPHzjR+/NVci/DVV59f9JlHHnmC/12x4kc6fz6xxGtjx07wuEMfDO2pU6dypBlG70cffUTz5s1z+t633nqLygoMVRjqiBTDwKxf37lSee7cOWrYsKHjMaLGMEIXLVrk6OYLoxlgOzDiQVxcHEeNPQGG9t///nc2emHknj17ln93Z3QjMo3oszK4ATIBcnJy2Lj+448/+Lm2bdtyFH39+vVszCM6jn0NHTqUxo4d63TbrVq1YqMehvsVV1xB48aNK+GQgOGN8yJGtyDUTJKTk2nhwrmsIEybNosiIiK8vSRBEARB8DnOn0/kpmnR0bBrZrBcrYmI0V1BunfvSW3atL0o0g2QFoF6BFeMHTveaaS7LCByDMMVac4wihGtdUZZI90ARuW+ffs4co6otCvwx6FSqwHSqt977z1HarY7VEo6QLRI1XIA7TaffPJJNpgRYcb7Jk+eXOL1iqLWAWMaUe41a9bQ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", + "text/plain": [ + "
" + ] + }, + "metadata": {}, + "output_type": "display_data" + } + ], + "source": [ + "fig, axes = plt.subplots(1, 2, figsize=(10, 4.4), sharex=True, sharey=True)\n", + "angles = np.linspace(0, 2 * np.pi, 200)\n", + "radius = math.sqrt(stats.chi2.ppf(0.95, 2))\n", + "for ax, draws in zip(axes, (\"common\", \"independent\")):\n", + " sample = wide[\"published counts\", draws].iloc[:4000]\n", + " ax.scatter(sample.C1, sample.C2, s=4, color=BLUE, alpha=0.3, lw=0)\n", + " mean, covariance = moments(PUBLISHED, correlated=draws == \"common\")\n", + " ellipse = mean[:, None] + np.linalg.cholesky(covariance) @ (\n", + " radius * np.array([np.cos(angles), np.sin(angles)])\n", + " )\n", + " ax.plot(\n", + " *ellipse,\n", + " color=INK,\n", + " lw=1.5,\n", + " label=\"95% of the normal distribution of eqs. (6) and (8)\",\n", + " )\n", + " ax.plot(\n", + " [7, 10.5], [7, 10.5], color=GRAY, lw=1, ls=\"--\", label=\"y = x (equal costs)\"\n", + " )\n", + " above = (\n", + " wide[\"published counts\", draws].C2 > wide[\"published counts\", draws].C1\n", + " ).mean()\n", + " ax.set_title(f\"{draws.capitalize()} draws: C2 > C1 in {above:.1%}\", fontsize=10)\n", + " ax.set(xlabel=\"C1 relative total program cost\", xlim=(7, 10.5), ylim=(7.5, 10.5))\n", + " ax.spines[[\"top\", \"right\"]].set_visible(False)\n", + "axes[0].set_ylabel(\"C2 relative total program cost\")\n", + "axes[0].legend(frameon=False, fontsize=8, loc=\"upper left\")\n", + "fig.tight_layout()\n", + "plt.show()" + ] + }, + { + "cell_type": "markdown", + "id": "778f85d7", + "metadata": {}, + "source": [ + "With common random numbers (left), the replicates fill the ellipse of eq. (8), tilted by the configuration the constellations share, and 2.2% fall below the line *y* = *x*. With independent draws (right), each cost spreads as much as before but the ellipse is not tilted, and 5.2% fall below the line.\n", + "\n", + "## Summary\n", + "\n", + "| Test | Result |\n", + "| --- | --- |\n", + "| 1. Growth by maturity (`Triangular`, `Component`, `CostModel.correlation`) | Table I's means reproduced to its three decimals (existing components 1.0403 against 1.041, rounded up in the table); standard deviations equal to SciPy's; scores correlated by 0.5 correlate the growths by 0.486, so a configuration's variance is 1.3% below eq. (2) (a correlation of 0.514 gives 0.5) |\n", + "| 2. Production blocks (`DeploymentSchedule`, `SatelliteCost.block_size`) | Table III's launches, production of later units, and developments of both blocks of G4c reproduced to the month, with 0.375 of the unit in production at the end (0.37 published); over the study period (`sustained`, with a design life of each configuration), the published numbers of G4c (4.375 and 6.375 later units) and L3e reproduced, and C1's expected cost (8.261 against 8.259), but not those of L4f (4 developments against 2.9, 3.81 counted as Table III counts them) |\n", + "| 3. Constellation costs (`risk_space`, `CostModel.draw`, `Study`) | with the published counts, expected costs, standard deviations, and covariance of eqs. (6) and (8) within the sampling error of 20,000 replicates (means 8.26 and 8.93, standard deviations 0.34 and 0.22); TAT-C's deployments cost 8.26 and 9.32, as their counts predict |\n", + "| 4. Order of costs (`exceedance`, `attribute_variance`) | P(C2 > C1) of 97.8% with the published counts and common random numbers (97.8% published), 94.8% with independent draws (94.9% expected); 99.9% with TAT-C's deployments, whose L4f costs 0.39 more; G4c is 83% of C2's variance but 4% of the variance of the difference |\n", + "\n", + "**Cost risk.** TAT-C's structured cost risk reproduces the paper's example. Configurations whose growth is drawn from scores, shared by common random numbers, give the constellations the covariance of eq. (8), and `exceedance` the probability of eq. (15), with no model of the covariance itself: what the constellations share is shared by drawing it once in each replicate. The same holds for configurations that share components or a common score, and for costs that are not linear in the growths (such as those of deployments with failures), which eq. (8) does not cover.\n", + "\n", + "**Correlation.** `CostModel.correlation` is the correlation of the normal scores of components, from which their growths are drawn; the growths of Table I's skewed distributions are correlated slightly less (0.486 for 0.5). To reproduce a FRISK estimate that correlates costs by 0.5, use a correlation of about 0.514.\n", + "\n", + "**Study periods.** The paper counts the costs of a sustained constellation over a fixed study period, including the share of the units in production at its end. A sustained `DeploymentSchedule` (`sustained=True`) does the same, and reproduces the paper's counts of G4c and L3e. A mission that is not sustained costs the satellites it launches by its end: here 1.7% less for C1 and 6.7% less for C2, whose fourth block of L4f is developed before the end but launched after it. The difference falls unevenly on alternatives, and so shifts the probability that one costs more than another (here, from 99.9% to 95.9%). The probability over the study period differs from the published one (97.8%) only because L4f's published counts cannot be derived from its schedule." + ] + } + ], + "metadata": { + "kernelspec": { + "display_name": "Python 3", + "language": "python", + "name": "python3" + }, + "language_info": { + "codemirror_mode": { + "name": "ipython", + "version": 3 + }, + "file_extension": ".py", + "mimetype": "text/x-python", + "name": "python", + "nbconvert_exporter": "python", + "pygments_lexer": "ipython3", + "version": "3.10.16" + } + }, + "nbformat": 4, + "nbformat_minor": 5 +} diff --git a/docs/validation/ValidateFeaturesTCPRIMED.ipynb b/docs/validation/ValidateFeaturesTCPRIMED.ipynb index 86e5563..b3cf7c3 100644 --- a/docs/validation/ValidateFeaturesTCPRIMED.ipynb +++ b/docs/validation/ValidateFeaturesTCPRIMED.ipynb @@ -11,7 +11,7 @@ "\n", "For every tropical cyclone, TC PRIMED collects the overpasses that cover enough of the storm from the passive microwave imagers and sounders of the Global Precipitation Measurement (GPM) constellation. Whether an overpass is kept is a geometric decision: it depends on how much of a circle around the storm's center the swath covers.\n", "\n", - "In TAT-C, `collect_feature_observations` collects observations of *features*: regions that exist for a period of time, such as the storms of a nature run in an observing system simulation experiment (OSSE; see the [hurricane OSSE example](../examples/RunOSSEHurricane.ipynb)). Each observation is one satellite's view of the part of a feature inside its swath, together with the fraction of the feature's area viewed.\n", + "In TAT-C, `collect_feature_observations` collects observations of *features*: regions that exist for a period of time, such as the storms of a nature run in an observing system simulation experiment (OSSE; see the [hurricane OSSE example](../examples/osse/RunOSSEHurricane.ipynb)). Each observation is one satellite's view of the part of a feature inside its swath, together with the fraction of the feature's area viewed.\n", "\n", "Here, the features are TC PRIMED's circles around each storm, at its best-track position. TAT-C reproduces TC PRIMED's selection of overpasses for the 13 Atlantic tropical cyclones of 2025, by 10 satellites carrying five sensors:\n", "* **Cross-track sounders:** ATMS on Suomi NPP, NOAA-20, and NOAA-21, and MHS on Metop-B and Metop-C.\n", diff --git a/docs/validation/ValidateImagerATMS.ipynb b/docs/validation/ValidateImagerATMS.ipynb index bf4cceb..00dfd81 100644 --- a/docs/validation/ValidateImagerATMS.ipynb +++ b/docs/validation/ValidateImagerATMS.ipynb @@ -2338,7 +2338,7 @@ "\n", "**Changes to TAT-C.** This validation led to the `velocity_frame` option and exposed two problems with the rectangular `PointedInstrument`, which have been fixed: rectangular footprint polygons for wide, elongated views were inaccurate (misplaced corners and too few points along the long sides), and `collect_observations` checked a pointed instrument's view only at the midpoint of each access period, missing up to 77% of observations for a view tailored to a scan period. It now checks the view at the time the view sweeps over the point and reports that time as the epoch.\n", "\n", - "**Footprint size.** TAT-C's viewing geometry gives the zenith angle and slant range of every pixel, from which the footprint of a beam of known width follows. ATMS's 2.2 deg beam has a 32 km footprint at nadir (confirming the nominal value), which grows to about 93 km (equivalent diameter) at the swath edge. Resolution therefore depends on where in the swath a feature is observed, which the [monsoon OSSE example](../examples/RunOSSEMonsoon.ipynb) accounts for.\n" + "**Footprint size.** TAT-C's viewing geometry gives the zenith angle and slant range of every pixel, from which the footprint of a beam of known width follows. ATMS's 2.2 deg beam has a 32 km footprint at nadir (confirming the nominal value), which grows to about 93 km (equivalent diameter) at the swath edge. Resolution therefore depends on where in the swath a feature is observed, which the [monsoon OSSE example](../examples/osse/RunOSSEMonsoon.ipynb) accounts for.\n" ] } ], diff --git a/docs/validation/ValidateImagerCrIS.ipynb b/docs/validation/ValidateImagerCrIS.ipynb index 6354462..bbe8287 100644 --- a/docs/validation/ValidateImagerCrIS.ipynb +++ b/docs/validation/ValidateImagerCrIS.ipynb @@ -15,7 +15,7 @@ "2. **Scan geometry.** Which scan angles, array layout, and scan plane orientation reproduce the actual scan?\n", "3. **Geolocation.** How closely do TAT-C's pixel positions (`collect_ground_pixels`) match the reported FOV positions, and how much of the difference comes from scan timing and the rotation of the FOV array, which TAT-C does not model?\n", "4. **Swath.** Does TAT-C's swath (`compute_ground_track`) match the area CrIS samples, for time steps from one scan to two minutes?\n", - "5. **Footprint size.** Does the satellite viewing geometry reproduce the reported zenith angles and ranges on which the footprint size depends, and how large are CrIS footprints and how do they grow toward the swath edge? Footprint size (horizontal resolution) is the figure of merit of the [monsoon OSSE example](../examples/RunOSSEMonsoon.ipynb), which uses the parameters fit here." + "5. **Footprint size.** Does the satellite viewing geometry reproduce the reported zenith angles and ranges on which the footprint size depends, and how large are CrIS footprints and how do they grow toward the swath edge? Footprint size (horizontal resolution) is the figure of merit of the [monsoon OSSE example](../examples/osse/RunOSSEMonsoon.ipynb), which uses the parameters fit here." ] }, { @@ -2470,7 +2470,7 @@ "source": [ "## Summary\n", "\n", - "The parameters fitted to the NOAA-20 CrIS data, used by the [monsoon OSSE example](../examples/RunOSSEMonsoon.ipynb):" + "The parameters fitted to the NOAA-20 CrIS data, used by the [monsoon OSSE example](../examples/osse/RunOSSEMonsoon.ipynb):" ] }, { diff --git a/docs/validation/ValidateSamplingErrorIMERG.ipynb b/docs/validation/ValidateSamplingErrorIMERG.ipynb new file mode 100644 index 0000000..8bd4a2e --- /dev/null +++ b/docs/validation/ValidateSamplingErrorIMERG.ipynb @@ -0,0 +1,1031 @@ +{ + "cells": [ + { + "cell_type": "markdown", + "id": "c0a1b2c3", + "metadata": {}, + "source": [ + "# Sampling Error Validation: GPM IMERG\n", + "\n", + "This notebook validates TAT-C's estimate of the **sampling error** of observations (`tatc.analysis.estimate_sampling_error`): the error of estimating the mean of a varying field over a period, such as the monthly mean precipitation at a place, from the samples that a constellation observes. The estimate models the field as stationary, with a standard deviation and an exponential correlation in time (a decorrelation time), for which the variance of the error is exact. Whether real precipitation behaves enough like this model for its predictions to hold is what this notebook tests.\n", + "\n", + "The reference is the [Integrated Multi-satellitE Retrievals for GPM (IMERG)](https://gpm.nasa.gov/data/imerg) Final Run, which estimates precipitation every half-hour on a 0.1 deg grid by merging the observations of the GPM constellation. It serves as the true field: the mean of its half-hourly values over a month is the true monthly mean, and its values at the times that a constellation observes are the samples. The region is the Maritime Continent (10 deg S to 10 deg N, 95 to 115 deg E: Sumatra, Borneo, Java, and the seas between), whose land and ocean have some of the strongest daily cycles of precipitation on Earth, a hard case for a model without one.\n", + "\n", + "Four constellation designs sample the field over July 2025: the GPM Core Observatory's GMI (a precessing, 65 deg inclined orbit), one sun-synchronous ATMS-like sounder (13:30), three of them (13:30, 17:30, and 21:30), and all four together. The tests compare the predicted and actual errors of the monthly means at 1,600 points:\n", + "\n", + "* **Test 1: Field statistics.** The standard deviation and decorrelation time of the field, and how well one month predicts the next.\n", + "* **Test 2: Sampling errors.** The predicted and actual errors of each design, with the statistics of the field estimated from the previous month (June 2025), as a study would estimate them from climatology.\n", + "* **Test 3: Model inputs.** How the estimates of the statistics, and the correlation model, change the predictions.\n", + "* **Test 4: Daily cycle.** Whether the errors of sun-synchronous sampling, at fixed local times, exceed the predictions where the daily cycle is strong." + ] + }, + { + "cell_type": "markdown", + "id": "c1b2c3d4", + "metadata": {}, + "source": [ + "## Reference Data\n", + "\n", + "The IMERG Final Run half-hourly product ([`GPM_3IMERGHH`](https://disc.gsfc.nasa.gov/datasets/GPM_3IMERGHH_07/summary), version 07), distributed by the NASA Goddard Earth Sciences Data and Information Services Center (GES DISC), holds one file per half-hour with the precipitation rate (mm/h) of each 0.1 deg cell, averaged over the half-hour. Every fifth cell of the region in each direction (a 0.5 deg grid of 40 by 40 cells) is downloaded for every half-hour of June and July 2025 through the [OPeNDAP](https://opendap.earthdata.nasa.gov/) service, which subsets the files on the server (requiring a free [NASA Earthdata Login](https://urs.earthdata.nasa.gov/) account and the `earthaccess` package), and is cached in a local `data/imerg` directory (about 1 MB per month).\n", + "\n", + "The times of the half-hours are taken from the file names (the start of each half-hour), as the time variable of the subsets returned by the service repeats some values." + ] + }, + { + "cell_type": "code", + "execution_count": 1, + "id": "c2c3d4e5", + "metadata": { + "execution": { + "iopub.execute_input": "2026-11-10T16:28:05.733965Z", + "iopub.status.busy": "2026-11-10T16:28:05.733794Z", + "iopub.status.idle": "2026-11-10T16:28:08.374645Z", + "shell.execute_reply": "2026-11-10T16:28:08.373779Z" + } + }, + "outputs": [ + { + "name": "stdout", + "output_type": "stream", + "text": [ + "June: 1440 half-hours, mean 0.286 mm/h\n", + "July: 1488 half-hours, mean 0.200 mm/h\n" + ] + } + ], + "source": [ + "import re\n", + "from concurrent.futures import ThreadPoolExecutor\n", + "from datetime import datetime, timedelta, timezone\n", + "from pathlib import Path\n", + "\n", + "import numpy as np\n", + "import pandas as pd\n", + "import requests\n", + "import xarray as xr\n", + "\n", + "DATA_DIR = Path(\"data\") / \"imerg\"\n", + "DATA_DIR.mkdir(parents=True, exist_ok=True)\n", + "COLLECTION = \"C2723754847-GES_DISC\" # GPM_3IMERGHH version 07\n", + "LON, LAT = \"2750:5:2949\", \"800:5:999\" # every fifth 0.1 deg cell of 95 to 115 E and 10 S to 10 N\n", + "MONTHS = {\"202506\": (\"2025-06-01\", \"2025-06-30\"), \"202507\": (\"2025-07-01\", \"2025-07-31\")}\n", + "\n", + "\n", + "def download_month(month, session):\n", + " \"\"\"Downloads the subsets of the half-hourly files of a month, with their times from the file names.\"\"\"\n", + " first, last = MONTHS[month]\n", + " names = [\n", + " item[\"umm\"][\"GranuleUR\"]\n", + " for item in requests.get(\n", + " \"https://cmr.earthdata.nasa.gov/search/granules.umm_json\",\n", + " params={\"collection_concept_id\": COLLECTION, \"temporal\": f\"{first}T00:00:00Z,{last}T23:59:59Z\", \"page_size\": 2000},\n", + " timeout=60,\n", + " ).json()[\"items\"]\n", + " ]\n", + " query = (\n", + " f\"dap4.ce=/Grid/precipitation%5B0%5D%5B{LON}%5D%5B{LAT}%5D;/Grid/lon%5B{LON}%5D;/Grid/lat%5B{LAT}%5D\"\n", + " )\n", + "\n", + " def fetch(name):\n", + " url = f\"https://opendap.earthdata.nasa.gov/collections/{COLLECTION}/granules/{name.replace(':', '%3A')}.dap.nc4?{query}\"\n", + " for attempt in range(6):\n", + " response = session.get(url, timeout=120)\n", + " if response.status_code == 200:\n", + " path = DATA_DIR / \"parts\" / f\"{name.split(':')[-1]}.nc4\"\n", + " path.parent.mkdir(exist_ok=True)\n", + " path.write_bytes(response.content)\n", + " return path\n", + " raise RuntimeError(f\"failed to download {name}\")\n", + "\n", + " with ThreadPoolExecutor(8) as pool:\n", + " paths = list(pool.map(fetch, sorted(names)))\n", + " times = [pd.Timestamp(\"T\".join(re.search(r\"\\.(\\d{8})-S(\\d{6})-E\", p.name).groups())) for p in paths]\n", + " frames = [xr.open_dataset(p, group=\"Grid\", decode_times=False).precipitation.isel(time=0).load() for p in paths]\n", + " grid = xr.concat(frames, dim=pd.Index(times, name=\"time\")).transpose(\"time\", \"lat\", \"lon\")\n", + " grid.rename(\"precipitation\").to_dataset().to_netcdf(DATA_DIR / f\"imerg_hh_{month}_maritime.nc\")\n", + "\n", + "\n", + "session = None\n", + "for month in MONTHS:\n", + " if not (DATA_DIR / f\"imerg_hh_{month}_maritime.nc\").exists():\n", + " if session is None:\n", + " import earthaccess\n", + "\n", + " earthaccess.login()\n", + " session = earthaccess.get_requests_https_session()\n", + " download_month(month, session)\n", + "\n", + "\n", + "def load_month(month):\n", + " \"\"\"The precipitation (mm/h) of a month, at the middle of each half-hour.\"\"\"\n", + " data = xr.open_dataset(DATA_DIR / f\"imerg_hh_{month}_maritime.nc\").precipitation.astype(float)\n", + " data = data.assign_coords(\n", + " time=data.time.values + np.timedelta64(15, \"m\"),\n", + " lat=data.lat.astype(float).round(2),\n", + " lon=data.lon.astype(float).round(2),\n", + " )\n", + " return data.transpose(\"time\", \"lat\", \"lon\")\n", + "\n", + "\n", + "june, july = load_month(\"202506\"), load_month(\"202507\")\n", + "START, END = datetime(2025, 7, 1, tzinfo=timezone.utc), datetime(2025, 8, 1, tzinfo=timezone.utc)\n", + "print(f\"June: {june.sizes['time']} half-hours, mean {float(june.mean()):.3f} mm/h\")\n", + "print(f\"July: {july.sizes['time']} half-hours, mean {float(july.mean()):.3f} mm/h\")" + ] + }, + { + "cell_type": "markdown", + "id": "c3d4e5f6", + "metadata": {}, + "source": [ + "## Setup\n", + "\n", + "The points are the centers of the 1,600 cells, identified by the hash of their geometry, as are TAT-C's observations of them. The designs fly generated orbits (at the start of July 2025) with instruments whose fields of regard give the swaths of GMI (885 km at 407 km) and ATMS (2,600 km at 824 km). Every observation (an access period of a point) is one sample, at the middle of the access period, of the half-hour that contains it (`tatc.analysis.sample_field`)." + ] + }, + { + "cell_type": "code", + "execution_count": 2, + "id": "c4e5f6a7", + "metadata": { + "execution": { + "iopub.execute_input": "2026-11-10T16:28:08.376625Z", + "iopub.status.busy": "2026-11-10T16:28:08.376213Z", + "iopub.status.idle": "2026-11-10T16:29:50.714084Z", + "shell.execute_reply": "2026-11-10T16:29:50.713349Z" + } + }, + "outputs": [ + { + "data": { + "text/html": [ + "
\n", + "\n", + "\n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + "
satellitespoints observedmedian samplesRMS error of the monthly mean (mm/h)
GMI1.01600.022.00.219
one sun-synchronous1.01600.059.00.120
three sun-synchronous3.01600.0176.00.045
GMI + three sun-synchronous4.01600.0198.00.048
\n", + "
" + ], + "text/plain": [ + " satellites points observed median samples \\\n", + "GMI 1.0 1600.0 22.0 \n", + "one sun-synchronous 1.0 1600.0 59.0 \n", + "three sun-synchronous 3.0 1600.0 176.0 \n", + "GMI + three sun-synchronous 4.0 1600.0 198.0 \n", + "\n", + " RMS error of the monthly mean (mm/h) \n", + "GMI 0.219 \n", + "one sun-synchronous 0.120 \n", + "three sun-synchronous 0.045 \n", + "GMI + three sun-synchronous 0.048 " + ] + }, + "execution_count": 2, + "metadata": {}, + "output_type": "execute_result" + } + ], + "source": [ + "import geopandas as gpd\n", + "from shapely.geometry import Point\n", + "\n", + "from tatc.analysis import collect_observations, compare_sampled_means, estimate_sampling_error, sample_field\n", + "from tatc.schemas import CircularOrbit, Instrument, Satellite, SunSynchronousOrbit\n", + "from tatc.utils import hash_geometry, swath_width_to_field_of_regard\n", + "\n", + "lon, lat = np.meshgrid(july.lon.values, july.lat.values)\n", + "points = gpd.GeoDataFrame(geometry=[Point(x, y) for x, y in zip(lon.ravel(), lat.ravel())], crs=\"EPSG:4326\")\n", + "points[\"target_hash\"] = [hash_geometry(point) for point in points.geometry]\n", + "GMI = Instrument(name=\"gmi\", field_of_regard=swath_width_to_field_of_regard(407e3, 885e3))\n", + "ATMS = Instrument(name=\"atms\", field_of_regard=swath_width_to_field_of_regard(824e3, 2600e3))\n", + "\n", + "\n", + "def sounder(crossing):\n", + " \"\"\"An ATMS-like sounder in a sun-synchronous orbit with an ascending equator crossing time.\"\"\"\n", + " orbit = SunSynchronousOrbit(altitude=824e3, equator_crossing_time=crossing, epoch=START)\n", + " return Satellite(name=f\"sounder {crossing}\", orbit=orbit, instruments=[ATMS])\n", + "\n", + "\n", + "gpm = Satellite(name=\"gpm\", orbit=CircularOrbit(altitude=407e3, inclination=65, epoch=START), instruments=[GMI])\n", + "DESIGNS = {\n", + " \"GMI\": [gpm],\n", + " \"one sun-synchronous\": [sounder(\"13:30\")],\n", + " \"three sun-synchronous\": [sounder(\"13:30\"), sounder(\"17:30\"), sounder(\"21:30\")],\n", + " \"GMI + three sun-synchronous\": [gpm, sounder(\"13:30\"), sounder(\"17:30\"), sounder(\"21:30\")],\n", + "}\n", + "observations, actual = {}, {}\n", + "for name, satellites in DESIGNS.items():\n", + " observations[name] = collect_observations(points, satellites, START, END)\n", + " sampled = sample_field(observations[name], july, name=\"precipitation\")\n", + " actual[name] = compare_sampled_means(\n", + " sampled, july, START, END, name=\"precipitation\", targets=points\n", + " ).set_index(\"target_hash\")\n", + "pd.DataFrame(\n", + " {\n", + " name: {\n", + " \"satellites\": len(DESIGNS[name]),\n", + " \"points observed\": int((actual[name].samples > 0).sum()),\n", + " \"median samples\": actual[name].samples.median(),\n", + " \"RMS error of the monthly mean (mm/h)\": np.sqrt((actual[name].error ** 2).mean()),\n", + " }\n", + " for name in DESIGNS\n", + " }\n", + ").T.round(3)" + ] + }, + { + "cell_type": "markdown", + "id": "c5f6a7b8", + "metadata": {}, + "source": [ + "## Test 1: Field Statistics\n", + "\n", + "The model of the field needs its standard deviation and its decorrelation time at each point. Both are estimated from the half-hourly series of each point: the standard deviation directly, and the decorrelation time by fitting an exponential, `exp(-lag / T)`, to the autocorrelation of the anomalies (the values less the monthly mean) at lags of 0.5 to 12 hours, where the autocorrelation exceeds 0.05. The figure compares the median autocorrelation with the exponential of the median decorrelation time.\n", + "\n", + "A study estimates these statistics before the observations exist, from climatology or another period. Here, the statistics of June predict the errors of July, and the table compares the statistics of the two months: their medians, and the correlation between their values at the points. The standard deviation smoothed over neighboring points (a 2.5 deg box of 5 by 5 points) is a more robust estimate of a point's than its own month, as rain at a point in a month is dominated by a few storms." + ] + }, + { + "cell_type": "code", + "execution_count": 3, + "id": "c6a7b8c9", + "metadata": { + "execution": { + "iopub.execute_input": "2026-11-10T16:29:50.716145Z", + "iopub.status.busy": "2026-11-10T16:29:50.715917Z", + "iopub.status.idle": "2026-11-10T16:29:51.012572Z", + "shell.execute_reply": "2026-11-10T16:29:51.011672Z" + } + }, + "outputs": [ + { + "data": { + "text/html": [ + "
\n", + "\n", + "\n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + "
June (median)July (median)correlation of June and July at the points
mean0.2610.1750.245
sigma1.1160.8710.161
smoothed sigma1.2020.9220.214
decorrelation (h)2.7402.8500.265
\n", + "
" + ], + "text/plain": [ + " June (median) July (median) \\\n", + "mean 0.261 0.175 \n", + "sigma 1.116 0.871 \n", + "smoothed sigma 1.202 0.922 \n", + "decorrelation (h) 2.740 2.850 \n", + "\n", + " correlation of June and July at the points \n", + "mean 0.245 \n", + "sigma 0.161 \n", + "smoothed sigma 0.214 \n", + "decorrelation (h) 0.265 " + ] + }, + "execution_count": 3, + "metadata": {}, + "output_type": "execute_result" + } + ], + "source": [ + "from scipy.ndimage import uniform_filter\n", + "\n", + "LAGS = np.arange(1, 25) # half-hours\n", + "\n", + "\n", + "def field_statistics(field):\n", + " \"\"\"The standard deviation, autocorrelation, and decorrelation time (h) of each point's half-hourly series.\"\"\"\n", + " series = field.values.reshape(field.sizes[\"time\"], -1).T # points (in the order of the points), times\n", + " anomaly = series - series.mean(axis=1, keepdims=True)\n", + " variance = anomaly.var(axis=1)\n", + " rho = np.array([(anomaly[:, :-k] * anomaly[:, k:]).mean(axis=1) / variance for k in LAGS]).T\n", + " scale = np.full(len(series), np.nan)\n", + " for i in range(len(series)):\n", + " fit = rho[i] > 0.05\n", + " x, y = LAGS[fit] * 0.5, np.log(rho[i][fit])\n", + " scale[i] = -(x @ x) / (x @ y) if fit.any() else np.nan\n", + " sigma = series.std(axis=1, ddof=1)\n", + " smooth = uniform_filter(sigma.reshape(field.sizes[\"lat\"], field.sizes[\"lon\"]), size=5, mode=\"nearest\").ravel()\n", + " stats = pd.DataFrame(\n", + " {\"mean\": series.mean(axis=1), \"sigma\": sigma, \"smoothed sigma\": smooth, \"decorrelation (h)\": scale},\n", + " index=points.target_hash,\n", + " )\n", + " return stats, rho\n", + "\n", + "\n", + "june_stats, june_rho = field_statistics(june)\n", + "july_stats, july_rho = field_statistics(july)\n", + "pd.DataFrame(\n", + " {\n", + " \"June (median)\": june_stats.median(),\n", + " \"July (median)\": july_stats.median(),\n", + " \"correlation of June and July at the points\": [\n", + " np.corrcoef(june_stats[c], july_stats[c if c != \"smoothed sigma\" else \"sigma\"])[0, 1]\n", + " if c != \"decorrelation (h)\"\n", + " else june_stats[c].corr(july_stats[c])\n", + " for c in june_stats.columns\n", + " ],\n", + " }\n", + ").round(3)" + ] + }, + { + "cell_type": "code", + "execution_count": 4, + "id": "c7b8c9d0", + "metadata": { + "execution": { + "iopub.execute_input": "2026-11-10T16:29:51.014228Z", + "iopub.status.busy": "2026-11-10T16:29:51.014049Z", + "iopub.status.idle": "2026-11-10T16:29:51.186838Z", + "shell.execute_reply": "2026-11-10T16:29:51.186073Z" + } + }, + "outputs": [ + { + "data": { + "image/png": "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KCIiIiIi6jwMFkRERERElDcGCyIiIiIiyhuDBRERERER5Y3BgoiIiIiI8sZgQUREREREeWOwICIiIiKivDFYEBFRp1m2bJksXbpUH3/55ZcZb2i5p/j8889lyZIlxT4MIqKSxWBBRFTG1q9fL0899ZSEw+Hd/t7Nzc16Z9dIJKLLb7zxhkyePFn2VFVVVXL22WfL5s2bi30oREQlicGCiKiMffDBBzJ+/Hg9yd/dpk+fLocddpgcc8wxUgoGDRoko0ePlnvuuafYh0JEVJIYLIiIKtjGjRu1ooHppZdeki+++CLjfrFYTN577z157bXXtAqybt06efHFF9t83Xg8Lg899JBcfvnladtQwfj4449l3rx5+lqZLF++XF544QX517/+pe9ttXLlSnnrrbds67777jvb8ZjNrlCpWbBggTzzzDPJqs3WrVvln//8p7z99tvS2Nhoe50JEybIzJkzJRAItPmzERFRZt421hMRUQX44YcfZO7cufoYVQ2EhzPPPFP+/ve/i8vl0vU4ycY6nNCj+rBixQqtRCAcnHvuuW32rVi7dq2cfPLJtvUNDQ1y4oknit/v12X0aXj66adl7NixydDx85//XN5991057rjjNGDst99+Gmh69uyp+zz33HPy5ptvyqmnnpp83UWLFsl1112XPB40u7rjjjvkgAMOkOrqatl///21mRPCzGWXXSbDhg3Tpk9r1qyRRx55JPlaP/nJT6SpqUkWLlwop512Wif8xomIyheDBRFRBTvyyCO1WmHasmWLDBkyRKsF559/vq57+OGHtZKBQIGT/G3btsnRRx/d7usidHTv3l33d1ZIHnzwweRr33zzzXLbbbclgwVO8ufPny+ffPKJhoKdO3fKCSecILfeeqvMmDEj59CEZk3Wqsmdd94pU6ZM0Qnws+DnMnXp0kUGDBigTcgYLIiIcsOmUEREFQ5NhBYvXqxhApWAfv36yfvvv5/cjgrBpZdemgwJCAxXXHFFu6+JgLL33nunrUfVwQwVMGrUKFm1alVyGSEH74VQAXV1dXL99ddrVSNX9fX1MnHiRNu6mpoaWb16dbKpE36Wk046ybYPjhvHT0REuWGwICKqYLhaP3DgQG0e9Nhjj2mzKFzp37RpU3IfNGnq37+/7XnOZaeuXbtm7DCOE3krNIkKBoPJ5W+//VaPx9mpGn0htm/fntPPhiBkNueydij/9NNPNeCcfvrp8uc//9n2/oDjRqAhIqLcsCkUEVEFQxOjU045RZ544onkujPOOEM7X1vDwI4dO2zP6+gkf/DgwTpsK07S0bwoWz169NDmSVZY9vl8WoEAt9ud1qE7U2drZ6gwm36hGrNhwwbtAD5t2jTtV/KPf/xDt+N10RH8kEMOyfqYiYjIwIoFEVEFQ58H60k0lnGibTVy5Eh5+eWXbeucy07HH3+8do5GE6tcoD8FqibW4PDss8/KiBEjxOPx6HKfPn3km2++kWg0mtznnXfeyer1zVGoevfurU2u0MzKeozoLI4w5Ox0TkREHWPFgoioAqD/RG1trW0dRl8aN26c3HfffTpyktfr1aZCmFvdcsstMnToUN33rLPO0iv9uJt2poqACe918cUXy5w5c2yjN3Vk6tSpGiTGjBkj5513ng43i2FwMUqUCR29f/WrX+nrozkTgtDrr7+e1evjNQ8//HA59thjpbW1Ve6//369z4cJfTkwepSz0zkREXXMFbfWu4mIqKx8+OGHcu+992bcNnv2bK0CYGhZjMSE/g44qUY1AM2NrrnmmuS+GJYVo0OhrwOGasWwsAgkX3/9dZvv/dVXX8nw4cN1RKlevXrpvSMwDCyeZ8IQthgW1joyFfp4YHQoPB8n+JMmTZJDDz3U9tq4TwVGicKoUQgJBx98sMyaNSs5clSm9zI7qj/55JMaWFBRQTOwc845R39eVCoOOuggDTI4biIiyg2DBRERdQj9HKwdr1G9QL8HVBfag5vk4R4S2H9Ph+ZUaBZlDkVLRES5YbAgIqIO4b4VaIKEvgmoBKAigBNxVC+IiIiAnbeJiKhD6KyN5kK4oo+RlTBkK0MFERFZsWJBRERERER5Y8WCiIiIiIjyxmBBRERERER5Y7AgIiIiIqK8MVgQEREREVHeGCyIiIiIiChvDBZERERERJQ3BgsiIiIiIsobgwUREREREeWNwYKIiIiIiCRf/w/JqsrqKG8M2QAAAABJRU5ErkJggg==", + "text/plain": [ + "
" + ] + }, + "metadata": {}, + "output_type": "display_data" + } + ], + "source": [ + "import matplotlib.pyplot as plt\n", + "\n", + "BLUE, ORANGE, AQUA, YELLOW, GRAY, INK = \"#2a78d6\", \"#eb6834\", \"#1baf7a\", \"#eda100\", \"#8a8a86\", \"#2b2b29\"\n", + "fig, ax = plt.subplots(figsize=(8, 4))\n", + "hours = LAGS * 0.5\n", + "for rho, color, label in [(june_rho, GRAY, \"June\"), (july_rho, BLUE, \"July\")]:\n", + " ax.fill_between(hours, *np.percentile(rho, [25, 75], axis=0), color=color, alpha=0.15, lw=0)\n", + " ax.plot(hours, np.median(rho, axis=0), color=color, lw=2, label=f\"{label} (median and interquartile range)\")\n", + "scale = june_stats[\"decorrelation (h)\"].median()\n", + "ax.plot(hours, np.exp(-hours / scale), color=ORANGE, lw=2, ls=\"--\", label=f\"exponential, T = {scale:.1f} h (June)\")\n", + "ax.axhline(0, color=GRAY, lw=0.8)\n", + "ax.set(xlabel=\"Lag (hours)\", ylabel=\"Autocorrelation of anomalies\", xlim=(0, 12))\n", + "ax.grid(axis=\"y\", color=\"#e6e6e3\", lw=0.8)\n", + "for side in (\"top\", \"right\"):\n", + " ax.spines[side].set_visible(False)\n", + "ax.legend(fontsize=8, frameon=False)\n", + "ax.set_title(\"Autocorrelation of half-hourly precipitation at the 1,600 points\", fontsize=10)\n", + "fig.tight_layout()\n", + "plt.show()" + ] + }, + { + "cell_type": "markdown", + "id": "c8c9d0e1", + "metadata": {}, + "source": [ + "The decorrelation time is stable between months: 2.7 hours in June and 2.9 hours in July (medians over the points), and the exponential of June's decorrelation time follows the measured autocorrelation, though precipitation decorrelates somewhat faster (an autocorrelation of 0.42 at 2 hours in July, against 0.48 for the exponential). The standard deviation is not stable at a point: June was wetter than July (a median of 1.12 against 0.87 mm/h), and the standard deviations of the points in the two months are hardly correlated (0.16), as each month's rain at a point is dominated by a few storms. Smoothing over neighboring points raises the correlation only to 0.21, but averages out much of the noise of a single month." + ] + }, + { + "cell_type": "markdown", + "id": "c9d0e1f2", + "metadata": {}, + "source": [ + "## Test 2: Sampling Errors\n", + "\n", + "For each design, `estimate_sampling_error` predicts the error of each point's monthly mean from the times of its samples, with the statistics of June: the smoothed standard deviation of each point, and the median decorrelation time of the region. The predicted errors are standard deviations: if the model holds, the actual errors divided by the predicted ones (the standardized errors) have a root mean square of 1, and 95% of them are within 2. The table gives these, and the root mean square of the predicted and actual errors over the points. The figure compares them for groups of points with similar predicted errors (fifths of the points, by predicted error)." + ] + }, + { + "cell_type": "code", + "execution_count": 5, + "id": "d0e1f2a3", + "metadata": { + "execution": { + "iopub.execute_input": "2026-11-10T16:29:51.188555Z", + "iopub.status.busy": "2026-11-10T16:29:51.188379Z", + "iopub.status.idle": "2026-11-10T16:29:52.173418Z", + "shell.execute_reply": "2026-11-10T16:29:52.172342Z" + } + }, + "outputs": [ + { + "data": { + "text/html": [ + "
\n", + "\n", + "\n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + "
median samplesmedian effective samplespredicted RMS (mm/h)actual RMS (mm/h)RMS standardized errorwithin 2 predicted (%)
GMI22.021.7900.2510.2191.03095.250
one sun-synchronous59.057.5850.1300.1201.05294.375
three sun-synchronous176.0110.8400.0530.0451.01794.438
GMI + three sun-synchronous198.0109.0140.0550.0481.03593.875
\n", + "
" + ], + "text/plain": [ + " median samples median effective samples \\\n", + "GMI 22.0 21.790 \n", + "one sun-synchronous 59.0 57.585 \n", + "three sun-synchronous 176.0 110.840 \n", + "GMI + three sun-synchronous 198.0 109.014 \n", + "\n", + " predicted RMS (mm/h) actual RMS (mm/h) \\\n", + "GMI 0.251 0.219 \n", + "one sun-synchronous 0.130 0.120 \n", + "three sun-synchronous 0.053 0.045 \n", + "GMI + three sun-synchronous 0.055 0.048 \n", + "\n", + " RMS standardized error within 2 predicted (%) \n", + "GMI 1.030 95.250 \n", + "one sun-synchronous 1.052 94.375 \n", + "three sun-synchronous 1.017 94.438 \n", + "GMI + three sun-synchronous 1.035 93.875 " + ] + }, + "execution_count": 5, + "metadata": {}, + "output_type": "execute_result" + } + ], + "source": [ + "REGIONAL_DECORRELATION = timedelta(hours=float(june_stats[\"decorrelation (h)\"].median()))\n", + "\n", + "\n", + "def evaluate(name, decorrelation_time, standard_deviation):\n", + " \"\"\"The predicted and actual errors of the monthly means of the points observed by a design.\"\"\"\n", + " predicted = estimate_sampling_error(\n", + " observations[name], START, END, decorrelation_time, standard_deviation, targets=points\n", + " ).set_index(\"target_hash\")\n", + " merged = actual[name].join(predicted[[\"sampling_error\", \"effective_samples\"]])\n", + " merged = merged[merged.samples > 0]\n", + " merged[\"z\"] = merged.error / merged.sampling_error\n", + " return merged\n", + "\n", + "\n", + "def score(merged):\n", + " \"\"\"Summary statistics of predicted and actual errors.\"\"\"\n", + " return {\n", + " \"predicted RMS (mm/h)\": np.sqrt((merged.sampling_error**2).mean()),\n", + " \"actual RMS (mm/h)\": np.sqrt((merged.error**2).mean()),\n", + " \"RMS standardized error\": np.sqrt((merged.z**2).mean()),\n", + " \"within 2 predicted (%)\": 100 * (merged.z.abs() <= 2).mean(),\n", + " }\n", + "\n", + "\n", + "held_out = {name: evaluate(name, REGIONAL_DECORRELATION, june_stats[\"smoothed sigma\"]) for name in DESIGNS}\n", + "test2 = pd.DataFrame(\n", + " {\n", + " name: {\"median samples\": m.samples.median(), \"median effective samples\": m.effective_samples.median(), **score(m)}\n", + " for name, m in held_out.items()\n", + " }\n", + ").T\n", + "test2.round(3)" + ] + }, + { + "cell_type": "code", + "execution_count": 6, + "id": "d1f2a3b4", + "metadata": { + "execution": { + "iopub.execute_input": "2026-11-10T16:29:52.175241Z", + "iopub.status.busy": "2026-11-10T16:29:52.174941Z", + "iopub.status.idle": "2026-11-10T16:29:52.473739Z", + "shell.execute_reply": "2026-11-10T16:29:52.472826Z" + } + }, + "outputs": [ + { + "data": { + "image/png": "iVBORw0KGgoAAAANSUhEUgAAAk4AAAHnCAYAAABOotJOAAAAOnRFWHRTb2Z0d2FyZQBNYXRwbG90bGliIHZlcnNpb24zLjExLjIsIGh0dHBzOi8vbWF0cGxvdGxpYi5vcmcvgI3uAAAAAAlwSFlzAAAPYQAAD2EBqD+naQAAjFdJREFUeJzt3QdYk1fbB/A/GwRZKrjAgXvvUffee2+ttrV7vp3v292v+237tnZqrVtbByjuvffeW0FFBESGbMh33ccmDSFAgAAh/H/XlQvyPMmTkyeQ3LnPfc6x0Wg0GhARERFRrmxzvwkRERERMXAiIiIiygNmnIiIiIhMxMCJiIiIyEQMnIiIiIhMxMCJiIiIyEQMnIiIiIhMxMCJiIiIyEQMnIiIiIhMxMCJKAe//PIL2rdvj9q1a2P79u0l4ly99tpreOONN3K8zbvvvovnn3++yNpU0phyDvPj119/Rbt27XR/T/IayGuR17+5Tp06YeXKlShKycnJeOWVV9C8eXPUqlULCQkJKG53795VbQkJCVHXr127pq7L9uJuCxXM/v17kZiYCEtkX9wNoJKtYcOG6g3VkLzBPvPMMyjJTp8+jWeffRZBQUGoW7cuKleuDEvz9ttvqw+wb7/9NtMbuL19zv/a9+7dQ2RkZBG0sGQy5Rzm1dmzZ9XfU2BgoO7vadasWUhNTc3xb65Hjx6YMWMGxo0bp7vd9evXERsbi6L022+/qXb9+eef8PDwgIuLC4pbWloarl69ipSUFHVdfsp12W6Ky5cvo1+/fjhw4ADKly9v1rZQwch5XLt2NUaMGA0bGxtYEgZOVCDyRvHOO+9kelMX5cqVK/FnVj7EfHx8MGDAAFgqCYDi4+OLuxlkglOnTqFChQqZ/p5++OEH2NnZ5fg3d/PmTcTExFhE+9u2bYuWLVvCUgUEBKhgqFKlSibdXr705SXQoqLTqVMX/PXXMuzduxsdO3a2qFPPrjoqMPkwkBS1/sXLy0vti46OVteDg4MxcuRINGjQAEuWLMGGDRvQokULbNq0SX2jlm/XkmYXsr9bt24qmzVs2DAcOXIkSzeKXD7//HO0bt0affr0UduvXLmCyZMno1mzZujVqxf++OOPHNud0+N88MEHePnll1VgIu1v2rSp0WNIO+R2cvsuXbqobgxpV1JSEt577z31IfPYY49hwYIFeXp8/ef59ddfo2vXrmjTpg0+/vhjpKenq/1fffUV/vrrL6xdu1Z33g8ePKj2ZWRkZHs/Q5s3b0bjxo2zpMXleQwdOtTsz1u6nwYPHoxGjRqpb/uSgdH3v//9T/d8WrVqhSeffBJ37tzJ07nJz9+DITnWp59+is6dO6u/VTnf2jXR83rO5Dy99NJLur8n7aVjx474/vvvs/2bGzVqlOr6ke487X20Hjx4gBdffFE9dzkHK1asyPSYW7duxcCBA9GkSRP197Vv374cv91/9NFH6v9JntfMmTMzdXf1798fS5cuxZo1a1Qb5DXJrgtx9uzZKtssr538bcj/vuFt5syZox5DHkvbVSnvFf/617/U344EaPL6GmbVLl68iOHDh6vnJO8nEszpCw0NRd++fREREaHbJseVbld5btIF+t1336n/D8m4yvMSsl2e19NPP222thiT23HPnDmj2iH/IxI8169fH7t371bnS/5nFi9erM5fnTp11Gsmf48SfHfo0EH9P02cOFEFjvrGjh2LL774Am+++ab6P3388cdREtja2mLQoCE4e/Y0rl69AouiISoAJycnzU8//ZTt/oiICPmk0fj4+GgWLFiguXDhgiYmJkbz119/aWxsbDTNmzfXbN68WXP58mVNSkqKZuHChRoXFxd1zCNHjmhefPFFjbOzs+bKlSu6Y06YMEFjZ2enmT59uubw4cOamzdvqu21atXSTJs2TXPs2DHNjh071P4NGzYYbVdujyPt/vzzzzUVK1ZUbbt69arR40hbbG1tNS+88ILm6NGjmnnz5qnrtWvX1rz22muqLb/++qvaJr+b+vj6z/Ppp59Wt1m1apXG09NTM2vWLLU/MjJSM2rUKM2AAQNUG+WSkJCQ6/3EU089pRkxYoT6PSkpSVOuXDnN/PnzdfvT09M1fn5+mq+//tqszzsoKEg91m+//aY5efKkZvHixer6kiVLdLeJiorSPZ8DBw5oxo0bp6lXr54mNTXV5HOT178HY89Pji/n9+DBg6p9Xl5emi+++CJf58zw70l76du3r3otsvubCw0N1fj7+2s+/PBD3X1ElSpVNGXKlNH873//05w4cULz1VdfqXN9+vRptf/atWvqf/Pbb79V29asWaPp0qWL5uHDh0af74wZMzTVq1fXBAcHa/bu3avp0aOHpn79+rpzHhISohk+fLhmyJAhqg137twx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ZGevslJ3796Gr29li/gmUtLItABS2C2jzdhtRaWFdPeEh9/h+wbliWStZ8/+RX2pGzx4WJYv0pQzdtUVMUdbO4z0b667ro1bGb8WjGSZtm/fjt9//72ARyIisk5SMylzxknWfNSoMfDw8DRpXj7KjIFTETMs4uakheYhI+qIiMi42NgYBAWtRJkyrhgxYrRFjuorKRg4ERERWTFZa2716lWqvlXWxqOCYeBERERkpY4ePYzt27fCz68aBg0awqVTzICBExERkZWScpDWrduiU6cuHHhkJgyciIiIrIgspXX9+lW0aNFKXci8GDgRERFZiWvXriA4eI3qkpO5mSxtPTxrwAmDipjhtAOlbRqCPXv24IknnijuZpRY//3vf7Nd7oaISi/5LNm3bw9WrPgLVatWxcSJUxg0FRIGTkUtIxnJV+cj4fh/1E+5bq5pCWQSyE8++UQtSNuyZUtMnDgRhw8f1u0/e/Ys6tWrhw8++CDT/V599VW1XZZskdvIUh7msn//fjVruJbM7B0aGmq245c29+7dU0vNEBEZFoHv3bsbHTp0wrBhI7NdfYEKjl11RSj13j7E7xgKTVKEblvC0ddQtlsQ7Cu0h7OzS76PnZKSgh49eqh/Fll7rVKlSmptsxdeeEGtCyffQBITE1VwJculvPHGG+q2soCurIMmH8hyDLmNrHuWm9u3b6uAa+nSpTneThamlYCMiIgKZ1JLWcKpadPmqFDBB9WqVedpLmTMOGVj1qxZaNCggVr/zRwpVE16UpagSe1LikDc9iFqv2uZ/E97LwFMZGSkWihWFtKVjNP48ePVMiQSRGlJv7fslzXShARREyZMyPPssTL7rKyflhvplpOsk2S05HG050MyY7I+m2zTZlCkG2/GjBn46KOP1Pprx44dU7eV10KyYLJm25dffplptvXs9hmSY8nzbtiwoWrLunXr1Pb3338fy5cv193uiy++wPz583XdYl999ZV6DvJ38Pbbb+fp+JJdk+chwarWp59+il9//TXX48tSGvLcZC26+vXrY/DgwZmWATJ2HzmenIPp06ejRYsWapsExHJbWThYFmvWLhQsxo4di8WLF2PIkCFqDUH5XSun+/Xv3z9TMDxy5EhcuHBB93coGU9ps5wH+ZskosJx8eIF/PrrT7h/P0rN0cSgqWgwcMqGrEgvi6nqd3XlJGZtK0Qv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Udf1szxz585V27XkuM8//7zK7HTt2lVleTp27KiJiYnRHD58WNO6dWuV2ZAMkFyCgoLM1hZD2kxSdHR0puyEbNu9e3eW282bN09Tr1493fbLly9rnJ2dNb/++mumjFOfPn00I0aMyNNrZMpz/P777zW+vr7qHHXq1Emdn4cPH6rHkm01a9bU9O3bV/PGG2+o2wcGBmrKli2rO8dyXhcuXJjpcSVjI/epUaOGyrxJli67v6E333wzy32lHbVq1VJ/P/JYw4YNU7eTvyXZ5urqqnnvvffMcj/x+uuva6ZOnZrpWHK+5FgDBw5U2VS5LudT38yZM9VxiSwRAyeiEhA4tWzZUjNo0CBd4CQfmtINoiXBQEBAgCYyMlK37eOPP84UOHz33XeaihUrasLCwtR1ua10s+UUOM2aNUt9gJ88eVK3bd++fZp79+5l21VnrraYEjgtXrxYbbt48WKW20lwJ8fbu3ev2i4Byrhx41SwoR84yQe+BIY//vij5vbt29k+fl6fowRO8jhyTvVJ4OTk5KQ5f/68btuDBw9UECnH0Pr22281bm5umbobJfCQwCohISHH9klwI92S+uS+0iWZkpKirm/evFm1TwKY1NRU3blzdHTM1E2W3/uJBg0aaJYvX57pWD169FCBs7h+/brG3t5es23btkz3k787Hx+fHJ8jUXHhqDoiCySj26T7a968eRgzZozqDnr11Vd1+5999lnVXaY1d+5c1VUihbh//fWX6l5xc3NTBc/SRSRk28SJE1GxYkV1XbqXpk+fnmM75PEnT56cqRtGusAqVKiQ7X0Kqy1aK1euVOfm888/x4svvoipU6eiTp06WW7n6OioHkO656SbSZ6Lscd46623VHffe++9hypVqqhC5ieeeAI3btwo0HMU7u7umDJlSpb79+7dG/Xq1dNd37JlC+Li4rK8xtLNtXbt2kz3lba5uLhk2zYZkSbHkm4wQ48//jgcHBx0r6N2mzyOdpvc3/C55+d+8rt05clzNTyWvDZCBj7IRbqc9UnbsxskQFTcWONEZIGkfklGf0ktjAQFUkdSt25d3Wg3qQHRJx9S8sElI9P0SdClHdotxxw3blym/draqJzaMXbs2Dy1vbDaoiWBhASN586dUx/Ab7/9dra3lUDpscceQ7du3eDs7Izu3btjxYoVmW4j5/izzz7Dp59+qs7znj178N///ledf3kMY0GiKc9RSGBobDSk4esntVKyTdqoJUFJtWrV1L6c7mtIzolcpPbMkH4wJc87u20y+rCg91uzZo2qjSpbtmymY8moRX1yX8PHk7Yb3o/IUjBwIrLw4nBjDD+MJbMhQcEXX3yR7X0kqyPFx/oMrxuSYumoqCiT212YbTEsDpdSgwkTJmDgwIGq0Fg/6NCSonopkH7uuedUNienKR1knxRUy0UKuqXwevPmzRg/fny+nqP2mKZslyJwGQRgSLYZFoibMi2FFJ5L1rI4ybQD8trkh7RdvigQWSJ21RFZAZkXZ9GiRaqLRp+MfNPq2LGjGpEnAYd+t1dOpJvFcEJCyQYkJCSo36V7yjBbUFhtMSQBxPfff4/w8HB8++232d7unXfeUW2aNm2a0f3GuuS0z0k7ys6QKc8xL6SrS87r1q1bddsOHjyoMowdOnTI8/F69OiBvXv3orjIc5GRi/kNnKTtPXv2NHu7iMyBGSciK/Duu++qD10Z9i01MDIsXj54ZYj9rl271G3efPNNVZczePBgNWGlZFPOnDmT43H/85//YMOGDeqDXWp1JKBYsmQJ1q1bpx5DhuBHRETg448/VhkamY6gsNqSXebqjTfeUF1tTz75ZJZuIDFkyBB1yY5kjY4ePYp+/fqpehupUfrll1/Uc5YAxBhTnmNeSIZI6qxkUk55PtJNJ+2SYE/OcV5Jm2TaCMkWGk7TUBQ2bdqkul4DAgLyfF+ZqkCmMZDMIpElYsaJyMJIF5DMbWOMfEBLHY10FemTgEHmB5LuqPPnz6taHfnGLrOQa0nh85EjR1QXiPyU/VLHM3z4cN1t5MNOP8iQbiK5rRSIyzxOMr+R1PVo62yk/kqCKAk2JIMk8xaZqy2Gqlatqp67trBY66WXXlIBmDbDor2dfvG8Pin+1t//448/qovMIi5ZEgkEJRCT37W1O4ZMeY5ybmS+LUOSbTOc10h8/fXXKmCTcyi1VXL9t99+y3QbaXduNU5Cuhv79++Pn3/+Odv7yvOVbTIDu5acW9mmH4Dm537ZddMZa78ErPrdcvJajBo1Kl9BF1FR4JIrRERWSOqEZOShNigsKtL9WrlyZTXyUWr18kLWqpNJL99//30VXBNZIgZORERkNpJ9lNnaZXCDdroCImvCwImIiIjIRKxxIiIiIjIRAyciIiIiEzFwIiIiIjIRAyciIiIiEzFwIiIiIjIRAyciIiIiEzFwIiIiIjIRAyciIiIiEzFwIiIiIjIRAyciIiIimOb/AYWN/nxCIuVGAAAAAElFTkSuQmCC", + "text/plain": [ + "
" + ] + }, + "metadata": {}, + "output_type": "display_data" + } + ], + "source": [ + "fig, ax = plt.subplots(figsize=(6, 5))\n", + "for (name, merged), color in zip(held_out.items(), (BLUE, ORANGE, AQUA, YELLOW)):\n", + " groups = merged.groupby(pd.qcut(merged.sampling_error, 5), observed=True)\n", + " predicted = groups.sampling_error.apply(lambda e: np.sqrt((e**2).mean()))\n", + " measured = groups.error.apply(lambda e: np.sqrt((e**2).mean()))\n", + " ax.plot(predicted, measured, marker=\"o\", ms=7, mec=\"white\", mew=1.2, color=color, lw=2, label=name)\n", + "limits = (0.008, 0.6)\n", + "ax.plot(limits, limits, color=GRAY, lw=1, ls=\"--\")\n", + "ax.annotate(\"predicted = actual\", (0.3, 0.3), xytext=(-20, 10), textcoords=\"offset points\", fontsize=8, color=GRAY, rotation=38)\n", + "ax.set(xscale=\"log\", yscale=\"log\", xlim=limits, ylim=limits, xlabel=\"Predicted RMS error (mm/h)\", ylabel=\"Actual RMS error (mm/h)\")\n", + "ax.grid(color=\"#e6e6e3\", lw=0.8, which=\"major\")\n", + "for side in (\"top\", \"right\"):\n", + " ax.spines[side].set_visible(False)\n", + "ax.legend(fontsize=8, frameon=False, loc=\"upper left\")\n", + "ax.set_title(\"Errors of monthly means, by fifths of predicted error\", fontsize=10)\n", + "fig.tight_layout()\n", + "plt.show()" + ] + }, + { + "cell_type": "markdown", + "id": "d2a3b4c5", + "metadata": {}, + "source": [ + "With the statistics of June, the predicted errors of July's monthly means hold for every design: the root mean square of the standardized errors is 1.02 to 1.05, and 94 to 95% of the errors are within 2 predicted standard deviations (95% for a normal distribution). The predictions are 8 to 18% larger than the actual errors on average over the points, as June was wetter than July, which a study can only know from climatology.\n", + "\n", + "The figure shows that the predictions rank the designs correctly, by an order of magnitude from GMI alone (22 samples a month, an error of 0.22 mm/h) to three sun-synchronous satellites (176 samples, 0.045 mm/h), and capture a design's error to within its spread. Within a design, the predictions distinguish points less well: the actual errors of GMI's points hardly differ between the groups whose predicted errors differ by a factor of 2.5, as the differences between the standard deviations of the points in June do not persist in July. The model also predicts, and the samples confirm, that adding GMI to the three sun-synchronous satellites slightly increases the error of a simple mean of the samples (0.048 against 0.045 mm/h): GMI's samples add little independent information, and they weight the times of its passes more than a mean of the field does." + ] + }, + { + "cell_type": "markdown", + "id": "d3b4c5d6", + "metadata": {}, + "source": [ + "## Test 3: Model Inputs\n", + "\n", + "The predictions depend on the statistics of the field. The table gives the root mean square of the standardized errors of each design for other inputs: the statistics of each point in June (rather than smoothed or regional), one regional standard deviation, the statistics of July itself (which a study would not have), and samples taken as independent (a decorrelation time of a second, for which the error is the familiar `sigma / sqrt(n)`)." + ] + }, + { + "cell_type": "code", + "execution_count": 7, + "id": "d4c5d6e7", + "metadata": { + "execution": { + "iopub.execute_input": "2026-11-10T16:29:52.475431Z", + "iopub.status.busy": "2026-11-10T16:29:52.475192Z", + "iopub.status.idle": "2026-11-10T16:29:58.713120Z", + "shell.execute_reply": "2026-11-10T16:29:58.712203Z" + } + }, + "outputs": [ + { + "data": { + "text/html": [ + "
\n", + "\n", + "\n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + "
June, smoothed sigma (Test 2)June, each point's sigma and decorrelationJune, regional sigmaJuly, each point's sigma and decorrelationindependent samples (June, smoothed sigma)
GMI1.031.191.001.010.95
one sun-synchronous1.051.291.071.120.81
three sun-synchronous1.021.210.991.070.55
GMI + three sun-synchronous1.041.231.011.080.62
\n", + "
" + ], + "text/plain": [ + " June, smoothed sigma (Test 2) \\\n", + "GMI 1.03 \n", + "one sun-synchronous 1.05 \n", + "three sun-synchronous 1.02 \n", + "GMI + three sun-synchronous 1.04 \n", + "\n", + " June, each point's sigma and decorrelation \\\n", + "GMI 1.19 \n", + "one sun-synchronous 1.29 \n", + "three sun-synchronous 1.21 \n", + "GMI + three sun-synchronous 1.23 \n", + "\n", + " June, regional sigma \\\n", + "GMI 1.00 \n", + "one sun-synchronous 1.07 \n", + "three sun-synchronous 0.99 \n", + "GMI + three sun-synchronous 1.01 \n", + "\n", + " July, each point's sigma and decorrelation \\\n", + "GMI 1.01 \n", + "one sun-synchronous 1.12 \n", + "three sun-synchronous 1.07 \n", + "GMI + three sun-synchronous 1.08 \n", + "\n", + " independent samples (June, smoothed sigma) \n", + "GMI 0.95 \n", + "one sun-synchronous 0.81 \n", + "three sun-synchronous 0.55 \n", + "GMI + three sun-synchronous 0.62 " + ] + }, + "execution_count": 7, + "metadata": {}, + "output_type": "execute_result" + } + ], + "source": [ + "variants = {\n", + " \"June, smoothed sigma (Test 2)\": (REGIONAL_DECORRELATION, june_stats[\"smoothed sigma\"]),\n", + " \"June, each point's sigma and decorrelation\": (\n", + " pd.to_timedelta(june_stats[\"decorrelation (h)\"].fillna(june_stats[\"decorrelation (h)\"].median()), unit=\"h\"),\n", + " june_stats.sigma,\n", + " ),\n", + " \"June, regional sigma\": (REGIONAL_DECORRELATION, float(june_stats.sigma.median())),\n", + " \"July, each point's sigma and decorrelation\": (\n", + " pd.to_timedelta(july_stats[\"decorrelation (h)\"].fillna(july_stats[\"decorrelation (h)\"].median()), unit=\"h\"),\n", + " july_stats.sigma,\n", + " ),\n", + " \"independent samples (June, smoothed sigma)\": (timedelta(seconds=1), june_stats[\"smoothed sigma\"]),\n", + "}\n", + "test3 = pd.DataFrame(\n", + " {\n", + " variant: {name: score(evaluate(name, scale, sigma))[\"RMS standardized error\"] for name in DESIGNS}\n", + " for variant, (scale, sigma) in variants.items()\n", + " }\n", + ")\n", + "test3.round(2)" + ] + }, + { + "cell_type": "markdown", + "id": "d5d6e7f8", + "metadata": {}, + "source": [ + "The inputs matter more than the details of the model. Each point's own standard deviation from June gives standardized errors of 1.19 to 1.29: the predictions are right on average but wrong at individual points, by the noise of a single month's statistics. One regional standard deviation, or the smoothed standard deviations of Test 2, give 0.99 to 1.07, as does each point's statistics from July itself (1.01 to 1.12), which a study would not have.\n", + "\n", + "Taking samples as independent (the error of a mean of `n` independent samples, `sigma / sqrt(n)`) is adequate for sparse sampling (0.95 for GMI's 22 samples a month) but overpredicts the errors of dense sampling by up to 1.8 times (0.55 for the three sun-synchronous satellites): samples within a few hours of each other repeat each other, but they also share their variations with the monthly mean that they estimate, which the exponential correlation model accounts for." + ] + }, + { + "cell_type": "markdown", + "id": "d6e7f8a9", + "metadata": {}, + "source": [ + "## Test 4: Daily Cycle\n", + "\n", + "The model's field is stationary: it has no daily cycle. Sun-synchronous satellites observe each point at nearly the same local times every day, so where precipitation has a strong daily cycle, their samples repeat the same phase of it, and the error of the mean has a systematic part (a bias) that the model does not predict. The daily cycle of each point is its mean precipitation in each 3-hour interval of local (mean solar) time in July, and its strength is the range of these means relative to the monthly mean. The table gives, for thirds of the points by the strength of their daily cycle, the root mean square of the standardized errors of each design (as in Test 2), and the mean error of the single sun-synchronous design relative to the mean precipitation." + ] + }, + { + "cell_type": "code", + "execution_count": 8, + "id": "d7f8a9b0", + "metadata": { + "execution": { + "iopub.execute_input": "2026-11-10T16:29:58.714807Z", + "iopub.status.busy": "2026-11-10T16:29:58.714632Z", + "iopub.status.idle": "2026-11-10T16:29:58.907962Z", + "shell.execute_reply": "2026-11-10T16:29:58.907051Z" + } + }, + "outputs": [ + { + "data": { + "text/html": [ + "
\n", + "\n", + "\n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + "
daily range / mean (median)GMIone sun-synchronousthree sun-synchronousGMI + three sun-synchronousone sun-synchronous: mean error (% of mean)
weak1.381.050.911.061.083.39
moderate2.020.850.960.930.911.80
strong2.921.161.251.051.112.99
\n", + "
" + ], + "text/plain": [ + " daily range / mean (median) GMI one sun-synchronous \\\n", + "weak 1.38 1.05 0.91 \n", + "moderate 2.02 0.85 0.96 \n", + "strong 2.92 1.16 1.25 \n", + "\n", + " three sun-synchronous GMI + three sun-synchronous \\\n", + "weak 1.06 1.08 \n", + "moderate 0.93 0.91 \n", + "strong 1.05 1.11 \n", + "\n", + " one sun-synchronous: mean error (% of mean) \n", + "weak 3.39 \n", + "moderate 1.80 \n", + "strong 2.99 " + ] + }, + "execution_count": 8, + "metadata": {}, + "output_type": "execute_result" + } + ], + "source": [ + "series = july.values.reshape(july.sizes[\"time\"], -1).T\n", + "utc_hours = july.time.dt.hour.values + july.time.dt.minute.values / 60\n", + "local_bin = (((utc_hours[None, :] + points.geometry.x.values[:, None] / 15) % 24) // 3).astype(int)\n", + "cycle = np.array([[series[i, local_bin[i] == b].mean() for b in range(8)] for i in range(len(points))])\n", + "strength = pd.Series((cycle.max(axis=1) - cycle.min(axis=1)) / series.mean(axis=1), index=points.target_hash)\n", + "band = pd.qcut(strength, 3, labels=[\"weak\", \"moderate\", \"strong\"])\n", + "test4 = pd.DataFrame(\n", + " {\n", + " name: merged.groupby(band.reindex(merged.index), observed=True).z.apply(lambda z: np.sqrt((z**2).mean()))\n", + " for name, merged in held_out.items()\n", + " }\n", + ")\n", + "single = held_out[\"one sun-synchronous\"]\n", + "test4[\"one sun-synchronous: mean error (% of mean)\"] = single.groupby(band.reindex(single.index), observed=True).apply(\n", + " lambda g: 100 * g.error.mean() / g.true_mean.mean()\n", + ")\n", + "test4.insert(0, \"daily range / mean (median)\", strength.groupby(band, observed=True).median())\n", + "test4.round(2)" + ] + }, + { + "cell_type": "markdown", + "id": "d8a9b0c1", + "metadata": {}, + "source": [ + "The daily cycle is the main limit of the model. At the third of the points with the strongest daily cycles (whose 3-hourly means range over about 3 times the monthly mean), the errors of the single sun-synchronous satellite are 25% larger than predicted (1.25), and those of GMI 16% larger, whereas they are within 15% of the predictions at the other points. The satellites that sample more local times are less affected (1.05 for three sun-synchronous satellites). The single sun-synchronous satellite also overestimates the monthly means by 2 to 3% (a bias at its local times of 13:30 and 01:30), small next to its random error here (60% of the mean). A study of a design that samples a strongly cycling field at few local times should expect errors somewhat larger than predicted." + ] + }, + { + "cell_type": "markdown", + "id": "d9b0c1d2", + "metadata": {}, + "source": [ + "## Summary\n", + "\n", + "| Test | Metric | Result |\n", + "|---|---|---|\n", + "| Field statistics | Decorrelation time (median, June and July) | 2.7 and 2.9 h |\n", + "| | Correlation of standard deviations of June and July at the points (each point, smoothed) | 0.16, 0.21 |\n", + "| Sampling errors (June statistics) | RMS standardized error of July's monthly means | 1.02 to 1.05 (four designs) |\n", + "| | Errors within 2 predicted standard deviations | 94 to 95% |\n", + "| | Errors of designs (actual RMS) | 0.22 mm/h (GMI, 22 samples a month) to 0.045 mm/h (three sun-synchronous, 176 samples), ranked as predicted |\n", + "| Model inputs | RMS standardized error: each point's June statistics; regional; July's | 1.19 to 1.29; 0.99 to 1.07; 1.01 to 1.12 |\n", + "| | Independent samples (`sigma / sqrt(n)`) | 0.55 to 0.95 (overpredicts dense sampling by up to 1.8 times) |\n", + "| Daily cycle | RMS standardized error at the strongest third of daily cycles | 1.25 (one sun-synchronous), 1.16 (GMI), 1.05 (three) |\n", + "| | Bias of one sun-synchronous satellite | +2 to +3% of the mean |\n", + "\n", + "TAT-C's sampling error model predicts the errors of monthly mean precipitation from real constellations' samples, given a standard deviation from another month (smoothed over neighboring points or regional) and a regional decorrelation time. Use smoothed or climatological standard deviations rather than a single month's at each point, and expect errors up to 25% larger than predicted where the field's daily cycle is strong and the design samples few local times.\n", + "\n", + "Limitations:\n", + "\n", + "* **One region and month.** The Maritime Continent in July, with convective precipitation and strong daily cycles; other fields (such as temperature) and seasons have other statistics.\n", + "* **IMERG as the truth.** IMERG's half-hourly values merge the observations of the same kinds of satellites, interpolated between them by the motion of the precipitation, which may smooth its variations within hours and lengthen its decorrelation time.\n", + "* **Temporal sampling only.** Each sample is the value of a 0.1 deg cell in its half-hour: the footprints of the instruments, the times within the half-hour, and the errors of the retrievals are not modeled." + ] + } + ], + "metadata": { + "kernelspec": { + "display_name": "Python 3 (ipykernel)", + "language": "python", + "name": "python3" + }, + "language_info": { + "codemirror_mode": { + "name": "ipython", + "version": 3 + }, + "file_extension": ".py", + "mimetype": "text/x-python", + "name": "python", + "nbconvert_exporter": "python", + "pygments_lexer": "ipython3", + "version": "3.14.9" + } + }, + "nbformat": 4, + "nbformat_minor": 5 +} diff --git a/docs/validation/index.rst b/docs/validation/index.rst index b8f0a09..cb5541f 100644 --- a/docs/validation/index.rst +++ b/docs/validation/index.rst @@ -2,7 +2,7 @@ Validation ========== -The following compare TAT-C analysis results with reference data from operational missions. The :doc:`summary` collects their headline results by capability, with modeling guidance and the limits of what TAT-C models. The :doc:`catalog` gives instruments of operational missions, ready to use, with their results against the :doc:`standard`. +The following compare TAT-C analysis results with reference data from operational missions, or with published studies. The :doc:`summary` collects their headline results by capability, with modeling guidance and the limits of what TAT-C models. The :doc:`catalog` gives instruments of operational missions, ready to use, with their results against the :doc:`standard`. .. toctree:: :maxdepth: 1 @@ -31,6 +31,7 @@ The following compare TAT-C analysis results with reference data from operationa ValidateConicalGMI.ipynb ValidateCoincidenceGMIAMSR2.ipynb ValidateGridSMAP.ipynb + ValidateSamplingErrorIMERG.ipynb ValidateOrbitGeneration.ipynb ValidateDopGNSS.ipynb ValidateLatencyNOAA20.ipynb @@ -47,8 +48,9 @@ The following compare TAT-C analysis results with reference data from operationa ValidateYawFlipGPM.ipynb ValidateSampleSizes.ipynb ValidateFeaturesTCPRIMED.ipynb + ValidateCostVarianceNSOSA.ipynb -These notebooks download reference data on first run, except ``ValidateSampleSizes``, which reuses the data of the imager and conical scanner notebooks, and ``ValidateSpaceCOSMIC2``, which reuses the data of ``ValidateROCOSMIC2``. ``ValidateSpaceSOCRATES`` includes a sample of a SOCRATES run (data from CelesTrak). The MLS, NISAR, AMSR2, GMI, SWOT, ICESat-2, ECOSTRESS, PACE, MODIS, OCO-2, GPM, GRACE-FO, and SMAP data require a free `NASA Earthdata Login `_ account, and the orbit histories of the Landsat 9, TC PRIMED, and GRACE-FO notebooks a free `Space-Track.org `_ account. The notebooks require additional dependencies, which can be installed via:: +These notebooks download reference data on first run, except ``ValidateSampleSizes``, which reuses the data of the imager and conical scanner notebooks, and ``ValidateSpaceCOSMIC2``, which reuses the data of ``ValidateROCOSMIC2``. ``ValidateSpaceSOCRATES`` includes a sample of a SOCRATES run (data from CelesTrak). ``ValidateCostVarianceNSOSA`` needs no data: its reference values are those published in the paper it reproduces. The MLS, NISAR, AMSR2, GMI, SWOT, ICESat-2, ECOSTRESS, PACE, MODIS, OCO-2, GPM, GRACE-FO, SMAP, and IMERG data require a free `NASA Earthdata Login `_ account, and the orbit histories of the Landsat 9, TC PRIMED, and GRACE-FO notebooks a free `Space-Track.org `_ account. The notebooks require additional dependencies, which can be installed via:: pip install tatc[validation] diff --git a/docs/validation/summary.rst b/docs/validation/summary.rst index 5655cb3..24f11a6 100644 --- a/docs/validation/summary.rst +++ b/docs/validation/summary.rst @@ -4,7 +4,8 @@ Validation Summary The validation notebooks compare TAT-C's analyses with data from operational missions: recorded orbits, geolocated samples, acquisition catalogs, and -archives of observations, mostly from 2025 and 2026. This page summarizes +archives of observations, mostly from 2025 and 2026, and one compares its +trade study capabilities with a published cost analysis. This page summarizes their headline results by capability, the modeling choices they found to matter, and the limits of what TAT-C models. Each result links to the notebook with its full method, data, and figures. Results marked as held out come from the @@ -215,6 +216,12 @@ Coverage Analyses - GMI and AMSR2 within 15 minutes - With `instantaneous=True`, 97.7% of true coincidences found and 99.9% of those found true, within 2.4 s (95th percentile); 98.2% of coincident points within coincident footprints (:doc:`ValidateCoincidenceGMIAMSR2`) + * - Sampling error (`estimate_sampling_error`) + - IMERG half-hourly precipitation, Maritime Continent, July 2025; four constellation designs + - With the statistics of June, errors of July's monthly means at 1,600 points as predicted (RMS standardized + errors 1.02 to 1.05; 94 to 95% within 2 predicted standard deviations); designs ranked by an order of magnitude, + as predicted; independent samples (`sigma / sqrt(n)`) overpredict dense sampling by up to 1.8 times + (:doc:`ValidateSamplingErrorIMERG`) Limb, Occultation, and Satellite-to-Satellite Analyses ====================================================== @@ -270,6 +277,31 @@ Ground Systems and Navigation - Within 0.01% (median) of an independent computation for the same satellites, including a clock per system (:doc:`ValidateDopGNSS`) +Trade Studies +============= + +.. list-table:: + :header-rows: 1 + :widths: 20 25 55 + + * - Capability + - Reference + - Result + * - Correlated cost risk (`Triangular`, `Component`, `CostModel.draw`, `risk_space`, `exceedance`) + - Maier, Yeakel, and Wendoloski (2023): two NSOSA constellations that share a geostationary configuration + - With the published numbers of blocks and units, replicates with common random numbers reproduce the + expected costs, standard deviations, and covariance of the constellations within their sampling error, and + the probability that one costs more than the other (97.8%; 94.8% with independent draws); Table I's growth + factors reproduced (:doc:`ValidateCostVarianceNSOSA`) + * - Production blocks and study periods (`DeploymentSchedule`, `SatelliteCost.block_size`) + - Launch schedules and production blocks of the same study + - Launches, production of later units, and developments of both blocks of the geostationary configuration + reproduced to the month; over the study period (a sustained constellation, with a design life of each + configuration), the published numbers of developments and units of two of three configurations + reproduced, and one constellation's expected cost; the third configuration's published numbers cannot be + derived from its schedule, which costs the constellation that flies it 4% more than published and raises + the probability above to 99.9% (:doc:`ValidateCostVarianceNSOSA`) + Modeling Guidance ================= @@ -311,6 +343,23 @@ numerical error in TAT-C: 5 deg reproduces the acquisitions of sun-synchronous land imagers. * **Coincidences of samples.** Observation periods of scanning instruments last minutes; compare their epochs with `instantaneous=True`. +* **Statistics of sampled fields.** A single month's standard deviation of + precipitation at a point predicts the next month's poorly (a correlation of + 0.16); smoothed or regional standard deviations, from climatology or another + period, give calibrated sampling errors, and one regional decorrelation time + suffices. +* **Correlation of cost growth.** `CostModel.correlation` correlates the normal + scores from which the growths of components are drawn; the growths of skewed + distributions are correlated slightly less (0.486 for 0.5, with the cost + growth factors of formal risk assessments). Use about 0.514 to correlate the + costs of components by 0.5. +* **Costs within a study period.** A mission that is not sustained costs the + satellites it launches by its end. To compare operational constellations + over a fixed study period, as architecture studies do, use + `DeploymentSchedule(sustained=True)`, which counts the share of the units + (and later blocks' developments) in production at the end; the two differ by + 2 to 7% of the cost of a constellation over 30 years, unevenly between + alternatives. * **Navigation constellations.** Model the operational satellites (those with healthy broadcast ephemerides); public TLE groups include others, which make DOP 4 to 16% optimistic. @@ -326,6 +375,10 @@ Not Modeled * Pointing limits in `collect_space_observations`, such as an antenna's field of view, and slews between attitudes, which are instantaneous. * Acquisition plans, downlink processing time, and data gaps. +* Daily cycles of sampled fields: sampling errors model a stationary field, so + sun-synchronous sampling of a field with a strong daily cycle has errors up + to 25% larger than predicted, and a small bias (2 to 3% for IMERG + precipitation over the Maritime Continent). Changes to TAT-C from Validation ================================ diff --git a/pyproject.toml b/pyproject.toml index 989c2dc..7410819 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -107,6 +107,12 @@ osse = [ preprocess = [ "rasterio" ] +tradespace = [ + "joblib", + "matplotlib", + "optuna", + "pymoo" +] validation = [ "tatc[examples,preprocess]", "awsgnssroutils", diff --git a/src/tatc/analysis/__init__.py b/src/tatc/analysis/__init__.py index e3dae03..d254d61 100644 --- a/src/tatc/analysis/__init__.py +++ b/src/tatc/analysis/__init__.py @@ -58,6 +58,14 @@ from .space_sampling import ( collect_space_observations, ) +from .sufficiency import ( + compare_sampled_means, + compute_local_time_coverage, + compute_revisit_statistics, + estimate_sampling_error, + sample_field, + sampling_error_variance, +) __all__ = [ "DopMethod", @@ -79,18 +87,24 @@ "collect_region_observations", "collect_ro_observations", "collect_space_observations", + "compare_sampled_means", "compute_access_periods", "compute_dop", "compute_ground_track", "compute_latencies", + "compute_local_time_coverage", "compute_platform_track", - "compute_sample_sizes", "compute_radar_track", "compute_region_access_periods", + "compute_revisit_statistics", + "compute_sample_sizes", + "estimate_sampling_error", "find_coincident_ground_track", "find_coincident_observations", "grid_latencies", "grid_observations", "reduce_latencies", "reduce_observations", + "sample_field", + "sampling_error_variance", ] diff --git a/src/tatc/analysis/latency_sampling.py b/src/tatc/analysis/latency_sampling.py index ef3c8c1..17b39af 100644 --- a/src/tatc/analysis/latency_sampling.py +++ b/src/tatc/analysis/latency_sampling.py @@ -150,6 +150,7 @@ def compute_latencies( Returns: geopandas.GeoDataFrame: The data frame of collected latency results, sorted by the 'observed' column in ascending order. It includes the following columns: + - 'target_hash' (str): Hash of the observation point (see `tatc.utils.geometry.hash_geometry`). - 'geometry' (geometry): Geometry representing the observation point. diff --git a/src/tatc/analysis/sufficiency.py b/src/tatc/analysis/sufficiency.py new file mode 100644 index 0000000..8759de7 --- /dev/null +++ b/src/tatc/analysis/sufficiency.py @@ -0,0 +1,583 @@ +""" +Methods to assess the statistical sufficiency of observations: how well the +samples of a target (such as a point) estimate a statistic of a varying +field, and how their times are distributed. + +Observations sample a field (such as precipitation or temperature) at +discrete times, from which a statistic (such as the mean over a month) is +estimated. Its error depends on how many samples there are, and on how they +are spread in time relative to how quickly the field decorrelates: samples +closer together than the decorrelation time repeat each other. The error +can be estimated for a model of the field (`estimate_sampling_error`) or +measured against a simulation of it (a nature run, see `sample_field` and +`compare_sampled_means`). The distribution of the samples in time +(`compute_revisit_statistics`) and in local time of day +(`compute_local_time_coverage`, for fields with daily cycles) explains it. + +@author: Paul T. Grogan +""" + +from __future__ import annotations + +from collections.abc import Mapping, Sequence +from datetime import datetime, timedelta +from typing import Any + +import geopandas as gpd +import numpy as np +import pandas as pd + +from ..utils.geometry import _hash_geometries + + +def _get_points(geometries: gpd.GeoSeries) -> tuple[np.ndarray, np.ndarray]: + """ + Gets the longitudes and latitudes (degrees) of geometries: points, or the + representative points of other geometries. + """ + points = geometries.representative_point() + return points.x.to_numpy(), points.y.to_numpy() + + +def _get_seconds(times: pd.Series | pd.Index, origin: datetime) -> np.ndarray: + """ + Gets times as seconds after an origin. + """ + times = pd.DatetimeIndex(pd.to_datetime(times, utc=True)) + return np.asarray((times - pd.Timestamp(origin)).total_seconds(), dtype=float) + + +def _get_targets( + observations: pd.DataFrame, targets: gpd.GeoDataFrame | gpd.GeoSeries | None +) -> gpd.GeoDataFrame: + """ + Gets the targets: those given (identified by the hash of their geometry), + or those observed. + """ + if targets is None: + first = ~observations["target_hash"].duplicated().to_numpy() + result = observations.loc[first, ["target_hash", "geometry"]] + result = result.reset_index(drop=True) + return result if result.crs is not None else result.set_crs("EPSG:4326") + geometry = targets if isinstance(targets, gpd.GeoSeries) else targets.geometry + return gpd.GeoDataFrame( + {"target_hash": _hash_geometries(geometry)}, + geometry=geometry.to_numpy(), + crs="EPSG:4326", + ) + + +def _exponential_integral(t: np.ndarray, length: float, scale: float) -> np.ndarray: + """ + Integrates the exponential correlation exp(-|t - s| / scale) over s in + [0, length], for each time t. + """ + inside = (t >= 0) & (t <= length) + before = np.exp(-np.abs(t) / scale) - np.exp(-np.abs(length - t) / scale) + within = 2 - np.exp(-t / scale) - np.exp(-(length - t) / scale) + return scale * np.where(inside, within, np.abs(before)) + + +def sampling_error_variance( + times: Sequence[float] | np.ndarray, + length: float, + decorrelation_time: float, +) -> float: + """ + Computes the variance (as a share of the variance of the field) of the + error of estimating the mean of a field over a period from its samples + at given times: the mean of the samples, compared with the mean over the + period. The field is stationary, with an exponential correlation in time + (`exp(-|dt| / decorrelation_time)`, a first-order Markov process), for + which the variance is exact:: + + var(e) / var(x) = (1/n^2) sum_ij r(t_i - t_j) + - (2/(n L)) sum_i integral_0^L r(t_i - s) ds + + (1/L^2) integral_0^L integral_0^L r(s - s') ds ds' + + Samples farther apart than the decorrelation time are nearly independent, + and the variance approaches 1/n; samples closer together repeat each + other, and the variance falls less. + + Args: + times (Sequence[float]): The times of the samples (seconds after the + start of the period). + length (float): The length of the period (seconds). + decorrelation_time (float): The decorrelation time (seconds). + + Returns: + float: the variance of the error, as a share of the field's variance + (`NaN` without samples) + """ + return _error_terms(times, length, decorrelation_time)[1] + + +def _error_terms( + times: Sequence[float] | np.ndarray, length: float, decorrelation_time: float +) -> tuple[float, float]: + """ + Computes the mean correlation between pairs of samples (the variance of + their mean, as a share of the field's) and the variance of the sampling + error (see `sampling_error_variance`). + """ + t = np.asarray(times, dtype=float) + if len(t) == 0: + return np.nan, np.nan + if length <= 0 or decorrelation_time <= 0: + raise ValueError("the length and decorrelation time must be positive") + scale = decorrelation_time + pairs = np.exp(-np.abs(t[:, None] - t[None, :]) / scale).mean() + cross = _exponential_integral(t, length, scale).sum() / (len(t) * length) + within = 2 * (scale * length - scale**2 * (1 - np.exp(-length / scale))) / length**2 + return float(pairs), float(max(pairs - 2 * cross + within, 0.0)) + + +def _error_terms_by_group( + seconds: np.ndarray, + codes: np.ndarray, + groups: int, + length: float, + scales: np.ndarray, +) -> tuple[np.ndarray, np.ndarray, np.ndarray]: + """ + Computes the error terms (see `_error_terms`) of the samples of each + group (such as a target) at once: the samples' times (seconds), the code + of the group of each (0 to `groups` - 1), and the decorrelation time of + each group. Gives the number of samples of each group, the mean + correlation between pairs of its samples, and the variance of its + sampling error (`NaN` without samples). + + The sum of the correlations between pairs of samples follows, for the + samples of a group in order of time, from the recursion `S_j = exp(-(t_j + - t_(j-1)) / scale) * (S_(j-1) + 1)` (the sum of the correlations of + sample `j` with those before it), stepped for every group at once. + """ + if length <= 0 or np.any(scales <= 0): + raise ValueError("the length and decorrelation time must be positive") + order = np.lexsort((seconds, codes)) + t, c = seconds[order], codes[order] + counts = np.bincount(c, minlength=groups) + first = np.concatenate([[0], np.cumsum(counts)[:-1]]) + position = np.arange(len(t)) - first[c] + width = int(counts.max()) if len(counts) > 0 and len(t) > 0 else 0 + table = np.zeros((groups, max(width, 1))) + table[c, position] = t + recent = np.zeros(groups) # S of the latest sample of each group + total = np.zeros(groups) # sum of S over the samples of each group + for k in range(1, width): + active = counts > k + gap = table[active, k] - table[active, k - 1] + recent[active] = np.exp(-gap / scales[active]) * (recent[active] + 1) + total[active] += recent[active] + with np.errstate(divide="ignore", invalid="ignore"): + pairs = (counts + 2 * total) / counts.astype(float) ** 2 + cross = np.bincount( + c, weights=_exponential_integral(t, length, scales[c]), minlength=groups + ) / (counts * length) + within = ( + 2 + * (scales * length - scales**2 * (1 - np.exp(-length / scales))) + / length**2 + ) + variance = np.maximum(pairs - 2 * cross + within, 0.0) + empty = counts == 0 + pairs[empty] = np.nan + variance[empty] = np.nan + return counts, pairs, variance + + +def estimate_sampling_error( + observations: gpd.GeoDataFrame, + start: datetime, + end: datetime, + decorrelation_time: timedelta | Mapping[str, timedelta] | pd.Series, + standard_deviation: float | Mapping[str, float] | pd.Series = 1.0, + targets: gpd.GeoDataFrame | gpd.GeoSeries | None = None, + time_column: str = "epoch", +) -> gpd.GeoDataFrame: + """ + Estimates the sampling error of each target: the error of estimating the + mean of a field over a period from the target's samples (observations) + for a model of the field, stationary with a standard deviation and an + exponential correlation in time with a decorrelation time (see + `sampling_error_variance`). The decorrelation time of a field is the time + over which its values become nearly independent: hours for convective + precipitation, days for synoptic temperature. + + Gives for each target the number of `samples`, the standard deviation of + the error (`sampling_error`, in the units of the field's standard + deviation), the error relative to the field's standard deviation + (`relative_error`), and the effective number of independent samples + (`effective_samples`): the number of independent samples whose mean + would vary as much as the mean of the samples (the inverse of the mean + correlation between pairs of samples), which equals the number of + samples if they are farther apart than the decorrelation time, and is + less if they repeat each other. Targets without samples have no error + estimate (`NaN`) and no effective samples. + + Args: + observations (geopandas.GeoDataFrame): The observations (see + `collect_observations`), with the `target_hash` and the time + (`time_column`) of each sample. + start (datetime.datetime): The start of the period. + end (datetime.datetime): The end of the period. + decorrelation_time (datetime.timedelta | Mapping | pandas.Series): The + decorrelation time of the field, or of each target (by + `target_hash`), as for a field that decorrelates faster in some + places (such as over land) than others. + standard_deviation (float | Mapping | pandas.Series): The standard + deviation of the field, or of each target (by `target_hash`). + targets (geopandas.GeoDataFrame | geopandas.GeoSeries | None): The + targets, including those not observed, or `None` for those + observed. + time_column (str): The column of the times of the samples. + + Returns: + geopandas.GeoDataFrame: a row per target + """ + length = (end - start).total_seconds() + result = _get_targets(observations, targets) + seconds = _get_seconds(observations[time_column], start) + codes, keys = pd.factorize(observations["target_hash"].to_numpy()) + # the decorrelation time of each observed target + if isinstance(decorrelation_time, (Mapping, pd.Series)): + scales = { + key: pd.Timedelta(value).total_seconds() + for key, value in dict(decorrelation_time).items() + } + per_group = np.array([scales[key] for key in keys], dtype=float) + else: + per_group = np.full(len(keys), decorrelation_time.total_seconds()) + counts, pairs, variance = _error_terms_by_group( + seconds, codes, len(keys), length, per_group + ) + # the group of each target (-1 for targets without samples) + index = pd.Index(keys).get_indexer(result["target_hash"].to_numpy()) + found = index >= 0 + picked = np.where(found, index, 0) + samples = np.where(found, counts[picked], 0).astype(int) + relative_error = np.sqrt(np.where(found, variance[picked], np.nan)) + with np.errstate(divide="ignore"): + effective = np.where(found, 1 / pairs[picked], 0.0) + if isinstance(standard_deviation, (Mapping, pd.Series)): + sigma = result["target_hash"].map(standard_deviation).to_numpy(dtype=float) + else: + sigma = float(standard_deviation) + return result.assign( + samples=samples, + relative_error=relative_error, + sampling_error=relative_error * sigma, + effective_samples=effective, + ) + + +def compute_revisit_statistics( + observations: gpd.GeoDataFrame, + start: datetime, + end: datetime, + quantiles: Sequence[float] = (0.5, 0.9), + targets: gpd.GeoDataFrame | gpd.GeoSeries | None = None, + time_column: str = "epoch", +) -> gpd.GeoDataFrame: + """ + Computes statistics of the revisits of each target over a period: the + number of `samples`, the mean and quantiles of the times between + consecutive samples (`revisit`, and `revisit p50`, `revisit p90`, ...), + and the longest time without a sample (`max_gap`), including the times + from the start of the period to the first sample and from the last + sample to the end, which a mean revisit hides. Targets without samples + have a gap of the whole period. + + Args: + observations (geopandas.GeoDataFrame): The observations (see + `collect_observations`), with the `target_hash` and the time + (`time_column`) of each sample. + start (datetime.datetime): The start of the period. + end (datetime.datetime): The end of the period. + quantiles (Sequence[float]): The quantiles of the revisits. + targets (geopandas.GeoDataFrame | geopandas.GeoSeries | None): The + targets, including those not observed, or `None` for those + observed. + time_column (str): The column of the times of the samples. + + Returns: + geopandas.GeoDataFrame: a row per target + """ + length = (end - start).total_seconds() + result = _get_targets(observations, targets) + seconds = _get_seconds(observations[time_column], start) + codes, keys = pd.factorize(observations["target_hash"].to_numpy()) + groups = len(keys) + # the samples of each target in order of time, and the gaps between them + order = np.lexsort((seconds, codes)) + t, c = seconds[order], codes[order] + counts = np.bincount(c, minlength=groups) + ends = np.cumsum(counts) + same = c[1:] == c[:-1] + gaps, gap_codes = (t[1:] - t[:-1])[same], c[1:][same] + gap_counts = np.bincount(gap_codes, minlength=groups) + with np.errstate(invalid="ignore", divide="ignore"): + revisit = np.bincount(gap_codes, weights=gaps, minlength=groups) / gap_counts + # the longest time without a sample, from the start to the end of the period + longest = np.full(groups, -np.inf) + if len(t) > 0: + longest = np.maximum(t[ends - counts], length - t[ends - 1]) + np.maximum.at(longest, gap_codes, gaps) + # quantiles of the gaps of each target (by linear interpolation, as numpy) + gap_order = np.lexsort((gaps, gap_codes)) + ordered = gaps[gap_order] + gap_starts = np.cumsum(gap_counts) - gap_counts + has_gaps = gap_counts > 0 + revisits = {} + for q in quantiles: + position = q * np.maximum(gap_counts - 1, 0) + below = np.floor(position).astype(int) + above = np.minimum(below + 1, np.maximum(gap_counts - 1, 0)) + low = np.where(has_gaps, gap_starts + below, 0) + high = np.where(has_gaps, gap_starts + above, 0) + if len(ordered) > 0: + value = ordered[low] + (ordered[high] - ordered[low]) * (position - below) + else: + value = np.zeros(groups) + revisits[f"revisit p{round(100 * q)}"] = np.where(has_gaps, value, np.nan) + # the statistics of every target (without samples: none, and the whole period) + index = pd.Index(keys).get_indexer(result["target_hash"].to_numpy()) + found = index >= 0 + picked = np.where(found, index, 0) + + def per_target(values: np.ndarray, missing: float) -> np.ndarray: + if groups == 0: + return np.full(len(index), missing) + return np.where(found, values[picked], missing) + + columns = { + "samples": per_target(counts, 0).astype(int), + "revisit": pd.to_timedelta(per_target(revisit, np.nan), unit="s"), + **{ + name: pd.to_timedelta(per_target(values, np.nan), unit="s") + for name, values in revisits.items() + }, + "max_gap": pd.to_timedelta(per_target(longest, length), unit="s"), + } + return result.assign(**columns) + + +def compute_local_time_coverage( + observations: gpd.GeoDataFrame, + bins: int = 8, + targets: gpd.GeoDataFrame | gpd.GeoSeries | None = None, + time_column: str = "epoch", +) -> gpd.GeoDataFrame: + """ + Computes the distribution of the samples of each target in local (mean + solar) time of day, which a field with a daily cycle (such as convective + precipitation, or land surface temperature) needs to be sampled across: + the number of samples in each of `bins` equal intervals of the day (`local + 00:00`, ...), the number of intervals sampled (`local_bins_sampled`), and + their share (`local_time_coverage`). The local time of a sample is the + universal time plus the target's longitude (15 degrees per hour). + + Args: + observations (geopandas.GeoDataFrame): The observations (see + `collect_observations`), with the `target_hash` and the time + (`time_column`) of each sample. + bins (int): The number of intervals of the day. + targets (geopandas.GeoDataFrame | geopandas.GeoSeries | None): The + targets, including those not observed, or `None` for those + observed. + time_column (str): The column of the times of the samples. + + Returns: + geopandas.GeoDataFrame: a row per target + """ + if bins < 1: + raise ValueError("bins must be at least 1") + result = _get_targets(observations, targets) + longitude, _ = _get_points(observations.geometry) + times = pd.to_datetime(observations[time_column], utc=True) + hours = ( + times.dt.hour + times.dt.minute / 60 + times.dt.second / 3600 + ).to_numpy() + longitude / 15 + index = np.floor((hours % 24) / (24 / bins)).astype(int) % bins + counts = ( + pd.crosstab(observations["target_hash"].to_numpy(), index) + .reindex(columns=range(bins), fill_value=0) + .reindex(result["target_hash"], fill_value=0) + ) + width = 24 / bins + for k in range(bins): + hour = k * width + label = f"local {int(hour):02d}:{round(60 * (hour % 1)):02d}" + result[label] = counts[k].to_numpy() + sampled = (counts.to_numpy() > 0).sum(axis=1) + result["local_bins_sampled"] = sampled + result["local_time_coverage"] = sampled / bins + return result + + +def _get_dimension(field: Any, names: Sequence[str], given: str | None) -> str: + """Gets the name of a dimension of a field.""" + if given is not None: + return given + for name in names: + if name in field.dims: + return name + raise ValueError(f"the field has no dimension named any of {list(names)}") + + +def _field_times(field: Any, dimension: str, times: pd.Series) -> np.ndarray: + """ + Converts times to those of the time coordinate of a field: naive (UTC) if + the field's are. + """ + times = pd.to_datetime(times, utc=True) + if getattr(field[dimension].dtype, "tz", None) is None: + times = times.dt.tz_convert("UTC").dt.tz_localize(None) + return times.to_numpy() + + +def _field_longitudes(field: Any, dimension: str, longitude: np.ndarray) -> np.ndarray: + """ + Converts longitudes to the convention of a field: [0, 360) if its + longitudes exceed 180 degrees, else [-180, 180). + """ + if float(field[dimension].max()) > 180: + return np.mod(longitude, 360) + return (longitude + 180) % 360 - 180 + + +def sample_field( + observations: gpd.GeoDataFrame, + field: Any, + name: str | None = None, + method: str = "nearest", + time_column: str = "epoch", + dimensions: Mapping[str, str] | None = None, +) -> gpd.GeoDataFrame: + """ + Samples a field (such as a variable of a nature run) at the time and place + of each observation: at its point (or the representative point of its + region), by the nearest value or by linear interpolation in time and + space. Observations outside the period of the field have no value + (`NaN`). Requires xarray. + + Args: + observations (geopandas.GeoDataFrame): The observations, with the time + (`time_column`) of each sample. + field (xarray.DataArray): The field, with dimensions of time, + latitude, and longitude (by default named `time`, `lat` or + `latitude`, and `lon` or `longitude`), in degrees, with longitudes + in [-180, 180) or [0, 360). + name (str | None): The column of the sampled values, or `None` for the + field's name (or `"value"`). + method (str): `"nearest"` or `"linear"`. + time_column (str): The column of the times of the samples. + dimensions (Mapping[str, str] | None): The names of the field's + dimensions of `time`, `lat`, and `lon`, if not the defaults. + + Returns: + geopandas.GeoDataFrame: the observations, with the sampled values + """ + # pylint: disable=import-outside-toplevel + import xarray as xr + + if method not in ("nearest", "linear"): + raise ValueError(f"method must be 'nearest' or 'linear', not {method!r}") + dimensions = dict(dimensions or {}) + time_dim = _get_dimension(field, ["time"], dimensions.get("time")) + lat_dim = _get_dimension(field, ["lat", "latitude"], dimensions.get("lat")) + lon_dim = _get_dimension(field, ["lon", "longitude"], dimensions.get("lon")) + name = name or field.name or "value" + result = observations.copy() + if len(observations) == 0: + result[name] = pd.Series(dtype=float) + return result + longitude, latitude = _get_points(observations.geometry) + where = { + time_dim: xr.DataArray( + _field_times(field, time_dim, observations[time_column]), dims="sample" + ), + lat_dim: xr.DataArray(latitude, dims="sample"), + lon_dim: xr.DataArray( + _field_longitudes(field, lon_dim, longitude), dims="sample" + ), + } + if method == "nearest": + values = field.sel(where, method="nearest").to_numpy().astype(float) + times = where[time_dim].to_numpy() + coordinate = field[time_dim].to_numpy() + outside = (times < coordinate.min()) | (times > coordinate.max()) + values[outside] = np.nan + else: + values = field.interp(where).to_numpy().astype(float) + result[name] = values + return result + + +def compare_sampled_means( + sampled: gpd.GeoDataFrame, + field: Any, + start: datetime, + end: datetime, + name: str | None = None, + targets: gpd.GeoDataFrame | gpd.GeoSeries | None = None, + method: str = "nearest", + dimensions: Mapping[str, str] | None = None, +) -> gpd.GeoDataFrame: + """ + Compares the mean of each target's samples of a field (see + `sample_field`) with the true mean of the field at the target over a + period (the mean of its values at the target's place, nearest or + interpolated, at every time of the field in the period): the number of + `samples`, the `sampled_mean`, the `true_mean`, and the `error` (sampled + less true), which measures the sampling error against a simulation of + the field. Targets without samples have no sampled mean (`NaN`). Requires + xarray. + + Args: + sampled (geopandas.GeoDataFrame): The observations with sampled + values. + field (xarray.DataArray): The field (see `sample_field`). + start (datetime.datetime): The start of the period. + end (datetime.datetime): The end of the period. + name (str | None): The column of the sampled values, or `None` for the + field's name (or `"value"`). + targets (geopandas.GeoDataFrame | geopandas.GeoSeries | None): The + targets, including those not observed, or `None` for those + observed. + method (str): `"nearest"` or `"linear"`, for the field at the targets. + dimensions (Mapping[str, str] | None): The names of the field's + dimensions of `time`, `lat`, and `lon`, if not the defaults. + + Returns: + geopandas.GeoDataFrame: a row per target + """ + # pylint: disable=import-outside-toplevel + import xarray as xr + + name = name or field.name or "value" + dimensions = dict(dimensions or {}) + time_dim = _get_dimension(field, ["time"], dimensions.get("time")) + lat_dim = _get_dimension(field, ["lat", "latitude"], dimensions.get("lat")) + lon_dim = _get_dimension(field, ["lon", "longitude"], dimensions.get("lon")) + result = _get_targets(sampled, targets) + window = _field_times(field, time_dim, pd.Series([start, end])) + period = field.sel({time_dim: slice(window[0], window[1])}) + longitude, latitude = _get_points(result.geometry) + where = { + lat_dim: xr.DataArray(latitude, dims="target"), + lon_dim: xr.DataArray( + _field_longitudes(field, lon_dim, longitude), dims="target" + ), + } + at_targets = ( + period.sel(where, method="nearest") + if method == "nearest" + else period.interp(where) + ) + result["true_mean"] = at_targets.mean(dim=time_dim).to_numpy().astype(float) + groups = sampled.groupby("target_hash")[name] + result["samples"] = result["target_hash"].map(groups.count()).fillna(0).astype(int) + result["sampled_mean"] = result["target_hash"].map(groups.mean()).astype(float) + result["error"] = result["sampled_mean"] - result["true_mean"] + return result diff --git a/src/tatc/generation/points.py b/src/tatc/generation/points.py index 57cb77a..d387034 100644 --- a/src/tatc/generation/points.py +++ b/src/tatc/generation/points.py @@ -23,12 +23,17 @@ def generate_points_fibonacci_lattice( - distance: float, + distance: float | None = None, elevation: float = 0, mask: Polygon | MultiPolygon | None = None, + *, + count: int | None = None, + rotate: bool = False, + seed: int | np.random.Generator | None = None, ) -> gpd.GeoDataFrame: """ - Generates geodetic points following a Fibonacci lattice. + Generates geodetic points following a Fibonacci lattice, of points about + a `distance` apart, or of a `count` of points. See: Gonzalez (2010). "Measurement of areas on a sphere using Fibonacci and latitude-longitude lattices", Mathematical Geosciences 42(49). @@ -38,29 +43,70 @@ def generate_points_fibonacci_lattice( requires an odd number of points. This implementation allows any number of points. In agreement with Gonzalez, no points are placed at poles. + A lattice in a random orientation (`rotate`, drawn from `seed`) is a + stratified sample of the sphere (randomized quasi-Monte Carlo). Each + point is distributed uniformly by surface area, as are those of + `generate_points_random`, but the points cover the sphere evenly rather + than clustering by chance, so that statistics of samples of points (such + as the share of points sampled sufficiently, over the replicates of a + trade study) vary less between samples of the same size (with about 1.5 + to 4 times less variance for the shares of points that constellations + sample):: + + points = generate_points_fibonacci_lattice(count=100, rotate=True, seed=7) + + With a mask, a lattice of a `count` of points covers the sphere with + about `count` points inside the mask (from the mask's share of the + sphere's area), and the number of points inside varies slightly with the + orientation of a rotated lattice. + Args: - distance (float): The typical surface distance (meters) between points. + distance (float | None): The typical surface distance (meters) between + points, or `None` for a `count` of points. elevation (float): The elevation (meters) above the datum in the WGS 84 coordinate system. - mask (shapely.geometry.Polygon | shapely.geometry.MultiPolygon | None): An optional mask to constrain points - using WGS84 (EPSG:4326) geodetic coordinates in a Polygon or MultiPolygon. + mask (shapely.geometry.Polygon | shapely.geometry.MultiPolygon | None): + An optional mask to constrain points using WGS84 (EPSG:4326) + geodetic coordinates in a Polygon or MultiPolygon. + count (int | None): The number of points (about, with a mask), in + place of a `distance`. + rotate (bool): Whether to rotate the lattice into a random + orientation, uniform over the rotations of the sphere. + seed (int | numpy.random.Generator | None): An optional seed (or + generator) of the random orientation. Returns: geopandas.GeoDataFrame: the data frame of generated points, each identified by the hash of its geometry (`point_id`, see `tatc.utils.geometry.hash_geometry`) - """ - # determine the number of global samples to achieve average sample distance - samples = compute_number_samples(distance) + Raises: + ValueError: if neither or both of `distance` and `count` are given, + `count` is negative, a `seed` is given without `rotate`, or the + mask is not valid. + """ + if (distance is None) == (count is None): + raise ValueError("Give either a distance or a count of points.") + if seed is not None and not rotate: + raise ValueError("A seed draws a random orientation (rotate=True).") + if count is None: + # determine the number of global samples to achieve average sample distance + samples = compute_number_samples(distance) + elif count < 0: + raise ValueError(f"Count must not be negative, got {count}.") + else: + samples = count if mask is None else int(round(count / _share_of(mask))) index = np.arange(samples) - # compute latitudes, starting from the southern hemisphere and placing - # neither first nor last points at poles - latitudes = np.degrees(np.arcsin(2 * (index + 1) / (samples + 2) - 1)) - # compute longitudes on the interval [-180, 180] - phi = (1 + np.sqrt(5)) / 2 # golden ratio - longitudes = np.mod(360 * index / phi, 360) - longitudes = np.where(longitudes > 180, longitudes - 360, longitudes) + if rotate: + latitudes, longitudes = _rotated_lattice(index, np.random.default_rng(seed)) + else: + # compute latitudes, starting from the southern hemisphere and placing + # neither first nor last points at poles + latitudes = np.degrees(np.arcsin(2 * (index + 1) / (samples + 2) - 1)) + # compute longitudes on the interval [-180, 180] + phi = (1 + np.sqrt(5)) / 2 # golden ratio + longitudes = np.mod(360 * index / phi, 360) + longitudes = np.where(longitudes > 180, longitudes - 360, longitudes) if mask is not None: if isinstance(mask, (Polygon, MultiPolygon)): if not mask.is_valid: @@ -100,6 +146,73 @@ def generate_points_fibonacci_lattice( return gdf +def _random_rotation(rng: np.random.Generator) -> np.ndarray: + """ + Draws a rotation matrix uniformly over the rotations of a sphere (from a + uniform random unit quaternion, after Shoemake, 1992). + """ + u1, u2, u3 = rng.random(3) + x, y = np.sqrt(1 - u1) * np.sin(2 * np.pi * u2), np.sqrt(1 - u1) * np.cos( + 2 * np.pi * u2 + ) + z, w = np.sqrt(u1) * np.sin(2 * np.pi * u3), np.sqrt(u1) * np.cos(2 * np.pi * u3) + return np.array( + [ + [1 - 2 * (y * y + z * z), 2 * (x * y - z * w), 2 * (x * z + y * w)], + [2 * (x * y + z * w), 1 - 2 * (x * x + z * z), 2 * (y * z - x * w)], + [2 * (x * z - y * w), 2 * (y * z + x * w), 1 - 2 * (x * x + y * y)], + ] + ) + + +def _share_of(mask: Polygon | MultiPolygon) -> float: + """ + Gets a mask's share of the sphere, with its edges straight in longitude + and latitude (as clipped): its area in a cylindrical equal-area + projection (longitude and the sine of latitude, in radians) of the mask + with edges divided into short segments. + """ + if not isinstance(mask, (Polygon, MultiPolygon)) or not mask.is_valid: + raise ValueError("Mask is not a valid Polygon or MultiPolygon.") + dense = shapely.segmentize(mask, 0.5) + projected = shapely.transform( + dense, + lambda xy: np.column_stack( + [np.radians(xy[:, 0]), np.sin(np.radians(xy[:, 1]))] + ), + ) + share = projected.area / (4 * np.pi) + if share <= 0: + raise ValueError("Mask has no area.") + return min(share, 1.0) + + +def _rotated_lattice( + index: np.ndarray, rng: np.random.Generator +) -> tuple[np.ndarray, np.ndarray]: + """ + Gets the latitudes and longitudes (degrees) of the points of a Fibonacci + lattice (see `generate_points_fibonacci_lattice`) in a random + orientation. + """ + samples = len(index) + # the lattice as unit vectors + sin_latitude = 2 * (index + 1) / (samples + 2) - 1 + longitude = 2 * np.pi * index / ((1 + np.sqrt(5)) / 2) + cos_latitude = np.sqrt(1 - sin_latitude**2) + vectors = np.column_stack( + [ + cos_latitude * np.cos(longitude), + cos_latitude * np.sin(longitude), + sin_latitude, + ] + ) + vectors = vectors @ _random_rotation(rng).T + latitudes = np.degrees(np.arcsin(np.clip(vectors[:, 2], -1, 1))) + longitudes = np.degrees(np.arctan2(vectors[:, 1], vectors[:, 0])) + return latitudes, longitudes + + def generate_points_uniform_spacing( distance: float, elevation: float = 0, diff --git a/src/tatc/tradespace/__init__.py b/src/tatc/tradespace/__init__.py new file mode 100644 index 0000000..37b726c --- /dev/null +++ b/src/tatc/tradespace/__init__.py @@ -0,0 +1,201 @@ +""" +Trade space analysis of constellations. + +A trade study declares a design space (`DesignSpace`), evaluates its designs +in replicates that draw its uncertain parameters (`Study`, or +`ObservationStudy` for the observations, deployment, costs, and failures of +constellations) into results (a row per replicate), judges designs by +criteria (`Criteria`) on summaries of the results (`summarize`, a row per +design) and their Pareto efficiency (`pareto_front`), and settles the +uncertainty of its replicates (`refine`, `confirm`), or finds efficient +designs of spaces too large to enumerate (`screen`, `optimize_optuna`, +`optimize_pymoo`). + +This package exports the functions and classes of trade studies, and the +outcomes of their steps (such as `Refinement`), for type hints. The parts +from which they are made (such as the layouts of constellations, the +simulation of missions, and fingerprints) are in its modules. + +@author: Paul T. Grogan +""" + +from .attribution import Attribution, attribute_variance +from .cache import SatelliteCache +from .comparison import exceedance +from .confirmation import Confirmation, confirm +from .constellations import ( + build_constellation, + count_planes, + count_satellites, + layout_of, + mog_space, + planes_space, + soc_space, + sso_planes_space, + walker_space, +) +from .cost import ( + Component, + CostModel, + LaunchCost, + OperationsCost, + SatelliteCost, + Triangular, + risk_space, +) +from .criteria import Across, Criteria, Requirement +from .deployment import DeploymentSchedule, Stage +from .failures import ( + Bathtub, + Exponential, + FailureModel, + Piecewise, + RestorationPolicy, + Weibull, + policy_space, +) +from .nodes import ( + Categorical, + Choice, + Derived, + Fixed, + Infeasible, + Integer, + Real, + Repeat, + Uncertain, +) +from .observations import ObservationStudy, Observations, Targets +from .optimization import Search, optimize_optuna, optimize_pymoo +from .pareto import hypervolume, hypervolume_progress, pareto_front, pareto_ranks +from .plans import Failures, MissionPlan +from .plotting import ( + COLORS, + GRAY, + INK, + plot_designs, + plot_exceedance, + plot_means, + plot_progress, + plot_shares, + style_axes, + use_style, +) +from .references import configure, value_of +from .refinement import Refinement, refine +from .scenarios import robustness +from .screening import Screening, screen +from .sensitivity import main_effects, sensitivity +from .space import Design, DesignSpace +from .statistics import ( + Maximum, + Mean, + Minimum, + Probability, + Quantile, + StandardDeviation, + Statistic, +) +from .store import ResultStore +from .study import Study +from .summary import pareto_probability, summarize +from .utility import ExponentialUtility, LinearUtility, PiecewiseUtility, Utility + +__all__ = [ + # design spaces + "Categorical", + "Choice", + "Derived", + "Design", + "DesignSpace", + "Fixed", + "Infeasible", + "Integer", + "Real", + "Repeat", + "Uncertain", + "build_constellation", + "configure", + "count_planes", + "count_satellites", + "layout_of", + "mog_space", + "planes_space", + "policy_space", + "soc_space", + "sso_planes_space", + "value_of", + "walker_space", + # studies + "Bathtub", + "Component", + "CostModel", + "DeploymentSchedule", + "Exponential", + "FailureModel", + "Failures", + "LaunchCost", + "MissionPlan", + "ObservationStudy", + "Observations", + "OperationsCost", + "Piecewise", + "RestorationPolicy", + "ResultStore", + "SatelliteCache", + "SatelliteCost", + "Stage", + "Study", + "Targets", + "Triangular", + "Weibull", + "risk_space", + # criteria and summaries + "Across", + "Criteria", + "ExponentialUtility", + "LinearUtility", + "Maximum", + "Mean", + "Minimum", + "PiecewiseUtility", + "Probability", + "Quantile", + "Requirement", + "StandardDeviation", + "Statistic", + "Utility", + "exceedance", + "hypervolume", + "hypervolume_progress", + "main_effects", + "pareto_front", + "pareto_probability", + "pareto_ranks", + "robustness", + "sensitivity", + "summarize", + # refinement and searches + "Attribution", + "Confirmation", + "Refinement", + "Screening", + "Search", + "attribute_variance", + "confirm", + "optimize_optuna", + "optimize_pymoo", + "refine", + "screen", + # plots + "COLORS", + "GRAY", + "INK", + "plot_designs", + "plot_exceedance", + "plot_means", + "plot_progress", + "plot_shares", + "style_axes", + "use_style", +] diff --git a/src/tatc/tradespace/alerts.py b/src/tatc/tradespace/alerts.py new file mode 100644 index 0000000..a07a44e --- /dev/null +++ b/src/tatc/tradespace/alerts.py @@ -0,0 +1,38 @@ +""" +Warnings of trade studies, which point at the call into the trade space +module that leads to them (rather than at the module's own code), however +deep within the module they are given. + +@author: Paul T. Grogan +""" + +from __future__ import annotations + +import sys +import warnings + +_TRADESPACE = __name__.rpartition(".")[0] +"""The name of the package of trade studies, whose frames a warning skips.""" + + +def _warn(message: str, category: type[Warning] = UserWarning) -> None: + """ + Gives a warning at the first frame of the stack outside the package + (the user's call into it), as `warnings.warn` would with the stack level + of that frame. + + Args: + message (str): The message. + category (type[Warning]): The category of the warning. + """ + level, frame = 2, sys._getframe(1) # pylint: disable=protected-access + while frame is not None and _is_tradespace_module(frame.f_globals.get("__name__")): + frame, level = frame.f_back, level + 1 + warnings.warn(message, category, stacklevel=level) + + +def _is_tradespace_module(module: object) -> bool: + """Whether a module name is of the package of trade studies or its modules.""" + return isinstance(module, str) and ( + module == _TRADESPACE or module.startswith(_TRADESPACE + ".") + ) diff --git a/src/tatc/tradespace/attribution.py b/src/tatc/tradespace/attribution.py new file mode 100644 index 0000000..a282bb6 --- /dev/null +++ b/src/tatc/tradespace/attribution.py @@ -0,0 +1,611 @@ +""" +Attribution of the variance of the outcomes of designs to their uncertain +parameters: which uncertainties spread the outcomes of a design between its +replicates, found by drawing each again while holding the others. + +@author: Paul T. Grogan +""" + +from __future__ import annotations + +import warnings +from collections.abc import Mapping, Sequence +from dataclasses import dataclass, field +from itertools import combinations + +import numpy as np +import pandas as pd + +from .space import Design, DesignSpace, _designs +from .study import Study +from .tables import FEASIBLE, check_records, draw_resamples, feasible_records, names +from .values import generic_path + +_SHARES = ("first", "total") +"""The shares of variance of a parameter (see `attribute_variance`).""" + + +@dataclass +class Attribution: + """ + The attribution of the variance of the metrics of designs between their + replicates to their uncertain parameters (see `attribute_variance`): as + the outcomes of other steps of a trade study (see `Refinement`), its + `results`, its `summary` (of the shares of the parameters over every + design), and the `designs` attributed. + """ + + results: pd.DataFrame + """pandas.DataFrame: The results of every evaluation (see `Study.run`): + the plain replicates, and the mixed replicates, whose `redrawn` column + names the parameter (or group of parameters) drawn as in other + replicates (`None` for plain replicates). Those of differences (see + `differences`) are the differences of the metrics of two designs + (`design` less `other`) in each replicate.""" + shares: pd.DataFrame + """pandas.DataFrame: A row per design (and group of `by`), metric + (`metric`), and parameter (`parameter`): the variance of the metric + between the design's replicates (`variance`), the share of the variance + that knowing the parameter would remove (`first`), the share that the + parameter causes, alone or with others (`total`), and the standard + errors of the shares (`first se` and `total se`, by a bootstrap). Those + of differences (see `differences`) are of a pair of designs (`design` + and `other`).""" + designs: list[Design] = field(default_factory=list) + """list[Design]: The designs attributed (of differences, those of the + pairs).""" + by: tuple[str, ...] = () + """tuple[str, ...]: The columns that separate the records of an + evaluation (see `attribute_variance`).""" + _samples: dict[str, np.ndarray] = field(default_factory=dict, repr=False) + """dict[str, numpy.ndarray]: The variances that the parameter of each row + of `shares` explains (`first` and `total`), and the variance of the + metric (`variance`), in each resample of the bootstrap (a row per row of + `shares`, and a column per resample, of the same replicates for every + design), from which `summary` estimates the standard errors of shares + over designs.""" + _resamples: np.ndarray | None = field(default=None, repr=False) + """numpy.ndarray | None: The rows of A, B, and the mixed replicates in + each resample of the bootstrap (a row per resample), which `differences` + resamples too.""" + + @property + def summary(self) -> pd.DataFrame: + """pandas.DataFrame: The total shares of the variance of each metric + that each parameter causes, alone or with others, over every design + (see `summary_of`).""" + return self.summary_of("total") + + def summary_of(self, share: str = "total") -> pd.DataFrame: + """ + Gets the shares of the variance of each metric that each parameter + explains over every design (and for each group of `by`): the + variances that it explains, summed over the designs in which it is + drawn, as a share of their variances (a mean of the designs' shares, + weighted by their variances), with their standard errors (by the + bootstrap of the shares, whose resamples are of the same replicates + for every design). + + Args: + share (str): `"total"` for the shares that the parameters cause, + alone or with others, or `"first"` for the shares that knowing + them would remove. + + Returns: + pandas.DataFrame: a row per parameter (and group of `by`), and a + column per metric, then a column of the standard errors of + each (` se`) + """ + if share not in _SHARES: + raise ValueError(f"share must be 'first' or 'total', not {share!r}") + frame = self.shares + metrics = list(pd.unique(frame["metric"])) + columns = [*metrics, *(f"{metric} se" for metric in metrics)] + if frame.empty: + return pd.DataFrame(columns=columns) + index = [*self.by, "parameter"] + usable = (frame[share].notna() & frame["variance"].notna()).to_numpy() + explained = np.where(usable, frame[share] * frame["variance"], 0.0) + variance = np.where(usable, frame["variance"], 0.0) + sampled = np.where(usable[:, None], self._samples[share], np.nan) + sampled_variance = np.where(usable[:, None], self._samples["variance"], np.nan) + records = [] + with warnings.catch_warnings(): + # parameters drawn in no design, or without variance + warnings.simplefilter("ignore", RuntimeWarning) + groups = frame.groupby([*index, "metric"], sort=False).indices + for key, rows in groups.items(): + # the share in each resample, of the designs it is estimated for + known = ~np.isnan(sampled[rows]) & ~np.isnan(sampled_variance[rows]) + resampled = np.where(known, sampled[rows], 0).sum(axis=0) / np.where( + known, sampled_variance[rows], 0 + ).sum(axis=0) + records.append( + { + **dict(zip([*index, "metric"], key)), + "share": explained[rows].sum() / variance[rows].sum(), + "se": np.nanstd(resampled, ddof=1), + } + ) + table = pd.DataFrame(records) + result = pd.concat( + [ + table.pivot(index=index, columns="metric", values="share"), + table.pivot(index=index, columns="metric", values="se").add_suffix( + " se" + ), + ], + axis=1, + ).reindex(columns=columns) + result.columns.name = None + if not self.by: + result = result.reindex(index=list(pd.unique(frame["parameter"]))) + return result + + def differences( + self, pairs: Sequence[tuple[Design | str, Design | str]] | None = None + ) -> Attribution: + """ + Attributes the variance of the differences of the metrics between + pairs of designs (the first less the other, in the same replicates) + to the uncertain parameters, from the evaluations of the designs, + without evaluating them again: the plain and mixed replicates of both + designs are the same replicates, so that their differences are those + of the difference. + + With common random numbers (see `Design.realize`), the parameters that + act alike on both designs cancel in their difference, and those that + act differently remain: the parameters with large shares of the + variance of a difference are those whose noise keeps the order of + the designs unsettled (such as their order on a front, see + `pareto_probability`), which more replicates, or less of that noise, + would settle. A parameter may spread the metrics of both designs but + not their difference, such as the growth of a cost that both share. + Without common random numbers, nothing cancels: the variance of a + difference is the sum of the designs' variances. + + A design that does not draw a parameter (such as one of a branch it + does not choose) is not evaluated for it, as it does not depend on + it: its values with the parameter drawn again are those of A. The + shares of a parameter that neither design draws are `NaN`, and the + replicates in which either design is infeasible are left out. + + Args: + pairs (Sequence[tuple[Design | str, Design | str]] | None): The + pairs of designs (or their keys), or `None` for every pair of + the designs, in their order. + + Returns: + Attribution: the differences (`results`) and their shares, whose + rows give both designs (`design` and `other`) + + Raises: + ValueError: if a design of a pair is not attributed, or a pair is + of a design with itself. + """ + if "other" in self.shares.columns or self._resamples is None: + raise ValueError("differences need an attribution of designs") + designs = list(pd.unique(self.results["design"])) + pairs = list(combinations(designs, 2)) if pairs is None else pairs + keyed = [ + tuple(d.key if isinstance(d, Design) else d for d in pair) for pair in pairs + ] + unknown = sorted({key for pair in keyed for key in pair} - set(designs)) + if unknown: + raise ValueError(f"designs that are not attributed: {unknown}") + same = [a for a, b in keyed if a == b] + if same: + raise ValueError(f"pairs of a design with itself: {same}") + metrics = list(pd.unique(self.shares["metric"])) + parameters = list(pd.unique(self.shares["parameter"])) + n = self._resamples.shape[1] + tables = { + key: _tables(self.results, key, metrics, parameters, self.by) + for key in dict.fromkeys(key for pair in keyed for key in pair) + } + frames = [] + for first, other in keyed: + for name in [None, *parameters]: + a, b = tables[first].get(name), tables[other].get(name) + if a is None and b is None: + continue # neither design draws the parameter + # a design that does not draw a parameter is as in A + a = _first_replicates(tables[first][None], n) if a is None else a + b = _first_replicates(tables[other][None], n) if b is None else b + frames.append( + _difference(a, b, metrics).assign( + design=first, other=other, redrawn=name + ) + ) + columns = [*self.by, "replicate", *metrics, FEASIBLE] + differences = ( + pd.concat(frames, ignore_index=True) + if frames + else pd.DataFrame(columns=[*columns, "design", "other", "redrawn"]) + ) + shares, samples = _shares( + differences, + ("design", "other"), + keyed, + parameters, + metrics, + self.by, + self._resamples, + ) + paired = {key for pair in keyed for key in pair} + return Attribution( + results=differences, + shares=shares, + designs=[design for design in self.designs if design.key in paired], + by=self.by, + _samples=samples, + _resamples=self._resamples, + ) + + +def _groups_of( + space: DesignSpace, parameters: Sequence[str] | Mapping[str, Sequence[str]] | None +) -> dict[str, list[str]]: + """ + Gets the groups of uncertain parameters to attribute variance to, by + name: each parameter of the design space, each given parameter, or the + given groups of parameters. + """ + if not space.uncertain_paths(): + raise ValueError("the design space has no uncertain parameters") + if parameters is None: + groups = {path: [path] for path in space.uncertain_paths()} + elif isinstance(parameters, str): + groups = {parameters: [parameters]} + elif isinstance(parameters, Mapping): + groups = { + name: [paths] if isinstance(paths, str) else list(paths) + for name, paths in parameters.items() + } + else: + groups = {path: [path] for path in parameters} + if not groups: + raise ValueError("no parameters to attribute variance to") + paths = [path for group in groups.values() for path in group] + space._check_uncertain(paths) # pylint: disable=protected-access + repeated = sorted({path for path in paths if paths.count(path) > 1}) + if repeated: + raise ValueError(f"parameters in more than one group: {repeated}") + empty = [name for name, group in groups.items() if not group] + if empty: + raise ValueError(f"groups without parameters: {empty}") + return groups + + +def _draws(design: Design, paths: Sequence[str]) -> bool: + """ + Whether a design draws any of the uncertain parameters (by their paths, + see `DesignSpace.uncertain_paths`), which those of branches it does not + choose (or of the items of an empty repetition) it does not. + """ + drawn = {generic_path(path) for path in design.uncertain_values()} + return any(path in drawn for path in paths) + + +def _estimate( + plain: np.ndarray, + mixed: np.ndarray, + n: int, + resamples: np.ndarray, +) -> dict[str, np.ndarray]: + """ + Estimates the variance of a metric and the first and total shares of each + group of parameters, from the metric in the plain replicates (`2 n`: the + rows of A, then of B) and the mixed replicates of each group (a row per + group, of `n`: the rows of A with the group drawn as in B), which are + `NaN` where infeasible (or not evaluated), with the variances that the + groups explain and the variance in each resample of a bootstrap + (`resamples`, indices of rows, resamples x n), and the standard errors + of the shares. + + The estimators are Jansen's: the total effect of a group is half the + mean squared difference between A and its mixed replicates (which differ + in the group alone), and the first-order effect is the variance less + half the mean squared difference between B and the mixed replicates + (which share the group alone). + """ + a, b = plain[:n], plain[n:] + # the rows in which A, B, and the mixed replicates are all feasible + joint = ~np.isnan(a) & ~np.isnan(b) & ~np.isnan(mixed) + halves = { + "first": np.where(joint, (b - mixed) ** 2, np.nan) / 2, + "total": np.where(joint, (a - mixed) ** 2, np.nan) / 2, + } + values = plain[~np.isnan(plain)] + variance = float(np.var(values, ddof=1)) if len(values) > 1 else np.nan + # shares need a variance, and two rows feasible in every replicate + valid = (joint.sum(axis=1) >= 2) & (variance > 0) + estimates: dict = {"variance": variance} + with warnings.catch_warnings(): + # designs that are infeasible (or groups not drawn) give empty slices + warnings.simplefilter("ignore", RuntimeWarning) + both = np.concatenate([a[resamples], b[resamples]], axis=1) + sampled_variance = np.nanvar(both, axis=1, ddof=1) + sampled_variance = np.where(sampled_variance > 0, sampled_variance, np.nan) + estimates["variance samples"] = sampled_variance + for share, terms in halves.items(): + explained = np.nanmean(terms, axis=1) + sampled = np.nanmean(terms[:, resamples], axis=2) + if share == "first": + explained, sampled = variance - explained, sampled_variance - sampled + estimates[share] = np.where(valid, explained / variance, np.nan) + estimates[f"{share} samples"] = np.where(valid[:, None], sampled, np.nan) + estimates[f"{share} se"] = np.where( + valid, np.nanstd(sampled / sampled_variance, axis=1, ddof=1), np.nan + ) + return estimates + + +def _tables( + results: pd.DataFrame, + key: str, + metrics: Sequence[str], + parameters: Sequence[str], + by: Sequence[str], +) -> dict[str | None, pd.DataFrame]: + """ + Gets the metrics of a design (`NaN` where infeasible) and whether it is + feasible, by (the groups of `by` and) replicate: in its plain replicates + (`None`), and in its mixed replicates of each group of parameters it was + evaluated for. + """ + rows = results[results["design"] == key] + + def table(part: pd.DataFrame) -> pd.DataFrame: + indexed = part.set_index([*by, "replicate"]) + feasible = indexed[FEASIBLE].astype(bool).to_numpy() + # a copy, as pandas may give a read-only view of the frame + values = indexed.reindex(columns=list(metrics)).to_numpy(dtype=float, copy=True) + values[~feasible] = np.nan + frame = pd.DataFrame(values, index=indexed.index, columns=list(metrics)) + frame[FEASIBLE] = feasible + return frame + + tables: dict[str | None, pd.DataFrame] = {None: table(rows[rows["redrawn"].isna()])} + for name in parameters: + part = rows[rows["redrawn"] == name] + if len(part): + tables[name] = table(part) + return tables + + +def _first_replicates(table: pd.DataFrame, n: int) -> pd.DataFrame: + """ + Gets the rows of a table (see `_tables`) of the first `n` replicates (A). + """ + return table[table.index.get_level_values("replicate") < n] + + +def _difference( + a: pd.DataFrame, b: pd.DataFrame, metrics: Sequence[str] +) -> pd.DataFrame: + """ + Gets the differences of the metrics of two tables (see `_tables`) in the + same rows, which are feasible if both are. + """ + index = a.index.union(b.index) + difference = a.reindex(index)[list(metrics)] - b.reindex(index)[list(metrics)] + difference[FEASIBLE] = a[FEASIBLE].reindex(index, fill_value=False) & b[ + FEASIBLE + ].reindex(index, fill_value=False) + return difference.reset_index() + + +def _by_replicate( + group: pd.DataFrame, metric: str, rows: pd.Series, size: int +) -> np.ndarray: + """ + Gets a metric of the rows of a group of results in the order of their + replicates, up to `size` (`NaN` where a replicate is missing). + """ + values = group.loc[rows, metric].astype(float) + return values.set_axis(group.loc[rows, "replicate"]).reindex(range(size)).to_numpy() + + +def _shares( + results: pd.DataFrame, + identity: Sequence[str], + keys: Sequence[tuple], + parameters: Sequence[str], + metrics: Sequence[str], + by: Sequence[str], + resamples: np.ndarray, +) -> tuple[pd.DataFrame, dict[str, np.ndarray]]: + """ + Estimates the shares of the variance of each metric of each design (or + pair of designs, by the values of the `identity` columns of the results + in `keys`, and of each group of `by`) of each group of parameters (see + `attribute_variance`), with a bootstrap of the resamples of the rows of + A, B, and the mixed replicates (`resamples x n`), whose samples it also + returns (see `Attribution._samples`). + """ + n = resamples.shape[1] + feasible = feasible_records(results)[0] + grouped = { + key if isinstance(key, tuple) else (key,): group + for key, group in feasible.groupby(list(identity), sort=False) + } + rows = [] + samples: dict[str, list] = {"first": [], "total": [], "variance": []} + for key in keys: + if key not in grouped: + continue # infeasible in every replicate + records = grouped[key] + separated = records.groupby(list(by), sort=False) if by else [((), records)] + for values, group in separated: + labels = dict(zip(by, values if isinstance(values, tuple) else (values,))) + redrawn = group["redrawn"] + for metric in (metric for metric in metrics if metric in group.columns): + estimates = _estimate( + _by_replicate(group, metric, redrawn.isna(), 2 * n), + np.array( + [ + _by_replicate(group, metric, redrawn == name, n) + for name in parameters + ] + ), + n, + resamples, + ) + rows.extend( + { + **dict(zip(identity, key)), + **labels, + "metric": metric, + "parameter": name, + "variance": estimates["variance"], + **{ + share: estimates[share][i] + for share in ("first", "total", "first se", "total se") + }, + } + for i, name in enumerate(parameters) + ) + for share in _SHARES: + samples[share].extend(estimates[f"{share} samples"]) + samples["variance"].extend( + [estimates["variance samples"]] * len(parameters) + ) + columns = [*identity, *by, "metric", "parameter", "variance"] + shares = pd.DataFrame( + rows, columns=[*columns, "first", "total", "first se", "total se"] + ) + return shares, { + name: np.array(arrays, dtype=float).reshape(len(shares), len(resamples)) + for name, arrays in samples.items() + } + + +def attribute_variance( + study: Study, + metrics: str | Sequence[str], + designs: Sequence[Design] | pd.DataFrame, + *, + parameters: Sequence[str] | Mapping[str, Sequence[str]] | None = None, + sample_size: int | None = None, + by: str | Sequence[str] = (), + n_resamples: int = 500, + seed: int = 0, +) -> Attribution: + """ + Attributes the variance of metrics between the replicates of each design + to its uncertain parameters (see `Uncertain`): which uncertainties spread + its outcomes, and by how much. For example, the spread of a share of + points sampled between replicates may be noise of the sample of points + (which more points would reduce), and that of a cost, a risk of the + growth of the cost. + + The effect of a parameter is measured by drawing it again while holding + the others (a pick-freeze design, as of Sobol' indices), as its values + need not relate to the outcomes in any order (as those of a seed do + not). The designs are evaluated in `2 n` plain replicates (`n` the + `sample_size`): A, the first `n`, and B, the next `n` (those evaluated + before are taken from the study's store). For each parameter (or group + of parameters), they are also evaluated in `n` mixed replicates: those + of A, with the parameter drawn as in B (see `Study.run`'s `shift`), which + takes `n` evaluations of each design for each parameter. + + Two shares of the variance of a metric are estimated for each parameter, + by Jansen's estimators (with common random numbers, the designs share + the parameters of each replicate): + + * `total`: the share that the parameter causes, alone or with others + (half the mean squared difference between A and the mixed replicates, + which differ in the parameter alone, as a share of the variance). A + parameter whose total share is near 0 could be fixed at any value + without changing the spread of the metric. + * `first`: the share that knowing the parameter would remove (the + variance less half the mean squared difference between B and the + mixed replicates, which share the parameter alone, as a share of the + variance). The first shares of the parameters sum to at most 1; the + rest is caused by the parameters together (their interactions). + + The shares are of the variance of a replicate, and so also of the + variance of a mean of replicates. They are not clipped (an estimate of a + share near 0 may be slightly negative), and their standard errors are + estimated by a bootstrap of the rows of A, B, and the mixed replicates + together. A share is `NaN` if the metric does not vary between the + design's replicates, if the design does not draw the parameter (such as + one of a branch it does not choose, which it is not evaluated for), or + if fewer than two rows are feasible in A, B, and the mixed replicates. + Infeasible evaluations are left out (and designs infeasible in every + replicate have no shares). + + The evaluations must be determined by the uncertain parameters (as a + study's store assumes): randomness from another source (such as a + generator that is not seeded by a parameter, see `Uncertain.seed`) adds + to the total share of every parameter. + + Args: + study (Study): The study that evaluates designs. + metrics (str | Sequence[str]): The metric (or metrics), columns of the + results. + designs (Sequence[Design] | pandas.DataFrame): The designs, or a data + frame of their values (such as rows of a summary that keeps them, + see `DesignSpace.designs_of`). + parameters (Sequence[str] | Mapping[str, Sequence[str]] | None): The + uncertain parameters to attribute variance to (by their paths, + see `DesignSpace.uncertain_paths`), groups of them (by name), or + `None` for each of the design space's. Parameters not given vary + between replicates, but are not attributed variance. + sample_size (int | None): The replicates of each of A and B (`n`), + or `None` for the study's replicates. + by (str | Sequence[str]): The columns that separate the records of an + evaluation, if it has several (such as a sensor). + n_resamples (int): The number of resamples of the bootstrap. + seed (int): The seed of the bootstrap. + + Returns: + Attribution: the results, and the shares of each design, metric, and + parameter + """ + n = study.replicates if sample_size is None else int(sample_size) + if n < 2: + raise ValueError("sample_size must be at least 2") + drawn = draw_resamples(n, n_resamples, seed) + groups = _groups_of(study.space, parameters) + metrics, by = names(metrics), tuple(names(by)) + unique = _designs(study.space, designs) + plain = study.run(unique, replicate_indices=range(2 * n)) + missing = [column for column in (*metrics, *by) if column not in plain.columns] + if missing and plain[FEASIBLE].any(): + raise ValueError(f"columns that are not in the results: {missing}") + if not missing: + check_records( + plain, + ["design", *by, "replicate"], + "give the columns that separate them as `by`", + metrics, + ) + frames = [plain.assign(redrawn=None)] + for name, paths in groups.items(): + drawing = [design for design in unique if _draws(design, paths)] + if drawing: + mixed = study.run( + drawing, replicate_indices=range(n), shift={path: n for path in paths} + ) + frames.append(mixed.assign(redrawn=name)) + results = pd.concat(frames, ignore_index=True) + + shares, samples = _shares( + results, + ("design",), + [(design.key,) for design in unique], + list(groups), + metrics, + by, + drawn, + ) + return Attribution( + results=results, + shares=shares, + designs=unique, + by=by, + _samples=samples, + _resamples=drawn, + ) diff --git a/src/tatc/tradespace/cache.py b/src/tatc/tradespace/cache.py new file mode 100644 index 0000000..2859ba0 --- /dev/null +++ b/src/tatc/tradespace/cache.py @@ -0,0 +1,367 @@ +""" +Caches of analyses by satellite, which designs of a trade study share. + +Most analyses of a constellation (such as `tatc.analysis.collect_observations` +or `tatc.analysis.collect_feature_observations`) compute the result of each +satellite independently of the others, then combine them. Designs in a +trade study often share satellites (the same orbit and instruments, if not +the same name), so caching the result of each satellite avoids computing it +again for every design that flies it. + +@author: Paul T. Grogan +""" + +from __future__ import annotations + +import json +import os +import pickle +import shutil +import tempfile +import time +from collections.abc import Callable, Iterable +from pathlib import Path +from typing import Any + +import pandas as pd + +from ..schemas import Satellite +from .fingerprint import _find_stale, _fingerprint_of, get_definition, warn_stale +from .hashing import canonical, digest +from .memory import Forgetful +from .store import _decode, _encode + + +def _write(path: Path, data: bytes, replace: bool = False) -> None: + """ + Writes a file (if it does not exist, or to `replace` it) through a + temporary file that is renamed, so that a parallel worker never reads a + partial file. + """ + if path.exists() and not replace: + return + descriptor, temporary = tempfile.mkstemp(dir=path.parent, suffix=".tmp") + with os.fdopen(descriptor, "wb") as file: + file.write(data) + try: + os.replace(temporary, path) + except PermissionError: + # on Windows, another worker is replacing or reading the file, which + # then holds the same content + os.remove(temporary) + if not path.exists(): + raise + + +def _read_definition(folder: Path) -> dict | None: + """Reads the definition of the results of a folder (`None` if unreadable).""" + try: + return json.loads((folder / "definition.json").read_text()) + except (OSError, ValueError): + return None + + +def get_satellite_key(satellite: Satellite) -> str: + """ + Gets a key of a satellite's content: its orbit, instruments, and + attitude, but not its name, so that satellites that differ only in their + names share a key. + + Args: + satellite (Satellite): The satellite. + + Returns: + str: the key + """ + data = satellite.model_dump(mode="json", exclude={"name"}) + return digest(canonical({"type": type(satellite).__name__, **data})) + + +class SatelliteCache(Forgetful): + """ + A cache of an analysis of single satellites, keyed by their content (see + `get_satellite_key`), in memory and optionally on disk. + + The function computes the result of one satellite, with every other + argument fixed (for example, by a closure over the targets and the + analysis period): the cache assumes that its result depends on nothing + else. A result that is a data frame with a `satellite` column is + relabeled with the name of the satellite it is retrieved for. + + A cache on disk (`directory`) persists between sessions and is shared by + the parallel workers of a trade study (see `Study`), each of which + otherwise has its own cache in memory. Results in the directory are keyed + by the fingerprint of the function (its code, the values it closes over + or refers to, such as data frames of targets, by their content, and the + source of the modules of TAT-C it depends on, see `get_definition`), by + a `namespace`, which must identify what the fingerprint cannot see (data + the function reads, such as from files, and the code of other modules it + calls, other than TAT-C's: change it whenever these change), and by the + satellite, in a folder of each namespace (by a hash of it, with the + namespace in `namespace.txt`, and a `context` that describes it in + `context.json`), and in it a folder of each fingerprint (with the + definition in `definition.json`). + + A cache warns if its namespace has results only of the same function + with other code (of the function, of TAT-C, or of Python: the same values + but for code, as a study warns of its store, see `Study`), which it does + not reuse, with the differences from the latest (see + `compare_definitions`), and removes them with `prune` (see + `Observations.prune` for the caches of the observations of a study). A + result that cannot be read (such as one written with other versions of + the libraries of its data) is computed again. + + Args: + function (Callable): The analysis of one satellite. + directory (str | os.PathLike | None): A directory in which to store + results, or `None` to keep them in memory only. + namespace (str): An identifier of the analysis (of what the + fingerprint of the function cannot see). + context (Any): A description of the namespace, such as the values + from which it is made (as of the caches of `Observations`, which + find their namespaces by it), kept on disk beside its results: + JSON data, or values that `ResultStore` encodes (such as tuples + and datetimes), or `None` for none. + """ + + _forgotten = ("_memory", "_unreadable") # (copies sent to parallel workers) + + def __init__( + self, + function: Callable[[Satellite], Any], + *, + directory: str | os.PathLike | None = None, + namespace: str = "", + context: Any = None, + ): + self.function = function + self.directory = None if directory is None else Path(directory) + self.namespace = namespace + self.fingerprint = "" + """str: The fingerprint of the function, which keys results on disk.""" + self.hits = 0 + """int: The number of results retrieved from the cache.""" + self.misses = 0 + """int: The number of results computed.""" + self._memory: dict[str, Any] = {} + self._unreadable: set[str] = set() + self._folder: Path | None = None + self._definition: dict | None = None + if self.directory is not None: + definition = get_definition(function=function) + self.fingerprint = _fingerprint_of(definition) + space = digest(namespace, 16) + self._folder = self.directory / space / self.fingerprint + self._folder.mkdir(parents=True, exist_ok=True) + _write(self._folder.parent / "namespace.txt", namespace.encode()) + if context is not None: + data = json.dumps(_encode(context)).encode() + _write(self._folder.parent / "context.json", data) + _write(self._folder / "definition.json", canonical(definition).encode()) + self._definition = definition + self._warn_other_definitions() + + @staticmethod + def _contexts(directory: str | os.PathLike) -> dict[str, Any]: + """ + Gets the namespaces of the results in a directory (of the caches that + share it) and their contexts (`None` if one has none, or if it cannot + be read), such as to find the caches of a set of observations (see + `Observations.prune`). + """ + directory = Path(directory) + if not directory.is_dir(): + return {} + contexts = {} + for folder in directory.iterdir(): + try: + namespace = (folder / "namespace.txt").read_text(encoding="utf-8") + except OSError: + continue + try: + context = _decode(json.loads((folder / "context.json").read_text())) + except Exception: # pylint: disable=broad-exception-caught + # none, or unreadable (such as pickled by other libraries) + context = None + contexts[namespace] = context + return contexts + + @property + def folder(self) -> Path | None: + """pathlib.Path | None: The folder of the results of the function's + definition on disk (in the folder of its namespace), if any.""" + return self._folder + + def __fingerprint__(self) -> dict: + """ + Gets what identifies the cache in a definition (see + `tatc.tradespace.fingerprint`), such as of a cache that a function of + a study refers to: its function and namespace, which identify its + results (not its directory, nor its counts of hits and misses, nor + the results it holds). + + Returns: + dict: the function and namespace + """ + return {"function": self.function, "namespace": self.namespace} + + def _stale(self) -> dict[Path, int]: + """ + Gets the folders of the results of the namespace by the function with + other code (the same values but for code, see `_find_stale`), the + latest first, and their numbers of results (including folders of + definitions without results). + """ + folders = [ + folder + for folder in self._folder.parent.iterdir() + if folder.is_dir() and folder != self._folder + ] + folders.sort(key=lambda folder: folder.stat().st_mtime, reverse=True) + others = {folder: _read_definition(folder) for folder in folders} + return _find_stale( + self._definition, + others, + lambda folder: sum(1 for _ in folder.glob("*.pkl")), + ) + + def _warn_other_definitions(self) -> None: + """ + Warns if the namespace has results only of the function with other + code (see `_stale`), with the differences from the latest, once (of + the caches of the definition, such as those of parallel workers). + """ + if next(self._folder.glob("*.pkl"), None) is not None: + return + + def first() -> bool: + # the first cache of the definition to warn marks its folder + try: + with open(self._folder / "warned", "x", encoding="utf-8"): + return True + except FileExistsError: + return False + + warn_stale( + self._stale(), + self._definition, + _read_definition, + lambda count: f"the cache in {self.directory} has {count} results of " + + f"namespace {self.namespace!r} by its function", + "prune removes them: Observations.prune for the observations of a study", + once=first, + ) + + def prune(self) -> int: + """ + Removes the results on disk of the namespace by the function with + other code (the same values but for code, of which the cache warns, + see `SatelliteCache`), and not those of other functions (such as of + other targets) that share the namespace. + + Returns: + int: the number of results removed + """ + if self._folder is None: + return 0 + stale = self._stale() + for folder in stale: + shutil.rmtree(folder, ignore_errors=True) + return sum(stale.values()) + + def _path(self, key: str) -> Path: + return self._folder / f"{key}.pkl" + + def _load(self, key: str) -> Any: + if key in self._memory: + return self._memory[key] + if self._folder is not None: + path = self._path(key) + for attempt in range(5): + if not path.exists(): + break + try: + with open(path, "rb") as file: + result = pickle.load(file) + except (OSError, EOFError, pickle.UnpicklingError): + # on Windows, another worker may be replacing the file: + # try again, then compute the result instead + time.sleep(0.02 * (attempt + 1)) + continue + except Exception: # pylint: disable=broad-exception-caught + # written with other versions of the libraries of its data + break + self._memory[key] = result + return result + if path.exists(): + self._unreadable.add(key) + raise KeyError(key) + + def _store(self, key: str, result: Any) -> None: + self._memory[key] = result + if self._folder is None: + return + path = self._path(key) + if path.exists() and key not in self._unreadable: + # another worker stored the (same) result + return + self._unreadable.discard(key) + _write(path, pickle.dumps(result), replace=True) + + def _get(self, satellite: Satellite) -> Any: + """ + Gets the result of a satellite, computing it if it is not cached. + """ + key = get_satellite_key(satellite) + try: + result = self._load(key) + self.hits += 1 + except KeyError: + result = self.function(satellite) + self.misses += 1 + self._store(key, result) + if isinstance(result, pd.DataFrame) and "satellite" in result.columns: + if len(result) > 0 and (result["satellite"] != satellite.name).any(): + result = result.copy() + result["satellite"] = satellite.name + return result + + def __call__(self, satellites: Satellite | Iterable[Satellite]) -> Any: + """ + Gets the results of satellites (or of a satellite), each computed if + it is not cached: concatenated if they are data frames (or the list + of results otherwise), or an empty data frame if there are no + satellites. + + Args: + satellites (Satellite | Iterable[Satellite]): The satellites. + + Returns: + Any: the concatenated data frame, or the list of results + """ + if isinstance(satellites, Satellite): + satellites = [satellites] + results = [self._get(satellite) for satellite in satellites] + if not results: + # no satellites (such as if all fail): an empty frame + return pd.DataFrame() + if all(isinstance(result, pd.DataFrame) for result in results): + non_empty = [result for result in results if len(result) > 0] + if not non_empty: + return results[0] + return pd.concat(non_empty, ignore_index=True) + return results + + def clear_memory(self) -> None: + """ + Clears the cache in memory and its statistics (not the results on + disk, which `prune` removes of other definitions). + """ + self._memory.clear() + self.hits = self.misses = 0 + + def __repr__(self) -> str: + return ( + f"SatelliteCache({len(self._memory)} results, " + + f"{self.hits} hits, {self.misses} misses)" + ) diff --git a/src/tatc/tradespace/comparison.py b/src/tatc/tradespace/comparison.py new file mode 100644 index 0000000..bf5337e --- /dev/null +++ b/src/tatc/tradespace/comparison.py @@ -0,0 +1,151 @@ +""" +Comparisons of designs by the replicates of a metric: the probability that +the metric of one design exceeds that of another in the same replicate, for +every pair of designs (such as the probability that one design costs more +than another). + +With common random numbers (see `Design.realize`), designs share the draws +of their uncertain parameters in each replicate, so that their metrics are +correlated by what they share (such as the growth of the cost of a +component that both carry, see `CostModel.draw`): the order of two designs +may then be settled although the metric of each spreads over the replicates +by more than they differ, as the noise that they share cancels in their +difference. Comparisons of the spreads of designs (such as their quantiles) +cannot see this, and judge the order of such designs unsettled. + +@author: Paul T. Grogan +""" + +from __future__ import annotations + +from collections.abc import Iterable, Sequence + +import numpy as np +import pandas as pd + +from .space import Design, _keys_of +from .tables import feasible_records, groups, matrices, names + + +def exceedance( + results: pd.DataFrame, + metric: str, + designs: Iterable[Design | str] | pd.DataFrame | None = None, + *, + by: Sequence[str] | str = (), +) -> pd.DataFrame: + """ + Estimates the probability that a metric of each design exceeds that of + each other design (and of itself) in the same replicate, from the + replicates in which both are feasible: the share of these replicates in + which it is greater, counting ties as half, so that the probabilities of + a pair and of its reverse add to 1 (and that of a design with itself is + 0.5). A probability near 0 or 1 is an order of the pair that the + replicates settle, and one near 0.5 an order that they do not:: + + results = study.run(designs) + compared = exceedance(results, "cost") + plot_exceedance(compared) + + With common random numbers (see `Design.realize`), the replicates of + designs share the draws of their uncertain parameters, and the + probability is that of the order of the designs given what they share + (such as the growth of the cost of a component that both carry, see + `CostModel.draw`). Without them, the draws are independent, and the + probability is that of the order of independent outcomes of the designs. + + Args: + results (pandas.DataFrame): The results of a study (see + `Study.run`), with a record per replicate of each design (and + group of `by`). Infeasible results, and those whose metric is + missing (`NaN`), are ignored. + metric (str): The metric. + designs (Iterable[Design | str] | pandas.DataFrame | None): The + designs (or their keys, or a data frame of them, such as a + summary), in order, or `None` for every design of the results + (of each group), by the mean of the metric (least first, and + those without a feasible result last). + by (Sequence[str] | str): The columns of groups of the results (such + as `scenario`) in which designs are compared separately. + + Returns: + pandas.DataFrame: a row per ordered pair of designs (and group), in + the order of the designs: the `design` and the `other`, the + columns of the group, the mean difference of the metric (the + design's less the other's, ` difference`), the + probability that the design's metric exceeds the other's + (`exceedance`), and the number of replicates in which both are + feasible (`shared_replicates`) + + Raises: + ValueError: if the results lack the metric or a design, or have + several records of a design in a replicate (of a group). + """ + by = tuple(names(by)) + if metric not in results.columns: + raise ValueError(f"no metric {metric!r} in the results") + keys = None if designs is None else _keys_of(designs) + if keys is not None: + present = set(results["design"]) + missing = [key for key in keys if key not in present] + if missing: + raise ValueError(f"no results of designs {missing[:5]}") + frames = [] + for group_key, positions in groups(results, by): + group = results.iloc[positions] + index = pd.Index(group["design"].unique() if keys is None else keys) + if index.empty: + continue + group = feasible_records(group)[0] + values = matrices( + group, [metric], index, hint="give the columns that separate them as `by`" + )[2][metric] + valid = ~np.isnan(values) + if keys is None: + # by the mean of the metric, designs without feasible results last + with np.errstate(invalid="ignore", divide="ignore"): + means = np.where(valid, values, 0.0).sum(axis=1) / valid.sum(axis=1) + order = np.argsort(means, kind="stable") + index, values, valid = index[order], values[order], valid[order] + parts: dict[str, list[np.ndarray]] = { + "design": [], + "other": [], + "difference": [], + "exceedance": [], + "shared_replicates": [], + } + for i, design in enumerate(index): + both = valid[i] & valid + counts = both.sum(axis=1) + greater = (both & (values[i] > values)).sum(axis=1) + ties = (both & (values[i] == values)).sum(axis=1) + with np.errstate(invalid="ignore", divide="ignore"): + difference = np.where(both, values[i] - values, 0.0) + parts["difference"].append(difference.sum(axis=1) / counts) + parts["exceedance"].append((greater + 0.5 * ties) / counts) + parts["design"].append(np.full(len(index), design, dtype=object)) + parts["other"].append(np.asarray(index, dtype=object)) + parts["shared_replicates"].append(counts) + frame = pd.DataFrame( + { + "design": np.concatenate(parts["design"]), + "other": np.concatenate(parts["other"]), + **dict(zip(by, group_key)), + f"{metric} difference": np.concatenate(parts["difference"]), + "exceedance": np.concatenate(parts["exceedance"]), + "shared_replicates": np.concatenate(parts["shared_replicates"]), + } + ) + frames.append(frame) + if not frames: + return pd.DataFrame( + columns=[ + "design", + "other", + *by, + f"{metric} difference", + "exceedance", + "shared_replicates", + ] + ) + return pd.concat(frames, ignore_index=True) diff --git a/src/tatc/tradespace/confirmation.py b/src/tatc/tradespace/confirmation.py new file mode 100644 index 0000000..5b0ea95 --- /dev/null +++ b/src/tatc/tradespace/confirmation.py @@ -0,0 +1,178 @@ +""" +Confirmation of selected designs with replicates that did not select them, +which removes the optimism of selection (the winner's curse). + +@author: Paul T. Grogan +""" + +from __future__ import annotations + +from collections.abc import Mapping, Sequence +from dataclasses import dataclass + +import numpy as np +import pandas as pd + +from .criteria import Criteria, _as_criteria +from .space import Design, _designs +from .study import Study +from .summary import _summarize +from .tables import FEASIBLE, JUDGMENT, efficient_keys + + +@dataclass +class Confirmation: + """ + The outcome of a confirmation (see `confirm`): as the outcomes of other + steps of a trade study (see `Refinement`), its `results`, the `summary` + of its designs, the `designs` it selects for a next step (those it + confirmed), and its `criteria`. Its results are only those of the new + replicates, which judge the designs without the optimism of their + selection: the designs still efficient by them are those of + `summary.pareto`. + """ + + results: pd.DataFrame + """pandas.DataFrame: The results of the new replicates (see `Study.run`), + which do not include those that selected the designs.""" + summary: pd.DataFrame + """pandas.DataFrame: A row per design (and group): the values of the + design, the statistics of the criteria by the new replicates (each mean + followed by its spread, ` std` and ` se`, as + `summarize` gives them), those of the replicates that selected the + design (` selected`), the optimism of the selection in each + objective (` optimism`: by + how much the selecting replicates made the design look better than the + new replicates do, in its units, positive if they did), the number of + new feasible `replicates`, the share of the new replicates that are + `feasible`, the `violation` of the requirements, and whether the design + meets them (`meets_requirements`) and is efficient among the confirmed + designs that do (`pareto`), by the new replicates.""" + designs: list[Design] + """list[Design]: The confirmed designs (every design evaluated with new + replicates).""" + criteria: Criteria + """Criteria: The criteria of the confirmation.""" + + @property + def optimism(self) -> pd.Series: + """pandas.Series: The optimism of selection: the mean over the designs + of their optimism in each objective of the criteria (see + `summary`), in its units, positive if the selecting replicates made + them look better (`NaN` without designs).""" + return pd.Series( + { + name: _mean(self.summary[f"{name} optimism"]) + for name in self.criteria.objectives + }, + dtype=float, + ) + + +def _mean(values: pd.Series) -> float: + """Gets the mean of the known values (`NaN` without any).""" + known = values.to_numpy(dtype=float) + known = known[~np.isnan(known)] + return float(known.mean()) if len(known) else float("nan") + + +def confirm( + study: Study, + criteria: Criteria | Mapping[str, str], + results: pd.DataFrame, + designs: Sequence[Design | str] | pd.DataFrame | None = None, + *, + replicates: int | None = None, +) -> Confirmation: + """ + Confirms selected designs (by default, the Pareto front of the results, + or the designs that another step selects, such as the efficient designs + of a refinement or a search, see `Refinement.designs`) with new + replicates. + + Designs selected for their outcomes in some replicates are selected in + part for the luck of those replicates: among many designs, the best + looking are likely to have drawn favorable uncertain parameters, so + their statistics in the replicates that selected them are optimistic + (the winner's curse), even if each design's statistics are unbiased + before selection. Replicates that played no part in the selection give + unbiased statistics of the selected designs. They are the replicates + after every replicate of the `results` (of any design), the same for + every design, so that common random numbers still pair the designs (see + `Design.realize`). + + Args: + study (Study): The study that evaluates designs. + criteria (Criteria | Mapping[str, str]): The criteria (see + `Criteria`), or the objectives (metrics whose means they are) + and their directions (`"min"` or `"max"`). + results (pandas.DataFrame): Every result that informed the selection + (see `Study.run`), such as those of an enumeration, refinement, + or search. + designs (Sequence[Design | str] | pandas.DataFrame | None): The + selected designs (designs, their keys, or a data frame of them, + such as rows of a summary, or the `designs` of another step), + or `None` for those efficient by + the criteria over every replicate of the results (see + `summarize` and `pareto_front`). + replicates (int | None): The number of new replicates, or `None` for + the study's number. + + Returns: + Confirmation: the new results, the summary of each design, and the + designs + """ + criteria = _as_criteria(criteria) + count = study.replicates if replicates is None else replicates + if count < 1: + raise ValueError("replicates must be at least 1") + if designs is None: + designs = efficient_keys(_summarize(results, criteria, design_values=False)) + designs = _designs(study.space, designs, results) + keys = {design.key for design in designs} + start = int(results["replicate"].max()) + 1 if len(results) > 0 else 0 + fresh = study.run(designs, replicate_indices=range(start, start + count)) + names = [name for name in criteria.names if name != FEASIBLE] + columns = ["design", *criteria.by] + confirmed = _summarize(fresh, criteria, spread=True) + # the spreads of the means by the new replicates, after each statistic + spreads = { + name: [ + column + for column in (f"{name} std", f"{name} se") + if column in confirmed.columns and column not in names + ] + for name in names + } + selected = _summarize( + results[results["design"].isin(keys)], criteria, design_values=False + )[[*columns, *names]] + summary = confirmed.merge( + selected.rename(columns={name: f"{name} selected" for name in names}), + on=columns, + how="left", + ) + for name, direction in criteria.objectives.items(): + sign = 1.0 if direction == "max" else -1.0 + summary[f"{name} optimism"] = sign * ( + summary[f"{name} selected"] - summary[name] + ) + status = ["replicates", FEASIBLE, *JUDGMENT] + statistics = [ + column + for name in names + for column in (name, *spreads[name], f"{name} selected") + ] + values = [c for c in confirmed.columns if c not in {*columns, *statistics, *status}] + summary = summary[ + [ + *columns, + *values, + *statistics, + *(f"{name} optimism" for name in criteria.objectives), + *status, + ] + ] + return Confirmation( + results=fresh, summary=summary, designs=designs, criteria=criteria + ) diff --git a/src/tatc/tradespace/constellations.py b/src/tatc/tradespace/constellations.py new file mode 100644 index 0000000..b6e4c0a --- /dev/null +++ b/src/tatc/tradespace/constellations.py @@ -0,0 +1,1302 @@ +""" +Building blocks of trade studies of constellations: fragments of design +spaces for common constellation layouts (Walker constellations, planes of +sun-synchronous orbits, and planes of inclined orbits, whose satellites are +evenly spaced or follow each other in trains, streets-of-coverage +constellations, and mutual orbiting groups), a builder of the satellites of +a layout (or of several, such as the shells of a mixed constellation) with a +payload (instruments, or entries of the instrument catalog), and counts of +satellites and planes for objectives and constraints. + +The fragments share the names of their values: `planes` is the planes, +their number (of Walker and streets-of-coverage constellations) or a +repetition of them (of planes of sun-synchronous or inclined orbits), whose +`count` is their number; `per_plane` is the number of satellites in each +plane, and `satellites` the number of satellites of a layout without planes +(a mutual orbiting group); `inclination`, `node` (the right ascension of the +ascending node), and `true_anomaly` are in degrees, and `phase_fraction` and +`node_fraction` are fractions of the intervals over which the phase and +node give distinct layouts. + +A fragment is a `DesignSpace` to place in a larger design space, for example +as a branch of a `Choice` between layouts:: + + space = DesignSpace( + altitude=Real(500e3, 800e3, step=100e3), + sounder=Categorical(["atms", "cris"]), + layout=Choice( + walker=walker_space(inclination=Real(45, 75, step=15)), + sso=sso_planes_space(), + ), + ) + + def build(d): + return build_constellation( + d.layout, d.sounder, epoch=START, altitude=d.altitude + ) + +A mixed constellation combines layouts, such as an inclined Walker +constellation and planes of sun-synchronous orbits (each layout a child of +the design space, or the items of a `Repeat` of a `Choice` of layouts), whose +satellites `build_constellation` builds together. + +The values of a fragment in a design are those of a `Layout` (see +`layout_of`), which gives its planes and the orbits of their satellites, a +short description (such as `"Walker 60 deg: 3 x 4 (spacing 1)"`, see +`Layout.describe`), and which other layouts extend. + +@author: Paul T. Grogan +""" + +from __future__ import annotations + +from collections.abc import Callable, Sequence +from dataclasses import dataclass +from datetime import datetime, time, timedelta +from functools import partial +from typing import Any + +import numpy as np + +from ..schemas import ( + CircularOrbit, + Instrument, + MOGConstellation, + Satellite, + SOCConstellation, + SunSynchronousOrbit, + TrainConstellation, + WalkerConstellation, +) +from .nodes import Derived, Fixed, Integer, Real, Repeat, Uncertain +from .space import DesignSpace, _as_constraints +from .values import ChoiceValues, RepeatValues, Scope, Values + +WALKER = "walker" +"""The pattern of the layouts of `walker_space`.""" +SSO_PLANES = "sso planes" +"""The pattern of the layouts of `sso_planes_space`.""" +PLANES = "planes" +"""The pattern of the layouts of `planes_space`.""" +SOC = "soc" +"""The pattern of the layouts of `soc_space`.""" +MOG = "mog" +"""The pattern of the layouts of `mog_space`.""" + + +def _node(value: Any, default: Any) -> Any: + return default if value is None else value + + +def walker_space( + *, + inclination: Any = None, + planes: Any = None, + per_plane: Any = None, + relative_spacing: Any = None, + altitude: Any = None, + configuration: Any = "delta", + phase_fraction: Any = 0.0, + node_fraction: Any = 0.0, + constraints: Callable[[Scope], Any] | Sequence[Callable[[Scope], Any]] = (), +) -> DesignSpace: + """ + Gets a fragment of a design space of Walker constellations (see + `tatc.schemas.WalkerConstellation`): their inclination (degrees), number + of planes, number of satellites in each plane, relative spacing of + satellites between planes, the phase and node of the lead satellite, and + (optionally, if not given to `build_constellation`) altitude (meters). + Each is a node of a design space (such as a design variable) or a value. + + The phase (true anomaly) and node (right ascension of the ascending + node) of the lead satellite are given as fractions of the intervals over + which they give distinct constellations: shifting every satellite's + phase by `360 / per_plane` degrees moves each onto the next in its plane, + and shifting every plane's node by `360 / planes` degrees (of a delta + configuration) moves each onto the next plane, which, with the shift of + phase between planes (`360 * relative_spacing / (planes * per_plane)`), + gives the same constellation. Fractions in [0, 1) of both therefore give every + distinct constellation once, without searching the same constellation + at several phases or nodes. A star configuration has no such symmetry of + its nodes (its planes span 180 degrees, and the next plane after the + last is the first, in the opposite direction), so its fraction of the + node is of 360 degrees. The fractions may be design variables (such as + `Real(0, 0.75, step=0.25)`, without 1, which is the same as 0) or + uncertain parameters (such as `Uncertain.uniform(0, 1)`), and the + fragment derives the lead satellite's `true_anomaly` and `node` (degrees) + from them. + + Args: + inclination (Any): The inclination, by default a variable from 30 to + 90 degrees in steps of 15. + planes (Any): The number of planes, by default a variable from 1 to 6. + per_plane (Any): The number of satellites in each plane, by default a + variable from 1 to 6. + relative_spacing (Any): The relative spacing, by default a variable + from 0 to the number of planes less 1. + altitude (Any): The altitude, if part of the layout. + configuration (Any): The configuration (`"delta"` or `"star"`). + phase_fraction (Any): The phase of the lead satellite, as a fraction + of `360 / per_plane` degrees. + node_fraction (Any): The node of the lead satellite, as a fraction of + `360 / planes` degrees (delta configuration) or 360 degrees (star + configuration). + constraints (Callable | Sequence[Callable]): A constraint, or the + constraints, of the fragment. + + Returns: + DesignSpace: the fragment + """ + children = { + "pattern": Fixed(WALKER), + "configuration": configuration, + "inclination": _node(inclination, Real(30, 90, step=15)), + "planes": _node(planes, Integer(1, 6)), + "per_plane": _node(per_plane, Integer(1, 6)), + "relative_spacing": _node(relative_spacing, Integer(0, lambda d: d.planes - 1)), + "phase_fraction": phase_fraction, + "node_fraction": node_fraction, + } + if altitude is not None: + children["altitude"] = altitude + children["true_anomaly"] = Derived(_lead_true_anomaly) + children["node"] = Derived(_lead_node) + return DesignSpace(constraints=constraints, **children) + + +def _lead_true_anomaly(d: Scope) -> float: + """The true anomaly (degrees) of the lead satellite of a Walker layout.""" + return float(d.phase_fraction) * 360 / d.per_plane % 360 + + +def _lead_node(d: Scope) -> float: + """The node (right ascension of the ascending node, degrees) of the lead + satellite of a Walker layout.""" + period = 360 if d.configuration == "star" else 360 / d.planes + return float(d.node_fraction) * period % 360 + + +def _plane_true_anomaly(d: Scope) -> float: + """The true anomaly (degrees) of the first satellite of a plane.""" + period = 360 if d.interval is not None else 360 / d.per_plane + return float(d.phase_fraction) * period % 360 + + +def _distinct_crossings(d: Scope) -> bool: + """Whether the planes of a layout have different crossing times.""" + crossings = [round(plane.crossing, 6) for plane in d.planes] + return len(set(crossings)) == len(crossings) + + +def sso_planes_space( + *, + crossing: Any = None, + planes: Any = None, + per_plane: Any = None, + phase_fraction: Any = 0.0, + interval: Any = None, + altitude: Any = None, + ascending: Any = True, + repeat_ground_track: Any = True, + ordered: bool = False, + distinct: bool = True, + constraints: Callable[[Scope], Any] | Sequence[Callable[[Scope], Any]] = (), +) -> DesignSpace: + """ + Gets a fragment of a design space of planes of sun-synchronous orbits + (see `tatc.schemas.SunSynchronousOrbit`), each with its own equator + crossing time (local solar time, in hours), number of satellites, + spacing of its satellites, and phase (see below), and (optionally, if not + given to `build_constellation`) their altitude (meters). Each is a node + of a design space (such as a design variable, a value derived from the + index of the plane, or an uncertain parameter) or a value. + + The planes are a `Repeat` named `planes`: the number of planes is its + `count` (in a design, `planes.count`), and the values of each plane + (`crossing`, `per_plane`, `interval`, `phase_fraction`, and the derived + `true_anomaly`) are its items (`planes[0].crossing`). + + The satellites of a plane are evenly spaced around its orbit if its + `interval` is `None`, or follow each other in a train (see + `tatc.schemas.TrainConstellation`) at an `interval` (minutes): each + crosses the equator the interval after the one ahead of it, on the same + ground track (if `repeat_ground_track`, with its node shifted by the + Earth's rotation, which delays its local crossing time by the interval) + or in the same plane. Evenly spaced satellites revisit at intervals of + the orbital period divided by their number; a train revisits within + minutes, then not until the next orbit. The interval may be a design + variable whose options include `None`, such as `Categorical([None, 5, + 15])`. + + The phase of each plane is a fraction of the interval over which it + gives distinct planes (as that of a Walker constellation, see + `walker_space`): `360 / per_plane` degrees of true anomaly if its + satellites are evenly spaced (a shift by which moves each onto the next), + or 360 degrees if they are a train. Fractions in [0, 1) therefore give + every distinct plane once, may be design variables or uncertain + parameters (such as `Uncertain.uniform(0, 1)`) whatever the spacing, and + the fragment derives the true anomaly of the plane's first satellite + (`true_anomaly`, degrees) from them. + + The planes are unordered by default: designs whose planes differ only in + their order are the same design (which requires that their values do + not depend on their index). Planes with the same crossing time would be + the same plane, so a constraint requires different crossing times + (unless `distinct` is `False`). + + Args: + crossing (Any): The crossing time of each plane, by default a variable + from 6 to 18 hours in steps of 1.5. + planes (Any): The number of planes, by default a variable from 1 to 3. + per_plane (Any): The number of satellites in each plane, by default + a variable from 1 to 4. + phase_fraction (Any): The phase of each plane, as a fraction of + `360 / per_plane` degrees (evenly spaced) or 360 degrees (a + train): an uncertain parameter, such as `Uncertain.uniform(0, 1)`, + if it is not designed. + interval (Any): The interval (minutes) between the satellites of a + train in each plane, or `None` for evenly spaced satellites. + altitude (Any): The altitude, if part of the layout. + ascending (Any): Whether the crossing times are of ascending nodes. + repeat_ground_track (Any): Whether the satellites of a train follow + the same ground track (or the same plane). + ordered (bool): `True` if the planes are ordered (for example, if + their values depend on their index). + distinct (bool): `True` to require different crossing times. + constraints (Callable | Sequence[Callable]): Another constraint, + or other constraints, of the fragment. + + Returns: + DesignSpace: the fragment + """ + plane = DesignSpace( + crossing=_node(crossing, Real(6, 18, step=1.5)), + per_plane=_node(per_plane, Integer(1, 4)), + interval=interval, + phase_fraction=phase_fraction, + true_anomaly=Derived(_plane_true_anomaly), + ) + children = { + "pattern": Fixed(SSO_PLANES), + "ascending": ascending, + "repeat_ground_track": repeat_ground_track, + "planes": Repeat(plane, count=_node(planes, Integer(1, 3)), ordered=ordered), + } + if altitude is not None: + children["altitude"] = altitude + constraints = [ + *([_distinct_crossings] if distinct else []), + *_as_constraints(constraints), + ] + return DesignSpace(constraints=constraints, **children) + + +def planes_space( + *, + inclination: Any = None, + node: Any = None, + planes: Any = None, + per_plane: Any = None, + phase_fraction: Any = 0.0, + interval: Any = None, + altitude: Any = None, + repeat_ground_track: Any = True, + ordered: bool = False, + constraints: Callable[[Scope], Any] | Sequence[Callable[[Scope], Any]] = (), +) -> DesignSpace: + """ + Gets a fragment of a design space of planes of circular orbits (see + `tatc.schemas.CircularOrbit`), each with its own inclination (degrees), + node (right ascension of the ascending node at the epoch, degrees), + number of satellites, spacing of its satellites (evenly spaced, or a + train at an `interval`), and phase (a fraction, see `sso_planes_space`), + and (optionally, if not given to `build_constellation`) their altitude + (meters). Each is a node of a design space (such as a design variable, a + value derived from the index of the plane, or an uncertain parameter) or + a value. The planes are a `Repeat` named `planes`, as those of + `sso_planes_space`. + + Unlike a Walker constellation, whose planes are evenly spaced in node, + the planes may have any nodes and inclinations, as those of satellites + launched as secondary payloads, whose nodes are chosen by the launches + of the primary payloads: the node of each plane is therefore uncertain + by default (uniform from 0 to 360 degrees), drawn for each replicate. + The planes are unordered by default (see `sso_planes_space`). + + Args: + inclination (Any): The inclination of each plane, by default a + variable from 30 to 90 degrees in steps of 15. + node (Any): The node of each plane, by default uncertain (uniform + from 0 to 360 degrees). + planes (Any): The number of planes, by default a variable from 1 to 3. + per_plane (Any): The number of satellites in each plane, by default + a variable from 1 to 4. + phase_fraction (Any): The phase of each plane, as a fraction of + `360 / per_plane` degrees (evenly spaced) or 360 degrees (a + train). + interval (Any): The interval (minutes) between the satellites of a + train in each plane, or `None` for evenly spaced satellites. + altitude (Any): The altitude, if part of the layout. + repeat_ground_track (Any): Whether the satellites of a train follow + the same ground track (or the same plane). + ordered (bool): `True` if the planes are ordered. + constraints (Callable | Sequence[Callable]): A constraint, or the + constraints, of the fragment. + + Returns: + DesignSpace: the fragment + """ + plane = DesignSpace( + inclination=_node(inclination, Real(30, 90, step=15)), + node=_node(node, Uncertain.uniform(0, 360)), + per_plane=_node(per_plane, Integer(1, 4)), + interval=interval, + phase_fraction=phase_fraction, + true_anomaly=Derived(_plane_true_anomaly), + ) + children = { + "pattern": Fixed(PLANES), + "repeat_ground_track": repeat_ground_track, + "planes": Repeat(plane, count=_node(planes, Integer(1, 3)), ordered=ordered), + } + if altitude is not None: + children["altitude"] = altitude + return DesignSpace(constraints=constraints, **children) + + +def _soc_of(values: Any, altitude: float, epoch: datetime | None = None): + """The streets-of-coverage constellation of the values of a layout (or of + a scope), at an altitude and (if given) an epoch.""" + orbit = { + "altitude": altitude, + "inclination": values.inclination, + "true_anomaly": getattr(values, "true_anomaly", 0.0), + "right_ascension_ascending_node": getattr(values, "node", 0.0), + } + return SOCConstellation( + name="soc", + orbit=CircularOrbit(**orbit, **({} if epoch is None else {"epoch": epoch})), + swath_width=values.swath_width, + packing_distance=values.packing_distance, + polar=values.polar, + ) + + +def _soc_planes(d: Scope) -> int: + """The number of planes of a streets-of-coverage layout.""" + return _soc_of(d, d.altitude).get_number_planes() + + +def _soc_per_plane(d: Scope) -> int: + """The number of satellites in each plane of a streets-of-coverage + layout.""" + return _soc_of(d, d.altitude).get_satellites_per_plane() + + +def _scope_altitude(d: Scope) -> float: + """The altitude decided before a fragment (outside it).""" + return d.altitude + + +def _soc_node(d: Scope) -> float: + """The node (right ascension of the ascending node, degrees) of the lead + satellite of a streets-of-coverage layout.""" + period = 360 if _soc_of(d, d.altitude).is_polar() else 360 / d.planes + return float(d.node_fraction) * period % 360 + + +def soc_space( + *, + swath_width: Any, + inclination: Any = None, + packing_distance: Any = 1.0, + polar: Any = None, + altitude: Any = None, + phase_fraction: Any = 0.0, + node_fraction: Any = 0.0, + constraints: Callable[[Scope], Any] | Sequence[Callable[[Scope], Any]] = (), +) -> DesignSpace: + """ + Gets a fragment of a design space of streets-of-coverage constellations + (see `tatc.schemas.SOCConstellation`): the fewest satellites whose + footprints (of a swath width, in meters) cover the Earth continuously at + an inclination (degrees), in a Walker delta pattern for inclined orbits + or the polar pattern for near-polar ones (`polar`, by default chosen by + the inclination), with a margin of overlap (`packing_distance`, 1 for + none). Each is a node of a design space (such as a design variable, or a + value derived from the instrument, as the swath width of the sensor of a + design) or a value. + + The fragment derives its number of planes (`planes`) and of satellites + in each plane (`per_plane`) from them and the altitude (meters), which + therefore must be decided before them: a value of the fragment + (`altitude`), or by default the altitude of the design space outside it + (declared before it), which the fragment keeps as its own (so that + `build_constellation` builds the satellites at the altitude its planes + were derived at). + + The phase and node of the lead satellite are fractions, as those of a + Walker constellation (see `walker_space`): of `360 / per_plane` degrees + of phase, and of `360 / planes` degrees of node (inclined orbits) or 360 + degrees (polar orbits, whose planes span 180 degrees). The fragment + derives the lead satellite's `true_anomaly` and `node` (degrees) from + them. + + Args: + swath_width (Any): The swath width (meters) of the footprints. + inclination (Any): The inclination, by default a variable from 30 to + 90 degrees in steps of 15. + packing_distance (Any): The relative distance between footprints + (inclined orbits) or the relative radius of the footprints (polar + orbits), in (0, 1]: less than 1 for a margin of overlap. + polar (Any): `True` for the polar pattern, `False` for the Walker + delta pattern, or `None` for the polar pattern of near-polar + orbits. + altitude (Any): The altitude, or `None` for that of the design space + outside the fragment. + phase_fraction (Any): The phase of the lead satellite, as a fraction + of `360 / per_plane` degrees. + node_fraction (Any): The node of the lead satellite, as a fraction of + `360 / planes` degrees (inclined orbits) or 360 degrees (polar + orbits). + constraints (Callable | Sequence[Callable]): A constraint, or the + constraints, of the fragment (such as a maximum of + `planes * per_plane` satellites). + + Returns: + DesignSpace: the fragment + """ + children = { + "pattern": Fixed(SOC), + "inclination": _node(inclination, Real(30, 90, step=15)), + "swath_width": swath_width, + "packing_distance": packing_distance, + "polar": polar, + "phase_fraction": phase_fraction, + "node_fraction": node_fraction, + "altitude": Derived(_scope_altitude) if altitude is None else altitude, + } + children["planes"] = Derived(_soc_planes) + children["per_plane"] = Derived(_soc_per_plane) + children["true_anomaly"] = Derived(_lead_true_anomaly) + children["node"] = Derived(_soc_node) + return DesignSpace(constraints=constraints, **children) + + +def _group_true_anomaly(d: Scope) -> float: + """The true anomaly (degrees) of the reference orbit of a mutual orbiting + group.""" + return float(d.phase_fraction) * 360 % 360 + + +def mog_space( + *, + parallel_axis: Any, + transverse_axis: Any, + inclination: Any = None, + node: Any = 0.0, + satellites: Any = None, + clockwise: Any = True, + altitude: Any = None, + phase_fraction: Any = 0.0, + constraints: Callable[[Scope], Any] | Sequence[Callable[[Scope], Any]] = (), +) -> DesignSpace: + """ + Gets a fragment of a design space of mutual orbiting groups (see + `tatc.schemas.MOGConstellation`): satellites that orbit each other (on + an ellipse with axes, in meters, parallel and transverse to the + velocity, clockwise or not) about a reference circular orbit of an + inclination and node (degrees), and (optionally, if not given to + `build_constellation`) altitude (meters). Each is a node of a design + space (such as a design variable) or a value. + + The satellites of a group are launched together, as a single plane (of + `count_planes`), although the orbit of each has its own inclination and + node. The phase of the reference orbit is a fraction of 360 degrees, + from which the fragment derives its `true_anomaly` (degrees). + + Args: + parallel_axis (Any): The axis (meters) of the mutual orbit parallel + to the velocity. + transverse_axis (Any): The axis (meters) of the mutual orbit + transverse to the velocity. + inclination (Any): The inclination of the reference orbit, by default + a variable from 30 to 90 degrees in steps of 15. + node (Any): The node of the reference orbit. + satellites (Any): The number of satellites, by default a variable + from 2 to 6. + clockwise (Any): Whether the mutual orbit is clockwise. + altitude (Any): The altitude, if part of the layout. + phase_fraction (Any): The phase of the reference orbit, as a fraction + of 360 degrees. + constraints (Callable | Sequence[Callable]): A constraint, or the + constraints, of the fragment. + + Returns: + DesignSpace: the fragment + """ + children = { + "pattern": Fixed(MOG), + "inclination": _node(inclination, Real(30, 90, step=15)), + "node": node, + "satellites": _node(satellites, Integer(2, 6)), + "parallel_axis": parallel_axis, + "transverse_axis": transverse_axis, + "clockwise": clockwise, + "phase_fraction": phase_fraction, + } + if altitude is not None: + children["altitude"] = altitude + children["true_anomaly"] = Derived(_group_true_anomaly) + return DesignSpace(constraints=constraints, **children) + + +@dataclass(frozen=True) +class Plane: + """ + An orbit plane of a layout (see `Layout`): its number of satellites, and + its values in a design. + """ + + satellites: int + """int: The number of satellites.""" + values: Any = None + """Any: The values of the plane in a design (such as those of each plane + of `sso_planes_space`), or `None` (as for the planes of a Walker + constellation), as given to the `order` and `launch_mass_capacity` of a + `DeploymentSchedule` (functions of the index and values of a plane).""" + + +class Layout: + """ + The satellites of a constellation, plane by plane: a Walker + constellation (`WalkerLayout`), planes of sun-synchronous orbits + (`SSOPlanesLayout`) or of inclined orbits (`PlanesLayout`), a + streets-of-coverage constellation (`SOCLayout`), a mutual orbiting group + (`MOGLayout`), or several layouts flown together (`Layouts`). `layout_of` + gets the layout of the values of a design (of a fragment such as + `walker_space`). The functions of layouts (`build_constellation`, + `count_satellites`, `count_planes`, `plane_sizes`, and + `DeploymentSchedule.plan`) take either. + + The satellites of a layout are those of its planes in order, and those of + each plane in their order in it, so that the satellites that `build` + builds are those of the planes that a deployment launches (see + `DeploymentSchedule.plan` and `MissionHistory.phases`). + + Other layouts subclass it, implementing `planes` and `orbits` (and + `names`, for names other than `"

-"`, and `describe`), so + that they are built, counted, deployed, and costed as the others. + + A layout of its own altitude (such as a fragment with an `altitude`) + is built at that altitude; the altitude given to `build_constellation` + (or `orbits`) is that of layouts without their own. + """ + + def planes(self) -> list[Plane]: + """ + Gets the planes, in order. + + Returns: + list[Plane]: the planes + """ + raise NotImplementedError + + def orbits(self, epoch: datetime, altitude: float | None = None) -> list[list[Any]]: + """ + Gets the orbits of the satellites of each plane, in the order of the + planes. + + Args: + epoch (datetime.datetime): The epoch of the orbits. + altitude (float | None): The altitude (meters) of a layout without + its own, if any. + + Returns: + list[list]: the orbits of the satellites of each plane + + Raises: + ValueError: if the layout has no altitude of its own and none is + given. + """ + raise NotImplementedError + + def _unrealized(self) -> bool: + """Whether the layout has values that are not realized (`NaN`).""" + return _has_nan(getattr(self, "values", None)) + + def describe(self) -> str: + """ + Gets a short description of the layout (such as `"Walker 60 deg: 3 x + 4 (spacing 1)"` or `"SSO: 2 at 06:00, 1 at 13:30"`), as for labels of + designs: by default, its numbers of planes and satellites. + + Returns: + str: the description + """ + planes = self.planes() + return f"{len(planes)} planes, {self.satellites} satellites" + + def __str__(self) -> str: + return self.describe() + + def __repr__(self) -> str: + return f"{type(self).__name__}({self.describe()!r})" + + def names(self, name: str) -> list[list[str]]: + """ + Gets the names of the satellites of each plane: `"

-"` + (plane `p`, satellite `s`). + + Args: + name (str): The prefix of the names. + + Returns: + list[list[str]]: the names of the satellites of each plane + """ + return [ + [f"{name} {p + 1}-{s + 1}" for s in range(plane.satellites)] + for p, plane in enumerate(self.planes()) + ] + + @property + def satellites(self) -> int: + """int: The number of satellites.""" + return sum(plane.satellites for plane in self.planes()) + + def build( + self, + payload: Payload, + *, + epoch: datetime, + altitude: float | None = None, + name: str = "satellite", + time_step: float | None = None, + ) -> list[Satellite]: + """ + Builds the satellites, in the order of the planes, each with a + payload (see `build_constellation`). + + Args: + payload (Payload): The payload of each satellite. + epoch (datetime.datetime): The epoch of the orbits. + altitude (float | None): The altitude (meters), if the layout does + not give its own. + name (str): The prefix of the names of the satellites. + time_step (float | None): The analysis time step (seconds), for + catalog configurations that tailor a field of view to it. + + Returns: + list[Satellite]: the satellites + + Raises: + ValueError: if the orbits or names of the satellites do not match + the planes, or the layout has values that are not realized. + """ + if self._unrealized(): + raise ValueError( + "the layout has values that are not realized (NaN, such as of " + + "uncertain parameters): build the satellites of a realized " + + "design (see Design.realize and Study.realize)" + ) + counts = [plane.satellites for plane in self.planes()] + orbits, names = self.orbits(epoch, altitude), self.names(name) + if [len(o) for o in orbits] != counts or [len(n) for n in names] != counts: + raise ValueError("the orbits and names of a layout must match its planes") + return [ + _make_satellite(payload, satellite, orbit, time_step) + for plane_names, plane_orbits in zip(names, orbits) + for satellite, orbit in zip(plane_names, plane_orbits) + ] + + +def _get_altitude(values: Any, altitude: float | None) -> float: + """Gets the altitude of the values of a layout, or else the given one.""" + own = getattr(values, "altitude", None) + altitude = altitude if own is None else own + if altitude is None: + raise ValueError("the layout has no altitude: give one") + return altitude + + +def _has_nan(value: Any) -> bool: + """Whether values (of a layout) have a missing number (`NaN`).""" + if isinstance(value, float): + return value != value # pylint: disable=comparison-with-itself + if isinstance(value, ChoiceValues): + return _has_nan(value.value) + if isinstance(value, RepeatValues): + return any(_has_nan(item) for item in value) + if isinstance(value, Values): + return any(_has_nan(value[name]) for name in value) + return False + + +def _km(altitude: Any) -> str: + """The description of an altitude (meters) of a layout, if it has one.""" + return "" if altitude is None else f" at {float(altitude) / 1e3:g} km" + + +class _ValuesLayout(Layout): + """ + A layout of the values of a fragment of a design space in a design. + + Args: + values (Values): The values of the layout. + """ + + def __init__(self, values: Any): + self.values = values + + def _altitude(self) -> str: + return _km(getattr(self.values, "altitude", None)) + + +class _MembersLayout(_ValuesLayout): + """ + A constellation whose members a schema of TAT-C generates (see + `_constellation`), plane by plane (the members of each plane following + each other), its satellites named `" "`, in order. + """ + + _MISMATCH = "the members of the constellation do not match its planes" + + def _constellation(self, epoch: datetime, altitude: float) -> Any: + """Gets the constellation (of `tatc.schemas`) at an epoch and altitude.""" + raise NotImplementedError + + def orbits(self, epoch: datetime, altitude: float | None = None) -> list[list[Any]]: + altitude = _get_altitude(self.values, altitude) + members = self._constellation(epoch, altitude).generate_members() + sizes = [plane.satellites for plane in self.planes()] + if len(members) != sum(sizes): + raise ValueError(self._MISMATCH) + starts = np.cumsum([0, *sizes]) + return [ + [member.orbit for member in members[start:stop]] + for start, stop in zip(starts[:-1], starts[1:]) + ] + + def names(self, name: str) -> list[list[str]]: + sizes = [plane.satellites for plane in self.planes()] + starts = np.cumsum([0, *sizes]) + return [ + [f"{name} {k + 1}" for k in range(start, start + size)] + for start, size in zip(starts[:-1], sizes) + ] + + +class WalkerLayout(_MembersLayout): + """ + A Walker constellation (see `tatc.schemas.WalkerConstellation`): the + values of `walker_space` in a design. Its satellites are named + `" "`, in order. + + Args: + values (Values): The values of the layout. + """ + + def planes(self) -> list[Plane]: + return [Plane(int(self.values.per_plane))] * int(self.values.planes) + + def _constellation(self, epoch: datetime, altitude: float) -> Any: + values = self.values + return WalkerConstellation( + name="walker", + configuration=values.configuration, + orbit=CircularOrbit( + altitude=altitude, + inclination=values.inclination, + true_anomaly=getattr(values, "true_anomaly", 0.0), + right_ascension_ascending_node=getattr(values, "node", 0.0), + epoch=epoch, + ), + number_planes=values.planes, + number_satellites=values.planes * values.per_plane, + relative_spacing=values.relative_spacing, + ) + + def describe(self) -> str: + values = self.values + star = "star " if values.configuration == "star" else "" + return ( + f"Walker {star}{float(values.inclination):g} deg{self._altitude()}: " + + f"{int(values.planes)} x {int(values.per_plane)} " + + f"(spacing {int(values.relative_spacing)})" + ) + + +class _PlanesLayout(_ValuesLayout): + """ + Planes of circular orbits, each with its own number of satellites, + evenly spaced or in a train (see `sso_planes_space`). + """ + + def _describe_plane(self, plane: Any) -> str: + """Gets a short description of a plane (its orbit).""" + raise NotImplementedError + + def _describe_planes(self) -> str: + """Gets a short description of the planes.""" + described = [] + for plane in self.values.planes: + text = f"{int(plane.per_plane)} at {self._describe_plane(plane)}" + interval = getattr(plane, "interval", None) + if interval is not None: + if isinstance(interval, timedelta): + interval = interval.total_seconds() / 60 + text += f" (train, {float(interval):g} min)" + described.append(text) + return ", ".join(described) + + def planes(self) -> list[Plane]: + return [Plane(int(plane.per_plane), plane) for plane in self.values.planes] + + def _orbit(self, plane: Any, epoch: datetime, altitude: float, anomaly: float): + """Gets the orbit of a satellite of a plane at a true anomaly.""" + raise NotImplementedError + + def orbits(self, epoch: datetime, altitude: float | None = None) -> list[list[Any]]: + altitude = _get_altitude(self.values, altitude) + repeat_ground_track = getattr(self.values, "repeat_ground_track", True) + return [ + _plane_orbits( + partial(self._orbit, plane, epoch, altitude), plane, repeat_ground_track + ) + for plane in self.values.planes + ] + + +class SSOPlanesLayout(_PlanesLayout): + """ + Planes of sun-synchronous orbits (see `tatc.schemas.SunSynchronousOrbit`): + the values of `sso_planes_space` in a design. Its satellites are named + `"

-"` (plane `p`, satellite `s`). + + Args: + values (Values): The values of the layout. + """ + + def _orbit(self, plane: Any, epoch: datetime, altitude: float, anomaly: float): + return SunSynchronousOrbit( + altitude=altitude, + equator_crossing_time=hours_to_time(plane.crossing), + equator_crossing_ascending=self.values.ascending, + epoch=epoch, + true_anomaly=anomaly, + ) + + def _describe_plane(self, plane: Any) -> str: + return hours_to_time(plane.crossing).strftime("%H:%M") + + def describe(self) -> str: + descending = "" if getattr(self.values, "ascending", True) else " descending" + return f"SSO{descending}{self._altitude()}: {self._describe_planes()}" + + +class PlanesLayout(_PlanesLayout): + """ + Planes of inclined circular orbits (see `tatc.schemas.CircularOrbit`): + the values of `planes_space` in a design. Its satellites are named + `"

-"` (plane `p`, satellite `s`). + + Args: + values (Values): The values of the layout. + """ + + def _orbit(self, plane: Any, epoch: datetime, altitude: float, anomaly: float): + return CircularOrbit( + altitude=altitude, + inclination=plane.inclination, + right_ascension_ascending_node=float(plane.node) % 360, + epoch=epoch, + true_anomaly=anomaly, + ) + + def _describe_plane(self, plane: Any) -> str: + node = float(plane.node) + known = "" if node != node else f" (node {node % 360:g} deg)" + return f"{float(plane.inclination):g} deg{known}" + + def describe(self) -> str: + return f"Planes{self._altitude()}: {self._describe_planes()}" + + +class SOCLayout(_MembersLayout): + """ + A streets-of-coverage constellation (see + `tatc.schemas.SOCConstellation`): the values of `soc_space` in a design, + whose planes and satellites in each plane it derived at its altitude. + Its satellites are named `" "`, in order. + + Args: + values (Values): The values of the layout. + """ + + _MISMATCH = ( + "the altitude of a streets-of-coverage layout must be the one its " + + "planes were derived at" + ) + + def planes(self) -> list[Plane]: + return [Plane(int(self.values.per_plane))] * int(self.values.planes) + + def _constellation(self, epoch: datetime, altitude: float) -> Any: + return _soc_of(self.values, altitude, epoch) + + def describe(self) -> str: + values = self.values + polar = ( + "polar " if _soc_of(values, _get_altitude(values, None)).is_polar() else "" + ) + return ( + f"SOC {polar}{float(values.inclination):g} deg{self._altitude()}: " + + f"{int(values.planes)} x {int(values.per_plane)}" + ) + + +class MOGLayout(_MembersLayout): + """ + A mutual orbiting group (see `tatc.schemas.MOGConstellation`): the + values of `mog_space` in a design, a single plane (launched together). + Its satellites are named `" "`, in order. + + Args: + values (Values): The values of the layout. + """ + + def planes(self) -> list[Plane]: + return [Plane(int(self.values.satellites))] + + def _constellation(self, epoch: datetime, altitude: float) -> Any: + values = self.values + return MOGConstellation( + name="mog", + orbit=CircularOrbit( + altitude=altitude, + inclination=values.inclination, + right_ascension_ascending_node=float(values.node) % 360, + true_anomaly=getattr(values, "true_anomaly", 0.0), + epoch=epoch, + ), + parallel_axis=values.parallel_axis, + transverse_axis=values.transverse_axis, + clockwise=bool(values.clockwise), + number_satellites=int(values.satellites), + ) + + def describe(self) -> str: + values = self.values + return ( + f"MOG {float(values.inclination):g} deg{self._altitude()}: " + + f"{int(values.satellites)} satellites " + + f"({float(values.parallel_axis) / 1e3:g} x " + + f"{float(values.transverse_axis) / 1e3:g} km)" + ) + + +class Layouts(Layout): + """ + Several layouts flown together (such as the shells of a mixed + constellation): their planes in turn, whose satellites are named with a + letter for each layout (`" A 1"`, `" B 1-1"`). + + Args: + layouts (Sequence): The layouts, or the values of each (see + `layout_of`). + """ + + def __init__(self, layouts: Sequence[Any]): + self.layouts = [layout_of(layout) for layout in layouts] + + def planes(self) -> list[Plane]: + return [plane for layout in self.layouts for plane in layout.planes()] + + def orbits(self, epoch: datetime, altitude: float | None = None) -> list[list[Any]]: + return [ + orbits + for layout in self.layouts + for orbits in layout.orbits(epoch, altitude) + ] + + def names(self, name: str) -> list[list[str]]: + return [ + names + for k, layout in enumerate(self.layouts) + for names in layout.names(f"{name} {chr(65 + k) if k < 26 else k + 1}") + ] + + def describe(self) -> str: + return "; ".join(layout.describe() for layout in self.layouts) + + def _unrealized(self) -> bool: + # pylint: disable-next=protected-access + return any(layout._unrealized() for layout in self.layouts) + + +_PATTERNS = { + WALKER: WalkerLayout, + SSO_PLANES: SSOPlanesLayout, + PLANES: PlanesLayout, + SOC: SOCLayout, + MOG: MOGLayout, +} +"""The layouts of the patterns of the fragments of design spaces (their +values `pattern`).""" + + +def layout_of(layout: Any) -> Layout: + """ + Gets the layout of the values of a design: those of a fragment + (`walker_space`, `sso_planes_space`, `planes_space`, `soc_space`, or + `mog_space`, or of a choice of them), or of several (a list or a + repetition of layouts, see `Layouts`). A layout is its own. + + Args: + layout (Any): The values of the layout (or layouts), or a layout. + + Returns: + Layout: the layout + + Raises: + ValueError: if the values are not those of a layout. + """ + if isinstance(layout, Layout): + return layout + if isinstance(layout, (list, tuple, RepeatValues)): + return Layouts(list(layout)) + if isinstance(layout, ChoiceValues): + layout = layout.value + pattern = getattr(layout, "pattern", None) + if not isinstance(pattern, str) or pattern not in _PATTERNS: + raise ValueError( + "a layout must be the values of walker_space, sso_planes_space, " + + "planes_space, soc_space, or mog_space, or a Layout" + ) + return _PATTERNS[pattern](layout) + + +def count_satellites(layout: Any) -> int: + """ + Counts the satellites of a layout (the values of a fragment such as + `walker_space`, or of a choice of them, or of several, or a `Layout`, + see `layout_of`), for objectives and constraints. + + Args: + layout (Any): The values of the layout (or layouts), or a layout. + + Returns: + int: the number of satellites + """ + return layout_of(layout).satellites + + +def count_planes(layout: Any) -> int: + """ + Counts the orbit planes of a layout (the values of a fragment such as + `walker_space`, or of a choice of them, or of several, or a `Layout`, + see `layout_of`), each of which needs its own launch. + + Args: + layout (Any): The values of the layout (or layouts), or a layout. + + Returns: + int: the number of planes + """ + return len(layout_of(layout).planes()) + + +def plane_sizes(layout: Any) -> list[int]: + """ + Gets the number of satellites of each orbit plane of a layout (the + values of a fragment such as `walker_space`, or of a choice of them, or + of several, or a `Layout`, see `layout_of`). + + Args: + layout (Any): The values of the layout (or layouts), or a layout. + + Returns: + list[int]: the number of satellites of each plane + """ + return [plane.satellites for plane in layout_of(layout).planes()] + + +def hours_to_time(hours: float) -> time: + """ + Converts a local time in hours (such as 13.5) to a time of day (13:30), + to the nearest second. + + Args: + hours (float): The time (hours, wrapped to [0, 24)). + + Returns: + datetime.time: the time of day + """ + seconds = round(hours * 3600) % 86400 + return time(seconds // 3600, seconds // 60 % 60, seconds % 60) + + +Payload = ( + Instrument + | Sequence[Instrument] + | str + | Sequence[str] + | Callable[[str, Any], Satellite] +) +"""A payload: instruments, catalog entries, or a function of a name and an +orbit that builds a satellite.""" + + +def _make_satellite( + payload: Any, name: str, orbit: Any, time_step: float | None +) -> Satellite: + """ + Makes a satellite with a payload in an orbit (see `build_constellation`). + """ + if callable(payload) and not isinstance(payload, Instrument): + return payload(name, orbit) + payloads = [payload] if isinstance(payload, (str, Instrument)) else list(payload) + if all(isinstance(item, Instrument) for item in payloads): + return Satellite(name=name, orbit=orbit, instruments=payloads) + if not all(isinstance(item, str) for item in payloads): + raise ValueError("a payload mixes instruments and catalog entries") + # pylint: disable=import-outside-toplevel + from ..catalog import get_entry + + instruments, attitude = [], None + for item in payloads: + entry_id, _, configuration = item.partition(":") + built = get_entry(entry_id).build( + configuration or None, orbit=orbit, time_step=time_step + ) + instruments.extend(built.instruments) + if attitude is None: + attitude = built.attitude + return Satellite(name=name, orbit=orbit, instruments=instruments, attitude=attitude) + + +def _plane_orbits( + make: Callable[[float], Any], + plane: Any, + repeat_ground_track: bool, +) -> list[Any]: + """ + Gets the orbits of the satellites of a plane: evenly spaced from the + true anomaly of its first satellite, or a train at its interval (see + `sso_planes_space`), with `make` the orbit of a satellite at a true + anomaly. + """ + interval = getattr(plane, "interval", None) + count = int(plane.per_plane) + if interval is None: + return [ + make((plane.true_anomaly + 360 * s / count) % 360) for s in range(count) + ] + interval = ( + interval + if isinstance(interval, timedelta) + else timedelta(minutes=float(interval)) + ) + if interval <= timedelta(0): + raise ValueError("the interval of a train must be positive") + train = TrainConstellation( + name="train", + orbit=make(plane.true_anomaly % 360), + number_satellites=count, + interval=interval, + repeat_ground_track=bool(repeat_ground_track), + ) + return [member.orbit for member in train.generate_members()] + + +def build_constellation( + layout: Any, + payload: Payload, + *, + epoch: datetime, + altitude: float | None = None, + name: str = "satellite", + time_step: float | None = None, +) -> list[Satellite]: + """ + Builds the satellites of a layout: the values of a fragment (such as + `walker_space`) in a design (or of a choice of them), or a `Layout` (see + `layout_of`), at the layout's own altitude (or else the given one), each + with a payload: + + * an `Instrument` (or a list of instruments); + * the identifier of an entry of the instrument catalog (see + `tatc.catalog.get_entry`), optionally with a configuration after a + colon (such as `"atms:swath_noaa_20"`), whose instruments are built for the + orbit with the attitude they were validated with (and, if the + configuration tailors a field of view, the analysis `time_step`), or + a list of identifiers, whose instruments the satellite carries + together (with the attitude of the first); + * a function of a name and an orbit that builds a satellite. + + Satellites of Walker and streets-of-coverage constellations and of + mutual orbiting groups are named `" "`, and those of planes + `"

-"` (plane `p`, satellite `s`), in the order of the + planes (see `Layout`). + + Several layouts (a list or a repetition of layouts, such as the shells + of a mixed constellation, see `Layouts`) are built in turn, with the + same payload, and the names of their satellites are prefixed by a + letter for each layout (`" A 1"`, `" B 1-1"`). Build layouts + with different payloads in separate calls, with different names. + + Args: + layout (Any): The values of the layout (or layouts), or a layout. + payload (Payload): The payload of each satellite. + epoch (datetime.datetime): The epoch of the orbits. + altitude (float | None): The altitude (meters), of layouts that do + not give their own. + name (str): The prefix of the names of the satellites. + time_step (float | None): The analysis time step (seconds), for + catalog configurations that tailor a field of view to it. + + Returns: + list[Satellite]: the satellites + """ + return layout_of(layout).build( + payload, epoch=epoch, altitude=altitude, name=name, time_step=time_step + ) + + +def remove_failures( + satellites: Sequence[Satellite], probability: float, seed: int | None +) -> list[Satellite]: + """ + Removes the satellites that fail, each with a probability, for the + robustness of a design to failures: drawn for each replicate from an + uncertain seed (see `Uncertain.seed`). Whether a satellite fails depends + only on the seed and its position in the list, so that with common + random numbers, the satellite at the same position fails in the same + replicate of every design. + + It is a snapshot, for the build function of any study: the constellation + with some of its satellites missing, without a deployment or the time of + a mission. The failures of an `ObservationStudy` with a `MissionPlan` + (see `Failures`) are those over a mission instead: the lives of + satellites, the failures of launches, and their restoration, averaged + over the phases of the mission. + + Args: + satellites (Sequence[Satellite]): The satellites, in the order they + are built. + probability (float): The probability that a satellite fails. + seed (int | None): The seed of the replicate, or `None` (as before a + design is realized) for no failures. + + Returns: + list[Satellite]: the satellites that do not fail + """ + if not 0 <= probability <= 1: + raise ValueError("probability must be between 0 and 1") + if seed is None or probability == 0: + return list(satellites) + return [ + satellite + for k, satellite in enumerate(satellites) + if np.random.default_rng([seed, k]).random() >= probability + ] diff --git a/src/tatc/tradespace/cost.py b/src/tatc/tradespace/cost.py new file mode 100644 index 0000000..7e66137 --- /dev/null +++ b/src/tatc/tradespace/cost.py @@ -0,0 +1,946 @@ +""" +Life-cycle cost of constellations for trade studies: the development, +production, launch, and operations of the satellites of a deployment (see +`DeploymentSchedule`), with learning in production, replacements over the +mission, and spares, dated for their present value and annual costs. + +TAT-C does not include cost-estimating relationships, whose common forms are +restricted or need calibration to an organization's experience: the costs of +each type of satellite (such as the satellites of each payload) and of +launches and operations are given, as values or functions of a design (such +as a mass-based relationship, as a `MissionPlan` of each design sizes them), +in a currency of the user's choice and constant-year amounts. Cost risk +enters as uncertain growth factors (see `CostModel.estimate`), drawn for +each replicate like other uncertain parameters, so that statistics of the +cost over replicates (such as a 0.7 `Quantile`) are objectives or +requirements: of every cost, of each element, or of each element of each +type of satellite. + +The costs of a type of satellite may also be the sum of those of its +components (such as its bus and instruments, see `Component`), each with an +uncertain growth by its maturity (such as a `Triangular` distribution, wider +for new components than for existing ones), correlated between the +components (`CostModel.correlation`), as in formal risk assessments of cost +estimates. Their growth is drawn from scores of the components and a common +score (`CostModel.draw`), uncertain parameters of the design space +(`risk_space`) that common random numbers give alike to every design of a +replicate: designs that share a component share its growth, so that the +costs of designs are correlated by what they share (as in M. W. Maier, K. +L. Yeakel, and E. B. Wendoloski, "Cost Variance Analysis in Constellation +Architecture Studies," IEEE Systems Journal 17(2), 2023), and comparisons +between them (such as the probability that one costs more than another, see +`exceedance`) see the differences of their costs. + +A deployment dates the costs: development of each type of satellite (and +of each later block of its production, see `SatelliteCost.block_size`), +production of its satellites, launches, replacements, and operations from +launch to the end of the mission, so that each design's costs follow from +its satellites and planes. The costs of a constellation sustained after the +end of its mission (such as of an operational program over the period of a +study, see `DeploymentSchedule`) are those incurred by the end, which count +the units in production then by the share produced. The dated costs give +the present value of the cost at a discount rate, and the cost of each year +(such as its peak, for annual budgets):: + + def evaluate(satellites, design): + deployment = SCHEDULE.plan(design.layout, kind=design.payload) + cost = MODEL.estimate(deployment, growth={"development": design.growth}) + return cost.metrics() + +(as an `ObservationStudy` with a `MissionPlan` does for each design). + +@author: Paul T. Grogan +""" + +from __future__ import annotations + +import dataclasses +import math +import numbers +from collections.abc import Callable, Mapping, Sequence +from dataclasses import dataclass, field +from typing import Any + +import numpy as np +import pandas as pd + +from .deployment import Deployment +from .events import _per_type +from .mission import MissionHistory +from .nodes import Uncertain +from .space import DesignSpace +from .values import is_number + +ELEMENTS = ("development", "production", "launch", "operations") +"""The elements of the cost of a constellation.""" + +_PATH_CHARACTERS = (".", "[", "]") +"""Characters of the paths of values of designs, which names of scores lack.""" + +COMMON = "common" +"""The name of the common score of the growth of components (see +`CostModel.draw`), which no component may have.""" + + +@dataclass(frozen=True) +class Triangular: + """ + A triangular distribution of the growth of a cost, from `low` to `high` + and most likely `mode` (by default 1, the estimate), such as of a + component of a given maturity: wider and skewed further up for new + components than for existing ones. For example, formal risk assessments + of satellites have used growths from 0.827 to 2.274 for new components, + 0.904 to 1.708 for modified ones, and 0.981 to 1.140 for existing ones + (M. W. Maier, K. L. Yeakel, and E. B. Wendoloski, "Cost Variance Analysis + in Constellation Architecture Studies," IEEE Systems Journal 17(2), + 2023, Table I): `Triangular(0.827, 2.274)`. (The mode is given by name, + as the bounds of such tables are, unlike the arguments of + `Uncertain.triangular`, which are in order of value.) + + Args: + low (float): The lowest growth. + high (float): The highest growth. + mode (float): The most likely growth. + """ + + low: float + high: float + _: dataclasses.KW_ONLY + mode: float = 1.0 + + def __post_init__(self): + if not 0 <= self.low <= self.mode <= self.high or self.low == self.high: + raise ValueError("growth must satisfy 0 <= low <= mode <= high, low < high") + + def mean(self) -> float: + """ + Gets the mean growth. + + Returns: + float: the mean + """ + return (self.low + self.mode + self.high) / 3 + + def std(self) -> float: + """ + Gets the standard deviation of the growth. + + Returns: + float: the standard deviation + """ + a, b, c = self.low, self.mode, self.high + return math.sqrt((a * a + b * b + c * c - a * b - a * c - b * c) / 18) + + def ppf(self, q: float) -> float: + """ + Gets the quantile of the growth at a probability (the inverse of its + cumulative distribution). + + Args: + q (float): The probability, in [0, 1]. + + Returns: + float: the growth + """ + low, mode, high = self.low, self.mode, self.high + split = (mode - low) / (high - low) + if q <= split: + return low + math.sqrt(q * (high - low) * (mode - low)) + return high - math.sqrt((1 - q) * (high - low) * (high - mode)) + + +@dataclass(frozen=True) +class Component: + """ + A component of a type of satellite (such as its bus, an instrument, or + its software), whose costs of development and of its first unit grow by + the same factor: a number, or a distribution (an object with methods + `ppf` and `mean`, such as `Triangular`). A component's growth is drawn + from the distribution by its score (see `CostModel.draw`), and is + otherwise the mean of the distribution, so that estimates without drawn + growth are expected costs. + + Components are identified by name: those of the same name draw the same + score, in every type of satellite and design (such as an instrument + that several types carry), and the types of satellites of a cost model + that carry a component develop it once (see `CostModel.estimate`). + + Args: + name (str): The name. + development (float): The nonrecurring cost. + first_unit (float): The recurring cost of the first unit. + growth (Any): The growth factor of its costs, or its distribution. + """ + + name: str + development: float = 0.0 + first_unit: float = 0.0 + growth: Any = 1.0 + + def __post_init__(self): + if not isinstance(self.name, str) or not self.name: + raise ValueError("a component needs a name") + if self.development < 0 or self.first_unit < 0: + raise ValueError("costs must not be negative") + if is_number(self.growth): + if self.growth < 0: + raise ValueError("growth must not be negative") + elif not (hasattr(self.growth, "ppf") and hasattr(self.growth, "mean")): + raise TypeError( + "growth must be a number or a distribution with methods ppf and mean" + ) + + @property + def uncertain(self) -> bool: + """bool: Whether its growth is drawn from a distribution.""" + return not is_number(self.growth) + + @property + def factor(self) -> float: + """float: Its growth factor (or the mean of its distribution).""" + if self.uncertain: + return float(self.growth.mean()) + return float(self.growth) + + +@dataclass(frozen=True) +class SatelliteCost: + """ + The cost of a type of satellite (bus and payload): a nonrecurring + `development` cost, and the recurring cost of its units, from that of + the first (`first_unit`, the theoretical first unit) by a learning curve: + unit `k` costs `first_unit * k ** log2(learning_rate)`, so that each + doubling of the units built costs `learning_rate` times as much per unit + (typically 0.85 to 0.95 for satellites, 1 for no learning). + + The costs may also be, or include, those of its components (such as its + bus and instruments, see `Component`), each with its growth: the costs + of the type are its own and those of its components, grown by their + factors (`total_development` and `total_first_unit`, of the type + alone). The growths of components may be correlated (when drawn, see + `CostModel.correlation`). + + Satellites may be produced in blocks of `block_size` units, each block + after the first a new design of the type (as its components become + obsolete over a long mission of replacements): its development is + repeated (a share of it, `redevelopment`, 1 for a full redesign) before + its first unit is produced, and the learning curve restarts with its + first unit, so that a type replaced over decades costs the development + and first units of each block (as in M. W. Maier, K. L. Yeakel, and E. + B. Wendoloski, "Cost Variance Analysis in Constellation Architecture + Studies," IEEE Systems Journal 17(2), 2023). Smaller blocks cost more + developments and first units for the same satellites. + + Args: + development (float): The nonrecurring cost (besides that of its + components). + first_unit (float): The recurring cost of the first unit (besides + that of its components). + learning_rate (float): The learning rate, in (0, 1]. + components (Sequence[Component]): The components, if any, of + distinct names. + block_size (int | None): The units of each block of production, or + `None` for one block of every unit. + redevelopment (float): The share of the development (with that of + its components, `total_development`) repeated for each block + after the first. + """ + + development: float = 0.0 + first_unit: float = 0.0 + learning_rate: float = 1.0 + components: Sequence[Component] = () + block_size: int | None = None + redevelopment: float = 1.0 + + def __post_init__(self): + if not 0 < self.learning_rate <= 1: + raise ValueError("learning_rate must be in (0, 1]") + if self.development < 0 or self.first_unit < 0: + raise ValueError("costs must not be negative") + if self.block_size is not None and ( + isinstance(self.block_size, bool) + or not isinstance(self.block_size, numbers.Integral) + or self.block_size < 1 + ): + raise ValueError("block_size must be a positive integer (or None)") + if self.redevelopment < 0: + raise ValueError("redevelopment must not be negative") + components = tuple(self.components) + if not all(isinstance(c, Component) for c in components): + raise TypeError("components must be Components") + names = [c.name for c in components] + if len(set(names)) < len(names): + raise ValueError( + "the components of a type of satellite need distinct names" + ) + object.__setattr__(self, "components", components) + + @property + def total_development(self) -> float: + """float: The nonrecurring cost, with those of its components grown + by their factors (of the type alone: types that share a component + develop it once, see `CostModel.estimate`).""" + return self.development + sum(c.development * c.factor for c in self.components) + + @property + def total_first_unit(self) -> float: + """float: The recurring cost of the first unit, with those of its + components grown by their factors.""" + return self.first_unit + sum(c.first_unit * c.factor for c in self.components) + + def production(self, units: int) -> float: + """ + Gets the recurring cost of building units (the sum of the costs of + units 1 to `units` on the learning curve, from `total_first_unit`, + which restarts with each block). + + Args: + units (int): The number of units. + + Returns: + float: the cost + """ + if units <= 0: + return 0.0 + exponent = math.log2(self.learning_rate) + size = units if self.block_size is None else int(self.block_size) + full, rest = divmod(units, size) + + def curve(count: int) -> float: + return float(np.sum(np.arange(1, count + 1) ** exponent)) + + return float(self.total_first_unit * (full * curve(size) + curve(rest))) + + def blocks(self, units: int) -> int: + """ + Gets the number of blocks of production that building units starts. + + Args: + units (int): The number of units. + + Returns: + int: the blocks (1 for any units without a block size) + """ + if units <= 0: + return 0 + if self.block_size is None: + return 1 + return -(-units // int(self.block_size)) + + +@dataclass(frozen=True) +class LaunchCost: + """ + The cost of launches: of each launch of a deployment (dedicated + launches, see `DeploymentSchedule` for their capacity), and prices per + satellite and per kg (as of rideshares). Give the fields of the launch + service of a study and leave the others zero. + + Args: + per_launch (float): The cost of a launch. + per_satellite (float): The cost of launching each satellite. + per_kg (float): The cost of launching each kg of satellite. + """ + + per_launch: float = 0.0 + per_satellite: float = 0.0 + per_kg: float = 0.0 + + +@dataclass(frozen=True) +class OperationsCost: + """ + The cost of operating a constellation: a fixed cost per year (such as + the mission operations center) and a cost per satellite and year. + + Args: + per_year (float): The fixed cost of each year. + per_satellite_year (float): The cost of each satellite in each year. + """ + + per_year: float = 0.0 + per_satellite_year: float = 0.0 + + +def _spread( + amount: float, begin: float, end: float, until: float = math.inf +) -> list[tuple[float, float]]: + """ + Spreads an amount evenly from `begin` to `end` (years), in parts within + the years from the start of development (so that each falls in its year + of `CostEstimate.annual`), each dated at its middle (or at `begin`, if it + has no duration), the parts before `until` (the end of a sustained + mission). + """ + if end <= begin: + return [(begin, amount)] if begin < until else [] + flows = [] + time, stop = begin, min(end, until) + while time < stop - 1e-12: + step = min(math.floor(time + 1e-9) + 1 - time, stop - time) + flows.append((time + step / 2, amount * step / (end - begin))) + time += step + return flows + + +@dataclass +class CostEstimate: + """ + An estimate of the life-cycle cost of a constellation (see + `CostModel.estimate`). + """ + + development: float = 0.0 + """float: The nonrecurring cost of the types of satellites.""" + production: float = 0.0 + """float: The recurring cost of the units built.""" + launch: float = 0.0 + """float: The cost of launches.""" + operations: float = 0.0 + """float: The cost of operations.""" + units: dict[Any, int] = field(default_factory=dict) + """dict: The units built of each type of satellite, by type (`None` for + the satellites of a deployment of one type without a type), including + replacements and spares, and those in production at the end of a + sustained mission.""" + launches: int = 0 + """int: The launches (including those that fail).""" + flows: list[tuple[float, str, float]] = field(default_factory=list) + """list: The dated costs: the time (years from the start of + development), element, and amount of each.""" + present: dict[str, float] = field(default_factory=dict) + """dict: The present value of each element.""" + blocks: dict[Any, int] = field(default_factory=dict) + """dict: The blocks of production of each type of satellite, by type + (see `units` and `SatelliteCost.block_size`).""" + + @property + def total(self) -> float: + """float: The total cost.""" + return self.development + self.production + self.launch + self.operations + + @property + def present_value(self) -> float: + """float: The present value of the total cost.""" + return float(sum(self.present.values())) + + def annual(self) -> pd.DataFrame: + """ + Gets the cost of each year (from the start of development), by + element and in total. + + Returns: + pandas.DataFrame: a row per year, a column per element, and the + `total` + """ + frame = pd.DataFrame(self.flows, columns=["time", "element", "amount"]) + if len(frame) == 0: + return pd.DataFrame(columns=[*ELEMENTS, "total"]) + frame["year"] = np.floor(frame["time"]).astype(int) + table = frame.pivot_table( + index="year", columns="element", values="amount", aggfunc="sum" + ) + table = table.reindex(columns=list(ELEMENTS)).fillna(0.0) + table = table.reindex(range(table.index.min(), table.index.max() + 1)) + table = table.fillna(0.0) + table["total"] = table.sum(axis=1) + return table + + def metrics(self) -> dict[str, float]: + """ + Gets the cost as metrics of an evaluation (see `Study`): the total + (`cost`), each element (`cost development`, `cost production`, `cost + launch`, and `cost operations`), the present value of the total + (`cost present`), and the cost of its most expensive year (`cost peak + annual`). + + Returns: + dict[str, float]: the metrics + """ + annual = self.annual() + return { + "cost": self.total, + **{f"cost {element}": getattr(self, element) for element in ELEMENTS}, + "cost present": self.present_value, + "cost peak annual": ( + float(annual["total"].max()) if len(annual) > 0 else 0.0 + ), + } + + +Growth = float | Mapping[str, float | Mapping[Any, float]] +"""Growth factors of costs: one for every element, or by element (see +`ELEMENTS`, others 1), and of development, production, and launches, by +type of satellite (a mapping of each type to its factor).""" + + +@dataclass(frozen=True) +class CostModel: + """ + A model of the life-cycle cost of constellations: the costs of their + types of satellites, launches, and operations, applied to their + deployments (see `DeploymentSchedule`), and the discount rate of their + present value. + + A cost at time `t` (years from the start of development, which begins + `start` years after the present) has a present value of `cost / (1 + + discount_rate) ** (start + t)`. + + The growths of the components of satellites (see `Component`) may be + correlated (when drawn, see `draw`): costs estimated together tend to be + underestimated together, as are those of the software and management of + a satellite whose payload costs more than estimated. A correlation of + 0.5 between the components of a satellite is commonly assumed; here, it + is of every pair of components of the model (such as of the instruments + of different types of satellites, estimated alike). + + Args: + satellites (SatelliteCost | Mapping[Any, SatelliteCost]): The cost of + the satellites, or of each type of satellite (by type). The + components of the same name of different types must be the same + (equal costs and growth). + launch (LaunchCost): The cost of launches. + operations (OperationsCost): The cost of operations. + discount_rate (float): The annual discount rate (such as 0.03). + start (float): The years from the present to the start of + development. + correlation (float): The correlation of the scores of the components + (see `draw`), in [0, 1]. + """ + + satellites: SatelliteCost | Mapping[Any, SatelliteCost] + launch: LaunchCost = LaunchCost() + operations: OperationsCost = OperationsCost() + discount_rate: float = 0.0 + start: float = 0.0 + correlation: float = 0.0 + + def __post_init__(self): + if self.discount_rate <= -1: + raise ValueError("discount_rate must be greater than -1") + if not 0 <= self.correlation <= 1: + raise ValueError("correlation must be in [0, 1]") + components: dict[str, Component] = {} + for _, cost in self._types(): + for component in cost.components: + if component.name == COMMON: + raise ValueError( + f"{COMMON!r} names the common score of cost risk, not a component" + ) + if components.setdefault(component.name, component) != component: + raise ValueError( + f"the components named {component.name!r} differ: types of " + + "satellites that share a component share its costs and growth" + ) + + def discount(self, time: float) -> float: + """ + Gets the factor of the present value of a cost at a time. + + Args: + time (float): The time (years from the start of development). + + Returns: + float: the factor + """ + return float((1 + self.discount_rate) ** -(self.start + time)) + + def satellite_cost_of(self, kind: Any = None) -> SatelliteCost: + """ + Gets the cost of a type of satellite. + + Args: + kind (Any): The type, or `None` for a model of one type. + + Returns: + SatelliteCost: the cost + """ + if isinstance(self.satellites, SatelliteCost): + return self.satellites + if kind is None: + raise ValueError("a model of several types of satellites needs a type") + return _per_type(self.satellites, kind, "cost") + + def _types(self) -> list[tuple[Any, SatelliteCost]]: + """Gets the types of satellites: each type, and its cost.""" + if isinstance(self.satellites, SatelliteCost): + return [(None, self.satellites)] + return list(self.satellites.items()) + + def score_names(self) -> list[str]: + """ + Gets the names of the scores from which the growth of the components + is drawn (see `draw`): those of the components with distributions of + growth, after the common score (`"common"`) if they are correlated. + + Returns: + list[str]: the names, in the order of the types and components + """ + names = list( + dict.fromkeys( + component.name + for _, cost in self._types() + for component in cost.components + if component.uncertain + ) + ) + if names and self.correlation > 0: + names.insert(0, COMMON) + return names + + def draw(self, scores: Mapping[str, float]) -> CostModel: + """ + Draws the growth of the costs of the components of its types of + satellites (see `Component`) from their scores: standard normal + values of the components and a common score (by name, see + `score_names`), such as uncertain parameters of a design space drawn + for each replicate (see `risk_space`). The growth of a component is + the quantile of its distribution at the normal probability of its + score, mixed with the common score by the correlation (ρ, see + `correlation`): `sqrt(ρ) * score["common"] + sqrt(1 - ρ) * + score[component]`. The growths of the components are then + correlated (by about ρ), and a component that several types of + satellites carry has the same growth in each. + + With common random numbers (see `Design.realize`), a component (and + the common score) has the same score in the same replicate of every + design, so that designs that share it share its growth: the costs of + designs are correlated by what they share, and comparisons between + them (such as `exceedance`) see the differences of their costs + rather than of independent draws. + + Args: + scores (Mapping[str, float]): The scores, by name (others are + ignored). + + Returns: + CostModel: the cost model, whose components have the drawn growths + + Raises: + ValueError: if a score is missing. + """ + names = self.score_names() + missing = [name for name in names if name not in scores] + if missing: + raise ValueError(f"no scores of {missing}") + common = float(scores[COMMON]) if COMMON in names else 0.0 + probabilities = {} + for name in names: + if name != COMMON: + score = math.sqrt(self.correlation) * common + math.sqrt( + 1 - self.correlation + ) * float(scores[name]) + probabilities[name] = 0.5 * (1 + math.erf(score / math.sqrt(2))) + drawn = {} + for kind, cost in self._types(): + components = tuple( + ( + dataclasses.replace( + component, + growth=float( + component.growth.ppf(probabilities[component.name]) + ), + ) + if component.uncertain + else component + ) + for component in cost.components + ) + drawn[kind] = dataclasses.replace(cost, components=components) + if isinstance(self.satellites, SatelliteCost): + return dataclasses.replace(self, satellites=drawn[None]) + return dataclasses.replace(self, satellites=drawn) + + def estimate( + self, deployment: Deployment | MissionHistory, growth: Growth = 1.0 + ) -> CostEstimate: + """ + Estimates the life-cycle cost of a deployment (its history without + failures, with the stages that their rules deploy and the spares of + its policy, see `Deployment.planned`) or of a simulated mission (see + `Deployment.simulate`), with the satellites and launches its failures + and restorations take, + dating its costs: the development of each type of satellite, spread + over its development; the production of its units (including spares, + replacements, and restorations) along its learning curve, spread over + their production; each launch (including those that fail), when it + flies; a fixed cost of operations over the mission; and the + operations of each satellite while it is in orbit (operating, or a + spare waiting). The costs of types of satellites include those of + their components, grown by their factors (drawn, see `draw`, or + otherwise the means of their distributions, for expected costs). A + component that several types of the deployment carry is developed + once, with the type whose development ends first (and by its growth + factor), and produced with each type (on its learning curve). Each + block of production after the first (see `SatelliteCost.block_size`) + develops its type again (a share of its development), dated over the + type's development just before the production of its first unit. + Every type of satellite of the deployment is developed, including a + type whose planes are all staged (see `Stage`) and whose stages are + never deployed: its development is the cost of the option to deploy + them. Launches priced by mass (see `LaunchCost.per_kg`) take the + masses of the satellites of the deployment (see + `DeploymentSchedule.plan`, and `MissionPlan.masses`), which also + limit the satellites of a launch. + + The costs of a sustained constellation (see `DeploymentSchedule`), + such as of an operational program over the period of a study, are + those incurred by the end of the mission: of each cost spread over a + duration (the development of each type and block, and the production + of each batch of satellites), the share before the end, so that the + units in production at the end count by the share produced (as in M. + W. Maier, K. L. Yeakel, and E. B. Wendoloski, "Cost Variance Analysis + in Constellation Architecture Studies," IEEE Systems Journal 17(2), + 2023), and a later block counts the share of its development before + the end, whether or not its first unit is in production. The units + (and blocks) of the estimate are those whose production begins + before the end. + + Growth factors multiply the estimate, such as uncertain parameters of + cost growth drawn for each replicate (for example, + `Uncertain.triangular(0.9, 1.0, 1.5)`), whose + statistics over the replicates give the cost at a confidence level + (such as the 0.7 `Quantile`). Factors of each type of satellite (such + as `{"development": {"narrow": "growth_narrow", "wide": + "growth_wide"}}` in a `MissionPlan`) are independent between types + but shared by the designs of each type of a replicate (with common + random numbers, see `Design.realize`), so that the costs of designs + are correlated by the types of satellites they share. Do not use + uncertain growth in constraints of a design space, which see their + nominal values (`NaN`). + + Args: + deployment (Deployment | MissionHistory): The deployment (see + `DeploymentSchedule.plan`), or a simulated mission. + growth (float | Mapping): A growth factor of the cost, or of each + element (`"development"`, `"production"`, `"launch"`, or + `"operations"`; others 1), and of development, production, and + launches, of each type of satellite (a mapping of each type of + the deployment to its factor). + + Returns: + CostEstimate: the estimate + + Raises: + ValueError: if growth names an unknown element, is of operations + by type of satellite, or lacks a type of the deployment, or if + launches priced by mass lack the mass of a type. + """ + factors = _get_growth(growth) + history = ( + deployment.planned() if isinstance(deployment, Deployment) else deployment + ) + masses = {kind: history.masses.get(kind) for kind in history.development} + if self.launch.per_kg > 0 and any(mass is None for mass in masses.values()): + raise ValueError( + "launches priced by mass require the masses of the deployment " + + "(see DeploymentSchedule.plan and MissionPlan.masses)" + ) + # the costs of a sustained constellation are those incurred by the end + until = history.end if history.schedule.sustained else math.inf + flows: list[tuple[float, str, float]] = [] + + def add( + element: str, amounts: list[tuple[float, float]], kind: Any = None + ) -> None: + factor = _get_factor(factors, element, kind) + flows.extend((time, element, amount * factor) for time, amount in amounts) + + estimate = CostEstimate() + self._add_development(history, until, add) + begun = self._add_production(history, until, add) + estimate.units = dict(begun) + estimate.blocks = { + kind: self.satellite_cost_of(kind).blocks(units) + for kind, units in begun.items() + } + estimate.launches = self._add_launches(history, masses, add) + self._add_operations(history, add) + flows = [flow for flow in flows if flow[2] != 0] + estimate.flows = sorted(flows, key=lambda flow: (flow[0], flow[1])) + for element in ELEMENTS: + setattr( + estimate, + element, + float(sum(amount for _, kind, amount in flows if kind == element)), + ) + estimate.present = { + element: float( + sum( + amount * self.discount(time) + for time, kind, amount in flows + if kind == element + ) + ) + for element in ELEMENTS + } + return estimate + + def _add_development( + self, history: MissionHistory, until: float, add: Callable[..., None] + ) -> None: + """ + Adds the development of each type of satellite, spread over its + development: its own, and that of the components that no type + developed before it (in the order their developments end). + """ + developed: set[str] = set() + for kind, ends in sorted(history.development.items(), key=lambda item: item[1]): + cost = self.satellite_cost_of(kind) + amount = cost.development + sum( + c.development * c.factor + for c in cost.components + if c.name not in developed + ) + developed.update(c.name for c in cost.components) + add("development", _spread(amount, 0.0, ends, until), kind) + + def _add_production( + self, history: MissionHistory, until: float, add: Callable[..., None] + ) -> dict[Any, int]: + """ + Adds the production of each batch of satellites, on its type's + learning curve, spread over its production, and the development of + each later block of production, before its first unit, returning the + units begun before `until` of each type. + """ + built: dict[Any, int] = {} + begun: dict[Any, int] = {} + for batch in history.production: + cost = self.satellite_cost_of(batch.kind) + before = built.get(batch.kind, 0) + amount = cost.production(before + batch.satellites) - cost.production( + before + ) + built[batch.kind] = before + batch.satellites + if batch.begin < until: + begun[batch.kind] = begun.get(batch.kind, 0) + batch.satellites + add( + "production", + _spread(amount, batch.begin, batch.end, until), + batch.kind, + ) + if cost.block_size is None or cost.redevelopment <= 0: + continue + # the development of each later block, before its first unit + duration = history.development.get(batch.kind, 0.0) + size = int(cost.block_size) + pace = (batch.end - batch.begin) / batch.satellites + for unit in range(before, before + batch.satellites): + if unit > 0 and unit % size == 0: + begins = batch.begin + (unit - before) * pace + add( + "development", + _spread( + cost.redevelopment * cost.total_development, + begins - duration, + begins, + until, + ), + batch.kind, + ) + return begun + + def _add_launches( + self, + history: MissionHistory, + masses: Mapping[Any, float | None], + add: Callable[..., None], + ) -> int: + """Adds the price of each launch when it flies, returning the launches.""" + for launch in history.launches: + mass = masses.get(launch.kind) or 0.0 + price = self.launch.per_launch + launch.satellites * ( + self.launch.per_satellite + self.launch.per_kg * mass + ) + add("launch", [(launch.time, price)], launch.kind) + return len(history.launches) + + def _add_operations( + self, history: MissionHistory, add: Callable[..., None] + ) -> None: + """ + Adds the operations of each satellite while it is in orbit, and the + fixed operations over the mission. + """ + for start, stop, count in history.in_orbit(): + amount = self.operations.per_satellite_year * count * (stop - start) + add("operations", _spread(amount, start, stop)) + begin, end = history.begin, history.end + add("operations", _spread(self.operations.per_year * (end - begin), begin, end)) + + +def _get_growth(growth: Growth) -> dict[str, float | dict[Any, float]]: + """ + Gets the growth factor of each element of cost (or a mapping of each type + of satellite to its factor). + """ + if not isinstance(growth, Mapping): + return {element: float(growth) for element in ELEMENTS} + unknown = set(growth) - set(ELEMENTS) + if unknown: + raise ValueError(f"growth of unknown elements: {sorted(unknown)}") + factors: dict[str, float | dict[Any, float]] = {} + for element in ELEMENTS: + value = growth.get(element, 1.0) + if isinstance(value, Mapping): + if element == "operations": + raise ValueError("the growth of operations is not by type of satellite") + factors[element] = {kind: float(factor) for kind, factor in value.items()} + else: + factors[element] = float(value) + return factors + + +def _get_factor( + factors: Mapping[str, float | Mapping[Any, float]], element: str, kind: Any +) -> float: + """ + Gets the growth factor of an element of the cost of a type of satellite + (`None` for costs of no type). + """ + factor = factors[element] + if isinstance(factor, Mapping) and kind is None: + raise ValueError(f"growth of {element} by type of satellite needs types") + return _per_type(factor, kind, f"growth of {element}") + + +def risk_space(*models: CostModel) -> DesignSpace: + """ + Gets a group of a design space of the scores of the cost risk of cost + models (from which the growth of their components is drawn, see + `CostModel.draw`): an uncertain standard normal value of each name of + their scores (see `CostModel.score_names`), drawn for each replicate:: + + space = space.extend(cost_risk=risk_space(COST_MODEL)) + PLAN = MissionPlan(SCHEDULE, COST_MODEL, kind="payload", scores="cost_risk") + + With common random numbers (see `Design.realize`), each name has the same + score in the same replicate of every design, so that the designs that + share a component share its growth. The variance of costs (or of the + differences of the costs of designs) may be attributed to each component + by the paths of its score (such as `"cost_risk.imager"`, see + `attribute_variance`), and to the risk that components share by that of + the common score (`"cost_risk.common"`); a scenario may give a score a + value (such as 1.28, for a growth at the 0.9 quantile of a component + without correlation). + + Args: + *models (CostModel): The cost models (such as the models of the + designs of a study, whose scores are shared by name). + + Returns: + DesignSpace: the group of scores, by name + + Raises: + ValueError: if a name has a character of paths (`.`, `[`, or `]`), or + is reserved (see `DesignSpace`, such as `index` or `count`). + """ + names = list( + dict.fromkeys(name for model in models for name in model.score_names()) + ) + invalid = [n for n in names if any(c in n for c in _PATH_CHARACTERS)] + if invalid: + raise ValueError(f"names of scores must not have '.', '[', or ']': {invalid}") + return DesignSpace(**{name: Uncertain.normal(0.0, 1.0) for name in names}) diff --git a/src/tatc/tradespace/criteria.py b/src/tatc/tradespace/criteria.py new file mode 100644 index 0000000..5a8f995 --- /dev/null +++ b/src/tatc/tradespace/criteria.py @@ -0,0 +1,498 @@ +""" +Criteria by which designs are judged from the statistics of the metrics of +their evaluations over their replicates (see `Statistic`): objectives to +minimize or maximize, requirements on statistics, the tolerances of the +objectives, and the rules that combine the statistics of a design across +groups of its results (such as scenarios). + +A requirement on a statistic is an output constraint, which a design meets +or violates (by an amount) once it is evaluated, as opposed to the +constraints of a design space, which are known before. + +@author: Paul T. Grogan +""" + +from __future__ import annotations + +from collections.abc import Mapping, Sequence +from dataclasses import dataclass, field +from typing import Any + +import numpy as np + +from . import tables +from .statistics import _OPERATORS, Mean, Statistic, _named_statistics + +_DIRECTIONS = ("min", "max") + + +@dataclass(frozen=True) +class Requirement: + """ + A requirement on a statistic of a design (by its name in the statistics + of criteria, see `Criteria`, or a metric, whose mean it then is): for + example, `Requirement("sufficient p10", ">=", 80)`, or + `Requirement("feasible", ">=", 1)`, which requires every replicate of a + design to be feasible (`feasible` is the share of its replicates that + are, see `summarize`). + + A design that does not meet it violates it by the difference between the + statistic and the value, relative to a `scale`: by default the magnitude + of the value (or 1 if the value is 0), so that the violations of + requirements in different units are comparable. Summaries add them (the + `violation` of a design, see `summarize`), by which the designs that miss + requirements are ranked (see `pareto_ranks` and `screen`), and the + constraint-aware optimizers of `optimize_optuna` and `optimize_pymoo` + keep each as a constraint of its own. + + Args: + name (str): The statistic (or metric). + operator (str): The comparison: `">="`, `">"`, `"<="`, or `"<"`. + value (float): The required value. + scale (float | None): The scale of violations, in the units of the + statistic, or `None` for the magnitude of the value (or 1 if it + is 0). + """ + + name: str + operator: str + value: float + scale: float | None = None + + def __post_init__(self): + if self.operator not in _OPERATORS: + raise ValueError(f"operator must be one of {list(_OPERATORS)}") + if self.scale is not None and not self.scale > 0: + raise ValueError("scale must be positive") + + def met(self, statistic: np.ndarray) -> np.ndarray: + """ + Gets whether values of the statistic meet the requirement (`False` + where they are `NaN`). + + Args: + statistic (numpy.ndarray): The values. + + Returns: + numpy.ndarray: whether each meets it + """ + values = np.asarray(statistic, dtype=float) + with np.errstate(invalid="ignore"): + return _OPERATORS[self.operator](values, self.value) + + def __str__(self) -> str: + return f"{self.name} {self.operator} {self.value:g}" + + def violation(self, statistic: np.ndarray) -> np.ndarray: + """ + Computes the violations of the requirement: 0 where the statistic + meets it, and otherwise how far it misses the value, relative to the + scale (`NaN` where the statistic is). A strict comparison that the + statistic misses by equality is violated by a small amount. + + Args: + statistic (numpy.ndarray): The statistic of each design. + + Returns: + numpy.ndarray: the violations + """ + statistic = np.asarray(statistic, dtype=float) + if self.operator in (">=", ">"): + gap = self.value - statistic + else: + gap = statistic - self.value + scale = self.scale if self.scale is not None else (abs(self.value) or 1.0) + violation = np.where(self.met(statistic), 0.0, np.maximum(gap / scale, 1e-9)) + return np.where(np.isnan(statistic), np.nan, violation) + + +_RULES = ("worst", "mean") + + +@dataclass(frozen=True) +class Across: + """ + A rule that combines the statistics of each design across the groups of + a column of the results, such as the scenarios of a study (see `Study`), + so that criteria (see `Criteria`) judge each design once, rather than in + each group (as criteria `by` the column do): each statistic is computed + over the replicates in each group, and then combined across the groups. + + * `"worst"`: a statistic is its worst value in any group: the largest of + an objective to minimize (the smallest of one to maximize), and the + worst of a statistic of requirements for them (the smallest for `">="`), + so that a design meets a requirement only if it does in every group, + as a design robust to the scenarios must. + * `"mean"`: a statistic is its mean over the groups, weighted by their + `weights` (equal if not given), as an expectation over scenarios of + these probabilities. + + `rules` combine some statistics (by name) otherwise than `rule`: for + example, objectives of the mean over scenarios, with a requirement in + every scenario on a statistic of another name:: + + Criteria( + {"accurate": "max", "satellites": "min"}, + statistics={"accurate anywhere": "accurate"}, + requirements=[Requirement("accurate anywhere", ">=", 40)], + across=Across("scenario", "mean", rules={"accurate anywhere": "worst"}), + ) + + The worst of a statistic needs its direction: that of the objective or + the requirements that name it, which must agree; other statistics are + combined by their means, unless a rule asks for their worst. The spreads + that `summarize` adds are those of the combined statistics (see + `summarize`). Requirements and tolerances apply to the combined + statistics. A design is judged only if it has feasible results in every + group of the results (in each group of the criteria's `by`). Statistics + of the feasibility of replicates (such as `feasible`, the share of a + design's replicates that are feasible, see `summarize`) are not + combined: they are over the evaluations of every group together. + + Combining the statistics of the groups (such as the worst of the means) + differs from a statistic of the worst group of each replicate (the mean + of the worst in each replicate), which, for a mean, is more pessimistic. + + Args: + column (str): The column of the groups, such as `"scenario"`. + rule (str): How statistics are combined: `"worst"` or `"mean"`. + weights (Mapping[Any, float] | None): The weights of the mean of the + groups (by value of the column), or `None` for equal weights: + normalized over the groups of the results, each of which must + have one. + rules (Mapping[str, str]): The rules of some statistics (by name), in + place of `rule`. + """ + + column: str = "scenario" + rule: str = "worst" + weights: Mapping[Any, float] | None = None + rules: Mapping[str, str] = field(default_factory=dict) + + def __post_init__(self): + if not isinstance(self.column, str) or not self.column: + raise TypeError("the column must be a name (a non-empty string)") + rules = dict(self.rules) + for rule in [self.rule, *rules.values()]: + if rule not in _RULES: + raise ValueError(f"a rule must be one of {list(_RULES)}, not {rule!r}") + weights = None if self.weights is None else dict(self.weights) + if weights is not None and not all( + np.isfinite(float(w)) and float(w) > 0 for w in weights.values() + ): + raise ValueError("the weights of groups must be positive") + object.__setattr__(self, "rules", rules) + object.__setattr__(self, "weights", weights) + + +def _weights_of(across: Across, groups: Sequence[Any]) -> np.ndarray: + """ + Gets the weights of the mean of groups (values of the column of a rule + across them), normalized to sum to 1. + """ + if across.weights is None: + return np.full(len(groups), 1.0 / max(len(groups), 1)) + missing = [group for group in groups if group not in across.weights] + if missing: + raise ValueError(f"groups of {across.column!r} without weights: {missing}") + weights = np.array([float(across.weights[group]) for group in groups]) + return weights / weights.sum() + + +Tolerance = float | str +"""A tolerance of an objective: a value in its units, or a share of its value +(a string of a percentage, such as `"5%"`).""" + + +def _tolerance_array( + objectives: Mapping[str, str], tolerances: Mapping[str, Tolerance] +) -> np.ndarray: + """ + Gets the tolerances of the objectives (zero if not given): their absolute + values (first row) and their shares of the values of the objectives + (second row), checking them. + """ + unknown = set(tolerances) - set(objectives) + if unknown: + raise ValueError(f"tolerances of names that are not objectives: {unknown}") + values = np.zeros((2, len(objectives))) + for i, name in enumerate(objectives): + value = tolerances.get(name, 0.0) + if isinstance(value, str): + if not value.strip().endswith("%"): + raise ValueError( + f"a tolerance string must be a percentage, not {value!r}" + ) + values[1, i] = float(value.strip()[:-1]) / 100 + else: + values[0, i] = float(value) + if np.any(values < 0): + raise ValueError("tolerances must not be negative") + return values + + +@dataclass(frozen=True) +class Criteria: + """ + The criteria by which designs are judged from the results of their + replicates: objectives to minimize or maximize and requirements to + meet, the statistics over the replicates that they name (see + `Statistic`), the tolerances of the objectives within which differences + do not matter, and the columns that group the records of an evaluation + (such as a sensor), in each group of which designs are judged + separately:: + + criteria = Criteria( + {"cost p70": "min", "coverage": "max"}, + statistics=[Quantile("cost", 0.7)], # named cost p70 + requirements=[Requirement("cost p70", "<=", 150)], + tolerances={"coverage": 1.0}, + ) + summary = summarize(results, criteria) + front = summary[summary.pareto] + + Objectives and requirements name statistics: those of `statistics`, or + otherwise the means of the metrics of their names. A design is + efficient if it meets the requirements and no other design that meets + them is as good in every objective and better in at least one, by more + than the tolerances (see `pareto_front`). + + Designs are judged by their feasible replicates. The share of a design's + replicates that are feasible is the statistic `feasible` (see + `summarize`), which requirements may name, such as + `Requirement("feasible", ">=", 1)` of designs feasible in every + replicate. Designs without a feasible replicate are not judged. + + Designs evaluated in several groups of a column (such as the scenarios + of a study, see `Study`) are judged in each group with criteria `by` the + column, or once with criteria `across` it (see `Across`), which combine + their statistics across the groups: their worst, or their mean. + + The functions that judge designs (`summarize`, `pareto_front`, + `pareto_ranks`, `hypervolume`, `hypervolume_progress`, + `pareto_probability`, `robustness`, `refine`, `confirm`, `screen`, and the + searches of `optimize_optuna` and `optimize_pymoo`) take criteria, or a + mapping of objectives to their directions, which are criteria of the + means of metrics alone. + + Args: + objectives (Mapping[str, str]): The objectives: statistics (or + metrics) and their directions (`"min"` or `"max"`). + statistics (Mapping[str, Statistic | str] | Sequence): Statistics, + by name, of objectives and requirements that are not means of + the metrics of their names (a metric given as a string, or a + `Utility`, is its mean), and others to compute with them (see + `summarize`), or a sequence of them, named by their conventional + names (see `Statistic.name`, such as `cost p70` of + `Quantile("cost", 0.7)`). + requirements (Sequence[Requirement]): Requirements on statistics. + tolerances (Mapping[str, float | str]): The tolerances of objectives + (by name, zero if not given): values in their units, or + percentages of their values (such as `"5%"`). + by (Sequence[str] | str): The columns that group the records of an + evaluation (such as a sensor), in each group of which designs are + judged separately. + across (Across | None): The rule that combines the statistics of + each design across the groups of a column (such as the + scenarios), if any. + """ + + objectives: Mapping[str, str] + statistics: Mapping[str, Statistic | str] | Sequence[Statistic | str] = field( + default_factory=dict + ) + requirements: Sequence[Requirement] = () + tolerances: Mapping[str, Tolerance] = field(default_factory=dict) + by: Sequence[str] | str = () + across: Across | None = None + + def __post_init__(self): + if not isinstance(self.objectives, Mapping): + raise TypeError("objectives must be a mapping of names to directions") + objectives = dict(self.objectives) + if len(objectives) == 0: + raise ValueError("at least one objective is required") + for name, direction in objectives.items(): + if direction not in _DIRECTIONS: + raise ValueError( + f"direction of {name!r} must be 'min' or 'max', not {direction!r}" + ) + statistics = _named_statistics(self.statistics) + requirements = tuple(self.requirements) + for requirement in requirements: + if not isinstance(requirement, Requirement): + raise TypeError(f"{requirement!r} is not a Requirement") + tolerances = dict(self.tolerances) + _tolerance_array(objectives, tolerances) # checks them + by = tuple(tables.names(self.by)) + object.__setattr__(self, "objectives", objectives) + object.__setattr__(self, "statistics", statistics) + object.__setattr__(self, "requirements", requirements) + object.__setattr__(self, "tolerances", tolerances) + object.__setattr__(self, "by", by) + if self.across is not None: + if not isinstance(self.across, Across): + raise TypeError("across must be an Across (or None)") + if self.across.column in by: + raise ValueError( + f"criteria cannot both group and combine {self.across.column!r}" + ) + unknown = sorted(set(self.across.rules) - set(self.names)) + if unknown: + raise ValueError(f"rules of names that are not statistics: {unknown}") + _combiners(self) # checks that each statistic has a worst, if needed + + @property + def names(self) -> list[str]: + """list[str]: The names of the statistics: of the objectives, of the + requirements, and the others of `statistics`, in that order.""" + return list( + dict.fromkeys( + [ + *self.objectives, + *(requirement.name for requirement in self.requirements), + *self.statistics, + ] + ) + ) + + @property + def metrics(self) -> list[str]: + """list[str]: The metrics (columns of the results of a study) of + the statistics.""" + return sorted( + {column for name in self.names for column in _statistic(self, name).columns} + ) + + +def _as_criteria(criteria: Criteria | Mapping[str, str]) -> Criteria: + """ + Gets criteria given as criteria, or as a mapping of objectives to their + directions (the criteria of the means of the metrics of their names). + + Raises: + TypeError: if the criteria are neither (with a hint, for metrics, + to give them as the `statistics` of `summarize`). + """ + if isinstance(criteria, Criteria): + return criteria + if isinstance(criteria, Mapping): + return Criteria(criteria) + hint = "" + if isinstance(criteria, (str, Sequence)): + hint = ( + ": give the metrics (or statistics) to summarize as `statistics`, " + + f"such as summarize(results, statistics={tables.names(criteria)!r})" + ) + raise TypeError( + "criteria must be Criteria or a mapping of objectives to their " + + f"directions, not {criteria!r}{hint}" + ) + + +def _statistic(criteria: Criteria, name: str) -> Statistic: + """ + Gets the statistic of a name of criteria: that of their `statistics`, or + the mean of the metric of the name. + """ + return criteria.statistics[name] if name in criteria.statistics else Mean(name) + + +def _resolved(criteria: Criteria) -> dict[str, Statistic]: + """Gets the statistic of each name of criteria (see `Criteria.names`).""" + return {name: _statistic(criteria, name) for name in criteria.names} + + +def _signs(criteria: Criteria) -> np.ndarray: + """ + Gets the sign of each objective of criteria that makes it a cost (to + minimize): 1 for an objective to minimize, and -1 for one to maximize. + """ + return np.array( + [ + 1.0 if direction == "min" else -1.0 + for direction in criteria.objectives.values() + ] + ) + + +def _tolerances(criteria: Criteria) -> np.ndarray: + """ + Gets the tolerances of the objectives of criteria (zero if not given), in + their order: their values in their units (first row), and their shares + of the values of the objectives (second row). + """ + return _tolerance_array(criteria.objectives, criteria.tolerances) + + +def _costs(criteria: Criteria, values: Mapping[str, Any]) -> np.ndarray: + """ + Gets the objectives of criteria as costs (to minimize, see `_signs`), + from the values of their statistics (by name, such as the columns of a + summary): maximized objectives are negated. The costs have a row per + design, and a column per objective (`NaN` where a value is missing). + """ + columns = [ + np.asarray(values[name], dtype=float) * sign + for name, sign in zip(criteria.objectives, _signs(criteria)) + ] + count = len(columns[0]) if columns else 0 + return np.column_stack(columns) if count else np.empty((0, len(columns))) + + +def _violation(criteria: Criteria, values: Mapping[str, Any], count: int) -> np.ndarray: + """ + Gets the total violation of the requirements of criteria by `count` + designs (the sum of their violations, see `Requirement.violation`), from + the values of their statistics (by name, such as the columns of a + summary): 0 if a design meets every requirement, and `NaN` where a + statistic of a requirement is. + """ + total = np.zeros(count) + for requirement in criteria.requirements: + statistic = np.asarray(values[requirement.name], dtype=float) + total = total + requirement.violation(statistic) + return total + + +def _combiners(criteria: Criteria) -> dict[str, str]: + """ + Gets how each statistic of criteria is combined across the groups of + their `across` (see `Across`), by name: by its largest (`"max"`) or + smallest (`"min"`) value, its worst, or by its `"mean"` (empty without + `across`). + + Raises: + ValueError: if the worst of a statistic is asked for but it has none, + or its objective and requirements disagree on it. + """ + across = criteria.across + if across is None: + return {} + worst: dict[str, set[str]] = {} + for name, direction in criteria.objectives.items(): + worst.setdefault(name, set()).add("max" if direction == "min" else "min") + for requirement in criteria.requirements: + sense = "min" if requirement.operator in (">=", ">") else "max" + worst.setdefault(requirement.name, set()).add(sense) + combiners = {} + for name in criteria.names: + rule = across.rules.get(name, across.rule) + if rule == "mean" or (name not in worst and name not in across.rules): + # statistics that are neither objectives nor required (such as + # others to compute with them) have no worst: their means + combiners[name] = "mean" + elif name not in worst: + raise ValueError( + f"statistic {name!r} has no worst across {across.column!r}: it " + + "is neither an objective nor required (combine it by its " + + "mean, see Across)" + ) + elif len(worst[name]) > 1: + raise ValueError( + f"the objective and requirements of statistic {name!r} disagree " + + "on its worst: give it another name (in the statistics) for each" + ) + else: + combiners[name] = next(iter(worst[name])) + return combiners diff --git a/src/tatc/tradespace/deployment.py b/src/tatc/tradespace/deployment.py new file mode 100644 index 0000000..9ebf202 --- /dev/null +++ b/src/tatc/tradespace/deployment.py @@ -0,0 +1,617 @@ +""" +Deployment of constellations: when the satellites of a design are developed, +produced, launched, and replaced, which dates their costs (see `CostModel`) +and sets the satellites that observe in each phase of the mission, for +measures of capability over the mission rather than of the full +constellation alone. + +A `DeploymentSchedule` holds the rates and durations of a study (the +mission, the design life of satellites, the development and production of +each type of satellite, and the launch cadence and capacity), from which +each design's `Deployment` follows: a design of more satellites and planes +takes longer to produce and launch. A deployment is planned with a policy +that restores the failures of its satellites or not (see +`RestorationPolicy`), and its spares, and simulates a mission +(`Deployment.simulate`) with the failures of its satellites and launches +(see `FailureModel`), drawn for each replicate: the `MissionHistory` of +what is produced and launched, which a `CostModel` prices, and of the +satellites that operate. Their changes divide the mission into phases +(`MissionHistory.phases`) of constant sets of operating satellites, each +evaluated over the study's representative period (`evaluate_phases`, which +states what these quasi-static phases assume) and combined over the mission +(`summarize_phases`), such as the time-weighted +mean of a metric and the time until it first meets a requirement. + +A deployment may be staged (see `Stage`): planes that are produced and +launched only if a rule decides to, at times during the mission, from what +it knows then (see `Decision`, which includes the capability of the +satellites in orbit), such as a second plane that is launched only if the +mission turns out to need it. Whether and how to stage a deployment +is a decision of a design, whose flexibility (the cost saved where a stage +is not needed, against the capability lost by deferring it where it is) the +analyses of a study compare with deployments that are not staged. + +@author: Paul T. Grogan +""" + +from __future__ import annotations + +import numbers +from collections.abc import Callable, Mapping, Sequence +from dataclasses import dataclass, field +from typing import Any + +import numpy as np +import pandas as pd + +from ..schemas import Satellite +from .constellations import layout_of +from .events import ( + Launch, + PlannedPlane, + Production, + _Manifest, + _per_type, + _per_type_values, + _split, +) +from .failures import FailureModel, RestorationPolicy +from .mission import Capability, Decision, MissionHistory, Phase +from .simulation import _check_sampling, _Sampler, _Simulation +from .values import Values + + +@dataclass(frozen=True) +class Stage: + """ + A stage of a deployment (see `DeploymentSchedule.plan`): planes that are + deployed only if (and when) a rule decides to. At each of its `times` + (years after the first launch) until it is deployed, the rule is given + what is known then (see `Decision`) and returns whether to deploy the + stage. A deployed stage's satellites are produced on their type's line + `lead_years` after the decision (after the work before them), and + launched at the next launch slots (in as many launches as they need, see + `DeploymentSchedule`); they are then replaced at the end of their design + life and restored if they fail, as the satellites of other planes. A + stage that is not deployed is neither produced nor launched, and its + satellites never operate; but a type of satellite whose planes are all + staged is still developed, and costs its development (see + `CostModel.estimate`), whether or not its stages are deployed: the cost + of the option to deploy them. + + A rule that depends on the values of a design (such as an uncertain + parameter or a value of a scenario, known by the time of the decision) + reads them from the design, as stages made for each design (see + `MissionPlan`) can: for example, `Stage([1], 1.0, lambda decision: + design.decorrelation_time < timedelta(hours=6))`. A rule may instead + read what the satellites in orbit achieve (see `Decision.capability`), + as a mission that does not know such values measures them: for example, + `Stage([1], 1.0, lambda decision: decision.capability["accurate"] < + 50)`, which deploys the plane if the satellites operating then sample + fewer than half the points accurately. + + Args: + planes (Sequence[int] | int): The planes of the stage (their indices, + in the order of the layouts' planes, such as integers of numpy), + produced in this order (on their types' lines) and launched in + the order they are ready. + times (float | Sequence[float]): The times of the decisions, in years + after the first launch (a number, or a sequence or array of + them). + rule (Callable | None): A function of a `Decision` that returns + whether to deploy the stage, or `None` to deploy it at the first + time (a planned delay). + lead_years (float): The time from a decision to the start of the + production of the stage's satellites (such as to procure + long-lead items). + """ + + planes: Sequence[int] | int + times: float | Sequence[float] = 0.0 + rule: Callable[[Decision], bool] | None = None + lead_years: float = 0.0 + + def __post_init__(self): + planes = self.planes + if isinstance(planes, numbers.Integral) or np.ndim(planes) == 0: + planes = (planes,) + planes = tuple(int(plane) for plane in planes) + if not planes: + raise ValueError("a stage needs planes") + if len(set(planes)) != len(planes) or min(planes) < 0: + raise ValueError("the planes of a stage must be distinct indices") + times = self.times + if isinstance(times, numbers.Real) or np.ndim(times) == 0: + times = (times,) + times = tuple(sorted(float(time) for time in times)) + if not times or times[0] < 0: + raise ValueError("a stage needs times of decisions, not negative") + if self.lead_years < 0: + raise ValueError("lead_years must not be negative") + object.__setattr__(self, "planes", planes) + object.__setattr__(self, "times", times) + + +@dataclass +class Deployment: + """ + The planned deployment of a constellation: its development, production, + launches, and planned replacements (see `DeploymentSchedule.plan`), + without failures, and the policy with which it restores the failures of + its satellites (see `simulate`). + """ + + schedule: DeploymentSchedule + """DeploymentSchedule: The schedule of the deployment.""" + planes: list[PlannedPlane] = field(default_factory=list) + """list[PlannedPlane]: The planes, in the order of the layouts' planes: + the type of their satellites, the number of satellites of the layout, + and of spares in orbit.""" + development: dict[Any, float] = field(default_factory=dict) + """dict: The end of the development of each type of satellite (years).""" + production: list[Production] = field(default_factory=list) + """list[Production]: The production of the satellites, in order (of a + sustained constellation, also of replacements launched after the end of + the mission, see `DeploymentSchedule`).""" + launches: list[Launch] = field(default_factory=list) + """list[Launch]: The launches (and planned replacements) of the mission, + in order.""" + masses: dict[Any, float | None] = field(default_factory=dict) + """dict: The mass (kg) of each type of satellite, if given.""" + plane_values: list[Any] = field(default_factory=list) + """list: The values of each plane in the design (see `Plane`), in the + order of `planes`, as given to functions of the schedule of a plane.""" + stages: tuple[Stage, ...] = () + """tuple[Stage, ...]: The stages deployed only if their rules decide to + (whose planes the production and launches above do not include).""" + policy: RestorationPolicy = field(default_factory=RestorationPolicy) + """RestorationPolicy: The policy for failed satellites, whose spares in + orbit the planes above include (and whose spares on the ground its + simulations produce, see `simulate`).""" + capability: Capability | None = field(default=None, repr=False, compare=False) + """Capability | None: The capability of the satellites, which the rules + of stages may read at their decisions (see `Decision.capability`) in + every simulation of the deployment (given to `DeploymentSchedule.plan`, + as the evaluations of an `ObservationStudy` with a `MissionPlan` give + it).""" + _planned: MissionHistory | None = field( + default=None, init=False, repr=False, compare=False + ) + + @property + def begin(self) -> float: + """float: The first launch, which begins the mission (years).""" + return min(launch.time for launch in self.launches) + + @property + def end(self) -> float: + """float: The end of the mission (years).""" + return self.begin + self.schedule.years + + @property + def deployed(self) -> float: + """float: The time by which every satellite of the first generation + is launched (years): of the planes that are not staged, and of the + stages that their rules deploy, in the history of the mission without + failures (see `planned` and `MissionHistory.deployed`, which is + infinite if the deployment does not finish within the mission).""" + return self.planned().deployed + + @property + def units(self) -> dict[Any, int]: + """dict: The satellites of each type that the plan produces: of the + planes that are not staged (with their spares in orbit) and their + planned replacements (and, of a sustained constellation, those in + production at the end of the mission), but not the spares on the + ground of the policy, the planes of stages, or restorations, which + its simulations produce (see `planned`, whose production a + `CostModel` prices).""" + units: dict[Any, int] = {} + for batch in self.production: + if not self.schedule.sustained or batch.begin < self.end: + units[batch.kind] = units.get(batch.kind, 0) + batch.satellites + return units + + def simulate( + self, + model: FailureModel | None = None, + seed: int | Sequence[int] | None = None, + ) -> MissionHistory: + """ + Simulates the mission: the deployment, with the failures of its + satellites and launches (drawn from a seed of a replicate, such as an + uncertain parameter, see `Uncertain.seed`) and the restoration of + failed satellites by its policy (see `policy`, whose spares in orbit + the plan produces and launches with their planes, and whose spares + on the ground the simulation produces after the planes of the plan). + Without a seed, nothing fails (but the spares are still produced). + To simulate another policy, plan the deployment with it (see + `DeploymentSchedule.plan`). + + A satellite's life is drawn when it is launched (or takes the place + of a failed one), from uniform numbers of a random number generator + seeded by the seed and its plane, position, and generation; the + success of a planned launch (of the deployment, or a replacement) + from one seeded by its plane, the position of its first satellite, + and its generation; and that of a launch of restorations or spares + from one seeded by its plane and its order among them: with common + random numbers, the satellite at the same position of the same plane + fails at the same age in the same replicate of every design. Spares + in orbit do not age or fail until they take a failed satellite's + place, which they then hold (and which planned replacements replace). + + A planned replacement (at the end of a design life) whose launch + fails is not flown again: the satellite it would replace operates + until it fails (and is then restored, by a policy that restores + failures). + + Args: + model (FailureModel | None): The failures, or `None` for none. + seed (int | Sequence[int] | None): The seed of the replicate (or + a sequence of integers, such as the seed and the index of a + history, see `simulate_many`), or `None` for no failures. + + Returns: + MissionHistory: the history of the mission + """ + return _Simulation(self, model or FailureModel(), seed).run() + + def planned(self) -> MissionHistory: + """ + Gets the history of the mission without failures (see `simulate`), + simulated once: its deployment, with the stages that their rules + deploy and the spares of its policy, whose costs a `CostModel` + estimates (see `CostModel.estimate`). + + Returns: + MissionHistory: the history + """ + if self._planned is None: + self._planned = self.simulate() + return self._planned + + def simulate_many( + self, + model: FailureModel | None = None, + seed: int | None = None, + *, + histories: int = 1, + sampling: str = "stratified", + stress: float = 1.0, + launch_stress: float | None = None, + ) -> list[MissionHistory]: + """ + Simulates several histories of the mission in a replicate (see + `simulate`), history `k` drawn from the seed and `k`, so that, with + common random numbers, the same history of the same replicate draws + the same failures in every design. Without a seed, the one history + without failures (of one history only). + + The failures of the histories are stratified by default + (`"stratified"`: a Latin hypercube over the histories, in which each + life and launch of each history draws from its own stratum of its + distribution, see `Lifetime.from_uniform`), which spreads the + histories over the distributions of the failures and estimates the + means of the measures of the mission more precisely than independent + histories (`"random"`), several times so for missions of a few + satellites or many, at no cost. + + With a `stress`, the failures are drawn from stressed distributions + for importance sampling, which samples rare outcomes (such as the + loss of several satellites of a reliable constellation) more often: + the hazards of the lives of the satellites times the stress, and the + probability that a launch fails times the `launch_stress` (by + default the stress, at most 0.5). Each history is weighted by its + likelihood ratio (`MissionHistory.weight`, see `Lifetime.stressed`), + which `summarize_histories` applies to every statistic. A stress + that samples the outcomes of interest about as often as the others + estimates their probabilities (and the quantiles of their tails) + with far fewer histories; too large a stress makes a few weights + dominate (see the effective number of histories). + + Many histories of the failures of a replicate, whose sample of + targets (the expensive part of an evaluation) they share, measure the + risk of a mission at little cost (see `evaluate_histories` and + `PhaseCache`). + + Args: + model (FailureModel | None): The failures, or `None` for none. + seed (int | None): The seed of the replicate, or `None` for the + one history without failures. + histories (int): The number of histories. + sampling (str): `"stratified"` or `"random"`. + stress (float): The factor of the hazards of stressed failures. + launch_stress (float | None): The factor of the probability that + a launch fails, or `None` for the stress. + + Returns: + list[MissionHistory]: the histories + + Raises: + ValueError: if the histories are fewer than 1 (or more than 1 + without a seed), the sampling is unknown, or a stress is not + positive. + """ + _check_sampling(histories, sampling, stress, launch_stress) + if seed is None: + if histories > 1: + raise ValueError( + "histories of failures need a seed: without one, the one " + + "history without failures" + ) + return [self.simulate(model, None)] + model = model or FailureModel() + launch_stress = stress if launch_stress is None else launch_stress + return [ + _Simulation( + self, + model, + (seed, k), + _Sampler(seed, k, histories) if sampling == "stratified" else None, + stress, + launch_stress, + ).run() + for k in range(histories) + ] + + def _expected_metrics( + self, + model: FailureModel | None = None, + seed: int = 0, + *, + histories: int = 1000, + sampling: str = "stratified", + ) -> dict[str, float]: + """ + Estimates the expected measures of the mission (see + `MissionHistory.metrics`, such as its `availability`) from many + simulated histories (see `simulate_many`), without evaluating their + phases: precise and cheap, as the expected values of control + variates (see `summarize_histories`, and the `controls` of + `Failures`). + """ + simulated = self.simulate_many( + model, seed, histories=histories, sampling=sampling + ) + rows = pd.DataFrame([history.metrics() for history in simulated]) + return {column: float(rows[column].mean()) for column in rows.columns} + + def phases(self, satellites: Sequence[Satellite | str]) -> list[Phase]: + """ + Gets the phases of the mission without failures (see + `MissionHistory.phases`), each evaluated over the same window (see + `evaluate_phases`). + + Args: + satellites (Sequence[Satellite | str]): The satellites (or their + names), in the order of the planes. + + Returns: + list[Phase]: the phases, in order + """ + return self.planned().phases(satellites) + + +@dataclass(frozen=True) +class DeploymentSchedule: + """ + A schedule of the deployment of constellations, from rates and + durations, so that each design's deployment follows from its satellites + and planes (see `plan`). Times are in years from the start of + development. + + * Each type of satellite is developed over `development_years` (one for + every type, or one for each). + * Its satellites are then produced on one line at `production_rate` + satellites a year (or at once, if `None`), plane by plane, in the + order of the layouts' planes (or of `order`), with the spares in orbit + of the deployment's policy. The line also produces, after the work + before them, the spares on the ground of the policy, the planes of + stages that are deployed, and the satellites that restore failed ones + (see `RestorationPolicy` and `Stage`). + * Each plane is launched when its satellites are ready, in as many + launches as its satellites need (given a `launch_capacity` in number + or mass, or one per plane), at most one every `launch_interval` years, + in the order the planes are ready. + * The mission lasts `years` from the first launch. Satellites are + replaced at the end of their `design_life` (one for every type, or one + for each; if before the end of the mission): those at the positions of + the layout that each launch carries, not its spares in orbit, which do + not age (see `Deployment.simulate`). Each replacement is produced at + the production rate just before it is needed (planned apart from the + line, so that replacements do not wait for each other) and launched + at the next launch slot then (keeping the launch interval), and is + replaced in turn a design life after its launch. A design life does + not retire a satellite: one that is not replaced (as near the end of + the mission, or if its replacement's launch fails) operates until it + fails (by the wear-out of its life, see `FailureModel`). + * A `sustained` constellation (such as of an operational program, whose + mission is the period of a study) is replaced after the end of the + mission as before it: the replacements needed after the end are + produced (their production begun before the end, or within the + development years of their type after it, for the development of a + later block of production, see `SatelliteCost.block_size`), though + not launched in the mission, and its costs are those incurred by the + end (see `CostModel.estimate`), which count the units in production + at the end by the share produced. + + A schedule that is itself a decision (such as the launch cadence) is a + design variable, with the schedule made for each design (such as with + `dataclasses.replace`). + + Args: + years (float): The duration of the mission, from the first launch. + design_life (float | Mapping | None): The design life of the + satellites (of each type), or `None` if they last the mission (or + fail, see `Deployment.simulate`). + development_years (float | Mapping): The duration of development of + each type of satellite, before production. + production_rate (float | Mapping | None): The satellites of each type + produced a year, or `None` for production that takes no time. + launch_interval (float): The least time between launches. + launch_capacity (int | None): The most satellites of a launch, if + limited. + launch_mass_capacity (float | Callable | None): The most mass (kg) of + a launch, if limited (which requires the masses of the + satellites): a value, or a function of the index and values of a + plane (see `Plane`, as for `order`), such as for planes at + different inclinations, to which a launcher lifts different + masses. + order (Callable | None): A function of the index and values of a + plane (`None` for the planes of a Walker layout) that gives the + key by which its type's planes are produced and launched, if + not in the order of the layouts. + sustained (bool): Whether the constellation is replaced after the + end of the mission, whose costs are then those incurred by the + end. + """ + + years: float = 1.0 + design_life: float | Mapping[Any, float] | None = None + development_years: float | Mapping[Any, float] = 0.0 + production_rate: float | Mapping[Any, float] | None = None + launch_interval: float = 0.0 + launch_capacity: int | None = None + launch_mass_capacity: float | Callable[[int, Any], float] | None = None + order: Callable[[int, Any], Any] | None = None + sustained: bool = False + + def __post_init__(self): + if self.years <= 0: + raise ValueError("years must be positive") + if any( + life is not None and life <= 0 + for life in _per_type_values(self.design_life) + ): + raise ValueError("design_life must be positive") + if self.launch_interval < 0: + raise ValueError("launch_interval must not be negative") + if self.launch_capacity is not None and self.launch_capacity < 1: + raise ValueError("launch_capacity must be at least 1") + if any( + rate is not None and rate <= 0 + for rate in _per_type_values(self.production_rate) + ): + raise ValueError("production_rate must be positive") + if any(years < 0 for years in _per_type_values(self.development_years)): + raise ValueError("development_years must not be negative") + + def launches_of( + self, + satellites: int, + mass: float | None = None, + plane: tuple[int, Any] | None = None, + ) -> int: + """ + Gets the launches of a plane of satellites: as few as carry them (by + the capacity of launches in number and in mass, at least one). + + Args: + satellites (int): The number of satellites. + mass (float | None): The mass (kg) of each satellite. + plane (tuple[int, Any] | None): The index and values of the plane, + for a capacity in mass that is a function of the plane. + + Returns: + int: the number of launches + """ + return len(_split(self, satellites, mass, plane)) + + def plan( + self, + layout: Any, + *, + kind: Any = None, + policy: RestorationPolicy | None = None, + masses: float | Mapping[Any, float] | None = None, + stages: Sequence[Stage] = (), + capability: Capability | None = None, + ) -> Deployment: + """ + Plans the deployment of a constellation: the layout (or layouts) of + its satellites, of one type (`kind`), or a mapping of types to + layouts (such as the shells of a mixed constellation), with the + policy that restores the failures of its satellites (see + `Deployment.simulate`): its spares in orbit in each plane are + produced and launched with the plane, and wait in orbit to take the + place of failed satellites, and its spares on the ground are + produced after the planes (see `RestorationPolicy`). The planes of + `stages` are deployed only if (and when) their rules decide to, in a + simulation of the mission (see `Stage` and `Deployment.simulate`), and + the others as planned; their rules may read the `capability` of the + satellites operating at their decisions (see `Decision.capability`). + + Args: + layout (Any): The layout (or layouts) of the satellites, or a + mapping of types of satellites to layouts. + kind (Any): The type of the satellites of a layout. + policy (RestorationPolicy | None): The policy for failed + satellites, and its spares, or `None` to restore them by + producing new ones (see `RestorationPolicy`, and `MissionPlan`, + which plans the deployment of each design with its policy). + masses (float | Mapping | None): The mass (kg) of the satellites + (of each type), for a launch capacity in mass (and the price + of launches by mass, see `CostModel.estimate`). + stages (Sequence[Stage]): The stages deployed later, if their + rules decide to. + capability (Capability | None): The capability of the + satellites, in the order of the planes, if any. + + Returns: + Deployment: the deployment + + Raises: + ValueError: if a plane is in several stages or is not a plane of + the layouts, if no satellites are planned, or if the spares of + the policy lack a type of the layouts. + """ + # pylint: disable=too-many-arguments,too-many-locals + policy = RestorationPolicy() if policy is None else policy + stages = tuple(stages) + staged = [plane for stage in stages for plane in stage.planes] + if len(set(staged)) != len(staged): + raise ValueError("a plane is in several stages") + # a mapping of types to layouts (the values of a layout are a mapping too) + if isinstance(layout, Mapping) and not isinstance(layout, Values): + fleets = dict(layout) + else: + fleets = {kind: layout} + deployment = Deployment( + schedule=self, stages=stages, policy=policy, capability=capability + ) + produced = [] # the planes that are not staged, in their order + for name, item in fleets.items(): + developed = float(_per_type(self.development_years, name, "development")) + spares = policy.orbit_spares_of(name) + policy.ground_spares_of(name) # (raises if it lacks the type) + deployment.development[name] = developed + deployment.masses[name] = ( + None if masses is None else _per_type(masses, name, "mass") + ) + listed = [] + for plane in layout_of(item).planes(): + index = len(deployment.planes) + deployment.planes.append( + PlannedPlane( + name, plane.satellites, spares if plane.satellites > 0 else 0 + ) + ) + deployment.plane_values.append(plane.values) + if plane.satellites > 0 and index not in staged: + listed.append((index, plane)) + if self.order is not None: + listed.sort(key=lambda item: self.order(item[0], item[1].values)) + produced.extend(index for index, _ in listed) + unknown = sorted(set(staged) - set(range(len(deployment.planes)))) + if unknown: + raise ValueError( + f"stages of planes that the layouts do not have: {unknown}" + ) + if not produced: + raise ValueError("a deployment requires satellites (that are not staged)") + # each type's planes produced on its line from the end of its development + manifest = _Manifest(deployment, deployment.production) + deployment.launches.extend(manifest.deploy(produced, 0.0)) + deployment.production.sort(key=lambda batch: batch.begin) + deployment.launches.sort(key=lambda launch: (launch.time, launch.plane)) + return deployment diff --git a/src/tatc/tradespace/dominance.py b/src/tatc/tradespace/dominance.py new file mode 100644 index 0000000..34e04e6 --- /dev/null +++ b/src/tatc/tradespace/dominance.py @@ -0,0 +1,142 @@ +""" +Dominance between points of several costs (objectives to minimize, such as +the objectives of designs, see `pareto_front`), with tolerances within +which differences do not matter. + +@author: Paul T. Grogan +""" + +from __future__ import annotations + +import numpy as np + +BLOCK_ELEMENTS = 2_000_000 +"""The most elements of the temporary arrays of a block of comparisons.""" + +CHUNK = 64 +"""The points of each chunk of a sweep (see `dominated_plain`).""" + + +def dominated_by( + points: np.ndarray, others: np.ndarray, tolerances: np.ndarray | None = None +) -> np.ndarray: + """ + Finds the points dominated by any of others, even if the other is + penalized by the tolerances (see `dominated`), comparing them in blocks + whose temporary arrays are limited to a few million elements. + + Args: + points (numpy.ndarray): The points (a row each). + others (numpy.ndarray): The others (a row each). + tolerances (numpy.ndarray | None): The tolerances of the costs (see + `dominated`), or `None` for none. + + Returns: + numpy.ndarray: whether each point is dominated + """ + beaten = np.zeros(len(points), dtype=bool) + if len(points) == 0 or len(others) == 0: + return beaten + if tolerances is None: + tolerances = np.zeros((2, points.shape[1])) + absolute, relative = tolerances + penalties = np.any(tolerances) + block = max(1, BLOCK_ELEMENTS // max(len(others) * points.shape[1], 1)) + for start in range(0, len(points), block): + part = points[start : start + block] + # [i, j]: other j dominates point i of the block + penalized = others[None, :, :] + if penalties: + penalized = penalized + absolute + relative * np.abs(part[:, None, :]) + no_worse = np.all(penalized <= part[:, None, :], axis=2) + better = np.any(penalized < part[:, None, :], axis=2) + beaten[start : start + block] = np.any(no_worse & better, axis=1) + return beaten + + +def dominated_plain(costs: np.ndarray) -> np.ndarray: + """ + Finds the points dominated by another (without tolerances) by a sweep in + lexicographic order, in which a point can only be dominated by points + before it, and is dominated by one if it is by any of the efficient + points before it (dominance is transitive). The sweep compares each + chunk of points with the efficient points before it, then those it does + not dominate with each other. + + Args: + costs (numpy.ndarray): The points (a row each). + + Returns: + numpy.ndarray: whether each point is dominated + """ + n = len(costs) + order = np.lexsort(costs.T[::-1]) + ordered = costs[order] + beaten_points = np.zeros(n, dtype=bool) + front = np.empty((0, costs.shape[1])) + for start in range(0, n, CHUNK): + part = ordered[start : start + CHUNK] + beaten = dominated_by(part, front) + # a point that an earlier efficient point dominates dominates nothing + # that it does not: compare only the others with each other + survivors = part[~beaten] + beaten[~beaten] = dominated_by(survivors, survivors) + beaten_points[order[start : start + CHUNK]] = beaten + front = np.vstack([front, part[~beaten]]) + return beaten_points + + +def dominated(costs: np.ndarray, tolerances: np.ndarray | None = None) -> np.ndarray: + """ + Finds the points (rows of costs) dominated by another, even if the other + is penalized by the tolerances: no worse in every cost, and better in at + least one, by at least its tolerance (absolute, plus a share of the + magnitude of the cost of the point it would dominate: the rows of + `tolerances`, see `criteria._tolerances`). + + A point that is dominated with tolerances is also dominated by a point + that is efficient without them: the penalty depends only on the point + dominated, so any point no worse than its dominator in every cost (as + some efficient point is) dominates it too. Points are therefore compared + only with the efficient points (see `dominated_plain`), which are few. + + Args: + costs (numpy.ndarray): The points (a row each). + tolerances (numpy.ndarray | None): The absolute tolerances of the + costs (first row) and their shares of the magnitudes of the costs + (second row), or `None` for none. + + Returns: + numpy.ndarray: whether each point is dominated + """ + plain = dominated_plain(costs) + if tolerances is None or not np.any(tolerances): + return plain + return dominated_by(costs, costs[~plain], tolerances) + + +def efficient( + costs: np.ndarray, admissible: np.ndarray, tolerances: np.ndarray | None = None +) -> np.ndarray: + """ + Finds the efficient points (rows of costs) among the admissible ones + (such as the designs that meet requirements): those that no other + admissible point dominates (see `dominated`). Points with a missing cost + (`NaN`) are neither efficient nor dominate others. + + Args: + costs (numpy.ndarray): The points (a row each). + admissible (numpy.ndarray): Whether each point is admissible. + tolerances (numpy.ndarray | None): The tolerances of the costs (see + `dominated`), or `None` for none. + + Returns: + numpy.ndarray: whether each point is efficient + """ + known = np.asarray(admissible, dtype=bool) + if len(costs) > 0: + known = known & ~np.isnan(costs).any(axis=1) + found = np.zeros(len(costs), dtype=bool) + if known.any(): + found[known] = ~dominated(costs[known], tolerances) + return found diff --git a/src/tatc/tradespace/events.py b/src/tatc/tradespace/events.py new file mode 100644 index 0000000..aea33be --- /dev/null +++ b/src/tatc/tradespace/events.py @@ -0,0 +1,365 @@ +""" +Events of the deployments of constellations: the production and launches of +satellites (see `Deployment` and `MissionHistory`), their booking on the +production lines and at the launch slots of a schedule, which plans and +simulations share, and values given for each type of satellite. + +@author: Paul T. Grogan +""" + +from __future__ import annotations + +import bisect +import heapq +import itertools +import math +from collections.abc import Mapping, Sequence +from dataclasses import dataclass +from typing import TYPE_CHECKING, Any, NamedTuple + +if TYPE_CHECKING: + from .deployment import Deployment, DeploymentSchedule + +_PerType = float | Mapping[Any, float] +"""A value for every type of satellite, or for each (a mapping by type).""" + + +def _per_type(value: Any, kind: Any, name: str) -> Any: + """ + Gets the value of a type of satellite of a value for every type or a + mapping of each (see `_PerType`), raising a `ValueError` if the mapping + lacks the type (`name` names the value in the error). + """ + if isinstance(value, Mapping): + if kind not in value: + raise ValueError(f"no {name} of satellites of type {kind!r}") + return value[kind] + return value + + +def _per_type_values(value: Any) -> list: + """ + Gets the values of every type of satellite of a value for every type or a + mapping of each (see `_PerType`), such as to validate them. + """ + return list(value.values()) if isinstance(value, Mapping) else [value] + + +def _production_years(schedule: DeploymentSchedule, kind: Any, count: int) -> float: + """ + Gets the time to produce satellites of a type on its line (0 for + production that takes no time). + """ + rate = _per_type(schedule.production_rate, kind, "production rate") + return 0.0 if rate is None else count / rate + + +def _next_slot( + schedule: DeploymentSchedule, booked: Sequence[float], ready: float +) -> float: + """ + Gets the earliest time of a launch at or after a time that keeps the + launch interval from the launches booked before (in order), as plans and + simulations book every launch: of deployments, replacements, + restorations, and spares. + """ + interval = schedule.launch_interval + time = ready + if interval > 0: + for other in booked: + if other - interval < time < other + interval: + time = other + interval + return time + + +def _per_launch( + schedule: DeploymentSchedule, + mass: float | None = None, + plane: tuple[int, Any] | None = None, +) -> float: + """ + Gets the most satellites of a launch (to a plane: its index and values, + for a capacity in mass that is a function of the plane), by the capacity + of launches in number and in mass (of satellites of a mass, kg), infinite + if not limited, raising a `ValueError` if a capacity in mass lacks the + mass (or the plane) or a satellite exceeds it. + """ + capacity = ( + math.inf if schedule.launch_capacity is None else schedule.launch_capacity + ) + mass_capacity = schedule.launch_mass_capacity + if callable(mass_capacity): + if plane is None: + raise ValueError("a launch capacity of each plane needs the plane") + mass_capacity = float(mass_capacity(*plane)) + if mass_capacity is not None: + if mass is None: + raise ValueError("a launch capacity in mass requires masses") + fits = math.floor(mass_capacity / mass) + if fits < 1: + raise ValueError("a satellite exceeds the mass capacity of a launch") + capacity = min(capacity, fits) + return capacity + + +def _split( + schedule: DeploymentSchedule, + satellites: int, + mass: float | None = None, + plane: tuple[int, Any] | None = None, +) -> list[int]: + """ + Gets the satellites of each launch of a plane: as few launches as carry + them (see `_per_launch`, at least one), sharing them evenly. + """ + capacity = _per_launch(schedule, mass, plane) + count = max(1, math.ceil(satellites / capacity)) if capacity < math.inf else 1 + return [ + satellites // count + (1 if j < satellites % count else 0) for j in range(count) + ] + + +class PlannedPlane(NamedTuple): + """A plane of a deployment (see `Deployment.planes`).""" + + kind: Any + """Any: The type of its satellites.""" + satellites: int + """int: The number of satellites of the layout (its positions).""" + orbit_spares: int + """int: The number of spares in orbit.""" + + +@dataclass(frozen=True) +class Launch: + """ + A launch of satellites of a plane (see `Deployment` and + `MissionHistory`). + """ + + time: float + """float: The time (years from the start of development).""" + plane: int + """int: The plane (its index, in the order of the layouts' planes).""" + kind: Any + """Any: The type of its satellites.""" + first: int + """int: The position in its plane of its first satellite (-1 for the + launches of restorations and spares).""" + satellites: int + """int: The number of satellites (including spares).""" + generation: int = 0 + """int: The generation (0 for the first, others planned replacements).""" + purpose: str = "deployment" + """str: `"deployment"`, `"replacement"` (planned, at the end of a + design life), `"restoration"` (of failed satellites), or `"spare"` (a + spare in orbit replenished).""" + failed: bool = False + """bool: Whether the launch failed, losing its satellites.""" + + +@dataclass(frozen=True) +class Production: + """ + The production of satellites of a type (see `Deployment` and + `MissionHistory`). + """ + + kind: Any + """Any: The type of the satellites.""" + begin: float + """float: The start of their production (years).""" + end: float + """float: The end of their production (years).""" + satellites: int + """int: The number of satellites.""" + purpose: str = "deployment" + """str: `"deployment"`, `"replacement"`, `"restoration"`, or `"spare"`.""" + + +class _Manifest: + """ + The production and launches of a deployment as they are booked, which + plans (see `DeploymentSchedule.plan`) and simulations (of the stages they + deploy, and of restorations) share: the production line of each type of + satellite, the launches booked (which later ones keep the launch + interval from, see `_next_slot`), and the production + added. + + Args: + deployment (Deployment): The deployment: its schedule, planes, masses, + and values of planes, which a plan fills as it goes. + production (list[Production]): The production, to which it adds. + lines (dict | None): The time from which each type's line is free, or + `None` for the end of its development. + booked (list[float] | None): The times of the launches booked, in + order, or `None` for none. + """ + + def __init__( + self, + deployment: Deployment, + production: list[Production], + lines: dict[Any, float] | None = None, + booked: list[float] | None = None, + ): + self.deployment, self.schedule = deployment, deployment.schedule + self.production = production + self.lines = dict(deployment.development) if lines is None else lines + self.booked = [] if booked is None else booked + + @classmethod + def resume(cls, deployment: Deployment, production: list[Production]) -> _Manifest: + """ + Gets the manifest of a planned deployment as its simulations continue + it: each type's line free after the production of its planes (or its + development), and the launches of the plan booked. + """ + lines = { + kind: max( + ( + batch.end + for batch in deployment.production + if batch.kind == kind and batch.purpose == "deployment" + ), + default=developed, + ) + for kind, developed in deployment.development.items() + } + booked = sorted(launch.time for launch in deployment.launches) + return cls(deployment, production, lines, booked) + + def plane(self, plane: int) -> tuple[int, Any]: + """The index and values of a plane (see `DeploymentSchedule`).""" + values = self.deployment.plane_values + return plane, values[plane] if plane < len(values) else None + + def capacity(self, plane: int) -> float: + """The most satellites of a launch to a plane (see `_per_launch`).""" + kind = self.deployment.planes[plane].kind + return _per_launch( + self.schedule, self.deployment.masses.get(kind), self.plane(plane) + ) + + def produce( + self, earliest: float, kind: Any, count: int, purpose: str = "deployment" + ) -> float: + """ + Produces satellites on their type's line, from a time (after the work + before them), returning when they are ready. + """ + begin = max(self.lines[kind], earliest) + ready = begin + _production_years(self.schedule, kind, count) + self.lines[kind] = ready + self.production.append(Production(kind, begin, ready, count, purpose)) + return ready + + def next_slot(self, ready: float) -> float: + """ + Gets the earliest launch at or after a time that keeps the launch + interval (see `_next_slot`), without booking it. + """ + return _next_slot(self.schedule, self.booked, ready) + + def slot(self, ready: float) -> float: + """ + Books the earliest launch at or after a time that keeps the launch + interval (see `_next_slot`), returning its time. + """ + time = self.next_slot(ready) + bisect.insort(self.booked, time) + return time + + def launch(self, plane: int, ready: float) -> list[Launch]: + """ + Launches the satellites of a plane (and its spares in orbit) when + they are ready: in as many launches as they need (see + `_split`), each at the next launch slot. + """ + kind, size, spares = self.deployment.planes[plane] + launches, first = [], 0 + for satellites in _split( + self.schedule, + size + spares, + self.deployment.masses.get(kind), + self.plane(plane), + ): + launches.append(Launch(self.slot(ready), plane, kind, first, satellites)) + first += satellites + return launches + + def deploy( + self, planes: Sequence[int], earliest: float, end: float | None = None + ) -> list[Launch]: + """ + Deploys planes, as a plan deploys those that are not staged and a + simulation the planes of a stage: produces the satellites of each + (and its spares in orbit) on its type's line from a time (after the + work before them), in order; launches each plane when they are ready + (see `launch`), in the order the planes are ready; and adds the + planned replacements of their satellites (see `replace`). Returns + the launches, then the replacements. + """ + ready = [] + for plane in planes: + kind, size, spares = self.deployment.planes[plane] + if size + spares > 0: + ready.append((self.produce(earliest, kind, size + spares), plane)) + launches = [] + for time, plane in sorted(ready, key=lambda item: item[0]): + launches.extend(self.launch(plane, time)) + if end is None: # a mission that begins at the first launch + end = min(launch.time for launch in launches) + self.schedule.years + return launches + self.replace(launches, end) + + def replace(self, launches: Sequence[Launch], end: float) -> list[Launch]: + """ + Adds the planned replacements of the satellites of launches at the end + of their design life (see `DeploymentSchedule`), returning their + launches: of the positions of the layout that a launch carries (not + of spares in orbit, which do not age), each produced just before it + is needed (at the production rate, apart from the line) and launched + at the next launch slot then, in the order they are needed, and + replaced in turn a design life after that launch. A replacement that + no slot before the end of the mission launches is not produced, but + for a sustained constellation, whose replacements are produced after + the end (their production begun within the development years of + their type after it), though not launched. + """ + schedule = self.schedule + queue: list = [] + order = itertools.count() + for launch in launches: + life = _per_type(schedule.design_life, launch.kind, "design life") + built = self.deployment.planes[launch.plane].satellites + count = min(launch.first + launch.satellites, built) - launch.first + if life is not None and count > 0: + item = (launch.plane, launch.kind, launch.first, count, life) + heapq.heappush(queue, (launch.time + life, next(order), 1, item)) + replacements = [] + while queue: + need, _, generation, item = heapq.heappop(queue) + plane, kind, first, count, life = item + begin = need - _production_years(schedule, kind, count) + time = math.inf + if need < end - 1e-9: + time = _next_slot(schedule, self.booked, need) + if time < end - 1e-9: + bisect.insort(self.booked, time) + replacements.append( + Launch(time, plane, kind, first, count, generation, "replacement") + ) + following = time + life + elif ( + schedule.sustained + and begin + < end + + float(_per_type(schedule.development_years, kind, "development")) + - 1e-9 + ): + following = need + life # produced after the end, not launched + else: + continue + self.production.append(Production(kind, begin, need, count, "replacement")) + heapq.heappush(queue, (following, next(order), generation + 1, item)) + return replacements diff --git a/src/tatc/tradespace/expectations.py b/src/tatc/tradespace/expectations.py new file mode 100644 index 0000000..ac86479 --- /dev/null +++ b/src/tatc/tradespace/expectations.py @@ -0,0 +1,287 @@ +""" +Exact expectations of the capability of missions without restoration over +their failures (`exact_expectations`), rather than from samples of their +histories (see `Deployment.simulate_many`), as the failures of a study +take them where they apply (see `Failures`). + +@author: Paul T. Grogan +""" + +from __future__ import annotations + +import itertools +import math +from typing import TYPE_CHECKING + +import numpy as np + +from .failures import FailureModel +from .mission import _PHASE_COLUMNS, Capability, _position_names + +if TYPE_CHECKING: + from .deployment import Deployment + +MAX_SETS = 4_096 +"""The most sets of satellites that exact expectations enumerate by default +(see `exact_expectations`), as those of the failures of a study do (see +`Failures`): those of about 12 satellites, whose metrics they evaluate +(nearly every set) in about 35 times as many evaluations as 20 histories.""" + + +class ExactExpectationsError(ValueError): + """ + Raised if exact expectations do not apply to a mission (see + `exact_expectations`): of a staged deployment, of a deployment whose + policy restores failures, or of more sets of satellites than they + enumerate. Its histories are simulated instead. + """ + + +def _launch_groups( + deployment: Deployment, model: FailureModel, times: np.ndarray +) -> tuple[int, list[tuple]]: + """ + Gets the launch groups of a deployment without restoration: the + positions of each launch of the deployment (in order of the planes' + positions), which its planned replacements carry again. For each group, + at each time: the probability that each of its launches so far is the + latest that succeeded (`weights`, launches by times), the survival of + the satellites of each since its launch (`survival`, launches by times), + the probability that none has succeeded (`none`), and whether the group + has launched. + """ + offsets = np.cumsum([0] + [plane.satellites for plane in deployment.planes]) + launches: dict[tuple[int, int], list] = {} + for launch in sorted(deployment.launches, key=lambda l: l.time): + launches.setdefault((launch.plane, launch.first), []).append(launch) + p = model.launch + groups = [] + for (plane, first), sequence in launches.items(): + built = deployment.planes[plane].satellites + members = [ + int(offsets[plane]) + position + for position in range(first, min(first + sequence[0].satellites, built)) + ] + if not members: + continue + life = model.life_of(sequence[0].kind) + flown = np.array([[t >= launch.time for t in times] for launch in sequence]) + # launches after each one, up to each time + later = np.flip(np.cumsum(np.flip(flown, axis=0), axis=0), axis=0) - flown + weights = np.where(flown, (1 - p) * p**later, 0.0) + survival = np.array( + [ + ( + np.ones(len(times)) + if life is None + else life.survival(np.maximum(times - launch.time, 0.0)) + ) + for launch in sequence + ] + ) + none = p ** flown.sum(axis=0) + groups.append((members, weights, survival, none, flown.any(axis=0))) + return int(offsets[-1]), groups + + +def _group_operating(group: tuple, count: int) -> np.ndarray: + """ + Gets the probability at each time that exactly a given set of `count` + satellites of a launch group operates (see `_set_weight`). + """ + members, weights, survival, none, _ = group + probability = np.sum( + weights * survival**count * (1 - survival) ** (len(members) - count), axis=0 + ) + return probability + none if count == 0 else probability + + +def _set_weight(active: np.ndarray, groups: list) -> float: + """ + Gets the share of the mission's time in which exactly the active + positions operate, in expectation: at each time, the product over the + launch groups of the probability that exactly the active satellites of + the group operate, which (as they are of one type and launched together) + depends only on their number `a` of the `n` of the group: the sum over + its launches of the probability that the launch is the latest that + succeeded times `S ** a * (1 - S) ** (n - a)`, for the survival `S` of + its satellites, and the probability that none has succeeded if `a` is 0. + """ + probability = 1.0 + for group in groups: + probability = probability * _group_operating(group, int(active[group[0]].sum())) + return float(np.mean(probability)) + + +def _missing_levels(groups: list, count: int, tolerance: float) -> int: + """ + Gets the most positions missing of the sets that exact expectations + enumerate (see `exact_expectations`): the least number such that the + sets of that many missing positions or fewer operate all but `tolerance` + of the mission's time, in expectation. The distribution of the number + missing at each time is the convolution over the launch groups of the + distributions of theirs (each the probability of a set times the number + of sets of its size), cheap to compute without enumerating the sets. + """ + if not groups: + return count + distribution = np.zeros((count + 1, len(groups[0][3]))) + distribution[0] = 1.0 + for group in groups: + size = len(group[0]) + combined = np.zeros_like(distribution) + for gone in range(size + 1): + share = math.comb(size, gone) * _group_operating(group, size - gone) + combined[gone:] += share * distribution[: count + 1 - gone] + distribution = combined + covered = np.cumsum(distribution.mean(axis=1)) + reached = np.flatnonzero(covered >= 1 - tolerance - 1e-12) + return int(reached[0]) if len(reached) > 0 else count + + +def _sets(count: int, levels: int) -> int: + """The sets of `count` positions of which at most `levels` are missing.""" + return sum(math.comb(count, missing) for missing in range(levels + 1)) + + +def _exact_sets( + deployment: Deployment, + model: FailureModel, + tolerance: float = 1e-3, + steps: int = 400, +) -> int: + """ + Gets the number of sets of satellites that exact expectations of a + deployment enumerate (see `exact_expectations`), without enumerating + them: the sets of at most the number of positions missing that cover + all but `tolerance` of the mission's time. + """ + count, groups = _launch_groups(deployment, model, _times(deployment, steps)) + return _sets(count, _missing_levels(groups, count, tolerance)) + + +def _times(deployment: Deployment, steps: int) -> np.ndarray: + """The times at which exact expectations integrate probabilities.""" + begin, end = deployment.begin, deployment.end + return begin + (np.arange(steps) + 0.5) * (end - begin) / steps + + +def exact_expectations( + deployment: Deployment, + model: FailureModel, + capability: Capability, + *, + tolerance: float = 1e-3, + steps: int = 400, + max_sets: int = MAX_SETS, +) -> dict[str, float]: + """ + Computes the expected capability of a mission without restoration (of a + deployment whose policy does not restore failed satellites, see + `RestorationPolicy`, though they may be replaced as planned at the end + of their design life) over its failures: the expectation of the mean of + each metric over the phases of the mission (` mission`, as + `summarize_phases` gives for one history) and of its availability + (`availability`), exactly rather than from samples of histories (see + `Deployment.simulate_many`). + + Without restoration, the satellites fail independently (but for the + satellites of a launch, which a failed launch loses together), so that + the probability that a set of satellites operates at a time is a product + over the launches of their survival (see `Lifetime.survival`). The + expected mean of a metric is the sum over the sets of satellites of the + metric of each set (evaluated once, as with a `PhaseCache`) times the + share of the mission's time in which exactly that set operates, in + expectation (integrated over `steps` times). The sets are enumerated by + the number of satellites missing until their shares cover all but + `tolerance` of the mission's time (a number known before they are + enumerated, from the distribution of the number missing), and evaluated + in order of their shares until they do (`coverage`, the share covered, + and `sets`, the sets evaluated); the expectation is over the sets + evaluated. + + Without sampling error, an expectation estimates the mean of many + histories with none of their variance (see `Deployment.simulate_many`), + for missions of a few to about a dozen satellites, but evaluates the + metrics of nearly every set (about `2 ** n` of `n` satellites, against + the few sets that histories evaluate); for larger ones (whose sets + number more than `max_sets`, which is known before any is enumerated), + or with restoration (whose shared production and launches make failures + dependent), simulate histories. + + Args: + deployment (Deployment): The deployment, whose policy does not + restore failures. + model (FailureModel): The failures. + capability (Capability): The capability of the satellites (in the + order of the planes, see `MissionHistory.phases`): their + observations and metric (see `Capability.evaluate`). + tolerance (float): The share of the mission's time that the sets + evaluated may leave out. + steps (int): The times at which the probabilities are integrated. + max_sets (int): The most sets to enumerate. + + Returns: + dict[str, float]: the expected metrics + + Raises: + ExactExpectationsError: if the deployment is staged (see `Stage`), + whose launches depend on its rules, its policy restores failures, + or it has more sets to enumerate than `max_sets` (raised before + any is enumerated). + """ + # pylint: disable=too-many-locals + if deployment.stages: + raise ExactExpectationsError( + "exact expectations need a deployment that is not staged: " + + "simulate histories of a staged deployment instead" + ) + if deployment.policy.restore: + raise ExactExpectationsError( + "exact expectations need a deployment whose policy does not restore " + + "failures (RestorationPolicy(restore=False)): simulate histories instead" + ) + names = list(_position_names(deployment.planes, capability.names).values()) + count, groups = _launch_groups(deployment, model, _times(deployment, steps)) + levels = _missing_levels(groups, count, tolerance) + if _sets(count, levels) > max_sets: + raise ExactExpectationsError( + "too many sets of satellites to enumerate: simulate histories" + ) + # availability: the expected years of operation of the positions, as a + # share of those of the planned deployment + operating = sum( + len(members) * float(np.mean(np.sum(weights * survival, axis=0))) + for members, weights, survival, _, _ in groups + ) + planned = sum( + len(members) * float(np.mean(launched)) for members, _, _, _, launched in groups + ) + availability = operating / planned if planned > 0 else math.nan + # enumerate the sets by the number of positions missing + weights: list[tuple[float, tuple[int, ...]]] = [] + for missing in range(levels + 1): + for gone in itertools.combinations(range(count), missing): + active = np.ones(count, dtype=bool) + active[list(gone)] = False + weight = _set_weight(active, groups) + if weight > 0: + weights.append((weight, tuple(np.flatnonzero(active)))) + weights.sort(key=lambda item: -item[0]) + totals: dict[str, float] = {} + evaluated, sets = 0.0, 0 + for weight, members in weights: + # the metrics of the set, as of a phase in which it operates + for name, value in capability(names[k] for k in members).items(): + if name in _PHASE_COLUMNS: + continue + totals[f"{name} mission"] = totals.get( + f"{name} mission", 0.0 + ) + weight * float(value) + evaluated += weight + sets += 1 + if evaluated >= 1 - tolerance: + break + result = {name: total / evaluated for name, total in totals.items()} + result.update(availability=availability, coverage=evaluated, sets=float(sets)) + return result diff --git a/src/tatc/tradespace/failures.py b/src/tatc/tradespace/failures.py new file mode 100644 index 0000000..ae117c7 --- /dev/null +++ b/src/tatc/tradespace/failures.py @@ -0,0 +1,523 @@ +""" +Failures of satellites and launches, and the policies that restore (or do +not restore) the satellites that fail, for simulations of missions (see +`Deployment.simulate`). + +The life of a satellite (from its launch) follows a distribution whose +failure rate may vary over its lifecycle: constant (`Exponential`), +decreasing in infancy or increasing with wear (`Weibull`), both (`Bathtub`, +the earliest of competing causes), or given by intervals of age +(`Piecewise`). A `FailureModel` gives the life of each type of satellite and +the probability that a launch fails, and a `RestorationPolicy` whether and +how failed satellites are restored: by spares in orbit, by spares on the +ground, or by satellites built when needed. A policy is a decision of a +design with a fragment of a design space (`policy_space`), whose values +configure it (see `configure`), as the policy of each design of a +`MissionPlan` may be. + +@author: Paul T. Grogan +""" + +from __future__ import annotations + +import math +from collections.abc import Callable, Mapping, Sequence +from dataclasses import dataclass, fields +from typing import Any + +import numpy as np + +from .events import _per_type, _per_type_values +from .nodes import Categorical +from .space import DesignSpace +from .values import Scope + + +class Lifetime: + """ + Base class of distributions of the life (years) of a satellite from its + launch. A subclass gives its hazard (`cumulative_hazard` and `hazard`) + and its life of uniform numbers (`from_uniform`, of `dimensions` numbers), + from which simulations draw every life (see `Deployment.simulate`), with + stratified or stressed uniform numbers (see `Deployment.simulate_many`). + """ + + def cumulative_hazard(self, age: np.ndarray) -> np.ndarray: + """ + Gets the cumulative hazard at ages (the negative logarithm of the + survival). + + Args: + age (numpy.ndarray): The ages (years). + + Returns: + numpy.ndarray: the cumulative hazard + """ + raise NotImplementedError + + def hazard(self, age: np.ndarray) -> np.ndarray: + """ + Gets the hazard (failure rate, per year) at ages. + + Args: + age (numpy.ndarray): The ages (years). + + Returns: + numpy.ndarray: the hazard + """ + raise NotImplementedError + + def survival(self, age: np.ndarray) -> np.ndarray: + """ + Gets the probability of surviving to ages. + + Args: + age (numpy.ndarray): The ages (years). + + Returns: + numpy.ndarray: the survival + """ + return np.exp(-self.cumulative_hazard(np.asarray(age, dtype=float))) + + def sample(self, rng: np.random.Generator) -> float: + """ + Draws a life (years, infinite if the satellite never fails). + + Args: + rng (numpy.random.Generator): The random number generator. + + Returns: + float: the life + """ + return self.from_uniform(rng.random(self.dimensions)) + + @property + def dimensions(self) -> int: + """int: The uniform numbers that determine a life (see + `from_uniform`).""" + return 1 + + def from_uniform(self, uniform: Sequence[float]) -> float: + """ + Gets the life determined by uniform numbers in [0, 1) (as many as + `dimensions`): the life whose cumulative distribution is the uniform + number (the inverse of the distribution), so that stratified + uniform numbers give stratified lives (see `Deployment.simulate_many`). + + Args: + uniform (Sequence[float]): The uniform numbers. + + Returns: + float: the life (years, infinite if the satellite never fails) + """ + raise NotImplementedError + + def stressed( + self, uniform: Sequence[float], factor: float, horizon: float = math.inf + ) -> tuple[float, float]: + """ + Gets a life from a stressed distribution, whose hazard is `factor` + times this one's (its survival this one's to the power `factor`), for + importance sampling (see `Deployment.simulate_many`), and the + logarithm of its likelihood ratio for what a mission observes of it + up to a `horizon` (such as the end of the mission): the density of a + failure before the horizon in this distribution over its density in + the stressed one, `S(life) ** (1 - factor) / factor` for the survival + `S`, or the ratio of the survivals to the horizon, + `S(horizon) ** (1 - factor)`, for a life that outlasts it (whose + length past the horizon does not matter, and whose ratio would + otherwise be unbounded). + + Args: + uniform (Sequence[float]): The uniform numbers (see + `from_uniform`). + factor (float): The factor of the hazard. + horizon (float): The age to which the life is observed. + + Returns: + tuple[float, float]: the life and the logarithm of its ratio + """ + life = self._stressed_life(uniform, factor) + if life > horizon: + survival = float(self.survival(np.array([horizon]))[0]) + return life, (1.0 - factor) * math.log(survival) if survival > 0 else 0.0 + survival = float(self.survival(np.array([life]))[0]) + if survival <= 0: + return life, -math.inf + return life, (1.0 - factor) * math.log(survival) - math.log(factor) + + def _stressed_life(self, uniform: Sequence[float], factor: float) -> float: + """Gets a life from the stressed distribution (see `stressed`).""" + return self.from_uniform([1.0 - (1.0 - float(uniform[0])) ** (1.0 / factor)]) + + +@dataclass(frozen=True) +class Exponential(Lifetime): + """ + A life of constant failure rate (random failures). + + Args: + rate (float): The failure rate (per year). + """ + + rate: float + + def __post_init__(self): + if self.rate < 0: + raise ValueError("rate must not be negative") + + def cumulative_hazard(self, age): + return self.rate * np.asarray(age, dtype=float) + + def hazard(self, age): + return np.full_like(np.asarray(age, dtype=float), self.rate) + + def from_uniform(self, uniform): + if self.rate == 0: + return math.inf + return float(-math.log1p(-float(uniform[0])) / self.rate) + + +@dataclass(frozen=True) +class Weibull(Lifetime): + """ + A life of a Weibull distribution: a failure rate that decreases with age + (infant mortality) if its shape is less than 1, is constant if 1, and + increases (wear-out) if greater. + + Args: + shape (float): The shape. + scale (float): The scale (years), the age at which 63% have failed. + """ + + shape: float + scale: float + + def __post_init__(self): + if self.shape <= 0 or self.scale <= 0: + raise ValueError("shape and scale must be positive") + + def cumulative_hazard(self, age): + return (np.asarray(age, dtype=float) / self.scale) ** self.shape + + def hazard(self, age): + age = np.asarray(age, dtype=float) + with np.errstate(divide="ignore"): + return (self.shape / self.scale) * (age / self.scale) ** (self.shape - 1) + + def from_uniform(self, uniform): + hazard = -math.log1p(-float(uniform[0])) + return float(self.scale * hazard ** (1 / self.shape)) + + +@dataclass(frozen=True) +class Bathtub(Lifetime): + """ + A life of competing causes of failure (the earliest of their lives), such + as the bathtub curve of infant mortality, random failures, and wear-out: + its hazard is the sum of theirs. + + Args: + infant (Lifetime | None): Failures early in life. + random (Lifetime | None): Failures at random. + wear_out (Lifetime | None): Failures late in life. + """ + + infant: Lifetime | None = None + random: Lifetime | None = None + wear_out: Lifetime | None = None + + @property + def causes(self) -> list[Lifetime]: + """list[Lifetime]: The causes of failure.""" + return [c for c in (self.infant, self.random, self.wear_out) if c is not None] + + def cumulative_hazard(self, age): + age = np.asarray(age, dtype=float) + return sum((c.cumulative_hazard(age) for c in self.causes), np.zeros_like(age)) + + def hazard(self, age): + age = np.asarray(age, dtype=float) + return sum((c.hazard(age) for c in self.causes), np.zeros_like(age)) + + @property + def dimensions(self) -> int: + return max(sum(c.dimensions for c in self.causes), 1) + + def from_uniform(self, uniform): + lives, start = [], 0 + for cause in self.causes: + lives.append(cause.from_uniform(uniform[start : start + cause.dimensions])) + start += cause.dimensions + return min(lives, default=math.inf) + + def _stressed_life(self, uniform, factor): + # each cause stressed: the sum of their hazards times the factor + lives, start = [], 0 + for cause in self.causes: + part = uniform[start : start + cause.dimensions] + # pylint: disable-next=protected-access + lives.append(cause._stressed_life(part, factor)) + start += cause.dimensions + return min(lives, default=math.inf) + + +@dataclass(frozen=True) +class Piecewise(Lifetime): + """ + A life of failure rates given by intervals of age: `rates[i]` from + `breaks[i]` to `breaks[i + 1]` (the last beyond the last break), as from + reliability data. + + Args: + breaks (Sequence[float]): The ages (years) at which the intervals + begin, from 0, increasing. + rates (Sequence[float]): The failure rate (per year) of each. + """ + + breaks: Sequence[float] + rates: Sequence[float] + + def __post_init__(self): + breaks, rates = list(self.breaks), list(self.rates) + if len(breaks) == 0 or breaks[0] != 0: + raise ValueError("breaks must begin at 0") + if len(breaks) != len(rates): + raise ValueError("a rate is required for each interval") + if any(b <= a for a, b in zip(breaks[:-1], breaks[1:])): + raise ValueError("breaks must increase") + if any(rate < 0 for rate in rates): + raise ValueError("rates must not be negative") + object.__setattr__(self, "breaks", tuple(float(b) for b in breaks)) + object.__setattr__(self, "rates", tuple(float(r) for r in rates)) + + def _ends(self) -> np.ndarray: + return np.append(np.asarray(self.breaks[1:]), math.inf) + + def cumulative_hazard(self, age): + age = np.asarray(age, dtype=float) + starts, ends = np.asarray(self.breaks), self._ends() + within = np.clip(age[..., None] - starts, 0, ends - starts) + return np.sum(within * np.asarray(self.rates), axis=-1) + + def hazard(self, age): + age = np.asarray(age, dtype=float) + index = np.searchsorted(np.asarray(self.breaks), age, side="right") - 1 + return np.asarray(self.rates)[np.clip(index, 0, len(self.rates) - 1)] + + def from_uniform(self, uniform): + return self._age_at(-math.log1p(-float(uniform[0]))) + + def _age_at(self, target: float) -> float: + """The age at which the cumulative hazard reaches a target.""" + cumulative = 0.0 + for start, end, rate in zip(self.breaks, self._ends(), self.rates): + span = end - start + if rate > 0 and cumulative + rate * span >= target: + return start + (target - cumulative) / rate + cumulative += rate * span if math.isfinite(span) else 0.0 + return math.inf + + +@dataclass(frozen=True) +class FailureModel: + """ + The failures of a mission: the life of the satellites (of every type, or + of each, by type; `None` if they do not fail) and the probability that a + launch fails, losing its satellites. + + Args: + life (Lifetime | Mapping[Any, Lifetime] | None): The life of the + satellites. + launch (float): The probability that a launch fails. + """ + + life: Lifetime | Mapping[Any, Lifetime | None] | None = None + launch: float = 0.0 + + def __post_init__(self): + if not 0 <= self.launch <= 1: + raise ValueError("launch must be a probability") + + def life_of(self, kind: Any) -> Lifetime | None: + """ + Gets the life of a type of satellite. + + Args: + kind (Any): The type. + + Returns: + Lifetime | None: the life, or `None` if it does not fail + """ + return _per_type(self.life, kind, "life") + + +@dataclass(frozen=True) +class RestorationPolicy: + """ + A policy for satellites that fail: to fly the others (`restore=False`, + degrading the constellation until the satellites are replaced at the end + of their design life, if they are), or to restore them, from the fastest + source available when the failure is known (`detection_years` after it): + + * a spare in orbit in the failed satellite's plane (`orbit_spares` in + each plane of every type, or of each, which a deployment planned with + the policy produces and launches with the plane: see + `DeploymentSchedule.plan`, and `MissionPlan`, which plans the + deployment of each design with its policy), which takes its place + after `drift_years` (and is then replaced as planned, as the satellite + it replaces would have been); + * a spare on the ground (`ground_spares` of each type, produced after + the first satellites and stored), launched at the next launch slot; + * a satellite produced when needed, `procurement_years` after it is + ordered (for long-lead items) and on its type's production line (after + the work before it), then launched at the next launch slot. + + A restoration of a plane joins a launch already booked for the plane if + the launch has room (see the launch capacity of `DeploymentSchedule`) + and flies once the restoration is ready, but no later than a launch the + restoration would book; otherwise it books one at the next launch slot + after waiting `batch_years` for others. With `replenish`, a spare that + is used is produced again (and, in orbit, launched to its plane), + procured and produced as a satellite produced when needed, which shares + the production line with restorations. + + A deployment has one policy (see `DeploymentSchedule.plan`), with which + it simulates its missions (see `Deployment.simulate`). + + Args: + restore (bool): `True` to restore failed satellites. + detection_years (float): The time to know of a failure. + drift_years (float): The time for a spare in orbit to take the place + of a failed satellite. + procurement_years (float): The time from ordering a satellite to the + start of its production. + orbit_spares (int | Mapping[Any, int]): The spares in orbit in each + plane of every type of satellite, or of each (by type, every type + of the deployment), which a deployment planned with the policy + produces and launches. + ground_spares (int | Mapping[Any, int]): The spares on the ground of + every type of satellite, or of each (by type, every type of the + deployment). + replenish (bool): `True` to replace the spares that are used. + batch_years (float): The time that restorations of a plane wait to + share a launch. + """ + + restore: bool = True + detection_years: float = 0.1 + drift_years: float = 0.25 + procurement_years: float = 0.0 + orbit_spares: int | Mapping[Any, int] = 0 + ground_spares: int | Mapping[Any, int] = 0 + replenish: bool = False + batch_years: float = 0.0 + + def __post_init__(self): + for name in ( + "detection_years", + "drift_years", + "procurement_years", + "batch_years", + ): + if getattr(self, name) < 0: + raise ValueError(f"{name} must not be negative") + for name in ("orbit_spares", "ground_spares"): + if any(value < 0 for value in _per_type_values(getattr(self, name))): + raise ValueError(f"{name} must not be negative") + + def orbit_spares_of(self, kind: Any) -> int: + """ + Gets the spares in orbit in each plane of a type of satellite. + + Args: + kind (Any): The type. + + Returns: + int: the number of spares + """ + return int(_per_type(self.orbit_spares, kind, "orbit spares")) + + def ground_spares_of(self, kind: Any) -> int: + """ + Gets the spares on the ground of a type of satellite. + + Args: + kind (Any): The type. + + Returns: + int: the number of spares + """ + return int(_per_type(self.ground_spares, kind, "ground spares")) + + +def _spares_restore(d: Scope) -> bool: + """Whether spares are only kept by a policy that restores failures.""" + return bool(d.restore) or (d.orbit_spares == 0 and d.ground_spares == 0) + + +def policy_space( + *, + restore: Any = None, + orbit_spares: Any = 0, + ground_spares: Any = 0, + replenish: Any = False, + require_restoration: bool = True, + constraints: Sequence[Callable[[Scope], Any]] = (), + **others: Any, +) -> DesignSpace: + """ + Gets a fragment of a design space of policies for failed satellites (see + `RestorationPolicy`), for trades of their cost against their + robustness: whether to `restore` failed satellites (by default a + variable, `False` or `True`), the spares in orbit in each plane + (`orbit_spares`, which a deployment planned with the policy produces and + launches, see `DeploymentSchedule.plan`), the spares on the ground + (`ground_spares`), whether to `replenish` used spares, and other fields + of the policy (such as `drift_years`). Each is a node of a design space + (such as a design variable) or a value. + + A design's policy is configured from the values of the fragment (see + `configure`), and its deployment planned with the policy:: + + policy = configure(BASE_POLICY, d.policy) + deployment = SCHEDULE.plan(d.layout, policy=policy) + history = deployment.simulate(FAILURE_MODEL, d.failure_seed) + + as an `ObservationStudy` with a mission plan does for a fragment named + `policy` (see `MissionPlan.policy`), whose values configure the default + policy (give the fields of a base policy to the fragment, or give the + plan a function of the design that configures it):: + + space = space.extend(policy=policy_space(orbit_spares=Integer(0, 1))) + + Spares without restoration would never be used, so a constraint excludes + them (unless `require_restoration` is `False`). + + Args: + restore (Any): Whether to restore failed satellites, by default a + variable. + orbit_spares (Any): The spares in orbit in each plane. + ground_spares (Any): The spares on the ground. + replenish (Any): Whether to replenish used spares. + require_restoration (bool): `True` to exclude spares without + restoration. + constraints (Sequence[Callable]): Other constraints of the fragment. + **others (Any): Other fields of `RestorationPolicy`. + + Returns: + DesignSpace: the fragment + """ + names = {field.name for field in fields(RestorationPolicy)} + unknown = set(others) - names + if unknown: + raise ValueError(f"no fields of RestorationPolicy named {sorted(unknown)}") + children = { + "restore": Categorical([False, True]) if restore is None else restore, + "orbit_spares": orbit_spares, + "ground_spares": ground_spares, + "replenish": replenish, + **others, + } + rules = ([_spares_restore] if require_restoration else []) + list(constraints) + return DesignSpace(constraints=rules, **children) diff --git a/src/tatc/tradespace/fingerprint.py b/src/tatc/tradespace/fingerprint.py new file mode 100644 index 0000000..f9a274b --- /dev/null +++ b/src/tatc/tradespace/fingerprint.py @@ -0,0 +1,1151 @@ +""" +Fingerprints of the definitions of trade studies (design spaces, functions, +and settings), which key persistent results so that results computed with +other definitions are not reused. + +A definition (see `get_definition`) describes values as follows (the rules +of `_Describer.describe`), whether they are given (such as the design space +and functions of a study), or are referred to by functions (as globals, the +values they close over, and their defaults), or are within other values: + +- By content: + + - plain values (`None`, booleans, numbers, strings, bytes, dates, times, + and durations) and their containers (lists, tuples, sets, and + dictionaries, also as globals, such as a dictionary of instruments); + - pydantic models (such as satellites and instruments); + - arrays and data frames (by a hash of their data, with geometries by + their well-known binary), and geometries; + - dataclasses (such as cost models), by their fields, but those whose + metadata has `"fingerprint": False` (such as directories of caches, + which do not change results); + - the nodes of design spaces, by their attributes; + - objects that describe themselves by a method `__fingerprint__()`, by + the value that it returns, which is described in their place: designs + (by their design space, decisions, replicate, and scenario), caches + of satellites (by their function and namespace, not their counts of + hits and misses, nor what they hold), and statistics (by their + attributes, such as their column and quantile); + - partial functions (by their function and arguments), bound methods (by + their function and object), and functions that decorators wrap (such + as by `functools.lru_cache`, by the wrapped function). + +- By code: + + - functions, by their compiled code (which ties a definition to the + version of Python, which it records, but not their docstrings or line + numbers, which do not change results), the values they close over, + their defaults, and the globals they refer to: those of functions of + their own module or of a module of the study's own (one that is not + installed, such as `__main__` or a module next to a notebook) are + described by code, also as attributes of a module of the study's own + (`helpers.score`), so that a notebook's function that calls a function + of such a module is described as the module's copy of it is; + - the classes of the study's own modules, by the code of their methods + (and their constants), and their objects, by their classes and their + attributes, but those that are mutable containers (lists, dictionaries, + and sets), which are often state (such as counters and records of + calls) rather than definitions. + +- By name: the functions of installed modules (as globals of functions), + classes and built-in functions (but the study's own classes), and modules + (but the attributes of the study's own modules that functions refer to). + +- By type: other objects, such as those of installed classes (a connection, + or a lock) and those of TAT-C's classes that none of the rules above + describe, whose state a definition takes not to change results. + +- Not at all: data that functions read (such as from files) and the code of + installed modules other than TAT-C's. Identify them, and the state of + objects described by type that changes results, by a namespace (see + `ResultStore` and `SatelliteCache`). + +TAT-C is described by the source of the modules that the values depend on: +the modules that define the functions, classes, and objects of TAT-C they +refer to, the modules of TAT-C that those import (anywhere in their code, +including imports within functions), and so on, with the resource files +these modules name (such as the instrument catalog). A name imported from a +package depends on the module that defines it, not on every module of the +package, so that `from tatc.analysis import collect_observations` depends +on the module of point sampling (and those it imports), not on the other +analyses. Results computed by a study are then reused after changes to TAT-C +that cannot change them (such as to modules the study does not use), and +not after changes that can. + +@author: Paul T. Grogan +""" + +from __future__ import annotations + +import ast +import dataclasses +import dis +import functools +import hashlib +import json +import sys +import sysconfig +import types +from collections.abc import Callable, Iterable, Mapping +from datetime import date, datetime, time, timedelta +from pathlib import Path +from typing import Any + +import numpy as np +import pandas as pd +import shapely +from pydantic import BaseModel + +from .alerts import _warn +from .hashing import canonical, digest +from .nodes import Node + +_MAX_DEPTH = 24 +"""The deepest nesting described, beyond which values are described by type.""" + +_MAX_ITEMS = 1000 +"""The most items of a container (or array) described one by one.""" + +_TATC = "tatc" +"""The name of the package (TAT-C) whose modules a definition describes by +source.""" + +_ROOT = Path(__file__).resolve().parents[1] +"""The directory of the package.""" + +_RESOURCES = "resources" +"""The directory of the package's resource files (data, not modules).""" + + +def _type(value: Any) -> dict: + kind = type(value) + return {"type": f"{kind.__module__}.{kind.__qualname__}"} + + +def _name(value: Any) -> str: + return f"{getattr(value, '__module__', None)}.{value.__qualname__}" + + +def _is_tatc_module(module: Any) -> bool: + """Whether a module name is of TAT-C (or is TAT-C's package).""" + return isinstance(module, str) and ( + module == _TATC or module.startswith(_TATC + ".") + ) + + +def _is_dataclass(value: Any) -> bool: + """Whether a value is an instance of a dataclass (such as a cost model).""" + return dataclasses.is_dataclass(value) and not isinstance(value, type) + + +def _has_fingerprint(value: Any) -> bool: + """ + Whether a value is an object that describes itself (by a method + `__fingerprint__`, see `_Describer.fingerprinted`), not a class. + """ + return callable(getattr(type(value), "__fingerprint__", None)) + + +@functools.lru_cache(maxsize=1) +def _installed_directories() -> tuple[Path, ...]: + """Gets the directories of installed modules (and the standard library).""" + paths = sysconfig.get_paths() + names = ("stdlib", "platstdlib", "purelib", "platlib") + found = {Path(paths[name]).resolve() for name in names if name in paths} + found.add(Path(sys.base_prefix).resolve()) + return tuple(sorted(found)) + + +def _is_own_module(module: Any) -> bool: + """ + Whether a module is of the study's own: neither of TAT-C nor installed + (such as `__main__`, or a module next to a notebook), so that its + functions are described by their code (see the module). + """ + if not isinstance(module, str) or _is_tatc_module(module): + return False + if module == "__main__": + return True + file = getattr(sys.modules.get(module), "__file__", None) + if file is None: + return False # built in, or not loaded + path = Path(file).resolve() + return not any(path.is_relative_to(d) for d in _installed_directories()) + + +def _is_own_class(value: Any) -> bool: + """Whether a value is a class of the study's own (see `_is_own_module`).""" + return isinstance(value, type) and _is_own_module(value.__module__) + + +def _is_own_object(value: Any) -> bool: + """Whether a value is an object of a class of the study's own.""" + return _is_own_module(type(value).__module__) + + +def _wrapped(value: Any) -> types.FunctionType | None: + """ + Gets the function that a decorator wraps (such as `functools.lru_cache`, + or another of `functools.wraps`), if a value is such a wrapper. + """ + if isinstance(value, (types.FunctionType, type)) or not callable(value): + return None + function = getattr(value, "__wrapped__", None) + return function if isinstance(function, types.FunctionType) else None + + +def _hash_column(column: pd.Series) -> bytes: + """ + Gets the hashes of the values of a column (geometries by their + well-known binary, which is exact). + """ + if str(column.dtype) == "geometry": + return b"".join( + hashlib.sha1(b"" if wkb is None else wkb).digest() + for wkb in column.to_wkb() + ) + try: + return pd.util.hash_pandas_object(column, index=False).to_numpy().tobytes() + except TypeError: # such as of unhashable objects + return "\x1f".join(repr(item) for item in column.tolist()).encode() + + +def _frame(value: pd.DataFrame | pd.Series) -> dict: + """ + Describes a data frame (or series) by its columns, types, and shape, and + a hash of its index and values. + """ + frame = value.to_frame() if isinstance(value, pd.Series) else value + hasher = hashlib.sha1() + hasher.update(pd.util.hash_pandas_object(frame.index).to_numpy().tobytes()) + for i in range(frame.shape[1]): + hasher.update(_hash_column(frame.iloc[:, i])) + return { + **_type(value), + "columns": [str(column) for column in frame.columns], + "types": [str(dtype) for dtype in frame.dtypes], + "index": str(frame.index.dtype), + "shape": list(value.shape), + "data": hasher.hexdigest(), + } + + +def _has_contents(cell: Any) -> bool: + try: + cell.cell_contents # pylint: disable=pointless-statement + except ValueError: # an empty cell + return False + return True + + +_GLOBAL_LOADS = ("LOAD_GLOBAL", "LOAD_NAME") +"""The instructions that load a global (rather than an attribute, whose names +code also lists).""" + +_ATTRIBUTE_LOADS = ("LOAD_ATTR", "LOAD_METHOD") +"""The instructions that load an attribute of the value loaded before.""" + + +def _global_names(code: types.CodeType) -> dict[str, set[tuple[str, ...]]]: + """ + Gets the global names a code (and its nested code) loads (not the names of + attributes, such as `values` of `design.values`, which may be the names + of unrelated globals), each with the chains of attributes that it loads + of the global (such as `("score",)` of `helpers.score`). + """ + found: dict[str, set[tuple[str, ...]]] = {} + instructions = list(dis.get_instructions(code)) + for i, instruction in enumerate(instructions): + if instruction.opname not in _GLOBAL_LOADS: + continue + chain = [] + for following in instructions[i + 1 :]: + if following.opname not in _ATTRIBUTE_LOADS: + break + chain.append(following.argval) + chains = found.setdefault(instruction.argval, set()) + if chain: + chains.add(tuple(chain)) + for constant in code.co_consts: + if isinstance(constant, types.CodeType): + for name, chains in _global_names(constant).items(): + found.setdefault(name, set()).update(chains) + return found + + +def _attribute(module: types.ModuleType, chain: tuple[str, ...]) -> tuple[str, Any]: + """ + Gets the value that a chain of attributes of a module reaches, through + its submodules (stopping at the first value that is not a module), and + the path to it, or `("", None)` if there is none. + """ + value: Any = module + path = [] + for name in chain: + if not isinstance(value, types.ModuleType): + break + if not hasattr(value, name): + return "", None + value = getattr(value, name) + path.append(name) + return ".".join(path), value + + +_PLAIN = (type(None), bool, int, float, str, bytes, date, time, timedelta, np.generic) + + +def _is_constant(value: Any, depth: int = 0) -> bool: + """ + Whether a value is a constant: a number, string, date or time, or a + (small) tuple or frozen set of them. Mutable containers (lists, + dictionaries, and sets) are not constants: as attributes of classes, + they are often state (such as registries) rather than definitions. + """ + if isinstance(value, _PLAIN): + return True + if depth > 3: + return False + if isinstance(value, (tuple, frozenset)): + return len(value) <= _MAX_ITEMS and all( + _is_constant(v, depth + 1) for v in value + ) + return False + + +class _Describer: + """ + Describes values as plain data (see the module, and `_RULES`), noting + the modules of the package that they depend on. + """ + + # pylint: disable=too-many-public-methods + + def __init__(self): + self.modules: set[str] = set() + """The modules of the package that the described values refer to.""" + + def note(self, module: Any) -> None: + """Notes a module that a value refers to (if it is of the package).""" + if _is_tatc_module(module): + self.modules.add(module) + + def describe(self, value: Any, depth: int = 0, seen: set | None = None) -> Any: + """ + Describes a value as plain data, by the first rule that it matches + (see `_RULES`), or by its type if none does. + """ + seen = set() if seen is None else seen + if depth <= _MAX_DEPTH: + for test, rule in _RULES: + if isinstance(value, test) if isinstance(test, tuple) else test(value): + return rule(self, value, depth, seen) + self.note(type(value).__module__) + return _type(value) + + def noted(self, module: Any, description: Any) -> Any: + """Notes a module (see `note`), and gives a description.""" + self.note(module) + return description + + # the rules of descriptions that are more than one expression (see `_RULES`) + + def dataclass(self, value: Any, depth: int, seen: set) -> dict: + """ + Describes a dataclass by its fields (but those whose metadata has + `"fingerprint": False`), and its class, if of the study's own. + """ + self.note(type(value).__module__) + described = { + **_type(value), + **{ + item.name: self.describe(getattr(value, item.name), depth + 1, seen) + for item in dataclasses.fields(value) + if item.metadata.get("fingerprint", True) + }, + } + if _is_own_module(type(value).__module__): + described["class"] = self.klass(type(value), depth + 1, seen) + return described + + def fingerprinted(self, value: Any, depth: int, seen: set) -> dict: + """ + Describes an object by the value that its method `__fingerprint__()` + returns (such as a design by its design space and decisions), which + identifies what of it changes results. + """ + self.note(type(value).__module__) + if id(value) in seen: + return {**_type(value), "recursive": True} + seen = seen | {id(value)} + return { + **_type(value), + "fingerprint": self.describe(value.__fingerprint__(), depth + 1, seen), + } + + def sequence(self, value: list | tuple, depth: int, seen: set) -> Any: + """Describes a list or tuple by its items (or its length, if long).""" + if len(value) > _MAX_ITEMS: + return {**_type(value), "length": len(value)} + return [self.describe(v, depth + 1, seen) for v in value] + + def collection(self, value: set | frozenset, depth: int, seen: set) -> Any: + """Describes a set by its sorted items (or its length, if long).""" + if len(value) > _MAX_ITEMS: + return {**_type(value), "length": len(value)} + return sorted((self.describe(v, depth + 1, seen) for v in value), key=canonical) + + def mapping(self, value: dict, depth: int, seen: set) -> Any: + """ + Describes a dictionary by its items (sorted pairs, if its keys are + not strings), or its length, if long. + """ + if len(value) > _MAX_ITEMS: + return {**_type(value), "length": len(value)} + if all(isinstance(key, str) for key in value): + return {key: self.describe(v, depth + 1, seen) for key, v in value.items()} + pairs = ( + [self.describe(k, depth + 1, seen), self.describe(v, depth + 1, seen)] + for k, v in value.items() + ) + return sorted(pairs, key=canonical) + + def node(self, value: Node, depth: int, seen: set) -> dict: + """Describes a node of a design space by its attributes.""" + self.note(type(value).__module__) + if id(value) in seen: + return {**_type(value), "recursive": True} + seen = seen | {id(value)} + return { + **_type(value), + **{ + name: self.describe(attribute, depth + 1, seen) + for name, attribute in sorted(vars(value).items()) + }, + } + + def code( + self, code: types.CodeType, depth: int, seen: set, doc: str | None = None + ) -> dict: + """ + Describes compiled code by its instructions, constants, and names (not + its file or line numbers, which change as code moves, nor the + docstring `doc` of its function, which does not change results). The + constants include the small integers that some versions of Python + load by an instruction of their own (`LOAD_SMALL_INT`, from 3.14) + rather than from the constants of the code, so that the constants of + code are its literals in every version. + """ + constants = list(code.co_consts) + if doc is not None and constants and constants[0] == doc: + constants = constants[1:] + constants.extend( + instruction.argval + for instruction in dis.get_instructions(code) + if instruction.opname == "LOAD_SMALL_INT" + ) + return { + "code": code.co_code.hex(), + "constants": [self.describe(c, depth + 1, seen) for c in constants], + "names": list(code.co_names), + } + + def function(self, function: types.FunctionType, depth: int, seen: set) -> dict: + """ + Describes a function: its code, the values it closes over, its + defaults, and the globals it refers to (see `reference`). + """ + self.note(function.__module__) + if id(function) in seen: + return {"function": function.__qualname__, "recursive": True} + seen = seen | {id(function)} + closure = { + name: self.describe(cell.cell_contents, depth + 1, seen) + for name, cell in zip( + function.__code__.co_freevars, function.__closure__ or () + ) + if _has_contents(cell) + } + referenced = { + name: self.reference( + function.__globals__[name], function.__module__, chains, depth, seen + ) + for name, chains in _global_names(function.__code__).items() + if name in function.__globals__ + } + return { + "function": function.__qualname__, + **self.code(function.__code__, depth, seen, function.__doc__), + "closure": closure, + "defaults": self.describe(function.__defaults__, depth + 1, seen), + "keyword defaults": self.describe(function.__kwdefaults__, depth + 1, seen), + "globals": referenced, + } + + def reference( + self, + value: Any, + module: str, + chains: Iterable[tuple[str, ...]], + depth: int, + seen: set, + ) -> Any: + """ + Describes a global that a function of a module refers to: a function + of another module (or one that a decorator wraps) by its name, unless + it is of a module of the study's own, a module of the study's own by + the attributes of it that the function refers to (by their `chains`, + see `_global_names`), and other values as any other (see `describe`). + """ + # pylint: disable=too-many-arguments,too-many-positional-arguments + function = _wrapped(value) or value + if ( + isinstance(function, types.FunctionType) + and function.__module__ != module + and not _is_own_module(function.__module__) + ): + self.note(function.__module__) + return {"name": _name(function)} + if isinstance(value, types.ModuleType) and _is_own_module(value.__name__): + attributes = {} + for chain in sorted(chains): + path, reached = _attribute(value, chain) + if path: + attributes[path] = self.reference( + reached, value.__name__, (), depth + 1, seen + ) + return {"module": value.__name__, "attributes": attributes} + return self.describe(value, depth + 1, seen) + + def method(self, value: types.MethodType, depth: int, seen: set) -> dict: + """Describes a bound method by its function and its object.""" + return { + "method": self.describe(value.__func__, depth + 1, seen), + "self": self.describe(value.__self__, depth + 1, seen), + } + + def partial(self, value: functools.partial, depth: int, seen: set) -> dict: + """Describes a partial function by its function and arguments.""" + return { + "partial": self.describe(value.func, depth + 1, seen), + "arguments": self.describe(value.args, depth + 1, seen), + "keywords": self.describe(value.keywords, depth + 1, seen), + } + + def wrapper(self, value: Any, depth: int, seen: set) -> dict: + """Describes a decorator's wrapper by its type and wrapped function.""" + self.note(type(value).__module__) + return { + **_type(value), + "wrapped": self.describe(_wrapped(value), depth + 1, seen), + } + + def klass(self, cls: type, depth: int, seen: set) -> dict: + """ + Describes a class of the study's own (see `_is_own_module`): its name, + bases (other than `object`), and members: its functions (methods, + static and class methods, and the functions of properties) by their + code, and its constants. + """ + if id(cls) in seen: + return {"class": cls.__qualname__, "recursive": True} + seen = seen | {id(cls)} + members: dict[str, Any] = {} + for name, member in sorted(vars(cls).items()): + if isinstance(member, (staticmethod, classmethod)): + member = member.__func__ + if isinstance(member, property): + members[name] = { + part: self.function(accessor, depth + 1, seen) + for part, accessor in (("get", member.fget), ("set", member.fset)) + if isinstance(accessor, types.FunctionType) + } + elif isinstance(member, types.FunctionType): + members[name] = self.function(member, depth + 1, seen) + elif not name.startswith("__") and _is_constant(member): + members[name] = self.describe(member, depth + 1, seen) + return { + "class": cls.__qualname__, + "bases": [ + self.describe(base, depth + 1, seen) + for base in cls.__bases__ + if base is not object + ], + "members": members, + } + + def instance(self, value: Any, depth: int, seen: set) -> dict: + """ + Describes an object of a class of the study's own: its class (see + `klass`) and its attributes, but those that are mutable containers + (lists, dictionaries, and sets), which are often state (such as + counters and records of calls). + """ + if id(value) in seen: + return {**_type(value), "recursive": True} + seen = seen | {id(value)} + if hasattr(value, "__dict__"): + attributes = dict(vars(value)) + else: + slots = getattr(type(value), "__slots__", ()) + slots = [slots] if isinstance(slots, str) else list(slots) + attributes = {n: getattr(value, n) for n in slots if hasattr(value, n)} + attributes = { + name: attribute + for name, attribute in attributes.items() + if not isinstance(attribute, (list, dict, set, bytearray)) + } + return { + **_type(value), + "class": self.klass(type(value), depth + 1, seen), + "attributes": self.describe(attributes, depth + 1, seen), + } + + +def _array(value: np.ndarray) -> dict: + """Describes an array by its type, shape, and a hash of its data.""" + if value.dtype == object: + return {**_type(value), "shape": list(value.shape)} + return { + "array": str(value.dtype), + "shape": list(value.shape), + "data": hashlib.sha1(np.ascontiguousarray(value).tobytes()).hexdigest(), + } + + +_RULES: tuple[tuple[tuple[type, ...] | Callable[[Any], bool], Callable], ...] = ( + # by content: plain values as themselves (floats by their representation, + # exactly, and numpy scalars as Python's), bytes by their hash, dates and + # times by their ISO format, and durations by their seconds + ((type(None), bool, int, str), lambda _, value, *__: value), + ((float,), lambda _, value, *__: repr(value)), + ( + (np.generic,), + lambda describer, value, *rest: describer.describe(value.item(), *rest), + ), + ((bytes,), lambda _, value, *__: hashlib.sha1(value).hexdigest()), + ((datetime, date, time), lambda _, value, *__: value.isoformat()), + ((timedelta,), lambda _, value, *__: {"timedelta": value.total_seconds()}), + (_has_fingerprint, _Describer.fingerprinted), + (_is_dataclass, _Describer.dataclass), + # pydantic models by their data, arrays and data frames by hashes of their + # data (see `_array` and `_frame`), and geometries by a hash of their + # well-known binary + ( + (BaseModel,), + lambda describer, value, *_: describer.noted( + type(value).__module__, {**_type(value), **value.model_dump(mode="json")} + ), + ), + ((np.ndarray,), lambda _, value, *__: _array(value)), + ((pd.DataFrame, pd.Series), lambda _, value, *__: _frame(value)), + ( + (shapely.Geometry,), + lambda _, value, *__: { + **_type(value), + "data": hashlib.sha1(value.wkb).hexdigest(), + }, + ), + ((list, tuple), _Describer.sequence), + ((set, frozenset), _Describer.collection), + ((dict,), _Describer.mapping), + ((Node,), _Describer.node), + ((functools.partial,), _Describer.partial), + ((types.MethodType,), _Describer.method), + (lambda value: _wrapped(value) is not None, _Describer.wrapper), + # by code + ((types.CodeType,), _Describer.code), + ((types.FunctionType,), _Describer.function), + (_is_own_class, _Describer.klass), + (_is_own_object, _Describer.instance), + # by name: classes and built-in functions, and modules + ( + (types.BuiltinFunctionType, type), + lambda describer, value, *_: describer.noted( + getattr(value, "__module__", None), {"name": _name(value)} + ), + ), + ( + (types.ModuleType,), + lambda describer, value, *_: describer.noted( + value.__name__, {"module": value.__name__} + ), + ), +) +"""What values are described by (see the module): the first rule whose test +(types, or a predicate) a value matches describes it, and a value that +matches none is described by its type (as is one nested too deep).""" + + +@functools.lru_cache(maxsize=1) +def _module_files() -> dict[str, Path]: + """ + Gets the source files of the modules of the package, by module name + (packages by their `__init__.py`). + """ + found = {} + for path in sorted(_ROOT.rglob("*.py")): + if "__pycache__" in path.parts: + continue + parts = path.relative_to(_ROOT).with_suffix("").parts + if parts[-1] == "__init__": + parts = parts[:-1] + found[".".join((_TATC, *parts))] = path + return found + + +def _is_init_module(module: str) -> bool: + """Whether a module of TAT-C is a package (an `__init__.py`).""" + path = _module_files().get(module) + return path is not None and path.name == "__init__.py" + + +@functools.lru_cache(maxsize=None) +def _tree(module: str) -> ast.Module: + """Gets the syntax tree of a module of the package.""" + return ast.parse(_module_files()[module].read_bytes()) + + +def _absolute(module: str, node: ast.ImportFrom) -> str: + """Gets the absolute name of the module of an import from a module.""" + if node.level == 0: + return node.module or "" + package = module if _is_init_module(module) else module.rpartition(".")[0] + parts = package.split(".") + parts = parts[: len(parts) - (node.level - 1)] + return ".".join(parts + ([node.module] if node.module else [])) + + +def _is_constant_node(node: ast.AST) -> bool: + """Whether an expression is a constant (or a tuple or list of them).""" + if isinstance(node, ast.Constant): + return True + return isinstance(node, (ast.Tuple, ast.List)) and all( + _is_constant_node(item) for item in node.elts + ) + + +def _assigned(node: ast.stmt) -> tuple[list[str], ast.AST | None]: + """Gets the names a statement assigns, and the value it assigns them.""" + if isinstance(node, ast.Assign): + return [t.id for t in node.targets if isinstance(t, ast.Name)], node.value + if isinstance(node, ast.AnnAssign) and isinstance(node.target, ast.Name): + return [node.target.id], node.value + return [], None + + +@functools.lru_cache(maxsize=None) +def _resolve_import(module: str, name: str) -> frozenset[tuple[str, str]]: + """ + Gets what a name imported from a module of the package depends on: a + submodule of that name, or (from a package) the module that defines it, + following the package's imports. Items are `("module", m)`, for a module + and those it imports, or `("file", m)`, for the source of a module only + (a package through which a name is imported, or that defines it as a + constant). + """ + files = _module_files() + if f"{module}.{name}" in files: + return frozenset({("module", f"{module}.{name}")}) + if module not in files: + return frozenset() + if not _is_init_module(module): + return frozenset({("module", module)}) + for node in _tree(module).body: + if isinstance(node, ast.ImportFrom): + for alias in node.names: + if (alias.asname or alias.name) == name: + source = _absolute(module, node) + if not _is_tatc_module(source) or source == module: + return frozenset({("file", module)}) + found = _resolve_import(source, alias.name) + return frozenset({("file", module)}) | found + elif isinstance(node, ast.Import): + for alias in node.names: + if alias.asname == name and _is_tatc_module(alias.name): + return frozenset({("file", module), ("module", alias.name)}) + elif isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef, ast.ClassDef)): + if node.name == name: + return frozenset({("module", module)}) + else: + names, value = _assigned(node) + if name in names: + if value is not None and _is_constant_node(value): + return frozenset({("file", module)}) + return frozenset({("module", module)}) + return frozenset({("module", module)}) + + +@functools.lru_cache(maxsize=None) +def _imports(module: str) -> frozenset[tuple[str, str]]: + """ + Gets what the imports of a module of the package (anywhere in its code) + depend on (see `_resolve_import`). + """ + found: set[tuple[str, str]] = set() + for node in ast.walk(_tree(module)): + if isinstance(node, ast.Import): + found.update( + ("module", alias.name) + for alias in node.names + if _is_tatc_module(alias.name) + ) + elif isinstance(node, ast.ImportFrom): + source = _absolute(module, node) + if not _is_tatc_module(source): + continue + for alias in node.names: + if alias.name == "*": + found.add(("module", source)) + else: + found.update(_resolve_import(source, alias.name)) + return frozenset(found) + + +@functools.lru_cache(maxsize=None) +def _resources_of(module: str) -> frozenset[str]: + """ + Gets the resource files a module of the package names: if it refers to + the directory of resources, those whose names, or the names of whose + directories (within it), are strings of its code. + """ + strings = { + node.value + for node in ast.walk(_tree(module)) + if isinstance(node, ast.Constant) and isinstance(node.value, str) + } + if _RESOURCES not in strings: + return frozenset() + directory = _ROOT / _RESOURCES + found = set() + for path in directory.rglob("*"): + if not path.is_file() or "__pycache__" in path.parts: + continue + folders = path.relative_to(directory).parts[:-1] + if path.name in strings or any(folder in strings for folder in folders): + found.add(path.relative_to(_ROOT).as_posix()) + return frozenset(found) + + +def _get_dependencies(modules: Iterable[str]) -> tuple[list[str], list[str]]: + """ + Gets the modules of TAT-C (and resource files) that modules depend on: + the modules and the modules of TAT-C they import (anywhere in their + code), and so on, where a name imported from a package depends on the + module that defines it (and the source of the package's `__init__.py`), + not on every module of the package, and the resource files that these + modules name. + + Args: + modules (Iterable[str]): The names of the modules (others than of + TAT-C are ignored). + + Returns: + tuple[list[str], list[str]]: the names of the modules, and the paths + of the resource files (within the package) + """ + files = _module_files() + whole: set[str] = set() + sources: set[str] = set() + pending = [module for module in modules if _is_tatc_module(module)] + while pending: + module = pending.pop() + if module in whole or module not in files: + continue + whole.add(module) + for kind, other in _imports(module): + if kind == "module": + pending.append(other) + else: + sources.add(other) + resources = set().union(*(_resources_of(module) for module in whole)) + # the trees are no longer needed: what they give is kept + _tree.cache_clear() + return sorted(whole | sources), sorted(resources) + + +@functools.lru_cache(maxsize=None) +def _hash_file(path: Path, modified: int, size: int) -> str: + del modified, size # keys of the cache, so that a changed file is hashed again + return digest(path.read_bytes(), 16) + + +def _hash(path: Path) -> str: + """Gets a hash of the content of a file (computed again if it changes).""" + status = path.stat() + return _hash_file(path, status.st_mtime_ns, status.st_size) + + +def describe(value: Any) -> Any: + """ + Describes a value as plain data, as a definition describes the values it + is given (see the module and `get_definition`), such as to identify the + overrides of a scenario by their content. + + Args: + value (Any): The value. + + Returns: + Any: the description, as plain data + """ + return _Describer().describe(value) + + +def get_definition(*values: Any, **named: Any) -> dict: + """ + Gets the definition of values (such as a design space and the functions + of a study) that their fingerprint hashes (see `get_fingerprint`): a + description of each value (see the module), the version of Python (as + functions are described by their compiled code), and a hash of the + source of each module of TAT-C (and of each resource file) that the + values depend on (see the module). + + Args: + *values (Any): The values, described by their positions. + **named (Any): The values, described by their names. + + Returns: + dict: the definition, as plain data (`python`, `values`, `modules`, + and `resources`), which `compare_definitions` compares + """ + describer = _Describer() + described = {str(i): describer.describe(value) for i, value in enumerate(values)} + described.update({name: describer.describe(value) for name, value in named.items()}) + modules, resources = _get_dependencies(describer.modules) + files = _module_files() + return { + "python": f"{sys.implementation.name} {sys.version_info[0]}.{sys.version_info[1]}", + "values": described, + "modules": {module: _hash(files[module]) for module in modules}, + "resources": {path: _hash(_ROOT / path) for path in resources}, + } + + +def _fingerprint_of(definition: dict) -> str: + """Gets the fingerprint of a definition (see `get_definition`).""" + return digest(canonical(definition), 16) + + +def get_fingerprint(*values: Any, **named: Any) -> str: + """ + Gets a fingerprint of values (such as a design space and the functions + of a study): a hash of their definition (see `get_definition`), which + changes if they do, or if the source of TAT-C that they depend on does. + + Args: + *values (Any): The values, described by their positions. + **named (Any): The values, described by their names. + + Returns: + str: the fingerprint + """ + return _fingerprint_of(get_definition(*values, **named)) + + +_SHORT = 40 +"""The longest value shown in a difference between definitions.""" + + +def _show(value: Any) -> str: + return value if isinstance(value, str) else json.dumps(value, default=str) + + +def _differences(before: Any, after: Any, path: str) -> list[str]: + """ + Gets the differences between descriptions, by the path to each value + that differs (and the values, if they are short). + """ + if before == after: + return [] + if isinstance(before, dict) and isinstance(after, dict): + found = [] + for key in sorted(set(before) | set(after), key=str): + inner = f"{path}.{key}" if path else str(key) + if key not in before: + found.append(f"{inner} (added)") + elif key not in after: + found.append(f"{inner} (removed)") + else: + found.extend(_differences(before[key], after[key], inner)) + return found + if ( + isinstance(before, list) + and isinstance(after, list) + and len(before) == len(after) + ): + found = [] + for i, (old, new) in enumerate(zip(before, after)): + found.extend(_differences(old, new, f"{path}[{i}]")) + return found + path = path or "values" + if all( + not isinstance(v, (dict, list)) and len(_show(v)) <= _SHORT + for v in (before, after) + ): + return [f"{path}: {_show(before)} -> {_show(after)}"] + return [path] + + +def _is_code(description: Any) -> bool: + """Whether a description is of compiled code (see `_Describer.code`).""" + return isinstance(description, dict) and {"code", "constants", "names"} <= set( + description + ) + + +_LOCALS = ".." +"""The part of the qualified names of nested code, which some versions of +Python (3.10) keep as constants of the code that makes their functions.""" + + +def _literals(constants: list) -> list: + """ + Gets the literals of the described constants of code, as the same code + gives them in every version of Python: the items of tuples and frozen + sets, and the constants of nested code (whose code is inlined by some + versions), each once, sorted, without `None` (which some versions keep + as a placeholder of a docstring) and the qualified names of nested code. + """ + found: dict[str, Any] = {} + + def visit(constant: Any) -> None: + if constant is None or (isinstance(constant, str) and _LOCALS in constant): + return + if isinstance(constant, list): + for item in constant: + visit(item) + elif _is_code(constant): + for item in constant["constants"]: + visit(item) + else: + found.setdefault(canonical(constant), constant) + + for constant in constants: + visit(constant) + return [found[key] for key in sorted(found)] + + +def _without_code(description: Any) -> Any: + """ + Gets a description of values without the code of their functions (the + instructions and names of compiled code, see `_Describer.code`), which is + the same for the same values with other code (such as a function after + its expressions are edited, or compiled by another version of Python). + The constants of the code (such as the numbers of a constraint) are + values, as its literals (see `_literals`, which every version of Python + gives alike): functions of other literals are of other studies, whose + results are not those of the same study with other code. + """ + if _is_code(description): + return { + key: (_literals(value) if key == "constants" else _without_code(value)) + for key, value in description.items() + if key not in ("code", "names") + } + if isinstance(description, dict): + return {key: _without_code(value) for key, value in description.items()} + if isinstance(description, list): + return [_without_code(value) for value in description] + return description + + +def _find_stale( + definition: dict, + others: Mapping[Any, dict | None], + count: Callable[[Any], int], +) -> dict[Any, int]: + """ + Gets the results of the same study (or function) as a definition with + other code (of its functions, of TAT-C, or of Python), which are not + reused: the keys of the other definitions (such as the contexts of a + store, or the folders of a cache) that have the same values but other + code (see `_without_code`), in their order, with their numbers of + results (by `count`, a function of a key, 0 for a definition kept + without results). The results of other studies (such as variants of + other settings) are not stale, as studies share stores and caches + freely, and definitions that are `None` (unknown) are of no study. + """ + values = _without_code(definition.get("values", {})) + return { + key: count(key) + for key, other in others.items() + if other is not None and _without_code(other.get("values", {})) == values + } + + +def warn_stale( + found: Mapping[Any, int], + definition: dict, + definition_of: Callable[[Any], dict | None], + subject: Callable[[int], str], + remedy: str, + once: Callable[[], bool] | None = None, +) -> bool: + """ + Warns (at the user's call) that the results of the same study (or + function) as a definition with other code (see `_find_stale`) are not + reused, if any are found, with the differences of the latest of their + definitions from the definition (see `compare_definitions`). + + Args: + found (Mapping[Any, int]): The numbers of stale results, by the key + of their definition, the latest first (see `_find_stale`). + definition (dict): The definition (see `get_definition`). + definition_of (Callable[[Any], dict | None]): A function of a key + that gives its definition. + subject (Callable[[int], str]): A function of the number of stale + results that says which they are (such as `"the store has 12 + evaluations of namespace 'a' by this study"`). + remedy (str): How to remove them. + once (Callable[[], bool] | None): A function called before warning + that gives whether to warn (such as only for the first of the + parallel workers of a study), or `None` to warn. + + Returns: + bool: whether it warned + """ + # pylint: disable=too-many-arguments,too-many-positional-arguments + found = {key: number for key, number in found.items() if number} + if not found or (once is not None and not once()): + return False + latest = definition_of(next(iter(found))) or {} + _warn( + f"{subject(sum(found.values()))} with other code, which are not reused " + + f"({remedy}); the latest differs in: " + + "; ".join(compare_definitions(latest, definition)) + ) + return True + + +def compare_definitions(before: dict, after: dict, limit: int = 5) -> list[str]: + """ + Compares definitions (see `get_definition`), as to explain why results + of one are not reused by the other: the version of Python, the values + that differ (by their path in the description, such as + `evaluate.closure.offset: 0.0 -> 1.0`, or `evaluate.code` for a change + to the code of a function), and the modules of TAT-C (and resource + files) whose source differs, or that only one depends on. + + Args: + before (dict): A definition. + after (dict): Another definition. + limit (int): The most differences listed (and a count of others). + + Returns: + list[str]: the differences (none if the definitions are the same) + """ + found = [] + if before.get("python") != after.get("python"): + found.append(f"python: {before.get('python')} -> {after.get('python')}") + found.extend(_differences(before.get("values", {}), after.get("values", {}), "")) + for kind, label in (("modules", "module"), ("resources", "resource")): + old, new = before.get(kind, {}), after.get(kind, {}) + for name in sorted(set(old) | set(new)): + if name not in old: + found.append(f"{label} {name} (added)") + elif name not in new: + found.append(f"{label} {name} (removed)") + elif old[name] != new[name]: + found.append(f"{label} {name}") + if len(found) > limit: + return found[:limit] + [f"{len(found) - limit} more"] + return found diff --git a/src/tatc/tradespace/hashing.py b/src/tatc/tradespace/hashing.py new file mode 100644 index 0000000..880259c --- /dev/null +++ b/src/tatc/tradespace/hashing.py @@ -0,0 +1,40 @@ +""" +Canonical text of plain values, and short hashes of it, which identify +designs (see `Design.key`), definitions (see `get_fingerprint`), and the +contents of caches and stores. + +@author: Paul T. Grogan +""" + +from __future__ import annotations + +import hashlib +import json +from typing import Any + + +def _json_default(value: Any) -> Any: + """ + Gets a value that JSON holds of one it does not: a numpy scalar as + Python's, or another value as its string. + """ + item = getattr(value, "item", None) + if callable(item) and type(value).__module__ == "numpy": + return item() + return str(value) + + +def canonical(value: Any) -> str: + """ + Gets the canonical text of a plain value: its JSON, with the keys of + mappings sorted (numpy scalars as Python's, and other values as their + strings). + """ + return json.dumps(value, sort_keys=True, default=_json_default) + + +def digest(data: str | bytes, length: int | None = None) -> str: + """Gets a hash of text (or bytes), as hexadecimal digits (the first `length`).""" + raw = data.encode() if isinstance(data, str) else data + text = hashlib.sha1(raw).hexdigest() + return text if length is None else text[:length] diff --git a/src/tatc/tradespace/histories.py b/src/tatc/tradespace/histories.py new file mode 100644 index 0000000..98d4bfa --- /dev/null +++ b/src/tatc/tradespace/histories.py @@ -0,0 +1,410 @@ +""" +Many histories of missions in a replicate (simulated by +`Deployment.simulate_many`): their evaluation with a cache of the metrics +of their phases (see `PhaseCache`), their summaries as the records of +evaluations, with control variates, and the allocation of evaluations +between replicates and histories. The exact expectations of missions +without restoration are in the module `expectations`. + +@author: Paul T. Grogan +""" + +from __future__ import annotations + +import math +import warnings +from collections.abc import Mapping, Sequence +from typing import Any + +import numpy as np +import pandas as pd + +from .criteria import Requirement +from .mission import Capability, MissionHistory, summarize_phases +from .statistics import Probability, Quantile, StandardDeviation, Statistic + + +def evaluate_histories( + histories: Sequence[MissionHistory], + capability: Capability, + *, + cost_model: Any = None, + growth: Any = 1.0, + requirements: Sequence[Requirement] = (), +) -> pd.DataFrame: + """ + Evaluates histories of a mission (such as those of a replicate, see + `Deployment.simulate_many`): for each, the mean of each metric over the + phases of the mission (` mission`, see `summarize_phases`), the + time at which a phase first meets each requirement on a metric + (` time`, infinite if none does), its measures (see + `MissionHistory.metrics`), and its cost (see `CostEstimate.metrics`, + with a cost model). The histories share the observations of the + replicate, so that each set of operating satellites is evaluated once, + by the capability of the satellites (see `Capability.evaluate`, with the + cache of its metric). + + Args: + histories (Sequence[MissionHistory]): The histories. + capability (Capability): The capability of the satellites: their + observations (of the replicate) and metric. + cost_model (CostModel | None): A model of the cost of each history. + growth (float | Mapping[str, float]): The growth of the cost. + requirements (Sequence[Requirement]): Requirements on the metrics of + the phases, if any. + + Returns: + pandas.DataFrame: a row per history (with its likelihood ratio, + `weight`, if the histories are of stressed failures) + """ + rows = [] + weighted = any(history.weight != 1.0 for history in histories) + for history in histories: + phases = capability.evaluate(history.phases(capability.satellites)) + row = { + **summarize_phases(phases, requirements=requirements), + **history.metrics(), + } + if weighted: + row["weight"] = history.weight + if cost_model is not None: + row.update(cost_model.estimate(history, growth).metrics()) + rows.append(row) + return pd.DataFrame(rows) + + +def summarize_histories( + histories: pd.DataFrame, + *, + statistics: Sequence[Statistic] = (), + controls: Mapping[str, float] | None = None, +) -> dict[str, float]: + """ + Summarizes histories of a mission (see `evaluate_histories`) as the + metrics of an evaluation: the mean of each column over the histories + (by the same name), and `statistics` of columns over the histories, as + those of `Criteria` are over the replicates, named after the histories: + a `Quantile` (` histories + p`, such as `"accurate mission histories p10"` for the 0.1 + quantile, the risk of the mission), a `Probability` (`P( + ) histories`, such as `"P(accurate time <= 4) + histories"`, the share of the histories that meet it), or a + `StandardDeviation` (` histories std`, as `allocate_histories` + needs of a pilot study). The statistics over the histories of a + replicate end in `histories`, apart from the statistics over the + replicates (see `Criteria`), which are taken of these. + + Missing values (`NaN`, such as the `restoration years` of a history + without restorations) are left out of the statistics of their column, + but infinite ones are not: the mean of the time until a history meets a + requirement (` time`, see `evaluate_histories`) is infinite if a + history never meets it, and its quantiles, or the share of the + histories that meet it by a time (such as `Probability("accurate time", + "<=", 4)`), summarize it. Histories of equal weights take each statistic + as over replicates (a linear quantile, and a standard deviation that is + `NaN` with an infinite value); weighted ones take the quantile of the + weighted distribution. + + With `controls`, the means are estimated with control variates: columns + whose expected values are known (such as the `availability` of a + mission, which simulations alone estimate precisely and cheaply), and + which vary with the other columns from history to history. The mean of + each other column is corrected by the deviation of the controls' means + from their expected values, times the regression of the column on the + controls over the histories, which removes the share of its variance + that the controls explain (a share of `rho ** 2` for a correlation + `rho`): fewer histories give the same precision. The other statistics + are not corrected, nor are the means of columns with an infinite value + (such as the time until a requirement is met, if a history never meets + it), which stay infinite. + + Histories of stressed failures (see `Deployment.simulate_many`) are + weighted by their likelihood ratios (`weight`), for every statistic, and + the effective number of histories (`effective histories`, the square of + the sum of the weights over the sum of their squares) measures how much + a few weights dominate. + + The statistics are over the histories of a replicate, whose statistics + over the replicates (such as their mean, see `summarize`) combine the + risk of the mission with the uncertainty of the replicates' other + parameters (such as their targets). + + Args: + histories (pandas.DataFrame): A row per history. + statistics (Sequence[Statistic]): Statistics of columns over the + histories: `Quantile`, `Probability`, or `StandardDeviation`. + controls (Mapping[str, float] | None): The expected values of + columns that are control variates, if any. + + Returns: + dict[str, float]: the summary + + Raises: + TypeError: if a statistic is not one of these. + ValueError: if a statistic is of a column that the histories do not + have. + """ + statistics = _history_statistics(statistics) + numeric = histories.select_dtypes("number") + named = [statistic.column for statistic in statistics] + unknown = sorted(set(named) - set(numeric.columns)) + if unknown: + raise ValueError( + "statistics of columns that the histories do not have: " + + f"{unknown} (they have {sorted(numeric.columns)})" + ) + weights = np.ones(len(numeric)) + if "weight" in numeric.columns: + weights = numeric.pop("weight").to_numpy(dtype=float) + summary = { + column: _weighted_mean(numeric[column].to_numpy(dtype=float), weights) + for column in numeric.columns + } + if "weight" in histories.columns: + summary["effective histories"] = float(weights.sum() ** 2 / np.sum(weights**2)) + if controls: + summary.update(_controlled_means(numeric, controls, weights)) + for statistic in statistics: + values = numeric[statistic.column].to_numpy(dtype=float) + summary[_history_name(statistic)] = _weighted_statistic( + statistic, values, weights + ) + return summary + + +_HISTORY_STATISTICS = (Quantile, Probability, StandardDeviation) +"""The statistics of columns over histories (see `summarize_histories`).""" + + +def _history_statistics(statistics: Sequence[Statistic]) -> tuple[Statistic, ...]: + """ + Gets statistics over histories (see `summarize_histories`), raising a + `TypeError` if one is not a statistic of a column of a kind that + summarizes histories. + """ + if isinstance(statistics, Statistic): + statistics = [statistics] + statistics = tuple(statistics) + for statistic in statistics: + if type(statistic) not in _HISTORY_STATISTICS or not isinstance( + statistic.column, str + ): + raise TypeError( + "statistics over histories are a Quantile, Probability, or " + + f"StandardDeviation of a column, not {statistic!r}" + ) + return statistics + + +def _history_name(statistic: Statistic) -> str: + """ + Gets the name of a statistic of a column over the histories of a + mission (see `summarize_histories`): ` histories p` of a + `Quantile`, `P( ) histories` of a + `Probability`, and ` histories std` of a `StandardDeviation`. + """ + if isinstance(statistic, Quantile): + return f"{statistic.column} histories p{100 * statistic.q:g}" + if isinstance(statistic, Probability): + return f"{statistic.name} histories" + return f"{statistic.column} histories std" + + +def _weighted_statistic( + statistic: Statistic, values: np.ndarray, weights: np.ndarray +) -> float: + """ + Computes a statistic over histories (see `summarize_histories`) of their + values, by their weights, leaving out missing values (`NaN`): with equal + weights, the statistic as over replicates (see `Statistic.reduce`), and + otherwise weighted (a quantile of the weighted distribution, and a + standard deviation that is `NaN` with an infinite value). + """ + known = ~np.isnan(values) + given = weights[known] + if len(given) == 0 or np.all(given == given[0]): + return float(statistic.reduce(values[None, :])[0]) + if isinstance(statistic, Quantile): + return _weighted_quantile(values, weights, statistic.q) + if isinstance(statistic, Probability): + if weights[known].sum() <= 0: + return math.nan + requirement = Requirement( + statistic.column, statistic.operator, statistic.threshold + ) + met = requirement.met(values[known]) + return float(np.sum(weights[known] * met) / np.sum(weights[known])) + count = known.sum() + if count < 2 or np.isinf(values[known]).any(): + return math.nan + mean = _weighted_mean(values, weights) + variance = _weighted_mean((values - mean) ** 2, weights) + return float(np.sqrt(variance * count / (count - 1))) + + +def _weighted_mean(values: np.ndarray, weights: np.ndarray) -> float: + """ + The weighted mean of the known values (not `NaN`, but infinite ones), + `NaN` without any. + """ + known = ~np.isnan(values) + if not known.any() or weights[known].sum() <= 0: + return math.nan + return float(np.sum(weights[known] * values[known]) / np.sum(weights[known])) + + +def _weighted_quantile(values: np.ndarray, weights: np.ndarray, q: float) -> float: + """ + The quantile of the known values (not `NaN`, but infinite ones), by + their weights: the least value whose cumulative weight reaches the share + `q` of the total (as numpy's `inverted_cdf`). + """ + known = ~np.isnan(values) + values, weights = values[known], weights[known] + if len(values) == 0: + return math.nan + order = np.argsort(values) + cumulative = np.cumsum(weights[order]) / weights.sum() + position = min(int(np.searchsorted(cumulative, q - 1e-12)), len(values) - 1) + return float(values[order][position]) + + +def _controlled_means( + numeric: pd.DataFrame, controls: Mapping[str, float], weights: np.ndarray +) -> dict: + """ + Estimates the means of columns with control variates (see + `summarize_histories`): each column's mean less the regression of the + column on the controls applied to the deviations of the controls' means + from their expected values, over the histories in which the column and + the controls are known. A column with an infinite value keeps its plain + (infinite) mean. + """ + names = list(controls) + missing = set(names) - set(numeric.columns) + if missing: + raise ValueError(f"no columns of controls {sorted(missing)}") + expected = np.array([float(controls[name]) for name in names]) + means = {name: float(value) for name, value in zip(names, expected)} + for column in numeric.columns: + if column in controls: + continue + if np.isinf(numeric[column].to_numpy(dtype=float)).any(): + continue # an infinite mean (such as of a time never met) is kept + data = numeric[[column, *names]].to_numpy(dtype=float) + known = np.all(np.isfinite(data), axis=1) + data, w = data[known], weights[known] + if len(data) <= len(names) + 1 or w.sum() <= 0: + continue + y, x = data[:, 0], data[:, 1:] + y_mean, x_mean = np.average(y, weights=w), np.average(x, axis=0, weights=w) + centered = x - x_mean + if not np.any(centered): + continue + root = np.sqrt(w)[:, None] + beta = np.linalg.lstsq(root * centered, root[:, 0] * (y - y_mean), rcond=None)[ + 0 + ] + means[column] = float(y_mean - (x_mean - expected) @ beta) + return means + + +def allocate_histories( + records: pd.DataFrame, + metric: str, + *, + histories: int, + replicate_seconds: float, + history_seconds: float, + standard_error: float | None = None, + max_histories: int = 10_000, +) -> dict[str, float]: + """ + Recommends how to divide the evaluations of a design between replicates + (each a sample of its uncertain parameters other than failures, such as + its targets, whose observations are expensive to compute) and histories + of the failures of its mission in each replicate (cheap, with a + `PhaseCache`), from a pilot study: the records of its replicates (with + the statistic `StandardDeviation(metric)` of `Failures`, see + `summarize_histories`), each the mean (``) and standard + deviation (` histories std`) of a metric over `histories` + histories. + + The variance of a replicate's mean is `between + within / K` for `K` + histories, with `within` the variance between the histories of a + replicate and `between` the variance between replicates of their + expected values, at a cost of `replicate_seconds + K * history_seconds`. + The variance of the mean of the replicates per second of evaluation is + least for `K = sqrt(replicate_seconds * within / (history_seconds * + between))`: more histories where failures vary more than replicates, or + where a history costs less than a replicate. With a `standard_error` of + the mean, the replicates that achieve it at that number of histories. + + The variances are estimated from independent histories, so the pilot's + must be (`sampling="random"`, see `Deployment.simulate_many`): the means + of stratified histories vary less than those of independent ones, which + would hide the variance between replicates (a warning is given if the + means vary less than independent histories can). Studies with stratified + histories then need fewer histories than recommended. With a standard + error that the least replicates (two) achieve, the fewest histories that + achieve it are recommended. + + Args: + records (pandas.DataFrame): The records of the pilot replicates of a + design. + metric (str): The metric. + histories (int): The histories of each pilot replicate. + replicate_seconds (float): The cost of a replicate without its + histories (such as computing the observations of its targets). + history_seconds (float): The cost of a history. + standard_error (float | None): A standard error of the mean of the + metric over the replicates to achieve, if any. + max_histories (int): The most histories to recommend. + + Returns: + dict[str, float]: the recommended `histories` (and `replicates`, with + a standard error), the standard deviations `between` and + `within`, and the time of a replicate (`replicate seconds`) and of + the evaluations (`seconds`, with a standard error) + """ + if len(records) < 2: + raise ValueError("a pilot needs at least two replicates") + if histories < 2 or replicate_seconds <= 0 or history_seconds <= 0: + raise ValueError("a pilot needs two or more histories and positive costs") + means = records[metric].to_numpy(dtype=float) + within = float( + np.mean(records[f"{metric} histories std"].to_numpy(dtype=float) ** 2) + ) + observed = float(np.var(means, ddof=1)) + if observed < 0.5 * within / histories: + warnings.warn( + "the replicates' means vary less than independent histories can: " + + "pilots need independent histories (sampling='random')", + stacklevel=2, + ) + between = max(observed - within / histories, 0.0) + if between == 0: + count = max_histories if within > 0 else 1 + else: + count = math.sqrt(replicate_seconds * within / (history_seconds * between)) + count = int(min(max(round(count), 1), max_histories)) + cost = replicate_seconds + count * history_seconds + result = { + "histories": float(count), + "between": math.sqrt(between), + "within": math.sqrt(within), + "replicate seconds": cost, + } + if standard_error is not None: + if standard_error <= 0: + raise ValueError("standard_error must be positive") + variance = between + within / count + replicates = max(math.ceil(variance / standard_error**2), 2) + if replicates == 2 and 2 * standard_error**2 > between: + # the least replicates suffice: the fewest histories that do + needed = math.ceil(within / (2 * standard_error**2 - between)) + count = int(min(max(needed, 1), count)) + cost = replicate_seconds + count * history_seconds + result.update(histories=float(count), **{"replicate seconds": cost}) + result.update(replicates=float(replicates), seconds=replicates * cost) + return result diff --git a/src/tatc/tradespace/memory.py b/src/tatc/tradespace/memory.py new file mode 100644 index 0000000..3808751 --- /dev/null +++ b/src/tatc/tradespace/memory.py @@ -0,0 +1,29 @@ +""" +Objects that keep results in memory (such as caches of the metrics of the +phases of missions, the targets of replicates, and the caches of their +observations), whose copies sent to the parallel workers of a study start +with empty memories. + +@author: Paul T. Grogan +""" + +from __future__ import annotations + + +class Forgetful: + """ + A mixin of objects that keep results in memory, in the attributes named + by `_forgotten` (each a container, such as a dictionary), which their + copies (such as those pickled for the parallel workers of a study) start + without: empty containers of the same types. + """ + + # pylint: disable=too-few-public-methods + + _forgotten: tuple[str, ...] = () + + def __getstate__(self) -> dict: + state = self.__dict__.copy() + for name in self._forgotten: + state[name] = type(state[name])() + return state diff --git a/src/tatc/tradespace/mission.py b/src/tatc/tradespace/mission.py new file mode 100644 index 0000000..fe4c33d --- /dev/null +++ b/src/tatc/tradespace/mission.py @@ -0,0 +1,831 @@ +""" +Simulated missions: the history of a deployment with failures and +restorations (see `Deployment.simulate`, whose simulation is in the module +`simulation`), the decisions of the rules of its stages, the phases of a +mission in which constant sets of satellites operate, and their evaluation +over the study's representative period and combination over the mission; +and the mission of a replicate of a design of an observation study +(`Mission`), which an evaluation plans (see `MissionPlan`) and summarizes +into its record. + +@author: Paul T. Grogan +""" + +from __future__ import annotations + +import math +from collections.abc import Callable, Iterable, Mapping, Sequence +from dataclasses import dataclass, field +from functools import cached_property, partial +from typing import TYPE_CHECKING, Any, NamedTuple + +import numpy as np +import pandas as pd + +from ..schemas import Satellite +from .cache import get_satellite_key +from .criteria import Requirement +from .events import Launch, PlannedPlane, Production +from .memory import Forgetful +from .references import _given_design + +if TYPE_CHECKING: + from .cost import CostEstimate, CostModel + from .deployment import Deployment, DeploymentSchedule + from .plans import Failures + from .space import Design + + +@dataclass(frozen=True) +class Phase: + """ + A phase of a mission, in which a set of satellites operates (see + `MissionHistory.phases`). + """ + + start: float + """float: The start (years from the start of development).""" + end: float + """float: The end (years from the start of development).""" + satellites: tuple[str, ...] + """tuple[str, ...]: The names of the satellites that operate.""" + + @property + def duration(self) -> float: + """float: The duration (years).""" + return self.end - self.start + + +_PHASE_COLUMNS = ("start", "end", "duration", "satellites") +"""The columns of the evaluations of phases that are not metrics (see +`evaluate_phases`).""" + + +def _names(satellites: Sequence[Satellite | str]) -> list[str]: + return [s.name if isinstance(s, Satellite) else str(s) for s in satellites] + + +def _position_names( + planes: Sequence[PlannedPlane], satellites: Sequence[Satellite | str] +) -> dict[tuple[int, int], str]: + """ + Gets the name of the satellite at each position of each plane (by plane + and position) of satellites in the order of the planes, without spares + (see `MissionHistory.phases`), raising a `ValueError` if their numbers + differ. + """ + names = _names(satellites) + positions = [ + (plane, position) + for plane, (_, built, _) in enumerate(planes) + for position in range(built) + ] + if len(names) != len(positions): + raise ValueError( + f"expected {len(positions)} satellites for the planes, not {len(names)}" + ) + return dict(zip(positions, names)) + + +def _satellite_keys(satellites: Sequence[Satellite | str]) -> dict[str, str]: + """ + Gets the keys of satellites in a cache of their metrics (see + `PhaseCache`), by name: of their content (see `get_satellite_key`), or + their names, if given as names. + """ + return { + name: get_satellite_key(s) if isinstance(s, Satellite) else name + for name, s in zip(_names(satellites), satellites) + } + + +class Failure(NamedTuple): + """A failure of a satellite (see `MissionHistory.failures`).""" + + time: float + """float: The time of the failure (years from the start of development).""" + plane: int + """int: The plane (its index).""" + position: int + """int: The position in the plane.""" + cause: str + """str: `"life"`, or `"launch"` (lost in a launch).""" + + +class Restoration(NamedTuple): + """A restoration of a failed satellite (see `MissionHistory.restorations`).""" + + plane: int + """int: The plane (its index).""" + position: int + """int: The position in the plane.""" + failed: float + """float: The time of the failure (years from the start of development).""" + restored: float + """float: The time of the restoration.""" + source: str + """str: `"orbit"` (a spare in orbit), `"ground"` (a spare on the ground), + or `"production"` (a satellite produced when needed).""" + + +@dataclass +class MissionHistory: + """ + The history of a simulated mission (see `Deployment.simulate`): what is + produced and launched (as a deployment, which a `CostModel` prices), when + satellites fail and are restored, and when each operates. + """ + + deployment: Deployment + """Deployment: The planned deployment.""" + production: list[Production] = field(default_factory=list) + """list[Production]: The production of satellites, in order.""" + launches: list[Launch] = field(default_factory=list) + """list[Launch]: The launches, in order.""" + operating: dict[tuple[int, int], list[tuple[float, float]]] = field( + default_factory=dict + ) + """dict: The intervals in which the satellite at each position of each + plane (by plane and position) operates.""" + parked: list[tuple[float, float, int]] = field(default_factory=list) + """list: The intervals in which spares wait in orbit, and their number.""" + failures: list[Failure] = field(default_factory=list) + """list[Failure]: The failures: their time, plane, position, and cause + (`"life"` or `"launch"`).""" + restorations: list[Restoration] = field(default_factory=list) + """list[Restoration]: The restorations: their plane, position, the time + of the failure and of the restoration, and the source (`"orbit"`, + `"ground"`, or `"production"`).""" + weight: float = 1.0 + """float: The likelihood ratio of the history, drawn from stressed + failures (see `Deployment.simulate_many`), or 1.""" + decided: list[float | None] = field(default_factory=list) + """list: When the rule of each stage of the deployment decided to deploy + it (years from the start of development, see `Stage`), or `None` if it + did not.""" + + @property + def schedule(self) -> DeploymentSchedule: + """DeploymentSchedule: The schedule of the deployment.""" + return self.deployment.schedule + + @property + def planes(self) -> list[PlannedPlane]: + """list[PlannedPlane]: The planes of the deployment.""" + return self.deployment.planes + + @property + def development(self) -> dict[Any, float]: + """dict: The end of the development of each type of satellite.""" + return self.deployment.development + + @property + def masses(self) -> dict[Any, float | None]: + """dict: The mass of each type of satellite, if given.""" + return self.deployment.masses + + @property + def begin(self) -> float: + """float: The beginning of the mission (its planned first launch).""" + return self.deployment.begin + + @property + def end(self) -> float: + """float: The end of the mission.""" + return self.deployment.end + + @property + def deployed(self) -> float: + """float: The time by which the satellites of the first generation + are launched (years), whether their launches succeed or not: of the + planes that are not staged, and of the stages that this history + deployed (see `decided`). It is infinite if the deployment does not + finish within the mission (a launch of the first generation booked at + or after its end), as is the time until the mission meets a + requirement that it never meets (see `summarize_phases`).""" + launched = [0] * len(self.planes) + for launch in self.launches: + if launch.purpose == "deployment": + launched[launch.plane] += launch.satellites + stage_of = { + plane: index + for index, stage in enumerate(self.deployment.stages) + for plane in stage.planes + } + for plane, (_, satellites, spares) in enumerate(self.planes): + index = stage_of.get(plane) + if index is not None and ( + index >= len(self.decided) or self.decided[index] is None + ): + continue # a stage that is not deployed + if launched[plane] < satellites + spares: + return math.inf + return max( + launch.time for launch in self.launches if launch.purpose == "deployment" + ) + + def in_orbit(self) -> list[tuple[float, float, int]]: + """ + Gets the intervals in which satellites are in orbit (operating, or + spares waiting), for the cost of their operations. + + Returns: + list: the intervals, and the number of satellites in each + """ + spans = [ + (start, stop, 1) + for intervals in self.operating.values() + for start, stop in intervals + ] + return spans + list(self.parked) + + def phases(self, satellites: Sequence[Satellite | str]) -> list[Phase]: + """ + Gets the phases of the mission, from its beginning to its end, in + which constant sets of satellites operate. + + The satellites are those built for the layouts of the deployment + (see `build_constellation`), in the order of their planes (and of + several layouts, in the order given to `DeploymentSchedule.plan`), + without spares: the satellite at each position of each plane is the + one (and its replacements) that operates there. + + Args: + satellites (Sequence[Satellite | str]): The satellites (or their + names), in the order of the planes. + + Returns: + list[Phase]: the phases, in order + """ + named = _position_names(self.planes, satellites) + names = list(named.values()) + intervals = { + named[position]: spans for position, spans in self.operating.items() + } + begin, end = self.begin, self.end + events = {begin, end} + for spans in intervals.values(): + for start, stop in spans: + events.update((start, stop)) + times = sorted(time for time in events if begin <= time <= end) + phases: list[Phase] = [] + for start, stop in zip(times[:-1], times[1:]): + if stop - start <= 1e-12: + continue + middle = (start + stop) / 2 + active = tuple( + name + for name in names + if any(a <= middle < b for a, b in intervals.get(name, [])) + ) + if phases and phases[-1].satellites == active: + phases[-1] = Phase(phases[-1].start, stop, active) + else: + phases.append(Phase(start, stop, active)) + return phases + + def metrics(self) -> dict[str, float]: + """ + Gets measures of the mission as metrics of an evaluation: the + failures of satellites (`failures`, including those lost in + launches), the launches that failed (`launch failures`), the + restorations (`restorations`), the spares used (`spares used`), the + mean time from failure to restoration (`restoration years`, `NaN` + without restorations), and the availability of the satellites + (`availability`: their years of operation, as a share of those + possible from the launches that deployed them to the end of the + mission, whether these succeeded or not, and of the stages that this + history deployed). + + Returns: + dict[str, float]: the metrics + """ + operated = sum(b - a for spans in self.operating.values() for a, b in spans) + built = [b for _, b, _ in self.planes] + possible = sum( + max(self.end - launch.time, 0.0) + * max( + min(launch.first + launch.satellites, built[launch.plane]) + - launch.first, + 0, + ) + for launch in self.launches + if launch.purpose == "deployment" + ) + delays = [r.restored - r.failed for r in self.restorations] + metrics = { + "failures": float(len(self.failures)), + "launch failures": float(sum(launch.failed for launch in self.launches)), + "restorations": float(len(self.restorations)), + "spares used": float( + sum(r.source != "production" for r in self.restorations) + ), + "restoration years": float(np.mean(delays)) if delays else math.nan, + "availability": operated / possible if possible > 0 else math.nan, + } + if self.deployment.stages: + metrics["stages deployed"] = float( + sum(time is not None for time in self.decided) + ) + return metrics + + +@dataclass(frozen=True) +class Decision: + """ + What the rule of a stage of a deployment knows when it decides whether to + deploy the stage (see `Stage`): the satellites operating and the history + so far, and the capability of the satellites operating (see + `capability`), such as for a stage deployed only if the satellites in + orbit fall short of a requirement. Its time is from the start of + development, as every time of a mission (see `since_launch` for the + time after the first launch, as of the times of the stage). + """ + + time: float + """float: The time of the decision (years from the start of + development).""" + stage: int + """int: The stage (its index).""" + satellites_operating: int + """int: The number of satellites operating.""" + history: MissionHistory + """MissionHistory: The history of the mission so far: its production, + launches, failures, restorations, and the periods of operation that + have ended.""" + stages_deployed: tuple[int, ...] + """tuple[int, ...]: The stages deployed so far (their indices).""" + _measure: Callable[[], dict[str, float]] | None = field( + default=None, repr=False, compare=False + ) + + @property + def since_launch(self) -> float: + """float: The time of the decision after the first launch (years), as + the times of stages are given (see `Stage`).""" + return self.time - self.history.begin + + @cached_property + def capability(self) -> dict[str, float]: + """dict[str, float]: The metrics of the satellites operating at the + decision, as of a phase in which they operate (see `Capability`): + the capability of the satellites in orbit then, evaluated only if a + rule reads it. It is the capability that the evaluation computes, + as if the mission measured it exactly and at once: a rule that + decides from an estimate adds its error (such as from an uncertain + parameter of the design), and one that waits for a measurement + decides later. + + Raises: + ValueError: if the deployment has no capability (see + `Deployment.capability`, which the evaluations of an + `ObservationStudy` with a `MissionPlan` give).""" + if self._measure is None: + raise ValueError( + "the capability of the satellites at a decision needs a " + + "deployment with a capability (see Deployment.capability), " + + "as the evaluations of an ObservationStudy with a plan give" + ) + return dict(self._measure()) + + +def evaluate_phases( + phases: Sequence[Phase], + observations: pd.DataFrame, + metric: Callable[..., Mapping[str, float]], + *, + design: Any = None, +) -> pd.DataFrame: + """ + Evaluates the phases of a mission: a metric of the observations of the + satellites that operate in each phase, over the study's representative + period (the observations of the full constellation, by satellite, such + as from a `SatelliteCache`, filtered to those of each phase). Phases of + the same satellites are evaluated once. + + The phases are quasi-static: each is evaluated over the same window, as + if the geometry of the constellation (and the season) were that of the + window throughout the mission. This misses the drift of the relative + nodes of shells of different inclinations or altitudes (which precess at + different rates), the drift of the local times of planes that are not + sun-synchronous, and seasons (for metrics that depend on the sun, or on + fields that vary with the seasons). Replicates average over these if the + epoch of the window is an uncertain parameter drawn over the mission (see + `Observations`), as are the relative nodes of shells (such as the nodes + of `planes_space`). A constellation whose planes share an altitude and + inclination keeps its geometry, so that only seasons remain. + + Args: + phases (Sequence[Phase]): The phases (see `MissionHistory.phases`). + observations (pandas.DataFrame): The observations of every + satellite, with their names (`satellite`). + metric (Callable): A function of the observations of a phase (which + may be empty) that gives its metrics (and of the design, if it + has a parameter named `design`, as the metrics of a study). + design (Design | None): The (realized) design of the mission, for a + metric with a parameter named `design`. + + Returns: + pandas.DataFrame: a row per phase: its `start`, `end`, `duration`, + number of `satellites`, and metrics + """ + given = _given_design(metric, design) + return _evaluate_phases(phases, observations, lambda subset, _: given(subset())) + + +def summarize_phases( + phases: pd.DataFrame, + *, + metrics: Sequence[str] | None = None, + requirements: Sequence[Requirement] = (), +) -> dict[str, float]: + """ + Summarizes the capability of a mission over its phases (see + `evaluate_phases`): the mean of each metric weighted by the durations of + the phases (` mission`, over the mission, from its first launch), + and, for each requirement on a metric, the time (years from the start of + development) at which a phase first meets it (` time`, infinite + if none does). + + Args: + phases (pandas.DataFrame): The metrics of each phase (see + `evaluate_phases`). + metrics (Sequence[str] | None): The metrics, or `None` for every + column other than those of the phases (`start`, `end`, + `duration`, and `satellites`). + requirements (Sequence[Requirement]): Requirements on metrics, at + most one of each metric (whose time it names). + + Returns: + dict[str, float]: the summary, as metrics of an evaluation + + Raises: + ValueError: if two requirements are of the same metric. + """ + named = [requirement.name for requirement in requirements] + repeated = sorted({name for name in named if named.count(name) > 1}) + if repeated: + raise ValueError( + f"requirements on phases of the same metrics: {repeated} (the time " + + "until a phase meets a requirement is named by its metric)" + ) + if metrics is None: + metrics = [column for column in phases.columns if column not in _PHASE_COLUMNS] + weights = phases["duration"].to_numpy(dtype=float) + summary = {} + for name in metrics: + values = phases[name].to_numpy(dtype=float) + summary[f"{name} mission"] = float(np.sum(values * weights) / np.sum(weights)) + for requirement in requirements: + met = requirement.met(phases[requirement.name].to_numpy(dtype=float)) + starts = phases["start"].to_numpy(dtype=float)[met] + summary[f"{requirement.name} time"] = ( + float(starts[0]) if len(starts) > 0 else math.inf + ) + return summary + + +def _evaluate_phases( + phases: Sequence[Phase], + observations: pd.DataFrame, + metric: Callable[[Callable[[], pd.DataFrame], frozenset], Mapping[str, float]], +) -> pd.DataFrame: + """ + Evaluates phases with a metric of a function that gets their + observations (only if needed) and the names of their satellites (see + `evaluate_phases`), each set of satellites once. + """ + rows, evaluated = [], {} + for phase in phases: + names = frozenset(phase.satellites) + if names not in evaluated: + subset = partial(_subset, observations, names) + evaluated[names] = dict(metric(subset, names)) + rows.append( + { + "start": phase.start, + "end": phase.end, + "duration": phase.duration, + "satellites": len(phase.satellites), + **evaluated[names], + } + ) + return pd.DataFrame(rows) + + +def _subset(observations: pd.DataFrame, names: frozenset) -> pd.DataFrame: + """The observations of the satellites of names (none if not by satellite).""" + if "satellite" in observations.columns: + return observations[observations["satellite"].isin(names)] + return observations.iloc[0:0] + + +def _as_cache(metric: Callable[..., Mapping[str, float]] | PhaseCache) -> PhaseCache: + """Gets a cache of a metric (see `PhaseCache`), or the cache given.""" + return metric if isinstance(metric, PhaseCache) else PhaseCache(metric) + + +class PhaseCache(Forgetful): + """ + A cache of a metric of the phases of missions (see `evaluate_phases`), + keyed by a context that identifies the observations (such as the seed of + a replicate's sample of targets and the analysis period) and by the + content of the satellites that operate (see `get_satellite_key`), so that + the phases of missions with the same satellites (of other histories, + policies, or designs, in the same replicate) are evaluated once. The + capabilities of the satellites of missions share it (see `Capability`). + + The metric must depend only on the observations (of the one window of + the observations, see `evaluate_phases`), not on the names of the + satellites. A metric with a parameter named `design` is given the design + of the mission (see `Capability`), on which it must depend only through + what the context identifies (such as a scenario). Copies sent to the + parallel workers of a study start with an empty memory, which the + evaluations of a chunk share (consecutive evaluations of the same + replicate, see `Study`). + + Args: + metric (Callable): A function of the observations of a phase (which + may be empty) that gives its metrics. + """ + + _forgotten = ("_memory",) + + def __init__(self, metric: Callable[..., Mapping[str, float]]): + self.metric = metric + self.hits = 0 + """int: The phases taken from the cache.""" + self.misses = 0 + """int: The phases evaluated.""" + self._memory: dict = {} + + def _metrics_of( + self, + keys: Mapping[str, str], + observations: pd.DataFrame, + *, + context: Any = None, + design: Any = None, + ) -> dict[str, float]: + """ + Gets the metrics of satellites that operate together, by their keys + in the cache (by their names in the observations), from the cache if + they are in it (keyed by the context and the keys, with those of + satellites of the same content counted, as each observes), or else + of their observations (and kept), given the design if the metric + takes one. + """ + key = (context, tuple(sorted(keys.values()))) + if key in self._memory: + self.hits += 1 + else: + self.misses += 1 + metric = _given_design(self.metric, design) + self._memory[key] = dict(metric(_subset(observations, frozenset(keys)))) + return dict(self._memory[key]) + + def clear(self) -> None: + """ + Clears the cache and its statistics. + """ + self._memory.clear() + self.hits = self.misses = 0 + + def __repr__(self) -> str: + return ( + f"PhaseCache({len(self._memory)} results, " + + f"{self.hits} hits, {self.misses} misses)" + ) + + +class Capability: + """ + The capability of the satellites that operate together at a time of a + mission: the metrics of their observations, as of a phase in which they + operate (over the study's representative period, see + `evaluate_phases`), which the rules of stages read at their decisions + (see `Decision.capability` and `Deployment.capability`). The + evaluations of an `ObservationStudy` with a `MissionPlan` give their + deployments the capability of their satellites, with the cache of their + phases: the satellites operating at a decision are those of a phase of + the mission, which the evaluation evaluates anyway. + + A capability also evaluates the phases of the mission's histories (see + `evaluate`, `evaluate_histories`, and `exact_expectations`), with its + cache. + + Args: + satellites (Sequence[Satellite | str]): The satellites (or their + names), in the order of the planes (see `MissionHistory.phases`). + observations (pandas.DataFrame): The observations of every + satellite, with their names (`satellite`). + metric (Callable | PhaseCache): A function of the observations of + satellites (which may be empty) that gives their metrics, or a + cache of one (which keys satellites by their content, or by the + names given for them). + context (Any): A hashable identifier of the observations, for a + cache (see `PhaseCache`). + design (Design | None): The (realized) design of the mission, for a + metric with a parameter named `design`. + """ + + def __init__( + self, + satellites: Sequence[Satellite | str], + observations: pd.DataFrame, + metric: Callable[..., Mapping[str, float]] | PhaseCache, + *, + context: Any = None, + design: Any = None, + ): + self.satellites = list(satellites) + """list: The satellites (or their names), in the order of the planes.""" + self.observations = observations + """pandas.DataFrame: The observations of every satellite.""" + self.metric = metric + """Callable | PhaseCache: The metric, or a cache of one.""" + self.context = context + """Any: The identifier of the observations, for a cache.""" + self.design = design + """Design | None: The (realized) design of the mission.""" + self.names = _names(self.satellites) + """list[str]: The names of the satellites, in the order of the + planes.""" + + @cached_property + def _keys(self) -> dict[str, str]: + """The keys of the satellites in a cache, by name.""" + return _satellite_keys(self.satellites) + + @cached_property + def _cache(self) -> PhaseCache: + """The cache of the metric (that given, or one of its own).""" + return _as_cache(self.metric) + + def evaluate(self, phases: Sequence[Phase]) -> pd.DataFrame: + """ + Evaluates the phases of a mission of the satellites (see + `evaluate_phases`): the metrics of the satellites that operate in + each, each set evaluated once (by the cache, with the context and the + design, see `PhaseCache`). + + Args: + phases (Sequence[Phase]): The phases (of the satellites, see + `MissionHistory.phases`). + + Returns: + pandas.DataFrame: a row per phase: its `start`, `end`, + `duration`, number of `satellites`, and metrics + """ + return _evaluate_phases(phases, self.observations, lambda _, names: self(names)) + + def __call__(self, names: Iterable[str]) -> dict[str, float]: + """ + Gets the metrics of satellites that operate together. + + Args: + names (Iterable[str]): The names of the satellites. + + Returns: + dict[str, float]: the metrics + """ + names = frozenset(names) + unknown = names - set(self.names) + if unknown: + raise ValueError(f"satellites that are not given: {sorted(unknown)}") + # pylint: disable-next=protected-access + return self._cache._metrics_of( + {name: self._keys[name] for name in names}, + self.observations, + context=self.context, + design=self.design, + ) + + def _at( + self, + planes: Sequence[PlannedPlane], + positions: Iterable[tuple[int, int]], + ) -> dict[str, float]: + """ + Gets the metrics of the satellites at positions (by plane and + position) of the planes of a deployment (see `Deployment.planes`), as + the phases of its missions name them (see `MissionHistory.phases`). + """ + named = _position_names(planes, self.names) + return self(named[plane, position] for plane, position in positions) + + +@dataclass(frozen=True, eq=False) +class Mission: + """ + The mission of a replicate of a design, as the evaluation of an + observation study plans it (see `MissionPlan.plan_mission` and + `ObservationStudy.mission_of`): its planned deployment (with the policy + that restores the failures of its satellites, and the capability of its + satellites: their observations, and the cache of the metrics of their + phases), its cost model and growth, the failures of its satellites, and + the study's requirements on its phases, from which follow the metrics of + its phases (`phases`, of the history of the mission without failures, + see `Deployment.planned`), its cost estimate (`estimate`), and the + histories of its failures (`histories`). + """ + + design: Design + """Design: The realized design.""" + deployment: Deployment + """Deployment: The planned deployment, with its policy (see + `Deployment.policy`) and the capability of its satellites (which the + rules of its stages read, see `Deployment.capability`).""" + cost_model: CostModel | None + """CostModel | None: The cost model (with the growth of its components + drawn), if any.""" + growth: Any + """Any: The growth of the costs (see `CostModel.estimate`).""" + failures: Failures | None = None + """Failures | None: The failures of the satellites, if any.""" + requirements: tuple[Requirement, ...] | None = None + """tuple[Requirement, ...] | None: The requirements on the metrics of + its phases, whose times its evaluation and histories give (see + `summarize_phases`), or `None` if the phases of a mission without + failures are not summarized (with failures, they always are).""" + + @property + def capability(self) -> Capability: + """Capability: The capability of the satellites (that of the + deployment).""" + return self.deployment.capability + + def phases(self) -> pd.DataFrame: + """ + Gets the metrics of the phases of the mission without failures (see + `Deployment.phases` and `evaluate_phases`), which the evaluation of + a study with `phases` summarizes (see `summarize_phases`). + + Returns: + pandas.DataFrame: a row per phase: its `start`, `end`, + `duration`, number of `satellites`, and metrics + """ + satellites = self.capability.satellites + return self.capability.evaluate(self.deployment.phases(satellites)) + + def estimate(self) -> CostEstimate: + """ + Gets the cost estimate of the mission without failures (see + `CostModel.estimate` of its deployment), with its growth: the costs + of the evaluation of a study without failures (those of a study with + failures are the means of those of its histories, see `histories`). + + Returns: + CostEstimate: the estimate + + Raises: + ValueError: if the plan has no cost model. + """ + if self.cost_model is None: + raise ValueError("the mission plan has no cost model") + return self.cost_model.estimate(self.deployment, self.growth) + + def histories(self) -> pd.DataFrame: + """ + Gets the histories of the failures of the mission, which the + evaluation of a study with failures summarizes (see `Failures` and + `evaluate_histories`): a row per history, with the mean of each + metric over its phases, the times until they meet the requirements + (see `requirements`), the measures of its mission, and its costs. + + Returns: + pandas.DataFrame: a row per history + + Raises: + ValueError: if the mission has no failures. + """ + if self.failures is None: + raise ValueError("the study has no failures") + # pylint: disable-next=protected-access + return self.failures._evaluate(self) + + def _record(self) -> dict[str, float]: + """ + Gets the metrics of the mission that its evaluation records: + `deployed` (see `Deployment.deployed`, of the history without + failures) and `stages deployed` (of a staged deployment, the stages + that its rules deploy without failures); and the summary of the + histories of its failures (see `Failures`), or else its costs (see + `estimate` and `CostEstimate.metrics`) and, with requirements (or + none, `()`), the summary of its phases (see `summarize_phases`). + """ + planned = self.deployment.planned() + record = {"deployed": planned.deployed} + if self.deployment.stages: + record["stages deployed"] = planned.metrics()["stages deployed"] + if self.failures is not None: + # pylint: disable-next=protected-access + record.update(self.failures._summarize(self)) + return record + if self.cost_model is not None: + record.update(self.estimate().metrics()) + if self.requirements is not None: + record.update( + summarize_phases(self.phases(), requirements=self.requirements) + ) + return record diff --git a/src/tatc/tradespace/nodes.py b/src/tatc/tradespace/nodes.py new file mode 100644 index 0000000..85c9a05 --- /dev/null +++ b/src/tatc/tradespace/nodes.py @@ -0,0 +1,479 @@ +""" +Nodes of design spaces: design variables, fixed, derived, and uncertain +values, choices, and repetitions (see `tatc.tradespace.DesignSpace`). + +@author: Paul T. Grogan +""" + +from __future__ import annotations + +import math +import numbers +from collections.abc import Callable, Sequence +from dataclasses import dataclass +from typing import Any + +import numpy as np + +from .hashing import canonical, digest +from .values import Scope + + +class Infeasible(Exception): + """ + Raised while deciding a design that violates a constraint of its design + space or has a variable without feasible values, and by the build or + evaluation functions of a study to reject a design, which is then + recorded as infeasible (see `Study`). + + Args: + message (str): The reason. + violation (float): The amount by which the design violates its + constraint (positive), as for constraint-aware optimizers: the + value of a constraint that gives one, or 1. + """ + + def __init__(self, message: str = "", violation: float = 1.0): + super().__init__(message) + self.violation = violation + + +# --------------------------------------------------------------------------- +# nodes +# --------------------------------------------------------------------------- + + +class Node: + """ + Base class of the nodes of a design space. + """ + + +Bound = float | Callable[[Scope], float] +"""A bound of a variable: a value, or a callable of the values decided so far.""" + + +def _resolve_bound(bound: Any, scope: Scope) -> Any: + """ + Resolves a bound that may be a callable of the values decided so far. + """ + return bound(scope) if callable(bound) else bound + + +@dataclass(frozen=True) +class _Domain: + """ + The values a variable may take where it is decided: a finite list of + levels, or a continuous interval. The kind (`"real"`, `"integer"`, or + `"categorical"`) and the step between levels inform optimizers, as does + whether categorical levels depend on earlier decisions (`dynamic`). + """ + + levels: list | None = None + low: float = 0.0 + high: float = 1.0 + log: bool = False + kind: str = "categorical" + step: float | None = None + dynamic: bool = False + + def from_unit(self, u: float) -> Any: + """ + Maps a value in [0, 1] to a value of the domain: a level (each + level spans an equal part of [0, 1]) or a point of the interval + (uniform, or uniform in its logarithm). + """ + u = min(max(float(u), 0.0), 1.0) + if self.levels is not None: + return self.levels[min(int(u * len(self.levels)), len(self.levels) - 1)] + if self.log: + return float( + math.exp( + math.log(self.low) + u * (math.log(self.high) - math.log(self.low)) + ) + ) + return float(self.low + u * (self.high - self.low)) + + def suggest(self, trial: Any, name: str) -> Any: + """ + Suggests a value of the domain with an Optuna trial. Optuna requires + the same options of a categorical parameter in every trial, so the + options of a categorical variable that depend on earlier decisions + are a parameter of their own for each set of options (named by the + path and a hash of the options). + """ + if self.kind == "categorical": + if self.dynamic: + name = f"{name}#{digest(canonical(self.levels), 8)}" + return trial.suggest_categorical(name, self.levels) + if self.kind == "integer": + return trial.suggest_int( + name, self.levels[0], self.levels[-1], step=int(self.step) + ) + if self.levels is not None: + value = trial.suggest_float( + name, self.levels[0], self.levels[-1], step=self.step + ) + # the level nearest the suggestion, without rounding errors + index = round((value - self.levels[0]) / self.step) + return self.levels[min(max(index, 0), len(self.levels) - 1)] + return trial.suggest_float(name, self.low, self.high, log=self.log) + + +class Variable(Node): + """ + Base class of design variables: the leaves of a design space that are + searched by enumeration, sampling, or optimization. + """ + + def domain(self, scope: Scope) -> _Domain: + """ + Gets the values this variable may take, given the values decided so + far. + + Args: + scope (Scope): The values decided so far. + + Returns: + _Domain: the domain + """ + raise NotImplementedError + + +def _levels(low: float, high: float, step: float, integer: bool) -> list: + """ + Gets the levels from `low` to `high` (inclusive, within a small + tolerance) at intervals of `step`. + """ + if step <= 0: + raise ValueError("step must be positive") + count = math.floor((high - low) / step + 1e-9) + 1 + if integer: + return [int(low + k * step) for k in range(max(count, 0))] + return [round(low + k * step, 12) for k in range(max(count, 0))] + + +class Real(Variable): + """ + A real-valued design variable on `[low, high]`: continuous, or discrete + at intervals of `step` from `low`. A continuous variable cannot be + enumerated and makes every sampled design distinct, so give it a step + unless a search needs the continuum. + + Args: + low (float | Callable): The lower bound, or a callable of the values + decided so far. + high (float | Callable): The upper bound, or a callable of the values + decided so far. + step (float | None): The interval between levels, or `None` for a + continuous variable. + log (bool): `True` to sample a continuous variable uniformly in its + logarithm (requires a positive lower bound). + """ + + def __init__( + self, low: Bound, high: Bound, step: float | None = None, log: bool = False + ): + if step is not None and log: + raise ValueError("a discrete variable cannot be logarithmic") + self.low, self.high, self.step, self.log = low, high, step, log + + def domain(self, scope: Scope) -> _Domain: + low = float(_resolve_bound(self.low, scope)) + high = float(_resolve_bound(self.high, scope)) + if high < low: + raise Infeasible(f"empty range [{low}, {high}]") + if self.step is not None: + levels = _levels(low, high, self.step, integer=False) + return _Domain(levels=levels, kind="real", step=self.step) + if self.log and low <= 0: + raise ValueError("a logarithmic variable requires a positive lower bound") + return _Domain(low=low, high=high, log=self.log, kind="real") + + def __repr__(self) -> str: + log = ", log=True" if self.log else "" + return f"Real({self.low!r}, {self.high!r}, step={self.step!r}{log})" + + +class Integer(Variable): + """ + An integer design variable from `low` to `high` (inclusive) at intervals + of `step`. + + Args: + low (int | Callable): The lower bound, or a callable of the values + decided so far. + high (int | Callable): The upper bound, or a callable of the values + decided so far. + step (int): The interval between levels. + """ + + def __init__(self, low: Bound, high: Bound, step: int = 1): + self.low, self.high, self.step = low, high, step + + def domain(self, scope: Scope) -> _Domain: + low = int(_resolve_bound(self.low, scope)) + high = int(_resolve_bound(self.high, scope)) + if high < low: + raise Infeasible(f"empty range [{low}, {high}]") + levels = _levels(low, high, self.step, integer=True) + return _Domain(levels=levels, kind="integer", step=self.step) + + def __repr__(self) -> str: + return f"Integer({self.low!r}, {self.high!r}, step={self.step!r})" + + +class Categorical(Variable): + """ + A design variable that takes one of a list of unordered options (for + example, the identifiers of instruments in the catalog). Options should + be numbers, strings, or booleans, which identify designs (see + `Design.key`). + + Args: + options (Sequence | Callable): The options, or a callable of the + values decided so far. + """ + + def __init__(self, options: Sequence | Callable[[Scope], Sequence]): + if not callable(options) and len(options) == 0: + raise ValueError("a categorical variable requires at least one option") + self.options = options if callable(options) else list(options) + + def domain(self, scope: Scope) -> _Domain: + options = list(_resolve_bound(self.options, scope)) + if len(options) == 0: + raise Infeasible("no options") + return _Domain(levels=options, dynamic=callable(self.options)) + + def __repr__(self) -> str: + return f"Categorical({self.options!r})" + + +class Fixed(Node): + """ + A fixed value. Plain values given as children of a design space are + wrapped as fixed values. + + Args: + value (Any): The value. + """ + + def __init__(self, value: Any): + self.value = value + + def __repr__(self) -> str: + return f"Fixed({self.value!r})" + + +class Derived(Node): + """ + A value computed from the values decided so far (for example, the + equator crossing time of an orbit plane from its index). Derived values + are not searched, and do not identify designs (see `Design.key`). A + derived value that depends on an uncertain parameter is computed from its + nominal value (`NaN` or `None`) until a design is realized (see + `Design.realize`). + + Args: + function (Callable): The function of the values decided so far. + """ + + def __init__(self, function: Callable[[Scope], Any]): + self.function = function + + def __repr__(self) -> str: + return f"Derived({self.function!r})" + + +class Uncertain(Node): + """ + An uncertain (nuisance) parameter: a value that is not designed but + changes the outcome of a design, such as the phase of satellites in + their orbit planes or the epoch of an analysis. It is drawn for each + replicate of a design (see `Design.realize`), does not identify designs + (see `Design.key`), and takes its nominal value until then. + + The constructors of common distributions (`uniform`, `normal`, + `triangular`, `choice`, and `seed`) name their distributions in their + representations; their nominal values are `NaN` (or `None`), unless + given, so that what depends on them before a design is realized is + plainly unrealized. + + Args: + sampler (Callable): A function that draws a value from a + `numpy.random.Generator`. + nominal (Any): The value before a design is realized. + label (str | None): A description of the distribution, for the + representation (`None` for the sampler's). + """ + + def __init__( + self, + sampler: Callable[[np.random.Generator], Any], + nominal: Any = math.nan, + label: str | None = None, + ): + self.sampler, self.nominal, self.label = sampler, nominal, label + + @classmethod + def uniform(cls, low: float, high: float, nominal: Any = math.nan) -> Uncertain: + """ + An uncertain parameter distributed uniformly on `[low, high)`. + """ + return cls( + lambda rng: float(rng.uniform(low, high)), + nominal, + f"uniform({low!r}, {high!r})", + ) + + @classmethod + def normal(cls, mean: float, std: float, nominal: Any = math.nan) -> Uncertain: + """ + An uncertain parameter distributed normally. + """ + return cls( + lambda rng: float(rng.normal(mean, std)), + nominal, + f"normal({mean!r}, {std!r})", + ) + + @classmethod + def triangular( + cls, low: float, mode: float, high: float, nominal: Any = math.nan + ) -> Uncertain: + """ + An uncertain parameter with a triangular distribution from `low` to + `high`, most likely at `mode` (such as the growth of a cost). + """ + if not low <= mode <= high or low == high: + raise ValueError("a triangular distribution needs low <= mode <= high") + return cls( + lambda rng: float(rng.triangular(low, mode, high)), + nominal, + f"triangular({low!r}, {mode!r}, {high!r})", + ) + + @classmethod + def seed(cls) -> Uncertain: + """ + An uncertain seed of random numbers (an integer), for randomness that + a build or evaluation function draws itself, such as a sample of + targets or the failures of satellites (see `remove_failures`). With + common random numbers, every design draws the same seed in the same + replicate. + """ + return cls(lambda rng: int(rng.integers(2**31)), None, "seed()") + + @classmethod + def choice( + cls, options: Sequence, p: Sequence[float] | None = None, nominal: Any = None + ) -> Uncertain: + """ + An uncertain parameter that takes one of `options` (with + probabilities `p`, or equally likely). + """ + options = list(options) + label = f"choice({options!r}" + ("" if p is None else f", p={list(p)!r}") + ")" + return cls( + lambda rng: options[int(rng.choice(len(options), p=p))], nominal, label + ) + + def __repr__(self) -> str: + label = repr(self.sampler) if self.label is None else self.label + return f"Uncertain({label})" + + +def _as_node(value: Any) -> Node: + """ + Wraps a plain value as a fixed value. + """ + return value if isinstance(value, Node) else Fixed(value) + + +class Group(Node): + """ + Base class of groups of nodes (see `tatc.tradespace.DesignSpace`): its + children, by name, are decided in order, and its constraints are checked + once they are. + """ + + children: dict[str, Node] + """dict[str, Node]: The nodes, by name, in the order they are decided.""" + + constraints: list[Callable[[Scope], Any]] + """list[Callable]: The constraints on the values of the group.""" + + +class Choice(Node): + """ + A choice of exactly one of several alternatives (branches), each a node + (typically a `DesignSpace`). The nodes of the other branches are + inactive. The value of a choice gives the name of the chosen branch as + `choice` (and equals it), and the values of the branch as its attributes + (see `ChoiceValues`), so that its branches, and the children of branches + that are groups, may not be named `choice` or `value`. + + Args: + **branches (Node): The alternatives, by name. + """ + + def __init__(self, **branches: Any): + if len(branches) == 0: + raise ValueError("a choice requires at least one branch") + reserved = sorted({"choice", "value"}.intersection(branches)) + if reserved: + raise ValueError(f"reserved names of branches: {reserved}") + self.branches = {name: _as_node(node) for name, node in branches.items()} + for name, node in self.branches.items(): + children = getattr(node, "children", {}) + reserved = sorted({"choice", "value"}.intersection(children)) + if reserved: + raise ValueError( + f"reserved names of the values of branch {name!r}: {reserved}" + ) + + def __repr__(self) -> str: + return f"Choice({', '.join(self.branches)})" + + +class Repeat(Node): + """ + A node repeated a (variable) number of times, such as the orbit planes of + a constellation, each with its own design. The value of a repetition is a + sequence of the values of its items, whose length is also given as + `count`. Within an item, `index` gives its position. + + The items of an unordered repetition (`ordered=False`) are exchangeable: + designs whose items are the same up to their order are the same design, + whose items are sorted by their decisions (so their values must not + depend on `index`). + + Args: + item (Node): The repeated node. + count (int | Integer | Categorical | Fixed | Derived): The number of + items: fixed (a number, or a `Fixed` one), a design variable of + integers (`Integer`, or `Categorical` of integers), or derived + from the values decided before (`Derived`, which a search that + encodes designs in a unit hypercube cannot encode). + ordered (bool): `False` if designs that differ only in the order of + their items are the same. + """ + + def __init__(self, item: Any, count: Any, *, ordered: bool = True): + self.item = _as_node(item) + if isinstance(count, bool) or not isinstance( + count, (numbers.Integral, Integer, Categorical, Fixed, Derived) + ): + raise TypeError( + "the count of a repetition is a number, an Integer or Categorical " + + f"design variable, or a Fixed or Derived value, not {count!r}" + ) + if isinstance(count, numbers.Integral): + if count < 0: + raise ValueError("count must not be negative") + count = int(count) + self.count, self.ordered = count, ordered + + def __repr__(self) -> str: + return f"Repeat({self.item!r}, count={self.count!r}, ordered={self.ordered})" diff --git a/src/tatc/tradespace/observations.py b/src/tatc/tradespace/observations.py new file mode 100644 index 0000000..092e43a --- /dev/null +++ b/src/tatc/tradespace/observations.py @@ -0,0 +1,689 @@ +""" +Studies of the observations of constellations: the targets of each replicate, +the observations of each satellite (cached), and the metrics of a design's +observations and, with a mission plan (see the module `plans`), its +deployment and costs, the histories of its failures, and the phases of its +mission. + +The parts refer to the values of designs as `tatc.tradespace.references` +describes. + +@author: Paul T. Grogan +""" + +from __future__ import annotations + +import dataclasses +import numbers +import os +import warnings +from collections.abc import Callable, Mapping, Sequence +from datetime import datetime, timedelta +from functools import partial +from typing import Any + +import pandas as pd + +from ..analysis import collect_observations +from ..schemas import Satellite +from .cache import SatelliteCache +from .constellations import count_planes +from .criteria import Requirement +from .memory import Forgetful +from .mission import Capability, Mission, PhaseCache +from .plans import Failures, MissionPlan +from .references import Reference, _given_design, _number, _takes_design, value_of +from .space import Design, DesignSpace +from .study import Study, _Case + +_MAX_TARGETS = 32 +"""The most sets of targets (of seeds) kept in memory.""" + + +@dataclasses.dataclass(frozen=True, eq=False, init=False) +class Targets(Forgetful): + """ + The targets of observations (such as points): fixed (a data frame), or + generated by a function (such as + `tatc.generation.generate_points_fibonacci_lattice`) given the `arguments` + and `keywords`, and a seed (as its keyword `seed`): a value of the design + (such as of `Uncertain.seed`), so that each replicate samples other + targets, or a fixed seed (an integer), so that every replicate samples + the same targets:: + + Targets(generate_points_fibonacci_lattice, count=100, rotate=True, seed="points_seed") + Targets(generate_points_fibonacci_lattice, count=100, rotate=True, seed=7) + + Generated targets are kept in memory by seed. + + Args: + source (pandas.DataFrame | Callable): The targets, or a function that + generates them. + *arguments (Any): The arguments of the function. + seed (Reference | int | None): The value of the design that seeds + the function (see `value_of`), a fixed seed (an integer), or + `None` (to give the function no seed). + **keywords (Any): The keyword arguments of the function. + + Raises: + TypeError: if the source is neither a data frame nor a function, or + the seed is neither a reference, an integer, nor `None`. + ValueError: if fixed targets are given arguments or a seed. + """ + + source: Any + arguments: tuple + keywords: dict + seed: Reference | int | None + _forgotten = ("_memory",) # (copies sent to parallel workers) + + def __init__( + self, + source: Any, + *arguments: Any, + seed: Reference | int | None = None, + **keywords: Any, + ): + if not ( + seed is None + or isinstance(seed, str) + or callable(seed) + or (isinstance(seed, numbers.Integral) and not isinstance(seed, bool)) + ): + raise TypeError( + "the seed of targets is a value of the design (its name or path, " + + f"or a function of the design), an integer, or None, not {seed!r}" + ) + if isinstance(source, pd.DataFrame): + if arguments or keywords or seed is not None: + raise ValueError("fixed targets take no arguments or seed") + elif not callable(source): + raise TypeError( + "targets are a data frame or a function that generates them" + ) + object.__setattr__(self, "source", source) + object.__setattr__(self, "arguments", tuple(arguments)) + object.__setattr__(self, "keywords", dict(keywords)) + object.__setattr__(self, "seed", seed) + object.__setattr__(self, "_memory", {}) + + def _seed_of(self, design: Design | None) -> Any: + """ + Gets the seed of the targets of a (realized) design: a value of the + design, the fixed seed, or `None` (without a seed). + """ + if self.seed is None: + return None + if design is None and not isinstance(self.seed, numbers.Integral): + raise ValueError( + "targets generated from a seed of the design need a design" + ) + return _number(design, self.seed) + + def _of(self, design: Design | None = None) -> pd.DataFrame: + """ + Gets the targets of a (realized) design, of its replicate (or `None` + for fixed targets, see `ObservationStudy.targets_of`). + """ + if isinstance(self.source, pd.DataFrame): + return self.source + return self._of_seed(self._seed_of(design)) + + def _of_seed(self, seed: Any) -> pd.DataFrame: + """Gets the targets of a seed (generated, or kept in memory).""" + if isinstance(self.source, pd.DataFrame): + return self.source + memory = self._memory + if seed not in memory: + if len(memory) >= _MAX_TARGETS: + memory.pop(next(iter(memory))) + keywords = ( + self.keywords if self.seed is None else {**self.keywords, "seed": seed} + ) + memory[seed] = self.source(*self.arguments, **keywords) + return memory[seed] + + +def _observe( + analysis: Callable, + targets: Targets, + seed: Any, + start: datetime, + end: datetime, + satellite: Satellite, +) -> pd.DataFrame: + """ + The observations of the targets of a seed by a satellite (see + `Observations`), generating them only if needed (and keeping them). + """ + # pylint: disable=too-many-arguments,too-many-positional-arguments + # pylint: disable-next=protected-access + return analysis(targets._of_seed(seed), satellite, start, end) + + +@dataclasses.dataclass(frozen=True, eq=False) +class Observations(Forgetful): + """ + The observations of targets by satellites over a period, by an analysis + of one satellite (such as `tatc.analysis.collect_observations`, called + as `analysis(targets, satellite, start, end)`), cached for each satellite + (see `SatelliteCache`) and each set of targets (of a seed, see + `Targets`), in memory, or on disk in a `directory` (shared by the + parallel workers of a study, and between sessions). The results on disk + are keyed by the fingerprint of the analysis, which describes fixed + targets by their content and generated targets by their recipe (see + `Targets`: their function, its arguments, and the seed's reference), + and in a namespace of the seed and the period, so that opening a cache + generates no targets: the `namespace` need only identify data that the + analysis (or the function of the targets) reads, such as from files, and + the code of other modules it calls (other than TAT-C's). + + The period is one window that represents the mission (see + `evaluate_phases`): its start may be a value of the design (see + `value_of`), such as an uncertain epoch drawn for each replicate over the + mission (`Uncertain`), so that the replicates average over the geometry + of the mission (such as the drift of the relative nodes of shells of + different inclinations or altitudes) and its seasons. With common random + numbers, the designs of a replicate share its epoch. The observations of + each epoch (and set of targets) are cached apart. + + Args: + targets (Targets | pandas.DataFrame): The targets. + start (datetime | Reference): The start of the period, or a value of + the design that gives it (see `value_of`). + duration (timedelta): The duration of the period. + analysis (Callable): The analysis of one satellite. + directory (str | os.PathLike | None): A directory of the cache on + disk, or `None` to cache in memory only. + namespace (str): An identifier of what the fingerprint of the + analysis cannot see. + + Results of the analysis with other code (such as of an earlier version of + TAT-C) are not reused, and a study warns of them (once, see + `SatelliteCache`); `prune` removes them. + """ + + targets: Targets | pd.DataFrame + start: datetime | Reference + duration: timedelta + analysis: Callable = collect_observations + _: dataclasses.KW_ONLY + directory: str | os.PathLike | None = dataclasses.field( + default=None, metadata={"fingerprint": False} + ) + namespace: str = "" + _forgotten = ("_caches",) # (copies sent to parallel workers) + + def __post_init__(self): + if isinstance(self.targets, pd.DataFrame): + object.__setattr__(self, "targets", Targets(self.targets)) + object.__setattr__(self, "_caches", {}) + + def start_of(self, design: Design | None = None) -> datetime: + """ + Gets the start of the period of a design (of its replicate). + + Args: + design (Design | None): The (realized) design, or `None` for a + fixed start. + + Returns: + datetime: the start + """ + if isinstance(self.start, datetime): + return self.start + if design is None: + raise ValueError("a start that is a value of the design needs a design") + start = value_of(design, self.start) + if not isinstance(start, datetime): + raise TypeError(f"the start of the period is not a datetime: {start!r}") + return start + + def end_of(self, design: Design | None = None) -> datetime: + """ + Gets the end of the period of a design (of its replicate). + + Args: + design (Design | None): The (realized) design, or `None` for a + fixed start. + + Returns: + datetime: the end + """ + return self.start_of(design) + self.duration + + def _context_of(self, design: Design | None = None) -> tuple: + """ + Gets a key of the observations of a (realized) design: the seed of + its targets and the period (such as the context of a `PhaseCache`). + """ + # pylint: disable-next=protected-access + return (self.targets._seed_of(design), self.start_of(design), self.duration) + + def _cache_of(self, design: Design | None = None) -> SatelliteCache: + """ + Gets the cache of the observations of the targets of a (realized) + design (by the seed of its targets and its period), in a namespace + of the targets' seed and the period (and the `namespace`), so that + the cache warns of results of the analysis with other code (see + `SatelliteCache`) of the same targets and period. + """ + # pylint: disable-next=protected-access + return self._cache(self.targets._seed_of(design), self.start_of(design)) + + def _namespace(self, seed: Any, start: datetime) -> str: + """Gets the namespace of the cache of the targets of a seed and a start.""" + context = ( + f"targets of seed {seed}, from {start.isoformat()} for {self.duration}" + ) + return f"{self.namespace}: {context}" if self.namespace else context + + def _cache(self, seed: Any, start: datetime) -> SatelliteCache: + """ + Gets the cache of the observations of the targets of a seed from a + start (see `_cache_of`), with the seed and start as the context of its + namespace (see `SatelliteCache._contexts`), from which `prune` finds + it. Its function generates the targets only if it computes a result. + """ + if (seed, start) not in self._caches: + if len(self._caches) >= _MAX_TARGETS: + self._caches.pop(next(iter(self._caches))) + function = partial( + _observe, + self.analysis, + self.targets, + seed, + start, + start + self.duration, + ) + self._caches[seed, start] = SatelliteCache( + function, + directory=self.directory, + namespace=self._namespace(seed, start), + context=(seed, start), + ) + return self._caches[seed, start] + + def prune(self) -> int: + """ + Removes the results on disk of the analysis with other code (see + `SatelliteCache.prune`) from the caches of every set of targets (of + each seed and start) of these observations in the directory, such as + after a study warns of them. The results of other observations that + share the directory (such as of other targets) are kept. + + Returns: + int: the number of results removed (0 without a directory) + """ + if self.directory is None: + return 0 + removed = 0 + contexts = SatelliteCache._contexts # pylint: disable=protected-access + for namespace, context in contexts(self.directory).items(): + if not isinstance(context, (tuple, list)) or len(context) != 2: + continue # of other caches + seed, start = context + if not isinstance(start, datetime): + continue + if namespace != self._namespace(seed, start): + continue # of other observations + with warnings.catch_warnings(): + warnings.simplefilter("ignore") + removed += self._cache(seed, start).prune() + return removed + + def __call__( + self, satellites: Sequence[Satellite], design: Design | None = None + ) -> pd.DataFrame: + """ + Gets the observations of the targets of a design by satellites. + + Args: + satellites (Sequence[Satellite]): The satellites. + design (Design | None): The (realized) design. + + Returns: + pandas.DataFrame: the observations (empty without satellites) + """ + return self._cache_of(design)(satellites) + + +def _hashable(value: Any) -> Any: + """A value, or its representation if it is not hashable.""" + try: + hash(value) + except TypeError: + return repr(value) + return value + + +def _uncertain_values(design: Design) -> tuple: + """ + Gets the values of the uncertain parameters of a realized design, by + path (see `DesignSpace.uncertain_paths`), as a key. + """ + return tuple( + (path, _hashable(value)) for path, value in design.uncertain_values().items() + ) + + +@dataclasses.dataclass(frozen=True, eq=False) +class _Evaluation: + """ + The evaluation of the satellites of a design (see `ObservationStudy`): + the metrics of the observations of every satellite and, with a plan, of + the mission (see `Mission`): its deployment and costs, and the phases of + its deployment or the histories of its failures (with the requirements + on their phases). + """ + + observations: Observations + metrics: Callable[[pd.DataFrame], Mapping[str, Any]] + layout: Reference | None = None + plan: MissionPlan | None = None + failures: Failures | None = None + phases: tuple[Requirement, ...] | None = None + _phase_cache: PhaseCache = dataclasses.field( + init=False, repr=False, metadata={"fingerprint": False} + ) + + def __post_init__(self): + object.__setattr__(self, "_phase_cache", PhaseCache(self.metrics)) + + def __call__(self, satellites: Sequence[Satellite], design: Design) -> dict: + observations = self.observations(satellites, design) + record: dict[str, Any] = {"satellites": len(satellites)} + layout = value_of(design, self.layout) + if layout is not None: + record["planes"] = count_planes(layout) + if self.plan is None: + record.update(_given_design(self.metrics, design)(observations)) + return record + mission = self.mission_from(satellites, observations, design) + if "satellite" in observations.columns: + # those of every satellite by the capability, whose cache the + # phases of the mission (such as its last) share + capability = mission.capability + record.update(capability(capability.names)) + else: + record.update(_given_design(self.metrics, design)(observations)) + # pylint: disable-next=protected-access + record.update(mission._record()) + return record + + def context_of(self, design: Design) -> tuple: + """ + Gets the context of the metrics of the phases of a design in the + cache (see `PhaseCache`): its observations (the seed of its targets + and its period) and, if the metrics are given the design, + its scenario and the values of its uncertain parameters, which such + metrics may read (designs of a replicate share them, with common + random numbers). + """ + # pylint: disable-next=protected-access + context = self.observations._context_of(design) + if _takes_design(self.metrics): + context = (context, design.scenario, _uncertain_values(design)) + return context + + def mission_from( + self, + satellites: Sequence[Satellite], + observations: pd.DataFrame, + design: Design, + ) -> Mission: + """ + Plans the mission of a realized design from its satellites and their + observations (see `MissionPlan.plan_mission`), with the capability of + its satellites (and the cache of the metrics of their phases). + """ + capability = Capability( + satellites, + observations, + self._phase_cache, + context=self.context_of(design), + design=design, + ) + return self.plan.plan_mission( + design, + value_of(design, self.layout), + capability, + failures=self.failures, + requirements=self.phases, + ) + + +class ObservationStudy(Study): + """ + A trade study of the observations of constellations: each replicate of a + design builds its satellites, observes the targets of the replicate (see + `Observations`), and records the metrics of the observations and, with a + mission `plan`, of its mission (see `Mission`): its deployment and costs, + the `phases` of its deployment, and the histories of its `failures`:: + + study = ObservationStudy( + space, + build, # the satellites of a design + Observations(Targets(generate_points_fibonacci_lattice, count=100, rotate=True, seed="seed"), START, DAY), + sample, # the metrics of observations + plan=MissionPlan(SCHEDULE, COST_MODEL), + phases=True, + ) + + Its results have the columns of every study (see `Study.run`), the + numbers of `satellites` and `planes`, the metrics of every satellite, + and those of the mission (see `Mission`): `deployed`, `stages deployed`, + and costs (see `CostEstimate.metrics`), the summary of its phases (see + `summarize_phases`), and that of the histories of its failures (see + `summarize_histories`), whose means replace the costs without failures. + + The metrics are a function of the observations of any set of satellites + (which may be empty), evaluated for those of each phase over the one + window of the observations (see `evaluate_phases`). One that takes the + realized `design` must depend on it only through the scenario and the + uncertain values of the replicate, by which phases are cached. The parts + of an evaluation are also given apart (`satellites_of`, `targets_of`, + `observations_of`, and `mission_of`). + + Args: + space (DesignSpace): The design space. + build (Callable): A function of a realized design that builds its + satellites (such as with `build_constellation`). + observations (Observations): The observations of the targets. + metrics (Callable): A function of observations (and of the realized + design, if it has a parameter named `design`) that gives their + metrics (a mapping). + layout (Reference | None): The value of the design that is its + layout (see `layout_of`), which a `plan` requires, or `None` for + the value `layout` of a design space that has one. + plan (MissionPlan | None): The deployment, policy, and costs, if any. + failures (Failures | None): The failures, if any, which require a + plan. + phases (Sequence[Requirement] | bool | None): `True` (or requirements + on the metrics, at most one of each) to summarize the phases of + the mission, which require a plan: of the deployment, or of each + history of the failures (whose phases are always summarized). + **options (Any): The settings of the study (see `Study`), such as + `replicates`, `seed`, `n_jobs`, and `store`. + + Raises: + TypeError: if the requirements on phases are not Requirements. + ValueError: if failures or phases are given without a plan, a plan + without a layout, several requirements on phases of a metric, or + statistics of failures of costs without a cost model. + """ + + def __init__( + self, + space: DesignSpace, + build: Callable[[Design], Sequence[Satellite]], + observations: Observations, + metrics: Callable[[pd.DataFrame], Mapping[str, Any]], + *, + layout: Reference | None = None, + plan: MissionPlan | None = None, + failures: Failures | None = None, + phases: Sequence[Requirement] | bool | None = None, + **options: Any, + ): + # the requirements on the phases, if they are summarized + phases = None if phases is None or phases is False else phases + phases = () if phases is True else None if phases is None else tuple(phases) + if phases is not None and not all(isinstance(r, Requirement) for r in phases): + raise TypeError("the requirements on phases are Requirements") + named = [requirement.name for requirement in phases or ()] + repeated = sorted({name for name in named if named.count(name) > 1}) + if repeated: + raise ValueError( + f"several requirements on the phases of metrics {repeated}: give " + + "one requirement per metric, whose time until the phases meet it " + + "is the column ` time`" + ) + if layout is None and "layout" in space.children: + layout = "layout" + if plan is None and (failures is not None or phases is not None): + raise ValueError("failures and phases require a mission plan") + if plan is not None and layout is None: + raise ValueError("a mission plan requires a layout") + if failures is not None and plan.cost_model is None: + named = [statistic.column for statistic in failures.statistics] + costs = [ + name for name in named if name == "cost" or name.startswith("cost ") + ] + if costs: + raise ValueError( + f"statistics of failures of costs without a cost model: {costs}" + ) + self.observations, self.metrics, self.layout = observations, metrics, layout + self.plan, self.failures, self.phases = plan, failures, phases + evaluation = _Evaluation(observations, metrics, layout, plan, failures, phases) + super().__init__(space, build, evaluation, **options) + + def _arguments(self) -> dict[str, Any]: + return { + "space": self.space, + "build": self.build, + "observations": self.observations, + "metrics": self.metrics, + "layout": self.layout, + "plan": self.plan, + "failures": self.failures, + "phases": self.phases, + **self._settings(), + } + + def _prepare( + self, + design: Design, + replicate: int, + shift: Mapping[str, int] | None, + case: _Case, + ) -> None: + # the cache of the observations of the first evaluation, in this + # process, so that it warns of results of other code here (once, see + # `SatelliteCache`), rather than in a worker process + realized = self._realized(design, replicate, shift, case) + self.observations._cache_of(realized) # pylint: disable=protected-access + + def satellites_of( + self, design: Design, replicate: int = 0, scenario: str | None = None + ) -> list[Satellite]: + """ + Gets the satellites of a replicate of a design (see `Study.realize`). + + Args: + design (Design): The design. + replicate (int): The replicate. + scenario (str | None): A scenario of the study (by name), if any. + + Returns: + list[Satellite]: the satellites + """ + return list(self.build(self.realize(design, replicate, scenario))) + + def targets_of( + self, design: Design, replicate: int = 0, scenario: str | None = None + ) -> pd.DataFrame: + """ + Gets the targets of a replicate of a design (see `Study.realize`). + + Args: + design (Design): The design. + replicate (int): The replicate. + scenario (str | None): A scenario of the study (by name), if any. + + Returns: + pandas.DataFrame: the targets + """ + realized = self.realize(design, replicate, scenario) + # pylint: disable-next=protected-access + return self.observations.targets._of(realized) + + def observations_of( + self, design: Design, replicate: int = 0, scenario: str | None = None + ) -> pd.DataFrame: + """ + Gets the observations of a replicate of a design (see `Study.realize`), + such as for analyses other than its metrics. + + Args: + design (Design): The design. + replicate (int): The replicate. + scenario (str | None): A scenario of the study (by name), if any. + + Returns: + pandas.DataFrame: the observations + """ + realized = self.realize(design, replicate, scenario) + return self.observations(self.build(realized), realized) + + def mission_of( + self, design: Design, replicate: int = 0, scenario: str | None = None + ) -> Mission: + """ + Gets the mission of a replicate of a design, as its evaluation plans + it (see `MissionPlan.plan_mission`), for analyses other than its + metrics: its planned deployment (`Mission.deployment`, with the + plan's schedule, type, policy and spares, masses, and stages, and the + capability of its satellites, which the rules of stages read, whose + history without failures `Deployment.planned` gives), the + metrics of its phases (`Mission.phases`, which a study with `phases` + summarizes), its cost estimate (`Mission.estimate`, the costs of a + study without failures), and the histories of its failures + (`Mission.histories`, a row per history, with the times until they + meet the study's requirements on phases, which a study with failures + summarizes). The design is realized, built, and observed once for + all of them. + + Args: + design (Design): The design. + replicate (int): The replicate. + scenario (str | None): A scenario of the study (by name), if any. + + Returns: + Mission: the mission + + Raises: + ValueError: if the study has no mission plan. + """ + if self.plan is None: + raise ValueError("the study has no mission plan") + realized = self.realize(design, replicate, scenario) + satellites = list(self.build(realized)) + observations = self.observations(satellites, realized) + return self.evaluate.mission_from(satellites, observations, realized) + + def prune(self) -> int: + """ + Removes the evaluations of the study's store by this study with other + code (see `Study.prune`), and the results of its observations' caches + with other code (see `Observations.prune`, which returns their number + when called alone). + + Returns: + int: the number of evaluations removed (as `Study.prune`, not + counting the results of the observations' caches) + """ + evaluations = super().prune() + self.observations.prune() + return evaluations diff --git a/src/tatc/tradespace/optimization.py b/src/tatc/tradespace/optimization.py new file mode 100644 index 0000000..15c79de --- /dev/null +++ b/src/tatc/tradespace/optimization.py @@ -0,0 +1,674 @@ +""" +Searches of design spaces for Pareto-efficient designs with optimizers: +Optuna (which searches the hierarchical design space directly, suggesting +each decision in turn) and pymoo (which searches the unit hypercube that +encodes it, a dimension per decision). Both are optional dependencies. + +Designs are judged by criteria (see `Criteria`, without `by`): their +objectives are statistics over their replicates of the metrics of their +evaluations (see `Study.run`, which must give one record per evaluation): +their means, or other statistics, such as a quantile or the probability of +meeting a threshold. Requirements on statistics (see `Requirement`) are +output constraints, whose violations the optimizers minimize along with +those of the constraints of the design space. The tolerances of the +criteria do not apply to the optimizers' own ranking of designs, but they +do to the front of the designs they evaluate (see `Search`). + +A search of a study with several scenarios (see `Study`) evaluates each +design in every scenario, and judges it by criteria `across` the scenarios +(see `Across`): by its worst or its mean over them, such as for designs +robust to scenarios that cannot be told apart in advance. +Each design is evaluated once, however often an optimizer proposes it, and +designs proposed together are evaluated together, in parallel if the study +is (see `Study`). + +Designs are judged by their feasible replicates, as summaries judge them +(see `summarize`): a design infeasible in some replicates is judged by the +others (a requirement on `feasible`, the share of its replicates that are +feasible, such as `Requirement("feasible", ">=", 1)`, rejects it), and a +design without a feasible replicate is infeasible, which the optimizers' +constraint of feasibility rejects. + +A search chooses its front from one evaluation of each design (with the +study's replicates), which favors the designs whose replicates were lucky: +refine the designs it evaluated (see `refine`) and confirm its front (see +`confirm`, of the designs of the search, see `Search`), as for any study. + +@author: Paul T. Grogan +""" + +from __future__ import annotations + +import copy +from collections.abc import Mapping, Sequence +from dataclasses import dataclass, field +from typing import Any + +import numpy as np +import pandas as pd + +from .criteria import Criteria, Requirement, _as_criteria, _signs +from .space import Design, Infeasible +from .study import Study +from .summary import _summarize +from .tables import FEASIBLE, check_records, efficient_keys + + +@dataclass +class Search: + """ + The outcome of a search with an optimizer (see `optimize_optuna` and + `optimize_pymoo`): as the outcomes of other steps of a trade study (see + `Refinement`), its `results`, the `summary` of its designs, the `designs` + it selects for the next step (the efficient designs it found), and its + `criteria`, which refine and confirm its front as for any study:: + + search = optimize_optuna(study, criteria, n_trials=200) + refinement = refine(study, criteria, search.results) + confirmation = confirm(study, criteria, refinement.results) + """ + + results: pd.DataFrame + """pandas.DataFrame: The results of every evaluation (see `Study.run`).""" + summary: pd.DataFrame + """pandas.DataFrame: A row per design that the search found feasible + (with a feasible replicate, in every scenario with criteria `across` + scenarios, as designs are judged by their feasible replicates, see + `summarize`): the summary of the criteria over its replicates (with the + spreads of means, as `summarize` gives them), with whether it is + efficient among these designs (`pareto`, with the tolerances of the + criteria).""" + designs: list[Design] + """list[Design]: The efficient designs that the search found (`pareto` of + `summary`), for the next step.""" + criteria: Criteria + """Criteria: The criteria of the search.""" + evaluated: list[Design] = field(default_factory=list) + """list[Design]: The designs evaluated, in the order of their evaluation.""" + state: Any = None + """Any: The optimizer's own outcome: the Optuna study (`optuna.Study`) or + the result of pymoo (`pymoo.core.result.Result`).""" + + +class Evaluations: + """ + The evaluations of designs for a search: the objectives of each design + (by its key), the violations of its requirements, and the records of the + study's evaluations. Designs are judged by their feasible replicates (see + `summarize`), and a design without a feasible replicate is infeasible. + + Args: + study (Study): The study that evaluates designs. + criteria (Criteria | Mapping[str, str]): The criteria, without `by` + (see `Criteria`), or the objectives (metrics whose means they + are) and their directions (`"min"` or `"max"`). + """ + + def __init__(self, study: Study, criteria: Criteria | Mapping[str, str]): + self.study, self.criteria = study, _as_criteria(criteria) + if self.criteria.by: + raise ValueError( + "searches need one record per evaluation: give criteria without `by`" + ) + self.values: dict[str, tuple[float, ...] | None] = {} + """dict: The objectives of each evaluated design (by key), or `None` + if it is infeasible.""" + self.violations: dict[str, tuple[float, ...] | None] = {} + """dict: The violation of each requirement by each evaluated design + (by key), or `None` if it is infeasible.""" + self.infeasibility: dict[str, float] = {} + """dict: The violation of the feasibility of each evaluated design (by + key), for constraint-aware optimizers: 0 for a design that has + feasible replicates (by which it is judged), and otherwise the share + of its evaluations that are infeasible (1 for a design infeasible in + every replicate, and less, with criteria `across` scenarios, for one + without a feasible replicate in some of them).""" + self.designs: dict[str, Design] = {} + """dict: The evaluated designs (by key), in the order of their + evaluation.""" + self._records: list[pd.DataFrame] = [] + self._checked = False + + @property + def results(self) -> pd.DataFrame: + """pandas.DataFrame: The results of every evaluation (see + `Study.run`).""" + if not self._records: + return pd.DataFrame() + return pd.concat(self._records, ignore_index=True) + + def evaluate(self, designs: list[Design]) -> list[tuple[float, ...] | None]: + """ + Gets the objectives of designs, evaluating those not yet evaluated + together (see also `violations`). A design is infeasible if none of + its replicates is feasible (see `infeasibility`). The first design + evaluated is evaluated alone, to check that the study's evaluations + give one record each before evaluating others. + + Args: + designs (list[Design]): The designs. + + Returns: + list[tuple[float, ...] | None]: the objectives of each design, in + the order of the objectives, or `None` if it is infeasible + """ + new = list({d.key: d for d in designs if d.key not in self.values}.values()) + if new and not self._checked: + self._run(new[:1]) + new = new[1:] + if new: + self._run(new) + return [self.values[d.key] for d in designs] + + def _run(self, designs: list[Design]) -> None: + """ + Evaluates designs, recording their objectives and violations (of + their summary, see `summarize`). + """ + self.designs.update((design.key, design) for design in designs) + records = self.study.run(designs) + self._records.append(records) + across = self.criteria.across + keys = ["design", "replicate", *([] if across is None else [across.column])] + if across is None and "scenario" in records.columns: + hint = ( + "a study with several scenarios gives a record in each: give " + + "criteria `across` the scenarios (see Across), or search a study " + + "with one scenario" + ) + else: + hint = ( + "searches need one record per evaluation: make the study's evaluate " + + "function return a mapping of metrics" + ) + check_records(records, keys, hint, self.criteria.metrics) + self._checked = self._checked or bool(records[FEASIBLE].any()) + summary = _summarize(records, self.criteria, design_values=False) + summary = summary.set_index("design") + shares = records.groupby("design")[FEASIBLE].mean() + for design in designs: + key = design.key + if key not in summary.index: + self.values[key] = self.violations[key] = None + self.infeasibility[key] = 1.0 - float(shares[key]) + continue + row = summary.loc[key] + self.values[key] = tuple( + float(row[name]) for name in self.criteria.objectives + ) + self.violations[key] = tuple( + float(requirement.violation(row[requirement.name])) + for requirement in self.criteria.requirements + ) + self.infeasibility[key] = 0.0 + + def search(self, state: Any) -> Search: + """ + Gets the outcome of a search of these evaluations. + + Args: + state (Any): The optimizer's own outcome. + + Returns: + Search: the search + """ + results = self.results + summary = _summarize(results, self.criteria, spread=True) + return Search( + results=results, + criteria=self.criteria, + summary=summary, + designs=[self.designs[key] for key in efficient_keys(summary)], + evaluated=list(self.designs.values()), + state=state, + ) + + def worst(self) -> list[float]: + """ + Gets the worst value of each objective of the feasible designs + evaluated (0 if none is), as for infeasible designs. + + Returns: + list[float]: the worst values, in the order of the objectives + """ + feasible = [ + values + for values in self.values.values() + if values is not None and not np.isnan(values).any() + ] + if not feasible: + return [0.0] * len(self.criteria.objectives) + table = np.array(feasible) + return [ + float(table[:, i].max() if direction == "min" else table[:, i].min()) + for i, direction in enumerate(self.criteria.objectives.values()) + ] + + +def optimize_optuna( + study: Study, + criteria: Criteria | Mapping[str, str], + *, + n_trials: int = 100, + seed: int | None = 0, + sampler: Any = None, + optuna_study: Any = None, + batch_size: int | None = None, + constraints: bool = True, + max_designs: int | None = None, +) -> Search: + """ + Searches a study's design space with Optuna: each trial suggests a design + (each of its decisions in turn) and is told the objectives of the criteria: + statistics (such as means) of its metrics over its replicates. + + With `constraints`, each trial records the violation of the constraints + of its design (`trial.set_constraint`, under the name `"feasibility"`): + 0 for a design with feasible replicates (by which it is judged, see + `summarize`), the amount by which it violates a constraint of the design + space (see `DesignSpace`), or, for a design without a feasible replicate, + the share of its evaluations that the study finds infeasible (see + `Evaluations.infeasibility`). Optuna's constraint-aware samplers (such + as TPE and NSGA-II) then prefer feasible designs, and infeasible designs + that violate their constraints less. An infeasible trial is told the + worst objectives of the feasible designs evaluated before it, which + these samplers do not use to rank it. Without `constraints` (or with a + version of Optuna before 5, which lacks `set_constraint`), an infeasible + design prunes its trial. + + Each requirement of the criteria is a constraint of the trials (named by + its statement, `str(requirement)`, such as `"sufficient p10 >= 80"`, or, + if requirements state themselves alike, by their values in full and + their order), whose value is its violation (see `Requirement.violation`), + and which requires `constraints`. A requirement on `feasible` (the share + of a design's replicates that are feasible) constrains the designs that + are infeasible in some of their replicates. + + Trials are asked in batches, whose designs are evaluated together (in + parallel, if the study is) before they are told. A batch defaults to one + trial per worker of the study. The default sampler is TPE, which, in + batches, tells its pending trials the worst values evaluated so far + (`constant_liar`), so that a batch spreads its trials rather than + suggesting nearly the same design several times. + + Samplers suggest designs evaluated before, especially in small design + spaces: such trials are told the objectives of the design without + evaluating it again. The trials (`n_trials`) are then a poor measure of + the cost of a search; `max_designs` limits the designs evaluated + instead (the search stops once it has evaluated as many, or after + `n_trials`). + + Args: + study (Study): The study that evaluates designs. + criteria (Criteria | Mapping[str, str]): The criteria, without `by` + (see `Criteria`), or the objectives (metrics whose means they + are) and their directions (`"min"` or `"max"`). + n_trials (int): The number of trials. + seed (int | None): The seed of the default sampler (`None` for one + drawn anew); a sampler given is seeded by its own arguments. + sampler (optuna.samplers.BaseSampler | None): The sampler, or `None` + for TPE (with a constant liar in batches); ignored with an + `optuna_study`. + optuna_study (optuna.Study | None): A study to continue, whose + directions are those of the objectives. + batch_size (int | None): The number of trials evaluated together. + constraints (bool): `True` to record the violations of constraints, + `False` to prune infeasible trials. + max_designs (int | None): The most designs to evaluate, if limited. + + Returns: + Search: the results and designs of the search, and the Optuna study + + Raises: + ValueError: if the criteria have requirements without `constraints` + (or with a version of Optuna before 5), or if `max_designs` is + less than 1. + """ + # pylint: disable=import-outside-toplevel + try: + import optuna + except ImportError as error: + raise ImportError( + "optimize_optuna requires optuna (pip install optuna)" + ) from error + if max_designs is not None and max_designs < 1: + raise ValueError("max_designs must be at least 1") + evaluations = Evaluations(study, criteria) + requirements = evaluations.criteria.requirements + directions = [ + "minimize" if direction == "min" else "maximize" + for direction in evaluations.criteria.objectives.values() + ] + batch_size = batch_size or study.workers + if optuna_study is None: + if sampler is None: + sampler = optuna.samplers.TPESampler( + constant_liar=batch_size > 1, seed=seed + ) + optuna_study = optuna.create_study(directions=directions, sampler=sampler) + constrained = constraints and hasattr(optuna.trial.Trial, "set_constraint") + if requirements and not constrained: + raise ValueError("requirements need constraints (and Optuna 5 or later)") + names = _constraint_names(requirements) + + def set_constraints(trial: Any, feasibility: float, violations) -> None: + trial.set_constraint("feasibility", feasibility) + for name, violation in zip(names, violations): + trial.set_constraint(name, violation) + + def infeasible(trial: Any, violation: float) -> None: + if constrained: + set_constraints(trial, max(violation, 1e-9), [0.0] * len(names)) + optuna_study.tell(trial, evaluations.worst()) + else: + optuna_study.tell(trial, state=optuna.trial.TrialState.PRUNED) + + remaining = n_trials + while remaining > 0: + size = min(batch_size, remaining) + if max_designs is not None: + size = min(size, max_designs - len(evaluations.values)) + if size <= 0: + break + trials, designs = [], [] + for _ in range(size): + trial = optuna_study.ask() + try: + design = study.space._suggest(trial) # pylint: disable=protected-access + except Infeasible as error: + trial.set_user_attr("error", str(error)) + infeasible(trial, error.violation) + continue + trial.set_user_attr("design", design.key) + trials.append(trial) + designs.append(design) + remaining -= size + for trial, design, values in zip( + trials, designs, evaluations.evaluate(designs) + ): + if values is None: + infeasible(trial, evaluations.infeasibility[design.key]) + else: + if constrained: + violations = evaluations.violations[design.key] + set_constraints(trial, 0.0, np.nan_to_num(violations, nan=1.0)) + optuna_study.tell( + trial, list(np.where(np.isnan(values), evaluations.worst(), values)) + ) + return evaluations.search(optuna_study) + + +def _constraint_names(requirements: Sequence[Requirement]) -> list[str]: + """ + Gets distinct names of the constraints of requirements (other than + `"feasibility"`): their statements (see `Requirement`), with their values + in full where statements are alike, and their order where these are too + (such as of requirements that differ only in their scales). + """ + names = [str(requirement) for requirement in requirements] + names = [ + (f"{r.name} {r.operator} {r.value!r}" if names.count(name) > 1 else name) + for r, name in zip(requirements, names) + ] + return [ + name if names[:i].count(name) == 0 else f"{name} ({names[:i].count(name) + 1})" + for i, name in enumerate(names) + ] + + +def make_pymoo_problem(study: Study, criteria: Criteria | Mapping[str, str]) -> Any: + """ + Makes a pymoo problem of a study's design space: its variables are the + unit hypercube that encodes the design space (a dimension per decision, + whose levels divide it equally), its objectives are minimized (maximized + objectives are negated), and its constraint (`G <= 0`) is violated by + designs that violate a constraint of the design space (by the amount of + the violation, see `DesignSpace`) or that have no feasible replicate (by + the share of their infeasible evaluations, see + `Evaluations.infeasibility`). Each requirement of the + criteria is a further constraint, whose value is its violation (see + `Requirement.violation`). + The designs of a population are evaluated together. + + The problem keeps its evaluations (`evaluations`, see `Evaluations`), + whose `results` are those of every evaluation (see `Study.run`), and an + elimination of duplicates by design (`duplicates`, a pymoo + `DuplicateElimination` for the `eliminate_duplicates` of an algorithm): + many points of the unit hypercube decode to the same design (those in the + same level of each variable, or that differ only in the variables of the + branches the design does not choose), which pymoo's elimination of equal + points does not see. A proposal is a duplicate if it decodes to the same + design (by key) as another proposal, a member of the population, or a + design evaluated before; proposals that violate a constraint of the + design space are not duplicates. + + Args: + study (Study): The study that evaluates designs. + criteria (Criteria | Mapping[str, str]): The criteria, without `by` + (see `Criteria`), or the objectives (metrics whose means they + are) and their directions (`"min"` or `"max"`). + + Returns: + pymoo.core.problem.Problem: the problem + """ + # pylint: disable=import-outside-toplevel + try: + from pymoo.core.duplicate import DuplicateElimination + from pymoo.core.problem import Problem + except ImportError as error: + raise ImportError( + "make_pymoo_problem requires pymoo (pip install pymoo)" + ) from error + + evaluations = Evaluations(study, criteria) + n_requirements = len(evaluations.criteria.requirements) + signs = _signs(evaluations.criteria) + space = study.space + decode = space._decode # pylint: disable=protected-access + n_var = len(space._unit_paths()) # pylint: disable=protected-access + + def key_of(individual: Any) -> str | None: + """The key of the design of a proposal, or `None` if it violates a + constraint of the design space.""" + try: + return decode(individual.X).key + except Infeasible: + return None + + class DesignDuplicates(DuplicateElimination): + """ + An elimination of the proposals of designs proposed or evaluated + before (see `make_pymoo_problem`). + """ + + def _do(self, pop: Any, other: Any, is_duplicate: np.ndarray) -> np.ndarray: + seen = set(evaluations.designs) + if other is not None: + seen.update(key for key in map(key_of, other) if key is not None) + for i, individual in enumerate(pop): + key = key_of(individual) + if key is None: + continue + if key in seen: + is_duplicate[i] = True + else: + seen.add(key) + return is_duplicate + + class DesignSpaceProblem(Problem): + """ + A pymoo problem of a design space (see `make_pymoo_problem`). + """ + + def __init__(self): + super().__init__( + n_var=n_var, + n_obj=len(signs), + n_ieq_constr=1 + n_requirements, + xl=0.0, + xu=1.0, + ) + self.evaluations = evaluations + self.duplicates = DesignDuplicates() + + def _evaluate(self, x, out, *args, **kwargs): + designs: list[Design | None] = [] + violation = np.ones(len(np.atleast_2d(x))) + for i, row in enumerate(np.atleast_2d(x)): + try: + designs.append(decode(row)) + except Infeasible as error: + designs.append(None) + violation[i] = max(error.violation, 1e-9) + feasible = [design for design in designs if design is not None] + values = iter(evaluations.evaluate(feasible)) + costs = np.zeros((len(designs), len(signs))) + unmet = np.zeros((len(designs), n_requirements)) + for i, design in enumerate(designs): + value = None if design is None else next(values) + if design is not None and value is None: + violation[i] = max(evaluations.infeasibility[design.key], 1e-9) + if value is not None: + value = np.where(np.isnan(value), evaluations.worst(), value) + costs[i] = signs * np.asarray(value) + violation[i] = 0.0 + unmet[i] = np.nan_to_num( + evaluations.violations[design.key], nan=1.0 + ) + out["F"] = costs + out["G"] = np.column_stack([violation, unmet]) + + return DesignSpaceProblem() + + +def _eliminate_duplicates(algorithm: Any, duplicates: Any) -> None: + """ + Makes a pymoo algorithm eliminate duplicates by design: pymoo's genetic + algorithms eliminate duplicates in their initialization and mating. + """ + parts = [ + algorithm, + getattr(algorithm, "initialization", None), + getattr(algorithm, "mating", None), + ] + if any(part is None or not hasattr(part, "eliminate_duplicates") for part in parts): + raise ValueError( + "distinct searches need an algorithm that eliminates duplicates in its " + + "initialization and mating (as pymoo's genetic algorithms do): " + + "pass distinct=False for others" + ) + for part in parts: + part.eliminate_duplicates = duplicates + + +def _designs_termination( + evaluations: Evaluations, max_designs: int, termination: Any +) -> Any: + """ + Gets a pymoo termination of a search once it has evaluated `max_designs` + designs, or by another termination (if any), whichever is first. + """ + # pylint: disable=import-outside-toplevel + from pymoo.core.termination import Termination + from pymoo.util.misc import termination_from_tuple + + class DesignsTermination(Termination): + """ + A termination by the number of designs evaluated (see + `optimize_pymoo`), or by another termination. + """ + + def __init__(self, other: Any): + super().__init__() + self.other = other + + def _update(self, algorithm: Any) -> float: + progress = len(evaluations.values) / max_designs + if self.other is not None: + progress = max(progress, self.other.update(algorithm)) + return progress + + return DesignsTermination( + None if termination is None else termination_from_tuple(termination) + ) + + +def optimize_pymoo( + study: Study, + criteria: Criteria | Mapping[str, str], + *, + algorithm: Any = None, + termination: Any = ("n_gen", 10), + seed: int | None = 0, + distinct: bool = True, + max_designs: int | None = None, + **kwargs: Any, +) -> Search: + """ + Searches a study's design space with a pymoo algorithm (see + `make_pymoo_problem`). The algorithm eliminates proposals of designs + proposed or evaluated before (its initialization and mating, see + `make_pymoo_problem`'s `duplicates`), unless `distinct` is `False`, so + that each generation proposes as many new designs as it can: as many + generations then evaluate more designs, and find more of the front. The + algorithm given is not changed: a distinct search changes a copy. + + The generations of a search (of the `termination`) are a poor measure of + its cost if they propose designs evaluated before (without `distinct`), + whose objectives are known without evaluating them again: `max_designs` + limits the designs evaluated instead, as of `optimize_optuna` (the search + stops after the generation in which it has evaluated as many, or by the + `termination`, whichever is first). As a generation evaluates its new + designs together, the last may evaluate more designs than are left. + + Args: + study (Study): The study that evaluates designs. + criteria (Criteria | Mapping[str, str]): The criteria, without `by` + (see `Criteria`), or the objectives (metrics whose means they + are) and their directions (`"min"` or `"max"`). + algorithm (pymoo.core.algorithm.Algorithm | None): The algorithm, or + `None` for NSGA-II with populations of 20. + termination (Any): The termination criterion of `pymoo.optimize.minimize`. + seed (int | None): The seed of the algorithm (`None` for one drawn + anew, as pymoo does). + distinct (bool): `True` to eliminate the proposals of designs proposed + or evaluated before, `False` for the algorithm's own elimination + of duplicates (of equal points). + max_designs (int | None): The most designs to evaluate (but those of + the last generation), if limited. + **kwargs (Any): Other arguments of `pymoo.optimize.minimize`. + + Returns: + Search: the results and designs of the search, and the result of pymoo + + Raises: + ValueError: if the search is distinct but the algorithm does not + eliminate duplicates as pymoo's genetic algorithms do, or if + `max_designs` is less than 1. + """ + # pylint: disable=import-outside-toplevel + try: + from pymoo.optimize import minimize + except ImportError as error: + raise ImportError( + "optimize_pymoo requires pymoo (pip install pymoo)" + ) from error + + if max_designs is not None and max_designs < 1: + raise ValueError("max_designs must be at least 1") + if algorithm is None: + from pymoo.algorithms.moo.nsga2 import NSGA2 + + algorithm = NSGA2(pop_size=20) + problem = make_pymoo_problem(study, criteria) + if distinct: + # a copy, so that the caller's algorithm keeps its own elimination + algorithm = copy.deepcopy(algorithm) + _eliminate_duplicates(algorithm, problem.duplicates) + if max_designs is not None: + termination = _designs_termination( + problem.evaluations, max_designs, termination + ) + result = minimize(problem, algorithm, termination, seed=seed, **kwargs) + evaluations = problem.evaluations + return evaluations.search(result) diff --git a/src/tatc/tradespace/pareto.py b/src/tatc/tradespace/pareto.py new file mode 100644 index 0000000..bf5250d --- /dev/null +++ b/src/tatc/tradespace/pareto.py @@ -0,0 +1,292 @@ +""" +Pareto efficiency of designs with several objectives: non-dominated +designs, Pareto ranks, and the hypervolume of a set of designs (and of the +designs of a search as it proceeds). + +Designs are judged by criteria (see `Criteria`): objectives (columns of a +data frame, such as the statistics of a summary of a study, see `summarize`) +to minimize or maximize, requirements that efficient designs meet, the +tolerances of the objectives, and the groups in which designs are judged +separately. A mapping of objectives to their directions (`"min"` or +`"max"`) is the criteria of these objectives alone. A design with a missing +objective (`NaN`, such as a statistic of a metric that none of its feasible +replicates gives) is not efficient, and dominates no other. The probability +that a design is efficient, given the uncertainty of its replicates, is that +of `pareto_probability` (of the summaries of studies, see `summarize`). + +@author: Paul T. Grogan +""" + +from __future__ import annotations + +from collections.abc import Mapping, Sequence + +import numpy as np +import pandas as pd + +from .criteria import ( + Criteria, + _as_criteria, + _costs, + _signs, + _tolerances, + _violation, +) +from .dominance import dominated, efficient +from .summary import _summarize +from .tables import check_summary, groups + + +def _get_costs(frame: pd.DataFrame, criteria: Criteria) -> np.ndarray: + """ + Gets the objectives of criteria of a data frame (of their columns) as + costs (to minimize, see `Criteria._costs`). + """ + missing = [column for column in criteria.objectives if column not in frame] + if missing: + raise ValueError(f"no columns of the objectives {missing}") + return _costs(criteria, frame) + + +def _get_violation(frame: pd.DataFrame, criteria: Criteria) -> np.ndarray: + """ + Gets the total violation of the requirements of criteria by the rows of a + data frame, from the columns of their statistics (infinite where a + statistic is missing). + """ + missing = [r.name for r in criteria.requirements if r.name not in frame.columns] + if missing: + raise ValueError( + f"no columns of the statistics {missing} of requirements: summarize " + + "the results with the criteria (see summarize)" + ) + violation = _violation(criteria, frame, len(frame)) + return np.where(np.isnan(violation), np.inf, violation) + + +def pareto_front( + summary: pd.DataFrame, criteria: Criteria | Mapping[str, str] +) -> pd.Series: + """ + Finds the Pareto-efficient (non-dominated) rows of a summary of designs + (a row per design, such as of `summarize`, not the results of a study, + which have a row per replicate): those that meet + the requirements of the criteria (by the columns of their statistics) + and that no other row that meets them dominates, being no worse in every + objective and better in at least one, in each group of the criteria's + `by`. Rows with the same objectives are all efficient if any is, and a + row with a missing objective (`NaN`) is not. Summaries of criteria give + whether each design is efficient already (`pareto`, see `summarize`). + + With a tolerance of an objective (see `Criteria`), a row dominates + another only if it would still dominate it if it were worse by the + tolerance in that objective: a value in the objective's units, or a + share of the other row's value (a percentage, such as `"5%"`), which + suits objectives that range over orders of magnitude. Rows within the + tolerances of the front (that no other row is clearly better than) are + then efficient as well, which suits objectives estimated with an + uncertainty (such as a few standard errors of their means, see + `summarize`), or by a cheaper analysis (see `screen`). + + Args: + summary (pandas.DataFrame): The rows (such as designs). + criteria (Criteria | Mapping[str, str]): The criteria, or the + objectives (columns) and their directions (`"min"` or `"max"`). + + Returns: + pandas.Series: whether each row is efficient (boolean, with the + summary's index) + + Raises: + ValueError: if the summary has several rows of a design (in a group + of the criteria's `by`), as the results of a study do. + """ + criteria = _as_criteria(criteria) + check_summary(summary, criteria.by) + front = np.zeros(len(summary), dtype=bool) + for _, positions in groups(summary, criteria.by): + group = summary.iloc[positions] + meets = _get_violation(group, criteria) == 0 + costs = _get_costs(group, criteria) + front[positions] = efficient(costs, meets, _tolerances(criteria)) + return pd.Series(front, index=summary.index, name="pareto") + + +def pareto_ranks( + summary: pd.DataFrame, criteria: Criteria | Mapping[str, str] +) -> pd.Series: + """ + Ranks the rows of a summary of designs (a row per design, see + `pareto_front`) by non-dominated sorting, in each group + of the criteria's `by`: rank 0 is the Pareto front (see `pareto_front`), + rank 1 the front of the others, and so on, with the tolerances of the + criteria. Rows that miss the requirements of the criteria are ranked + after those that meet them, in order of their violation (the sum of the + violations of the requirements, see `Requirement`), and rows with a + missing objective (`NaN`) that meet them last. + + Args: + summary (pandas.DataFrame): The rows (such as designs). + criteria (Criteria | Mapping[str, str]): The criteria, or the + objectives (columns) and their directions (`"min"` or `"max"`). + + Returns: + pandas.Series: the rank of each row (with the summary's index) + + Raises: + ValueError: if the summary has several rows of a design (in a group + of the criteria's `by`), as the results of a study do. + """ + criteria = _as_criteria(criteria) + check_summary(summary, criteria.by) + tolerances = _tolerances(criteria) + ranks = np.full(len(summary), -1, dtype=int) + for _, positions in groups(summary, criteria.by): + group = summary.iloc[positions] + violation = _get_violation(group, criteria) + costs = _get_costs(group, criteria) + known = ~np.isnan(costs).any(axis=1) + meets = (violation == 0) & known + remaining, costs = positions[meets], costs[meets] + rank = 0 + while len(remaining) > 0: + front = ~dominated(costs, tolerances) + ranks[remaining[front]] = rank + remaining, costs = remaining[~front], costs[~front] + rank += 1 + missing = violation != 0 + if missing.any(): + order = pd.Series(violation[missing]).rank(method="dense").to_numpy() + ranks[positions[missing]] = rank + order.astype(int) - 1 + rank = int(ranks[positions[missing]].max()) + 1 + unknown = (violation == 0) & ~known + ranks[positions[unknown]] = rank + return pd.Series(ranks, index=summary.index, name="pareto_rank") + + +def _hypervolume(points: np.ndarray, reference: np.ndarray) -> float: + """ + Computes the hypervolume (to minimize) of points that are all better than + the reference in every dimension, by slicing the last dimension (exact, + for few dimensions). + """ + if len(points) == 0: + return 0.0 + if points.shape[1] == 1: + return float(reference[0] - points[:, 0].min()) + points = points[~dominated(points)] + order = np.argsort(points[:, -1], kind="stable") + points = points[order] + if points.shape[1] == 2: + # sweep: by increasing second cost, the first cost decreases + x = points[:, 0] + upper = np.append(points[1:, 1], reference[1]) + return float(np.sum((reference[0] - x) * (upper - points[:, 1]))) + volume = 0.0 + for i in range(len(points)): + upper = points[i + 1, -1] if i + 1 < len(points) else reference[-1] + height = upper - points[i, -1] + if height > 0: + volume += height * _hypervolume(points[: i + 1, :-1], reference[:-1]) + return float(volume) + + +def hypervolume( + summary: pd.DataFrame, + criteria: Criteria | Mapping[str, str], + reference: Mapping[str, float] | Sequence[float], +) -> float: + """ + Computes the hypervolume of the rows of a summary of designs (a row per + design, see `pareto_front`): the volume of the + objective space that they dominate, up to a reference point that is + worse than every row of interest in every objective. Rows that are not + better than the reference in every objective, that miss the requirements + of the criteria, or that have a missing objective add nothing (the + tolerances of the criteria do not apply). A larger hypervolume is a better set of designs, + which makes it a measure of the progress of a search, or of how close a + search comes to the true Pareto front. + + The hypervolume is exact. Its computation slices the objectives in turn, + which takes long with many objectives and many efficient rows. + + Args: + summary (pandas.DataFrame): The rows (such as designs), of one group + (criteria with `by` are not accepted). + criteria (Criteria | Mapping[str, str]): The criteria, or the + objectives (columns) and their directions (`"min"` or `"max"`). + reference (Mapping[str, float] | Sequence[float]): The reference + point: the value of each objective (by column, or in order). + + Returns: + float: the hypervolume, in the product of the units of the objectives + + Raises: + ValueError: if the summary has several rows of a design, as the + results of a study do (see `hypervolume_progress` for those of a + search). + """ + criteria = _as_criteria(criteria) + if criteria.by: + raise ValueError( + "a hypervolume is of the rows of one group: give criteria without `by`" + ) + check_summary(summary) + objectives = criteria.objectives + if isinstance(reference, Mapping): + reference = [reference[column] for column in objectives] + if len(reference) != len(objectives): + raise ValueError("the reference point needs a value for each objective") + bound = _signs(criteria) * np.asarray(reference, dtype=float) + if len(summary) == 0: + return 0.0 + summary = summary[_get_violation(summary, criteria) == 0] + costs = _get_costs(summary, criteria) + costs = costs[np.all(costs < bound, axis=1)] + return _hypervolume(costs, bound) + + +def hypervolume_progress( + results: pd.DataFrame, + criteria: Criteria | Mapping[str, str], + reference: Mapping[str, float] | Sequence[float], + *, + step: int = 10, +) -> pd.Series: + """ + Gets the hypervolume of the designs evaluated by a search (such as an + optimizer, see `optimize_optuna`) as it proceeds: of the first designs + evaluated (in the order of their first records in the results of the + search), judged by their statistics over their replicates (see + `summarize`), in steps of `step` designs (and of all of them). + + Args: + results (pandas.DataFrame): The results of the search (see + `Study.run`). + criteria (Criteria | Mapping[str, str]): The criteria, or the + objectives (columns) and their directions (`"min"` or `"max"`). + reference (Mapping[str, float] | Sequence[float]): The reference + point (see `hypervolume`). + step (int): The number of designs of each step. + + Returns: + pandas.Series: the hypervolume, by the number of designs evaluated + """ + if step < 1: + raise ValueError("step must be at least 1") + criteria = _as_criteria(criteria) + summary = _summarize(results, criteria, design_values=False) + summary = summary.set_index("design") + order = results["design"].drop_duplicates().tolist() + counts = list(range(step, len(order) + 1, step)) + if order and (not counts or counts[-1] != len(order)): + counts.append(len(order)) + return pd.Series( + [ + hypervolume(summary[summary.index.isin(order[:n])], criteria, reference) + for n in counts + ], + index=pd.Index(counts, name="designs"), + name="hypervolume", + dtype=float, + ) diff --git a/src/tatc/tradespace/plans.py b/src/tatc/tradespace/plans.py new file mode 100644 index 0000000..6c59a98 --- /dev/null +++ b/src/tatc/tradespace/plans.py @@ -0,0 +1,430 @@ +""" +The missions of the designs of an observation study (see `ObservationStudy`): +the plan of each design's mission (`MissionPlan`: its deployment, the policy +that restores the failures of its satellites, and its costs, from the +values of the design), and the failures of its satellites (`Failures`), +from which an evaluation plans the mission of a replicate of a design (see +`Mission`) and summarizes it into its record. + +The parts refer to the values of designs as `tatc.tradespace.references` +describes. + +@author: Paul T. Grogan +""" + +from __future__ import annotations + +import dataclasses +import numbers +from collections.abc import Mapping, Sequence +from typing import Any + +import numpy as np +import pandas as pd + +from .cost import CostModel +from .criteria import Requirement +from .deployment import DeploymentSchedule, Stage +from .expectations import ExactExpectationsError, exact_expectations +from .failures import FailureModel, RestorationPolicy +from .histories import _history_statistics, evaluate_histories, summarize_histories +from .mission import Capability, Mission +from .references import Reference, _number, configure, value_of +from .simulation import _check_sampling +from .space import Design +from .statistics import Statistic +from .values import ChoiceValues, Values + +_NUMBERS = (numbers.Real, Mapping) +"""The values of fields of numbers: a number, or a mapping (such as of +each type of satellite to its number).""" + + +def _resolve(design: Design, value: Any, kinds: type | tuple[type, ...] = ()) -> Any: + """ + Gets the value of a field of a plan for a design: the value given, if it + is `None` or of the kinds of the field's values, or else the value of the + design that it refers to (see `value_of`). + """ + if value is None or isinstance(value, kinds): + return value + return value_of(design, value) + + +def _numbers(design: Design, value: Any) -> Any: + """ + Gets the value of a field of numbers of a plan for a design (see + `_NUMBERS`): a number, or a mapping of each type of satellite to its + number, each given or a reference to a value of the design. + """ + value = _resolve(design, value, _NUMBERS) + if isinstance(value, Mapping): + return {kind: _number(design, number) for kind, number in value.items()} + return value + + +def _policy(value: Any) -> RestorationPolicy | None: + """ + Gets the policy that a value gives: a policy, or the default policy + configured from the values of a group (a mapping, or a choice of + groups, see `configure`), or else `None`. + """ + if isinstance(value, RestorationPolicy): + return value + if isinstance(value, ChoiceValues): + if value.value is not None and not isinstance(value.value, Values): + return None # a choice of other values + elif not isinstance(value, Mapping): + return None + return configure(RestorationPolicy(), value) + + +@dataclasses.dataclass(frozen=True) +class MissionPlan: + """ + The deployment of the satellites of each design (see + `DeploymentSchedule.plan`), the policy that restores the failures of its + satellites (see `RestorationPolicy`), and its costs (see `CostModel`). + + Each part is given as a value, or as a reference to a value of the + design (see `Reference`: its name or path, or a function of the realized + design that computes it), which the plan reads for each design: a part + that is not a value of its kind (a `DeploymentSchedule`, a `CostModel`, a + `RestorationPolicy`, a sequence of `Stage`, or numbers) is a reference. + The type of the satellites (`kind`) and the scores of cost risk + (`scores`) are always references. A function sizes a part by the values + of the design with relationships of the study's own (TAT-C includes + none, see the module `tatc.tradespace.cost`): for example, the costs of + a type of satellite from the mass of its payload, or the capacity of + launches to the design's altitude:: + + def schedule(d): + return dataclasses.replace(SCHEDULE, launch_mass_capacity=capacity(d.altitude)) + + PLAN = MissionPlan(schedule, COST_MODEL, kind="payload", masses=lambda d: mass(d.payload)) + + The deployment of each design is planned with its policy (see + `DeploymentSchedule.plan`), which gives its spares: in orbit in each + plane (`RestorationPolicy.orbit_spares`) and on the ground, which are + produced (and cost) whether or not the study has failures (see + `Failures`). By default, the policy of a design is its value `policy`, + if it has one (a policy, or a group that configures one, such as a group + of `policy_space`, whose values configure the default policy, see + `configure`; other values raise a `TypeError`), and otherwise the + default policy, which restores failed satellites by producing new ones. + A policy may also be given, or a reference to another value of the + design (a policy, or a group that + configures one), or a function that gives each design's policy (such as + one that configures a base policy):: + + space = space.extend(policy=policy_space(orbit_spares=Integer(0, 1), procurement_years=0.5)) + PLAN = MissionPlan(SCHEDULE, COST_MODEL) # the policy of each design: its values `policy` + PLAN = MissionPlan(SCHEDULE, COST_MODEL, policy=lambda d: configure(BASE_POLICY, d.policy)) + + Launches limited in mass, or priced by mass (see `CostModel.estimate`), + take the masses of the satellites (`masses`). + + The growth of the costs of the components of the cost model (see + `Component`) is drawn from scores that are values of the design (such as + a group of `risk_space`), shared by designs that share components:: + + space = space.extend(cost_risk=risk_space(COST_MODEL)) + PLAN = MissionPlan(SCHEDULE, COST_MODEL, kind="payload", scores="cost_risk") + + Args: + schedule (DeploymentSchedule | Reference): The schedule of the + deployment. + cost_model (CostModel | Reference | None): The costs, or `None`. + kind (Reference | None): The type of the satellites (for schedules, + failures, and costs of several types). + policy (RestorationPolicy | Reference | None): The policy for the + failed satellites of each design, and its spares (or the values + of a group that configure the default policy), or `None` for the + design's value `policy`, if it has one (which must be a policy or + configure one), and otherwise the default policy. + growth (float | Reference | Mapping): The growth of the costs (see + `CostModel.estimate`): a factor, or a mapping of each element + (such as `"development"`) to a factor, or to a mapping of each + type of satellite to one (each a number or a reference). + stages (Sequence[Stage] | Reference): The stages of the deployment + (see `Stage`), such as a function of the design that gives them + by a decision whether to stage it and the values its rules read. + Their rules may also read the capability of the satellites + operating at a decision, by the study's metrics (see + `Decision.capability`). + masses (float | Mapping | Reference | None): The mass (kg) of the + satellites (or of each type, a mapping of each to a number or a + reference), for launches limited (or priced) in mass, or `None`. + scores (Reference | None): The scores from which the growth of the + components of the cost model is drawn (see `CostModel.draw`), + such as a group of `risk_space`, or `None` for the expected + costs of the components. + """ + + schedule: DeploymentSchedule | Reference + cost_model: CostModel | Reference | None = None + _: dataclasses.KW_ONLY + kind: Reference | None = None + policy: RestorationPolicy | Reference | None = None + growth: float | Reference | Mapping[str, Any] = 1.0 + stages: Sequence[Stage] | Reference = () + masses: float | Mapping[Any, float] | Reference | None = None + scores: Reference | None = None + + def _policy_of(self, design: Design) -> RestorationPolicy: + """ + Gets the policy for the failed satellites of a design, and its + spares, raising a `TypeError` if the policy it refers to (or, by + default, its value `policy`, if not `None`) is not a policy or a + group that configures one. + """ + if self.policy is None: + value = design["policy"] if "policy" in design else None + if value is None: + return RestorationPolicy() + named = _policy(value) + if named is None: + raise TypeError( + "the value policy of a design is the default policy of a plan: " + + f"a RestorationPolicy, or values that configure one, not {value!r} " + + "(give the plan's policy= a function of the design that gives it)" + ) + return named + policy = _policy(_resolve(design, self.policy, RestorationPolicy)) + if policy is None: + raise TypeError( + "the policy of a design is a RestorationPolicy, or values that " + + f"configure one, not {value_of(design, self.policy)!r}" + ) + return policy + + def _cost_model_of(self, design: Design) -> CostModel | None: + """ + Gets the cost model of a design, with the growth of its components + drawn from the design's scores (if any, see `CostModel.draw`). + """ + model = _resolve(design, self.cost_model, CostModel) + if model is None or self.scores is None: + return model + return model.draw(value_of(design, self.scores)) + + def _growth_of(self, design: Design) -> Any: + """ + Gets the growth of the costs of a design: a factor, or a mapping of + each element to its factor (or to a mapping of each type of + satellite to its factor). + """ + growth = _resolve(design, self.growth, _NUMBERS) + if not isinstance(growth, Mapping): + return growth + return {element: _numbers(design, value) for element, value in growth.items()} + + def plan_mission( + self, + design: Design, + layout: Any, + capability: Capability, + *, + failures: Failures | None = None, + requirements: Sequence[Requirement] | None = None, + ) -> Mission: + """ + Plans the mission of a realized design: its deployment (with its + policy and spares, and whose stages read the capability of the + satellites operating at their decisions) and its costs. + + Args: + design (Design): The (realized) design. + layout (Any): The layout of its satellites (see `layout_of`). + capability (Capability): The capability of its satellites. + failures (Failures | None): The failures of its satellites, if + any. + requirements (Sequence[Requirement] | None): The requirements on + the metrics of its phases (see `Mission.requirements`), or + `None` not to summarize the phases of a mission without + failures. + + Returns: + Mission: the mission + """ + stages = _resolve(design, self.stages, (list, tuple)) + deployment = _resolve(design, self.schedule, DeploymentSchedule).plan( + layout, + kind=value_of(design, self.kind), + policy=self._policy_of(design), + masses=_numbers(design, self.masses), + stages=tuple(stages or ()), + capability=capability, + ) + return Mission( + design, + deployment, + self._cost_model_of(design), + self._growth_of(design), + failures, + None if requirements is None else tuple(requirements), + ) + + +@dataclasses.dataclass(frozen=True) +class Failures: + """ + The failures of the satellites of each design: histories of its mission + (see `Deployment.simulate_many`), drawn from a `seed` of each replicate + and restored by the policy of its deployment (see `MissionPlan.policy`: + by default by producing new satellites; with + `RestorationPolicy(restore=False)`, not restored), summarized over the + histories (see `summarize_histories`): the mean of each metric over the + phases of the mission and the histories (and the time until a phase + first meets each requirement of the study on its phases, see + `ObservationStudy`), `statistics` of them over the histories (such as a + `Quantile` of the cost), and their costs:: + + statistics = [Quantile("accurate mission", 0.1), Quantile("cost", 0.7)] + FAILURES = Failures(FAILURE_MODEL, seed="failure_seed", histories=20, statistics=statistics) + + The time until a history meets a requirement is infinite if it never + does, so that its mean is infinite if any history never meets it, and + its quantiles, or the share of the histories that meet it by a time (a + `Probability`), summarize it. + + Without restoration, the means of the metrics and the availability are + the exact expectations over the failures (see `exact_expectations`) if + they apply: if the deployment is not staged (see `Stage`, whose rules + make its launches depend on the history) and has at most `MAX_SETS` + (4,096) sets of satellites to enumerate, which is known before they are + enumerated; otherwise (such as for constellations of more than about 12 + satellites, whose sets would cost far more evaluations than the + histories) they are the means of the histories. + + With a `stress`, the failures of satellites and launches are drawn from + stressed distributions for importance sampling (see + `Deployment.simulate_many`), each history weighted by its likelihood + ratio. With `controls`, the means over the histories are estimated with + control variates (see `summarize_histories`): measures of the missions + (see `MissionHistory.metrics`, such as `availability`) whose expected + values are estimated from `control_histories` other histories of the + replicate, simulated without evaluating their phases. + + Args: + model (FailureModel): The failures. + seed (Reference): The value of the design that seeds the failures of + its replicate (see `value_of`), such as of `Uncertain.seed`. + histories (int): The histories of each replicate. + sampling (str): The sampling of the histories (`"stratified"` or + `"random"`, see `Deployment.simulate_many`). + statistics (Sequence[Statistic]): Statistics of the columns of the + histories over the histories: `Quantile`, `Probability`, or + `StandardDeviation` (see `summarize_histories`). + stress (float): The factor of the hazards of stressed failures, and + of the probability that a launch fails (1 for none). + controls (Sequence[str]): The measures of the missions that are + control variates, if any. + control_histories (int): The histories that estimate the expected + values of the controls. + + Raises: + TypeError: if the statistics are not of these kinds. + ValueError: if the numbers of histories are less than 1, the + sampling is unknown, or the stress is not positive. + """ + + model: FailureModel + _: dataclasses.KW_ONLY + seed: Reference + histories: int = 1 + sampling: str = "stratified" + statistics: Sequence[Statistic] = () + stress: float = 1.0 + controls: Sequence[str] = () + control_histories: int = 1000 + + def __post_init__(self): + if isinstance(self.controls, str): + raise TypeError("controls are a sequence of names of measures") + object.__setattr__(self, "controls", tuple(self.controls)) + object.__setattr__(self, "statistics", _history_statistics(self.statistics)) + if self.seed is None: + raise ValueError("failures need a seed: a value of the design") + if self.control_histories < 1: + raise ValueError("control_histories must be at least 1") + _check_sampling(self.histories, self.sampling, self.stress) + + def _seed_of(self, design: Design) -> Any: + """ + Gets the seed of the failures of a (realized) design's replicate, + raising a `ValueError` if it is `None` (of a design that is not + realized). + """ + seed = value_of(design, self.seed) + if seed is None: + raise ValueError( + "the seed of the failures of a design is None: failures need " + + "a realized design (with a seed, such as of Uncertain.seed)" + ) + return seed + + def _evaluate(self, mission: Mission) -> pd.DataFrame: + """ + Evaluates the histories of a mission (see `evaluate_histories`): for + each, the mean of each metric over its phases, the times until they + meet the requirements of the mission, the measures of its mission, + and its costs. + """ + histories = mission.deployment.simulate_many( + self.model, + self._seed_of(mission.design), + histories=self.histories, + sampling=self.sampling, + stress=self.stress, + ) + return evaluate_histories( + histories, + mission.capability, + cost_model=mission.cost_model, + growth=mission.growth, + requirements=mission.requirements or (), + ) + + def _summarize(self, mission: Mission) -> dict[str, float]: + """ + Summarizes the histories of a mission as the metrics of its + evaluation (see `summarize_histories`): with the controls (if any), + and with exact expectations of its means if they apply. + """ + seed = self._seed_of(mission.design) + controls = None + if self.controls: + # other histories of the replicate (by a seed of its seed) + other = int(np.random.default_rng([int(seed), 7]).integers(2**31)) + # pylint: disable-next=protected-access + expected = mission.deployment._expected_metrics( + self.model, + other, + histories=self.control_histories, + sampling=self.sampling, + ) + unknown = sorted(set(self.controls) - set(expected)) + if unknown: + raise ValueError( + f"controls that are not measures of missions: {unknown} " + + f"(they are {sorted(expected)})" + ) + controls = {name: expected[name] for name in self.controls} + record = summarize_histories( + self._evaluate(mission), statistics=self.statistics, controls=controls + ) + try: + exact = exact_expectations( + mission.deployment, self.model, mission.capability + ) + except ExactExpectationsError: + exact = {} # the means of the histories instead + record.update( + { + key: value + for key, value in exact.items() + if key.endswith(" mission") or key == "availability" + } + ) + return record diff --git a/src/tatc/tradespace/plotting.py b/src/tatc/tradespace/plotting.py new file mode 100644 index 0000000..eb88a4a --- /dev/null +++ b/src/tatc/tradespace/plotting.py @@ -0,0 +1,641 @@ +""" +Plots of the results of trade studies (with matplotlib, an optional +dependency, imported when a plot is drawn): designs by two metrics, with the +efficient designs ringed and labeled; the progress of searches; the means +of metrics over replicates; the probabilities that the metrics of designs +exceed those of others; and the shares of the variance of metrics that +factors explain. Each plot draws on given axes (or new ones, with a +constrained layout) and returns them, for further labels and annotations. +`use_style` gives the figures of a session (such as of a notebook) the +style of these plots: titles and legends of their sizes, frameless legends, +light grids behind the data, no top or right spines, and constrained +layouts. + +@author: Paul T. Grogan +""" + +from __future__ import annotations + +from collections.abc import Callable, Mapping, Sequence +from typing import Any + +import numpy as np +import pandas as pd + +from .tables import feasible_records + +COLORS = ( + "#2a78d6", + "#eb6834", + "#1baf7a", + "#eda100", + "#8f5bd6", + "#d6457a", + "#5aa8b0", + "#8a6b4f", +) +"""The colors of groups, in order.""" + +INK = "#2b2b29" +"""The color of text and of the rings of efficient designs.""" + +GRAY = "#8a8a86" +"""The color of references (such as lines of equal values).""" + +GRID = "#e6e6e3" +"""The color of grids.""" + +NEUTRAL = "#f0efec" +"""The color of the midpoint of diverging scales (such as of even odds).""" + +STYLE = { + "axes.titlesize": 10, + "axes.labelcolor": INK, + "axes.axisbelow": True, + "axes.spines.top": False, + "axes.spines.right": False, + "axes.grid": True, + "axes.grid.axis": "y", + "grid.color": GRID, + "grid.linewidth": 0.8, + "legend.fontsize": 8, + "legend.frameon": False, + "figure.constrained_layout.use": True, +} +"""The matplotlib settings of `use_style`.""" + + +def use_style() -> None: + """ + Gives the figures of the session the style of the plots of trade studies + (see `STYLE`): titles of 10 points and legends of 8 without frames, light + grids (of the vertical axis) behind the data, no top or right spines, and + constrained layouts (which need no `tight_layout`). + """ + try: + # pylint: disable-next=import-outside-toplevel + import matplotlib as mpl + except ImportError as error: + raise ImportError( + "plots require matplotlib (pip install matplotlib)" + ) from error + mpl.rcParams.update(STYLE) + + +def _axes(ax: Any, size: tuple[float, float]) -> Any: + """Gets the axes to draw on: those given, or those of a new figure.""" + if ax is not None: + return ax + try: + # pylint: disable-next=import-outside-toplevel + import matplotlib.pyplot as plt + except ImportError as error: + raise ImportError( + "plots require matplotlib (pip install matplotlib)" + ) from error + _, ax = plt.subplots(figsize=size, layout="constrained") + return ax + + +def style_axes(ax: Any, grid: str | None = "y") -> Any: + """ + Styles axes plainly: a light grid behind the data (of the given axes + only), and no top or right spines. + + Args: + ax (matplotlib.axes.Axes): The axes. + grid (str | None): The axes of the grid (`"x"`, `"y"`, or `"both"`), + or `None` for none. + + Returns: + matplotlib.axes.Axes: the axes + """ + ax.grid(False) + if grid is not None: + ax.grid(True, axis=grid, color=GRID, lw=0.8) + ax.set_axisbelow(True) + for side in ("top", "right"): + ax.spines[side].set_visible(False) + return ax + + +_JITTER_SEED = 0 +"""The seed of the random shifts of `plot_designs` (see its `jitter`).""" + +_OTHERS = object() +"""The group of the rows without a value of the column that groups them.""" + + +def _color(colors: Sequence[str] | Mapping[Any, str], value: Any, k: int) -> str: + if isinstance(colors, Mapping): + if value is None and None not in colors: + return next(iter(colors.values())) # of rows without groups + return colors[value] + return colors[k % len(colors)] + + +def _mask(frame: pd.DataFrame, rows: str | Sequence[bool], name: str) -> np.ndarray: + """Gets the rows of a frame that a boolean column (or values) selects.""" + if isinstance(rows, str): + return frame[rows].to_numpy(dtype=bool) + mask = np.asarray(rows, dtype=bool) + if mask.shape != (len(frame),): + raise ValueError(f"{name} needs a value for each row ({len(frame)})") + return mask + + +def _name(names: Mapping[Any, str] | Callable[[Any], str] | None, value: Any) -> str: + if names is None: + return str(value) + if callable(names): + return names(value) + return names.get(value, str(value)) + + +def _front(frame: pd.DataFrame, front: str | Sequence[bool] | None) -> Any: + """ + Gets the efficient rows of a frame to ring (a boolean column, or values), + or `None` for none: without the column `"pareto"` (of a summary of + criteria), none. + """ + if front is None: + return None + if isinstance(front, str) and front not in frame.columns: + if front == "pareto": + return None + raise ValueError(f"the frame has no column {front!r} of efficient designs") + return _mask(frame, front, "front") + + +def _distinct(values: pd.Series) -> list: + """Gets the distinct values (of a column), sorted if they can be.""" + distinct = list(pd.unique(values.dropna())) + try: + return sorted(distinct) + except TypeError: + return distinct + + +def _values_of(frame: pd.DataFrame, by: str | Sequence, name: str) -> pd.Series: + """Gets the values of a column of a frame, or values given for its rows.""" + if isinstance(by, str): + return frame[by] + values = pd.Series(np.asarray(by), index=frame.index) + if len(values) != len(frame): + raise ValueError(f"{name} needs a value for each row ({len(frame)})") + return values + + +def plot_designs( + frame: pd.DataFrame, + x: str, + y: str, + *, + by: str | Sequence | None = None, + front: str | Sequence[bool] | None = "pareto", + annotate: str | Callable[[pd.Series], str] | None = None, + names: Mapping[Any, str] | Callable[[Any], str] | None = None, + highlight: str | Sequence[bool] | None = None, + label: str | None = None, + others: str | None = None, + front_label: str = "Pareto-efficient", + jitter: float = 0.0, + colors: Sequence[str] | Mapping[Any, str] = COLORS, + legend: str | None = "best", + ax: Any = None, +) -> Any: + """ + Plots designs (such as a summary of a study, see `summarize`) by two + metrics: a point per row, colored by the value of a column `by` (if + any), with the efficient designs (`front`, by default those of the + column `pareto` of a summary of criteria, if it has one) ringed. Rows + without a value of `by` (`NaN`, such as of a variable of a branch that a + design does not choose) are drawn in gray, named `others` (or "other") + in the legend. With `highlight`, only some designs are colored, over the + others in gray (such as the designs a search evaluated, over every + design):: + + plot_designs(summary, "satellites", "sufficient", by="layout") + plot_designs( + summary, "cost", "accurate", highlight=summary.policy == "degrade", + label="degrade", others="other policies", + ) + + Args: + frame (pandas.DataFrame): A row per design. + x (str): The column of the horizontal axis. + y (str): The column of the vertical axis. + by (str | Sequence | None): A column whose values color the designs, + values for the rows (such as of a column grouped, as + `summary.planes.clip(upper=3)`), or `None`. + front (str | Sequence[bool] | None): The efficient designs: a boolean + column (by default `"pareto"`, of a summary of criteria, which a + frame without the column does not ring) or values (one per row, + such as of `pareto_front`), or `None`. + annotate (str | Callable | None): The labels of the efficient + designs, written next to them: a column, a function of a row, or + `None` (which needs a front). + names (Mapping | Callable | None): The names of the values of `by` in + the legend (by default, the values). + highlight (str | Sequence[bool] | None): The designs to color (a + boolean column, or values), the others drawn in gray, or `None` + to color every design. + label (str | None): The name of the colored designs in the legend, + without `by`. + others (str | None): The name of the designs in gray in the legend: + those not highlighted, or without a value of `by` ("other" if + not given). + front_label (str): The name of the efficient designs in the legend. + jitter (float): The most that `x` is shifted at random (in its units), + to separate designs of the same `x` (such as numbers of + satellites). + colors (Sequence[str] | Mapping): The colors of the values of `by`, + in order (or by value). + legend (str | None): The location of the legend, or `None` for none. + ax (matplotlib.axes.Axes | None): The axes, or `None` for a new figure. + + Returns: + matplotlib.axes.Axes: the axes + + Raises: + ValueError: if `front` is a column (other than `"pareto"`) that the + frame lacks, or values of a length other than the frame's, or if + designs are annotated without a front. + """ + ringed = _front(frame, front) + if annotate is not None and ringed is None: + raise ValueError( + "annotate labels the efficient designs: give a front (a column " + + "'pareto', such as of a summary of criteria, or values)" + ) + ax = _axes(ax, (9, 4.5)) + shift = np.random.default_rng(_JITTER_SEED).uniform(-jitter, jitter, len(frame)) + xs = frame[x].to_numpy(dtype=float) + (shift if jitter else 0.0) + ys = frame[y].to_numpy(dtype=float) + shown = np.ones(len(frame), dtype=bool) + if highlight is not None: + shown = _mask(frame, highlight, "highlight") + ax.scatter( + xs[~shown], ys[~shown], s=10, color=GRAY, alpha=0.3, lw=0, label=others + ) + if by is None: + ax.scatter( + xs[shown], + ys[shown], + s=14, + color=_color(colors, None, 0), + alpha=0.55 if highlight is None else 0.8, + lw=0, + label=label, + ) + else: + groups = _values_of(frame, by, "by") + for k, value in enumerate(_distinct(groups)): + selected = (groups == value).to_numpy() & shown + ax.scatter( + xs[selected], + ys[selected], + s=14, + color=_color(colors, value, k), + alpha=0.55, + lw=0, + label=_name(names, value), + ) + missing = groups.isna().to_numpy() & shown + if missing.any(): + # the designs not highlighted, if any, are named so already + named = highlight is not None and others is not None + ax.scatter( + xs[missing], + ys[missing], + s=14, + color=GRAY, + alpha=0.55, + lw=0, + label=None if named else (others or "other"), + ) + if ringed is not None: + ax.scatter( + xs[ringed], + ys[ringed], + s=70, + facecolor="none", + edgecolor=INK, + lw=1.5, + label=front_label, + ) + if annotate is not None: + rows = frame[ringed] + for (_, row), point in zip(rows.iterrows(), zip(xs[ringed], ys[ringed])): + ax.annotate( + annotate(row) if callable(annotate) else str(row[annotate]), + point, + xytext=(8, -3), + textcoords="offset points", + fontsize=8, + color=INK, + ) + ax.set(xlabel=x, ylabel=y) + style_axes(ax) + named = by is not None or ringed is not None or label is not None + if legend is not None and (named or others is not None): + ax.legend(loc=legend, fontsize=8, frameon=False, markerscale=1.6) + return ax + + +def plot_progress( + progress: Mapping[str, pd.Series], + *, + colors: Sequence[str] | Mapping[str, str] = COLORS, + legend: str | None = "lower right", + ax: Any = None, +) -> Any: + """ + Plots the progress of searches: a line of each (such as the hypervolume + of the designs evaluated, see `hypervolume_progress`) by the number of + designs evaluated, labeled at its end. + + Args: + progress (Mapping[str, pandas.Series]): The progress of each search, + by its name: a value by the number of designs evaluated. + colors (Sequence[str] | Mapping): The colors of the searches, in + order (or by name). + legend (str | None): The location of the legend, or `None` for none. + ax (matplotlib.axes.Axes | None): The axes, or `None` for a new figure. + + Returns: + matplotlib.axes.Axes: the axes + """ + ax = _axes(ax, (9, 4.2)) + for k, (name, series) in enumerate(progress.items()): + ax.plot( + series.index, series.values, color=_color(colors, name, k), lw=2, label=name + ) + if len(series) > 0: + ax.annotate( + name, + (series.index[-1], series.values[-1]), + xytext=(6, 0), + textcoords="offset points", + va="center", + fontsize=8, + color=INK, + ) + ax.set(xlabel="Designs evaluated", xlim=(0, None)) + style_axes(ax) + if legend is not None and progress: + ax.legend(loc=legend, fontsize=8, frameon=False) + return ax + + +def plot_means( + results: pd.DataFrame, + x: str, + y: str, + *, + by: str | None = None, + names: Mapping[Any, str] | Callable[[Any], str] | None = None, + others: str | None = None, + colors: Sequence[str] | Mapping[Any, str] = COLORS, + legend: str | None = "best", + ax: Any = None, +) -> Any: + """ + Plots the mean of a metric over the feasible records of each value of a + column (such as over the replicates of the designs of each number of + satellites), with a band of one standard deviation about it, a line for + each value of a column `by` (if any), and a line in gray of the records + without a value of `by` (`NaN`), named `others` (or "other"). + + Args: + results (pandas.DataFrame): The results of a study (see `Study.run`). + x (str): The column of the horizontal axis. + y (str): The metric. + by (str | None): A column whose values have their own lines, or + `None`. + names (Mapping | Callable | None): The names of the values of `by` in + the legend (by default, the values). + others (str | None): The name of the records without a value of `by` + in the legend ("other" if not given). + colors (Sequence[str] | Mapping): The colors of the values of `by`, + in order (or by value). + legend (str | None): The location of the legend, or `None` for none. + ax (matplotlib.axes.Axes | None): The axes, or `None` for a new figure. + + Returns: + matplotlib.axes.Axes: the axes + """ + ax = _axes(ax, (6.5, 4.2)) + results = feasible_records(results)[0] + groups = ( + [(None, results)] + if by is None + else [ + (value, results[results[by] == value]) for value in _distinct(results[by]) + ] + ) + missing = None if by is None else results[results[by].isna()] + if missing is not None and len(missing) > 0: + groups.append((_OTHERS, missing)) + for k, (value, group) in enumerate(groups): + stats = group.groupby(x)[y].agg(["mean", "std"]).sort_index() + spread = stats["std"].fillna(0.0) + color = GRAY if value is _OTHERS else _color(colors, value, k) + ax.fill_between( + stats.index, + stats["mean"] - spread, + stats["mean"] + spread, + color=color, + alpha=0.12, + lw=0, + ) + ax.plot( + stats.index, + stats["mean"], + marker="o", + ms=5, + lw=2, + color=color, + mec="white", + mew=1.2, + label=( + None + if value is None + else (others or "other") if value is _OTHERS else _name(names, value) + ), + ) + ax.set(xlabel=x, ylabel=y) + style_axes(ax) + if legend is not None and by is not None: + ax.legend(loc=legend, fontsize=8, frameon=False) + return ax + + +def plot_exceedance( + frame: pd.DataFrame, + *, + names: Mapping[str, str] | Callable[[str], str] | None = None, + colorbar: bool = True, + ax: Any = None, +) -> Any: + """ + Plots the probabilities that the metric of each design exceeds that of + each other design (see `exceedance`) as a matrix: a row per design and a + column per other, in the order of the frame, colored from blue (0: the + design's metric is below the other's in every replicate) through gray + (0.5: as likely either way) to orange (1: above it in every replicate). + Pairs whose order the replicates settle are blue or orange, and those + whose order they leave open are gray: with designs in the order of the + metric's mean, a band of gray along the diagonal is the designs that + the replicates do not tell apart. + + Args: + frame (pandas.DataFrame): The probabilities of a group (see + `exceedance`). + names (Mapping | Callable | None): The names of the designs (by + key), or `None` for their keys. + colorbar (bool): `True` to draw a color bar. + ax (matplotlib.axes.Axes | None): The axes, or `None` for a new figure. + + Returns: + matplotlib.axes.Axes: the axes + + Raises: + ValueError: if the frame has several rows of a pair of designs (as of + several groups, of which plot one). + """ + if frame.duplicated(["design", "other"]).any(): + raise ValueError( + "the frame has several rows of a pair of designs: plot one group" + ) + ax = _axes(ax, (6.5, 5.5)) + # pylint: disable-next=import-outside-toplevel + from matplotlib.colors import LinearSegmentedColormap + + rows = list(pd.unique(frame["design"])) + columns = list(pd.unique(frame["other"])) + matrix = frame.pivot(index="design", columns="other", values="exceedance") + matrix = matrix.reindex(index=rows, columns=columns).to_numpy(dtype=float) + scale = LinearSegmentedColormap.from_list( + "exceedance", [COLORS[0], NEUTRAL, COLORS[1]] + ) + image = ax.imshow( + matrix, cmap=scale, vmin=0, vmax=1, interpolation="nearest", aspect="equal" + ) + ax.set_xticks(range(len(columns))) + ax.set_xticklabels([_name(names, key) for key in columns], rotation=90) + ax.set_yticks(range(len(rows))) + ax.set_yticklabels([_name(names, key) for key in rows]) + ax.tick_params(length=0, labelsize=8, colors=INK) + ax.set(xlabel="Other design", ylabel="Design") + for spine in ax.spines.values(): + spine.set_visible(False) + if colorbar: + legend = ax.figure.colorbar(image, ax=ax, fraction=0.046, pad=0.03) + legend.set_label("Probability that the design exceeds the other", fontsize=9) + legend.set_ticks([0, 0.25, 0.5, 0.75, 1]) + legend.ax.tick_params(labelsize=8, length=0) + legend.outline.set_visible(False) + return ax + + +def plot_shares( + table: pd.DataFrame, + metrics: Sequence[str] | None = None, + *, + groups: str = "factors", + names: Mapping[Any, str] | Callable[[Any], str] | None = None, + labels: Mapping[Any, str] | Callable[[Any], str] | None = None, + horizontal: bool = False, + colors: Sequence[str] | Mapping[Any, str] = COLORS, + legend: str | None = "best", + ax: Any = None, +) -> Any: + """ + Plots the shares of the variance of metrics that factors explain (such + as those of `sensitivity`, by design variable, or of + `Attribution.summary`, by uncertain parameter) as grouped bars: a group + of bars for each factor (a row of the table), one bar for each metric + (a column), or a group for each metric (`groups="metrics"`), one bar for + each factor, with error bars of the standard errors of the shares + (` se`) where the table gives them. + + Args: + table (pandas.DataFrame): A row per factor and a column per metric + (and optionally their standard errors, ` se`). + metrics (Sequence[str] | None): The metrics, or `None` for every + numeric column but standard errors and `active`. + groups (str): `"factors"` for a group of bars for each factor, or + `"metrics"` for one for each metric. + names (Mapping | Callable | None): The names of the factors (by the + index of the table), by default their values. + labels (Mapping | Callable | None): The names of the metrics, by + default the metrics. + horizontal (bool): `True` for horizontal bars (the groups down the + vertical axis, the first at the top). + colors (Sequence[str] | Mapping): The colors of the bars of each + group, in order (or by metric or factor). + legend (str | None): The location of the legend, or `None` for none. + ax (matplotlib.axes.Axes | None): The axes, or `None` for a new figure. + + Returns: + matplotlib.axes.Axes: the axes + """ + # pylint: disable=too-many-locals + if groups not in ("factors", "metrics"): + raise ValueError(f"groups must be 'factors' or 'metrics', not {groups!r}") + if metrics is None: + metrics = [ + column + for column in table.columns + if not str(column).endswith(" se") + and column != "active" + and pd.api.types.is_numeric_dtype(table[column]) + ] + metrics = list(metrics) + factors = list(table.index) + values = table[metrics].to_numpy(dtype=float) + errors = np.column_stack( + [ + ( + table[f"{metric} se"].to_numpy(dtype=float) + if f"{metric} se" in table.columns + else np.full(len(table), np.nan) + ) + for metric in metrics + ] + ) + if groups == "metrics": + values, errors = values.T, errors.T + group_names = [_name(labels, metric) for metric in metrics] + bar_keys, bar_names = factors, [_name(names, factor) for factor in factors] + else: + group_names = [_name(names, factor) for factor in factors] + bar_keys, bar_names = metrics, [_name(labels, metric) for metric in metrics] + ax = _axes(ax, (7.5, 4) if horizontal else (8, 4)) + positions = np.arange(len(group_names)) + width = 0.8 / max(len(bar_keys), 1) + for k, (key, name) in enumerate(zip(bar_keys, bar_names)): + offset = positions + (k - (len(bar_keys) - 1) / 2) * width + error = None if np.all(np.isnan(errors[:, k])) else errors[:, k] + options = { + "color": _color(colors, key, k), + "edgecolor": "white", + "lw": 1, + "label": name, + "error_kw": {"ecolor": INK, "lw": 1}, + } + if horizontal: + ax.barh(offset, values[:, k], height=width, xerr=error, **options) + else: + ax.bar(offset, values[:, k], width=width, yerr=error, **options) + if horizontal: + ax.set_yticks(positions, group_names) + ax.invert_yaxis() + style_axes(ax, grid="x") + else: + ax.set_xticks(positions, group_names) + style_axes(ax, grid="y") + if legend is not None and len(bar_keys) > 1: + ax.legend(loc=legend, fontsize=8, frameon=False) + return ax diff --git a/src/tatc/tradespace/references.py b/src/tatc/tradespace/references.py new file mode 100644 index 0000000..4dc785e --- /dev/null +++ b/src/tatc/tradespace/references.py @@ -0,0 +1,158 @@ +""" +Reading designs: references to their values, the dataclasses configured +from them, and the functions given them. + +A reference names a value of a design, by which the parts of studies (such +as `ObservationStudy`, `Observations`, `Targets`, `MissionPlan`, and +`Failures`) read the designs they are given (see `value_of`). It is either +a string, which names a value by its name (such as `"points_seed"` for +`d.points_seed`) or path (as the columns of the results of a study name +values, see `Design.flat`, such as `"layout.walker.planes"`, or of a group +of values, such as `"cost_risk"`), or a function of the (realized) design +that computes the value (such as `lambda d: d.layout`). A string given where +a reference is expected is always a reference, never a value itself: give a +function that returns a string to give a string. Where a number is also +expected (such as a growth of costs), a number is the value itself, and +other values are references:: + + MissionPlan(SCHEDULE, COST_MODEL, kind="field_of_regard") # d.field_of_regard + MissionPlan(SCHEDULE, COST_MODEL, kind=lambda d: "imager") # always "imager" + +A dataclass, such as a `RestorationPolicy` or a `DeploymentSchedule`, is +configured from the values of a design by `configure`. + +A function of a study's results (such as the evaluation function of a +`Study`, or the metrics of an `ObservationStudy`) that takes a keyword named +`design` is given the realized design as it, as for a function that +depends on values of the design other than those it is given. + +@author: Paul T. Grogan +""" + +from __future__ import annotations + +import dataclasses +import inspect +import numbers +from collections.abc import Callable, Mapping +from functools import partial +from typing import Any + +from .space import Design +from .values import ChoiceValues, Values + +Reference = str | Callable[[Design], Any] +"""A reference to a value of a design: its name or path (see `Design.flat`), +or a function of the (realized) design that gives it (see `value_of`).""" + + +def value_of(design: Design, reference: Reference | None) -> Any: + """ + Gets a value of a design that a reference names (see the module): a + string names a value by its name or path (`design[reference]`, see + `Values`: such as `"layout.walker.planes"`, the path of a column of + results, see `Design.flat`, or of a group of values, such as + `"cost_risk"`), a function computes it from the design, and `None` is + `None`. + + Args: + design (Design): The (realized) design. + reference (Reference | None): The reference: a string, a function, + or `None`. + + Returns: + Any: the value + + Raises: + KeyError: if the design has no value of a name or path. + TypeError: if the reference is neither a string nor a function. + """ + if reference is None: + return None + if callable(reference): + return reference(design) + if not isinstance(reference, str): + raise TypeError(f"a reference to a value of a design, not {reference!r}") + return design[reference] + + +def _number(design: Design, value: Any) -> Any: + """A number, or a value of a design that a reference names.""" + if isinstance(value, numbers.Real): + return value + return value_of(design, value) + + +def configure(base: Any, values: Any = None, **overrides: Any) -> Any: + """ + Configures a dataclass (such as a `RestorationPolicy` or a + `DeploymentSchedule`) from the values of a design: the fields of `base` + that the values name (such as those of `policy_space`, or design + variables named after fields) are replaced by them, as are those given + as keyword arguments. Values that name no field are ignored:: + + policy = configure(RestorationPolicy(), design.policy) + schedule = configure(SCHEDULE, design, years=6) + + Args: + base (Any): The dataclass instance, whose other fields are kept. + values (Any): The values of a design: a `Design`, the `Values` of + a group, a mapping, or the `ChoiceValues` of a choice (whose + branch is a group, or a fixed `None`), or `None`. + **overrides (Any): Other values of fields. + + Returns: + Any: a copy of `base` with the values of its fields + + Raises: + TypeError: if `base` is not a dataclass instance, or `values` are + not values of a design (or a choice's branch is not a group). + ValueError: if an override names no field of `base`. + """ + if not dataclasses.is_dataclass(base) or isinstance(base, type): + raise TypeError("configure requires a dataclass instance") + if isinstance(values, ChoiceValues): + branch = values.value + if branch is not None and not isinstance(branch, Values): + raise TypeError( + "configure requires the values of a group: the choice chose " + + f"{values.choice!r}, whose value is {branch!r}" + ) + values = branch + elif isinstance(values, Design): + values = values.values + elif values is not None and not isinstance(values, Mapping): + raise TypeError(f"configure requires the values of a design, not {values!r}") + names = {field.name for field in dataclasses.fields(base)} + changes = {name: values[name] for name in (values or {}) if name in names} + unknown = set(overrides) - names + if unknown: + raise ValueError(f"no fields named {sorted(unknown)}") + return dataclasses.replace(base, **changes, **overrides) + + +def _takes_design(function: Callable[..., Any]) -> bool: + """ + Whether a function takes a keyword named `design` (a parameter named + `design` that may be given by keyword), by which the parts of studies + give it the realized design (see `_given_design`). + """ + try: + parameter = inspect.signature(function).parameters.get("design") + except (TypeError, ValueError): # such as of some built-in functions + return False + return parameter is not None and parameter.kind in ( + inspect.Parameter.POSITIONAL_OR_KEYWORD, + inspect.Parameter.KEYWORD_ONLY, + ) + + +def _given_design(function: Callable[..., Any], design: Design) -> Callable[..., Any]: + """ + Gets a function of its other arguments: the function given the + (realized) design as its keyword `design`, if it takes one (see + `_takes_design`), or the function itself:: + + outcome = _given_design(evaluate, realized)(built) + """ + return partial(function, design=design) if _takes_design(function) else function diff --git a/src/tatc/tradespace/refinement.py b/src/tatc/tradespace/refinement.py new file mode 100644 index 0000000..075453b --- /dev/null +++ b/src/tatc/tradespace/refinement.py @@ -0,0 +1,404 @@ +""" +Adaptive replication: replicates added only to the designs whose Pareto +efficiency their replicates do not settle, within a budget of evaluations. + +@author: Paul T. Grogan +""" + +from __future__ import annotations + +from collections.abc import Mapping, Sequence +from dataclasses import dataclass, field + +import numpy as np +import pandas as pd + +from .alerts import _warn +from .criteria import Criteria, _as_criteria, _tolerances +from .space import Design, _designs +from .study import Study +from .summary import pareto_probability +from .tables import efficient_keys + + +@dataclass +class Refinement: + """ + The outcome of an adaptive replication (see `refine`): as the outcomes of + other steps of a trade study (see `Confirmation`, `Screening`, and + `Search`), its `results`, the `summary` of its designs, the `designs` it + selects for the next step, and its `criteria`:: + + refinement = refine(study, criteria, results) + confirmation = confirm(study, criteria, refinement.results, refinement.designs) + + The designs a refinement selects are those efficient by the criteria over + every replicate after its last round (`pareto` of its `summary`), which a + confirmation checks with new replicates (see `confirm`, which selects + them by default): designs whose efficiency is still uncertain may be + efficient by more replicates too, those that more replicates would + settle:: + + summary = refinement.summary + unsettled = summary[summary.uncertain & ~summary.indifferent] + """ + + results: pd.DataFrame + """pandas.DataFrame: The results of every evaluation, those given and + those added (see `Study.run`).""" + summary: pd.DataFrame + """pandas.DataFrame: A row per design (and group of the criteria's `by`): + the probability that it is efficient after the last round (see + `pareto_probability`, with the values of the design), whether its + efficiency is `uncertain` (its probability is strictly between the + bounds of `refine`, or it has fewer feasible replicates than the least), + and whether an uncertain design is `indifferent` (its objectives are + known to within the precision of their tolerances, so that whether it is + within the tolerances of the front does not matter, and it is not + refined). Designs that more replicates would settle are those uncertain + but not indifferent.""" + designs: list[Design] + """list[Design]: The designs efficient after the last round (`pareto` of + `summary`, in any group of the criteria's `by`), for the next step.""" + criteria: Criteria + """Criteria: The criteria of the refinement.""" + rounds: pd.DataFrame = field(default_factory=pd.DataFrame) + """pandas.DataFrame: A row per round (`round`, from 0): the number of + designs whose efficiency is uncertain (`uncertain`, in any group), of + these, those that are indifferent wherever they are uncertain + (`indifferent`), the number to which replicates were added (`refined`), + and the evaluations added (`evaluations`, a design in a replicate in + each scenario of a study with scenarios).""" + candidates: list[Design] = field(default_factory=list) + """list[Design]: The designs that could be refined (those given to + `refine`).""" + + @property + def evaluations(self) -> int: + """int: The number of evaluations added over every round (a design in + a replicate in a scenario: a study with scenarios evaluates each + replicate in each scenario).""" + if "evaluations" not in self.rounds: + return 0 + return int(self.rounds["evaluations"].sum()) + + +def _precise( + probability: pd.DataFrame, criteria: Criteria, precision: float | None +) -> np.ndarray: + """ + Gets whether each design's objectives are known to within the precision + of their tolerances: the standard error of each objective that varies + between replicates is less than `precision` times its tolerance (at the + design's value). Designs whose varying objectives lack a tolerance are + not precise. An objective without a standard error (which + `pareto_probability` leaves out where it is zero for every design) does + not vary, and one whose standard error is unknown (`NaN`) is not precise. + """ + precise = np.zeros(len(probability), dtype=bool) + if precision is None or not criteria.tolerances: + return precise + tolerances = _tolerances(criteria) + precise[:] = True + for i, name in enumerate(criteria.objectives): + if f"{name} se" not in probability: + continue + error = probability[f"{name} se"].to_numpy(dtype=float) + value = np.abs(probability[name].to_numpy(dtype=float)) + tolerance = tolerances[0, i] + tolerances[1, i] * value + # an unknown (NaN) error may vary, and is not less than any precision + varies = ~(error == 0) + precise &= ~varies | (error < precision * tolerance) + return precise + + +def refine( + study: Study, + criteria: Criteria | Mapping[str, str], + results: pd.DataFrame, + designs: Sequence[Design | str] | pd.DataFrame | None = None, + *, + bounds: tuple[float, float] = (0.05, 0.95), + step: int | None = None, + max_replicates: int | None = None, + min_replicates: int = 5, + max_rounds: int = 10, + precision: float | None = 0.5, + budget: int | None = None, + n_resamples: int = 500, + seed: int = 0, +) -> Refinement: + """ + Adds replicates to the designs whose Pareto efficiency (by criteria, see + `Criteria`) is uncertain, until it is settled: in each round, the + probability that each design is efficient (and meets the requirements) + is estimated by a bootstrap (see + `pareto_probability`), and each design whose probability is strictly + between the `bounds` gets `step` more replicates, up to + `max_replicates`. Rounds end when no design is uncertain (or can be + refined), when the `budget` of evaluations is spent, or after + `max_rounds`. If a round would spend more than is left of the budget, the + designs with the fewest replicates (below `min_replicates`) are refined + first, and then those whose probability is nearest 0.5. A study with + scenarios evaluates each replicate in each scenario, which spends an + evaluation of the budget in each. + + A bootstrap of few replicates has few distinct resamples, and can find a + design surely inefficient (or efficient) by the luck of its replicates: + with two replicates, designs as good as the front can be efficient in + none of the resamples. Designs with fewer than `min_replicates` are + therefore uncertain whatever their probability, and are refined first. + + Replicates are added in order (the next indices after a design's + replicates), so that designs refined together share their uncertain + parameters (with common random numbers, see `Design.realize`). Designs + that are surely efficient or surely not keep their replicates, which + saves the evaluations that uniform replication would spend on them. + + Designs that differ by less than any number of replicates could + separate (such as designs near saturation) stay uncertain: give the + criteria a tolerance of the objectives within which differences do not + matter, so that such designs are all efficient (see + `pareto_probability`). A design whose distance from the front is about + its tolerance stays uncertain too, and more replicates settle which side + of the tolerance it falls on only slowly, though it does not matter: a + design is `indifferent`, and not refined, once the standard error of each + objective that varies between its replicates (see `pareto_probability`) + is less than `precision` times the objective's tolerance (at the + design's value), which saves the evaluations that would otherwise go to + such designs until `max_replicates`. A design whose varying objectives + lack a tolerance is never indifferent. A warning is given if designs + remain uncertain (but not indifferent) without a tolerance. + + Designs are judged by their feasible replicates (see `summarize`): a + design has fewer than `min_replicates` if fewer of its replicates are + feasible, and `max_replicates` limits all of its replicates. Designs + without a feasible replicate are not refined (and a refinement of results + without a feasible record adds none). + + The refinement selects the designs efficient after its last round for + the next step (`Refinement.designs`, such as of `confirm`), and keeps + those that could be refined (`Refinement.candidates`), its rounds + (`Refinement.rounds`), and the number of evaluations it added + (`Refinement.evaluations`). + + Args: + study (Study): The study that evaluates designs. + criteria (Criteria | Mapping[str, str]): The criteria, or the + objectives (metrics whose means they are) and their directions + (`"min"` or `"max"`). A design is uncertain if it is in any + group of the criteria's `by`. + results (pandas.DataFrame): The results of the designs (see + `Study.run`), such as those of an enumeration or a search. + designs (Sequence[Design | str] | pandas.DataFrame | None): The + designs that may be refined (designs, their keys, or a data + frame of them, such as rows of a summary, or the `designs` of + another step), or `None` for every design of the results + (rebuilt from them, see `DesignSpace.designs_of`). + bounds (tuple[float, float]): The probabilities between which a + design is uncertain. + step (int | None): The replicates added to an uncertain design in a + round, or `None` for the study's number of replicates. + max_replicates (int | None): The most replicates of a design, if + limited. + min_replicates (int): The fewest feasible replicates with which a + design's efficiency can be settled. + max_rounds (int): The most rounds. + precision (float | None): The standard error of an objective, as a + share of its tolerance, below which an uncertain design is + indifferent, or `None` to refine uncertain designs until + `max_replicates`. + budget (int | None): The most evaluations to add (a design in a + replicate in a scenario: a replicate of a study with scenarios + takes an evaluation in each), if limited. + n_resamples (int): The number of resamples of each bootstrap. + seed (int): The seed of the bootstraps. + + Returns: + Refinement: the results, the final probabilities, the rounds, the + efficient designs, and the candidates + """ + criteria = _as_criteria(criteria) + low, high = bounds + if not 0 <= low < high <= 1: + raise ValueError("bounds must satisfy 0 <= low < high <= 1") + step = study.replicates if step is None else step + if step < 1: + raise ValueError("step must be at least 1") + if max_replicates is not None and max_replicates < min_replicates: + raise ValueError("max_replicates must be at least min_replicates") + if precision is not None and precision <= 0: + raise ValueError("precision must be positive (or None)") + if budget is not None and budget < 0: + raise ValueError("budget must not be negative") + refined = _designs(study.space, results if designs is None else designs, results) + by_key = {design.key: design for design in refined} + # the evaluations of a replicate of a design: one in each scenario + cost = len(study.scenarios or [None]) + combined, rounds, spent = results, [], 0 + + def estimate(round_: int) -> pd.DataFrame: + probability = pareto_probability( + combined, criteria, n_resamples=n_resamples, seed=seed + round_ + ) + few = probability["replicates"] < min_replicates + probability["uncertain"] = ( + (probability["pareto_probability"] > low) + & (probability["pareto_probability"] < high) + ) | few + probability["indifferent"] = ( + probability["uncertain"] & ~few & _precise(probability, criteria, precision) + ) + return probability + + for round_ in range(max_rounds): + probability = estimate(round_) + uncertain, indifferent, settling = _settling(probability) + following = combined.groupby("design")["replicate"].max() + 1 + added_to = _allocate( + probability, + settling, + following, + list(by_key), + step=step, + min_replicates=min_replicates, + max_replicates=max_replicates, + budget=None if budget is None else budget - spent, + cost=cost, + ) + record = { + "round": round_, + "uncertain": int(uncertain.sum()), + "indifferent": int(indifferent.sum()), + "refined": len(added_to), + "evaluations": 0, + } + if not added_to: + rounds.append(record) + break + added = _evaluate_added(study, by_key, following, added_to) + combined = pd.concat([combined, *added], ignore_index=True) + record["evaluations"] = sum(_count_evaluations(new) for new in added) + spent += record["evaluations"] + rounds.append(record) + else: + probability = estimate(max_rounds) + remaining = probability.loc[ + probability["uncertain"] & ~probability["indifferent"], "design" + ].nunique() + if remaining > 0 and not criteria.tolerances: + _warn( + f"{remaining} designs remain uncertain: designs that differ by less " + + "than replicates separate stay uncertain without a tolerance of " + + "the objectives (see Criteria)" + ) + selected = [by_key.get(key, key) for key in efficient_keys(probability)] + return Refinement( + results=combined, + summary=probability, + designs=_designs(study.space, selected, combined), + criteria=criteria, + rounds=pd.DataFrame(rounds), + candidates=refined, + ) + + +def _settling(probability: pd.DataFrame) -> tuple[pd.Series, pd.Series, pd.Series]: + """ + Gets, by design, whether its efficiency is uncertain (in any group of the + criteria's `by`), indifferent (uncertain only where its objectives are + known to within the precision of their tolerances), and settling (more + replicates would settle it), for a round of `refine`. + """ + uncertain = probability.groupby("design")["uncertain"].any() + settling = ( + (probability["uncertain"] & ~probability["indifferent"]) + .groupby(probability["design"]) + .any() + ) + return uncertain, uncertain & ~settling, settling + + +def _allocate( + probability: pd.DataFrame, + settling: pd.Series, + following: pd.Series, + refinable: list[str], + *, + step: int, + min_replicates: int, + max_replicates: int | None, + budget: int | None, + cost: int = 1, +) -> dict[str, int]: + """ + Gets the replicates to add to designs whose efficiency more replicates + would settle (by key), for a round of `refine`: `step` each (up to + `max_replicates`), the fewest replicates and the least settled first + (nearest a probability of 0.5), within a budget of evaluations (if any), + of which each replicate spends `cost` (one in each scenario). + """ + grouped = probability.groupby("design") + distance = (probability["pareto_probability"] - 0.5).abs() + priority = pd.DataFrame( + { + "few": grouped["replicates"].min() < min_replicates, + "distance": distance.groupby(probability["design"]).min(), + "replicates": grouped["replicates"].min(), + } + ) + candidates = priority[settling.reindex(priority.index, fill_value=False)] + candidates = candidates.sort_values( + ["few", "distance", "replicates"], ascending=[False, True, True] + ) + left: int | None = budget + added: dict[str, int] = {} + allowed = set(refinable) + for key in candidates.index: + if key not in allowed: + continue + count = step + if max_replicates is not None: + count = min(count, max_replicates - int(following[key])) + if left is not None: + count = min(count, left // cost) + if count <= 0: + continue + added[key] = count + if left is not None: + left -= count * cost + if left < cost: + break + return added + + +def _count_evaluations(results: pd.DataFrame) -> int: + """ + Counts the evaluations of results: a design in a replicate (in a + scenario, with scenarios), whatever the number of records of each. + """ + keys = ["design", "replicate", *(["scenario"] if "scenario" in results else [])] + return results.groupby(keys).ngroups + + +def _evaluate_added( + study: Study, + designs: dict[str, Design], + following: pd.Series, + added: dict[str, int], +) -> list[pd.DataFrame]: + """ + Evaluates the replicates added to designs (by key, after the replicates + each has): designs with the same new replicates together. + """ + plan = pd.DataFrame( + {"start": following[list(added)].astype(int), "count": list(added.values())}, + index=list(added), + ) + return [ + study.run( + [designs[key] for key in keys.index], + replicate_indices=range(int(start), int(start) + int(count)), + ) + for (start, count), keys in plan.groupby(["start", "count"]) + ] diff --git a/src/tatc/tradespace/scenarios.py b/src/tatc/tradespace/scenarios.py new file mode 100644 index 0000000..12d7676 --- /dev/null +++ b/src/tatc/tradespace/scenarios.py @@ -0,0 +1,179 @@ +""" +Scenarios: conditions under which designs are compared rather than averaged +over (see `Study`), such as the requirements of a mission or the field it +must sample, and the robustness of designs across them. + +@author: Paul T. Grogan +""" + +from __future__ import annotations + +import dataclasses +from collections.abc import Mapping + +import numpy as np +import pandas as pd + +from .criteria import Criteria, _as_criteria, _resolved, _signs, _tolerances +from .summary import _summarize +from .tables import design_values, value_columns + + +def _scales(criteria: Criteria, scale: Mapping[str, float] | None) -> np.ndarray: + """ + Gets the scale of each objective of criteria: the given one, or its + absolute tolerance (if any), or 1. + """ + objectives = list(criteria.objectives) + scale = dict(scale or {}) + unknown = sorted(set(scale) - set(objectives)) + if unknown: + raise ValueError(f"scales of names that are not objectives: {unknown}") + absolute = _tolerances(criteria)[0] + values = np.array( + [ + float(scale[name]) if name in scale else (absolute[i] or 1.0) + for i, name in enumerate(objectives) + ] + ) + if not np.all(values > 0): + raise ValueError("the scales of the objectives must be positive") + return values + + +def robustness( + results: pd.DataFrame, + criteria: Criteria | Mapping[str, str], + *, + scale: Mapping[str, float] | None = None, +) -> pd.DataFrame: + """ + Measures the robustness of designs across scenarios (see `Study`): how + often each design is efficient, and how far it falls from the front of + each scenario, from the results of a study in each scenario (judged by + the criteria in each scenario, see `summarize` and `pareto_front`). The + scenarios are the groups of the column of the criteria's `by` (by + default, `"scenario"`, as of a study with scenarios). + + * `pareto_trace`: the share of the scenarios in which the design is + efficient (with the tolerances of the criteria, within which designs + near the front are efficient, as in epoch-era analysis's fuzzy + normalized Pareto trace). A design efficient in every scenario has a + trace of 1. + * ` regret`: in each scenario, the improvement in every + objective (in units of its `scale`) that the design would need to match + a design of the scenario's front (the additive epsilon indicator, as + the fuzzy Pareto number of epoch-era analysis): 0 if it is efficient, + and infinite if it misses the requirements of the criteria, is + infeasible in every replicate, or has a missing objective (`NaN`, which + is not efficient, see `pareto_front`). With one objective, it is the + difference from the best design. + * `max_regret`: the largest regret of the design over the scenarios, which + the most robust designs minimize (minimax regret). + + With objectives of few levels (such as numbers of satellites), regret is + at most a design's distance in them from the cheapest design of the + front, whatever its other objectives, as dropping that much matches it: + for the regret of the other objectives at a cost, require the cost (see + `Requirement`) rather than minimizing it. + + Designs are compared with the others of the results, by the statistics of + their replicates, whose uncertainty these measures do not show (see + `pareto_probability`, with criteria `by` the scenario). + + Args: + results (pandas.DataFrame): The results of a study with scenarios + (see `Study.run`). + criteria (Criteria | Mapping[str, str]): The criteria, by which + designs are judged in each scenario (`by` none, for the column + `"scenario"`, or the column of the scenarios), or the objectives + (metrics whose means they are) and their directions (`"min"` or + `"max"`). + scale (Mapping[str, float] | None): The units of regret of + objectives (by name): by default, the absolute tolerance of an + objective (if it has one), or else 1 (its units). + + Returns: + pandas.DataFrame: a row per design (`design`): the values of the + design (as a summary keeps them, see `summarize`), each objective + in each scenario (` `), or once + (``) if it is a value of the designs (the same in + every feasible record of a design, such as a number of + satellites), its `pareto_trace`, `max_regret`, and regret in each + scenario (` regret`) + + Raises: + ValueError: if the results have no scenarios, or the criteria group + records by several columns or combine them across scenarios (see + `Across`, by which searches find robust designs). + """ + criteria = _as_criteria(criteria) + if criteria.across is not None: + raise ValueError( + "robustness judges designs in each scenario: give criteria without " + + "`across`" + ) + if len(criteria.by) > 1: + raise ValueError( + "robustness judges designs in each scenario: give criteria `by` the " + + f"column of the scenarios alone, not {list(criteria.by)}" + ) + scenario = criteria.by[0] if criteria.by else "scenario" + if scenario not in results.columns: + raise ValueError( + f"the results have no column {scenario!r} of scenarios (see Study, " + + "or give the column as the criteria's `by`)" + ) + judged = dataclasses.replace(criteria, by=(scenario,)) + objectives = list(criteria.objectives) + # each objective in units of its scale, larger being better + units = -_signs(criteria) / _scales(criteria, scale) + summary = _summarize(results, judged, design_values=False) + efficient = summary["pareto"].to_numpy(dtype=bool) + scenarios = list(pd.unique(results[scenario])) + designs = list(pd.unique(results["design"])) + regret = pd.DataFrame(np.inf, index=designs, columns=scenarios) + trace = pd.Series(0.0, index=designs) + for name in scenarios: + rows = (summary[scenario] == name).to_numpy() + group, front = summary[rows], efficient[rows] + keys = group["design"].to_numpy() + values = group[objectives].to_numpy(dtype=float) * units + needed = np.full(len(group), np.inf) + if front.any(): + # the improvement in every objective that each design needs to + # match a design of the front: the least over the front of the + # largest shortfall over the objectives + shortfall = values[front][None, :, :] - values[:, None, :] + needed = np.maximum(shortfall.max(axis=2).min(axis=1), 0.0) + # a design with a missing objective is not efficient: infinite regret + needed = np.where(np.isnan(values).any(axis=1), np.inf, needed) + meets = group["meets_requirements"].to_numpy(dtype=bool) + regret.loc[keys, name] = np.where(front, 0.0, np.where(meets, needed, np.inf)) + trace[keys[front]] += 1 + # the values of the designs (of their first records, as of a summary), and + # the objectives that are values of the designs, which are the same in + # every scenario + statistics = _resolved(judged) + every = value_columns(results, {}, (scenario,), None) + metrics = {column for s in statistics.values() for column in s.columns} + columns = [c for c in every if c not in metrics and c not in statistics] + collapsed = { + name + for name in objectives + if name in every and set(statistics[name].columns) <= set(every) + } + frame = design_values(results, designs, columns) + for name in objectives: + table = summary.pivot(index="design", columns=scenario, values=name) + table = table.reindex(index=designs, columns=scenarios) + if name in collapsed: + frame[name] = table.bfill(axis=1).iloc[:, 0].to_numpy() + else: + for group in scenarios: + frame[f"{group} {name}"] = table[group].to_numpy() + frame["pareto_trace"] = (trace / max(len(scenarios), 1)).to_numpy() + frame["max_regret"] = regret.max(axis=1, skipna=False).to_numpy() + for name in scenarios: + frame[f"{name} regret"] = regret[name].to_numpy() + return frame diff --git a/src/tatc/tradespace/screening.py b/src/tatc/tradespace/screening.py new file mode 100644 index 0000000..b359606 --- /dev/null +++ b/src/tatc/tradespace/screening.py @@ -0,0 +1,200 @@ +""" +Screening of designs with analyses of increasing fidelity: cheap analyses +(such as shorter periods, fewer targets, or fewer replicates) rank many +designs, and only the best are analyzed with more expensive ones. + +@author: Paul T. Grogan +""" + +from __future__ import annotations + +import math +import numbers +from collections.abc import Mapping, Sequence +from dataclasses import dataclass, field + +import pandas as pd + +from .criteria import Criteria, _as_criteria +from .pareto import pareto_ranks +from .space import Design, _designs +from .study import Study +from .summary import _summarize + + +@dataclass +class Screening: + """ + The outcome of a screening (see `screen`): as the outcomes of other steps + of a trade study (see `Refinement`), its `results` and the `summary` of + its designs (those of its last stage, the analysis of the highest + fidelity), the `designs` it selects for the next step (those that + survive every stage), and its `criteria` (those of the last stage), + which refine and confirm its designs as for any study:: + + screening = screen([quick, full], criteria, designs, keep=0.1) + refinement = refine(full, criteria, screening.results, screening.designs) + + The results and summaries of every stage are kept as well (`history` and + `summaries`, with the `stage` of each row). + """ + + results: pd.DataFrame + """pandas.DataFrame: The results of the last stage (see `Study.run`).""" + summary: pd.DataFrame + """pandas.DataFrame: The summary of the designs of the last stage (a row + of `summaries`).""" + designs: list[Design] + """list[Design]: The designs that survive every stage (those the last + stage analyzes), for the next step.""" + criteria: Criteria + """Criteria: The criteria of the last stage.""" + history: pd.DataFrame = field(default_factory=pd.DataFrame) + """pandas.DataFrame: The results of every stage, with the `stage` (0 for + the first), such as for the cost of the screening.""" + summaries: pd.DataFrame = field(default_factory=pd.DataFrame) + """pandas.DataFrame: The summaries of the designs of every stage (see + `summarize`, with the spreads of means and whether each is efficient by + the stage's analysis, `pareto`), with their Pareto rank (`pareto_rank`, + see `pareto_ranks`), whether they were `kept` for the next stage, and the + `stage` (0 for the first).""" + + +def _per_stage(value, count: int, name: str) -> list: + """ + Gets a value for each of `count` transitions between stages. + """ + if isinstance(value, Sequence) and not isinstance(value, str): + if len(value) != count: + raise ValueError(f"{name} needs a value for each of {count} transitions") + return list(value) + return [value] * count + + +def _check_keep(value) -> None: + """ + Checks a number of designs to keep (an integer of at least 1) or a share + of them (a float greater than 0 and at most 1). + """ + if isinstance(value, bool) or not isinstance(value, numbers.Real): + raise TypeError(f"keep must be a number or a share of designs, not {value!r}") + if isinstance(value, numbers.Integral): + if value < 1: + raise ValueError(f"a number of designs to keep must be at least 1: {value}") + elif not 0 < value <= 1: + raise ValueError( + f"a share of designs to keep must be greater than 0 and at most 1: {value}" + ) + + +def screen( + studies: Sequence[Study], + criteria: Criteria | Mapping[str, str] | Sequence[Criteria | Mapping[str, str]], + designs: Sequence[Design] | pd.DataFrame, + *, + keep: float | int | Sequence[float | int] = 0.25, +) -> Screening: + """ + Screens designs with studies of increasing fidelity (and cost): each + study (stage) evaluates the designs kept by the one before, ranks them by + non-dominated sorting of the objectives of the criteria (see + `pareto_ranks`): the means of metrics, or other statistics over their + replicates (see `Criteria`), and keeps whole fronts, best first, until + it keeps at least `keep` designs (a number, or a share of the feasible + designs). + + Designs that miss a requirement are ranked after those that meet them + all, in order of their violation, and designs with a missing objective + last (see `pareto_ranks`), rather than dropped: + a cheap analysis may miss a requirement that the full analysis meets, so + designs that nearly meet the requirements are kept if `keep` reaches + them. + + A cheap analysis ranks designs less exactly than an expensive one, so a + design it ranks just behind another may be better: keep enough designs, + or give the stages of cheap analyses criteria of their own, with a + tolerance of each objective (in the units of the stage's analysis) + within which differences do not separate fronts (see `pareto_front`), + so that nearly efficient designs are kept:: + + cheap = Criteria(objectives, tolerances={"sufficient": 5.0}) + screening = screen([quick, full], [cheap, objectives], designs, keep=0.1) + + Compare the final front with one found without screening on a sample of + designs to check that screening does not lose efficient designs. + + The screening's `results` are those of its last stage, which the next + steps continue (such as `refine` and `confirm`), and its `designs` are + those that survive every stage (that the last stage analyzes); its + `history` gives the results of every stage (with the `stage`), such as + for the cost of the screening. + + Args: + studies (Sequence[Study]): The studies of each stage, in order of + increasing fidelity. + criteria (Criteria | Mapping[str, str] | Sequence): The criteria, + without `by` (see `Criteria`), or the objectives (metrics whose + means they are) and their directions (`"min"` or `"max"`): the + same for every stage, or those of each stage. + designs (Sequence[Design] | pandas.DataFrame): The designs to + screen, or a data frame of their values (see + `DesignSpace.designs_of`). + keep (float | int | Sequence): The designs kept by each stage but the + last: a number (an int of at least 1), or a share of its feasible + designs (a float greater than 0 and at most 1), or a value for + each stage. + + Returns: + Screening: the results and summary of the last stage, the designs + that survive every stage, and the results and summaries of each + stage + """ + if len(studies) == 0: + raise ValueError("at least one study is required") + transitions = len(studies) - 1 + keeps = _per_stage(keep, transitions, "keep") + for amount in keeps: + _check_keep(amount) + if isinstance(criteria, (Criteria, Mapping)): + stages = [_as_criteria(criteria)] * len(studies) + else: + stages = [ + _as_criteria(c) for c in _per_stage(criteria, len(studies), "criteria") + ] + for criteria in stages: + if criteria.by: + raise ValueError( + "screening ranks designs by one record per evaluation: " + + "give criteria without `by`" + ) + current = _designs(studies[0].space, designs) + frames, summaries = [], [] + for stage, study in enumerate(studies): + criteria = stages[stage] + results = study.run(current) + frames.append(results.assign(stage=stage)) + summary = _summarize(results, criteria, spread=True) + summary["pareto_rank"] = pareto_ranks(summary, criteria) + if stage < transitions: + amount = keeps[stage] + count = ( + min(int(amount), len(summary)) + if isinstance(amount, numbers.Integral) + else math.ceil(amount * len(summary)) + ) + ranks = summary["pareto_rank"].sort_values(kind="stable") + last = ranks.iloc[count - 1] if count > 0 else -1 + summary["kept"] = summary["pareto_rank"] <= last + kept = set(summary.loc[summary["kept"], "design"]) + current = [design for design in current if design.key in kept] + else: + summary["kept"] = True + summaries.append(summary.assign(stage=stage)) + return Screening( + results=results, + summary=summaries[-1], + designs=current, + criteria=criteria, + history=pd.concat(frames, ignore_index=True), + summaries=pd.concat(summaries, ignore_index=True), + ) diff --git a/src/tatc/tradespace/sensitivity.py b/src/tatc/tradespace/sensitivity.py new file mode 100644 index 0000000..282c58e --- /dev/null +++ b/src/tatc/tradespace/sensitivity.py @@ -0,0 +1,140 @@ +""" +Sensitivity of the metrics of designs to their design variables: which +decisions drive which outcomes, from the designs of a study (an enumeration, +or a sample such as a Latin hypercube). + +@author: Paul T. Grogan +""" + +from __future__ import annotations + +from collections.abc import Sequence + +import numpy as np +import pandas as pd + +from .tables import check_summary, names + + +def _levels(values: pd.Series, max_levels: int) -> pd.Series: + """ + Gets the levels of a variable: its values, or (for a numeric variable + with more than `max_levels` values) equal-count bins of them (intervals, + in order). + """ + if pd.api.types.is_numeric_dtype(values) and values.nunique() > max_levels: + return pd.qcut(values, max_levels, duplicates="drop") + return values + + +def main_effects( + summary: pd.DataFrame, variable: str, metric: str, *, max_levels: int = 10 +) -> pd.DataFrame: + """ + Computes the main effects of a design variable on a metric: the mean (and + standard deviation and count) of the metric over the designs at each + level of the variable, among the designs in which the variable is active + (not `NaN`, as a variable of a branch not chosen is). + + Args: + summary (pandas.DataFrame): The designs, a row each, with their + values (see `Design.flat`) and metrics (such as a summary of a + study, see `summarize`). + variable (str): The column of the variable. + metric (str): The column of the metric. + max_levels (int): The most levels of a numeric variable, beyond which + its values are grouped in bins of equal counts. + + Returns: + pandas.DataFrame: a row per level (in order, of the values or of the + bins of a numeric variable): the `mean`, `std`, and `count` of + the metric + """ + check_summary(summary) + active = summary.dropna(subset=[variable, metric]) + levels = _levels(active[variable], max_levels) + return active.groupby(levels, sort=True, observed=True)[metric].agg( + ["mean", "std", "count"] + ) + + +def sensitivity( + summary: pd.DataFrame, + variables: str | Sequence[str], + metrics: str | Sequence[str], + *, + max_levels: int = 10, + adjusted: bool = True, +) -> pd.DataFrame: + """ + Computes the sensitivity of metrics to design variables: for each + variable and metric, the share of the variance of the metric explained + by the levels of the variable (of a one-way analysis of variance), among + the designs in which the variable is active, and the share of the designs + in which it is (`active`). + + The share of explained variance of a sample (the correlation ratio, eta + squared) is biased upward: with `k` levels and `n` designs, a variable + that does not affect a metric explains `(k - 1) / (n - 1)` of its + variance on average, as the means of its levels differ by chance (0.47 + for 10 levels and 20 designs). The adjusted share (epsilon squared) + removes this bias: it subtracts the variance between levels that chance + explains (the variance within levels, times `k - 1`), and is near 0 for + such a variable (it is clipped at 0, and is `NaN` with no more designs + than levels). + + A share near 1 means that the variable alone determines the metric; a + share near 0, that the metric hardly depends on it. The shares of a full + factorial enumeration are first-order effects (the shares of different + variables do not add to 1 if variables interact); those of a sample + estimate them. The shares of variables that are active in different + designs (such as those of different branches of a choice) are of + different designs, and compare how much each matters where it applies. + + Args: + summary (pandas.DataFrame): The designs, a row each, with their + values (see `Design.flat`) and metrics (such as a summary of a + study, see `summarize`, which keeps the values of the designs). + variables (str | Sequence[str]): The column (or columns) of the + variables. + metrics (str | Sequence[str]): The column (or columns) of the metrics. + max_levels (int): The most levels of a numeric variable, beyond which + its values are grouped in bins of equal counts. + adjusted (bool): `True` for the adjusted shares, `False` for the + correlation ratios. + + Returns: + pandas.DataFrame: a row per variable: the share of each metric's + variance it explains, and the share of designs in which it is + `active`, sorted by the share of the first metric + """ + check_summary(summary) + variables, metrics = names(variables), names(metrics) + rows = [] + for variable in variables: + row: dict = {"variable": variable} + active = summary[variable].notna() + row["active"] = float(active.mean()) + for metric in metrics: + subset = summary[active & summary[metric].notna()] + values = subset[metric].astype(float) + total = float(((values - values.mean()) ** 2).sum()) + if len(subset) < 2 or total == 0: + row[metric] = np.nan + continue + levels = _levels(subset[variable], max_levels) + means = values.groupby(levels, observed=True).transform("mean") + between = float(((means - values.mean()) ** 2).sum()) + if not adjusted: + row[metric] = between / total + continue + k, n = int(pd.Series(levels).nunique()), len(subset) + if n <= k: + row[metric] = np.nan + continue + within = (total - between) / (n - k) + row[metric] = max((between - (k - 1) * within) / total, 0.0) + rows.append(row) + result = pd.DataFrame(rows).set_index("variable") + result = result[[*metrics, "active"]] + return result.sort_values(metrics[0], ascending=False) if metrics else result diff --git a/src/tatc/tradespace/simulation.py b/src/tatc/tradespace/simulation.py new file mode 100644 index 0000000..24042dc --- /dev/null +++ b/src/tatc/tradespace/simulation.py @@ -0,0 +1,468 @@ +""" +The discrete-event simulation of missions (see `Deployment.simulate`): the +deployment of a constellation with the failures of its satellites and +launches, the restoration of failed satellites by its policy, and the +decisions of the rules of its stages, into the history of the mission (see +`MissionHistory`); and the samplers of many histories of a replicate, +independent or stratified (see `Deployment.simulate_many`). + +@author: Paul T. Grogan +""" + +from __future__ import annotations + +import heapq +import itertools +import math +from collections.abc import Callable, Sequence +from dataclasses import dataclass, field, replace +from functools import partial +from typing import TYPE_CHECKING, Any + +import numpy as np + +from .events import Launch, _Manifest +from .failures import FailureModel +from .mission import Decision, Failure, MissionHistory, Restoration + +if TYPE_CHECKING: + from .deployment import Deployment + + +@dataclass +class _Slot: + """ + The state of a position of a plane: the generation of its satellite, + when it began to operate (or `None`), when it failed, and whether it + awaits restoration. + """ + + generation: int = -1 + up: float | None = None + down: float | None = None + pending: bool = False + + +@dataclass +class _Booking: + """A launch of restorations or spares, open to more until it flies.""" + + time: float + plane: int + kind: Any + items: list = field(default_factory=list) + order: int = 0 + + +class _Draws: + """ + The random numbers of the failures of a history: uniform numbers of each + draw (by its key), of a sampler of the histories of a replicate (such as + `_Sampler`) or from the seed of the history, from which the lives of + satellites and the failures of launches are drawn, stressed (with their + likelihood ratio) or not. + """ + + def __init__( + self, + seed: int | Sequence[int] | None, + uniforms: Callable[[tuple, int], np.ndarray] | None = None, + stress: float = 1.0, + launch_stress: float = 1.0, + ): + self.seed, self.stress, self.launch_stress = seed, stress, launch_stress + self.uniforms = self._from_seed if uniforms is None else uniforms + self.log_weight = 0.0 + + def _from_seed(self, key: tuple, dimensions: int) -> np.ndarray: + """The uniform numbers of a draw, from the seed and its key.""" + seed = list(self.seed) if isinstance(self.seed, Sequence) else [self.seed] + return np.random.default_rng([*seed, *key]).random(dimensions) + + @property + def weight(self) -> float: + """float: The likelihood ratio of the draws (1 without stress).""" + return math.exp(self.log_weight) + + def life(self, life: Any, key: tuple, remaining: float) -> float: + """ + Draws a life (years, infinite without a seed or a life), stressed + over the time remaining in the mission, if the draws are. + """ + if self.seed is None or life is None: + return math.inf + uniform = self.uniforms(key, life.dimensions) + if self.stress == 1.0: + return life.from_uniform(uniform) + value, log_ratio = life.stressed(uniform, self.stress, remaining) + self.log_weight += log_ratio + return value + + def launch_fails(self, probability: float, key: tuple) -> bool: + """Draws whether a launch fails (stressed, if the draws are).""" + if self.seed is None or probability == 0: + return False + uniform = self.uniforms(key, 1)[0] + if self.launch_stress == 1.0: + return bool(uniform < probability) + stressed = min(probability * self.launch_stress, 0.5) + failed = bool(uniform < stressed) + ratio = probability / stressed if failed else (1 - probability) / (1 - stressed) + self.log_weight += math.log(ratio) + return failed + + +class _Sampler: + """ + The uniform numbers of the failures of a history of a replicate, + stratified over the histories of the replicate (see + `Deployment.simulate_many`): a Latin hypercube in which, for each draw + (each life and launch), history `k` of `K` takes a uniform number in its + stratum of a permutation of the `K` strata of [0, 1). Each draw is keyed + by its key, so that the same draw of the same history of a replicate + takes the same number in every design (common random numbers). + """ + + def __init__(self, seed: int, index: int, histories: int): + self.seed, self.index, self.histories = seed, index, histories + + def __call__(self, key: tuple, dimensions: int) -> np.ndarray: + strata = np.random.default_rng([self.seed, 1, self.histories, *key]) + orders = [strata.permutation(self.histories) for _ in range(dimensions)] + jitter = np.random.default_rng([self.seed, 2, self.index, *key]) + offsets = jitter.random(dimensions) + return np.array( + [ + (order[self.index] + offset) / self.histories + for order, offset in zip(orders, offsets) + ] + ) + + +_SAMPLINGS = ("random", "stratified") +"""The samplings of the failures of histories (see `Deployment.simulate_many`).""" + + +def _check_sampling( + histories: int, sampling: str, stress: float, launch_stress: float | None = None +) -> None: + """ + Checks the sampling of histories (see `Deployment.simulate_many`), + raising a `ValueError` if the histories are fewer than 1, the sampling is + unknown, or a stress is not positive. + """ + if histories < 1: + raise ValueError("histories must be at least 1") + if sampling not in _SAMPLINGS: + raise ValueError(f"sampling must be one of {_SAMPLINGS}, not {sampling!r}") + if stress <= 0 or (launch_stress is not None and launch_stress <= 0): + raise ValueError("stress must be positive") + + +class _Simulation: + """ + A discrete-event simulation of a mission (see `Deployment.simulate`), + with the policy of its deployment. + """ + + # pylint: disable=too-many-instance-attributes + + def __init__( + self, + deployment: Deployment, + model: FailureModel, + seed: int | Sequence[int] | None, + uniforms: Callable[[tuple, int], np.ndarray] | None = None, + stress: float = 1.0, + launch_stress: float = 1.0, + ): + self.deployment, self.model = deployment, model + self.policy = deployment.policy + self.draws = _Draws(seed, uniforms, stress, launch_stress) + self.end = deployment.end + self.history = MissionHistory( + deployment, production=list(deployment.production) + ) + self.events: list = [] + self.counter = itertools.count() + self.slots = { + (plane, position): _Slot() + for plane, (_, built, _) in enumerate(deployment.planes) + for position in range(built) + } + self.spares = dict.fromkeys(range(len(deployment.planes)), 0) + self.spares_since: dict[int, float] = {} + self.ground: dict[Any, int] = {} + # the production lines and the launches booked, after the plan's + self.manifest = _Manifest.resume(deployment, self.history.production) + self.open: dict[int, list[_Booking]] = {} + self.launches_of_plane: dict[int, int] = {} + self.decided: dict[int, float] = {} + + # --- randomness + + def _life( + self, plane: int, position: int, generation: int, start: float = 0.0 + ) -> float: + life = self.model.life_of(self.deployment.planes[plane].kind) + key = (0, plane, position, generation) + return self.draws.life(life, key, self.end - start) + + def _launch_fails(self, *key: int) -> bool: + return self.draws.launch_fails(self.model.launch, (1, *key)) + + # --- events + + def _push(self, time: float, event: str, *payload: Any) -> None: + heapq.heappush(self.events, (time, next(self.counter), event, payload)) + + def run(self) -> MissionHistory: + """Runs the simulation, returning the history of the mission.""" + # pylint: disable=too-many-branches + for kind in self.deployment.development: + count = self.policy.ground_spares_of(kind) + if count > 0: + ready = self.manifest.produce(0.0, kind, count, "spare") + self.ground.setdefault(kind, 0) + self._push(ready, "stock", kind, count) + for launch in self.deployment.launches: + self._push(launch.time, "planned", launch) + for index, stage in enumerate(self.deployment.stages): + for time in stage.times: + self._push(self.deployment.begin + time, "decide", index) + steps = 0 + while self.events: + time, _, event, payload = heapq.heappop(self.events) + if time >= self.end: + break + steps += 1 + if steps > 1_000_000: + raise RuntimeError("the simulation does not progress") + getattr(self, f"_on_{event}")(time, *payload) + for (plane, position), slot in self.slots.items(): + if slot.up is not None: + self._close(plane, position, self.end) + for plane, since in self.spares_since.items(): + if self.spares[plane] > 0: + self.history.parked.append((since, self.end, self.spares[plane])) + self.history.weight = self.draws.weight + self.history.decided = [ + self.decided.get(index) for index in range(len(self.deployment.stages)) + ] + self.history.production.sort(key=lambda batch: batch.begin) + self.history.launches.sort(key=lambda launch: (launch.time, launch.plane)) + return self.history + + def _on_stock(self, time: float, kind: Any, count: int) -> None: + del time + self.ground[kind] = self.ground.get(kind, 0) + count + + def _on_planned(self, time: float, launch: Launch) -> None: + failed = self._launch_fails(0, launch.plane, launch.first, launch.generation) + self.history.launches.append(replace(launch, failed=failed)) + built = self.deployment.planes[launch.plane].satellites + positions = range(launch.first, launch.first + launch.satellites) + for position in positions: + if position >= built: + continue + slot = self.slots[launch.plane, position] + if launch.purpose == "deployment": + if failed: + self._fail(time, launch.plane, position, "launch") + else: + self._up(time, launch.plane, position) + elif not failed: + # a planned replacement takes the place of the satellite + if slot.up is not None: + self._close(launch.plane, position, time) + self._up(time, launch.plane, position) + # the spares in orbit of a deployment (planned replacements carry + # none: spares in orbit do not age) + spares = sum(position >= built for position in positions) + if spares and not failed: + self._park(time, launch.plane, spares) + + def _on_decide(self, time: float, index: int) -> None: + if index in self.decided: + return # deployed at an earlier decision + stage = self.deployment.stages[index] + if stage.rule is not None: + operating = [ + position for position, slot in self.slots.items() if slot.up is not None + ] + capability = self.deployment.capability + decision = Decision( + time, + index, + len(operating), + self.history, + tuple(sorted(self.decided)), + ( + None + if capability is None + # pylint: disable-next=protected-access + else partial(capability._at, self.deployment.planes, operating) + ), + ) + if not stage.rule(decision): + return + self.decided[index] = time + self._deploy(time, stage) + + def _on_fail(self, time: float, plane: int, position: int, generation: int) -> None: + slot = self.slots[plane, position] + if slot.generation != generation or slot.up is None: + return # a satellite replaced before it failed + self._close(plane, position, time) + self._fail(time, plane, position, "life") + + def _fail(self, time: float, plane: int, position: int, cause: str) -> None: + slot = self.slots[plane, position] + slot.down = time + self.history.failures.append(Failure(time, plane, position, cause)) + if self.policy.restore and not slot.pending: + slot.pending = True + self._push(time + self.policy.detection_years, "request", plane, position) + + def _on_request(self, time: float, plane: int, position: int) -> None: + slot = self.slots[plane, position] + if slot.up is not None: # restored by a planned replacement + slot.pending = False + return + kind = self.deployment.planes[plane].kind + if self.spares[plane] > 0: + self._park(time, plane, -1) + self._push( + time + self.policy.drift_years, "activate", plane, position, "orbit" + ) + if self.policy.replenish: + ready = self.manifest.produce( + time + self.policy.procurement_years, kind, 1, "spare" + ) + self._book(plane, kind, ready, ("spare",)) + elif self.ground.get(kind, 0) > 0: + self.ground[kind] -= 1 + self._book(plane, kind, time, ("slot", position, "ground")) + if self.policy.replenish: + ready = self.manifest.produce( + time + self.policy.procurement_years, kind, 1, "spare" + ) + self._push(ready, "stock", kind, 1) + else: + ready = self.manifest.produce( + time + self.policy.procurement_years, kind, 1, "restoration" + ) + self._book(plane, kind, ready, ("slot", position, "production")) + + def _on_activate(self, time: float, plane: int, position: int, source: str) -> None: + slot = self.slots[plane, position] + if slot.up is not None: + self._park(time, plane, 1) # not needed: back to waiting + return + self._restore(time, plane, position, source) + + def _on_booking(self, time: float, booking: _Booking) -> None: + self.open[booking.plane].remove(booking) + failed = self._launch_fails(1, booking.plane, booking.order) + spare = all(item[0] == "spare" for item in booking.items) + self.history.launches.append( + Launch( + time, + booking.plane, + booking.kind, + -1, + len(booking.items), + purpose="spare" if spare else "restoration", + failed=failed, + ) + ) + for item in booking.items: + if item[0] == "spare": + if not failed: + self._park(time, booking.plane, 1) + continue + _, position, source = item + slot = self.slots[booking.plane, position] + if failed: + slot.pending = False + self.history.failures.append( + Failure(time, booking.plane, position, "launch") + ) + if self.policy.restore: + slot.pending = True + self._push( + time + max(self.policy.detection_years, 1e-6), + "request", + booking.plane, + position, + ) + elif slot.up is not None: + self._park(time, booking.plane, 1) # not needed: a spare in orbit + else: + self._restore(time, booking.plane, position, source) + + # --- actions + + def _up(self, time: float, plane: int, position: int) -> None: + slot = self.slots[plane, position] + slot.generation += 1 + slot.up, slot.pending = time, False + life = self._life(plane, position, slot.generation, time) + if time + life < self.end: + self._push(time + life, "fail", plane, position, slot.generation) + + def _close(self, plane: int, position: int, time: float) -> None: + slot = self.slots[plane, position] + if time > slot.up: + self.history.operating.setdefault((plane, position), []).append( + (slot.up, time) + ) + slot.up = None + + def _restore(self, time: float, plane: int, position: int, source: str) -> None: + slot = self.slots[plane, position] + self.history.restorations.append( + Restoration(plane, position, slot.down, time, source) + ) + self._up(time, plane, position) + + def _park(self, time: float, plane: int, change: int) -> None: + if change == 0: + return + if self.spares[plane] > 0: + since = self.spares_since[plane] + if time > since: + self.history.parked.append((since, time, self.spares[plane])) + self.spares[plane] += change + self.spares_since[plane] = time + + def _deploy(self, time: float, stage: Any) -> None: + """ + Deploys the planes of a stage, as a plan deploys the others (see + `DeploymentSchedule.plan`): produced after its lead time (on their + type's line), launched at the next launch slots, and replaced at the + end of their design life. + """ + start = time + stage.lead_years + for launch in self.manifest.deploy(stage.planes, start, self.end): + self._push(launch.time, "planned", launch) + + def _book(self, plane: int, kind: Any, ready: float, item: tuple) -> None: + """ + Books an item that is ready at a time on a launch of a plane: an open + one that has room and flies once the item is ready, but no later + than a new one would (at the next launch slot after waiting the + batch years), or else a new one. + """ + latest = self.manifest.next_slot(ready + self.policy.batch_years) + capacity = self.manifest.capacity(plane) + for booking in self.open.get(plane, []): + if ready <= booking.time <= latest and len(booking.items) < capacity: + booking.items.append(item) + return + time = self.manifest.slot(ready + self.policy.batch_years) + order = self.launches_of_plane.get(plane, 0) + self.launches_of_plane[plane] = order + 1 + booking = _Booking(time, plane, kind, [item], order) + self.open.setdefault(plane, []).append(booking) + self._push(time, "booking", booking) diff --git a/src/tatc/tradespace/space.py b/src/tatc/tradespace/space.py new file mode 100644 index 0000000..2161dcf --- /dev/null +++ b/src/tatc/tradespace/space.py @@ -0,0 +1,909 @@ +""" +Design spaces: declarative trees of design variables from which designs +(architectures) are enumerated or sampled for trade studies. + +A design space is a tree of nodes. Its leaves are design variables +(`Real`, `Integer`, `Categorical`), fixed values, values derived from other +values (`Derived`), and uncertain (nuisance) parameters (`Uncertain`), which +are drawn for each replicate of a design rather than searched. Its branches +group nodes (`DesignSpace`), choose one of several alternatives (`Choice`), +or repeat a node a variable number of times (`Repeat`), which makes the +space hierarchical: for example, a constellation of a variable number of +orbit planes, each with its own design. + +Nodes are decided in the order they are declared. A callable (a bound of a +variable, a derived value, or a constraint) is given a view of the values +decided so far, in which names resolve to the innermost enclosing group +that declares them (as in lexically scoped code), and `index` gives the +position of the innermost enclosing repeated item. + +@author: Paul T. Grogan +""" + +from __future__ import annotations + +import numbers +import zlib +from collections.abc import Callable, Iterable, Iterator, Mapping, Sequence +from functools import partial +from typing import Any + +import numpy as np +import pandas as pd + +from .hashing import canonical, digest +from .nodes import ( + Choice, + Fixed, + Group, + Infeasible, + Uncertain, + _as_node, +) +from .values import Scope, Values, generic_path +from .walks import ( + _ABSENT, + _Context, + _decided, + _flatten, + _leaf_paths, + _level_of, + _node_at, + _Odometer, + _walk, +) +from .walks import _unit_paths as _paths_of_units + +STATUS_COLUMNS = ("design", "replicate", "scenario", "feasible", "error", "seconds") +"""tuple[str, ...]: The columns of the results of a study (see `Study.run`) +that are neither values of designs nor metrics, in their order: the key of +the design, the replicate, the name of the scenario (of a study with +scenarios only), whether the evaluation is feasible (and its error if not), +and the seconds it took to build and evaluate the design. Neither metrics +nor the children of design spaces may be named as them.""" + +RESERVED_NAMES = frozenset( + { + # names that the views of values give otherwise (see `Values`) + "index", + "count", + "choice", + "get", + "items", + "keys", + "values", + # attributes of designs (see `Design`) + "decisions", + "flat", + "key", + "realize", + "replicate", + "scenario", + "space", + "uncertain_values", + # columns of the results of a study + *STATUS_COLUMNS, + } +) +"""frozenset[str]: The names that the children of a design space may not +have: those that designs and the views of their values give otherwise (as +attributes, such as `key`, `items`, or `index`), and the columns of the +results of a study that are not values of designs (see `STATUS_COLUMNS`).""" + + +# --------------------------------------------------------------------------- +# designs and design spaces +# --------------------------------------------------------------------------- + + +class Design: + """ + A design: one decision of every active design variable of a design + space. Its values are given as attributes (or keys), as for the views of + the callables of the design space, and are those of a replicate (with + drawn uncertain parameters) if the design is realized (see `realize`). + """ + + def __init__( + self, + space: DesignSpace, + decisions: dict, + values: dict, + replicate: int | None = None, + scenario: str | None = None, + ): + # pylint: disable=too-many-arguments,too-many-positional-arguments + self.space, self.replicate = space, replicate + self.decisions = decisions + """dict: The decisions of the design, as the design space declares + them: those of a group are a mapping of the decisions of its + children, by name (omitting those without decisions: fixed, + derived, and uncertain values); that of a design variable is its + value; that of a choice is a list of the name of its branch and the + decisions of the branch (`None` if it has none), such as + `["walker", {"planes": 3}]`; and that of a repetition is a list of + the decisions of its items (`None` for an item without decisions), + as many as its count, whose unordered items are in the order of the + levels of their decisions (see `Repeat`).""" + self._values = values + self._scenario = scenario + self.key = digest(canonical(decisions), 12) + """str: An identifier of the design, from its decisions only (not + from its derived values or uncertain parameters).""" + + @property + def scenario(self) -> str | None: + """str | None: The name of the scenario in which the design is + realized (see `realize`), or `None` if it is not realized in one.""" + return self._scenario + + @property + def values(self) -> Values: + """Values: the values of the design.""" + return Values(self._values) + + def __getattr__(self, name: str) -> Any: + if name.startswith("_"): + raise AttributeError(name) + try: + return getattr(self.values, name) + except AttributeError as error: + raise AttributeError( + f"the design has {error}", name=name, obj=self + ) from None + + def __dir__(self) -> list[str]: + # the values, for completion (and suggestions of misspelled names) + return sorted({*object.__dir__(self), *self._values}) + + def __getitem__(self, name: str) -> Any: + return self.values[name] + + def __contains__(self, name: object) -> bool: + return name in self.values + + __iter__ = None # type: ignore[assignment] + + def __eq__(self, other: object) -> bool: + return ( + isinstance(other, Design) + and self.key == other.key + and self.replicate == other.replicate + and self._scenario == other._scenario + ) + + def __hash__(self) -> int: + return hash((self.key, self.replicate, self._scenario)) + + def __fingerprint__(self) -> dict: + """ + Gets what identifies the design in a definition (see + `tatc.tradespace.fingerprint`), such as of a design that a function + of a study refers to: its design space, its decisions, and its + replicate and scenario (if it is realized). + + Returns: + dict: the design space, decisions, replicate, and scenario + """ + return { + "space": self.space, + "decisions": self.decisions, + "replicate": self.replicate, + "scenario": self._scenario, + } + + def flat(self) -> dict[str, Any]: + """ + Gets the values of the design by path, as for the columns of a + table: `a.b` for the value `b` of group `a`, `c` for the chosen + branch of choice `c` (and `c..d` for its values), `e.count` + for the count of repetition `e` (and `e[k].f` for the values of its + items). Fixed values are omitted. + + Returns: + dict: the values by path + """ + out: dict = {} + _flatten(self.space, self._values, "", out) + return out + + def uncertain_values(self) -> dict[str, Any]: + """ + Gets the values of the uncertain parameters of the design (see + `Uncertain`) by path (as of `flat`), in the order they are drawn: + those of the branches that it chooses and of the items of its + repetitions, as drawn in its replicate (or given by its scenario) if + it is realized (see `realize`), and their nominal values otherwise. + Their paths with `[*]` for the indices of items (see + `generic_path`) are those of `DesignSpace.uncertain_paths`:: + + design.realize(3).uncertain_values() # {"planes[0].phase": 41.2, ...} + + Returns: + dict[str, Any]: the values, by path + """ + paths = set(self.space.uncertain_paths()) + return { + path: value + for path, value in self.flat().items() + if generic_path(path) in paths + } + + def realize( + self, + replicate: int, + *, + seed: int = 0, + common_random_numbers: bool = True, + shift: Mapping[str, int] | None = None, + overrides: Mapping[str, Any] | None = None, + scenario: str | None = None, + ) -> Design: + """ + Realizes a replicate of the design: draws its uncertain parameters + (and computes the values derived from them). + + Each uncertain parameter is drawn from a random number generator + seeded by `seed`, `replicate`, and its path, so that with common + random numbers, a parameter at the same path (such as the phase of + the first orbit plane) takes the same value in the same replicate + of every design. Comparisons between designs then measure the + differences between the designs rather than between their draws, + which needs fewer replicates to rank them. Otherwise, the generator + is also seeded by the design's key, so that draws are independent + between designs. + + A `shift` draws some parameters as in other replicates: a parameter + named in it (by its path, with `[*]` for the index of any item of a + repetition, see `DesignSpace.uncertain_paths`) is drawn as in + replicate `replicate + shift[name]`, and the others as in + `replicate`. Such a mixed replicate differs from `replicate` in the + named parameters only, which measures their effects on the outcomes + of a design (see `attribute_variance`). + + The `overrides` of a scenario give fixed values and uncertain + parameters other values (by their paths, with `[*]` for the index of + any item of a repetition, as of `DesignSpace.uncertain_paths`): a + condition under which designs are compared, such as a requirement, + rather than averaged over (see `Study`). Values derived from them are + derived from the overrides, an uncertain parameter that they give is + not drawn, and the constraints of the design space are checked + again, as the overrides may change what they depend on. The realized + design is of the scenario named `scenario` (see `Design.scenario`). + + Args: + replicate (int): The replicate (a non-negative integer). + seed (int): The seed of the trade study (a non-negative integer). + common_random_numbers (bool): `True` to use common random numbers + between designs. + shift (Mapping[str, int] | None): The offsets of the replicates + as in which the named uncertain parameters are drawn (each a + non-negative integer), if any. + overrides (Mapping[str, Any] | None): The values of fixed values + and uncertain parameters in a scenario (by path), if any. + scenario (str | None): The name of the scenario of the overrides, + if any. + + Returns: + Design: the realized design + + Raises: + Infeasible: if the design violates a constraint with the + overrides. + ValueError: if `replicate`, `seed`, or an offset of `shift` is + not a non-negative integer, `shift` names a path that is not + of an uncertain parameter of the design space, or + `overrides` one that is not of a fixed value or an uncertain + parameter. + """ + # pylint: disable=too-many-arguments + _check_seed(seed) + replicate = _check_replicate(replicate) + shift = _check_shift(shift) + self.space._check_uncertain(shift) # pylint: disable=protected-access + overrides = dict(overrides or {}) + self.space._check_overrides(overrides) # pylint: disable=protected-access + tail = [] if common_random_numbers else [int(self.key, 16)] + + def draw(path: str, node: Uncertain) -> Any: + name = generic_path(path) + if name in overrides: + return overrides[name] + drawn_in = replicate + shift.get(name, 0) + rng = np.random.default_rng( + [seed, drawn_in, *tail, zlib.crc32(path.encode())] + ) + return node.sampler(rng) + + def fix(path: str, node: Fixed) -> Any: + return overrides.get(generic_path(path), node.value) + + ctx = _Context( + draw=draw, + check=bool(overrides), + fix=fix if overrides else None, + canonical=True, + ) + values, _ = _walk(self.space, "", Scope(), ctx, self.decisions) + return Design(self.space, self.decisions, values, replicate, scenario) + + def __repr__(self) -> str: + replicate = "" if self.replicate is None else f", replicate={self.replicate}" + scenario = "" if self._scenario is None else f", scenario={self._scenario!r}" + return f"Design({self.key}{replicate}{scenario}: {self.flat()})" + + +def _check_index(value: Any, what: str) -> int: + """ + Checks that a value that seeds uncertain parameters (a seed, a replicate, + or the offset of a shift) is a non-negative integer, as numpy's + generators require, raising a `ValueError` if not (naming it `what`), + and returns it as a Python integer. + """ + if ( + isinstance(value, (bool, np.bool_)) + or not isinstance(value, numbers.Integral) + or value < 0 + ): + raise ValueError(f"{what} must be a non-negative integer, not {value!r}") + return int(value) + + +def _check_seed(seed: Any) -> None: + """ + Checks that a seed of uncertain parameters is a non-negative integer (see + `_check_index`). + """ + _check_index(seed, "the seed") + + +def _check_replicate(replicate: Any) -> int: + """ + Checks that a replicate is a non-negative integer (see `_check_index`), + returning it. + """ + return _check_index(replicate, "a replicate") + + +def _check_shift(shift: Mapping[str, Any] | None) -> dict[str, int]: + """ + Checks that the offsets of a shift (see `Design.realize`) are + non-negative integers (see `_check_index`), returning them. + """ + return { + name: _check_index(offset, f"the offset of {name!r} in a shift") + for name, offset in (shift or {}).items() + } + + +def _as_constraints(constraints: Any) -> list[Callable[[Scope], Any]]: + """ + Gets the constraints of a design space given as a constraint or a + sequence of them, raising a `TypeError` if one is not callable. + """ + found = [constraints] if callable(constraints) else list(constraints) + for constraint in found: + if not callable(constraint): + raise TypeError(f"a constraint is a callable, not {constraint!r}") + return found + + +def _lhs_column(n: int, rng: np.random.Generator) -> np.ndarray: + """ + Gets `n` values in [0, 1) stratified in `n` equal intervals in random + order (a column of a Latin hypercube sample). + """ + return (rng.permutation(n) + rng.random(n)) / n + + +class DesignSpace(Group): + """ + A group of nodes: the root of a design space, or a group within it (such + as the design of each orbit plane). Children are given by name, in the + order they are decided; plain values are fixed values. Children may not + be named as the attributes of designs and of the views of their values + (such as `key`, `items`, or `index`), nor as the columns of the results + of a study that are not values of designs (see `STATUS_COLUMNS`): see + `RESERVED_NAMES`. + + Constraints are callables of the group's values (and those of enclosing + groups), checked once the group's values are decided, that return + whether a design satisfies them (`True` or `False`) or by how much it + violates them: a number that is not positive if it satisfies them, and + otherwise the amount of violation (for example, `lambda d: d.satellites - + 12` for at most 12 satellites), which guides constraint-aware optimizers + toward feasible designs (see `optimize_optuna` and `make_pymoo_problem`). + They must not depend on uncertain parameters. + + Args: + constraints (Callable | Sequence[Callable]): A constraint, or the + constraints. + **children (Any): The nodes, by name. + """ + + def __init__( + self, + constraints: Callable[[Scope], Any] | Sequence[Callable[[Scope], Any]] = (), + **children: Any, + ): + reserved = RESERVED_NAMES.intersection(children) + if reserved: + raise ValueError( + f"children may not be named {sorted(reserved)}: designs and the " + + "views of their values give these names otherwise (as attributes, " + + "such as `key` and `items`), as do the results of a study (as " + + f"columns); the reserved names are {sorted(RESERVED_NAMES)}" + ) + self.children = {name: _as_node(node) for name, node in children.items()} + self.constraints = _as_constraints(constraints) + + def __repr__(self) -> str: + return f"DesignSpace({', '.join(self.children)})" + + def _design(self, ctx: _Context, prescribed: Any = _ABSENT) -> Design: + """ + Decides a design (with nominal uncertain parameters), following the + prescribed decisions, if any. + """ + values, decisions = _walk(self, "", Scope(), ctx, prescribed) + return Design(self, decisions, values) + + def design( + self, decisions: Mapping | Design | None = None, /, **overrides: Any + ) -> Design: + """ + Gets the design of given decisions (see `Design.decisions` for their + shapes), or of the decisions of another design (such as of a design + space this one extends, see `extend`), with the decisions of some + children replaced (by name: a value, the decisions of a group or a + choice, or a design of their own space), checking its constraints:: + + space = base.extend(policy=policy_space(orbit_spares=Integer(0, 1))) + design = space.design(base_design, policy=policy_design) + sso = space.design(base_design, layout="sso") + + A choice may also be given the name of its branch alone, here and in + the decisions: the branch's decisions are then those given (of a + replaced child that chose the same branch) or, otherwise, the first + levels of its variables (and the lower bounds of continuous ones). + + Args: + decisions (Mapping | Design | None): The decisions, or a design + whose decisions to take. + **overrides (Any): The decisions of children, by name. + + Returns: + Design: the design + + Raises: + Infeasible: if the design violates a constraint. + ValueError: if an override names no child of the design space, + the decisions of a group name others than its children, or a + decision is not a value of its variable's domain. + """ + if isinstance(decisions, Design): + decisions = decisions.decisions + merged = dict(decisions or {}) + unknown = sorted(set(overrides) - set(self.children)) + if unknown: + raise ValueError(f"no children {unknown} of the design space") + for name, decision in overrides.items(): + if isinstance(decision, Design): + decision = decision.decisions + given = merged.get(name) + if ( + isinstance(self.children[name], Choice) + and isinstance(decision, str) + and isinstance(given, (list, tuple)) + and len(given) == 2 + and given[0] == decision + ): + continue # the branch, with the decisions given of it + merged[name] = decision + values, merged = _walk(self, "", Scope(), _Context(normalize=_level_of), merged) + return Design(self, merged, values) + + def extend( + self, + constraints: Callable[[Scope], Any] | Sequence[Callable[[Scope], Any]] = (), + **children: Any, + ) -> DesignSpace: + """ + Gets a design space with other children: those named as children of + this one replace them (in their place), and others are added after + them, with this one's constraints and others. This one is unchanged:: + + policy_trade = space.extend(policy=policy_space(orbit_spares=Integer(0, 1))) + year = space.extend(epoch=Uncertain(draw_epoch)) + + Designs of this design space are designs of the other with the + decisions of its new children (see `design`). + + Args: + constraints (Callable | Sequence[Callable]): Another constraint, + or other constraints. + **children (Any): The nodes, by name. + + Returns: + DesignSpace: the design space + """ + return DesignSpace( + [*self.constraints, *_as_constraints(constraints)], + **{**self.children, **children}, + ) + + def designs_of( + self, frame: pd.DataFrame, *, keys: Iterable[str] | None = None + ) -> pd.Series: + """ + Rebuilds designs from the rows of a data frame of their values by path + (see `Design.flat`): the results of a study (see `Study.run`), or a + summary that keeps the values of the designs (see `summarize`). The + designs are those of the rows, aligned with them (with the frame's + index), so that functions of designs map over the rows, or those of + `keys` (indexed by them). Each design is rebuilt once, from the first + row of its key (`design`, a column or the name of the index), whose + key it must have, if the frame has keys:: + + front = space.designs_of(summary[summary.pareto]) + realized = [study.realize(design) for design in front] + + Args: + frame (pandas.DataFrame): The rows. + keys (Iterable[str] | None): The keys of the designs to rebuild, + or `None` for the design of each row of the frame. + + Returns: + pandas.Series: the designs, by row (with the frame's index) or by + key (of `keys`, each once) + + Raises: + KeyError: if the frame has no rows of a key. + ValueError: if the frame lacks the value of a decision of a + design, or its values give a design of another key. + """ + rows = frame + if "design" not in rows.columns and rows.index.name == "design": + rows = rows.reset_index() + if "design" not in rows.columns: + if keys is not None: + raise ValueError("the frame has no keys of designs (`design`)") + designs = [self._rebuilt(record) for record in rows.to_dict("records")] + return pd.Series(designs, index=frame.index, name="design", dtype=object) + first = rows.drop_duplicates("design") + records = dict(zip(first["design"], first.to_dict("records"))) + wanted = list(rows["design"]) if keys is None else list(dict.fromkeys(keys)) + missing = [key for key in dict.fromkeys(wanted) if key not in records] + if missing: + raise KeyError(f"no rows of designs {missing[:5]}") + rebuilt = { + key: self._rebuilt(records[key], key) for key in dict.fromkeys(wanted) + } + designs = [rebuilt[key] for key in wanted] + index = frame.index if keys is None else pd.Index(wanted, name="design") + return pd.Series(designs, index=index, name="design", dtype=object) + + def _rebuilt(self, record: Mapping[str, Any], key: str | None = None) -> Design: + """ + Rebuilds a design from its values by path (see `designs_of`), which + must give its key, if given. + """ + design = self._design(_Context(choose=partial(_decided, record))) + if key is not None and design.key != key: + raise ValueError( + f"the values of design {key} give another design ({design.key}): " + + "are they of another design space?" + ) + return design + + def enumerate(self, designs: Iterable[Design] | None = None) -> list[Design]: + """ + Enumerates every feasible design (a full factorial design over the + levels of the design variables, including those that exist only in + some designs), without duplicates, or every feasible design that + extends given designs: designs of a design space that this one + extends (see `extend`), each with every combination of the levels of + the decisions it lacks, such as each policy for each of the efficient + designs of the space without policies:: + + failure_space = cost_space.extend(policy=POLICY) + with_policies = failure_space.enumerate(cost_space.designs_of(efficient)) + + Args: + designs (Iterable[Design] | None): The designs to extend, or + `None` for every design. + + Returns: + list[Design]: the designs, in the order of their decisions (and of + the given designs) + + Raises: + ValueError: if a design variable is continuous, or the decisions + of a given design are not those of a design of this design + space (see `design`). + """ + if designs is None: + return list(self._iterate()) + found: dict[str, Design] = {} + for given in designs: + if not isinstance(given, Design): + raise TypeError(f"designs to extend, not {given!r}") + for design in self._iterate(given.decisions): + found.setdefault(design.key, design) + return list(found.values()) + + def _iterate(self, prescribed: Any = _ABSENT) -> Iterator[Design]: + """ + Iterates over every feasible design (see `enumerate`), or every one + with the prescribed decisions (of some of its nodes). The items of + unordered repetitions are walked in only one of their orders, so that + their permutations are not walked. + """ + odometer = _Odometer() + ctx = _Context( + choose=odometer.choose, + odometer=odometer, + normalize=None if prescribed is _ABSENT else _level_of, + ) + keys: set[str] = set() + while True: + try: + design = self._design(ctx, prescribed) + if design.key not in keys: + keys.add(design.key) + yield design + except Infeasible: + pass + if not odometer.advance(): + return + + def size(self) -> int: + """ + Counts the feasible designs (see `enumerate`), without keeping them. + + Returns: + int: the number of designs + """ + return sum(1 for _ in self._iterate()) + + def sample( + self, + n: int, + *, + method: str = "lhs", + seed: int = 0, + max_tries: int = 1000, + ) -> list[Design]: + """ + Samples feasible designs, which may repeat. + + With `method="lhs"`, each design variable (identified by its path, + including those that exist only in some designs) is sampled in a + Latin hypercube: its range is divided into `n` equal parts and each + design samples a different part. A design that is infeasible is + drawn again at random, which disturbs the stratification. With + `method="random"`, every variable is sampled independently. + + Args: + n (int): The number of designs. + method (str): `"lhs"` (Latin hypercube) or `"random"`. + seed (int): The seed of the random number generator. + max_tries (int): The number of draws of a design before giving up. + + Returns: + list[Design]: the designs + + Raises: + Infeasible: if no feasible design is drawn in `max_tries`. + """ + if method not in ("lhs", "random"): + raise ValueError(f"method must be 'lhs' or 'random', not {method!r}") + rng = np.random.default_rng(seed) + columns: dict[str, np.ndarray] = {} + designs = [] + for i in range(n): + for attempt in range(max_tries): + stratified = method == "lhs" and attempt == 0 + + def unit(path: str, i: int = i, stratified: bool = stratified) -> float: + if not stratified: + return float(rng.random()) + if path not in columns: + columns[path] = _lhs_column(n, rng) + return float(columns[path][i]) + + ctx = _Context( + choose=lambda path, domain, unit=unit: domain.from_unit(unit(path)) + ) + try: + designs.append(self._design(ctx)) + break + except Infeasible: + continue + else: + raise Infeasible(f"no feasible design in {max_tries} draws") + return designs + + def uncertain_paths(self) -> list[str]: + """ + Gets the paths of the uncertain parameters of the design space (see + `Uncertain`), in the order they are drawn, with `[*]` for the index + of any item of a repetition (so that the phases of every plane of a + constellation are one path, such as `planes[*].phase`), and with + the branches of choices (such as `layout.walker.phase_fraction`), + whether a design chooses them or not. These name the parameters of a + shift (see `Design.realize`) and the overrides of a scenario (see + `Study`). + + Returns: + list[str]: the paths + """ + return _leaf_paths(self, "", Uncertain) + + def _check_uncertain(self, paths: Iterable[str]) -> None: + """ + Checks that paths are of uncertain parameters of the design space (as + of `uncertain_paths`, with `[*]` for the index of any item of a + repetition), such as those of a shift (see `Design.realize`), raising + a `ValueError` if one is not. + """ + unknown = [p for p in paths if not isinstance(_node_at(self, p), Uncertain)] + if unknown: + raise ValueError( + "not uncertain parameters of the design space: " + + f"{sorted(unknown, key=str)} (it has {self.uncertain_paths()})" + ) + + def _check_overrides(self, overrides: Iterable[str]) -> None: + """ + Checks that the paths of the overrides of a scenario (a mapping by + path, or the paths, see `Design.realize`) are of fixed values or + uncertain parameters of the design space (with `[*]` for the index of + any item of a repetition), raising a `ValueError` if one is not. + """ + unknown = [ + p + for p in overrides + if not isinstance(_node_at(self, p), (Fixed, Uncertain)) + ] + if unknown: + known = [*_leaf_paths(self, "", Fixed), *self.uncertain_paths()] + raise ValueError( + "not fixed values or uncertain parameters of the design space: " + + f"{sorted(unknown, key=str)} (it has {known})" + ) + + def _unit_paths(self) -> list[str]: + """ + Gets the paths of every decision of the design space, in the order + they are decided: its design variables, its choices, and the counts + of its repetitions, with the items of each repetition up to its + largest count. These are the dimensions of the unit hypercube that + encodes its designs for optimizers of fixed numbers of continuous + variables (see `_decode` and `make_pymoo_problem`), raising a + `ValueError` if the count of a repetition has an upper bound that is + not fixed. + """ + return _paths_of_units(self, "") + + def _decode(self, unit: Sequence[float]) -> Design: + """ + Decodes a design from a point of the unit hypercube (a value in + [0, 1] for each of `_unit_paths`): each decision maps the value of + its path to a level (each level spans an equal part of [0, 1]) or to + a point of its interval. Values of the paths of inactive nodes (such + as the branches not chosen) are ignored. Raises `Infeasible` if the + design violates a constraint. + """ + index = {path: i for i, path in enumerate(self._unit_paths())} + if len(unit) != len(index): + raise ValueError(f"expected {len(index)} values, not {len(unit)}") + return self._design( + _Context(choose=lambda path, domain: domain.from_unit(unit[index[path]])) + ) + + def _suggest(self, trial: Any) -> Design: + """ + Decides a design with an Optuna trial (define-by-run, see + `optimize_optuna`): each decision is suggested by the trial, named by + its path, with the kind of its variable (`suggest_float`, with the + step of a discrete `Real`; `suggest_int`; or `suggest_categorical`, + also for choices), so that Optuna's samplers search the hierarchical + design space directly. Raises `Infeasible` if the design violates a + constraint. + """ + return self._design( + _Context(choose=lambda path, domain: domain.suggest(trial, path)) + ) + + +def _design_items(designs: Iterable[Design | str] | pd.DataFrame) -> list[Design | str]: + """ + Gets designs given as designs, keys, or a data frame of designs (with + their keys, `design`, as a column or the name of the index), in order. + """ + if isinstance(designs, pd.DataFrame): + if "design" in designs.columns: + items = list(designs["design"]) + elif designs.index.name == "design": + items = list(designs.index) + else: + raise ValueError("the data frame has no keys of designs (`design`)") + else: + items = list(designs) + for item in items: + if not isinstance(item, (Design, str)): + raise TypeError(f"a design or the key of one, not {item!r}") + return items + + +def _keys_of(designs: Iterable[Design | str] | pd.DataFrame) -> list[str]: + """ + Gets the keys of designs given as designs, keys, or a data frame of them + (with keys `design`, a column or the name of the index), each once. + """ + keys = [d.key if isinstance(d, Design) else d for d in _design_items(designs)] + return list(dict.fromkeys(keys)) + + +def _in_space(space: DesignSpace, design: Design) -> Design: + """ + Gets the design of a design space of the decisions of a design of + another (see `DesignSpace.design`), raising a `ValueError` if they are + not decisions of the design space. + """ + try: + return space.design(design) + except ValueError as error: + raise ValueError( + f"design {design.key} is of another design space, whose decisions are " + + f"not those of a design of this one: {error}" + ) from error + + +def _designs( + space: DesignSpace, + designs: Iterable[Design | str] | pd.DataFrame, + *frames: pd.DataFrame, +) -> list[Design]: + """ + Gets designs of a design space given as designs, keys, or a data frame + of designs (with their keys, `design`), each once, in order: designs of + other design spaces (such as of a design space that this one extends) + are the designs of this one of their decisions (see + `DesignSpace.design`), and designs given by their keys are rebuilt from + the values of the frame (if it has them) or of other frames (such as the + results of a study, see `DesignSpace.designs_of`). + """ + if isinstance(designs, pd.DataFrame): + frames = (designs, *frames) + found: dict[str, Design | None] = {} + for item in _design_items(designs): + if isinstance(item, Design): + design = item if item.space is space else _in_space(space, item) + found[design.key] = design + else: + found.setdefault(item, None) + error: ValueError | None = None + for frame in frames: + missing = [key for key, design in found.items() if design is None] + if not missing: + break + rows = frame.reset_index() if "design" not in frame else frame + if "design" not in rows: + continue + keys = set(rows["design"]) + present = [key for key in missing if key in keys] + try: + for design in space.designs_of(rows, keys=present): + found[design.key] = design + except ValueError as failure: + error = failure # the frame lacks values of the designs: try the next + missing = [key for key, design in found.items() if design is None] + if missing: + raise ValueError( + f"the values of designs {missing[:5]} are not given: give the designs, " + + "or their keys with the results of a study (or a summary that keeps " + + "the values of designs, see summarize)" + ) from error + return [design for design in found.values() if design is not None] diff --git a/src/tatc/tradespace/statistics.py b/src/tatc/tradespace/statistics.py new file mode 100644 index 0000000..e211452 --- /dev/null +++ b/src/tatc/tradespace/statistics.py @@ -0,0 +1,341 @@ +""" +Statistics of the metrics of designs over their replicates: such as a mean, +a standard deviation, a quantile, or the probability of meeting a threshold. + +The outcomes of a design are uncertain if its replicates differ (see +`Uncertain`), and a statistic over the replicates states how a design is +judged (see `Criteria`): by its mean, by a pessimistic quantile, or by how +reliably it meets a threshold. + +@author: Paul T. Grogan +""" + +from __future__ import annotations + +import operator as op +from collections.abc import Mapping +from typing import Any + +import numpy as np + +_OPERATORS = {">=": op.ge, ">": op.gt, "<=": op.le, "<": op.lt} + + +def _is_derived(metric: Any) -> bool: + """ + Whether a metric is computed from others in each replicate (such as a + `Utility`): an object with the `columns` it needs and an `evaluate` + method of their values. + """ + return ( + not isinstance(metric, (str, Statistic)) + and hasattr(metric, "columns") + and callable(getattr(metric, "evaluate", None)) + ) + + +def _as_statistic(name: str, value: Any) -> Statistic: + """ + Gets a statistic given by name: a statistic, or the mean of a metric + given as a string or a metric computed from others (such as a + `Utility`). + """ + if isinstance(value, str) or _is_derived(value): + return Mean(value) + if not isinstance(value, Statistic): + raise TypeError(f"statistic {name!r} is not a Statistic") + return value + + +def _named_statistics(statistics: Any) -> dict[str, Statistic]: + """ + Gets statistics by name: of a mapping of names to statistics (or metrics, + whose means they are), or of a sequence of statistics (or metrics), named + by their conventional names (see `Statistic.name`). + """ + if statistics is None: + return {} + if isinstance(statistics, Mapping): + return {name: _as_statistic(name, value) for name, value in statistics.items()} + if isinstance(statistics, (str, Statistic)) or _is_derived(statistics): + raise TypeError( + "statistics must be a sequence of statistics (or metrics) or a mapping " + + f"of names to them, not {statistics!r}: give [{statistics!r}]" + ) + named: dict[str, Statistic] = {} + for item in statistics: + statistic = _as_statistic(str(item), item) + if statistic.name in named and named[statistic.name] != statistic: + raise ValueError(f"statistics of the same name: {statistic.name!r}") + named[statistic.name] = statistic + return named + + +class Statistic: + """ + Base class of statistics of a metric over the replicates of each design: + a column of the results of a study, or a metric computed from others in + each replicate (such as a `Utility`, whose mean is the expected utility). + + The column `feasible` of the results is the feasibility of each replicate + (1 if it is feasible, 0 if not), whose statistics are over every + replicate of a design, feasible or not (its mean is the share of its + replicates that are feasible, see `summarize`); the statistics of other + metrics are over the feasible replicates. + + Args: + column (str | Utility): The metric. + """ + + def __init__(self, column: Any): + self.column = column + + @property + def metric(self) -> str: + """str: The name of the statistic's metric: its column, or `"utility"` + of a metric computed from others.""" + return "utility" if _is_derived(self.column) else str(self.column) + + @property + def name(self) -> str: + """str: The conventional name of the statistic, by which criteria name + the statistics given without names: such as `cost` (a mean), `cost + std`, `cost min`, `cost max`, `cost p70` (a quantile), or `P(cost <= + 150)`. The statistics within a + replicate over the histories of a mission (see `summarize_histories`) + are named apart from these, as ` histories p10`, ` + histories std`, and `P() histories`, and a statistic + other than the mean of a metric must not have the name of a column of + the results (see `summarize`).""" + return self.metric + + @property + def columns(self) -> tuple[str, ...]: + """tuple[str, ...]: The columns of the results that the statistic + needs: its metric, or those its metric is computed from.""" + if _is_derived(self.column): + return tuple(self.column.columns) + return (self.column,) + + def values_of(self, matrices: Mapping[str, np.ndarray]) -> np.ndarray: + """ + Gets the values of the statistic's metric in each replicate of each + design, from those of the columns of the results. + + Args: + matrices (Mapping[str, numpy.ndarray]): The values of each column + (shape (designs, replicates)). + + Returns: + numpy.ndarray: the values of the metric (shape (designs, + replicates)) + """ + if _is_derived(self.column): + values = {name: matrices[name] for name in self.columns} + return np.asarray(self.column.evaluate(values), dtype=float) + return matrices[self.column] + + def reduce(self, values: np.ndarray) -> np.ndarray: + """ + Computes the statistic of each design (row) from its values in its + replicates (columns), ignoring missing values (`NaN`). + + Args: + values (numpy.ndarray): The values (shape (designs, replicates)). + + Returns: + numpy.ndarray: the statistic of each design (`NaN` without values) + """ + raise NotImplementedError + + def __eq__(self, other: object) -> bool: + return type(self) is type(other) and vars(self) == vars(other) + + def __hash__(self) -> int: + return hash((type(self), tuple(sorted(vars(self).items())))) + + def __fingerprint__(self) -> dict: + """ + Gets what identifies the statistic in a definition (see + `tatc.tradespace.fingerprint`), such as of the statistics of the + failures of a study (see `Failures`): its attributes (such as its + column, and its quantile or threshold). + + Returns: + dict: the attributes + """ + return dict(vars(self)) + + def __repr__(self) -> str: + return f"{type(self).__name__}({self.column!r})" + + +def _all_nan(values: np.ndarray) -> np.ndarray: + return np.all(np.isnan(values), axis=1) + + +def _nan_reduce(function, values: np.ndarray) -> np.ndarray: + """ + Applies a nan-aware reduction along replicates, giving `NaN` (without a + warning) for designs without values. + """ + result = np.full(values.shape[0], np.nan) + valid = ~_all_nan(values) + if np.any(valid): + result[valid] = function(values[valid], axis=1) + return result + + +class Mean(Statistic): + """ + The mean of a metric over the replicates. + """ + + def reduce(self, values: np.ndarray) -> np.ndarray: + return _nan_reduce(np.nanmean, values) + + +def _standard_deviation(values: np.ndarray) -> np.ndarray: + """ + Computes the sample standard deviation of each design (row) over its + values in its replicates (columns), ignoring missing values (`NaN` with + fewer than two, or with an infinite value, such as of a time that is + never met). + """ + counts = np.sum(~np.isnan(values), axis=1) + result = np.full(values.shape[0], np.nan) + valid = counts > 1 + if np.any(valid): + with np.errstate(invalid="ignore"): # inf - inf, of infinite values + result[valid] = np.nanstd(values[valid], axis=1, ddof=1) + return result + + +def _standard_error(values: np.ndarray) -> np.ndarray: + """ + Computes the standard error of the mean of each design (row) from its + values in its replicates (columns): their standard deviation over the + square root of their number (`NaN` with fewer than two), as the spreads + of summaries give it (` se`, see `summarize`). + """ + counts = np.sum(~np.isnan(values), axis=1) + return _standard_deviation(values) / np.sqrt(np.maximum(counts, 1)) + + +class StandardDeviation(Statistic): + """ + The (sample) standard deviation of a metric over the replicates, a + measure of how much a design's outcome depends on its uncertain + parameters (`NaN` with fewer than two replicates). + """ + + @property + def name(self) -> str: + return f"{self.metric} std" + + def reduce(self, values: np.ndarray) -> np.ndarray: + return _standard_deviation(values) + + +class Minimum(Statistic): + """ + The least value of a metric over the replicates (the worst case of a + metric to maximize). + """ + + @property + def name(self) -> str: + return f"{self.metric} min" + + def reduce(self, values: np.ndarray) -> np.ndarray: + return _nan_reduce(np.nanmin, values) + + +class Maximum(Statistic): + """ + The greatest value of a metric over the replicates (the worst case of a + metric to minimize). + """ + + @property + def name(self) -> str: + return f"{self.metric} max" + + def reduce(self, values: np.ndarray) -> np.ndarray: + return _nan_reduce(np.nanmax, values) + + +class Quantile(Statistic): + """ + A quantile of a metric over the replicates: for example, the 0.1 + quantile of a metric to maximize is a value that the design exceeds in + 90% of the replicates (by linear interpolation between them). + + Args: + column (str | Utility): The metric. + q (float): The quantile, between 0 and 1. + """ + + def __init__(self, column: str, q: float): + super().__init__(column) + if not 0 <= q <= 1: + raise ValueError("q must be between 0 and 1") + self.q = q + + def reduce(self, values: np.ndarray) -> np.ndarray: + # numpy's nanquantile, vectorized: sort each row (missing values + # last), and interpolate linearly between the values around the + # quantile's position among each row's values + ordered = np.sort(values, axis=1) + counts = np.sum(~np.isnan(values), axis=1) + position = self.q * np.maximum(counts - 1, 0) + below = np.floor(position).astype(int) + above = np.minimum(below + 1, np.maximum(counts - 1, 0)) + rows = np.arange(len(values)) + weight = position - below + with np.errstate(invalid="ignore"): + result = (1 - weight) * ordered[rows, below] + weight * ordered[rows, above] + result[weight == 0] = ordered[rows, below][weight == 0] + result[counts == 0] = np.nan + return result + + @property + def name(self) -> str: + return f"{self.metric} p{100 * self.q:g}" + + def __repr__(self) -> str: + return f"Quantile({self.column!r}, {self.q!r})" + + +class Probability(Statistic): + """ + The probability that a metric meets a threshold: the share (0 to 1) of + the replicates in which it does, such as the reliability of a design. + + Args: + column (str | Utility): The metric. + operator (str): The comparison: `">="`, `">"`, `"<="`, or `"<"`. + threshold (float): The threshold. + """ + + def __init__(self, column: str, operator: str, threshold: float): + super().__init__(column) + if operator not in _OPERATORS: + raise ValueError(f"operator must be one of {list(_OPERATORS)}") + self.operator, self.threshold = operator, threshold + + def reduce(self, values: np.ndarray) -> np.ndarray: + valid = ~np.isnan(values) + with np.errstate(invalid="ignore"): + met = _OPERATORS[self.operator](values, self.threshold) & valid + counts = valid.sum(axis=1) + result = np.full(values.shape[0], np.nan) + result[counts > 0] = met.sum(axis=1)[counts > 0] / counts[counts > 0] + return result + + @property + def name(self) -> str: + return f"P({self.metric} {self.operator} {self.threshold:g})" + + def __repr__(self) -> str: + return f"Probability({self.column!r}, {self.operator!r}, {self.threshold!r})" diff --git a/src/tatc/tradespace/store.py b/src/tatc/tradespace/store.py new file mode 100644 index 0000000..11fd9a5 --- /dev/null +++ b/src/tatc/tradespace/store.py @@ -0,0 +1,359 @@ +""" +Persistent stores of the results of trade studies, so that a study that is +interrupted resumes where it stopped, and a study that is extended (with +more designs or replicates) evaluates only what is new. + +@author: Paul T. Grogan +""" + +from __future__ import annotations + +import base64 +import json +import math +import os +import pickle +import sqlite3 +from collections.abc import Callable, Iterable +from contextlib import closing +from datetime import date, datetime, time, timedelta, timezone +from pathlib import Path +from typing import Any + +import numpy as np + +from .hashing import canonical + +_RESULTS_TABLE = ( + "CREATE TABLE IF NOT EXISTS results (namespace TEXT, context TEXT, " + + "design TEXT, replicate INTEGER, variant TEXT, records TEXT, " + + "PRIMARY KEY (namespace, context, design, replicate, variant))" +) +"""The table of the records of evaluations.""" + +_JSON = (bool, int, str) +"""Types whose values are kept as they are in JSON (exactly these types).""" + + +def _encode(value: Any) -> Any: + """ + Encodes a value as JSON data: plain values as they are, and others + tagged (as `{"$tag": data}`), so that they are decoded exactly (numpy + scalars as Python's), or pickled if JSON cannot hold them. + """ + # pylint: disable=too-many-return-statements + kind = type(value) + if value is None or kind in _JSON: + return value + if kind is float: + return value if math.isfinite(value) else {"$float": repr(value)} + if isinstance(value, np.generic): + item = value.item() + if type(item) in (*_JSON, float): + return _encode(item) + elif kind is list: + return [_encode(item) for item in value] + elif kind is tuple: + return {"$tuple": [_encode(item) for item in value]} + elif kind is dict: + if all(type(key) is str and not key.startswith("$") for key in value): + return {key: _encode(item) for key, item in value.items()} + return {"$dict": [[_encode(k), _encode(v)] for k, v in value.items()]} + elif kind is datetime and value.tzinfo in (None, timezone.utc): + return {"$datetime": value.isoformat()} + elif kind is date: + return {"$date": value.isoformat()} + elif kind is time and value.tzinfo is None: + return {"$time": value.isoformat()} + elif kind is timedelta: + return {"$timedelta": [value.days, value.seconds, value.microseconds]} + return {"$pickle": base64.b64encode(pickle.dumps(value)).decode("ascii")} + + +_DECODERS: dict[str, Callable[[Any], Any]] = { + "$float": float, + "$tuple": lambda items: tuple(_decode(item) for item in items), + "$dict": lambda pairs: {_decode(k): _decode(v) for k, v in pairs}, + "$datetime": datetime.fromisoformat, + "$date": date.fromisoformat, + "$time": time.fromisoformat, + "$timedelta": lambda parts: timedelta(*parts), + "$pickle": lambda text: pickle.loads(base64.b64decode(text)), +} + + +def _decode(value: Any) -> Any: + """Decodes a value from JSON data (see `_encode`).""" + if isinstance(value, list): + return [_decode(item) for item in value] + if isinstance(value, dict): + if len(value) == 1: + tag, data = next(iter(value.items())) + if tag in _DECODERS: + return _DECODERS[tag](data) + return {key: _decode(item) for key, item in value.items()} + return value + + +class ResultStore: + """ + A store of the records of the evaluations of a study (see `Study.run`), + by the key of each design, its replicate, and the variant of the + replicate, in a SQLite database file. The variant of a plain replicate + is `""`; that of a replicate whose parameters are drawn as in other + replicates (see `Study.run`), or that is evaluated in a scenario (see + `Study`), names the shift and a hash of the overrides of the scenario + (by their content, not the scenario's name), so that the evaluations of + a scenario are those of any scenario of the same overrides, and a + scenario without overrides shares the evaluations of plain replicates. + + Records are also keyed by a `context`: a study gives its fingerprint, + which changes with its definition (see `Study.fingerprint` for what it + describes), so that records computed with other definitions are not + reused. The store keeps the definition of each context, + from which a study explains why it does not reuse records (see + `compare_definitions`). What a fingerprint cannot describe (such as data + that the functions read from files, and the code of modules other than + TAT-C's that they call) a `namespace` identifies, which must change + whenever it does. Studies of other definitions (such as variants of a + study) may share a namespace, as their fingerprints keep their records + apart, and several namespaces may share a file. + + Records are kept as JSON (in the column `records` of the table `results`, + a list of records per evaluation), which other tools can read: numbers + (numpy's as Python's), strings, and booleans as they are, and other + values (such as infinite numbers, dates and times, and tuples) tagged, + as `{"$tag": data}`, so that they are read exactly as they were written + (or pickled, as `{"$pickle": data}`, if JSON cannot hold them). + + A study reads and writes the store (see `Study.run`), and removes the + records of its definitions with other code (see `Study.prune`); `len` + counts the records of the namespace, and `clear` removes them:: + + study = Study(space, build, evaluate, store=ResultStore("results.sqlite")) + + Args: + path (str | os.PathLike): The database file (created if needed). + namespace (str): An identifier of what the fingerprints of the + studies cannot see (such as data they read from files), if any. + """ + + def __init__(self, path: str | os.PathLike, *, namespace: str = ""): + self.path, self.namespace = Path(path), namespace + self.path.parent.mkdir(parents=True, exist_ok=True) + with closing(self._connect()) as connection: + connection.isolation_level = None + connection.execute("BEGIN IMMEDIATE") + try: + columns = { + row[1] for row in connection.execute("PRAGMA table_info(results)") + } + if columns and "variant" not in columns: + # evaluations stored before replicates had variants are of + # plain replicates + connection.execute("ALTER TABLE results RENAME TO _invariant") + connection.execute(_RESULTS_TABLE) + connection.execute( + "INSERT INTO results SELECT namespace, context, design, " + + "replicate, '', records FROM _invariant" + ) + connection.execute("DROP TABLE _invariant") + connection.execute(_RESULTS_TABLE) + connection.execute( + "CREATE TABLE IF NOT EXISTS definitions (namespace TEXT, " + + "context TEXT, definition TEXT, defined TEXT, " + + "PRIMARY KEY (namespace, context))" + ) + connection.execute("COMMIT") + except BaseException: + connection.execute("ROLLBACK") + raise + + def _connect(self) -> sqlite3.Connection: + return sqlite3.connect(self.path, timeout=60) + + def _get( + self, keys: Iterable[tuple[str, int]], context: str = "", variant: str = "" + ) -> dict[tuple[str, int], list[dict]]: + """ + Gets the stored records of evaluations. + + Args: + keys (Iterable[tuple[str, int]]): The evaluations: the key of a + design and its replicate. + context (str): The context of the evaluations (such as the + fingerprint of a study). + variant (str): The variant of the replicates (`""` for plain + replicates). + + Returns: + dict: the records of each stored evaluation (others are omitted) + """ + keys = list(keys) + found = {} + with closing(self._connect()) as connection: + for start in range(0, len(keys), 500): + part = keys[start : start + 500] + designs = sorted({design for design, _ in part}) + marks = ",".join("?" * len(designs)) + rows = connection.execute( + "SELECT design, replicate, records FROM results WHERE " + + "namespace = ? AND context = ? AND variant = ? " + + f"AND design IN ({marks})", + [self.namespace, context, variant, *designs], + ).fetchall() + wanted = set(part) + for design, replicate, text in rows: + if (design, replicate) in wanted: + found[design, replicate] = _decode(json.loads(text)) + return found + + def _put( + self, + items: Iterable[tuple[str, int, list[dict]]], + context: str = "", + variant: str = "", + ) -> None: + """ + Stores the records of evaluations, replacing any stored before. + + Args: + items (Iterable[tuple[str, int, list[dict]]]): The evaluations: the + key of a design, its replicate, and its records. + context (str): The context of the evaluations (such as the + fingerprint of a study). + variant (str): The variant of the replicates (`""` for plain + replicates). + """ + rows = [ + ( + self.namespace, + context, + design, + int(replicate), + variant, + json.dumps(_encode(records), allow_nan=False), + ) + for design, replicate, records in items + ] + if rows: + with closing(self._connect()) as connection: + with connection: + connection.executemany( + "INSERT OR REPLACE INTO results VALUES (?, ?, ?, ?, ?, ?)", + rows, + ) + + def _define(self, context: str, definition: dict) -> None: + """ + Keeps the definition of a context (such as that of a study, see + `Study.definition`), if it is not kept already. + + Args: + context (str): The context (such as the fingerprint of a study). + definition (dict): Its definition (see `get_definition`). + """ + defined = datetime.now(timezone.utc).isoformat(timespec="seconds") + with closing(self._connect()) as connection: + with connection: + connection.execute( + "INSERT OR IGNORE INTO definitions VALUES (?, ?, ?, ?)", + [ + self.namespace, + context, + canonical(definition), + defined, + ], + ) + + def _definition(self, context: str) -> dict | None: + """ + Gets the definition of a context (see `_define`). + + Args: + context (str): The context. + + Returns: + dict | None: the definition, or `None` if it is not kept + """ + with closing(self._connect()) as connection: + row = connection.execute( + "SELECT definition FROM definitions WHERE namespace = ? AND context = ?", + [self.namespace, context], + ).fetchone() + return None if row is None else json.loads(row[0]) + + def _contexts(self) -> dict[str, int]: + """ + Gets the contexts of the namespace: those of its stored evaluations + and of its kept definitions (see `_define`, such as of a study whose + evaluations all failed), in the order they were defined (those not + defined first). + + Returns: + dict[str, int]: the number of evaluations of each context (0 for + a definition without evaluations) + """ + with closing(self._connect()) as connection: + rows = connection.execute( + "SELECT c.context, COALESCE(r.evaluations, 0) FROM " + + "(SELECT context FROM results WHERE namespace = ? UNION " + + "SELECT context FROM definitions WHERE namespace = ?) AS c " + + "LEFT JOIN (SELECT context, COUNT(*) AS evaluations FROM results " + + "WHERE namespace = ? GROUP BY context) AS r ON r.context = c.context " + + "LEFT JOIN definitions AS d ON d.namespace = ? " + + "AND d.context = c.context " + + "ORDER BY d.defined, d.rowid, c.context", + [self.namespace] * 4, + ).fetchall() + return dict(rows) + + def __len__(self) -> int: + return sum(self._contexts().values()) + + def _remove(self, contexts: str | Iterable[str]) -> int: + """ + Removes the stored records (and definitions) of contexts of the + namespace, such as those of earlier definitions of a study (see + `Study.prune`, which removes those of the study with other code, + also of definitions without records, and not those of other studies + that share the namespace). + + Args: + contexts (str | Iterable[str]): The contexts. + + Returns: + int: the number of evaluations removed + """ + contexts = [contexts] if isinstance(contexts, str) else list(contexts) + removed = 0 + with closing(self._connect()) as connection: + with connection: + for context in contexts: + removed += connection.execute( + "DELETE FROM results WHERE namespace = ? AND context = ?", + [self.namespace, context], + ).rowcount + connection.execute( + "DELETE FROM definitions WHERE namespace = ? AND context = ?", + [self.namespace, context], + ) + return removed + + def clear(self) -> None: + """ + Removes the stored records (and definitions) of the namespace (of + every context). + """ + with closing(self._connect()) as connection: + with connection: + for table in ("results", "definitions"): + connection.execute( + f"DELETE FROM {table} WHERE namespace = ?", [self.namespace] + ) + + def __repr__(self) -> str: + return ( + f"ResultStore({str(self.path)!r}, namespace={self.namespace!r}: " + + f"{len(self)} evaluations)" + ) diff --git a/src/tatc/tradespace/study.py b/src/tatc/tradespace/study.py new file mode 100644 index 0000000..368ccf1 --- /dev/null +++ b/src/tatc/tradespace/study.py @@ -0,0 +1,1000 @@ +""" +Trade studies: the evaluation of designs from a design space, with +replicates that draw their uncertain parameters, in sequence or in parallel. + +@author: Paul T. Grogan +""" + +from __future__ import annotations + +import math +import os +import time +from collections.abc import Callable, Iterable, Mapping, Sequence +from concurrent.futures import Executor, as_completed +from typing import Any, NamedTuple + +import pandas as pd +from pydantic import ValidationError + +from .alerts import _warn +from .fingerprint import _find_stale, _fingerprint_of, get_definition, warn_stale +from .fingerprint import describe as describe_value +from .hashing import canonical, digest +from .nodes import Infeasible +from .references import _given_design +from .space import ( + STATUS_COLUMNS, + Design, + DesignSpace, + _check_replicate, + _check_seed, + _check_shift, + _designs, +) +from .store import ResultStore + +_DESCRIPTION = "description" +"""The column of the results of a study that describes designs (see `Study`).""" + +_UNSTORED = "_unstored" +"""A key of the records of evaluations that are not stored: those that failed +(with `errors="record"`) and designs that failed validation, which may be +mistakes in a study's functions that its fingerprint cannot see.""" + + +_WORKER_TIMEOUT = 120 +"""The seconds that an idle worker process waits for evaluations before it +exits: long enough to outlast the pauses of a study between its runs (such +as the bootstrap of each round of `refine`), which would otherwise start new +workers (with a warning of loky's, if evaluations arrive as a worker exits).""" + + +def _get_executor(n_jobs: int) -> Executor: + """ + Gets a reusable executor of `n_jobs` worker processes (from joblib's + loky, which serializes functions defined in notebooks and lambdas). + """ + try: + # pylint: disable=import-outside-toplevel + from joblib.externals.loky import get_reusable_executor + except ImportError as error: + raise ImportError( + "parallel trade studies require joblib (pip install joblib), " + + "or pass an executor" + ) from error + # one thread per worker for the numerical libraries, whose thread pools + # (one thread per processor in each worker) otherwise exhaust memory + threads = { + name: "1" + for name in ( + "OMP_NUM_THREADS", + "OPENBLAS_NUM_THREADS", + "MKL_NUM_THREADS", + "NUMEXPR_NUM_THREADS", + "NUMBA_NUM_THREADS", + ) + } + return get_reusable_executor( + max_workers=n_jobs, env=threads, timeout=_WORKER_TIMEOUT + ) + + +class Study: + """ + A trade study: designs from a design space, each built into an + architecture (or any object to evaluate) and evaluated in replicates:: + + study = Study(space, build, evaluate, replicates=5, n_jobs=-1, store=store) + results = study.run() # every design, a row per replicate + more = study.replace(replicates=20).run(designs) + + Each replicate realizes a design (see `Design.realize`), builds it with + `build`, and evaluates the result with `evaluate`, which returns its + outcomes: a mapping (or `pandas.Series`) of metrics, or a + `pandas.DataFrame` of several records of metrics (such as one per + sensor), whose named index is kept as columns, and which must have at + least one record (an empty data frame raises a `ValueError`, whatever + `errors` is: give a record of no sensors, for example, with missing + metrics). Designs given of another design space (such as of a design + space that the study's extends) are evaluated as the designs of the + study's design space of their decisions, which must be decisions of a + design of it. An `evaluate` function that takes a keyword named `design` + is also given the realized design (with the uncertain parameters of the + replicate, see `tatc.tradespace.references`), as for an evaluation that + depends on values of the design other than those it builds:: + + def build(d): + return build_constellation(d.layout, payload, epoch=START) + + def evaluate(satellites, design): + deployment = SCHEDULE.plan(design.layout) + ... + + A design is recorded as infeasible, with the error, rather than raised, + if `build` or `evaluate` rejects it by raising `Infeasible`, or if + `build` fails the validation of TAT-C's schemas (a pydantic + `ValidationError`, such as of an orbit too high to be sun-synchronous). + Other errors of `build` and `evaluate`, and of the realization of a + design (such as of a derived value of a drawn uncertain parameter), + including other `ValueError`s, which are as likely mistakes in the + functions as properties of designs, are raised, which stops the study, + unless `errors` is `"record"`: then the evaluation is recorded as + infeasible, with the type of the error and its message. + Evaluations that fail and designs that fail validation are not kept in + the study's store, so that a later run evaluates them again (as after + fixing a mistake in code that the study's fingerprint cannot see, see + `fingerprint`). A warning is given if no design of a run (of several) + is feasible. + + The metrics must not be named as the columns of the results that + identify an evaluation (see `STATUS_COLUMNS`: `design`, `replicate`, + `scenario`, `feasible`, `error`, and `seconds`, also `scenario` in a + study without scenarios), and a metric named as a value of the design + (see `Design.flat`) must equal it (restating it, as a design variable + that is also an objective): metrics that would replace these columns + raise a `ValueError`, whatever `errors` is. + + A study may evaluate designs in `scenarios`: conditions under which + designs are compared rather than averaged over (as uncertain parameters + are), such as the requirements of a mission or the field it must sample. + A scenario overrides fixed values or uncertain parameters of the design + space with other values (by path, see `Design.realize`), which the + functions read from the design as any other value (so that they need + not change), and each design is evaluated in each scenario in each + replicate (with the same uncertain parameters in every scenario), + recorded with the name of its scenario (`scenario`, which the realized + design also gives, see `Design.scenario`). A design that violates a + constraint of the design space with the values of a scenario is + recorded as infeasible in that scenario. Judge designs in each scenario + with criteria `by` the scenario (see `Criteria`), once across the + scenarios with criteria that combine their statistics `Across` them + (such as their worst or mean), and by their efficiency in each with + `robustness`. Scenarios are not part of the study's fingerprint: the + evaluations of each are stored by its values (as a variant of the + replicates, see `ResultStore`), so that a scenario added later is + evaluated alone, and one without values shares the evaluations of the + study without scenarios. + + A study may `describe` its designs with a function of a design (not of + a replicate) that labels it for tables and plots, as the value + `description` of each design in the results (after its other values), + which summaries keep (see `summarize`). Labels are given by every run, + not stored, nor part of the fingerprint: a new function needs no new + evaluations:: + + study = Study(space, build, evaluate, describe=lambda d: str(layout_of(d.layout))) + + Evaluations run in parallel with `n_jobs` worker processes (or an + `executor` with the interface of `concurrent.futures.Executor`). They are + sent to the workers in chunks of consecutive evaluations of the same + replicates, so that a cache of each worker (see `SatelliteCache`) is + shared by the designs of a replicate, which share their uncertain + parameters (with common random numbers). The functions, and the objects + they refer to, are copied to each worker for each chunk, so keep large + inputs out of them (for example, load them from files in the workers) if + copying them takes long. Each evaluation is added to the study's store + (if any) as it completes, by the worker that evaluates it, so that a run + that is interrupted loses only the evaluations in progress; chunks that + have not begun are then cancelled. + + Args: + space (DesignSpace): The design space. + build (Callable): A function of a realized design that builds the + object to evaluate (for example, a list of satellites). + evaluate (Callable): A function of a built object that evaluates it + (and of the realized design, if it takes a keyword named + `design`). + replicates (int): The number of replicates of each design. + seed (int): The seed of the uncertain parameters (a non-negative + integer). + common_random_numbers (bool): `True` to draw the same uncertain + parameters in the same replicate of every design (see + `Design.realize`). + n_jobs (int): The number of worker processes (1 to evaluate in this + process, -1 for one per processor), each limited to one thread of + the numerical libraries (OpenMP, OpenBLAS, MKL, and numba). + executor (concurrent.futures.Executor | None): An executor to use + instead of worker processes. + chunks_per_job (int): The number of chunks of evaluations per worker. + errors (str): `"raise"` to raise the errors of evaluations (other than + those of designs that `build` rejects), or `"record"` to record + them as infeasible evaluations (also those of the realization of + designs). + store (ResultStore | None): A store of the records of evaluations, from + which evaluations stored before (by a study of the same + fingerprint, see `fingerprint`) are taken rather than evaluated + again, and to which new ones are added as they complete (see + `ResultStore`), by the workers that evaluate them (so its file + must be reachable from them). Studies of other definitions may + share a store (and its namespace): their fingerprints keep their + evaluations apart. A warning is given if the store has + evaluations of the same study with other code (of its functions, + of TAT-C, or of Python), which are not reused. + scenarios (Mapping[str, Mapping[str, Any]] | None): The scenarios + in which to evaluate designs, if any: the overrides of fixed + values and uncertain parameters of each (by path), by name. + describe (Callable | None): A function of a design that gives a label + of it (`description`), if any, which a value of the design space + (or a metric) may then not be named as (a `ValueError`). + """ + + def __init__( + self, + space: DesignSpace, + build: Callable[[Design], Any], + evaluate: Callable[[Any], Any], + *, + replicates: int = 1, + seed: int = 0, + common_random_numbers: bool = True, + n_jobs: int = 1, + executor: Executor | None = None, + chunks_per_job: int = 2, + store: ResultStore | None = None, + errors: str = "raise", + scenarios: Mapping[str, Mapping[str, Any]] | None = None, + describe: Callable[[Design], Any] | None = None, + ): + # pylint: disable=too-many-arguments + if errors not in ("raise", "record"): + raise ValueError(f"errors must be 'raise' or 'record', not {errors!r}") + if replicates < 1: + raise ValueError("replicates must be at least 1") + if n_jobs == 0 or n_jobs < -1: + raise ValueError("n_jobs must be positive or -1") + if chunks_per_job < 1: + raise ValueError("chunks_per_job must be at least 1") + _check_seed(seed) + if describe is not None and not callable(describe): + raise TypeError(f"describe is a function of a design, not {describe!r}") + if describe is not None and _DESCRIPTION in space.children: + raise ValueError(f"a value of the design space named {_DESCRIPTION!r}") + self.space, self.build, self.evaluate = space, build, evaluate + self.replicates, self.seed = replicates, seed + self.common_random_numbers = common_random_numbers + self.n_jobs, self.executor = n_jobs, executor + self.chunks_per_job = chunks_per_job + self.store = store + self.errors = errors + self.scenarios = _check_scenarios(space, scenarios) + self.describe = describe + + def __getstate__(self) -> dict: + # an executor is not sent to workers (which add evaluations to the store) + state = self.__dict__.copy() + state["executor"] = None + return state + + def _evaluate( + self, + design: Design, + replicate: int, + shift: Mapping[str, int] | None, + case: _Case, + ) -> list[dict]: + """ + Evaluates a replicate of a design (with parameters drawn as in other + replicates, if shifted) in a case (a scenario, or none), returning + its records. + """ + # pylint: disable=too-many-return-statements,too-many-branches + base: dict = {"design": design.key, "replicate": replicate} + if case.name is not None: + base["scenario"] = case.name + try: + realized = self._realized(design, replicate, shift, case) + except Infeasible as error: + # the scenario's values violate a constraint of the design + return [{**base, **design.flat(), "feasible": False, "error": str(error)}] + except Exception as error: # pylint: disable=broad-exception-caught + # such as of a derived value of a drawn uncertain parameter + if self.errors == "raise": + raise + return [self._failure({**base, **design.flat()}, error)] + base.update(realized.flat()) + began = time.perf_counter() + try: + built = self.build(realized) + except Infeasible as error: + return [{**base, "feasible": False, "error": str(error)}] + except ValidationError as error: + return [{**base, "feasible": False, "error": str(error), _UNSTORED: True}] + except Exception as error: # pylint: disable=broad-exception-caught + if self.errors == "raise": + raise + return [self._failure(base, error)] + try: + outcome = _given_design(self.evaluate, realized)(built) + except Infeasible as error: + return [{**base, "feasible": False, "error": str(error)}] + except Exception as error: # pylint: disable=broad-exception-caught + if self.errors == "raise": + raise + return [self._failure(base, error)] + base.update(feasible=True, seconds=time.perf_counter() - began) + if isinstance(outcome, pd.DataFrame): + if len(outcome) == 0: + raise ValueError( + f"the evaluation of design {design.key} (replicate {replicate}) " + + "gives an empty data frame: give at least one record (such as " + + "of no sensors, with missing metrics)" + ) + named = any(name is not None for name in outcome.index.names) + frame = outcome.reset_index() if named else outcome + records = frame.to_dict("records") + else: + records = [dict(outcome)] + for record in records: + _check_metrics(record, base, self.describe is not None) + return [{**base, **record} for record in records] + + @staticmethod + def _failure(base: dict, error: Exception) -> dict: + """ + Gets the record of an evaluation that failed. + """ + message = f"{type(error).__name__}: {error}" + return {**base, "feasible": False, "error": message, _UNSTORED: True} + + def _evaluate_and_store( + self, + design: Design, + replicate: int, + context: str, + shift: Mapping[str, int] | None, + case: _Case, + ) -> list[dict]: + """ + Evaluates a replicate of a design (shifted, if given) in a case, + adding its records to the store (if any, and if they are stored, see + `_UNSTORED`) in a context, as the variant of the case. + """ + records = self._evaluate(design, replicate, shift, case) + if self.store is not None and not _unstored(records): + variant = case.variant + if case.name is not None: + # the evaluations of a scenario are stored by its values, not + # its name (which the results give, see `_in_scenario`) + kept = [ + {k: v for k, v in r.items() if k != "scenario"} for r in records + ] + else: + kept = records + # pylint: disable-next=protected-access + self.store._put([(design.key, replicate, kept)], context, variant) + return records + + def _run_chunk( + self, + tasks: list[_Task], + context: str, + shift: Mapping[str, int] | None, + cases: Sequence[_Case], + ) -> list[list[dict]]: + """ + Evaluates a chunk of tasks in turn (shifted, if given), adding each + to the store (if any) in a context. + """ + return [ + self._evaluate_and_store( + task.design, task.replicate, context, shift, cases[task.case] + ) + for task in tasks + ] + + def _cases(self, shift: Mapping[str, int]) -> list[_Case]: + """ + Gets the cases of a run: its scenarios (or none), and the variants of + their evaluations in a store, with a (normalized) shift. + """ + if not self.scenarios: + return [_Case(None, {}, _variant_of(shift))] + return [ + _Case(name, values, _variant_of(shift, _describe_overrides(values))) + for name, values in self.scenarios.items() + ] + + def replace(self, **changes: Any) -> Study: + """ + Gets a study like this one with some of its arguments changed (by + name, as of its class), such as a variant with more replicates, in + scenarios, or of another design space:: + + confirming = study.replace(replicates=20) + policies = study.replace(space=space.extend(policy=POLICY)) + + Args: + **changes (Any): The arguments to change. + + Returns: + Study: the study, of the same class + + Raises: + TypeError: if a change names no argument of the study's class. + """ + arguments = self._arguments() + unknown = sorted(set(changes) - set(arguments)) + if unknown: + raise TypeError(f"{type(self).__name__} has no arguments {unknown}") + return type(self)(**{**arguments, **changes}) + + def _arguments(self) -> dict[str, Any]: + """ + Gets the arguments of the study, by name, from which `replace` makes + another (a subclass with other arguments gives its own). + """ + if type(self).__init__ is not Study.__init__: + raise TypeError( + f"{type(self).__name__} does not give its arguments to replace" + ) + return { + "space": self.space, + "build": self.build, + "evaluate": self.evaluate, + **self._settings(), + } + + def _settings(self) -> dict[str, Any]: + """Gets the settings of the study (the arguments of every study but + its design space and functions), by name.""" + return { + "replicates": self.replicates, + "seed": self.seed, + "common_random_numbers": self.common_random_numbers, + "n_jobs": self.n_jobs, + "executor": self.executor, + "chunks_per_job": self.chunks_per_job, + "store": self.store, + "errors": self.errors, + "scenarios": self.scenarios, + "describe": self.describe, + } + + def realize( + self, design: Design, replicate: int = 0, scenario: str | None = None + ) -> Design: + """ + Realizes a replicate of a design as the study evaluates it (see + `Design.realize`): as a design of the study's design space (if it is + of another), with the study's seed and common random numbers, and in + one of its scenarios (by name), if given, such as for analyses of a + design other than its metrics. + + Args: + design (Design): The design. + replicate (int): The replicate. + scenario (str | None): A scenario of the study (by name), or `None` + for the values of the design space. + + Returns: + Design: the realized design + + Raises: + KeyError: if the study has no scenario of the name. + Infeasible: if the design violates a constraint in the scenario. + """ + values = None + if scenario is not None: + if not self.scenarios or scenario not in self.scenarios: + raise KeyError( + f"no scenario {scenario!r} of the study " + + f"(it has {list(self.scenarios or {})})" + ) + values = self.scenarios[scenario] + (design,) = _designs(self.space, [design]) + return self._realized(design, replicate, None, _Case(scenario, values, "")) + + def _realized( + self, + design: Design, + replicate: int, + shift: Mapping[str, int] | None, + case: _Case, + ) -> Design: + """ + Realizes a replicate of a design (of the study's design space) as the + study evaluates it in a case (a scenario, or none), with parameters + drawn as in other replicates, if shifted. + + Raises: + Infeasible: if the design violates a constraint in the scenario. + """ + return design.realize( + replicate, + seed=self.seed, + common_random_numbers=self.common_random_numbers, + shift=shift, + overrides=case.values, + scenario=case.name, + ) + + def _prepare( + self, + design: Design, + replicate: int, + shift: Mapping[str, int] | None, + case: _Case, + ) -> None: + """ + Prepares to evaluate designs (in this process, before any worker + does), given the first evaluation of a run: nothing, unless a subclass + prepares something. + """ + + @property + def definition(self) -> dict: + """dict: The definition of the study (see `get_definition`), which + its fingerprint hashes: its seed, its use of common random numbers, + its design space (including fixed values and the distributions of + uncertain parameters), its build and evaluation functions (their + code, the values they close over, and the globals they refer to, see + `tatc.tradespace.fingerprint`), and the source of the modules of + TAT-C that these, and studies, depend on.""" + return get_definition( + study=Study, + seed=self.seed, + common_random_numbers=self.common_random_numbers, + space=self.space, + build=self.build, + evaluate=self.evaluate, + ) + + @property + def fingerprint(self) -> str: + """str: A key of the definition of the study (see `definition`), which + changes if it does: if its seed or use of common random numbers + changes, or its design space, or the code of its functions, the + values they close over or take as defaults, or the globals they + refer to (plain values and their containers, dataclasses, models, + data, designs, caches of satellites, and the functions, classes, and + objects of the study's own modules, which are described by content + or code, see `tatc.tradespace.fingerprint`), + or the source of the modules of TAT-C they depend on, or the version + of Python. It does not change with the study's scenarios (whose + evaluations a store keeps apart, see `ResultStore`), nor its other + settings (such as its number of replicates or workers). It keys the + records of a store (see `ResultStore`); what it cannot describe + (data that the functions read, such as from files, the code of + installed modules other than TAT-C's, and the state of objects + described by type: those of installed classes, and those of TAT-C's + classes that are neither dataclasses, models, nor nodes, nor + describe themselves, as designs and caches of satellites do, see + `tatc.tradespace.fingerprint`) must be identified by the store's + namespace.""" + return _fingerprint_of(self.definition) + + def prune(self) -> int: + """ + Removes the evaluations of the study's store (in its namespace) by + this study with other code (of its functions, of TAT-C, or of Python: + the same values but for code), which it does not reuse, and of which + it warns. The evaluations of other studies that share the namespace + (such as variants with other settings) are kept. + + Returns: + int: the number of evaluations removed (0 without a store) + """ + if self.store is None: + return 0 + definition = self.definition + context = _fingerprint_of(definition) + stale = _stale_contexts(self.store, context, definition) + return self.store._remove(stale) # pylint: disable=protected-access + + @property + def workers(self) -> int: + """int: The number of workers that evaluate designs (1 in this process).""" + if self.executor is not None: + return max(getattr(self.executor, "_max_workers", 1) or 1, 1) + if self.n_jobs == -1: + return os.cpu_count() or 1 + return self.n_jobs + + def run( + self, + designs: Iterable[Design] | pd.DataFrame | None = None, + *, + progress: Callable[[int, int], None] | None = None, + replicate_indices: Iterable[int] | None = None, + shift: Mapping[str, int] | None = None, + ) -> pd.DataFrame: + """ + Evaluates designs in every replicate (or in given replicates, such as + additional ones, see `refine`). Repeated designs (with the same key) + are evaluated once. + + With a `shift`, each replicate draws the named uncertain parameters + as in another replicate (see `Design.realize`): for example, with a + shift of `{"points_seed": 10}`, replicate 3 draws `points_seed` as + replicate 13 does, and its other parameters as replicate 3 does. + Such mixed replicates are kept apart from plain ones in the store + (by their variant, see `ResultStore`), and are recorded with the + replicate they shift (and the values they draw, see `Design.flat`). + + With scenarios (see `Study`), each design is evaluated in each + scenario in each replicate. + + Args: + designs (Iterable[Design] | pandas.DataFrame | None): The designs, + a data frame of their values (such as a summary that keeps + them, see `DesignSpace.designs_of`), or `None` for every + design of the design space (see `DesignSpace.enumerate`). + progress (Callable | None): A function called as evaluations + complete with the number completed and the number of + evaluations (not counting those taken from the store). + replicate_indices (Iterable[int] | None): The replicates (their + indices, non-negative integers, which seed their uncertain + parameters), or `None` for the study's (`range(replicates)`). + shift (Mapping[str, int] | None): The offsets of the replicates as + in which the named uncertain parameters are drawn (by their + paths, see `DesignSpace.uncertain_paths`; non-negative + integers), if any. + + Returns: + pandas.DataFrame: The outcomes, a record per evaluation (or per + record of an evaluation), in the order of the designs (and + scenarios) and replicates, with the design's key (`design`), + the `replicate` (and the `scenario`, with scenarios), the + values of the design by path (see `Design.flat`), its + `description` (if the study describes its designs), whether it + is `feasible` (and the `error` if not), the time to build and + evaluate it (`seconds`), and the metrics (the status columns + alone, without evaluations, see `STATUS_COLUMNS`). + + Raises: + ValueError: if a replicate index or an offset of `shift` is not + a non-negative integer, `shift` names a path that is not of + an uncertain parameter, or a metric names another column. + """ + shift = {name: offset for name, offset in _check_shift(shift).items() if offset} + self.space._check_uncertain(shift) # pylint: disable=protected-access + replicates = ( + range(self.replicates) + if replicate_indices is None + else sorted({_check_replicate(r) for r in replicate_indices}) + ) + cases = self._cases(shift) + unique = ( + self.space.enumerate() if designs is None else _designs(self.space, designs) + ) + # tasks in the order of replicates (and scenarios), whose designs share + # uncertain values + tasks = [ + _Task(i, design, replicate, case) + for replicate in replicates + for case in range(len(cases)) + for i, design in enumerate(unique) + ] + context, results, tasks = self._stored(tasks, cases) + if tasks: + first = tasks[0] + try: + self._prepare(first.design, first.replicate, shift, cases[first.case]) + except Infeasible: + pass # infeasible in its scenario, which its evaluation records + except Exception: # pylint: disable=broad-exception-caught + if self.errors == "raise": + raise + # such as of its realization, which its evaluation records + results.extend(self._execute(tasks, context, shift, cases, progress)) + results.sort(key=lambda outcome: outcome[:3]) + records = [ + _in_scenario(record, cases[case].name) + for _, case, _, records in results + for record in records + ] + if not records: + frame = pd.DataFrame( + columns=[ + column + for column in STATUS_COLUMNS + if column != "scenario" or self.scenarios + ] + ) + else: + frame = pd.DataFrame.from_records(records) + _check_feasible(frame) + if self.describe is not None: + _add_descriptions(frame, self.describe, unique) + return frame + + def _stored( + self, tasks: list[_Task], cases: Sequence[_Case] + ) -> tuple[str, list[_Outcome], list[_Task]]: + """ + Takes the evaluations of tasks stored before (by an interrupted or + earlier run), if the study has a store: the context of its + evaluations in the store (its fingerprint, `""` without a store), the + outcomes of the stored tasks, and the tasks left to evaluate. Warns of + evaluations of the study with other code if none is stored. + """ + if self.store is None: + return "", [], tasks + definition = self.definition + context = _fingerprint_of(definition) + stored = {} + for k, case in enumerate(cases): + found = self.store._get( # pylint: disable=protected-access + ((d.key, r) for _, d, r, c in tasks if c == k), context, case.variant + ) + stored.update({(key, r, k): records for (key, r), records in found.items()}) + if tasks and not stored: + _warn_other_definitions(self.store, context, definition) + self.store._define(context, definition) # pylint: disable=protected-access + outcomes = [ + _Outcome(i, case, replicate, stored[design.key, replicate, case]) + for i, design, replicate, case in tasks + if (design.key, replicate, case) in stored + ] + left = [t for t in tasks if (t[1].key, t[2], t[3]) not in stored] + return context, outcomes, left + + def _execute( + self, + tasks: list[_Task], + context: str, + shift: Mapping[str, int], + cases: Sequence[_Case], + progress: Callable[[int, int], None] | None, + ) -> list[_Outcome]: + """ + Evaluates tasks (in this process, or in chunks by workers), adding + each to the store (if any) in a context, and reporting progress. + """ + # pylint: disable=too-many-arguments,too-many-positional-arguments + outcomes: list[_Outcome] = [] + total = len(tasks) + if self.executor is None and self.n_jobs == 1: + for done, (i, design, replicate, case) in enumerate(tasks, 1): + records = self._evaluate_and_store( + design, replicate, context, shift, cases[case] + ) + outcomes.append(_Outcome(i, case, replicate, records)) + if progress is not None: + progress(done, total) + return outcomes + if not tasks: + return outcomes + executor = self.executor or _get_executor(self.workers) + n_chunks = min(total, self.workers * self.chunks_per_job) + size = math.ceil(total / max(n_chunks, 1)) + chunks = [tasks[k : k + size] for k in range(0, total, size)] + futures = { + executor.submit(self._run_chunk, chunk, context, shift, cases): chunk + for chunk in chunks + } + done = 0 + try: + for future in as_completed(futures): + chunk = futures[future] + for (i, _, replicate, case), records in zip(chunk, future.result()): + outcomes.append(_Outcome(i, case, replicate, records)) + done += len(chunk) + if progress is not None: + progress(done, total) + except BaseException: + # interrupted (or an error): chunks that have not begun are + # cancelled, and those in progress add their evaluations to the + # store as they complete + for future in futures: + future.cancel() + raise + return outcomes + + +class _Task(NamedTuple): + """ + A task of a run: the position of a design (in the designs of the run), + the design, the replicate, and the position of the case (scenario) in + which to evaluate it. + """ + + position: int + design: Design + replicate: int + case: int + + +class _Outcome(NamedTuple): + """ + The outcome of a task: the position of its design, the position of its + case, its replicate, and the records of its evaluation, in the order in + which the results of a run are sorted. + """ + + position: int + case: int + replicate: int + records: list[dict] + + +def _in_scenario(record: dict, name: str | None) -> dict: + """ + Gets a record of an evaluation for the results of a run: without the + marker of unstored records (see `_UNSTORED`), and with the name of its + scenario (if any) after its replicate (as records of a scenario are + stored without it). + """ + items = [(k, v) for k, v in record.items() if k != _UNSTORED] + if name is None: + return dict(items) + items = [(k, v) for k, v in items if k != "scenario"] + return dict([*items[:2], ("scenario", name), *items[2:]]) + + +class _Case(NamedTuple): + """ + A scenario of a run (or none, without scenarios): its name, its values, + and the variant of its evaluations in a store (see `_variant_of`). + """ + + name: str | None + values: Mapping[str, Any] + variant: str + + +def _check_scenarios( + space: DesignSpace, scenarios: Mapping[str, Mapping[str, Any]] | None +) -> dict[str, dict[str, Any]] | None: + """ + Checks the scenarios of a study (see `Study`), returning them as plain + mappings (or `None` without scenarios). + """ + if not scenarios: + return None + if not isinstance(scenarios, Mapping): + raise TypeError("scenarios must be a mapping of names to values") + checked = {} + for name, values in scenarios.items(): + if not isinstance(name, str): + raise TypeError(f"the name of a scenario must be a string, not {name!r}") + if not isinstance(values, Mapping): + raise TypeError(f"the values of scenario {name!r} must be a mapping") + space._check_overrides(values) # pylint: disable=protected-access + checked[name] = dict(values) + return checked + + +def _describe_overrides(values: Mapping[str, Any]) -> str: + """ + Gets a description of the overrides of a scenario (`""` without values), + which identifies them (by their content, see `get_definition`). + """ + if not values: + return "" + return canonical(describe_value(dict(values))) + + +def _variant_of(shift: Mapping[str, int], scenario: str = "") -> str: + """ + Gets the variant of replicates in a store (see `ResultStore`): `""` for + plain replicates, or (as JSON) a hash of the description of the overrides + of a scenario (see `_describe_overrides`) and the shift of each parameter + (normalized: offsets that are not zero, as integers, see `Study.run`). + """ + parts: dict[str, Any] = {} + if scenario: + parts["scenario"] = digest(scenario, 16) + if shift: + parts["shift"] = shift + return canonical(parts) if parts else "" + + +def _stale_contexts( + store: ResultStore, context: str, definition: dict +) -> dict[str, int]: + """ + Gets the contexts of a store's namespace (and their numbers of + evaluations) of the same study with other code (its functions', TAT-C's, + or Python's, see `_find_stale`), the latest first, including those whose + definitions are kept without evaluations. + """ + contexts = store._contexts() # pylint: disable=protected-access + others = { + other: store._definition(other) # pylint: disable=protected-access + for other in reversed(contexts) + if other != context + } + return _find_stale(definition, others, contexts.__getitem__) + + +def _warn_other_definitions(store: ResultStore, context: str, definition: dict) -> None: + """ + Warns if a store has evaluations of its namespace by the same study with + other code (see `_stale_contexts`), which a study does not reuse, with + the differences from the latest (see `warn_stale`). Studies of other + values (such as other settings) share a namespace without a warning, as + their fingerprints keep their evaluations apart. + """ + warn_stale( + _stale_contexts(store, context, definition), + definition, + store._definition, # pylint: disable=protected-access + lambda count: f"the store has {count} evaluations of namespace " + + f"{store.namespace!r} by this study", + "see Study.fingerprint; Study.prune removes them", + ) + + +def _unstored(records: list[dict]) -> bool: + """ + Whether the records are of an evaluation that is not stored (see + `_UNSTORED`). + """ + return any(record.get(_UNSTORED, False) for record in records) + + +def _same(value: Any, other: Any) -> bool: + """ + Whether two values are equal (`NaN` equal to `NaN`). + """ + try: + # pylint: disable-next=comparison-with-itself + return bool(value == other) or bool(value != value and other != other) + except (TypeError, ValueError): # such as arrays + return False + + +def _check_metrics(metrics: dict, base: dict, described: bool = False) -> None: + """ + Checks that the metrics of a record do not replace the columns of the + results of a study: they must not be named as its status columns (see + `STATUS_COLUMNS`, also `scenario` in a study without scenarios), as its + descriptions of designs (`description`, if `described`, see `Study`), nor + as the marker of unstored records (see `_UNSTORED`), and a metric named + as a value of the design (a key of `base`) must equal it. + """ + columns = [*STATUS_COLUMNS, *([_DESCRIPTION] if described else [])] + clashes = [ + str(name) + for name, value in metrics.items() + if name in columns + or name == _UNSTORED + or (name in base and not _same(value, base[name])) + ] + if clashes: + raise ValueError( + f"metrics named as columns of the results of a study: {sorted(clashes)}; " + + f"rename them (the results have the columns {columns}, " + + "and the values of each design, see Design.flat, which a metric of " + + "the same name must equal)" + ) + + +def _add_descriptions( + results: pd.DataFrame, describe: Callable[[Design], Any], designs: list[Design] +) -> None: + """ + Adds the descriptions of designs (see `Study`) to the results of a run, + before `feasible`, raising a `ValueError` if the results have a column of + their name (a metric stored by a study that did not describe designs). + """ + if _DESCRIPTION in results.columns: + raise ValueError( + f"metrics named {_DESCRIPTION!r}, as descriptions: rename them" + ) + labels = {design.key: describe(design) for design in designs} + results.insert( + results.columns.get_loc("feasible"), + _DESCRIPTION, + [labels[key] for key in results["design"]], + ) + + +def _check_feasible(results: pd.DataFrame) -> None: + """ + Warns if none of several designs of the results of a study is feasible, + which is as likely a mistake in the study's functions as a property of + its designs. + """ + if len(results) == 0 or results["feasible"].any(): + return + designs = results["design"].nunique() + if designs < 2: + return + errors = results["error"].value_counts() + _warn( + f"none of the {designs} designs is feasible; the most common error " + + f"({errors.iloc[0]} of {len(results)} evaluations): {errors.index[0]}" + ) diff --git a/src/tatc/tradespace/summary.py b/src/tatc/tradespace/summary.py new file mode 100644 index 0000000..1fb7ab7 --- /dev/null +++ b/src/tatc/tradespace/summary.py @@ -0,0 +1,900 @@ +""" +Summaries of the results of trade studies: the statistics of each design over +its replicates (see `Statistic`) and their spreads, its judgment by criteria +(see `Criteria`), and the probability that it is efficient, given the +uncertainty of its replicates (by a bootstrap). + +Designs are judged by their feasible replicates: the statistics of a metric +are over the replicates in which a design is feasible, and the share of its +replicates that are feasible is the statistic `feasible` (over every +replicate of the design), which requirements may name. Designs without a +feasible replicate are infeasible, and are left out of summaries. + +@author: Paul T. Grogan +""" + +from __future__ import annotations + +from collections.abc import Iterator, Mapping, Sequence +from dataclasses import replace +from typing import Any + +import numpy as np +import pandas as pd + +from .criteria import ( + Across, + Criteria, + _as_criteria, + _combiners, + _costs, + _resolved, + _statistic, + _tolerances, + _violation, + _weights_of, +) +from .dominance import efficient +from .statistics import ( + Mean, + Statistic, + _named_statistics, + _standard_deviation, + _standard_error, +) +from .tables import ( + FEASIBLE, + JUDGMENT, + draw_resamples, + feasible_records, + groups, + matrices, + names, + value_columns, + with_values, +) + +_NEGLIGIBLE = 1e-12 +"""The share of the sum of the magnitudes of its terms below which a variance +combined from the covariances of groups is zero (rather than the error of +rounding of terms that cancel).""" + + +def _bootstrap_error( + sums: np.ndarray, squares: np.ndarray, n: np.ndarray +) -> np.ndarray: + """ + Gets the standard errors of statistics from the sums of their values (and + of their squares) over the resamples of a bootstrap in which each is + known (`n`, of each): their standard deviations over these resamples + (`NaN` with fewer than two). + """ + n = np.asarray(n, dtype=float) + with np.errstate(invalid="ignore", divide="ignore"): + mean = sums / n + variance = np.maximum(squares - n * mean**2, 0.0) / (n - 1) + return np.where(n >= 2, np.sqrt(variance), np.nan) + + +def _replicates_of(feasible: pd.DataFrame, infeasible: pd.DataFrame) -> pd.Index: + """Gets the replicates of feasible and infeasible records, in order.""" + return pd.Index(sorted({*feasible["replicate"], *infeasible["replicate"]})) + + +def _feasibility( + feasible: pd.DataFrame, + infeasible: pd.DataFrame, + designs: pd.Index, + replicates: pd.Index, +) -> np.ndarray: + """ + Gets the feasibility of each design (rows) in each replicate (columns): 1 + if it has feasible records, 0 if it has infeasible ones, and `NaN` if it + has none. + """ + matrix = np.full((len(designs), len(replicates)), np.nan) + for records, flag in ((infeasible, 0.0), (feasible, 1.0)): + rows = designs.get_indexer(records["design"]) + columns = replicates.get_indexer(records["replicate"]) + known = (rows >= 0) & (columns >= 0) + matrix[rows[known], columns[known]] = flag + return matrix + + +def _evaluate( + statistics: Mapping[str, Statistic], + values: Mapping[str, np.ndarray], + columns: np.ndarray | None = None, +) -> dict[str, np.ndarray]: + """ + Computes statistics of each design from the values of the columns of the + results in its replicates (of the replicates `columns`, or all). + """ + computed = {} + for name, statistic in statistics.items(): + matrix = statistic.values_of(values) + computed[name] = statistic.reduce( + matrix if columns is None else matrix[:, columns] + ) + return computed + + +def _across_groups(results: pd.DataFrame, across: Across | None) -> list | None: + """ + Gets the groups of results (values of a column, in order) across which + criteria combine statistics, if any. + """ + if across is None: + return None + if across.column not in results.columns: + raise ValueError( + f"the results have no column {across.column!r} to combine across " + + "(such as the scenarios of a study, see Study)" + ) + return list(pd.unique(results[across.column])) + + +def _attributed( + infeasible: pd.DataFrame, by: Sequence[str], key: Sequence[Any] +) -> pd.DataFrame: + """ + Gets the infeasible records of a group of the columns `by` (of the values + `key`): those of its values, or without a value (such as a sensor, which + an infeasible evaluation does not give), which are of every group. + """ + if not by or infeasible.empty: + return infeasible + mask = np.ones(len(infeasible), dtype=bool) + for column, value in zip(by, key): + values = infeasible[column] + mask &= ((values == value) | values.isna()).to_numpy() + return infeasible[mask] + + +def _covariances( + a: np.ndarray, b: np.ndarray +) -> tuple[np.ndarray, np.ndarray, np.ndarray, np.ndarray]: + """ + Gets the sample covariance of the values of each design (rows) in two + groups over the replicates (columns) in which both have values, and the + numbers of these replicates and of the values of each group (the + covariance is `NaN` with fewer than two shared replicates). + """ + both = ~np.isnan(a) & ~np.isnan(b) + shared = both.sum(axis=1) + counts = (~np.isnan(a)).sum(axis=1), (~np.isnan(b)).sum(axis=1) + x, y = np.where(both, a, 0.0), np.where(both, b, 0.0) + with np.errstate(invalid="ignore", divide="ignore"): + mx = x.sum(axis=1) / shared + my = y.sum(axis=1) / shared + products = np.where(both, (x - mx[:, None]) * (y - my[:, None]), 0.0) + covariance = products.sum(axis=1) / (shared - 1) + covariance = np.where(shared > 1, covariance, np.nan) + return covariance, shared, *counts + + +def _spread_of_mean( + parts: Sequence[np.ndarray], weights: np.ndarray +) -> tuple[np.ndarray, np.ndarray]: + """ + Gets the spread of the weighted mean of the means of the values of each + design (rows) in groups (`parts`) over their replicates (columns), from + the covariances of the groups over the replicates they share (none + between groups without shared replicates): the standard deviation of the + weighted sum of the values of a replicate, and the standard error of the + weighted mean of the groups' means. + """ + if len(parts) == 1: + # the spread of the replicates of one group + return _standard_deviation(parts[0]), _standard_error(parts[0]) + # the variance of the weighted sum, and the squared standard error, from + # terms whose magnitudes tell rounding from a variance + totals = np.zeros((2, len(parts[0]))) + magnitudes = np.zeros((2, len(parts[0]))) + for s, a in enumerate(parts): + for t, b in enumerate(parts): + covariance, shared, n_a, n_b = _covariances(a, b) + if s != t: + covariance = np.nan_to_num(covariance) + weighted = weights[s] * weights[t] * covariance + with np.errstate(invalid="ignore", divide="ignore"): + terms = np.vstack([weighted, weighted * shared / (n_a * n_b)]) + totals += terms + magnitudes += np.abs(terms) + totals = np.where(totals <= _NEGLIGIBLE * magnitudes, 0.0, totals) + return np.sqrt(totals[0]), np.sqrt(totals[1]) + + +class _Statistics: + """ + The statistics of the designs of the feasible results of a group (of the + criteria's `by`), over every replicate or some of them (see `evaluate`), + from the values of their metrics in each replicate: in each group of a + column, combined across the groups (see `Across`), or, without criteria + across a column, in one group of every result. Designs without feasible + results in every group are left out. + + The statistics of the feasibility of replicates (`feasible`, see + `summarize`) are over the replicates of the feasible and infeasible + records of the designs, and, across groups, over those of every group + together (they are not combined). + + Args: + results (pandas.DataFrame): The feasible results of a group. + statistics (Mapping[str, Statistic]): The statistics, by name. + criteria (Criteria | None): The criteria (of the requirements, and + of the rule that combines the groups of a column), if any. + levels (Sequence | None): The groups of the column (of every result) + that the criteria combine, if any. + infeasible (pandas.DataFrame | None): The infeasible results of the + group, if any. + """ + + def __init__( + self, + results: pd.DataFrame, + statistics: Mapping[str, Statistic], + criteria: Criteria | None = None, + levels: Sequence | None = None, + infeasible: pd.DataFrame | None = None, + ): + self.statistics, self.criteria = statistics, criteria + across = None if criteria is None else criteria.across + infeasible = results.iloc[:0] if infeasible is None else infeasible + columns = {c for statistic in statistics.values() for c in statistic.columns} + metrics = sorted(columns - {FEASIBLE}) + # statistics of the feasibility alone are over every group together + self.pooled = { + name + for name, statistic in statistics.items() + if set(statistic.columns) == {FEASIBLE} + } + if across is None: + # one group of every result, whose statistics are its own + column, self.combiners = None, {} + parts, failures = [results], [infeasible] + self.weights = np.ones(1) + else: + column, self.combiners = across.column, _combiners(criteria) + parts = [results[(results[column] == group).to_numpy()] for group in levels] + failures = [ + infeasible[(infeasible[column] == group).to_numpy()] for group in levels + ] + self.weights = _weights_of(across, levels) + designs = results["design"].drop_duplicates() + if len(parts) > 1: + # the designs with feasible results in every group + complete = set.intersection(*(set(part["design"]) for part in parts)) + designs = designs[designs.isin(complete)] + self.designs = pd.Index(designs) + failures = [failed[failed["design"].isin(self.designs)] for failed in failures] + self.replicates = _replicates_of(results, pd.concat(failures)) + self.matrices = [] + for part, failed in zip(parts, failures): + values = matrices(part, metrics, self.designs, self.replicates)[2] + values[FEASIBLE] = _feasibility(part, failed, self.designs, self.replicates) + self.matrices.append(values) + # the fewest replicates of a design in any group + counts = results.groupby(["design", *([] if column is None else [column])])[ + "replicate" + ].nunique() + if column is not None: + counts = counts.groupby(level="design").min() + self.counts = counts.reindex(self.designs).to_numpy() + + def _pooled(self, statistic: Statistic, columns: np.ndarray | None) -> np.ndarray: + """ + Computes a statistic over the replicates (`columns`, or all) of every + group together. + """ + matrix = np.hstack([statistic.values_of(m) for m in self.matrices]) + if columns is not None: + n = len(self.replicates) + matrix = matrix[ + :, np.concatenate([columns + k * n for k in range(len(self.matrices))]) + ] + return statistic.reduce(matrix) + + def violation(self, values: Mapping[str, np.ndarray]) -> np.ndarray: + """Gets the total violation of the requirements of the criteria.""" + if self.criteria is None: + return np.zeros(len(self.designs)) + return _violation(self.criteria, values, len(self.designs)) + + def evaluate( + self, columns: np.ndarray | None = None + ) -> tuple[dict[str, np.ndarray], np.ndarray]: + """ + Computes the statistics of each design (of the replicates `columns` + of the matrices, or all) and the total violation of the requirements. + """ + combined = { + name: statistic + for name, statistic in self.statistics.items() + if name not in self.pooled + } + parts = [_evaluate(combined, m, columns) for m in self.matrices] + values = {} + for name, statistic in self.statistics.items(): + if name in self.pooled: + values[name] = self._pooled(statistic, columns) + continue + if len(parts) == 1: + values[name] = parts[0][name] + continue + stacked = np.vstack([part[name] for part in parts]) + how = self.combiners.get(name, "mean") + if how == "max": + values[name] = stacked.max(axis=0) + elif how == "min": + values[name] = stacked.min(axis=0) + else: + values[name] = self.weights @ stacked + return values, self.violation(values) + + def judged(self, columns: np.ndarray) -> np.ndarray: + """ + Gets whether each design has a feasible record among some replicates + (`columns`) in every group, without which it is not judged by them. + """ + found = np.ones(len(self.designs), dtype=bool) + for values in self.matrices: + found &= np.any(values[FEASIBLE][:, columns] == 1, axis=1) + return found + + def recorded(self, columns: np.ndarray) -> np.ndarray: + """ + Gets whether each design has a record (feasible or not) among some + replicates (`columns`), in any group. + """ + found = np.zeros(len(self.designs), dtype=bool) + for values in self.matrices: + found |= np.any(~np.isnan(values[FEASIBLE][:, columns]), axis=1) + return found + + def spread(self, name: str, statistic: Statistic) -> tuple[np.ndarray, np.ndarray]: + """ + Computes the spread of a mean of a metric (of a name) over the + replicates of each design: its standard deviation and standard error + (see `summarize`), and, across groups, those of the statistic of the + groups that it combines into. + """ + parts = [statistic.values_of(m) for m in self.matrices] + how = self.combiners.get(name, "mean") + if how in ("max", "min"): + # the spread of the group of the worst value + means = np.vstack([statistic.reduce(part) for part in parts]) + deviations = np.vstack([_standard_deviation(part) for part in parts]) + errors = np.vstack([_standard_error(part) for part in parts]) + filled = np.where( + np.isnan(means), -np.inf if how == "max" else np.inf, means + ) + chosen = filled.argmax(axis=0) if how == "max" else filled.argmin(axis=0) + rows = np.arange(len(self.designs)) + missing = np.isnan(means).any(axis=0) + return ( + np.where(missing, np.nan, deviations[chosen, rows]), + np.where(missing, np.nan, errors[chosen, rows]), + ) + return _spread_of_mean(parts, self.weights) + + +def _summary_groups( + results: pd.DataFrame, + statistics: Mapping[str, Statistic], + by: Sequence[str], + criteria: Criteria | None = None, + design_columns: Sequence[str] | None = None, +) -> Iterator[tuple[pd.DataFrame, _Statistics]]: + """ + Iterates over the groups (of the columns `by`) of the feasible results of + a study, for summaries of their designs: a data frame of the designs of + each group (`design`, the values of `by`, and the values of the designs, + see `summarize`: those of `design_columns`, or, if `None`, those that are + the same in every feasible record of a design), and their statistics + (see `_Statistics`). Results without a feasible record have no groups. + """ + feasible, infeasible = feasible_records(results) + if feasible.empty: + return + across = None if criteria is None else criteria.across + combined = _across_groups(results, across) + grouped = [*by, *([] if across is None else [across.column])] + columns = value_columns(results, statistics, grouped, design_columns) + for key, positions in groups(feasible, by): + group = feasible.iloc[positions] + failed = _attributed(infeasible, by, key) + table = _Statistics(group, statistics, criteria, combined, failed) + frame = pd.DataFrame({"design": table.designs}) + for name, value in zip(by, key): + frame[name] = value + with_values(frame, group, table.designs, columns) + yield frame, table + + +def _criteria_of( + criteria: Criteria | Mapping[str, str] | None, + statistics: Mapping[str, Statistic | str] | Sequence | None, + by: Sequence[str] | str, +) -> tuple[Criteria | None, dict[str, Statistic], tuple[str, ...]]: + """ + Gets the criteria (if any) of the arguments of `summarize`, the + statistics to compute (by name), and the columns that group records. + """ + by = tuple(names(by)) + extra = _named_statistics(statistics) + if criteria is None: + if not extra: + raise ValueError( + "give criteria, or the statistics (or metrics, whose means they " + + "are) to summarize as `statistics`" + ) + return None, extra, by + if isinstance(criteria, Mapping) and not all( + isinstance(value, str) for value in criteria.values() + ): + # statistics given as criteria (strings that are not directions, such + # as "minimize", are misspelled directions, which Criteria rejects) + raise ValueError( + "a mapping of criteria gives the directions of objectives ('min' or " + + "'max'): give statistics by name as `statistics`" + ) + judged = _as_criteria(criteria) + if by: + if isinstance(criteria, Criteria): + raise ValueError( + "criteria group records by their own `by`: give it to the criteria" + ) + judged = replace(judged, by=by) + if extra: + clashes = sorted( + name + for name in extra + if name in judged.names and _statistic(judged, name) != extra[name] + ) + if clashes: + raise ValueError(f"statistics that the criteria name otherwise: {clashes}") + judged = replace(judged, statistics={**judged.statistics, **extra}) + return judged, _resolved(judged), judged.by + + +def _with_feasibility(statistics: Mapping[str, Statistic]) -> dict[str, Statistic]: + """ + Gets statistics with the share of the replicates of each design that are + feasible (`feasible`), unless a statistic has the name. + """ + if FEASIBLE in statistics: + return dict(statistics) + return {**statistics, FEASIBLE: Mean(FEASIBLE)} + + +def _spreads(statistics: Mapping[str, Statistic]) -> dict[str, list[str]]: + """ + Gets the columns of the spreads of the means of metrics (a column, or a + metric computed from others, such as a `Utility`) among statistics (by + name): their standard deviations and standard errors (` std` and + ` se`), but those that statistics name. + """ + return { + name: [ + column + for column in (f"{name} std", f"{name} se") + if column not in statistics + ] + for name, statistic in statistics.items() + if type(statistic) is Mean and FEASIBLE not in statistic.columns + } + + +def _ordered( + statistics: Mapping[str, Statistic], added: Mapping[str, Sequence[str]] +) -> list[str]: + """Gets the columns of statistics, each followed by those `added` to it + (such as its spreads).""" + return [column for name in statistics for column in (name, *added.get(name, ()))] + + +def _with_spreads( + values: dict[str, np.ndarray], + table: _Statistics, + statistics: Mapping[str, Statistic], + spreads: Mapping[str, Sequence[str]], +) -> None: + """Adds the spreads of means (see `_spreads`) to the values of a group.""" + for name, columns in spreads.items(): + deviation, error = table.spread(name, statistics[name]) + for column, value in ((f"{name} std", deviation), (f"{name} se", error)): + if column in columns: + values[column] = value + + +def _check_names( + statistics: Mapping[str, Statistic], + results: pd.DataFrame, + added: Sequence[str] = (), +) -> None: + """ + Checks that no statistic but the mean of a metric (of its name), and no + column `added` to a summary (such as a standard error), has the name of + a column of the results, which it would be taken for (such as a + probability over the replicates for the share of the histories of a + replicate that meet a requirement, see `summarize_histories`). + """ + clashes = sorted( + { + *( + name + for name, statistic in statistics.items() + if name in results.columns and statistic != Mean(name) + ), + *(name for name in added if name in results.columns), + } + ) + if clashes: + raise ValueError( + f"statistics with the names of columns of the results: {clashes} (a " + + "statistic of a column's name is its mean): give them other names" + ) + + +def _judge( + frame: pd.DataFrame, + values: Mapping[str, np.ndarray], + violation: np.ndarray, + criteria: Criteria, +) -> None: + """ + Adds the judgment of designs by criteria to the rows of a summary of + them, from the values of their statistics and the violation of the + criteria's requirements: the `violation`, whether each design meets the + requirements (`meets_requirements`), and whether it is efficient among + those that do (`pareto`). + """ + meets = violation == 0 + violations, requirements, front = JUDGMENT + frame[violations] = violation + frame[requirements] = meets + frame[front] = efficient(_costs(criteria, values), meets, _tolerances(criteria)) + + +def _assemble( + frame: pd.DataFrame, + table: _Statistics, + values: Mapping[str, np.ndarray], + violation: np.ndarray, + criteria: Criteria | None, +) -> pd.DataFrame: + """ + Adds to the rows of the designs of a group (of `_summary_groups`) their + statistics (and the other columns of `values`, in order), the number of + their feasible `replicates`, the share of their replicates that are + feasible (`feasible`), and their judgment by criteria (if any, see + `_judge`). + """ + for name, value in values.items(): + if name != FEASIBLE: + frame[name] = value + frame["replicates"] = table.counts + frame[FEASIBLE] = values[FEASIBLE] + if criteria is not None: + _judge(frame, values, violation, criteria) + return frame + + +def _summaries( + frames: Sequence[pd.DataFrame], + by: Sequence[str], + columns: Sequence[str], + criteria: Criteria | None, + after: Sequence[str] = (), +) -> pd.DataFrame: + """ + Gets a summary of the frames of its groups (see `_assemble`), or an empty + one of its columns (without the values of designs) if there are none, + such as of results without a feasible record: the `columns` of + statistics, `replicates`, `feasible`, the judgment (with criteria), and + the columns `after`. + """ + if frames: + return pd.concat(frames, ignore_index=True) + dtypes = { + "design": object, + **{column: object for column in by}, + **{name: float for name in columns if name != FEASIBLE}, + "replicates": int, + FEASIBLE: float, + } + if criteria is not None: + dtypes.update(zip(JUDGMENT, (float, bool, bool))) + dtypes.update({column: float for column in after}) + return pd.DataFrame( + {column: pd.Series(dtype=dtype) for column, dtype in dtypes.items()} + ) + + +def _without_constant(summary: pd.DataFrame, columns: Sequence[str]) -> pd.DataFrame: + """ + Removes the columns of spreads (such as standard errors) of a summary + that are zero (or `NaN`) for every design, such as of a metric that is + the same in every replicate of each design (a summary without designs + keeps them). + """ + if summary.empty: + return summary + constant = [ + column + for column in columns + if column in summary.columns + and (summary[column].fillna(0.0).to_numpy(dtype=float) == 0).all() + ] + return summary.drop(columns=constant) + + +def _summarize( + results: pd.DataFrame, + criteria: Criteria | Mapping[str, str] | None = None, + *, + statistics: Mapping[str, Statistic | str] | Sequence | None = None, + by: Sequence[str] | str = (), + spread: bool = False, + design_values: bool = True, +) -> pd.DataFrame: + """ + Summarizes results by the statistics of their designs (see `summarize`), + as the steps of trade studies judge designs: without spreads by default + (the summaries that steps give have them, as `summarize` does), and, + without `design_values`, without the values of the designs (only their + keys, `design`), which saves finding them. + """ + judged, resolved, by = _criteria_of(criteria, statistics, by) + statistics = _with_feasibility(resolved) + spreads = _spreads(statistics) if spread else {} + added = [column for columns in spreads.values() for column in columns] + _check_names(statistics, results, added) + order = _ordered(statistics, spreads) + frames = [] + for frame, table in _summary_groups( + results, statistics, by, judged, None if design_values else [] + ): + values, violation = table.evaluate() + _with_spreads(values, table, statistics, spreads) + ordered = {name: values[name] for name in order} + frames.append(_assemble(frame, table, ordered, violation, judged)) + summary = _summaries(frames, by, order, judged) + return _without_constant(summary, added) + + +def summarize( + results: pd.DataFrame, + criteria: Criteria | Mapping[str, str] | None = None, + *, + statistics: Mapping[str, Statistic | str] | Sequence | None = None, + by: Sequence[str] | str = (), + spread: bool = True, +) -> pd.DataFrame: + """ + Summarizes the results of a study (see `Study.run`, a row per replicate) + with a row per design (and per group of the columns `by`, such as a + sensor): statistics over the feasible replicates of each design, the + spread of each that is the mean of a metric (with `spread`), the number + of these `replicates`, the share of its replicates that are feasible + (`feasible`), and the values of the design (see `Design.flat`), from + which `DesignSpace.designs_of` rebuilds the designs. + + The statistics are those of criteria (see `Criteria`, or a mapping of + objectives to their directions, which are the means of the metrics of + their names), and other `statistics`: a sequence of statistics or + metrics (a metric given as a string, or a `Utility`, is its mean), + named by their conventional names (see `Statistic.name`), or a mapping + of names to them:: + + summarize(results, {"satellites": "min", "sufficient": "max"}) + summarize(results, statistics=["sufficient", "accurate"]) + summarize(results, statistics=[Quantile("cost", 0.7)]) # cost p70 + summarize(results, COST, statistics=["cost development"]) + + A statistic of the name of a column of the results is the mean of the + column: any other statistic of the name raises an error, as its values + would be taken for those of the column. + + The spread of a mean of a metric (a column, or a metric computed from + others, such as a `Utility`) follows it: the standard deviation + (` std`) and the standard error (` se`) between the + replicates. A spread that is zero for every design (of a metric that is + the same in every replicate of each design, such as a number of + satellites, or of designs with one replicate) is left out (but those of + a summary without designs). + + With criteria, the summary also gives the `violation` of their + requirements (the sum of the violations, see `Requirement`, 0 if the + design meets them all), whether the design meets them + (`meets_requirements`), and whether it is efficient among the designs + that do (`pareto`, see `pareto_front`, in each group of the criteria's + `by`; a design with a missing objective, `NaN`, is not):: + + summary = summarize(results, criteria) + front = summary[summary.pareto] + + Criteria `across` the groups of a column (such as scenarios, see + `Across`) combine the statistics of each design across its groups, of + which `replicates` is the fewest of any group. The spread of a combined + statistic is that of the worst group's value (of the worst), or, of a + weighted mean, the standard deviation of the weighted sum of the values + of a replicate in each group and the standard error of the weighted mean + of the groups' means, from the covariances of the groups over the + replicates they share (the same replicate in every group, in which it + has the same uncertain parameters, see `Study`), so that what the groups + share cancels. Groups without shared replicates are independent: the + standard error is then the square root of the weighted sum of the + squared standard errors of the groups (by the squared weights). + + Designs are judged by their feasible replicates. `feasible` is a + statistic over every replicate of a design (the mean of the feasibility + of each, 1 or 0, see `Statistic`), and across the groups of criteria + `across` a column, over the replicates of every group together, which + requirements may name: `Requirement("feasible", ">=", 1)` requires every + replicate to be feasible. In groups of columns `by` that infeasible + records lack (such as a sensor, which an infeasible evaluation does not + give), the infeasible replicates of a design count in each of its groups. + Designs without a feasible replicate (in a group) are infeasible, and are + left out: a summary of results without a feasible record is empty. + + The results must have one record per evaluation (a design in a + replicate) in each group (and in each group of the column of the + criteria's `across`). + + Args: + results (pandas.DataFrame): The results. + criteria (Criteria | Mapping[str, str] | None): The criteria, or the + objectives (metrics whose means they are) and their directions + (`"min"` or `"max"`), if any. + statistics (Mapping[str, Statistic | str] | Sequence | None): Other + statistics: a sequence of statistics (or metrics, whose means + they are), named by their conventional names, or a mapping of + names to them. + by (Sequence[str] | str): The columns that group records of an + evaluation (those of the criteria, if they have any). + spread (bool): `True` to give the spreads of means. + + Returns: + pandas.DataFrame: a row per feasible design (and group) + + Raises: + TypeError: if the criteria are neither criteria nor a mapping of + directions (give metrics as `statistics`). + ValueError: if a statistic other than the mean of a column has the + column's name, or the results have several records of an + evaluation (in a group). + """ + return _summarize(results, criteria, statistics=statistics, by=by, spread=spread) + + +def pareto_probability( + results: pd.DataFrame, + criteria: Criteria | Mapping[str, str], + *, + n_resamples: int = 500, + seed: int = 0, +) -> pd.DataFrame: + """ + Estimates the probability that each design is Pareto-efficient by + criteria (and meets their requirements, if any), given the uncertainty + of its replicates, by a bootstrap: each resample draws replicates with + replacement, the same replicates for every design (which keeps the + correlation between designs of common random numbers, see + `Design.realize`), computes the statistics of each design over the drawn + replicates, and finds the front of the designs that meet the + requirements (in each group of the criteria's `by`). The probability is + the share of resamples in which a design is on that front. + + Designs that are efficient with a probability between 0 and 1 are those + whose efficiency the replicates do not settle: more replicates (see + `refine`) would settle it, unless designs differ by less than matters (as + near saturation), which a tolerance of the objectives settles: designs + within the tolerances of the front are efficient (see `pareto_front`). + With few replicates, the bootstrap has few distinct resamples and + understates the uncertainty. Designs may have different replicates (as + after `refine`): replicates are drawn from all of them, each design's + statistics are those of its drawn replicates, and a design none of whose + replicates is drawn keeps the statistics of all of them. With criteria + `across` the scenarios of a study (see `Across`), a drawn replicate is + drawn in every scenario, in which it has the same uncertain parameters. + + Designs are judged by their feasible replicates, and the replicates in + which a design is infeasible are drawn too: the statistics of a resample + are those of the drawn replicates in which the design is feasible, and + the share of its replicates that are feasible (`feasible`, see + `summarize`) is that of the drawn replicates. A design whose drawn + replicates are all infeasible (in a scenario, with criteria `across` + scenarios) is not judged in the resample: it neither meets the + requirements nor is efficient. + + Args: + results (pandas.DataFrame): The results of a study (see + `Study.run`), with a record per replicate of each design (and + group of the criteria's `by`). + criteria (Criteria | Mapping[str, str]): The criteria, or the + objectives (metrics whose means they are) and their directions + (`"min"` or `"max"`). + n_resamples (int): The number of resamples (at least 2). + seed (int): The seed of the resamples. + + Returns: + pandas.DataFrame: a row per feasible design (and group), empty + without one: the summary of the criteria over every replicate + (see `summarize`, with the spreads of means), in which each + objective that is not a mean (such as a quantile) is followed by + its standard error, its standard deviation over the resamples + in which the design is judged (` se`, `NaN` with + fewer than two, and left out if it is zero for every design, as + `summarize` leaves out spreads), and the probability that the + design is efficient (`pareto_probability`) and that it meets the + requirements (`requirements_probability`) + + Raises: + ValueError: if a statistic other than the mean of a column has the + column's name, or the results have several records of an + evaluation (in a group). + """ + criteria = _as_criteria(criteria) + statistics = _with_feasibility(_resolved(criteria)) + spreads = _spreads(statistics) + # the standard errors of the objectives that are not means, by the bootstrap + booted = [ + name + for name in criteria.objectives + if name not in spreads and f"{name} se" not in statistics + ] + added = {**spreads, **{name: [f"{name} se"] for name in booted}} + columns = [column for spread in added.values() for column in spread] + _check_names(statistics, results, columns) + order = _ordered(statistics, added) + tolerances = _tolerances(criteria) + rng = np.random.default_rng(seed) + frames = [] + for frame, table in _summary_groups(results, statistics, criteria.by, criteria): + values, violation = table.evaluate() + counts = np.zeros(len(table.designs)) + met = np.zeros(len(table.designs)) + # the sums of the objectives (and of their squares) over the resamples + # in which they are known (in which each design is judged) + sums = {name: np.zeros(len(table.designs)) for name in booted} + squares = {name: np.zeros(len(table.designs)) for name in booted} + known = {name: np.zeros(len(table.designs)) for name in booted} + for drawn in draw_resamples(len(table.replicates), n_resamples, rng): + sample, sample_violation = table.evaluate(drawn) + # designs without a drawn replicate keep the statistics of all of + # theirs, and those without a feasible one are not judged + undrawn = ~table.recorded(drawn) + for name in sample: + sample[name][undrawn] = values[name][undrawn] + sample_violation[undrawn] = violation[undrawn] + judged = table.judged(drawn) | undrawn + meets = (sample_violation == 0) & judged + counts += efficient(_costs(criteria, sample), meets, tolerances) + met += meets + for name in booted: + value = sample[name] + found = ~np.isnan(value) + sums[name] += np.where(found, value, 0.0) + squares[name] += np.where(found, value, 0.0) ** 2 + known[name] += found + computed = dict(values) + _with_spreads(computed, table, statistics, spreads) + for name in booted: + computed[f"{name} se"] = _bootstrap_error( + sums[name], squares[name], known[name] + ) + ordered = {name: computed[name] for name in order} + _assemble(frame, table, ordered, violation, criteria) + frame["pareto_probability"] = counts / n_resamples + frame["requirements_probability"] = met / n_resamples + frames.append(frame) + summary = _summaries( + frames, + criteria.by, + order, + criteria, + after=["pareto_probability", "requirements_probability"], + ) + return _without_constant(summary, columns) diff --git a/src/tatc/tradespace/tables.py b/src/tatc/tradespace/tables.py new file mode 100644 index 0000000..5a8a6b9 --- /dev/null +++ b/src/tatc/tradespace/tables.py @@ -0,0 +1,343 @@ +""" +Tables of trade studies: the results of a study (a row per evaluation, a +design in a replicate) and the summaries of its designs (a row per design): +their columns, their groups, the values of the metrics of designs in each +replicate, the values of designs, and checks that a table has the rows that +a function needs. + +@author: Paul T. Grogan +""" + +from __future__ import annotations + +from collections.abc import Iterable, Iterator, Mapping, Sequence +from typing import Any + +import numpy as np +import pandas as pd + +from .space import STATUS_COLUMNS + +FEASIBLE = "feasible" +"""The column of the results of a study of whether each record is feasible, +and the statistic (and column of summaries) of the share of a design's +replicates that are feasible (see `summarize`).""" + +JUDGMENT = ("violation", "meets_requirements", "pareto") +"""The columns of the judgment of designs by criteria in their summaries (see +`summarize`).""" + +SEPARATE = ( + "give the columns that separate them as `by` (of the criteria), or combine " + + "their groups `across` (see Across)" +) +"""How to separate several records of an evaluation for criteria.""" + +SUMMARIZE = ( + "summarize the results of a study (a row per replicate) first, with a row " + + "per design (see summarize), or select the rows of one group (such as those " + + "of a scenario)" +) +"""How to give each design one row, rather than the results of a study (a +row per replicate).""" + + +def names(value: str | Iterable[str]) -> list[str]: + """ + Gets names given as a name or a sequence of names. + + Args: + value (str | Iterable[str]): The name, or names. + + Returns: + list[str]: the names + """ + return [value] if isinstance(value, str) else list(value) + + +def groups(frame: pd.DataFrame, by: Sequence[str]) -> Iterator[tuple[tuple, Any]]: + """ + Iterates over the groups of a data frame by columns (or the frame, if + none): the values of the columns, and the positions of the group's rows. + Rows without a value of a column (`NaN` or `None`) are a group of their + own, rather than left out. + + Args: + frame (pandas.DataFrame): The data frame. + by (Sequence[str]): The columns. + + Returns: + Iterator[tuple[tuple, numpy.ndarray]]: the values and positions of + each group + + Raises: + ValueError: if the frame lacks a column. + """ + if not by: + yield (), np.arange(len(frame)) + return + missing = [column for column in by if column not in frame.columns] + if missing: + raise ValueError(f"no columns {missing} to group by") + grouped = frame.groupby(list(by), sort=False, dropna=False) + for key, positions in grouped.indices.items(): + yield (key if isinstance(key, tuple) else (key,)), positions + + +def check_summary( + summary: pd.DataFrame, by: Sequence[str] = (), hint: str = SUMMARIZE +) -> None: + """ + Checks that a data frame is a summary of designs (a row per design, in + each group of the columns `by`), not the results of a study (a row per + replicate), which the functions of summaries would judge as if each + replicate were a design. + + Args: + summary (pandas.DataFrame): The data frame. + by (Sequence[str]): The columns of groups, in each of which a design + may have a row. + hint (str): What to do if the data frame is not a summary. + + Raises: + ValueError: if the data frame has several rows of a design (in a + group), with the hint. + """ + if "design" in summary.columns: + keys = summary[["design", *(c for c in by if c in summary.columns)]] + elif summary.index.name == "design" and not by: + keys = summary.index.to_frame() + else: + return + if keys.duplicated().any(): + raise ValueError(f"the data frame has several rows of a design: {hint}") + + +def check_records( + results: pd.DataFrame, + keys: Sequence[str] = ("design", "replicate"), + hint: str = SEPARATE, + metrics: Sequence[str] = (), +) -> None: + """ + Checks that results have one record per evaluation (a design in a + replicate, or a combination of the values of other `keys`). + + Args: + results (pandas.DataFrame): The results. + keys (Sequence[str]): The columns of an evaluation. + hint (str): How to separate several records of an evaluation. + metrics (Sequence[str]): The metrics, whose values may differ + between the records of an evaluation without separating them. + + Raises: + ValueError: if the results have several records of an evaluation, + with the hint and the columns whose values differ between them + (which may separate them). + """ + keys = list(keys) + if not results.duplicated(keys).any(): + return + candidates = [ + column + for column in results.columns + if column not in (*STATUS_COLUMNS, *keys, *metrics) or column == "scenario" + ] + varying: list[str] = [] + if candidates: + counts = results.groupby(keys)[candidates].nunique(dropna=False).max() + varying = list(counts.index[counts > 1]) + raise ValueError( + "the results have several records of an evaluation (a design in a " + + f"replicate): {hint}" + + (f", such as {varying}" if varying else "") + ) + + +def matrices( + group: pd.DataFrame, + columns: Sequence[str], + designs: pd.Index | None = None, + replicates: pd.Index | None = None, + hint: str = SEPARATE, +) -> tuple[pd.Index, pd.Index, dict[str, np.ndarray]]: + """ + Gets the values of metrics of each design (rows) in each replicate + (columns) of the results of a group, which must have one record per + evaluation (see `check_records`): of the designs and replicates of the + group, or of those given (`NaN` without a record). + + Args: + group (pandas.DataFrame): The results. + columns (Sequence[str]): The metrics. + designs (pandas.Index | None): The designs (keys), or `None` for + those of the results, in order. + replicates (pandas.Index | None): The replicates, or `None` for those + of the results, sorted. + hint (str): How to separate several records of an evaluation. + + Returns: + tuple[pandas.Index, pandas.Index, dict[str, numpy.ndarray]]: the + designs, the replicates, and the values of each metric (shape + (designs, replicates)) + + Raises: + ValueError: if the results lack a metric, or have several records + of an evaluation. + """ + missing = [column for column in columns if column not in group.columns] + if missing: + raise ValueError(f"metrics that are not in the results: {missing}") + check_records(group, hint=hint, metrics=columns) + if designs is None: + designs = pd.Index(group["design"].drop_duplicates()) + if replicates is None: + replicates = pd.Index(sorted(group["replicate"].unique())) + values = {} + for column in columns: + table = group.pivot(index="design", columns="replicate", values=column) + values[column] = table.reindex(index=designs, columns=replicates).to_numpy( + dtype=float + ) + return designs, replicates, values + + +def feasible_records(results: pd.DataFrame) -> tuple[pd.DataFrame, pd.DataFrame]: + """ + Gets the feasible and the infeasible records of results (every record is + feasible without a column `feasible`). + + Args: + results (pandas.DataFrame): The results. + + Returns: + tuple[pandas.DataFrame, pandas.DataFrame]: the feasible records and + the infeasible ones + """ + if FEASIBLE not in results.columns: + return results, results.iloc[:0] + status = results[FEASIBLE].astype(bool).to_numpy() + return results[status], results[~status] + + +def _constant_columns(results: pd.DataFrame, excluded: set[str]) -> list[str]: + """ + Gets the columns (other than `excluded`) that are the same in every + record of each design. + """ + candidates = [column for column in results.columns if column not in excluded] + if not candidates or len(results) == 0: + return [] + constant = results.groupby("design")[candidates].nunique(dropna=False) + return [column for column in candidates if (constant[column] <= 1).all()] + + +def value_columns( + results: pd.DataFrame, + statistics: Mapping[str, Any], + by: Sequence[str], + design_columns: Sequence[str] | None, +) -> list[str]: + """ + Gets the columns of the values of designs that a summary of results + keeps: those given, or those that are the same in every feasible record + of each design (but the metrics of the statistics, the columns of groups, + and status columns), without the names of statistics and the columns of + groups. + + Args: + results (pandas.DataFrame): The results. + statistics (Mapping[str, Statistic]): The statistics of the summary, + by name. + by (Sequence[str]): The columns of groups (such as those of the + criteria's `by`, and the column they combine `across`). + design_columns (Sequence[str] | None): The columns of the values of + designs, or `None` for those that are the same in every feasible + record of a design. + + Returns: + list[str]: the columns + """ + if design_columns is None: + metrics = { + column for statistic in statistics.values() for column in statistic.columns + } + design_columns = _constant_columns( + feasible_records(results)[0], {*STATUS_COLUMNS, *metrics, *by} + ) + return [c for c in design_columns if c not in statistics and c not in by] + + +def with_values( + frame: pd.DataFrame, results: pd.DataFrame, designs: Any, columns: Sequence[str] +) -> None: + """ + Adds the values of designs (columns of the first record of each design of + results) to the rows of the designs (in order) of a data frame. + + Args: + frame (pandas.DataFrame): The data frame, a row per design. + results (pandas.DataFrame): The results. + designs (Any): The keys of the designs of the rows. + columns (Sequence[str]): The columns of the values of designs. + """ + first = results.drop_duplicates("design").set_index("design") + for column in columns: + frame[column] = first.loc[designs, column].to_numpy() + + +def design_values( + results: pd.DataFrame, designs: Sequence[str], columns: Sequence[str] +) -> pd.DataFrame: + """ + Gets the values of designs from their records in results (see + `with_values`). + + Args: + results (pandas.DataFrame): The results. + designs (Sequence[str]): The keys of the designs. + columns (Sequence[str]): The columns of the values of designs. + + Returns: + pandas.DataFrame: a row per design: its key (`design`), and its values + """ + frame = pd.DataFrame({"design": list(designs)}) + with_values(frame, results, list(designs), columns) + return frame + + +def draw_resamples(count: int, n_resamples: int, seed: Any) -> np.ndarray: + """ + Gets the replicates of each resample of a bootstrap: a row per resample of + `count` replicates (their positions) drawn with replacement. + + Args: + count (int): The number of replicates. + n_resamples (int): The number of resamples (at least 2). + seed (Any): The seed, or a random number generator, which draws them. + + Returns: + numpy.ndarray: the positions of the replicates (shape (n_resamples, + count)) + + Raises: + ValueError: if `n_resamples` is less than 2. + """ + if n_resamples < 2: + raise ValueError("n_resamples must be at least 2") + return np.random.default_rng(seed).integers(count, size=(n_resamples, count)) + + +def efficient_keys(summary: pd.DataFrame) -> list: + """ + Gets the keys of the efficient designs of a summary of criteria (whose + `pareto` is true, in any group), each once, in order. + + Args: + summary (pandas.DataFrame): The summary (see `summarize`). + + Returns: + list: the keys + """ + rows = summary["pareto"].to_numpy(dtype=bool) + return list(pd.unique(summary.loc[rows, "design"])) diff --git a/src/tatc/tradespace/utility.py b/src/tatc/tradespace/utility.py new file mode 100644 index 0000000..4cd3116 --- /dev/null +++ b/src/tatc/tradespace/utility.py @@ -0,0 +1,290 @@ +""" +Utility: the value of the metrics of designs to their stakeholders, as a +single-attribute utility of each metric (from 0 at its worst acceptable +value to 1 at its best) combined into a multi-attribute utility (by the +weights of the metrics, additively or in Keeney and Raiffa's multiplicative +form), for trade spaces of utility against cost (as in multi-attribute +tradespace exploration). + +A utility is a metric computed from others in each replicate (or each row +of a summary), so that statistics of it judge designs as statistics of any +metric do (see `Statistic`): its mean over the replicates is the expected +utility, whose curvature expresses an attitude to the risks that the +replicates draw. + +@author: Paul T. Grogan +""" + +from __future__ import annotations + +import math +from collections.abc import Callable, Mapping, Sequence +from dataclasses import dataclass +from typing import Any + +import numpy as np +import pandas as pd + + +def _normalized(values: Any, worst: float, best: float) -> np.ndarray: + """Gets values as shares of the way from the worst to the best, clipped + to [0, 1] (`NaN` kept).""" + share = (np.asarray(values, dtype=float) - worst) / (best - worst) + return np.clip(share, 0.0, 1.0) + + +@dataclass(frozen=True) +class LinearUtility: + """ + A single-attribute utility linear in the value of a metric: 0 at the worst + value and 1 at the best (and beyond them), for a metric to maximize + (`worst < best`) or to minimize (`worst > best`). + + Args: + worst (float): The worst acceptable value (utility 0). + best (float): The best value (utility 1). + """ + + worst: float + best: float + + def __post_init__(self): + if self.worst == self.best: + raise ValueError("the worst and best values must differ") + + def __call__(self, values: Any) -> np.ndarray: + return _normalized(values, self.worst, self.best) + + +@dataclass(frozen=True) +class ExponentialUtility: + """ + A single-attribute utility exponential in the value of a metric (of + constant absolute risk aversion): 0 at the worst value and 1 at the best, + and `(1 - exp(-risk z)) / (1 - exp(-risk))` between, where `z` is the share + of the way from the worst value to the best. A positive `risk` is averse + (concave: the first gains matter most, and a sure value is preferred to + a gamble of the same mean), a negative one is seeking (convex), and 0 is + linear (see `LinearUtility`). + + Args: + worst (float): The worst acceptable value (utility 0). + best (float): The best value (utility 1). + risk (float): The coefficient of risk aversion (of the shares `z`). + """ + + worst: float + best: float + risk: float = 0.0 + + def __post_init__(self): + if self.worst == self.best: + raise ValueError("the worst and best values must differ") + + def __call__(self, values: Any) -> np.ndarray: + share = _normalized(values, self.worst, self.best) + if self.risk == 0: + return share + return np.expm1(-self.risk * share) / math.expm1(-self.risk) + + +@dataclass(frozen=True) +class PiecewiseUtility: + """ + A single-attribute utility interpolated linearly between points (value, + utility), and constant beyond the first and last, such as a utility + elicited at a few values. + + Args: + points (Sequence[tuple[float, float]]): The points: values (distinct) + and their utilities (between 0 and 1). + """ + + points: Sequence[tuple[float, float]] + + def __post_init__(self): + points = tuple(sorted((float(x), float(u)) for x, u in self.points)) + if len(points) < 2: + raise ValueError("a piecewise utility needs at least two points") + values = [x for x, _ in points] + if len(set(values)) != len(values): + raise ValueError("the values of the points must be distinct") + if not all(0 <= u <= 1 for _, u in points): + raise ValueError("utilities must be between 0 and 1") + object.__setattr__(self, "points", points) + + def __call__(self, values: Any) -> np.ndarray: + array = np.asarray(values, dtype=float) + xs, us = zip(*self.points) + result = np.interp(array, xs, us) + return np.where(np.isnan(array), np.nan, result) + + +_FORMS = ("additive", "multiplicative") + + +def _scaling_constant(weights: Sequence[float]) -> float: + """ + Gets the scaling constant `K` of a multiplicative utility, the root other + than 0 of `1 + K = prod(1 + K k)` (0 if the weights sum to 1): between -1 + and 0 if they sum to more than 1, and positive if less. + """ + total = sum(weights) + if len(weights) < 2 or math.isclose(total, 1.0): + return 0.0 + + def excess(k: float) -> float: + return math.prod(1 + k * w for w in weights) - (1 + k) + + if total > 1: + low, high = -1.0 + 1e-12, -1e-12 + else: + low, high = 1e-12, 1.0 + while excess(high) < 0: + high *= 2 + for _ in range(200): + middle = (low + high) / 2 + if (excess(middle) > 0) == (excess(low) > 0): + low = middle + else: + high = middle + return (low + high) / 2 + + +@dataclass(frozen=True, eq=False) +class Utility: + """ + A multi-attribute utility of the metrics of a design: the single-attribute + utility of each metric (see `LinearUtility`, `ExponentialUtility`, and + `PiecewiseUtility`, or any function of the values that gives utilities + from 0 to 1), combined by weights: + + * `"additive"`: the weighted sum of the utilities (by weights normalized + to sum to 1), for metrics that are preferentially independent and whose + gains add. + * `"multiplicative"`: Keeney and Raiffa's multiplicative form, `1 + K U = + prod(1 + K k u)`, with the weights `k` (each between 0 and 1) the utility + of each metric at its best with the others at their worst, and `K` from + them: weights that sum to less than 1 make the metrics complements (a + design must do well in all), and more than 1 substitutes (doing well in + one suffices). + + A utility is a metric of statistics (such as `Mean(utility)`, its expected + value over the replicates, see `Statistic`), computed in each replicate + from its metrics. The expected utility suits replicates that draw risks + of a mission (such as cost growth, or failures): a concave utility then + penalizes the spread of outcomes, as a risk-averse stakeholder would. + Where the spread between replicates is noise of an estimate (such as of + a sample of points, see `attribute_variance`), the expected utility + penalizes the noise rather than the design: judge the utility of the + means instead (`utility(summary)`, of a summary of the means of the + metrics, see `summarize`). + + Args: + attributes (Mapping[str, Callable]): The single-attribute utility of + each metric. + weights (Mapping[str, float]): The weight of each metric. + form (str): `"additive"` or `"multiplicative"`. + """ + + attributes: Mapping[str, Callable[[Any], Any]] + weights: Mapping[str, float] + form: str = "additive" + + def __post_init__(self): + attributes, weights = dict(self.attributes), dict(self.weights) + if not attributes: + raise ValueError("a utility needs attributes") + if set(weights) != set(attributes): + raise ValueError( + "a utility needs a weight for each attribute, and no others" + ) + if self.form not in _FORMS: + raise ValueError(f"form must be one of {list(_FORMS)}, not {self.form!r}") + if any(not weight > 0 for weight in weights.values()): + raise ValueError("weights must be positive") + if self.form == "multiplicative" and any(w > 1 for w in weights.values()): + raise ValueError( + "the weights of a multiplicative utility must be at most 1" + ) + object.__setattr__(self, "attributes", attributes) + object.__setattr__( + self, "weights", {name: weights[name] for name in attributes} + ) + + def __eq__(self, other: object) -> bool: + return ( + isinstance(other, Utility) + and self.attributes == other.attributes + and self.weights == other.weights + and self.form == other.form + ) + + def __hash__(self) -> int: + return hash( + (tuple(self.attributes.items()), tuple(self.weights.items()), self.form) + ) + + @property + def columns(self) -> tuple[str, ...]: + """tuple[str, ...]: The metrics of the utility.""" + return tuple(self.attributes) + + @property + def scaling(self) -> float: + """float: The scaling constant `K` of a multiplicative utility (0 for + an additive one, or weights that sum to 1).""" + if self.form == "additive": + return 0.0 + return _scaling_constant(list(self.weights.values())) + + def evaluate(self, values: Mapping[str, Any]) -> np.ndarray: + """ + Computes the utility of values of the metrics (arrays of the same + shape, such as of designs by replicates). + + Args: + values (Mapping[str, Any]): The values of each metric. + + Returns: + numpy.ndarray: the utility of each value + """ + utilities = { + name: np.asarray(function(values[name]), dtype=float) + for name, function in self.attributes.items() + } + weights = self.weights + scaling = self.scaling + if scaling == 0.0: + total = sum(weights.values()) + return sum(weights[name] / total * u for name, u in utilities.items()) + product = np.ones_like(next(iter(utilities.values()))) + for name, u in utilities.items(): + product = product * (1 + scaling * weights[name] * u) + return (product - 1) / scaling + + def __call__(self, frame: pd.DataFrame | Mapping[str, Any]) -> Any: + """ + Computes the utility of each row of a data frame (such as the records + of a study, or a summary of the means of designs), or of values of + the metrics. + + Args: + frame (pandas.DataFrame | Mapping[str, Any]): The metrics. + + Returns: + pandas.Series | numpy.ndarray: the utility of each row (with the + frame's index), or of the values + """ + if isinstance(frame, pd.DataFrame): + missing = [name for name in self.columns if name not in frame.columns] + if missing: + raise ValueError( + f"metrics of the utility that are not columns: {missing}" + ) + values = {name: frame[name].to_numpy(dtype=float) for name in self.columns} + return pd.Series(self.evaluate(values), index=frame.index, name="utility") + return self.evaluate(frame) + + def __repr__(self) -> str: + return f"Utility({list(self.attributes)}, {self.form})" diff --git a/src/tatc/tradespace/values.py b/src/tatc/tradespace/values.py new file mode 100644 index 0000000..8c396fa --- /dev/null +++ b/src/tatc/tradespace/values.py @@ -0,0 +1,400 @@ +""" +Views of the values of designs, the scopes given to the callables of design +spaces, and the paths of values (see `Values`). + +@author: Paul T. Grogan +""" + +from __future__ import annotations + +import re +from collections.abc import Iterator, Mapping +from typing import Any + +import numpy as np + + +class _ChoiceValue: + """The value of a choice: the chosen branch and its value.""" + + __slots__ = ("choice", "value") + + def __init__(self, choice: str, value: Any = None): + self.choice, self.value = choice, value + + +class _RepeatValue: + """The value of a repetition: its count and its items.""" + + __slots__ = ("count", "items") + + def __init__(self, count: int): + self.count, self.items = count, [] + + +def _view(value: Any) -> Any: + """ + Wraps a decided value for attribute access. + """ + if isinstance(value, dict): + return Values(value) + if isinstance(value, _ChoiceValue): + return ChoiceValues(value) + if isinstance(value, _RepeatValue): + return RepeatValues(value) + return value + + +_SEGMENT = re.compile(r"\[(\d+)\]|([^.\[\]]+)") +"""A segment of a path: the index of an item (`[k]`) or a name.""" + + +def _segments(path: str) -> list[str | int]: + """ + Gets the segments of a path of values (see `Values`), such as + `["layout", "sso", "planes", 0, "crossing"]` of + `"layout.sso.planes[0].crossing"`. + """ + segments: list[str | int] = [] + for index, name in _SEGMENT.findall(path): + segments.append(int(index) if index else name) + rebuilt = "".join(f"[{s}]" if isinstance(s, int) else f".{s}" for s in segments) + if not segments or rebuilt.lstrip(".") != path.lstrip("."): + raise KeyError(f"{path!r} is not a path of values") + return segments + + +def _join(path: str, segment: str | int) -> str: + """Gets the path of a segment within a path (see `_segments`).""" + if isinstance(segment, int): + return f"{path}[{segment}]" + return f"{path}.{segment}" if path else segment + + +_ITEM_INDEX = re.compile(r"\[\d+\]") +"""The index of an item of a repetition in a path (`[k]`).""" + + +def generic_path(path: str) -> str: + """ + Gets the path of the node of a value: its path (see `Design.flat`) with + `[*]` for the index of any item of a repetition, as the paths of + uncertain parameters (see `DesignSpace.uncertain_paths`), shifts, and + the overrides of scenarios name them (such as `planes[*].phase` of + `planes[2].phase`). + + Args: + path (str): The path of a value. + + Returns: + str: the path, with `[*]` for the indices of items + """ + return _ITEM_INDEX.sub("[*]", path) + + +def is_number(value: Any) -> bool: + """ + Whether a value is a number: an integer or a float (also of numpy), but + not a boolean. + + Args: + value (Any): The value. + + Returns: + bool: `True` if the value is a number + """ + return isinstance(value, (int, float, np.number)) and not isinstance( + value, (bool, np.bool_) + ) + + +def _step(value: Any, segment: str | int, path: str) -> Any: + """ + Gets the value of a segment of a path within a value (see `Values`): a + child of a group, an item of a repetition (`[k]`) or its `count`, or, of + a choice, its chosen branch (by its name) or a value of that branch. + """ + where = path or "the design" + if isinstance(value, RepeatValues): + if isinstance(segment, int): + if not 0 <= segment < len(value): + raise KeyError(f"{where} has {len(value)} items, not an item {segment}") + return value[segment] + if segment == "count": + return value.count + raise KeyError(f"{where} is a repetition: give an item ([k]) or its count") + if isinstance(value, ChoiceValues): + if segment == value.choice: + return value.value + try: + return _step(value.value, segment, path) + except KeyError: + raise KeyError( + f"{where} chose {value.choice!r}, which has no value {segment!r}" + ) from None + if isinstance(value, Values) and isinstance(segment, str): + names = list(value) + if segment in names: + return value[segment] + raise KeyError(f"{where} has no value {segment!r} (it has {names})") + raise KeyError(f"{where} is a value ({value!r}), which has no {segment!r}") + + +def _resolve_path(value: Any, path: str) -> Any: + """Gets the value at a path within a value (see `Values`).""" + walked = "" + for segment in _segments(path): + value = _step(value, segment, walked) + walked = _join(walked, segment) + return value + + +class Values(Mapping): + """ + A read-only view of the values of a design space (a group of nodes), by + attribute or by key. A key may also be a path of values, as the columns + of the results of a study name them (see `Design.flat`): `"a.b"` for the + value `b` of group `a`, `"c..d"` for the value `d` of the chosen + branch of choice `c` (an error if it chose another), `"e.count"` for the + count of repetition `e`, and `"e[k].f"` for the value `f` of its item + `k`. Fixed values, which the columns of results omit, are also given:: + + d["layout.walker.planes"] # d.layout.walker.planes, if it chose walker + d["layout.sso.planes[0].crossing"] + """ + + def __init__(self, values: dict, index: int | None = None): + self._values, self._index = values, index + + def __getitem__(self, name: str) -> Any: + if name in self._values: + return _view(self._values[name]) + if isinstance(name, str) and ("." in name or "[" in name): + return _resolve_path(self, name) + raise KeyError(name) + + def __getattr__(self, name: str) -> Any: + if name.startswith("_"): + raise AttributeError(name) + if name == "index" and self._index is not None: + return self._index + try: + return self[name] + except KeyError: + raise AttributeError( + f"no value {name!r} (it has {list(self._values)})", name=name, obj=self + ) from None + + def __dir__(self) -> list[str]: + # the values, for completion (and suggestions of misspelled names) + index = ["index"] if self._index is not None else [] + return sorted({*object.__dir__(self), *self._values, *index}) + + def __iter__(self) -> Iterator[str]: + return iter(self._values) + + def __len__(self) -> int: + return len(self._values) + + def __repr__(self) -> str: + return f"Values({ {k: _view(v) for k, v in self._values.items()} })" + + +class ChoiceValues: + """ + A read-only view of the value of a choice: the name of the chosen branch + (`choice`), which the view equals (as the columns of the results of a + study give it, see `Design.flat`), and, as attributes (or keys), the + values of the branch, which are also those of the branch's name:: + + d.layout == "walker" # d.layout.choice == "walker" + d.layout.planes # d.layout.walker.planes, if it chose walker + + An attribute is a value of the branch (of a branch that is a group, a + choice, or a repetition) if the branch has one of that name, and + otherwise the branch, if it is the branch's name; a path (see `Values`) + names the branch first, as the columns of results do. + """ + + def __init__(self, value: _ChoiceValue): + self._value = value + + @property + def choice(self) -> str: + """The name of the chosen branch.""" + return self._value.choice + + @property + def value(self) -> Any: + """The value of the chosen branch.""" + return _view(self._value.value) + + def __getattr__(self, name: str) -> Any: + # the values of the branch first (as before branches were attributes), + # then the branch by its name (which paths give first, see `Values`) + if name.startswith("_"): + raise AttributeError(name) + value = self.value + if isinstance(value, (Values, ChoiceValues, RepeatValues)): + # not the attributes of a branch that is a plain value (a variable) + try: + return getattr(value, name) + except AttributeError: + pass + if name == self._value.choice: + return value + raise AttributeError( + f"the choice chose {self.choice!r}, which has no value {name!r}", + name=name, + obj=self, + ) + + def __dir__(self) -> list[str]: + # the values of the branch and its name, for completion (and + # suggestions of misspelled names) + value = self.value + branch = isinstance(value, (Values, ChoiceValues, RepeatValues)) + names = dir(value) if branch else [] + return sorted({*object.__dir__(self), *names, self._value.choice}) + + def __getitem__(self, name: str) -> Any: + return _resolve_path(self, name) + + def __contains__(self, name: object) -> bool: + try: + self[name] # type: ignore[index] + except (KeyError, TypeError): + return False + return True + + def __eq__(self, other: object) -> bool: + if isinstance(other, str): + return self.choice == other + if isinstance(other, ChoiceValues): + return self.choice == other.choice and self.value == other.value + return NotImplemented + + def __hash__(self) -> int: + return hash(self.choice) + + __iter__ = None # type: ignore[assignment] + + def __str__(self) -> str: + return self.choice + + def __repr__(self) -> str: + return f"ChoiceValues({self.choice!r}, {self.value!r})" + + +class RepeatValues: + """ + A read-only view of the value of a repetition: a sequence of the values + of its items, whose length is also given as `count`. + """ + + def __init__(self, value: _RepeatValue): + self._value = value + + @property + def count(self) -> int: + """The number of items.""" + return self._value.count + + def __getitem__(self, index: int | slice) -> Any: + if isinstance(index, slice): + return [self[k] for k in range(len(self))[index]] + position = index + len(self) if index < 0 else index + if not 0 <= position < len(self): + raise IndexError(f"the repetition has {len(self)} items, not item {index}") + index = position + item = self._value.items[index] + return Values(item, index) if isinstance(item, dict) else _view(item) + + def __len__(self) -> int: + return len(self._value.items) + + def __iter__(self) -> Iterator[Any]: + return (self[k] for k in range(len(self))) + + def __eq__(self, other: object) -> bool: + if isinstance(other, (RepeatValues, list, tuple)): + return list(self) == list(other) + return NotImplemented + + __hash__ = None # type: ignore[assignment] + + def __repr__(self) -> str: + return f"RepeatValues({list(self)!r})" + + +class Scope: + """ + The values decided so far, as given to the callables of a design space. + A name resolves to the innermost enclosing group that declares it (and + has decided it), and `index` to the position of the innermost enclosing + repeated item. + """ + + def __init__(self, frames: tuple = ()): + self._frames = frames + + def push(self, values: dict, index: int | None = None) -> Scope: + """ + Gets the scope of a group within this scope (or of a repeated item, + at `index`). + """ + return Scope(self._frames + ((values, index),)) + + def __getattr__(self, name: str) -> Any: + if name.startswith("_"): + raise AttributeError(name) + for values, index in reversed(self._frames): + if name in values: + return _view(values[name]) + if name == "index" and index is not None: + return index + raise AttributeError(f"{name!r} is not decided before it is used") + + def get(self, name: str, default: Any = None) -> Any: + """ + Gets a value by its name, or by a path within it (see `__getitem__`), + if it is decided. + + Args: + name (str): The name or path. + default (Any): The value if it is not decided. + + Returns: + Any: the value + """ + try: + return self[name] + except KeyError: + return default + + def __contains__(self, name: object) -> bool: + if not isinstance(name, str): + return False + try: + self[name] + except KeyError: + return False + return True + + def __getitem__(self, name: str) -> Any: + """ + Gets a value by its name, or by a path within it (see `Values`), such + as `"layout.walker.planes"`. + """ + segments = _segments(name) + if not isinstance(segments[0], str): + raise KeyError(f"{name!r} does not start with a name") + try: + value = getattr(self, segments[0]) + except AttributeError as error: + raise KeyError(str(error)) from None + walked = segments[0] + for segment in segments[1:]: + value = _step(value, segment, walked) + walked = _join(walked, segment) + return value diff --git a/src/tatc/tradespace/walks.py b/src/tatc/tradespace/walks.py new file mode 100644 index 0000000..b9892d6 --- /dev/null +++ b/src/tatc/tradespace/walks.py @@ -0,0 +1,645 @@ +""" +Walks of design spaces: the decisions of the nodes of a design space in the +order they are declared, which decide designs (see `DesignSpace`), and the +paths of its nodes. + +A walk decides each node in turn: a design variable by a decision that is +prescribed (such as the decisions of a design) or chosen (by an enumeration, +a sample, or an optimizer), a fixed, derived, or uncertain value by its +value (or a value of a scenario, or a draw), a group by its children (then +its constraints), a choice by its branch (then the branch), and a repetition +by its count (then its items, sorted by the levels of their decisions if they +are unordered). + +@author: Paul T. Grogan +""" + +from __future__ import annotations + +import copy +import math +from collections.abc import Callable, Mapping +from functools import partial +from typing import Any + +import numpy as np + +from .nodes import ( + Choice, + Derived, + Fixed, + Group, + Infeasible, + Integer, + Node, + Repeat, + Uncertain, + Variable, + _Domain, +) +from .values import Scope, _ChoiceValue, _join, _RepeatValue, is_number + +_ABSENT = object() +"""Marker of a node that records no decision (fixed, derived, or uncertain), +or of a decision that is not prescribed.""" + +_FIRST = object() +"""Marker of a node whose decisions are their first levels (as of a branch +of a choice given by its name, see `DesignSpace.design`).""" + + +def _scalar(value: Any) -> Any: + """ + Converts a numpy scalar to a plain Python value, for decisions. + """ + return value.item() if isinstance(value, np.generic) else value + + +def _first_level(path: str, domain: _Domain) -> Any: + """ + Chooses the first level of a domain (or its lower bound). + """ + if domain.levels is not None and len(domain.levels) == 0: + raise Infeasible(f"{path} has no levels") + return domain.from_unit(0.0) + + +def _rank(domain: _Domain, value: Any) -> float: + """ + Gets the rank of a decision in its domain, by which unordered items are + sorted: the index of its level (or its value, if continuous). + """ + if domain.levels is None: + return float(value) + try: + return domain.levels.index(value) + except ValueError: + return len(domain.levels) + + +class _Context: + """ + How a walk of a design space decides its nodes: `choose(path, domain)` + decides a variable, `draw(path, node)` draws an uncertain parameter (or + `None` for nominal values), `fix(path, node)` gives a fixed value (or + `None` for its value), and `check` enables constraints. If given, + `normalize(path, domain, value)` gives the value of the domain that a + prescribed decision is (such as its level, see `_level_of`). With an + `odometer` (of an enumeration), the items of unordered repetitions are + only walked in the order of their levels. A walk of the decisions of a + design (`canonical`), whose unordered items are in order, does not sort + them again. + """ + + # pylint: disable=too-many-instance-attributes + + def __init__( + self, + choose: Callable[[str, _Domain], Any] | None = None, + draw: Callable[[str, Uncertain], Any] | None = None, + check: bool = True, + odometer: _Odometer | None = None, + fix: Callable[[str, Fixed], Any] | None = None, + normalize: Callable[[str, _Domain, Any], Any] | None = None, + canonical: bool = False, + ): + # pylint: disable=too-many-arguments,too-many-positional-arguments + self.choose, self.draw, self.check = choose, draw, check + self.fix, self.normalize = fix, normalize + self.odometer = odometer + self.canonical = canonical + self.ranks: list[list[float]] = [] + """The ranks of the decisions of the unordered items being walked + (the innermost last), by which they are sorted (see `_rank`).""" + + def decide(self, path: str, domain: _Domain, prescribed: Any) -> Any: + """ + Decides a value of a domain: the prescribed value (normalized, if + the walk normalizes them), or a chosen one. + """ + if prescribed is _ABSENT: + value = _scalar(_choose(self, path, domain)) + elif self.normalize is not None: + value = self.normalize(path, domain, prescribed) + else: + value = prescribed + if self.ranks: + rank = _rank(domain, value) + for ranks in self.ranks: + ranks.append(rank) + return value + + def first(self) -> _Context: + """ + Gets this context, but choosing the first levels of the domains (see + `_FIRST`). + """ + other = copy.copy(self) + other.choose = _first_level + return other + + +class _Unsorted(Infeasible): + """ + Raised while enumerating a walk whose unordered items are not in the + order of their levels: another walk gives the same design. + """ + + +def _walk( + node: Node, + path: str, + scope: Scope, + ctx: _Context, + prescribed: Any = _ABSENT, + publish: Callable[[Any], None] | None = None, +) -> tuple[Any, Any]: + """ + Decides a node: returns its value and its decision (the values of its + design variables, or `_ABSENT` if it has none). A prescribed decision is + followed instead of choosing (or, if `_FIRST`, the first levels are). A + container publishes its (partial) value as soon as it is created, so + that its contents are visible to the callables of later nodes within it. + """ + if prescribed is _FIRST: + ctx, prescribed = ctx.first(), _ABSENT + if isinstance(node, Variable): + if prescribed is not _ABSENT and ctx.normalize is None and not ctx.ranks: + return prescribed, prescribed + value = ctx.decide(path, node.domain(scope), prescribed) + return value, value + if isinstance(node, Fixed): + return (node.value if ctx.fix is None else ctx.fix(path, node)), _ABSENT + if isinstance(node, Derived): + return node.function(scope), _ABSENT + if isinstance(node, Uncertain): + return (node.nominal if ctx.draw is None else ctx.draw(path, node)), _ABSENT + if isinstance(node, Group): + return _walk_group(node, path, scope, ctx, prescribed, publish) + if isinstance(node, Choice): + return _walk_choice(node, path, scope, ctx, prescribed, publish) + if isinstance(node, Repeat): + return _walk_repeat(node, path, scope, ctx, prescribed, publish) + raise TypeError(f"unknown node {node!r} at {path or 'the root'}") + + +def _choose(ctx: _Context, path: str, domain: _Domain) -> Any: + """ + Chooses a value of a domain, if the walk can choose. + """ + if ctx.choose is None: + raise ValueError(f"no decision for {path}") + return ctx.choose(path, domain) + + +def _walk_group( + node: Group, + path: str, + scope: Scope, + ctx: _Context, + prescribed: Any, + publish: Callable[[Any], None] | None, +) -> tuple[dict, dict]: + """ + Decides the children of a group in order, then checks its constraints + (see `_walk`). + """ + if prescribed is not _ABSENT and ctx.normalize is not None: + _check_children(node, path, prescribed) + values: dict = {} + if publish is not None: + publish(values) + inner = scope.push(values) + decisions = {} + for name, child in node.children.items(): + value, decision = _walk( + child, + _join(path, name), + inner, + ctx, + _ABSENT if prescribed is _ABSENT else prescribed.get(name, _ABSENT), + partial(values.__setitem__, name), + ) + values[name] = value + if decision is not _ABSENT: + decisions[name] = decision + if ctx.check: + for i, constraint in enumerate(node.constraints): + violation = _get_violation(constraint(inner)) + if math.isnan(violation) or violation > 0: + label = getattr(constraint, "__name__", "") + raise Infeasible( + f"constraint {i} ({label}) of {path or 'the design space'} " + + ("is NaN" if math.isnan(violation) else "is not satisfied"), + 1.0 if math.isnan(violation) else violation, + ) + return values, decisions + + +def _check_children(node: Group, path: str, prescribed: Any) -> None: + """ + Checks that the prescribed decisions of a group (such as those given to + `DesignSpace.design`) are a mapping of the decisions of its children, + raising a `ValueError` if not, or if they name others. + """ + where = path or "the design space" + if not isinstance(prescribed, Mapping): + raise ValueError( + f"the decisions of {where} are a mapping of its children, " + + f"not {prescribed!r}" + ) + unknown = [name for name in prescribed if name not in node.children] + if unknown: + raise ValueError( + f"decisions of no children of {where}: {sorted(unknown, key=str)} " + + f"(it has {list(node.children)})" + ) + + +def _get_violation(result: Any) -> float: + """ + Gets the violation of a constraint from its result: a boolean (`True` if + satisfied, a violation of 1 otherwise) or a number (satisfied if it is + not positive, its value is the violation otherwise, and `NaN`, which is + not satisfied, if it is `NaN`). + """ + if isinstance(result, (bool, np.bool_)): + return 0.0 if result else 1.0 + return float(result) + + +def _walk_choice( + node: Choice, + path: str, + scope: Scope, + ctx: _Context, + prescribed: Any, + publish: Callable[[Any], None] | None, +) -> tuple[_ChoiceValue, list]: + """ + Decides the branch of a choice, then the branch (see `_walk`). A branch + prescribed by its name alone is decided at its first levels. + """ + if prescribed is _ABSENT: + choice, sub = _ABSENT, _ABSENT + elif isinstance(prescribed, str): + choice, sub = prescribed, _FIRST + else: + choice = prescribed[0] + sub = _ABSENT if prescribed[1] is None else prescribed[1] + name = ctx.decide(path, _Domain(levels=list(node.branches)), choice) + result = _ChoiceValue(name) + if publish is not None: + publish(result) + result.value, decision = _walk( + node.branches[name], + _join(path, name), + scope, + ctx, + sub, + partial(setattr, result, "value"), + ) + return result, [name, None if decision is _ABSENT else decision] + + +def _walk_items( + node: Repeat, + path: str, + scope: Scope, + ctx: _Context, + count: int, + prescribed: Any, + publish: Callable[[Any], None] | None, + ranked: bool = False, +) -> tuple[_RepeatValue, list, list[list[float]]]: + """ + Decides the items of a repetition (see `_walk_repeat`), and the ranks of + their decisions, if `ranked` (see `_rank`). + """ + # pylint: disable=too-many-arguments,too-many-positional-arguments,too-many-locals + result = _RepeatValue(count) + if publish is not None: + publish(result) + decisions, ranks = [], [] + # with an odometer, permutations of unordered items give the same design: + # enumerate only the first, whose items are in the order of their levels + odometer = ctx.odometer if prescribed is _ABSENT and not node.ordered else None + previous: list[int] | None = None + for k in range(count): + sub = _ABSENT if prescribed is _ABSENT else prescribed[k] + start = 0 if odometer is None else odometer.position + if odometer is not None and previous is not None: + odometer.floors.append((start, previous)) + item_ranks: list[float] = [] + if ranked: + ctx.ranks.append(item_ranks) + try: + value, decision = _walk( + node.item, + _join(path, k), + scope.push({}, k), + ctx, + _ABSENT if sub is None else sub, + result.items.append, + ) + finally: + if odometer is not None and previous is not None: + odometer.floors.pop() + if ranked: + ctx.ranks.pop() + if len(result.items) == k: + # a value that is not a container is not published + result.items.append(value) + decisions.append(None if decision is _ABSENT else decision) + ranks.append(item_ranks) + if odometer is not None: + previous = odometer.indices[start : odometer.position] + return result, decisions, ranks + + +def _walk_repeat( + node: Repeat, + path: str, + scope: Scope, + ctx: _Context, + prescribed: Any, + publish: Callable[[Any], None] | None, +) -> tuple[_RepeatValue, list]: + """ + Decides the count of a repetition, then its items, which are sorted by + the levels of their decisions (in the order they are decided, see + `_rank`) and decided again in that order if they are unordered (see + `_walk`). + """ + if isinstance(node.count, Variable): + count = int( + ctx.decide( + _join(path, "count"), + node.count.domain(scope), + _ABSENT if prescribed is _ABSENT else len(prescribed), + ) + ) + elif isinstance(node.count, Fixed): + count = int(node.count.value) + elif isinstance(node.count, Derived): + count = int(node.count.function(scope)) + else: + count = int(node.count) + if count < 0: + raise Infeasible(f"the count of {path} is negative ({count})") + if prescribed is not _ABSENT and len(prescribed) != count: + raise ValueError( + f"{len(prescribed)} items are given for {path}, whose count is {count}" + ) + ranked = not node.ordered and not ctx.canonical + # the ranks of the enclosing unordered items, which take those of these + # items in their order + marks = [len(ranks) for ranks in ctx.ranks] + result, decisions, ranks = _walk_items( + node, path, scope, ctx, count, prescribed, publish, ranked + ) + if ranked: + order = sorted(range(count), key=ranks.__getitem__) + if order != list(range(count)): + for enclosing, mark in zip(ctx.ranks, marks): + del enclosing[mark:] + canonical = [decisions[k] for k in order] + result, decisions, _ = _walk_items( + node, path, scope, ctx, count, canonical, publish + ) + return result, decisions + + +def _flatten(node: Node, value: Any, path: str, out: dict) -> None: + """ + Flattens the values of a node into `out`, by path: the chosen branch of + a choice at its path (and its values under the branch's name), the count + of a repetition at `.count` (also of a fixed count) and its items + at `[k]`, and the other values (except fixed values) at their + paths. + """ + if isinstance(node, Fixed): + return + if isinstance(node, Group): + for name, child in node.children.items(): + _flatten(child, value[name], _join(path, name), out) + elif isinstance(node, Choice): + out[path] = value.choice + _flatten( + node.branches[value.choice], value.value, _join(path, value.choice), out + ) + elif isinstance(node, Repeat): + out[_join(path, "count")] = value.count + for k, item in enumerate(value.items): + _flatten(node.item, item, _join(path, k), out) + else: + out[path] = value + + +class _Odometer: + """ + Chooses the levels of the variables of successive walks in the order of + an odometer whose digits are the decisions of a walk, so that walks + enumerate every combination of levels, including those of variables + whose existence or domain depends on earlier decisions. + """ + + def __init__(self): + self.indices: list[int] = [] + self.sizes: list[int] = [] + self.position = 0 + self.floors: list[tuple[int, list[int]]] = [] + """The levels of the previous unordered items (and where the + current items' levels start), which the current items must not + precede.""" + + def choose(self, path: str, domain: _Domain) -> Any: + """ + Chooses the level of the current digit of the odometer (adding a + digit, at the first level, if the walk is longer than before), and + stops a walk whose unordered items precede the previous ones. + """ + if domain.levels is None: + raise ValueError( + f"{path} is continuous: give it a step to enumerate the design space" + ) + if len(domain.levels) == 0: + raise Infeasible(f"{path} has no levels") + if self.position == len(self.indices): + self.indices.append(0) + self.sizes.append(len(domain.levels)) + level = domain.levels[self.indices[self.position]] + self.position += 1 + for start, previous in self.floors: + current = self.indices[start : self.position] + if current < previous[: len(current)]: + raise _Unsorted() + return level + + def advance(self) -> bool: + """ + Advances to the next combination after a walk, returning `False` + after the last. + """ + del self.indices[self.position :], self.sizes[self.position :] + self.position = 0 + self.floors.clear() + while self.indices: + if self.indices[-1] + 1 < self.sizes[-1]: + self.indices[-1] += 1 + return True + self.indices.pop() + self.sizes.pop() + return False + + +def _level_of(path: str, domain: _Domain, value: Any) -> Any: + """ + Gets the value of a domain that a decision is (see `DesignSpace.design` + and `DesignSpace.designs_of`): the level that equals it (whose type a + data frame may have changed, as integers in a column of floats, or that + is given as a numpy scalar), or the value (a float) in the range of a + continuous domain, raising a `ValueError` if there is none. + """ + if domain.levels is None: + try: + number = float(value) + except (TypeError, ValueError): + number = math.nan + if domain.low <= number <= domain.high: + return number + raise ValueError( + f"{value!r} is not in the range of {path} ({domain.low}, {domain.high})" + ) + for level in domain.levels: + try: + if level == value: + return _scalar(level) + except (TypeError, ValueError): + continue + if is_number(value): + for level in domain.levels: + if is_number(level) and math.isclose( + float(level), float(value), rel_tol=1e-9, abs_tol=1e-12 + ): + return _scalar(level) + raise ValueError(f"{value!r} is not a level of {path} ({domain.levels})") + + +def _missing(value: Any) -> bool: + """Whether a value of a data frame is missing (`None` or `NaN`).""" + return value is None or (isinstance(value, float) and math.isnan(value)) + + +def _decided(values: Mapping[str, Any], path: str, domain: _Domain) -> Any: + """ + Gets the decision of a path from values by path (such as a row of the + results of a study, see `DesignSpace.designs_of`): the level of the domain + that equals the value (whose type a data frame may have changed, as + integers in a column of floats), or the value of a continuous domain. + """ + value = values.get(path) + if _missing(value): + raise ValueError( + f"no value of {path}: rebuild designs from the results of a study, or " + + "from a summary that keeps the values of designs (see summarize)" + ) + return _level_of(path, domain, value) + + +# --------------------------------------------------------------------------- +# paths of nodes +# --------------------------------------------------------------------------- + + +def _unit_paths(node: Node, path: str) -> list[str]: + """ + Gets the paths of the decisions of a node (see `DesignSpace._unit_paths`). + """ + if isinstance(node, Variable): + return [path] + if isinstance(node, Group): + return [ + p + for name, child in node.children.items() + for p in _unit_paths(child, _join(path, name)) + ] + if isinstance(node, Choice): + return [path] + [ + p + for name, branch in node.branches.items() + for p in _unit_paths(branch, _join(path, name)) + ] + if isinstance(node, Repeat): + paths, largest = [], _largest_count(node.count, path) + if isinstance(node.count, Variable): + paths = [_join(path, "count")] + return paths + [ + p for k in range(largest) for p in _unit_paths(node.item, _join(path, k)) + ] + return [] + + +def _largest_count(count: Any, path: str) -> int: + """ + Gets the largest count of a repetition (see `_unit_paths`), which must + not depend on other values. + """ + if isinstance(count, Integer) and not callable(count.high): + return int(count.high) + if isinstance(count, Variable) and not isinstance(count, Integer): + options = getattr(count, "options", None) + if options is not None and not callable(options): + return int(max(options)) + elif isinstance(count, Fixed): + return int(count.value) + elif isinstance(count, int): + return count + raise ValueError(f"the count of {path} needs a fixed upper bound to be encoded") + + +def _leaf_paths(node: Node, path: str, kind: type) -> list[str]: + """ + Gets the paths of the leaves of a kind of a node (such as its fixed + values), with `[*]` for the index of any item of a repetition, and with + the branches of choices, whether a design chooses them or not. + """ + if isinstance(node, kind): + return [path] + if isinstance(node, Group): + return [ + p + for name, child in node.children.items() + for p in _leaf_paths(child, _join(path, name), kind) + ] + if isinstance(node, Choice): + return [ + p + for name, branch in node.branches.items() + for p in _leaf_paths(branch, _join(path, name), kind) + ] + if isinstance(node, Repeat): + return _leaf_paths(node.item, f"{path}[*]", kind) + return [] + + +def _node_at(node: Node, path: Any) -> Node | None: + """ + Gets the node at a path of leaves (see `_leaf_paths`): through the + children of groups and the branches of choices by their names, and the + items of repetitions by `[*]`, or `None` if there is none. + """ + if not isinstance(path, str) or not path: + return None + for segment in path.replace("[*]", ".[*]").split("."): + if isinstance(node, Group): + node = node.children.get(segment) + elif isinstance(node, Choice): + node = node.branches.get(segment) + elif isinstance(node, Repeat) and segment == "[*]": + node = node.item + else: + return None + if node is None: + return None + return node diff --git a/tests/analysis/test_sufficiency.py b/tests/analysis/test_sufficiency.py new file mode 100644 index 0000000..d7a3de9 --- /dev/null +++ b/tests/analysis/test_sufficiency.py @@ -0,0 +1,247 @@ +""" +Unit tests for methods to assess the statistical sufficiency of observations. + +@author Paul T. Grogan +""" + +import importlib.util +import unittest +from datetime import datetime, timedelta, timezone + +import geopandas as gpd +import numpy as np +import pandas as pd +from shapely.geometry import Point + +from tatc.analysis import ( + compare_sampled_means, + compute_local_time_coverage, + compute_revisit_statistics, + estimate_sampling_error, + sample_field, + sampling_error_variance, +) +from tatc.utils import hash_geometry + +HAS_XARRAY = importlib.util.find_spec("xarray") is not None +START = datetime(2026, 1, 1, tzinfo=timezone.utc) +DAY = timedelta(days=1) + + +def _observations(samples): + """Observations of points (longitude, latitude) at hours after the start.""" + rows = [ + { + "geometry": Point(lon, lat), + "target_hash": hash_geometry(Point(lon, lat)), + "epoch": START + timedelta(hours=hour), + } + for (lon, lat), hours in samples.items() + for hour in hours + ] + return gpd.GeoDataFrame(rows, crs="EPSG:4326") + + +class TestSamplingErrorVariance(unittest.TestCase): + """ + Unit tests for the variance of sampling errors. + """ + + def test_limits(self): + """Independent samples give 1/n; dense samples give no error.""" + length = 1000.0 + # samples far apart relative to the decorrelation time + sparse = sampling_error_variance(np.linspace(50, 950, 10), length, 1.0) + self.assertAlmostEqual(sparse, 1 / 10, delta=0.01) + dense = sampling_error_variance(np.arange(0.5, 1000, 1.0), length, 10.0) + self.assertLess(dense, 0.001) + # a field that hardly varies over the period is estimated by one sample + self.assertLess(sampling_error_variance([500.0], length, 1e6), 0.01) + self.assertTrue(np.isnan(sampling_error_variance([], length, 1.0))) + # samples closer than the decorrelation time repeat each other + clustered = sampling_error_variance(np.linspace(0, 1, 10), length, 10.0) + self.assertGreater(clustered, 0.5) + with self.assertRaises(ValueError): + sampling_error_variance([1.0], 0, 1.0) + + def test_monte_carlo(self): + """The variance matches simulations of a first-order Markov process.""" + rng = np.random.default_rng(0) + dt, length, scale = 0.1, 48.0, 3.0 + steps = int(length / dt) + rho = np.exp(-dt / scale) + n = 4000 + x = np.empty((n, steps)) + x[:, 0] = rng.normal(size=n) + noise = rng.normal(size=(n, steps)) * np.sqrt(1 - rho**2) + for k in range(1, steps): + x[:, k] = rho * x[:, k - 1] + noise[:, k] + grid = (np.arange(steps) + 0.5) * dt + for times in ([10.0, 22.0, 34.0, 46.0], [12.0, 13.0, 14.0], [24.0]): + index = [int(t / dt) for t in times] + errors = x[:, index].mean(axis=1) - x.mean(axis=1) + expected = sampling_error_variance(grid[index], length, scale) + self.assertAlmostEqual(np.var(errors) / expected, 1, delta=0.08) + + +class TestEstimateSamplingError(unittest.TestCase): + """ + Unit tests for estimates of sampling errors. + """ + + def test_targets(self): + """Each target's error follows its samples, and unobserved targets have none.""" + observations = _observations( + {(0, 0): [2, 8, 14, 20], (10, 0): [2, 3], (20, 0): [12]} + ) + targets = gpd.GeoSeries([Point(0, 0), Point(10, 0), Point(20, 0), Point(30, 0)]) + error = estimate_sampling_error( + observations, + START, + START + DAY, + timedelta(hours=1), + standard_deviation=2.0, + targets=targets, + ) + self.assertEqual(list(error.samples), [4, 2, 1, 0]) + self.assertTrue( + error.relative_error[0] < error.relative_error[1] < error.relative_error[2] + ) + np.testing.assert_allclose( + error.sampling_error[:3], 2 * error.relative_error[:3] + ) + self.assertTrue(np.isnan(error.relative_error[3])) + self.assertEqual(error.effective_samples[3], 0) + # four samples six hours apart are nearly independent; two an hour apart are not + self.assertAlmostEqual(error.effective_samples[0], 4, delta=0.5) + self.assertLess(error.effective_samples[1], 2) + + def test_standard_deviation_by_target(self): + """The standard deviation may differ between targets.""" + observations = _observations({(0, 0): [6, 18], (10, 0): [6, 18]}) + sigma = {hash_geometry(Point(0, 0)): 1.0, hash_geometry(Point(10, 0)): 3.0} + error = estimate_sampling_error( + observations, START, START + DAY, timedelta(hours=2), sigma + ) + self.assertAlmostEqual(error.sampling_error[1], 3 * error.sampling_error[0]) + + +class TestDecorrelationByTarget(unittest.TestCase): + """ + Unit tests for decorrelation times of each target. + """ + + def test_by_target(self): + """Each target may have its own decorrelation time.""" + observations = _observations({(0, 0): [6, 7], (10, 0): [6, 7]}) + scales = { + hash_geometry(Point(0, 0)): timedelta(minutes=10), + hash_geometry(Point(10, 0)): timedelta(hours=10), + } + error = estimate_sampling_error(observations, START, START + DAY, scales) + # samples an hour apart are independent for the shorter decorrelation time + self.assertAlmostEqual(error.effective_samples[0], 2, delta=0.01) + self.assertLess(error.effective_samples[1], 1.2) + single = estimate_sampling_error( + observations, START, START + DAY, timedelta(minutes=10) + ) + self.assertAlmostEqual(single.relative_error[0], error.relative_error[0]) + + +class TestRevisitStatistics(unittest.TestCase): + """ + Unit tests for revisit statistics. + """ + + def test_gaps(self): + """Revisits are between samples; gaps include the edges of the period.""" + observations = _observations({(0, 0): [1, 3, 11], (10, 0): [12]}) + targets = gpd.GeoSeries([Point(0, 0), Point(10, 0), Point(20, 0)]) + stats = compute_revisit_statistics( + observations, START, START + DAY, quantiles=(0.5,), targets=targets + ) + self.assertEqual(list(stats.samples), [3, 1, 0]) + self.assertEqual(stats.revisit[0], timedelta(hours=5)) + self.assertEqual(stats["revisit p50"][0], timedelta(hours=5)) + self.assertEqual(stats.max_gap[0], timedelta(hours=13)) + self.assertEqual(stats.max_gap[1], timedelta(hours=12)) + self.assertTrue(pd.isna(stats.revisit[1])) + self.assertEqual(stats.max_gap[2], DAY) + + +class TestLocalTimeCoverage(unittest.TestCase): + """ + Unit tests for local time coverage. + """ + + def test_bins(self): + """Samples are binned by local mean solar time.""" + # at 90 degrees east, local time is six hours after universal time + observations = _observations({(90, 0): [0, 1, 12], (-90, 0): [10, 22]}) + coverage = compute_local_time_coverage(observations, bins=4) + east = coverage.iloc[0] + self.assertEqual(east["local 06:00"], 2) + self.assertEqual(east["local 18:00"], 1) + self.assertEqual(east.local_bins_sampled, 2) + west = coverage.iloc[1] + # 04:00 and 16:00 local time + self.assertEqual((west["local 00:00"], west["local 12:00"]), (1, 1)) + self.assertEqual(west.local_time_coverage, 0.5) + with self.assertRaises(ValueError): + compute_local_time_coverage(observations, bins=0) + + +@unittest.skipUnless(HAS_XARRAY, "requires xarray") +class TestSampleField(unittest.TestCase): + """ + Unit tests for sampling fields. + """ + + def setUp(self): + import xarray as xr # pylint: disable=import-outside-toplevel + + times = pd.date_range("2026-01-01", periods=25, freq="h") + lat = np.arange(-10.0, 11.0, 1.0) + lon = np.arange(0.0, 360.0, 1.0) + hours = np.arange(25, dtype=float) + # a field linear in time, latitude, and longitude (0-360) + values = ( + hours[:, None, None] + 10 * lat[None, :, None] + 0.1 * lon[None, None, :] + ) + self.field = xr.DataArray( + values, + dims=("time", "lat", "lon"), + coords={"time": times, "lat": lat, "lon": lon}, + name="temperature", + ) + + def test_linear(self): + """Linear interpolation recovers a linear field, across longitude conventions.""" + observations = _observations({(10.5, 2.25): [3.5], (-20, -1): [6]}) + sampled = sample_field(observations, self.field, method="linear") + expected = [3.5 + 22.5 + 1.05, 6 - 10 + 0.1 * 340] + np.testing.assert_allclose(sampled.temperature, expected) + + def test_nearest_and_outside(self): + """Nearest values snap to the grid; times outside the field have no value.""" + observations = _observations({(10.4, 2.2): [3.4, 30]}) + sampled = sample_field(observations, self.field, name="t") + self.assertAlmostEqual(sampled.t[0], 3 + 20 + 1.0) + self.assertTrue(np.isnan(sampled.t[1])) + + def test_compare_means(self): + """Sampled means are compared with the means of the field over the period.""" + observations = _observations({(10, 2): [0, 24], (20, 0): [12]}) + sampled = sample_field(observations, self.field) + comparison = compare_sampled_means( + sampled, + self.field, + START, + START + DAY, + targets=gpd.GeoSeries([Point(10, 2), Point(20, 0), Point(30, 0)]), + ) + # the field's mean over hours 0 to 24 is its value at hour 12 + np.testing.assert_allclose(comparison.true_mean, [12 + 20 + 1, 12 + 2, 12 + 3]) + np.testing.assert_allclose(comparison.error[:2], [0, 0], atol=1e-9) + self.assertEqual(list(comparison.samples), [2, 1, 0]) + self.assertTrue(np.isnan(comparison.sampled_mean[2])) diff --git a/tests/generation/test_points.py b/tests/generation/test_points.py index 549f69d..9bd940f 100644 --- a/tests/generation/test_points.py +++ b/tests/generation/test_points.py @@ -496,3 +496,113 @@ def test_weights_invalid(self): ]: with self.subTest(kwargs=kwargs), self.assertRaises(ValueError): generate_points_random(10, **kwargs) + + +class TestGeneratePointsRotatedLattice(unittest.TestCase): + """ + Unit tests for Fibonacci lattices of a number of points, in a random + orientation. + """ + + def test_points(self): + """Lattices have the number of points, reproducibly, uniform by area.""" + points = generate_points_fibonacci_lattice(count=500, rotate=True, seed=3) + self.assertEqual(len(points), 500) + self.assertEqual(list(points.columns), ["point_id", "geometry"]) + self.assertEqual(points.crs, "EPSG:4326") + same = generate_points_fibonacci_lattice(count=500, rotate=True, seed=3) + self.assertTrue(points.geometry.geom_equals(same.geometry).all()) + other = generate_points_fibonacci_lattice(count=500, rotate=True, seed=4) + self.assertFalse(points.geometry.geom_equals(other.geometry).all()) + self.assertEqual( + len(generate_points_fibonacci_lattice(count=0, rotate=True, seed=1)), 0 + ) + with self.assertRaises(ValueError): + generate_points_fibonacci_lattice(count=-1) + # uniform by area: the sine of latitude is uniform on [-1, 1] + sines = np.concatenate( + [ + np.sin( + np.radians( + generate_points_fibonacci_lattice( + count=200, rotate=True, seed=k + ).geometry.y + ) + ) + for k in range(100) + ] + ) + self.assertAlmostEqual(sines.mean(), 0, delta=0.01) + self.assertAlmostEqual(sines.var(), 1 / 3, delta=0.01) + elevated = generate_points_fibonacci_lattice( + count=10, rotate=True, elevation=100, seed=1 + ) + self.assertTrue((elevated.geometry.z == 100).all()) + + def test_mask(self): + """About the number of points fall in a mask.""" + for mask in ( + box(-30, -20, 40, 35), + box(-180, 60, 180, 90), + Polygon([(-100, 20), (-80, 25), (-90, 45)]), + ): + counts = [ + len( + generate_points_fibonacci_lattice( + count=100, rotate=True, mask=mask, seed=k + ) + ) + for k in range(50) + ] + self.assertAlmostEqual(np.mean(counts), 100, delta=2) + self.assertLess(max(counts) - min(counts), 15) + with self.assertRaises(ValueError): + generate_points_fibonacci_lattice( + count=10, mask=Polygon([(0, 0), (1, 1), (0, 1), (1, 0)]) + ) + + def test_stratification(self): + """Lattices estimate shares of the surface with less variance.""" + region = box(-60, -10, 30, 50) + + def share(points): + return points.geometry.within(region).mean() + + lattices = [ + share(generate_points_fibonacci_lattice(count=200, rotate=True, seed=k)) + for k in range(60) + ] + randoms = [share(generate_points_random(200, seed=k)) for k in range(60)] + self.assertAlmostEqual(np.mean(lattices), np.mean(randoms), delta=0.02) + self.assertLess(np.var(lattices), 0.5 * np.var(randoms)) + + def test_arguments(self): + """A lattice takes a distance or a count of points, and a seed of its + orientation only if it is rotated.""" + for kwargs in ({}, {"distance": 1e6, "count": 5}, {"count": 5, "seed": 1}): + with self.subTest(kwargs=kwargs), self.assertRaises(ValueError): + generate_points_fibonacci_lattice(**kwargs) + # the same lattice of a count, in its fixed orientation + fixed = generate_points_fibonacci_lattice(count=50) + self.assertEqual(len(fixed), 50) + self.assertTrue( + fixed.geometry.geom_equals( + generate_points_fibonacci_lattice(count=50).geometry + ).all() + ) + # a lattice of a distance, in a random orientation + rotated = generate_points_fibonacci_lattice(2000e3, rotate=True, seed=1) + self.assertEqual(len(rotated), len(generate_points_fibonacci_lattice(2000e3))) + + def test_antimeridian_mask(self): + """Rotated lattices sample masks that cross the antimeridian.""" + mask = box(170, -10, 190, 10) + counts = [ + len( + generate_points_fibonacci_lattice( + count=100, mask=mask, rotate=True, seed=k + ) + ) + for k in range(30) + ] + self.assertAlmostEqual(np.mean(counts), 100, delta=3) diff --git a/tests/tradespace/__init__.py b/tests/tradespace/__init__.py new file mode 100644 index 0000000..e69de29 diff --git a/tests/tradespace/test_attribution.py b/tests/tradespace/test_attribution.py new file mode 100644 index 0000000..aade4f7 --- /dev/null +++ b/tests/tradespace/test_attribution.py @@ -0,0 +1,425 @@ +""" +Unit tests for the attribution of variance to uncertain parameters. + +@author Paul T. Grogan +""" + +import tempfile +import unittest +from pathlib import Path + +import numpy as np +import pandas as pd + +from tatc.tradespace import ( + Choice, + DesignSpace, + Infeasible, + Integer, + ResultStore, + Study, + Uncertain, + attribute_variance, +) + +SPACE = DesignSpace( + x=Integer(1, 2), + u1=Uncertain.normal(0, 1), + u2=Uncertain.normal(0, 1), + s=Uncertain.seed(), +) + + +def _evaluate(d): + """Metrics with known shares: y = x (u1 + 2 u2) (0.2 and 0.8 of u1 and u2, + without interactions), z = u1 u2 (only their interaction), v (a draw of a + seed), and w (constant).""" + return { + "y": d.x * (d.u1 + 2 * d.u2), + "z": d.u1 * d.u2, + "v": float(np.random.default_rng(d.s).normal()), + "w": 1.0, + } + + +def _share(attribution, metric, parameter, share="total", design=None): + shares = attribution.shares + rows = shares[(shares.metric == metric) & (shares.parameter == parameter)] + if design is not None: + rows = rows[rows.design == design] + return rows[share].to_numpy() + + +class TestAttributeVariance(unittest.TestCase): + """ + Unit tests for attributing variance to uncertain parameters. + """ + + @classmethod + def setUpClass(cls): + cls.study = Study(SPACE, lambda d: d, _evaluate, replicates=2) + cls.designs = SPACE.enumerate() + cls.attribution = attribute_variance( + cls.study, + ["y", "z", "v", "w"], + cls.designs, + sample_size=300, + n_resamples=200, + ) + + def test_known_shares(self): + """The shares of additive effects and interactions are estimated (within + three standard errors), and those of parameters without effects are 0.""" + a = self.attribution + expected = { + ("y", "u1"): (0.2, 0.2), + ("y", "u2"): (0.8, 0.8), + ("z", "u1"): (0.0, 1.0), + ("z", "u2"): (0.0, 1.0), + ("v", "s"): (1.0, 1.0), + } + for (metric, parameter), values in expected.items(): + for share, value in zip(("first", "total"), values): + with self.subTest(metric=metric, parameter=parameter, share=share): + estimate = _share(a, metric, parameter, share) + error = _share(a, metric, parameter, f"{share} se") + self.assertTrue((np.abs(estimate - value) <= 3 * error).all()) + np.testing.assert_array_equal(_share(a, "y", "s"), 0.0) + np.testing.assert_array_equal(_share(a, "z", "s"), 0.0) + np.testing.assert_array_equal(_share(a, "v", "u1"), 0.0) + np.testing.assert_array_equal(_share(a, "v", "s", "first"), 1.0) + # with common random numbers, the shares of y do not depend on x + np.testing.assert_allclose(*_share(a, "y", "u1").reshape(2, 1)) + + def test_standard_errors(self): + """The standard errors are those of the shares' estimates.""" + shares = self.attribution.shares + y = shares[(shares.metric == "y") & (shares.parameter != "s")] + self.assertTrue((y["total se"] > 0).all() and (y["total se"] < 0.1).all()) + # a share of 0 or 1 that every resample gives has no error + v = shares[(shares.metric == "v") & (shares.parameter == "s")] + np.testing.assert_array_equal(v["first se"], 0.0) + + def test_constant_metric(self): + """The shares of a metric that does not vary are undefined.""" + shares = self.attribution.shares + w = shares[shares.metric == "w"] + self.assertTrue((w["variance"] == 0).all()) + self.assertTrue( + w[["first", "total", "first se", "total se"]].isna().all().all() + ) + + def test_results(self): + """The results have the plain and the mixed replicates.""" + results = self.attribution.results + plain = results[results.redrawn.isna()] + self.assertEqual(sorted(plain.replicate.unique()), list(range(600))) + for name in ("u1", "u2", "s"): + mixed = results[results.redrawn == name] + self.assertEqual(len(mixed), 2 * 300) + self.assertEqual(sorted(mixed.replicate.unique()), list(range(300))) + # a mixed replicate draws its parameter as in B, and others as in A + a = plain.set_index(["design", "replicate"]) + mixed = results[results.redrawn == "u1"].set_index(["design", "replicate"]) + shifted = [(d, r + 300) for d, r in mixed.index] + np.testing.assert_array_equal(mixed.u1, a.loc[shifted].u1) + np.testing.assert_array_equal(mixed.u2, a.loc[mixed.index].u2) + + def test_designs_of_frame(self): + """Designs may be given by a data frame of their values.""" + frame = pd.DataFrame([{"design": d.key, **d.flat()} for d in self.designs]) + a = attribute_variance(self.study, ["y"], frame.iloc[:1], sample_size=2) + self.assertEqual(set(a.shares.design), {self.designs[0].key}) + + def test_summary(self): + """The summary pools the designs' shares, weighted by their variances.""" + a = self.attribution + summary = a.summary + metrics = ["y", "z", "v", "w"] + self.assertEqual( + list(summary.columns), [*metrics, *(f"{m} se" for m in metrics)] + ) + self.assertEqual(list(summary.index), ["u1", "u2", "s"]) + rows = a.shares[(a.shares.metric == "y") & (a.shares.parameter == "u2")] + expected = (rows.total * rows.variance).sum() / rows.variance.sum() + self.assertAlmostEqual(summary.loc["u2", "y"], expected) + self.assertTrue(summary[["w", "w se"]].isna().all().all()) + # with common random numbers, the shares of y of both designs are the + # same in every resample, and so is their pooled share + np.testing.assert_allclose(summary.loc["u2", "y se"], rows["total se"]) + self.assertTrue((summary.loc[["u1", "u2"], ["y se", "z se"]] > 0).all().all()) + np.testing.assert_array_equal(summary.loc["s", ["y se", "z se"]], 0.0) + first = a.summary_of("first") + self.assertAlmostEqual(first.loc["s", "v"], 1.0) + self.assertAlmostEqual(first.loc["s", "v se"], 0.0) + self.assertEqual(a._samples["total"].shape, (len(a.shares), 200)) + with self.assertRaises(ValueError): + a.summary_of("second") + + def test_groups(self): + """Groups of parameters are redrawn together.""" + a = attribute_variance( + self.study, + ["y"], + self.designs[:1], + parameters={"normal": ["u1", "u2"], "seed": "s"}, + sample_size=50, + n_resamples=50, + ) + self.assertEqual(list(a.shares.parameter), ["normal", "seed"]) + np.testing.assert_allclose(_share(a, "y", "normal", "first"), 1.0) + np.testing.assert_allclose(_share(a, "y", "normal", "total"), 1.0, atol=0.3) + np.testing.assert_array_equal(_share(a, "y", "seed", "total"), 0.0) + named = attribute_variance( + self.study, ["y"], self.designs[:1], parameters=["u2"], sample_size=50 + ) + self.assertEqual(list(named.shares.parameter), ["u2"]) + self.assertEqual(set(named.results.redrawn.dropna()), {"u2"}) + + def test_validation(self): + """Unknown, repeated, or missing parameters and too few replicates raise.""" + for parameters in (["u3"], {"a": ["u1"], "b": ["u1", "u2"]}, {"a": []}, {}): + with self.subTest(parameters=parameters): + with self.assertRaises(ValueError): + attribute_variance( + self.study, + ["y"], + self.designs, + parameters=parameters, + sample_size=2, + ) + with self.assertRaises(ValueError): + attribute_variance(self.study, ["y"], self.designs, sample_size=1) + with self.assertRaises(ValueError): + attribute_variance(self.study, ["q"], self.designs, sample_size=2) + certain = Study(DesignSpace(x=Integer(1, 2)), lambda d: d, lambda d: {"y": d.x}) + with self.assertRaises(ValueError): + attribute_variance(certain, ["y"], certain.space.enumerate()) + + def test_inactive_branches(self): + """Designs that do not draw a parameter are not evaluated for it.""" + space = DesignSpace( + layout=Choice( + a=DesignSpace(phase=Uncertain.uniform(0, 1)), + b=DesignSpace(size=Integer(1, 2)), + ), + noise=Uncertain.uniform(0, 1), + ) + + def evaluate(d): + phase = d.layout.phase if d.layout.choice == "a" else 0.0 + return {"y": phase + d.noise} + + study = Study(space, lambda d: d, evaluate) + designs = space.enumerate() + a = attribute_variance(study, ["y"], designs, sample_size=20, n_resamples=20) + redrawn = a.results[a.results.redrawn == "layout.a.phase"] + self.assertEqual(set(redrawn.design), {designs[0].key}) + shares = a.shares.set_index(["design", "parameter"]) + for design in designs[1:]: + self.assertTrue( + np.isnan(shares.loc[(design.key, "layout.a.phase"), "total"]) + ) + self.assertAlmostEqual( + shares.loc[(design.key, "noise"), "total"], 1.0, delta=0.5 + ) + + def test_infeasible(self): + """Infeasible evaluations are left out.""" + + def build(d): + if d.u1 > 1: + raise Infeasible("too large") + return d + + study = Study(SPACE, build, _evaluate) + a = attribute_variance( + study, ["y"], self.designs[:1], parameters=["u1", "u2"], sample_size=100 + ) + self.assertFalse(a.results.feasible.all()) + self.assertTrue(a.shares[["first", "total"]].notna().all().all()) + + def reject(d): + raise Infeasible("never") + + never = Study(SPACE, reject, _evaluate) + with self.assertWarns(UserWarning): + none = attribute_variance(never, ["y"], self.designs, sample_size=2) + self.assertEqual(len(none.shares), 0) + self.assertEqual(len(none.summary), 0) + with self.assertWarns(UserWarning): + separated = attribute_variance( + never, ["y"], self.designs, sample_size=2, by=["sensor"] + ) + self.assertEqual(len(separated.shares), 0) + + def test_by(self): + """The records of an evaluation are separated by `by`.""" + + def evaluate(d): + return pd.DataFrame( + {"y": [d.u1, d.u2]}, index=pd.Index(["one", "two"], name="sensor") + ) + + study = Study(SPACE, lambda d: d, evaluate) + a = attribute_variance( + study, + ["y"], + self.designs[:1], + parameters=["u1", "u2"], + sample_size=20, + by=["sensor"], + ) + shares = a.shares.set_index(["sensor", "parameter"])["total"] + self.assertAlmostEqual(shares["one", "u1"], 1.0, delta=0.5) + self.assertEqual(shares["one", "u2"], 0.0) + self.assertEqual(shares["two", "u1"], 0.0) + self.assertEqual(list(a.summary.index.names), ["sensor", "parameter"]) + with self.assertRaises(ValueError): + attribute_variance(study, ["y"], self.designs[:1], sample_size=2) + + def test_store(self): + """The evaluations are stored, and taken from the store again.""" + self.calls = [] + + def evaluate(d): + self.calls.append(d.replicate) + return _evaluate(d) + + with tempfile.TemporaryDirectory() as directory: + store = ResultStore( + Path(directory) / "results.sqlite", namespace="attribution" + ) + study = Study(SPACE, lambda d: d, evaluate, replicates=3, store=store) + first = attribute_variance(study, ["y"], self.designs, sample_size=3) + self.assertEqual(len(self.calls), 2 * (2 * 3 + 3 * 3)) + self.calls.clear() + again = attribute_variance(study, ["y"], self.designs, sample_size=3) + self.assertEqual(self.calls, []) + pd.testing.assert_frame_equal(first.shares, again.shares) + + +def _evaluate_pairs(d): + """Metrics of differences with known shares: y = x (u1 + 2 u2), whose + difference between the designs is that of one design, and c = x u1 + u2, + whose difference is u1 alone (u2 cancels).""" + return {"y": d.x * (d.u1 + 2 * d.u2), "c": d.x * d.u1 + d.u2} + + +class TestDifferences(unittest.TestCase): + """ + Unit tests for attributing the variance of differences between designs. + """ + + @classmethod + def setUpClass(cls): + cls.designs = SPACE.enumerate() + cls.study = Study(SPACE, lambda d: d, _evaluate_pairs) + cls.attribution = attribute_variance( + cls.study, + ["y", "c"], + cls.designs, + parameters=["u1", "u2"], + sample_size=200, + n_resamples=200, + ) + cls.differences = cls.attribution.differences() + + def test_cancelled(self): + """Parameters that act alike on both designs cancel in differences.""" + d = self.differences + self.assertEqual(list(d.shares.columns[:2]), ["design", "other"]) + self.assertEqual( + (d.shares.design.iloc[0], d.shares.other.iloc[0]), + (self.designs[0].key, self.designs[1].key), + ) + # c differs by u1 alone: u2 explains none of its variance in any resample + np.testing.assert_allclose(_share(d, "c", "u2"), 0.0, atol=1e-12) + np.testing.assert_allclose(_share(d, "c", "u1", "first"), 1.0) + estimate, error = _share(d, "c", "u1"), _share(d, "c", "u1", "total se") + self.assertTrue((np.abs(estimate - 1) <= 3 * error).all()) + self.assertAlmostEqual(d.summary.loc["u2", "c se"], 0.0) + # u2 spreads c of both designs, but not their difference + self.assertTrue((_share(self.attribution, "c", "u2") > 0.1).all()) + + def test_differences_of_one_design(self): + """The difference of y is that of a design, whose shares it has.""" + d, a = self.differences, self.attribution + for share in ("first", "total", "first se", "total se"): + for parameter in ("u1", "u2"): + np.testing.assert_allclose( + _share(d, "y", parameter, share), + _share(a, "y", parameter, share, self.designs[0].key), + ) + + def test_results(self): + """The results are the differences in each replicate.""" + results, differences = self.attribution.results, self.differences.results + plain = results[results.redrawn.isna()].set_index(["design", "replicate"]) + first, other = self.designs[0].key, self.designs[1].key + expected = plain.loc[first, "c"] - plain.loc[other, "c"] + found = differences[differences.redrawn.isna()].set_index("replicate")["c"] + np.testing.assert_allclose(found.sort_index(), expected.sort_index()) + self.assertEqual(len(differences), 2 * 200 + 2 * 200) + + def test_pairs(self): + """Pairs are given by designs or keys, and reversed pairs have the + same shares.""" + first, other = self.designs + reversed_ = self.attribution.differences([(other, first.key)]) + columns = ["variance", "first", "total", "first se", "total se"] + np.testing.assert_allclose( + reversed_.shares[columns], self.differences.shares[columns] + ) + self.assertEqual(reversed_.shares.design.iloc[0], other.key) + for pairs in ([(first, first)], [(first.key, "unknown")]): + with self.subTest(pairs=pairs): + with self.assertRaises(ValueError): + self.attribution.differences(pairs) + with self.assertRaises(ValueError): + self.differences.differences() + + def test_inactive_branches(self): + """A design that does not draw a parameter is as in A.""" + space = DesignSpace( + layout=Choice( + a=DesignSpace(phase=Uncertain.uniform(0, 1)), + b=DesignSpace(size=Integer(1, 2)), + ), + noise=Uncertain.uniform(0, 1), + ) + + def evaluate(d): + if d.layout.choice == "a": + return {"y": d.layout.phase + d.noise} + return {"y": d.layout.size * d.noise} + + study = Study(space, lambda d: d, evaluate) + designs = space.enumerate() + a = attribute_variance(study, ["y"], designs, sample_size=20, n_resamples=20) + d = a.differences().shares.set_index(["design", "other", "parameter"]) + branch_a, b1, b2 = (design.key for design in designs) + # a less b1 is the phase alone + self.assertAlmostEqual(d.loc[(branch_a, b1, "noise"), "total"], 0.0) + self.assertAlmostEqual(d.loc[(branch_a, b1, "layout.a.phase"), "first"], 1.0) + # neither b1 nor b2 draws the phase + self.assertTrue(np.isnan(d.loc[(b1, b2, "layout.a.phase"), "total"])) + self.assertAlmostEqual(d.loc[(b1, b2, "noise"), "first"], 1.0) + + def test_independent_draws(self): + """Without common random numbers, no parameter cancels.""" + study = Study(SPACE, lambda d: d, _evaluate_pairs, common_random_numbers=False) + a = attribute_variance( + study, ["c"], self.designs, parameters=["u1", "u2"], sample_size=200 + ) + d = a.differences() + # c of the designs differs by u1 of both and u2 of both: 5 and 2 of 7 + for parameter, value in (("u1", 5 / 7), ("u2", 2 / 7)): + estimate, error = _share(d, "c", parameter), _share( + d, "c", parameter, "total se" + ) + self.assertTrue((np.abs(estimate - value) <= 3 * error).all()) + + +if __name__ == "__main__": + unittest.main() diff --git a/tests/tradespace/test_cache.py b/tests/tradespace/test_cache.py new file mode 100644 index 0000000..b65e26f --- /dev/null +++ b/tests/tradespace/test_cache.py @@ -0,0 +1,305 @@ +""" +Unit tests for caches of analyses by satellite. + +@author Paul T. Grogan +""" + +import importlib.util +import pickle +import tempfile +import unittest +import warnings +from datetime import datetime, timedelta, timezone +from pathlib import Path + +import pandas as pd + +from tatc.analysis import collect_observations +from tatc.schemas import Instrument, Point, Satellite, SunSynchronousOrbit +from tatc.tradespace import ( + DesignSpace, + Integer, + SatelliteCache, + Study, +) +from tatc.tradespace.cache import get_satellite_key +from tatc.tradespace.fingerprint import get_fingerprint + +HAS_JOBLIB = importlib.util.find_spec("joblib") is not None + +EPOCH = datetime(2026, 1, 1, tzinfo=timezone.utc) + + +def _satellite(name: str, anomaly: float = 0, altitude: float = 700e3) -> Satellite: + return Satellite( + name=name, + orbit=SunSynchronousOrbit( + altitude=altitude, + equator_crossing_time="13:30", + epoch=EPOCH, + true_anomaly=anomaly, + ), + instruments=[Instrument(name="imager", field_of_regard=100)], + ) + + +def _name(satellite: Satellite) -> str: + return satellite.name + + +def _frame(satellite: Satellite) -> pd.DataFrame: + return pd.DataFrame({"satellite": [satellite.name] * 2}) + + +class TestSatelliteKey(unittest.TestCase): + """ + Unit tests for satellite keys. + """ + + def test_name_is_ignored(self): + """Satellites that differ only in name share a key.""" + self.assertEqual( + get_satellite_key(_satellite("a")), get_satellite_key(_satellite("b")) + ) + + def test_content_is_keyed(self): + """Satellites with other orbits or instruments have other keys.""" + base = _satellite("a") + self.assertNotEqual( + get_satellite_key(base), get_satellite_key(_satellite("a", anomaly=90)) + ) + other = base.model_copy( + update={"instruments": [Instrument(name="imager", field_of_regard=90)]} + ) + self.assertNotEqual(get_satellite_key(base), get_satellite_key(other)) + + +class TestSatelliteCache(unittest.TestCase): + """ + Unit tests for caches of analyses by satellite. + """ + + def setUp(self): + self.calls = [] + + def analysis(satellite): + self.calls.append(satellite.name) + return pd.DataFrame( + {"satellite": [satellite.name] * 2, "value": [1.0, 2.0]} + ) + + self.analysis = analysis + + def test_hits_and_relabeling(self): + """Results are computed once per content and relabeled with the name.""" + cache = SatelliteCache(self.analysis) + first = cache([_satellite("a"), _satellite("b", anomaly=90)]) + second = cache([_satellite("c"), _satellite("d", anomaly=90)]) + self.assertEqual(self.calls, ["a", "b"]) + self.assertEqual((cache.hits, cache.misses), (2, 2)) + self.assertEqual(list(first.satellite), ["a", "a", "b", "b"]) + self.assertEqual(list(second.satellite), ["c", "c", "d", "d"]) + # the cached result is not changed by relabeling + self.assertEqual(list(cache([_satellite("a")]).satellite), ["a", "a"]) + + def test_disk_cache(self): + """Results on disk are shared by caches of the same namespace.""" + with tempfile.TemporaryDirectory() as directory: + SatelliteCache(self.analysis, directory=directory, namespace="x")( + _satellite("a") + ) + again = SatelliteCache(self.analysis, directory=directory, namespace="x") + self.assertEqual(list(again(_satellite("b")).satellite), ["b", "b"]) + self.assertEqual((again.hits, again.misses), (1, 0)) + other = SatelliteCache(self.analysis, directory=directory, namespace="y") + other(_satellite("c")) + self.assertEqual(other.misses, 1) + self.assertEqual(self.calls, ["a", "c"]) + + def test_disk_cache_of_other_functions(self): + """Results on disk are not shared by functions of other definitions.""" + + def make(rows): + # the same function, edited to give other rows + namespace = {"pd": pd} + names = ", ".join(["satellite.name"] * rows) + exec( # pylint: disable=exec-used + "def analysis(satellite):\n" + + f" return pd.DataFrame({{'satellite': [{names}]}})", + namespace, + ) + return SatelliteCache( + namespace["analysis"], directory=directory, namespace="x" + ) + + with tempfile.TemporaryDirectory() as directory: + for rows in (1, 1): + self.assertEqual(len(make(rows)(_satellite("a"))), rows) + # a namespace with results only of the function with other code warns + with self.assertWarnsRegex( + UserWarning, r"1 results.*with other code.*function.(code|constants)" + ) as context: + cache = make(2) + # at the call that makes the cache + self.assertEqual(Path(context.filename).resolve(), Path(__file__).resolve()) + # once, of the caches of the definition (such as of parallel workers) + with warnings.catch_warnings(record=True) as caught: + warnings.simplefilter("always") + make(2) + self.assertEqual(caught, []) + self.assertEqual(len(cache(_satellite("a"))), 2) + namespaces = list(Path(directory).iterdir()) + self.assertEqual(len(namespaces), 1) + self.assertEqual((namespaces[0] / "namespace.txt").read_text(), "x") + folders = [p for p in namespaces[0].iterdir() if p.is_dir()] + self.assertEqual(len(folders), 2) + self.assertTrue(all((p / "definition.json").exists() for p in folders)) + # results of other definitions are removed, and their definitions + # (also those without results) + with warnings.catch_warnings(): + warnings.simplefilter("ignore") + make(3) + self.assertEqual(cache.prune(), 1) + self.assertEqual(len([p for p in namespaces[0].iterdir() if p.is_dir()]), 1) + self.assertEqual(SatelliteCache(_name).prune(), 0) # in memory + + def test_fingerprint(self): + """A cache is described by its function and namespace, not by its + counts of hits and misses, nor the results it holds.""" + + def make(offset, namespace=""): + return SatelliteCache(lambda satellite: offset, namespace=namespace) + + cache = make(0.0) + before = get_fingerprint(cache) + cache(_satellite("a")) + cache(_satellite("b")) + self.assertEqual((cache.hits, cache.misses), (1, 1)) + self.assertEqual(get_fingerprint(cache), before) + self.assertEqual(get_fingerprint(make(0.0)), before) + self.assertNotEqual(get_fingerprint(make(1.0)), before) + self.assertNotEqual(get_fingerprint(make(0.0, "other")), before) + + def test_disk_cache_of_other_data(self): + """Results on disk are keyed by the data the function closes over.""" + + def make(frame): + return SatelliteCache( + lambda satellite: frame.assign(satellite=satellite.name), + directory=directory, + ) + + with tempfile.TemporaryDirectory() as directory: + make(pd.DataFrame({"value": [1.0]}))(_satellite("a")) + same = make(pd.DataFrame({"value": [1.0]})) + same(_satellite("b")) + self.assertEqual((same.hits, same.misses), (1, 0)) + # results of other data are not reused, without a warning (as + # they are not of the same function with other code) + with warnings.catch_warnings(): + warnings.simplefilter("error") + other = make(pd.DataFrame({"value": [2.0]})) + self.assertEqual(list(other(_satellite("c")).value), [2.0]) + self.assertEqual(other.misses, 1) + + def test_contexts(self): + """A cache on disk keeps the context of its namespace beside its + results, by which the namespaces of a directory are found.""" + with tempfile.TemporaryDirectory() as directory: + for namespace, context in ( + ("x", (3, EPOCH)), + ("y", None), + ("z", {"seed": 1}), + ): + SatelliteCache( + self.analysis, + directory=directory, + namespace=namespace, + context=context, + ) + # pylint: disable-next=protected-access + contexts = SatelliteCache._contexts(directory) + self.assertEqual(contexts, {"x": (3, EPOCH), "y": None, "z": {"seed": 1}}) + # a context that cannot be read is none + for path in Path(directory).rglob("context.json"): + path.write_text("{") + found = SatelliteCache._contexts( + directory + ) # pylint: disable=protected-access + self.assertEqual(set(found.values()), {None}) + found = SatelliteCache._contexts(directory) # pylint: disable=protected-access + self.assertEqual(found, {}) # removed + with self.assertRaises(TypeError): + SatelliteCache( # pylint: disable=too-many-function-args + self.analysis, directory + ) + + def test_unreadable_file(self): + """A result that cannot be read from disk is computed again and replaced.""" + with tempfile.TemporaryDirectory() as directory: + cache = SatelliteCache(self.analysis, directory=directory, namespace="x") + cache(_satellite("a")) + for path in Path(directory).rglob("*.pkl"): + path.write_bytes(b"not a pickle") + again = SatelliteCache(self.analysis, directory=directory, namespace="x") + self.assertEqual(list(again(_satellite("b")).satellite), ["b", "b"]) + self.assertEqual(again.misses, 1) + # the file is replaced + third = SatelliteCache(self.analysis, directory=directory, namespace="x") + third(_satellite("c")) + self.assertEqual((third.hits, third.misses), (1, 0)) + + @unittest.skipUnless(HAS_JOBLIB, "requires joblib") + def test_disk_cache_in_parallel(self): + """Workers of a study share a cache on disk, storing each result once.""" + satellites = [_satellite(f"s{i}", anomaly=30 * (i % 4)) for i in range(40)] + with tempfile.TemporaryDirectory() as directory: + cache = SatelliteCache(_frame, directory=directory, namespace="parallel") + study = Study( + DesignSpace(i=Integer(0, 39)), + lambda d: satellites[d.i], + lambda satellite: {"rows": len(cache(satellite))}, + n_jobs=4, + chunks_per_job=5, + ) + results = study.run() + self.assertTrue((results.rows == 2).all()) + files = sorted(p.suffix for p in Path(directory).rglob("*.*")) + self.assertEqual(files, [".json"] + [".pkl"] * 4 + [".txt"]) + + def test_pickled_cache_is_empty(self): + """Copies of a cache (as sent to workers) start without results.""" + cache = SatelliteCache(_name) + cache(_satellite("a")) + copy = pickle.loads(pickle.dumps(cache)) + self.assertEqual(copy._memory, {}) # pylint: disable=protected-access + cache.clear_memory() + self.assertEqual((cache.hits, cache.misses), (0, 0)) + + def test_no_satellites(self): + """No satellites give an empty frame.""" + result = SatelliteCache(self.analysis)([]) + self.assertIsInstance(result, pd.DataFrame) + self.assertEqual(len(result), 0) + + def test_non_frame_results(self): + """Results that are not data frames are listed.""" + cache = SatelliteCache(lambda satellite: satellite.name) + self.assertEqual(cache([_satellite("a"), _satellite("b")]), ["a", "a"]) + + def test_matches_analysis(self): + """Cached observations of satellites match those of the constellation.""" + points = [Point(id=i, latitude=10 * i, longitude=0) for i in range(5)] + end = EPOCH + timedelta(days=1) + satellites = [_satellite(f"s{i}", anomaly=120 * i) for i in range(3)] + cache = SatelliteCache( + lambda satellite: collect_observations(points, satellite, EPOCH, end) + ) + cached = cache(satellites).sort_values(["target_hash", "epoch"]) + direct = collect_observations(points, satellites, EPOCH, end).sort_values( + ["target_hash", "epoch"] + ) + pd.testing.assert_frame_equal( + cached.reset_index(drop=True)[direct.columns], + direct.reset_index(drop=True), + ) diff --git a/tests/tradespace/test_comparison.py b/tests/tradespace/test_comparison.py new file mode 100644 index 0000000..fec830f --- /dev/null +++ b/tests/tradespace/test_comparison.py @@ -0,0 +1,124 @@ +""" +Unit tests for comparisons of designs by the replicates of a metric. + +@author Paul T. Grogan +""" + +import unittest + +import numpy as np +import pandas as pd + +from tatc.tradespace import exceedance + + +def _results(values, feasible=None, **columns): + """Results of designs (by key) in replicates, from a mapping of keys to + the metric of each replicate.""" + rows = [] + for design, metrics in values.items(): + for replicate, value in enumerate(metrics): + rows.append({"design": design, "replicate": replicate, "cost": value}) + frame = pd.DataFrame(rows) + frame["feasible"] = True if feasible is None else feasible + for name, value in columns.items(): + frame[name] = value + return frame + + +class TestExceedance(unittest.TestCase): + """ + Unit tests for the probability that the metric of a design exceeds that + of another. + """ + + def test_pairs(self): + """Shares of the replicates in which a design's metric is greater, ties + counting as half.""" + results = _results( + {"a": [1.0, 2.0, 3.0, 4.0], "b": [2.0, 2.0, 1.0, 5.0], "c": [9.0] * 4} + ) + compared = exceedance(results, "cost").set_index(["design", "other"]) + # designs in the order of their means: a (2.5), b (2.5), c (9) + self.assertEqual( + list(compared.index.get_level_values(0).unique()), ["a", "b", "c"] + ) + self.assertAlmostEqual(compared.loc[("a", "b"), "exceedance"], 1.5 / 4) + self.assertAlmostEqual(compared.loc[("b", "a"), "exceedance"], 2.5 / 4) + self.assertEqual(compared.loc[("a", "a"), "exceedance"], 0.5) + self.assertEqual(compared.loc[("c", "a"), "exceedance"], 1.0) + self.assertAlmostEqual(compared.loc[("a", "b"), "cost difference"], 0.0) + self.assertAlmostEqual(compared.loc[("c", "a"), "cost difference"], 6.5) + self.assertTrue((compared["shared_replicates"] == 4).all()) + self.assertEqual(len(compared), 9) + + def test_order_and_infeasible(self): + """Given designs keep their order, and only replicates in which both + designs are feasible count.""" + results = _results( + {"a": [1.0, 5.0, 1.0], "b": [2.0, 2.0, 2.0]}, + feasible=[True, False, True, True, True, True], + ) + compared = exceedance(results, "cost", ["b", "a"]) + self.assertEqual(list(compared["design"]), ["b", "b", "a", "a"]) + pair = compared[(compared.design == "b") & (compared.other == "a")].iloc[0] + self.assertEqual(pair["shared_replicates"], 2) + self.assertEqual(pair["exceedance"], 1.0) + missing = _results({"a": [np.nan, np.nan], "b": [1.0, 2.0]}) + pair = exceedance(missing, "cost").set_index(["design", "other"]) + self.assertTrue(np.isnan(pair.loc[("a", "b"), "exceedance"])) + self.assertEqual(pair.loc[("a", "b"), "shared_replicates"], 0) + + def test_groups(self): + """Designs are compared in each group of `by`, which several records of + an evaluation need.""" + hot = _results({"a": [1.0, 2.0], "b": [3.0, 4.0]}, scenario="hot") + cold = _results({"a": [5.0, 6.0], "b": [3.0, 4.0]}, scenario="cold") + results = pd.concat([hot, cold], ignore_index=True) + with self.assertRaisesRegex(ValueError, "as `by`") as context: + exceedance(results, "cost") + # exceedance has its own `by`, and no criteria to combine groups across + self.assertNotIn("across", str(context.exception)) + self.assertNotIn("criteria", str(context.exception)) + compared = exceedance(results, "cost", by="scenario").set_index( + ["scenario", "design", "other"] + ) + self.assertEqual(compared.loc[("hot", "a", "b"), "exceedance"], 0.0) + self.assertEqual(compared.loc[("cold", "a", "b"), "exceedance"], 1.0) + + def test_infinite_and_infeasible(self): + """Infinite values are ordered (equal ones tie), designs infeasible in + every replicate come last, and results without feasible ones give + pairs of no replicates.""" + results = _results({"a": [np.inf, 2.0], "b": [np.inf, 1.0]}) + compared = exceedance(results, "cost").set_index(["design", "other"]) + self.assertEqual(compared.loc[("a", "a"), "exceedance"], 0.5) + self.assertEqual(compared.loc[("a", "b"), "exceedance"], 0.75) + self.assertEqual(compared.loc[("b", "a"), "exceedance"], 0.25) + results = _results( + {"a": [3.0, 4.0], "b": [1.0, 2.0]}, feasible=[False, False, True, True] + ) + compared = exceedance(results, "cost") + self.assertEqual(list(compared["design"].unique()), ["b", "a"]) + self.assertTrue(compared[compared.design == "a"]["exceedance"].isna().all()) + results["feasible"] = False + compared = exceedance(results, "cost") + self.assertEqual(len(compared), 4) + self.assertTrue((compared["shared_replicates"] == 0).all()) + empty = exceedance(results.iloc[:0], "cost") + self.assertTrue(empty.empty) + self.assertIn("exceedance", empty.columns) + + def test_invalid(self): + """The metric and the designs must be in the results.""" + results = _results({"a": [1.0], "b": [2.0]}) + with self.assertRaises(ValueError): + exceedance(results, "mass") + with self.assertRaises(ValueError): + exceedance(results, "cost", ["a", "z"]) + with self.assertRaises(TypeError): + exceedance(results, "cost", [1, 2]) + + +if __name__ == "__main__": + unittest.main() diff --git a/tests/tradespace/test_confirmation.py b/tests/tradespace/test_confirmation.py new file mode 100644 index 0000000..b7bb09f --- /dev/null +++ b/tests/tradespace/test_confirmation.py @@ -0,0 +1,164 @@ +""" +Unit tests for the confirmation of selected designs. + +@author Paul T. Grogan +""" + +import unittest +import warnings + +import numpy as np +import pandas as pd + +from tatc.tradespace import ( + Confirmation, + Criteria, + DesignSpace, + Integer, + Probability, + Requirement, + Study, + Uncertain, + confirm, + pareto_front, + summarize, +) + +OBJECTIVES = {"cost": "min", "value": "max"} + + +def _study(replicates=3): + """Designs of equal true values (but for the cost), with independent noise.""" + space = DesignSpace( + cost=Integer(1, 2), variant=Integer(0, 49), noise=Uncertain.normal(0, 1) + ) + return Study( + space, + lambda d: d, + lambda d: {"cost": d.cost, "value": d.cost + d.noise}, + replicates=replicates, + common_random_numbers=False, + ) + + +class TestConfirm(unittest.TestCase): + """ + Unit tests for confirmation. + """ + + def setUp(self): + self.study = _study() + self.designs = self.study.space.enumerate() + self.results = self.study.run(self.designs) + summary = summarize(self.results, statistics=list(OBJECTIVES)) + # the best looking designs of each cost + best = summary.sort_values("value", ascending=False).groupby( + summary.design.map({d.key: d.cost for d in self.designs}) + ) + self.selected_keys = set(best.head(5).design) + self.selected = [d for d in self.designs if d.key in self.selected_keys] + + def test_removes_optimism(self): + """New replicates remove the optimism of selection.""" + confirmation = confirm( + self.study, OBJECTIVES, self.results, self.selected, replicates=20 + ) + self.assertEqual(set(confirmation.summary.design), self.selected_keys) + self.assertTrue((confirmation.summary.replicates == 20).all()) + # the new replicates follow every replicate of the results + self.assertEqual(set(confirmation.results.replicate), set(range(3, 23))) + optimism = confirmation.optimism + self.assertAlmostEqual(optimism["cost"], 0) + # the optimism of each design, signed by the direction of the objective + summary = confirmation.summary + np.testing.assert_allclose( + summary["value optimism"], summary["value selected"] - summary["value"] + ) + np.testing.assert_allclose( + summary["cost optimism"], summary["cost"] - summary["cost selected"] + ) + self.assertAlmostEqual(optimism["value"], summary["value optimism"].mean()) + # the 5 best of 50 designs of 3 replicates look better by about a + # standard deviation of their means (0.58), which the new ones remove + self.assertGreater(optimism["value"], 0.6) + # the confirmed values are unbiased (their true values are the costs) + errors = confirmation.summary.value - confirmation.summary.design.map( + {d.key: d.cost for d in self.designs} + ) + self.assertLess(abs(errors.mean()), 0.15) + + def test_spreads(self): + """The summary gives the spreads of the means by the new replicates, + after each statistic, as summarize does.""" + confirmation = confirm( + self.study, OBJECTIVES, self.results, self.selected, replicates=20 + ) + summary = confirmation.summary + new = summarize(confirmation.results, OBJECTIVES).set_index("design") + np.testing.assert_allclose( + summary.set_index("design").loc[new.index, "value se"], new["value se"] + ) + # the cost, the same in every replicate, has no spread + self.assertNotIn("cost se", summary.columns) + columns = list(summary.columns) + self.assertEqual( + columns[columns.index("value") : columns.index("value") + 4], + ["value", "value std", "value se", "value selected"], + ) + self.assertLess(columns.index("variant"), columns.index("cost")) + + def test_default_front(self): + """Without designs, the front of the results is confirmed; designs may + also be given by their keys or a data frame of them.""" + summary = summarize(self.results, statistics=list(OBJECTIVES)) + front = summary[pareto_front(summary, OBJECTIVES)] + confirmation = confirm(self.study, OBJECTIVES, self.results) + self.assertEqual(set(confirmation.summary.design), set(front.design)) + self.assertEqual({d.key for d in confirmation.designs}, set(front.design)) + by_frame = confirm(self.study, OBJECTIVES, self.results, front) + pd.testing.assert_frame_equal(by_frame.summary, confirmation.summary) + by_keys = confirm(self.study, OBJECTIVES, self.results, list(front.design)) + pd.testing.assert_frame_equal(by_keys.summary, confirmation.summary) + + def test_front(self): + """The front is found among the confirmed designs by the new replicates.""" + confirmation = confirm(self.study, OBJECTIVES, self.results, self.selected) + summary = confirmation.summary + np.testing.assert_array_equal( + summary.pareto, pareto_front(summary, OBJECTIVES).to_numpy() + ) + + def test_requirements(self): + """Requirements are judged by the new replicates.""" + confirmation = confirm( + self.study, + Criteria( + OBJECTIVES, + statistics={"reliability": Probability("value", ">=", 1.5)}, + requirements=[Requirement("reliability", ">=", 0.5)], + ), + self.results, + self.selected, + ) + summary = confirmation.summary + self.assertIn("reliability selected", summary.columns) + np.testing.assert_array_equal( + summary.meets_requirements, summary.reliability >= 0.5 + ) + self.assertFalse((summary.pareto & ~summary.meets_requirements).any()) + with self.assertRaises(ValueError): + confirm(self.study, OBJECTIVES, self.results, self.selected, replicates=0) + + def test_optimism_without_designs(self): + """The optimism of a confirmation without designs is unknown.""" + empty = Confirmation( + results=pd.DataFrame(), + summary=pd.DataFrame({"cost optimism": [], "value optimism": []}), + designs=[], + criteria=Criteria(OBJECTIVES), + ) + with warnings.catch_warnings(): + warnings.simplefilter("error") + optimism = empty.optimism + self.assertTrue(optimism.isna().all()) + self.assertEqual(list(optimism.index), list(OBJECTIVES)) diff --git a/tests/tradespace/test_constellations.py b/tests/tradespace/test_constellations.py new file mode 100644 index 0000000..ca71b6e --- /dev/null +++ b/tests/tradespace/test_constellations.py @@ -0,0 +1,905 @@ +""" +Unit tests for building blocks of constellations. + +@author Paul T. Grogan +""" + +import unittest +from datetime import datetime, time, timezone + +import numpy as np + +import tatc.tradespace + +from tatc.schemas import ( + CircularOrbit, + Instrument, + MOGConstellation, + Satellite, + SOCConstellation, +) +from tatc.tradespace import ( + Categorical, + Choice, + Derived, + DeploymentSchedule, + DesignSpace, + Integer, + Real, + Repeat, + Uncertain, + build_constellation, + count_planes, + count_satellites, + mog_space, + planes_space, + soc_space, + sso_planes_space, + walker_space, +) +from tatc.tradespace.constellations import ( + Layout, + Plane, + hours_to_time, + layout_of, + plane_sizes, + remove_failures, +) +from tatc.tradespace.constellations import ( + WALKER, + Layouts, + MOGLayout, + SOCLayout, + SSOPlanesLayout, + WalkerLayout, +) + +EPOCH = datetime(2026, 1, 1, tzinfo=timezone.utc) +IMAGER = Instrument(name="imager", field_of_regard=60) + + +def _space(): + return DesignSpace( + altitude=Real(600e3, 700e3, step=100e3), + layout=Choice( + walker=walker_space( + inclination=Real(45, 60, step=15), + planes=Integer(1, 3), + per_plane=Integer(1, 2), + ), + sso=sso_planes_space( + crossing=Real(9, 15, step=3), + planes=Integer(1, 2), + per_plane=Integer(1, 2), + ), + ), + constraints=[lambda d: count_satellites(d.layout) - 4], + ) + + +class TestFragments(unittest.TestCase): + """ + Unit tests for fragments of design spaces. + """ + + def test_enumeration(self): + """Fragments enumerate their layouts, with constraints.""" + designs = _space().enumerate() + walker = [d for d in designs if d.layout.choice == "walker"] + sso = [d for d in designs if d.layout.choice == "sso"] + # 2 altitudes x 2 inclinations x (planes, per plane, spacing) with at most + # 4 satellites: 1x1, 1x2 (1 each), 2x1, 2x2 (2 each), 3x1 (3) + self.assertEqual(len(walker), 2 * 2 * (1 + 1 + 2 + 2 + 3)) + # 6 plane designs: one plane (6), or two with different crossings + # (6 x 6 - same-crossing pairs) / 2 unordered = 12 + self.assertEqual(len(sso), 2 * (6 + 12)) + for design in sso: + crossings = [plane.crossing for plane in design.layout.planes] + self.assertEqual(len(set(crossings)), len(crossings)) + self.assertTrue(all(count_satellites(d.layout) <= 4 for d in designs)) + + def test_counts(self): + """Satellites and planes are counted for each pattern of layout.""" + designs = _space().enumerate() + walker = [d for d in designs if d.layout.choice == "walker"][-1] + self.assertEqual(count_planes(walker.layout), walker.layout.planes) + self.assertEqual( + count_satellites(walker.layout), + walker.layout.planes * walker.layout.per_plane, + ) + sso = [d for d in designs if d.layout.choice == "sso"][-1] + self.assertEqual(count_planes(sso.layout), sso.layout.planes.count) + with self.assertRaises(ValueError): + count_planes(sso) + + def test_defaults(self): + """Fragments have default variables.""" + self.assertGreater(DesignSpace(layout=walker_space(altitude=500e3)).size(), 100) + self.assertGreater( + DesignSpace(layout=sso_planes_space(altitude=500e3)).size(), 100 + ) + + def test_single_constraint(self): + """Fragments take a constraint, or a sequence of them.""" + + def at_most_two(d): + return count_satellites(d) <= 2 + + fragments = { + "walker": lambda c: walker_space( + inclination=60, + planes=Integer(1, 2), + per_plane=Integer(1, 2), + constraints=c, + ), + "sso": lambda c: sso_planes_space( + crossing=Real(6, 9, step=3), + planes=Integer(1, 2), + per_plane=Integer(1, 2), + constraints=c, + ), + "planes": lambda c: planes_space( + inclination=60, + planes=Integer(1, 2), + per_plane=Integer(1, 2), + constraints=c, + ), + } + for name, fragment in fragments.items(): + single = DesignSpace(layout=fragment(at_most_two)).enumerate() + listed = DesignSpace(layout=fragment([at_most_two])).enumerate() + self.assertEqual([d.key for d in single], [d.key for d in listed], name) + self.assertTrue(all(count_satellites(d.layout) <= 2 for d in single)) + self.assertLess(len(single), DesignSpace(layout=fragment(())).size()) + # the crossings of planes of sun-synchronous orbits are still distinct + planes = DesignSpace(layout=fragments["sso"](at_most_two)).enumerate() + for design in planes: + crossings = [plane.crossing for plane in design.layout.planes] + self.assertEqual(len(set(crossings)), len(crossings)) + + +class TestBuild(unittest.TestCase): + """ + Unit tests for building constellations. + """ + + def test_walker(self): + """Walker layouts build the members of a Walker constellation.""" + space = DesignSpace( + altitude=650e3, + layout=walker_space( + inclination=55, planes=3, per_plane=2, relative_spacing=1 + ), + ) + design = space.enumerate()[0] + satellites = build_constellation( + design.layout, IMAGER, epoch=EPOCH, altitude=design.altitude, name="w" + ) + self.assertEqual(len(satellites), 6) + self.assertEqual(satellites[0].name, "w 1") + self.assertEqual(satellites[0].instruments, [IMAGER]) + raans = {round(s.orbit.right_ascension_ascending_node, 6) for s in satellites} + self.assertEqual(len(raans), 3) + self.assertTrue(all(s.orbit.inclination == 55 for s in satellites)) + + def test_sso(self): + """Sun-synchronous layouts build evenly spaced satellites in their planes.""" + space = DesignSpace( + layout=sso_planes_space( + crossing=13.5, + per_plane=4, + planes=1, + phase_fraction=Uncertain.uniform(0, 1), + altitude=700e3, + ), + ) + design = space.enumerate()[0].realize(0) + satellites = build_constellation(design.layout, [IMAGER], epoch=EPOCH) + self.assertEqual( + [s.name for s in satellites][:2], ["satellite 1-1", "satellite 1-2"] + ) + anomalies = [s.orbit.true_anomaly for s in satellites] + gaps = np.diff(np.unwrap(np.radians(anomalies))) + np.testing.assert_allclose(np.degrees(gaps) % 360, 90) + self.assertEqual(satellites[0].orbit.equator_crossing_time, time(13, 30)) + plane = design.layout.planes[0] + self.assertAlmostEqual(anomalies[0], plane.true_anomaly) + # a fraction of the 90 degrees between 4 evenly spaced satellites + self.assertAlmostEqual(plane.true_anomaly, plane.phase_fraction * 90) + + def test_derived_planes(self): + """Plane values may be derived from their index and enclosing values.""" + space = DesignSpace( + size=Integer(1, 2), + layout=sso_planes_space( + crossing=Derived(lambda d: (13.5 + 12 * d.index / d.planes.count) % 24), + planes=Integer(1, 3), + per_plane=Derived(lambda d: d.size), + ordered=True, + ), + ) + design = [d for d in space.enumerate() if len(d.layout.planes) == 3][-1] + satellites = build_constellation( + design.layout, IMAGER, epoch=EPOCH, altitude=830e3 + ) + self.assertEqual(len(satellites), 3 * design.size) + times = sorted({s.orbit.equator_crossing_time for s in satellites}) + self.assertEqual(times, [time(13, 30), time(17, 30), time(21, 30)]) + + def test_catalog_payloads(self): + """Catalog entries are built with their validated attitude.""" + space = DesignSpace( + sounder=Categorical(["atms", "cris"]), + layout=sso_planes_space(crossing=13.5, per_plane=1, planes=1), + ) + design = space.enumerate()[0] + satellite = build_constellation( + design.layout, design.sounder, epoch=EPOCH, altitude=830e3, time_step=30 + )[0] + self.assertIsInstance(satellite, Satellite) + self.assertIsNotNone(satellite.attitude) + both = build_constellation( + design.layout, + ["atms:swath_noaa_20", "cris:swath"], + epoch=EPOCH, + altitude=830e3, + time_step=30, + )[0] + self.assertEqual(len(both.instruments), 2) + custom = build_constellation( + design.layout, + lambda name, orbit: Satellite(name=name, orbit=orbit, instruments=[IMAGER]), + epoch=EPOCH, + altitude=830e3, + )[0] + self.assertEqual(custom.instruments, [IMAGER]) + with self.assertRaises(ValueError): + build_constellation(design.layout, IMAGER, epoch=EPOCH) + + def test_hours_to_time(self): + """Hours convert to times of day, wrapping and rounding to seconds.""" + self.assertEqual(hours_to_time(13.5), time(13, 30)) + self.assertEqual(hours_to_time(15.9), time(15, 54)) + self.assertEqual(hours_to_time(24.25), time(0, 15)) + self.assertEqual(hours_to_time(10.9999999), time(11, 0)) + + +class TestFailures(unittest.TestCase): + """ + Unit tests for failures of satellites. + """ + + def test_remove_failures(self): + """Failures depend on the seed and position, common to every design.""" + satellites = [ + Satellite(name=f"s{k}", orbit=_orbit(), instruments=[IMAGER]) + for k in range(200) + ] + survivors = remove_failures(satellites, 0.25, seed=7) + self.assertAlmostEqual(len(survivors) / 200, 0.75, delta=0.08) + # the first 10 satellites fail alike in a design of 10 + first = {s.name for s in remove_failures(satellites[:10], 0.25, seed=7)} + self.assertEqual(first, {s.name for s in survivors if int(s.name[1:]) < 10}) + self.assertEqual(len(remove_failures(satellites, 0.25, seed=None)), 200) + self.assertEqual(remove_failures(satellites, 1.0, seed=3), []) + with self.assertRaises(ValueError): + remove_failures(satellites, 1.5, seed=3) + + def test_seed(self): + """Uncertain seeds are drawn for each replicate, common to designs.""" + space = DesignSpace(a=Integer(1, 2), seed=Uncertain.seed()) + a, b = space.enumerate() + self.assertIsNone(a.seed) + self.assertEqual(a.realize(3).seed, b.realize(3).seed) + self.assertNotEqual(a.realize(3).seed, a.realize(4).seed) + + +def _orbit(): + from tatc.schemas import ( + SunSynchronousOrbit, + ) # pylint: disable=import-outside-toplevel + + return SunSynchronousOrbit( + altitude=700e3, equator_crossing_time="10:30", epoch=EPOCH + ) + + +def _walker(**kwargs): + """The satellites of a Walker layout (on its own) of given values.""" + values = { + "inclination": 55.0, + "planes": 3, + "per_plane": 4, + "relative_spacing": 1, + "configuration": "delta", + **kwargs, + } + space = DesignSpace(layout=walker_space(**values)) + (design,) = space.enumerate() + return design, build_constellation( + design.layout, IMAGER, epoch=EPOCH, altitude=700e3 + ) + + +def _orbits(satellites): + """The (node, anomaly) of each satellite, as a set, ignoring names.""" + return { + ( + round(s.orbit.right_ascension_ascending_node % 360, 6) % 360, + round(s.orbit.true_anomaly % 360, 6) % 360, + ) + for s in satellites + } + + +class TestWalkerPhase(unittest.TestCase): + """ + Unit tests for the phase and node of the lead satellite of Walker layouts. + """ + + def test_default(self): + """The lead satellite is at the origin by default.""" + design, satellites = _walker() + self.assertEqual(design.layout.true_anomaly, 0) + self.assertEqual(design.layout.node, 0) + self.assertEqual(satellites[0].orbit.true_anomaly, 0) + self.assertEqual(satellites[0].orbit.right_ascension_ascending_node, 0) + + def test_fractions(self): + """Fractions give angles of the intervals of distinct constellations.""" + design, satellites = _walker(phase_fraction=0.5, node_fraction=0.25) + self.assertAlmostEqual(design.layout.true_anomaly, 0.5 * 360 / 4) + self.assertAlmostEqual(design.layout.node, 0.25 * 360 / 3) + self.assertAlmostEqual(satellites[0].orbit.true_anomaly, 45) + self.assertAlmostEqual(satellites[0].orbit.right_ascension_ascending_node, 30) + star, _ = _walker(configuration="star", node_fraction=0.25) + self.assertAlmostEqual(star.layout.node, 90) + + def test_symmetries(self): + """A whole interval of phase or node gives the same constellation.""" + _, base = _walker() + _, phased = _walker(phase_fraction=1.0) + self.assertEqual(_orbits(phased), _orbits(base)) + # a shift of node by 360 / planes is a shift of phase by + # -360 * relative_spacing / satellites (a fraction of -1 / planes) + _, noded = _walker(node_fraction=1.0) + _, shifted = _walker(phase_fraction=-1 / 3) + self.assertEqual(_orbits(noded), _orbits(shifted)) + self.assertNotEqual(_orbits(noded), _orbits(base)) + # fractions within the intervals give other constellations + _, half = _walker(phase_fraction=0.5) + self.assertNotEqual(_orbits(half), _orbits(base)) + + def test_uncertain_and_designed(self): + """Fractions are design variables or uncertain parameters.""" + space = DesignSpace( + layout=walker_space( + inclination=55.0, + planes=Integer(1, 2), + per_plane=2, + relative_spacing=0, + phase_fraction=Uncertain.uniform(0, 1), + node_fraction=Real(0, 0.5, step=0.5), + ) + ) + designs = space.enumerate() + self.assertEqual(len(designs), 4) + realized = designs[-1].realize(0) + fraction = realized.layout.phase_fraction + self.assertTrue(0 <= fraction < 1) + self.assertAlmostEqual(realized.layout.true_anomaly, fraction * 180) + self.assertAlmostEqual(realized.layout.node, 0.5 * 180) + # the same draw in every design (common random numbers) + self.assertEqual(designs[0].realize(0).layout.phase_fraction, fraction) + + +def _minutes(value): + """Minutes of a time of day.""" + return value.hour * 60 + value.minute + value.second / 60 + + +def _single(space): + """The only design of a design space.""" + (design,) = space.enumerate() + return design + + +class TestTrains(unittest.TestCase): + """ + Unit tests for trains of satellites in planes. + """ + + def _build(self, **kwargs): + space = DesignSpace( + layout=sso_planes_space(crossing=13.5, per_plane=3, planes=1, **kwargs) + ) + return build_constellation( + _single(space).layout, IMAGER, epoch=EPOCH, altitude=700e3 + ) + + def test_evenly_spaced(self): + """Without an interval, satellites are evenly spaced.""" + satellites = self._build() + anomalies = [s.orbit.true_anomaly for s in satellites] + np.testing.assert_allclose(anomalies, [0, 120, 240]) + + def test_same_ground_track(self): + """A train on the same ground track crosses at later local times.""" + satellites = self._build(interval=10) + crossings = [_minutes(s.orbit.equator_crossing_time) for s in satellites] + np.testing.assert_allclose(np.diff(crossings), [10, 10], atol=0.05) + # each trails the one ahead by 10 minutes of a ~99 minute orbit + anomalies = [s.orbit.true_anomaly for s in satellites] + lags = np.mod(-np.diff(anomalies), 360) + np.testing.assert_allclose(lags, 360 * 10 / 98.8, rtol=0.01) + self.assertEqual( + [s.name for s in satellites], [f"satellite 1-{k}" for k in (1, 2, 3)] + ) + + def test_same_plane(self): + """A train in the same plane crosses at the same local time.""" + satellites = self._build(interval=10, repeat_ground_track=False) + crossings = {_minutes(s.orbit.equator_crossing_time) for s in satellites} + self.assertEqual(len(crossings), 1) + + def test_phase_fraction(self): + """Phases are fractions of the interval of distinct planes.""" + even = self._build(phase_fraction=0.25) + self.assertAlmostEqual(even[0].orbit.true_anomaly, 0.25 * 120) + # a whole interval moves each satellite onto the next + shifted = self._build(phase_fraction=1.0) + self.assertEqual( + sorted(round(s.orbit.true_anomaly % 360, 6) for s in shifted), + sorted(round(s.orbit.true_anomaly % 360, 6) for s in self._build()), + ) + # a train has no such symmetry: its interval is 360 degrees + train = self._build(phase_fraction=0.25, interval=10) + self.assertAlmostEqual(train[0].orbit.true_anomaly, 90) + + def test_interval_variable(self): + """The interval is a design variable that may be evenly spaced.""" + space = DesignSpace( + layout=sso_planes_space( + crossing=13.5, per_plane=2, planes=1, interval=Categorical([None, 5]) + ) + ) + designs = space.enumerate() + self.assertEqual(len(designs), 2) + built = [ + build_constellation(d.layout, IMAGER, epoch=EPOCH, altitude=700e3) + for d in designs + ] + self.assertAlmostEqual(built[0][1].orbit.true_anomaly, 180) + self.assertLess(np.mod(-built[1][1].orbit.true_anomaly, 360), 30) + with self.assertRaises(ValueError): + self._build(interval=0) + + +class TestPlanes(unittest.TestCase): + """ + Unit tests for planes of inclined orbits. + """ + + def test_uncertain_nodes(self): + """Nodes are uncertain by default, drawn for each replicate.""" + space = DesignSpace( + layout=planes_space(inclination=30.0, per_plane=2, planes=Integer(1, 3)), + constraints=[lambda d: count_satellites(d.layout) <= 4], + ) + designs = space.enumerate() + self.assertEqual(len(designs), 2) + realized = designs[1].realize(3) + nodes = [plane.node for plane in realized.layout.planes] + self.assertTrue(all(0 <= node < 360 for node in nodes)) + self.assertNotEqual(nodes[0], nodes[1]) + satellites = build_constellation( + realized.layout, IMAGER, epoch=EPOCH, altitude=550e3 + ) + self.assertEqual(len(satellites), 4) + self.assertEqual(count_planes(realized.layout), 2) + self.assertAlmostEqual( + satellites[2].orbit.right_ascension_ascending_node, nodes[1] + ) + self.assertEqual(satellites[0].orbit.inclination, 30) + + def test_designed_nodes_and_trains(self): + """Nodes may be designed, and planes may be trains.""" + space = DesignSpace( + layout=planes_space( + inclination=Real(30, 60, step=30), + node=Real(0, 90, step=90), + per_plane=2, + planes=1, + interval=5, + repeat_ground_track=False, + ) + ) + designs = space.enumerate() + self.assertEqual(len(designs), 4) + satellites = build_constellation( + designs[-1].layout, IMAGER, epoch=EPOCH, altitude=550e3 + ) + self.assertEqual( + {s.orbit.right_ascension_ascending_node for s in satellites}, {90} + ) + self.assertEqual({s.orbit.inclination for s in satellites}, {60}) + + +class TestStreetsOfCoverage(unittest.TestCase): + """ + Unit tests for streets-of-coverage layouts. + """ + + def test_derived_planes(self): + """The planes and satellites in each are those of the constellation.""" + space = DesignSpace( + layout=soc_space(swath_width=4000e3, inclination=60.0, altitude=700e3) + ) + (design,) = space.enumerate() + soc = SOCConstellation( + name="soc", + orbit=CircularOrbit(altitude=700e3, inclination=60, epoch=EPOCH), + swath_width=4000e3, + packing_distance=1, + ) + self.assertEqual(design.layout.planes, soc.get_number_planes()) + self.assertEqual(design.layout.per_plane, soc.get_satellites_per_plane()) + self.assertIsInstance(layout_of(design.layout), SOCLayout) + satellites = build_constellation(design.layout, IMAGER, epoch=EPOCH) + self.assertEqual(_orbits(satellites), _orbits(soc.generate_members())) + self.assertEqual(satellites[0].name, "satellite 1") + self.assertEqual(count_planes(design.layout), design.layout.planes) + self.assertEqual( + plane_sizes(design.layout), [design.layout.per_plane] * design.layout.planes + ) + + def test_altitude_outside(self): + """The altitude may be decided outside the fragment, before it.""" + space = DesignSpace( + altitude=Real(500e3, 1000e3, step=500e3), + layout=soc_space(swath_width=6000e3, inclination=90.0), + ) + low, high = space.enumerate() + self.assertGreater(count_satellites(low.layout), count_satellites(high.layout)) + satellites = build_constellation( + high.layout, IMAGER, epoch=EPOCH, altitude=high.altitude + ) + self.assertEqual(len(satellites), count_satellites(high.layout)) + # the fragment keeps the altitude its planes were derived at, which + # builds its satellites whatever altitude is given + self.assertEqual(high.layout.altitude, high.altitude) + for given in (None, 500e3): + built = build_constellation( + high.layout, IMAGER, epoch=EPOCH, altitude=given + ) + self.assertEqual(len(built), count_satellites(high.layout)) + self.assertAlmostEqual(built[0].orbit.mean_altitude, 1000e3) + + def test_constraints(self): + """Constraints of the fragment limit the satellites it derives.""" + space = DesignSpace( + layout=soc_space( + swath_width=Categorical([4000e3, 6000e3]), + inclination=90.0, + altitude=1000e3, + constraints=[lambda d: d.planes * d.per_plane <= 50], + ) + ) + (design,) = space.enumerate() + self.assertEqual(design.layout.swath_width, 6000e3) + + def test_fractions(self): + """The node of the lead satellite of polar planes is of 360 degrees.""" + for inclination, polar in [(60.0, False), (90.0, True)]: + space = DesignSpace( + layout=soc_space( + swath_width=6000e3, + inclination=inclination, + altitude=1000e3, + phase_fraction=0.5, + node_fraction=0.5, + ) + ) + (design,) = space.enumerate() + layout = design.layout + self.assertAlmostEqual(layout.true_anomaly, 180 / layout.per_plane) + self.assertAlmostEqual(layout.node, 180 if polar else 180 / layout.planes) + satellites = build_constellation(layout, IMAGER, epoch=EPOCH) + self.assertAlmostEqual( + satellites[0].orbit.right_ascension_ascending_node, + layout.node, + ) + + +class TestMutualOrbitingGroup(unittest.TestCase): + """ + Unit tests for mutual orbiting groups. + """ + + def test_build(self): + """A group is a single plane of the satellites of the constellation.""" + space = DesignSpace( + layout=mog_space( + parallel_axis=100e3, + transverse_axis=50e3, + inclination=60.0, + node=30.0, + satellites=3, + phase_fraction=0.25, + altitude=500e3, + ) + ) + (design,) = space.enumerate() + self.assertEqual(design.layout.true_anomaly, 90) + self.assertIsInstance(layout_of(design.layout), MOGLayout) + satellites = build_constellation(design.layout, IMAGER, epoch=EPOCH) + mog = MOGConstellation( + name="mog", + orbit=CircularOrbit( + altitude=500e3, + inclination=60, + right_ascension_ascending_node=30, + true_anomaly=90, + epoch=EPOCH, + ), + parallel_axis=100e3, + transverse_axis=50e3, + number_satellites=3, + ) + self.assertEqual( + [s.orbit for s in satellites], [m.orbit for m in mog.generate_members()] + ) + self.assertEqual( + [s.name for s in satellites], ["satellite 1", "satellite 2", "satellite 3"] + ) + self.assertEqual(count_satellites(design.layout), 3) + self.assertEqual(count_planes(design.layout), 1) + + def test_defaults(self): + """By default, the inclination and number of satellites are designed.""" + space = DesignSpace( + layout=mog_space(parallel_axis=100e3, transverse_axis=50e3, altitude=500e3) + ) + self.assertEqual(space.size(), 5 * 5) + + +class TestMixedLayouts(unittest.TestCase): + """ + Unit tests for constellations of several layouts. + """ + + def test_list_of_layouts(self): + """Several layouts are built and counted together.""" + space = DesignSpace( + inclined=walker_space( + inclination=65.0, planes=1, per_plane=2, relative_spacing=0 + ), + polar=sso_planes_space( + crossing=13.5, per_plane=1, planes=2, distinct=False + ), + ) + design = _single(space) + layouts = [design.inclined, design.polar] + satellites = build_constellation(layouts, IMAGER, epoch=EPOCH, altitude=700e3) + self.assertEqual( + [s.name for s in satellites], + ["satellite A 1", "satellite A 2", "satellite B 1-1", "satellite B 2-1"], + ) + self.assertEqual(count_satellites(layouts), 4) + self.assertEqual(count_planes(layouts), 3) + + def test_repeat_of_choice(self): + """A repetition of a choice of layouts is a variable mix of shells.""" + space = DesignSpace( + shells=Repeat( + Choice( + walker=walker_space( + inclination=65.0, planes=1, per_plane=2, relative_spacing=0 + ), + sso=sso_planes_space(crossing=13.5, per_plane=1, planes=1), + ), + count=Integer(1, 2), + ) + ) + designs = space.enumerate() + self.assertEqual(len(designs), 2 + 4) + mixed = [ + d for d in designs if [s.choice for s in d.shells] == ["walker", "sso"] + ] + (design,) = mixed + satellites = build_constellation( + design.shells, IMAGER, epoch=EPOCH, altitude=700e3 + ) + self.assertEqual(len(satellites), 3) + self.assertEqual(count_satellites(design.shells), 3) + self.assertEqual(count_planes(design.shells), 2) + + +class _Pair(Layout): + """Two satellites in each of two planes of given nodes, for the tests.""" + + def __init__(self, nodes, altitude=None): + self.nodes, self.altitude = nodes, altitude + + def planes(self): + return [Plane(2, node) for node in self.nodes] + + def orbits(self, epoch, altitude=None): + altitude = self.altitude if altitude is None else altitude + return [ + [ + CircularOrbit( + altitude=altitude, + inclination=50, + right_ascension_ascending_node=node, + true_anomaly=anomaly, + epoch=epoch, + ) + for anomaly in (0, 180) + ] + for node in self.nodes + ] + + +class TestLayout(unittest.TestCase): + """ + Unit tests for layouts. + """ + + def test_layout_of(self): + """The values of each fragment are those of a layout.""" + designs = _space().enumerate() + walker = next(d for d in designs if d.layout.choice == "walker") + sso = next(d for d in designs if d.layout.choice == "sso") + self.assertIsInstance(layout_of(walker.layout), WalkerLayout) + self.assertIsInstance(layout_of(sso.layout), SSOPlanesLayout) + both = layout_of([walker.layout, sso.layout]) + self.assertIsInstance(both, Layouts) + self.assertEqual(both.satellites, count_satellites(walker.layout) + 1) + self.assertIs(layout_of(both), both) + planes = layout_of(sso.layout).planes() + self.assertEqual(planes[0].values.crossing, sso.layout.planes[0].crossing) + self.assertIsNone(layout_of(walker.layout).planes()[0].values) + with self.assertRaises(ValueError): + layout_of({"pattern": "flower"}) + # the values of a fragment name its pattern (not a type of satellite) + self.assertEqual(walker.layout.value.pattern, WALKER) + self.assertIs(tatc.tradespace.layout_of, layout_of) + + def test_walker_planes(self): + """The satellites of a Walker layout follow each other plane by plane.""" + space = DesignSpace( + layout=walker_space( + inclination=60.0, planes=3, per_plane=2, relative_spacing=1 + ) + ) + layout = layout_of(_single(space).layout) + self.assertEqual([p.satellites for p in layout.planes()], [2, 2, 2]) + orbits = layout.orbits(EPOCH, 700e3) + nodes = [{o.right_ascension_ascending_node for o in plane} for plane in orbits] + self.assertEqual(nodes, [{0.0}, {120.0}, {240.0}]) + self.assertEqual( + [s.name for s in layout.build(IMAGER, epoch=EPOCH, altitude=700e3)], + [f"satellite {k}" for k in range(1, 7)], + ) + with self.assertRaises(ValueError): + layout.orbits(EPOCH) # no altitude + + def test_custom_layout(self): + """Other layouts are built, counted, and deployed as the others.""" + layout = _Pair([0, 90], altitude=600e3) + satellites = build_constellation(layout, IMAGER, epoch=EPOCH) + self.assertEqual( + [s.name for s in satellites], + ["satellite 1-1", "satellite 1-2", "satellite 2-1", "satellite 2-2"], + ) + self.assertEqual(satellites[2].orbit.right_ascension_ascending_node, 90) + self.assertEqual(count_satellites(layout), 4) + self.assertEqual(count_planes(layout), 2) + self.assertEqual(plane_sizes(layout), [2, 2]) + # the nodes of the planes order their deployment (90, 45, then 0) + schedule = DeploymentSchedule( + years=3, production_rate=2, order=lambda index, node: -node + ) + layouts = [layout, _Pair([45], altitude=600e3)] + deployment = schedule.plan(layouts) + self.assertEqual([launch.plane for launch in deployment.launches], [1, 2, 0]) + phases = deployment.phases(build_constellation(layouts, IMAGER, epoch=EPOCH)) + self.assertEqual([len(phase.satellites) for phase in phases], [2, 4, 6]) + + def test_mismatched_orbits(self): + """A layout whose orbits do not match its planes is not built.""" + + class Short(_Pair): + """A layout with an orbit missing.""" + + def orbits(self, epoch, altitude=None): + orbits = super().orbits(epoch, altitude) + return [orbits[0][:1], *orbits[1:]] + + with self.assertRaises(ValueError): + Short([0, 90], altitude=600e3).build(IMAGER, epoch=EPOCH) + + +class TestDescriptions(unittest.TestCase): + """ + Unit tests for the descriptions of layouts, and their altitudes. + """ + + def test_describe(self): + """Layouts describe themselves briefly.""" + from tatc.tradespace.constellations import ( + layout_of, + ) # pylint: disable=import-outside-toplevel + + walker = _single( + DesignSpace( + layout=walker_space( + inclination=60, planes=3, per_plane=4, relative_spacing=1 + ) + ) + ).layout + self.assertEqual( + layout_of(walker).describe(), "Walker 60 deg: 3 x 4 (spacing 1)" + ) + self.assertIn("Walker 60 deg", repr(layout_of(walker))) + sso = _single( + DesignSpace( + layout=sso_planes_space( + crossing=Derived(lambda d: [6, 13.5][d.index]), + planes=2, + per_plane=Integer(1, 1), + ordered=True, + ) + ) + ).layout + self.assertEqual(str(layout_of(sso)), "SSO: 1 at 06:00, 1 at 13:30") + mixed = layout_of([walker, sso]) + self.assertEqual( + mixed.describe(), + "Walker 60 deg: 3 x 4 (spacing 1); SSO: 1 at 06:00, 1 at 13:30", + ) + mog = _single( + DesignSpace( + layout=mog_space( + parallel_axis=10e3, + transverse_axis=5e3, + inclination=45, + satellites=3, + altitude=500e3, + ) + ) + ).layout + self.assertEqual( + layout_of(mog).describe(), "MOG 45 deg at 500 km: 3 satellites (10 x 5 km)" + ) + + def test_own_altitude(self): + """A layout's own altitude is built, rather than the one given.""" + layout = _single( + DesignSpace( + layout=walker_space( + inclination=60, planes=1, per_plane=1, altitude=700e3 + ) + ) + ).layout + satellites = build_constellation(layout, IMAGER, epoch=EPOCH, altitude=500e3) + self.assertAlmostEqual(satellites[0].orbit.mean_altitude, 700e3) + + def test_unrealized(self): + """A layout of unrealized values (NaN) is not built.""" + space = DesignSpace( + layout=walker_space( + inclination=60, + planes=1, + per_plane=2, + phase_fraction=Uncertain.uniform(0, 1), + ) + ) + design = space.enumerate()[0] + with self.assertRaisesRegex(ValueError, "realize"): + build_constellation(design.layout, IMAGER, epoch=EPOCH, altitude=500e3) + built = build_constellation( + design.realize(0).layout, IMAGER, epoch=EPOCH, altitude=500e3 + ) + self.assertEqual(len(built), 2) diff --git a/tests/tradespace/test_cost.py b/tests/tradespace/test_cost.py new file mode 100644 index 0000000..122359e --- /dev/null +++ b/tests/tradespace/test_cost.py @@ -0,0 +1,833 @@ +""" +Unit tests for life-cycle costs of constellations. + +@author Paul T. Grogan +""" + +import dataclasses +import math +import unittest + +import numpy as np +import pandas as pd + +from tatc.tradespace import ( + Categorical, + Component, + CostModel, + DeploymentSchedule, + DesignSpace, + Integer, + LaunchCost, + MissionPlan, + OperationsCost, + Quantile, + RestorationPolicy, + SatelliteCost, + Study, + Triangular, + Uncertain, + count_satellites, + exceedance, + planes_space, + risk_space, + sso_planes_space, + summarize, + walker_space, +) +from tatc.tradespace.constellations import plane_sizes +from tatc.tradespace.mission import Capability + + +def _design(**children): + """The only design of a design space.""" + (design,) = DesignSpace(**children).enumerate() + return design + + +def _walker(planes=3, per_plane=4): + return _design( + layout=walker_space( + inclination=55.0, planes=planes, per_plane=per_plane, relative_spacing=0 + ) + ).layout + + +class TestSatelliteCost(unittest.TestCase): + """ + Unit tests for costs of satellites. + """ + + def test_learning_curve(self): + """Each doubling of units costs the learning rate times as much per unit.""" + flat = SatelliteCost(first_unit=10) + self.assertEqual(flat.production(5), 50) + learning = SatelliteCost(first_unit=10, learning_rate=0.9) + self.assertAlmostEqual(learning.production(1), 10) + self.assertAlmostEqual(learning.production(2), 10 + 9) + self.assertAlmostEqual(learning.production(4) - learning.production(3), 8.1) + self.assertEqual(learning.production(0), 0) + with self.assertRaises(ValueError): + SatelliteCost(first_unit=10, learning_rate=1.2) + with self.assertRaises(ValueError): + SatelliteCost(development=-1) + + def test_blocks(self): + """The learning curve restarts with each block of production.""" + blocks = SatelliteCost(first_unit=10, learning_rate=0.9, block_size=2) + self.assertAlmostEqual(blocks.production(2), 10 + 9) + self.assertAlmostEqual(blocks.production(5), 3 * 10 + 2 * 9) + self.assertEqual([blocks.blocks(n) for n in (0, 1, 2, 3, 5)], [0, 1, 1, 2, 3]) + self.assertEqual(SatelliteCost(first_unit=10).blocks(7), 1) + for invalid in ({"block_size": 0}, {"block_size": 2.5}, {"redevelopment": -1}): + with self.assertRaises(ValueError): + SatelliteCost(**invalid) + + +class TestPlaneSizes(unittest.TestCase): + """ + Unit tests for the satellites of each plane of layouts. + """ + + def test_layouts(self): + """Plane sizes of each layout, and of several.""" + walker = _walker(planes=2, per_plane=3) + sso = _design( + layout=sso_planes_space(crossing=13.5, per_plane=2, planes=1) + ).layout + inclined = _design( + layout=planes_space(inclination=30.0, node=0.0, per_plane=4, planes=2) + ).layout + self.assertEqual(plane_sizes(walker), [3, 3]) + self.assertEqual(plane_sizes(sso), [2]) + self.assertEqual(plane_sizes(inclined), [4, 4]) + self.assertEqual(plane_sizes([walker, sso]), [3, 3, 2]) + + +class TestCostModel(unittest.TestCase): + """ + Unit tests for life-cycle costs of deployments. + """ + + def setUp(self): + self.satellite = SatelliteCost( + development=100, first_unit=10, learning_rate=0.9 + ) + + def test_elements(self): + """Costs of development, production, launches, and operations.""" + model = CostModel( + self.satellite, + launch=LaunchCost(per_launch=30), + operations=OperationsCost(per_year=5, per_satellite_year=1), + ) + schedule = DeploymentSchedule(years=6, design_life=3, launch_capacity=3) + estimate = model.estimate(schedule.plan(_walker(planes=3, per_plane=4))) + # two generations of 3 planes of 4 satellites, 2 launches each + self.assertEqual(estimate.units, {None: 24}) + self.assertEqual(estimate.launches, 12) + self.assertEqual(estimate.development, 100) + self.assertAlmostEqual(estimate.production, self.satellite.production(24)) + self.assertEqual(estimate.launch, 12 * 30) + self.assertEqual(estimate.operations, 6 * (5 + 12)) + self.assertAlmostEqual( + estimate.total, 100 + self.satellite.production(24) + 360 + 102 + ) + # without discounting, the present value is the total + self.assertAlmostEqual(estimate.present_value, estimate.total) + metrics = estimate.metrics() + self.assertEqual( + list(metrics), + [ + "cost", + "cost development", + "cost production", + "cost launch", + "cost operations", + "cost present", + "cost peak annual", + ], + ) + self.assertEqual(metrics["cost"], estimate.total) + + def test_rideshare(self): + """Rideshares are priced per satellite and per kg.""" + model = CostModel( + self.satellite, launch=LaunchCost(per_satellite=2, per_kg=0.1) + ) + estimate = model.estimate(DeploymentSchedule().plan(_walker(1, 4), masses=50)) + self.assertEqual(estimate.launches, 1) # counted, though not priced per launch + self.assertAlmostEqual(estimate.launch, 4 * (2 + 0.1 * 50)) + with self.assertRaises(ValueError): + CostModel(SatelliteCost(), launch=LaunchCost(per_kg=1)).estimate( + DeploymentSchedule().plan(_walker()) + ) + + def test_spares(self): + """Spares in orbit are built, launched, and operated with each plane, + and spares on the ground are built, of the policy of the deployment.""" + model = CostModel( + self.satellite, + launch=LaunchCost(per_launch=30), + operations=OperationsCost(per_satellite_year=1), + ) + schedule = DeploymentSchedule(launch_capacity=4) + spared = RestorationPolicy(orbit_spares=1) + estimate = model.estimate(schedule.plan(_walker(2, 4), policy=spared)) + self.assertEqual(estimate.units[None], 10) + self.assertEqual(estimate.launches, 4) + self.assertEqual(estimate.operations, 10) + # spares (which do not age) are not replaced at each design life + replaced = dataclasses.replace(schedule, years=6, design_life=2) + units = model.estimate(replaced.plan(_walker(2, 4), policy=spared)).units + self.assertEqual(units[None], 10 + 2 * 8) + # those on the ground, as the history of the deployment produces them + grounded = dataclasses.replace(spared, ground_spares=2) + deployment = schedule.plan(_walker(2, 4), policy=grounded) + estimate = model.estimate(deployment) + self.assertEqual(estimate.units[None], 10 + 2) + self.assertEqual(estimate.total, model.estimate(deployment.planned()).total) + + def test_masses_of_the_deployment(self): + """Launches are priced by the masses of the deployment, which size + them.""" + schedule = DeploymentSchedule(years=3, launch_mass_capacity=250) + deployment = schedule.plan(_walker(1, 4), masses=100) + self.assertEqual(len(deployment.launches), 2) + by_kg = LaunchCost(per_kg=0.01) + model = CostModel(SatelliteCost(first_unit=1), launch=by_kg) + self.assertAlmostEqual(model.estimate(deployment).launch, 4 * 100 * 0.01) + unsized = DeploymentSchedule(years=3).plan(_walker(1, 4)) + with self.assertRaisesRegex(ValueError, "masses"): + model.estimate(unsized) + + def test_masses_of_a_plan(self): + """The masses of a plan, and of each type, are numbers or references + to values of the design, as are the growths of each type.""" + design = _design( + layout=walker_space( + inclination=55.0, planes=1, per_plane=2, relative_spacing=0 + ), + payload=Categorical(["imager"]), + mass=Categorical([100.0]), + growth=Categorical([1.5]), + ) + capability = Capability(["a", "b"], pd.DataFrame({"satellite": []}), len) + model = CostModel( + {"imager": SatelliteCost(first_unit=1)}, launch=LaunchCost(per_kg=0.01) + ) + for masses in (100.0, "mass", {"imager": "mass"}, {"imager": lambda d: 100}): + plan = MissionPlan( + DeploymentSchedule(), + model, + kind="payload", + masses=masses, + growth={"launch": {"imager": "growth"}}, + ) + mission = plan.plan_mission(design, design.layout, capability) + self.assertEqual(mission.deployment.masses, {"imager": 100.0}) + self.assertAlmostEqual(mission.estimate().launch, 1.5 * 2 * 100 * 0.01) + + def test_types(self): + """Types of satellites are developed once each, with their own curves.""" + small = SatelliteCost(development=10, first_unit=1) + model = CostModel({"large": self.satellite, "small": small}) + sso = _design( + layout=sso_planes_space(crossing=13.5, per_plane=3, planes=1) + ).layout + mixed = model.estimate( + DeploymentSchedule().plan({"large": _walker(1, 2), "small": sso}) + ) + self.assertEqual(mixed.units, {"large": 2, "small": 3}) + self.assertEqual(mixed.development, 110) + self.assertAlmostEqual(mixed.production, self.satellite.production(2) + 3) + one = model.estimate(DeploymentSchedule().plan(_walker(1, 2), kind="small")) + self.assertEqual(one.development, 10) + with self.assertRaises(ValueError): + model.estimate(DeploymentSchedule().plan(_walker(1, 2))) + with self.assertRaises(ValueError): + model.estimate(DeploymentSchedule().plan(_walker(1, 2), kind="medium")) + + def test_growth(self): + """Growth factors multiply the cost, or its elements.""" + model = CostModel( + self.satellite, operations=OperationsCost(per_year=5), discount_rate=0.05 + ) + deployment = DeploymentSchedule(years=2, development_years=2).plan(_walker()) + base = model.estimate(deployment) + grown = model.estimate(deployment, growth=1.5) + self.assertAlmostEqual(grown.total, 1.5 * base.total) + partial = model.estimate(deployment, growth={"development": 2.0}) + self.assertAlmostEqual(partial.development, 200) + self.assertAlmostEqual(partial.operations, base.operations) + self.assertAlmostEqual( + partial.present["development"], 2 * base.present["development"] + ) + with self.assertRaises(ValueError): + model.estimate(deployment, growth={"insurance": 1.1}) + with self.assertRaises(ValueError): + CostModel(self.satellite, discount_rate=-1) + + def test_trade_study(self): + """Costs are constraints of design spaces and metrics of studies.""" + model = CostModel( + { + "narrow": SatelliteCost(development=50, first_unit=10), + "wide": SatelliteCost(development=80, first_unit=16), + }, + launch=LaunchCost(per_launch=20), + ) + schedule = DeploymentSchedule() + budget = 200 + space = DesignSpace( + imager=Categorical(["narrow", "wide"]), + layout=walker_space( + inclination=55.0, + planes=Integer(1, 3), + per_plane=Integer(1, 3), + relative_spacing=0, + ), + growth=Uncertain(lambda rng: float(rng.triangular(0.9, 1.0, 1.5))), + constraints=[ + lambda d: model.estimate(schedule.plan(d.layout, kind=d.imager)).total + - budget + ], + ) + designs = space.enumerate() + nominal = [ + model.estimate(schedule.plan(d.layout, kind=d.imager)).total + for d in designs + ] + self.assertTrue(all(cost <= budget for cost in nominal)) + self.assertLess(len(designs), 2 * 9) + + def evaluate(d): + deployment = schedule.plan(d.layout, kind=d.imager) + cost = model.estimate(deployment, growth=d.growth) + return {**cost.metrics(), "satellites": count_satellites(d.layout)} + + results = Study(space, lambda d: d, evaluate, replicates=20).run(designs) + summary = summarize( + results, statistics={"cost": "cost", "cost p70": Quantile("cost", 0.7)} + ) + # the 0.7 quantile of a growth skewed upward exceeds the mean + self.assertTrue((summary["cost p70"] > summary["cost"]).all()) + ratio = summary["cost"] / np.array(nominal) + np.testing.assert_allclose(ratio, ratio.iloc[0]) # common random numbers + + +class TestDatedCosts(unittest.TestCase): + """ + Unit tests for dated costs and their present value. + """ + + def setUp(self): + self.terms = { + "satellites": SatelliteCost( + development=90, first_unit=10, learning_rate=0.9 + ), + "launch": LaunchCost(per_launch=30), + "operations": OperationsCost(per_year=5, per_satellite_year=1), + } + self.layout = _walker(planes=3, per_plane=4) + + def _estimate(self, discount_rate=0.1, start=0.0, **schedule): + terms = {"years": 6, "design_life": 3, "launch_capacity": 3, **schedule} + model = CostModel(**self.terms, discount_rate=discount_rate, start=start) + return model.estimate(DeploymentSchedule(**terms).plan(self.layout)) + + def test_present_value(self): + """Costs are discounted from the present to their dates.""" + dated = self._estimate(development_years=3) + # development of 90, evenly over 3 years, dated at mid-year + expected = sum(30 / 1.1 ** (year + 0.5) for year in range(3)) + self.assertAlmostEqual(dated.present["development"], expected) + # launches of the first generation at year 3, the second at year 6 + self.assertAlmostEqual(dated.present["launch"], 180 / 1.1**3 + 180 / 1.1**6) + later = self._estimate(development_years=3, start=2) + self.assertAlmostEqual(later.present_value, dated.present_value / 1.1**2) + self.assertLess(dated.metrics()["cost present"], dated.total) + + def test_production(self): + """Production is paid while produced, along the learning curve.""" + dated = self._estimate(development_years=2, production_rate=8) + production = [f for f in dated.flows if f[1] == "production"] + self.assertAlmostEqual(production[0][0], 2.25) # middle of [2, 2.5) + self.assertAlmostEqual(production[0][2], self.terms["satellites"].production(4)) + + def test_blocks(self): + """Each block of production after the first develops its type again, + just before its first unit, and restarts the learning curve.""" + self.terms["satellites"] = dataclasses.replace( + self.terms["satellites"], block_size=4, redevelopment=0.5 + ) + dated = self._estimate(development_years=2, production_rate=8) + self.assertEqual(dated.units, {None: 24}) + self.assertEqual(dated.blocks, {None: 6}) + self.assertAlmostEqual(dated.development, 90 + 5 * 45) + learning = SatelliteCost(first_unit=10, learning_rate=0.9) + self.assertAlmostEqual(dated.production, 6 * learning.production(4)) + development = [ + (t, a) for t, element, a in dated.flows if element == "development" + ] + # the second block (the second plane of the first generation, produced + # from 2.5) is developed over the two years before + # (in parts within the years from the start of development) + for flow in [(0.75, 11.25), (1.5, 22.5), (2.25, 11.25)]: + self.assertIn(flow, development) + # the fourth (the first replacements, produced from 5.25) + for flow in [(3.625, 16.875), (4.5, 22.5), (5.125, 5.625)]: + self.assertIn(flow, development) + # without blocks, one + self.assertEqual( + CostModel(SatelliteCost(development=90)) + .estimate(DeploymentSchedule(years=6, design_life=3).plan(self.layout)) + .blocks, + {None: 1}, + ) + + def test_sustained(self): + """The costs of a sustained constellation are those incurred by the end + of the mission: the share of each development and production before + it, also of a block whose first unit is produced after it.""" + model = CostModel( + SatelliteCost(development=90, first_unit=10, block_size=2), + launch=LaunchCost(per_launch=30), + ) + terms = { + "years": 5, + "design_life": 2, + "development_years": 3, + "production_rate": 0.5, + } + # units produced over [3, 5], [5, 7], [7, 9], [9, 11], and [11, 13] + # (the last two after the end at 10), in blocks of two + ending = model.estimate(DeploymentSchedule(**terms).plan(_walker(1, 1))) + sustained = model.estimate( + DeploymentSchedule(**terms, sustained=True).plan(_walker(1, 1)) + ) + self.assertEqual(ending.units, {None: 3}) + self.assertEqual(ending.development, 90 + 90) + self.assertEqual(ending.production, 30) + self.assertEqual(sustained.units, {None: 4}) + self.assertEqual(sustained.blocks, {None: 2}) + # the third block is developed over [8, 11], two thirds by the end + self.assertAlmostEqual(sustained.development, 90 + 90 + 60) + # half of the fourth unit, and none of the fifth + self.assertAlmostEqual(sustained.production, 30 + 5) + # the fourth unit is launched after the end + self.assertEqual(sustained.launch, ending.launch) + self.assertEqual(sustained.launch, 3 * 30) + self.assertLess(max(time for time, *_ in sustained.flows), 10) + self.assertAlmostEqual(sustained.annual()["total"].sum(), sustained.total) + + def test_operations_from_launch(self): + """Satellites launched later are operated for less of the mission.""" + dated = self._estimate(development_years=2, launch_interval=1) + launches = [t for t, element, _ in dated.flows if element == "launch"] + # (no slot is free for replacements before the end of the mission) + self.assertEqual(launches, [2, 3, 4, 5, 6, 7]) + expected = 5 * 6 + sum(2 * (8 - t) for t in [2, 3, 4, 5, 6, 7]) + self.assertAlmostEqual(dated.operations, expected) + + def test_annual(self): + """Annual costs add to the total, and their peak is a metric.""" + dated = self._estimate(development_years=2, launch_interval=1) + annual = dated.annual() + self.assertAlmostEqual(annual["total"].sum(), dated.total) + self.assertEqual(list(annual.index), list(range(0, 8))) + self.assertAlmostEqual( + dated.metrics()["cost peak annual"], annual["total"].max() + ) + + +NEW = Triangular(0.827, 2.274) +"""The growth of new components (Maier et al., 2023, Table I).""" +EXISTING = Triangular(0.981, 1.140) +"""The growth of existing components (Maier et al., 2023, Table I).""" + + +def _normal_probability(score): + return 0.5 * (1 + math.erf(score / math.sqrt(2))) + + +class TestTriangular(unittest.TestCase): + """ + Unit tests for triangular distributions of growth. + """ + + def test_moments(self): + """The mean and standard deviation of a triangular distribution.""" + self.assertAlmostEqual(NEW.mean(), 1.367, places=3) + self.assertAlmostEqual(EXISTING.mean(), 1.0403, places=4) + rng = np.random.default_rng(1) + draws = rng.triangular(0.827, 1.0, 2.274, 200000) + self.assertAlmostEqual(NEW.std(), draws.std(), places=2) + + def test_quantiles(self): + """Quantiles run from the lowest to the highest growth, through the mode.""" + self.assertAlmostEqual(NEW.ppf(0.0), 0.827) + self.assertAlmostEqual(NEW.ppf(1.0), 2.274) + self.assertAlmostEqual(NEW.ppf((1 - 0.827) / (2.274 - 0.827)), 1.0) + draws = [NEW.ppf(q) for q in np.random.default_rng(2).random(100000)] + self.assertAlmostEqual(np.mean(draws), NEW.mean(), places=2) + with self.assertRaises(ValueError): + Triangular(1.2, 1.5) # mode below the lowest growth + with self.assertRaises(ValueError): + Triangular(1.0, 1.0) + # the mode by name, unlike the order of Uncertain.triangular + self.assertAlmostEqual(Triangular(0.9, 1.6, mode=1.2).ppf(3 / 7), 1.2) + with self.assertRaises(TypeError): + Triangular(0.9, 1.0, 1.6) # pylint: disable=too-many-function-args + + +class TestComponents(unittest.TestCase): + """ + Unit tests for the costs of the components of satellites. + """ + + def setUp(self): + self.satellite = SatelliteCost( + development=10, + first_unit=1, + components=[ + Component("bus", development=20, first_unit=4), + Component("imager", development=30, first_unit=6, growth=NEW), + ], + ) + + def test_expected_costs(self): + """Without drawn growth, components cost their expected growth.""" + expected_development = 10 + 20 + 30 * NEW.mean() + expected_first_unit = 1 + 4 + 6 * NEW.mean() + self.assertAlmostEqual(self.satellite.total_development, expected_development) + self.assertAlmostEqual(self.satellite.total_first_unit, expected_first_unit) + self.assertAlmostEqual(self.satellite.production(2), 2 * expected_first_unit) + estimate = CostModel(self.satellite).estimate( + DeploymentSchedule().plan(_walker(1, 2)) + ) + self.assertAlmostEqual(estimate.development, expected_development) + self.assertAlmostEqual(estimate.production, 2 * expected_first_unit) + # a satellite without components costs as before + self.assertEqual(SatelliteCost(development=5).total_development, 5) + + def test_redevelopment(self): + """Blocks develop their components again, grown by their factors.""" + satellite = dataclasses.replace(self.satellite, block_size=1) + estimate = CostModel(satellite).estimate( + DeploymentSchedule().plan(_walker(1, 2)) + ) + self.assertAlmostEqual(estimate.development, 2 * satellite.total_development) + self.assertAlmostEqual(estimate.production, 2 * satellite.total_first_unit) + + def test_invalid(self): + """Components need names, costs that are not negative, and growth.""" + with self.assertRaises(ValueError): + Component("") + with self.assertRaises(ValueError): + Component("bus", development=-1) + with self.assertRaises(ValueError): + Component("bus", growth=-0.5) + with self.assertRaises(TypeError): + Component("bus", growth="new") + with self.assertRaises(ValueError): + SatelliteCost(components=[Component("bus"), Component("bus")]) + with self.assertRaises(ValueError): + CostModel(self.satellite, correlation=1.5) + with self.assertRaises(TypeError): + SatelliteCost(components=["bus"]) + # the name of the common score is not a component's + with self.assertRaises(ValueError): + CostModel(SatelliteCost(components=[Component("common", growth=NEW)])) + # types that share a component share its costs and growth + other = SatelliteCost( + components=[Component("bus", development=25, first_unit=4)] + ) + with self.assertRaises(ValueError): + CostModel({"a": self.satellite, "b": other}) + + def test_score_names(self): + """Scores are of uncertain components, after the common score if they + are correlated.""" + wide = SatelliteCost( + components=[ + Component("bus", development=20, first_unit=4), + Component("wide imager", development=50, growth=NEW), + ] + ) + model = CostModel({"narrow": self.satellite, "wide": wide}, correlation=0.5) + self.assertEqual(model.score_names(), ["common", "imager", "wide imager"]) + self.assertEqual(CostModel(self.satellite).score_names(), ["imager"]) + self.assertEqual(CostModel(SatelliteCost(), correlation=0.5).score_names(), []) + + def test_draw(self): + """Growth is the quantile at the probability of the scores of the + component and the common score, mixed by the correlation.""" + model = CostModel({"narrow": self.satellite}, correlation=0.5) + drawn = model.draw({"common": 1.0, "imager": -0.5, "other": 3.0}) + imager = drawn.satellites["narrow"].components[1] + score = math.sqrt(0.5) * 1.0 + math.sqrt(0.5) * -0.5 + self.assertAlmostEqual(imager.growth, NEW.ppf(_normal_probability(score))) + self.assertFalse(imager.uncertain) + # components of fixed growth, and the model, are unchanged + self.assertEqual(drawn.satellites["narrow"].components[0].growth, 1.0) + self.assertTrue(model.satellites["narrow"].components[1].uncertain) + self.assertAlmostEqual( + drawn.satellites["narrow"].total_development, 10 + 20 + 30 * imager.growth + ) + # without correlation, the component's score alone + independent = CostModel( + SatelliteCost(components=[Component("imager", 30, growth=NEW)]) + ) + self.assertEqual(independent.score_names(), ["imager"]) + growth = independent.draw({"imager": 0.0}).satellites.components[0].growth + self.assertAlmostEqual(growth, NEW.ppf(0.5)) + with self.assertRaises(ValueError): + model.draw({"imager": 0.0}) # no common score + + def test_correlation(self): + """Drawn growths are correlated between every pair of components, and a + component that types share has the same growth in each.""" + bus = Component("bus", 1, growth=NEW) + model = CostModel( + { + "a": SatelliteCost( + components=[bus, Component("imager", 1, growth=NEW)] + ), + "b": SatelliteCost( + components=[bus, Component("sounder", 1, growth=NEW)] + ), + }, + correlation=0.5, + ) + rng = np.random.default_rng(3) + draws = [] + for _ in range(4000): + scores = {name: rng.normal() for name in model.score_names()} + drawn = model.draw(scores).satellites + draws.append( + [c.growth for c in drawn["a"].components] + + [c.growth for c in drawn["b"].components] + ) + draws = np.array(draws) + np.testing.assert_array_equal(draws[:, 0], draws[:, 2]) + r = np.corrcoef(draws.T) + self.assertAlmostEqual(r[0, 1], 0.5, delta=0.06) + self.assertAlmostEqual(r[1, 3], 0.5, delta=0.06) + independent = dataclasses.replace(model, correlation=0.0) + draws = [] + for _ in range(4000): + scores = {name: rng.normal() for name in independent.score_names()} + drawn = independent.draw(scores).satellites + draws.append( + [c.growth for c in drawn["a"].components + drawn["b"].components] + ) + r = np.corrcoef(np.array(draws).T) + self.assertAlmostEqual(r[1, 3], 0.0, delta=0.06) + + def test_shared_development(self): + """A component that types of a deployment share is developed once, and + produced with each type.""" + bus = Component("bus", development=20, first_unit=4) + model = CostModel( + { + "a": SatelliteCost( + development=5, components=[bus, Component("imager", 30, 6)] + ), + "b": SatelliteCost( + development=7, components=[bus, Component("sounder", 10, 2)] + ), + } + ) + sso = _design( + layout=sso_planes_space(crossing=13.5, per_plane=3, planes=1) + ).layout + mixed = model.estimate( + DeploymentSchedule().plan({"a": _walker(1, 2), "b": sso}) + ) + self.assertAlmostEqual(mixed.development, 5 + 30 + 7 + 10 + 20) + self.assertAlmostEqual(mixed.production, 2 * (4 + 6) + 3 * (4 + 2)) + alone = model.estimate(DeploymentSchedule().plan(_walker(1, 2), kind="b")) + self.assertAlmostEqual(alone.development, 7 + 10 + 20) + + +class TestGrowthByType(unittest.TestCase): + """ + Unit tests for growth factors of each type of satellite. + """ + + def setUp(self): + self.model = CostModel( + { + "narrow": SatelliteCost(development=50, first_unit=10), + "wide": SatelliteCost(development=80, first_unit=16), + }, + launch=LaunchCost(per_launch=20), + operations=OperationsCost(per_year=1), + ) + sso = _design( + layout=sso_planes_space(crossing=13.5, per_plane=2, planes=1) + ).layout + self.deployment = DeploymentSchedule().plan( + {"narrow": _walker(1, 2), "wide": sso} + ) + + def test_by_type(self): + """Each type of satellite grows by its own factor.""" + base = self.model.estimate(self.deployment) + grown = self.model.estimate( + self.deployment, + growth={ + "development": {"narrow": 2.0, "wide": 1.0}, + "production": {"narrow": 1.0, "wide": 1.5}, + "launch": {"narrow": 1.0, "wide": 3.0}, + "operations": 2.0, + }, + ) + self.assertAlmostEqual(grown.development, 2 * 50 + 80) + self.assertAlmostEqual(grown.production, 20 + 1.5 * 32) + self.assertAlmostEqual(grown.launch, 20 + 3 * 20) + self.assertAlmostEqual(grown.operations, 2 * base.operations) + + def test_invalid(self): + """Growth by type needs every kind of the deployment, and is not of + operations.""" + with self.assertRaises(ValueError): + self.model.estimate(self.deployment, growth={"development": {"narrow": 2}}) + with self.assertRaises(ValueError): + self.model.estimate( + self.deployment, growth={"operations": {"narrow": 1, "wide": 1}} + ) + single = CostModel(SatelliteCost(development=10)) + with self.assertRaises(ValueError): + single.estimate( + DeploymentSchedule().plan(_walker(1, 2)), + growth={"development": {"satellites": 2}}, + ) + + def test_shared_types(self): + """Common random numbers correlate the costs of designs of the same type + (as in Maier et al., 2023): the order of such designs is settled, and + that of designs of different types is not.""" + space = DesignSpace( + imager=Categorical(["narrow", "wide"]), + layout=walker_space( + inclination=55.0, planes=1, per_plane=Integer(2, 3), relative_spacing=0 + ), + narrow=Uncertain.normal(1.0, 0.3), + wide=Uncertain.normal(1.0, 0.3), + ) + schedule = DeploymentSchedule() + + def evaluate(d): + deployment = schedule.plan(d.layout, kind=d.imager) + growth = {"narrow": d.narrow, "wide": d.wide} + return self.model.estimate( + deployment, growth={"development": growth, "production": growth} + ).metrics() + + designs = space.enumerate() + + def compare(common): + study = Study( + space, + lambda d: d, + evaluate, + replicates=200, + common_random_numbers=common, + ) + compared = exceedance(study.run(designs), "cost", designs) + return compared.set_index(["design", "other"])["exceedance"] + + shared, independent = compare(True), compare(False) + narrow2, narrow3 = (d.key for d in designs if d.imager == "narrow") + wide2 = next(d.key for d in designs if d.imager == "wide") + # three narrow satellites cost more than two in every replicate + self.assertEqual(shared[(narrow3, narrow2)], 1.0) + self.assertLess(independent[(narrow3, narrow2)], 0.99) + # designs of different types are not ordered by their shared draws + self.assertLess(shared[(wide2, narrow3)], 1.0) + self.assertGreater(shared[(wide2, narrow3)], 0.0) + + +class TestRiskSpace(unittest.TestCase): + """ + Unit tests for the scores of the cost risk of designs. + """ + + def setUp(self): + self.model = CostModel( + { + 30: SatelliteCost( + components=[ + Component("bus", 20, 4, growth=EXISTING), + Component("imager 30", 15, 3, growth=NEW), + ], + ), + 60: SatelliteCost( + components=[ + Component("bus", 20, 4, growth=EXISTING), + Component("imager 60", 30, 6, growth=NEW), + ], + ), + }, + correlation=0.5, + ) + + def test_scores(self): + """A standard normal score of each name, the same in every design of a + replicate.""" + group = risk_space(self.model) + self.assertEqual( + list(group.children), ["common", "bus", "imager 30", "imager 60"] + ) + space = DesignSpace( + imager=Categorical([30, 60]), + layout=walker_space( + inclination=55.0, planes=1, per_plane=2, relative_spacing=0 + ), + cost_risk=group, + ) + self.assertIn("cost_risk.imager 30", space.uncertain_paths()) + narrow, wide = space.enumerate() + a, b = narrow.realize(4), wide.realize(4) + self.assertEqual(a.cost_risk["bus"], b.cost_risk["bus"]) + # every design of a replicate draws the same growths, and the bus grows + # alike in both types + drawn = self.model.draw(a.cost_risk) + self.assertEqual(drawn, self.model.draw(b.cost_risk)) + self.assertEqual( + drawn.satellites[30].components[0], drawn.satellites[60].components[0] + ) + scores = np.array([narrow.realize(r).cost_risk["bus"] for r in range(500)]) + self.assertAlmostEqual(scores.mean(), 0.0, delta=0.15) + self.assertAlmostEqual(scores.std(), 1.0, delta=0.15) + + def test_invalid(self): + """Names are not reserved, nor have characters of paths.""" + reserved = CostModel(SatelliteCost(components=[Component("count", growth=NEW)])) + with self.assertRaisesRegex(ValueError, "count"): + risk_space(reserved) + dotted = CostModel( + SatelliteCost(components=[Component("imager.v2", growth=NEW)]) + ) + with self.assertRaises(ValueError): + risk_space(dotted) + + +class TestSpread(unittest.TestCase): + """ + Unit tests for amounts spread over durations. + """ + + def test_years(self): + """Amounts are spread in parts within years, for the annual costs.""" + from tatc.tradespace.cost import ( + _spread, + ) # pylint: disable=import-outside-toplevel + + flows = _spread(10.0, 3.5, 6.0) + self.assertEqual(flows, [(3.75, 2.0), (4.5, 4.0), (5.5, 4.0)]) + self.assertEqual(_spread(10.0, 0.0, 2.0), [(0.5, 5.0), (1.5, 5.0)]) + # the part before the end of a sustained mission + self.assertEqual(_spread(10.0, 3.5, 6.0, until=5.0), [(3.75, 2.0), (4.5, 4.0)]) diff --git a/tests/tradespace/test_criteria.py b/tests/tradespace/test_criteria.py new file mode 100644 index 0000000..f439e93 --- /dev/null +++ b/tests/tradespace/test_criteria.py @@ -0,0 +1,198 @@ +""" +Unit tests for criteria: requirements on statistics, and the objectives, +tolerances, and rules across groups by which designs are judged. + +@author Paul T. Grogan +""" + +import dataclasses +import unittest + +import numpy as np +import pandas as pd + +from tatc.tradespace import ( + Across, + Criteria, + Mean, + Quantile, + Requirement, + pareto_front, +) +from tatc.tradespace.criteria import ( + _as_criteria, + _combiners, + _costs, + _resolved, + _signs, + _statistic, + _tolerances, + _violation, +) + + +class TestRequirement(unittest.TestCase): + """ + Unit tests for requirements. + """ + + def test_violation(self): + """Violations are the gaps to the required values, relative to them.""" + statistic = np.array([5.0, 10.0, 12.0, np.nan]) + np.testing.assert_allclose( + Requirement("x", ">=", 10).violation(statistic), [0.5, 0, 0, np.nan] + ) + np.testing.assert_allclose( + Requirement("x", "<=", 10).violation(statistic), [0, 0, 0.2, np.nan] + ) + strict = Requirement("x", ">", 10).violation(statistic) + self.assertGreater(strict[1], 0) + self.assertEqual(strict[2], 0) + + def test_scale(self): + """Violations are relative to a scale: given, or 1 for a value of 0.""" + statistic = np.array([5.0, 12.0]) + np.testing.assert_allclose( + Requirement("x", ">=", 10, scale=1).violation(statistic), [5, 0] + ) + np.testing.assert_allclose( + Requirement("x", "<=", 0).violation(statistic), [5, 12] + ) + np.testing.assert_allclose( + Requirement("x", "<=", -10).violation(statistic), [1.5, 2.2] + ) + + def test_statements(self): + """Requirements tell which values meet them, and state themselves.""" + requirement = Requirement("cost", "<=", 1.5) + np.testing.assert_array_equal( + requirement.met([1.0, 2.0, np.nan]), [True, False, False] + ) + self.assertEqual(str(requirement), "cost <= 1.5") + + def test_invalid(self): + """Operators and scales are checked.""" + with self.assertRaises(ValueError): + Requirement("x", "!=", 1) + with self.assertRaises(ValueError): + Requirement("x", ">=", 1, scale=0) + + +class TestCriteria(unittest.TestCase): + """ + Unit tests for criteria. + """ + + def test_names(self): + """Names are those of objectives, requirements, and other statistics.""" + criteria = Criteria( + {"a": "min", "b": "max"}, + statistics={"c": Mean("x"), "b": "y"}, + requirements=[Requirement("c", ">=", 1), Requirement("a", "<=", 2)], + by="sensor", + ) + self.assertEqual(criteria.names, ["a", "b", "c"]) + self.assertEqual(criteria.metrics, ["a", "x", "y"]) + self.assertEqual(_statistic(criteria, "a"), Mean("a")) + self.assertEqual(_statistic(criteria, "b"), Mean("y")) + self.assertEqual( + _resolved(criteria), {"a": Mean("a"), "b": Mean("y"), "c": Mean("x")} + ) + self.assertEqual(criteria.by, ("sensor",)) + + def test_conventional_names(self): + """Statistics given without names are named by convention.""" + criteria = Criteria( + {"value p25": "max"}, statistics=[Quantile("value", 0.25), "cost"] + ) + self.assertEqual(criteria.names, ["value p25", "cost"]) + + def test_invalid(self): + """Objectives, statistics, requirements, and tolerances are checked.""" + with self.assertRaises(ValueError): + Criteria({}) + with self.assertRaises(ValueError): + Criteria({"a": "lowest"}) + with self.assertRaises(ValueError): + Criteria({"a": "min"}, tolerances={"b": 1}) + with self.assertRaises(ValueError): + Criteria({"a": "min"}, tolerances={"a": "5"}) + with self.assertRaises(ValueError): + Criteria({"a": "min"}, tolerances={"a": -1}) + with self.assertRaises(TypeError): + Criteria({"a": "min"}, statistics={"b": 1}) + with self.assertRaises(TypeError): + Criteria({"a": "min"}, requirements=[("a", "<=", 1)]) + with self.assertRaises(TypeError): + pareto_front(pd.DataFrame({"a": [1]}), ["a"]) + + def test_shorthand(self): + """A mapping of objectives is the criteria of their means.""" + frame = pd.DataFrame({"cost": [1, 2, 3], "value": [1, 3, 2]}) + objectives = {"cost": "min", "value": "max"} + pd.testing.assert_series_equal( + pareto_front(frame, objectives), pareto_front(frame, Criteria(objectives)) + ) + criteria = Criteria(objectives) + self.assertIs(_as_criteria(criteria), criteria) + self.assertEqual(_as_criteria(objectives), criteria) + with self.assertRaises(TypeError): + _as_criteria(["cost"]) + + def test_costs_and_violation(self): + """Objectives are costs (maximized ones negated), and the violations + of requirements add.""" + criteria = Criteria( + {"cost": "min", "value": "max"}, + requirements=[Requirement("cost", "<=", 2), Requirement("value", ">=", 4)], + ) + np.testing.assert_array_equal(_signs(criteria), [1.0, -1.0]) + values = {"cost": np.array([1.0, 3.0]), "value": np.array([5.0, np.nan])} + np.testing.assert_array_equal( + _costs(criteria, values), [[1.0, -5.0], [3.0, np.nan]] + ) + np.testing.assert_allclose(_violation(criteria, values, 2), [0.0, np.nan]) + np.testing.assert_allclose( + _violation(criteria, {"cost": [3.0], "value": [2.0]}, 1), [0.5 + 0.5] + ) + self.assertEqual(_costs(criteria, {"cost": [], "value": []}).shape, (0, 2)) + np.testing.assert_array_equal(_violation(Criteria({"a": "min"}), {}, 3), 0.0) + + def test_tolerance_array(self): + """Tolerances are values in the units of objectives, or shares of + them, in the order of the objectives (zero if not given).""" + criteria = Criteria( + {"a": "min", "b": "max", "c": "min"}, tolerances={"c": "5%", "a": 2} + ) + np.testing.assert_array_equal( + _tolerances(criteria), [[2.0, 0.0, 0.0], [0.0, 0.0, 0.05]] + ) + # derived from the tolerances, which compare criteria + changed = dataclasses.replace(criteria, tolerances={"b": 1}) + np.testing.assert_array_equal( + _tolerances(changed), [[0.0, 1.0, 0.0], [0.0, 0.0, 0.0]] + ) + self.assertEqual(criteria, dataclasses.replace(criteria)) + self.assertNotEqual(criteria, changed) + + def test_combiners(self): + """Statistics across groups are combined by their worst, or their + mean.""" + self.assertEqual(_combiners(Criteria({"a": "min"})), {}) + criteria = Criteria( + {"a": "min", "b": "max"}, + statistics={"c": "x", "d": "y"}, + requirements=[Requirement("c", ">=", 1)], + across=Across(rules={"b": "mean"}), + ) + self.assertEqual( + _combiners(criteria), {"a": "max", "b": "mean", "c": "min", "d": "mean"} + ) + with self.assertRaisesRegex(ValueError, "no worst"): + Criteria( + {"a": "min"}, statistics={"d": "y"}, across=Across(rules={"d": "worst"}) + ) + with self.assertRaisesRegex(ValueError, "disagree"): + Criteria( + {"a": "min"}, requirements=[Requirement("a", ">=", 1)], across=Across() + ) diff --git a/tests/tradespace/test_deployment.py b/tests/tradespace/test_deployment.py new file mode 100644 index 0000000..eee17ef --- /dev/null +++ b/tests/tradespace/test_deployment.py @@ -0,0 +1,373 @@ +""" +Unit tests for the deployment of constellations and capability over its +phases. + +@author Paul T. Grogan +""" + +import dataclasses +import math +import unittest + +import numpy as np +import pandas as pd + +from tatc.tradespace import ( + CostModel, + DeploymentSchedule, + DesignSpace, + Exponential, + FailureModel, + Real, + Requirement, + RestorationPolicy, + SatelliteCost, + Stage, + sso_planes_space, + walker_space, +) +from tatc.tradespace.mission import Phase, evaluate_phases, summarize_phases + + +def _walker(planes=3, per_plane=4): + (design,) = DesignSpace( + layout=walker_space( + inclination=55.0, planes=planes, per_plane=per_plane, relative_spacing=0 + ) + ).enumerate() + return design.layout + + +def _names(planes, per_plane): + """The names of the satellites of a Walker layout, in build order.""" + return [f"satellite {k + 1}" for k in range(planes * per_plane)] + + +class TestPlan(unittest.TestCase): + """ + Unit tests for planned deployments. + """ + + def test_mass_capacity_by_plane(self): + """A launch capacity in mass may differ by plane (such as by inclination), + for the launches of a deployment and those of its restorations.""" + + def capacity(index, values): + del values # the planes of a Walker constellation have none + return 100.0 if index == 0 else 200.0 + + schedule = DeploymentSchedule(years=5, launch_mass_capacity=capacity) + deployment = schedule.plan(_walker(2, 4), masses=50.0) + launches = { + plane: sum(l.plane == plane for l in deployment.launches) + for plane in (0, 1) + } + self.assertEqual(launches, {0: 2, 1: 1}) + self.assertEqual(deployment.plane_values, [None, None]) + with self.assertRaises(ValueError): + schedule.launches_of(4, 50.0) + self.assertEqual(schedule.launches_of(4, 50.0, (1, None)), 1) + # restorations that wait to share a launch fill it to the plane's capacity + batching = schedule.plan( + _walker(2, 4), masses=50.0, policy=RestorationPolicy(batch_years=1.0) + ) + history = batching.simulate(FailureModel(life=Exponential(2.0)), seed=0) + restorations = [l for l in history.launches if l.purpose == "restoration"] + self.assertTrue(any(l.plane == 1 and l.satellites > 2 for l in restorations)) + self.assertTrue( + all(l.satellites <= (2 if l.plane == 0 else 4) for l in restorations) + ) + + def test_production_rate(self): + """A production line deploys planes as their satellites are built.""" + schedule = DeploymentSchedule(years=2, development_years=2, production_rate=8) + deployment = schedule.plan(_walker(3, 4)) + # 4 satellites a plane at 8 a year: ready every half year + self.assertEqual([l.time for l in deployment.launches], [2.5, 3.0, 3.5]) + self.assertEqual(deployment.begin, 2.5) + self.assertEqual(deployment.deployed, 3.5) + larger = schedule.plan(_walker(3, 6)) + self.assertGreater(larger.deployed, deployment.deployed) + + def test_launch_cadence(self): + """Launches are at least an interval apart, a plane taking several, + planned replacements too.""" + schedule = DeploymentSchedule( + years=8, + design_life=3, + development_years=2, + launch_interval=1, + launch_capacity=3, + ) + deployment = schedule.plan(_walker(3, 4)) + first = [l for l in deployment.launches if l.generation == 0] + self.assertEqual([l.time for l in first], [2, 3, 4, 5, 6, 7]) + self.assertEqual( + [(l.plane, l.first, l.satellites) for l in first[:2]], + [(0, 0, 2), (0, 2, 2)], + ) + # replacements needed 3 years later, from year 5, wait for the slots + # after the first generation: two before the end of the mission at 10 + replacements = [ + (l.time, l.plane, l.first) for l in deployment.launches if l.generation > 0 + ] + self.assertEqual(replacements, [(8, 0, 0), (9, 0, 2)]) + self.assertEqual(deployment.end, 10) + self.assertEqual(deployment.units, {None: 12 + 4}) + + def test_deployment_outlasting_the_mission(self): + """A deployment whose launches outlast the mission is not deployed in + it: the time it is deployed is infinite (as the time until a mission + meets a requirement that it never meets).""" + schedule = DeploymentSchedule(years=1.5, launch_interval=1) + deployment = schedule.plan(_walker(3, 1)) + self.assertEqual([l.time for l in deployment.launches], [0, 1, 2]) + self.assertEqual([l.time for l in deployment.planned().launches], [0, 1]) + self.assertEqual(deployment.planned().deployed, math.inf) + self.assertEqual(deployment.deployed, math.inf) + longer = dataclasses.replace(schedule, years=2.5).plan(_walker(3, 1)) + self.assertEqual(longer.deployed, 2) + + def test_replacements_keep_the_interval(self): + """Planned replacements of several types keep the launch interval, from + the launches of the deployment and from each other, and are replaced a + design life after their launch.""" + schedule = DeploymentSchedule( + years=8, launch_interval=0.5, design_life={"a": 3.0, "b": 2.5} + ) + deployment = schedule.plan({"a": _walker(1, 2), "b": _walker(1, 2)}) + launches = [(l.time, l.kind, l.purpose) for l in deployment.launches] + self.assertEqual( + launches, + [ + (0.0, "a", "deployment"), + (0.5, "b", "deployment"), + (3.0, "a", "replacement"), + (3.5, "b", "replacement"), # needed at 3.0, with a's + (6.0, "a", "replacement"), + (6.5, "b", "replacement"), # needed at 3.5 + 2.5, with a's + ], + ) + times = [time for time, _, _ in launches] + self.assertGreaterEqual(min(np.diff(times)), 0.5) + # produced just before they are needed + produced = [ + (b.kind, b.end) for b in deployment.production if b.purpose == "replacement" + ] + self.assertEqual( + sorted(produced), [("a", 3.0), ("a", 6.0), ("b", 3.0), ("b", 6.0)] + ) + + def test_spares_are_not_replaced(self): + """Planned replacements replace the satellites of the layout, not the + spares in orbit, which do not age: a spare is launched once.""" + schedule = DeploymentSchedule(years=6, design_life=2) + spared = RestorationPolicy(orbit_spares=1) + deployment = schedule.plan(_walker(1, 2), policy=spared) + self.assertEqual( + [(l.time, l.satellites, l.purpose) for l in deployment.launches], + [(0, 3, "deployment"), (2, 2, "replacement"), (4, 2, "replacement")], + ) + self.assertEqual(deployment.units, {None: 3 + 2 + 2}) + self.assertEqual(schedule.plan(_walker(1, 2)).units, {None: 6}) + # the spare waits in orbit for the whole mission + self.assertEqual(deployment.simulate().parked, [(0, 6, 1)]) + # a launch of the spare alone is not replaced + single = dataclasses.replace(schedule, launch_capacity=1) + launches = single.plan(_walker(1, 2), policy=spared).launches + self.assertEqual( + sorted((l.purpose, l.first) for l in launches), + [("deployment", 0), ("deployment", 1), ("deployment", 2)] + + [("replacement", 0)] * 2 + + [("replacement", 1)] * 2, + ) + # spares of each type (of every type of the deployment) + by_type = RestorationPolicy(orbit_spares={"a": 1, "b": 0}) + mixed = schedule.plan({"a": _walker(1, 2), "b": _walker(1, 2)}, policy=by_type) + self.assertEqual([p.orbit_spares for p in mixed.planes], [1, 0]) + for lacking in (by_type, RestorationPolicy(ground_spares={"a": 1})): + with self.assertRaises(ValueError): + schedule.plan(_walker(1, 2), policy=lacking) + + def test_policy(self): + """A deployment has the policy it is planned with, whose spares in + orbit its planes include, whose spares on the ground the history + without failures produces (after the planes that are not staged, and + before a stage, which the time it is deployed and its costs take), + and with which it restores failures.""" + self.assertEqual( + DeploymentSchedule().plan(_walker()).policy, RestorationPolicy() + ) + policy = RestorationPolicy(ground_spares=2) + schedule = DeploymentSchedule(years=5, production_rate=1.0) + # the second plane is staged, and deployed at the first launch + deployment = schedule.plan(_walker(2, 2), policy=policy, stages=[Stage(1, 0)]) + self.assertIs(deployment.policy, policy) + planned = deployment.planned() + spares = [b for b in planned.production if b.purpose == "spare"] + self.assertEqual([(b.begin, b.end) for b in spares], [(2, 4)]) + self.assertEqual(planned.deployed, 6) + self.assertEqual(deployment.deployed, 6) + self.assertEqual(deployment.units, {None: 2}) # of the plan alone + model = CostModel(SatelliteCost(first_unit=10)) + self.assertEqual(model.estimate(deployment).production, 60) + self.assertEqual(model.estimate(deployment).units, {None: 6}) + # its simulations restore failures with its spares in orbit + spared = DeploymentSchedule(years=5).plan( + _walker(1, 2), policy=RestorationPolicy(orbit_spares=1) + ) + history = spared.simulate(FailureModel(life=Exponential(0.5)), seed=1) + self.assertEqual(history.restorations[0].source, "orbit") + + def test_types_and_order(self): + """Types are developed over their own durations, planes in an order.""" + schedule = DeploymentSchedule(development_years={"new": 5, "heritage": 2}) + sso = DesignSpace( + layout=sso_planes_space(crossing=Real(9, 12, step=3), per_plane=1, planes=2) + ) + layout = sso.enumerate()[0].layout + deployment = schedule.plan({"new": _walker(1, 2), "heritage": layout}) + self.assertEqual( + sorted((l.time, l.kind) for l in deployment.launches), + [(2.0, "heritage"), (2.0, "heritage"), (5.0, "new")], + ) + ordered = DeploymentSchedule( + production_rate=1, order=lambda index, plane: -plane.crossing + ).plan(layout) + crossings = [plane.crossing for plane in layout.planes] + latest = int(np.argmax(crossings)) + self.assertEqual(ordered.launches[0].plane, latest) + with self.assertRaises(ValueError): + DeploymentSchedule(development_years={"new": 5}).plan( + _walker(), kind="heritage" + ) + + def test_design_life_by_type(self): + """Each type of satellite has its own design life (or none).""" + schedule = DeploymentSchedule( + years=6, design_life={"short": 2, "long": None}, development_years=1 + ) + deployment = schedule.plan({"short": _walker(1, 2), "long": _walker(1, 2)}) + replacements = [ + (l.kind, l.time) for l in deployment.launches if l.purpose == "replacement" + ] + self.assertEqual(replacements, [("short", 3), ("short", 5)]) + self.assertEqual(deployment.units, {"short": 6, "long": 2}) + with self.assertRaises(ValueError): + DeploymentSchedule(design_life={"short": 2}).plan(_walker(), kind="long") + + def test_sustained(self): + """A sustained constellation's replacements are produced after the end + of the mission (from within its development years after the end), but + not launched in it.""" + terms = { + "years": 5, + "design_life": 2, + "development_years": 3, + "production_rate": 0.5, + } + ending = DeploymentSchedule(**terms).plan(_walker(1, 1)) + sustained = DeploymentSchedule(**terms, sustained=True).plan(_walker(1, 1)) + self.assertEqual(sustained.end, 10) + self.assertEqual( + [(b.begin, b.end) for b in ending.production], [(3, 5), (5, 7), (7, 9)] + ) + self.assertEqual( + [(b.begin, b.end) for b in sustained.production], + [(3, 5), (5, 7), (7, 9), (9, 11), (11, 13)], + ) + self.assertEqual([l.time for l in sustained.launches], [5, 7, 9]) + self.assertEqual(sustained.launches, ending.launches) + # those in production at the end, not those begun after it + self.assertEqual(sustained.units, {None: 4}) + self.assertEqual(ending.units, {None: 3}) + + def test_mass_capacity(self): + """A launch carries as many satellites as its mass capacity allows.""" + schedule = DeploymentSchedule(launch_mass_capacity=120) + deployment = schedule.plan(_walker(2, 4), masses=50) + self.assertEqual(len(deployment.launches), 4) + with self.assertRaises(ValueError): + schedule.plan(_walker(2, 4)) + with self.assertRaises(ValueError): + schedule.plan(_walker(2, 4), masses=200) + + def test_validation(self): + """Schedules are validated.""" + for invalid in ( + {"years": 0}, + {"design_life": 0}, + {"design_life": {"a": 2, "b": 0}}, + {"production_rate": 0}, + {"launch_interval": -1}, + {"launch_capacity": 0}, + {"development_years": -1}, + ): + with self.assertRaises(ValueError): + DeploymentSchedule(**invalid) + + +class TestPhases(unittest.TestCase): + """ + Unit tests for phases of a mission. + """ + + def setUp(self): + self.schedule = DeploymentSchedule( + years=4, design_life=2, development_years=1, production_rate=2 + ) + self.deployment = self.schedule.plan(_walker(2, 2)) + self.names = _names(2, 2) + + def test_deployment(self): + """Phases begin as planes are launched.""" + phases = self.deployment.phases(self.names) + self.assertEqual([(p.start, p.end) for p in phases], [(2, 3), (3, 6)]) + self.assertEqual(phases[0].satellites, tuple(self.names[:2])) + self.assertEqual(phases[1].satellites, tuple(self.names)) + with self.assertRaises(ValueError): + self.deployment.phases(self.names[:3]) + + def test_evaluate_and_summarize(self): + """Phases are evaluated with their satellites' observations, and summarized.""" + observations = pd.DataFrame({"satellite": self.names * 3, "target": range(12)}) + calls = [] + + def metric(obs): + calls.append(len(obs)) + return {"targets": 25.0 * obs["satellite"].nunique()} + + # the first satellite fails at 2.5 and is replaced at 4 + names = tuple(self.names) + phases = [ + Phase(2, 2.5, names[:2]), + Phase(2.5, 3, names[1:2]), + Phase(3, 4, names[1:]), + Phase(4, 6, names), + ] + capability = evaluate_phases(phases, observations, metric) + self.assertEqual(list(capability.targets), [50, 25, 75, 100]) + self.assertEqual(list(capability.satellites), [2, 1, 3, 4]) + summary = summarize_phases( + capability, requirements=[Requirement("targets", ">=", 200)] + ) + expected = (50 * 0.5 + 25 * 0.5 + 75 * 1 + 100 * 2) / 4 + self.assertAlmostEqual(summary["targets mission"], expected) + self.assertEqual(summary["targets time"], math.inf) # never met + first = summarize_phases( + capability, requirements=[Requirement("targets", ">=", 75)] + ) + self.assertEqual(first["targets time"], 3) + # two requirements of a metric would name the same time + with self.assertRaisesRegex(ValueError, "same metric"): + summarize_phases( + capability, + requirements=[ + Requirement("targets", ">=", 75), + Requirement("targets", ">=", 200), + ], + ) + # phases of the same satellites are evaluated once + repeated = evaluate_phases(phases + phases, observations, metric) + self.assertEqual(len(repeated), 8) + self.assertEqual(len(calls), 4 + 4) diff --git a/tests/tradespace/test_failures.py b/tests/tradespace/test_failures.py new file mode 100644 index 0000000..a04d3e2 --- /dev/null +++ b/tests/tradespace/test_failures.py @@ -0,0 +1,1167 @@ +""" +Unit tests for failures of satellites and launches, their restoration, and +simulations of missions. + +@author Paul T. Grogan +""" + +import math +import unittest +import warnings +from dataclasses import dataclass +from unittest import mock + +import numpy as np +import pandas as pd + +from tatc.tradespace import ( + Bathtub, + CostModel, + DeploymentSchedule, + DesignSpace, + Exponential, + FailureModel, + Integer, + LaunchCost, + Mean, + OperationsCost, + Piecewise, + Probability, + Quantile, + RestorationPolicy, + SatelliteCost, + Stage, + StandardDeviation, + Study, + Uncertain, + Weibull, + build_constellation, + pareto_front, + policy_space, + summarize, + walker_space, +) +from tatc.tradespace import expectations as expectations_module +from tatc.tradespace.expectations import ( + MAX_SETS, + ExactExpectationsError, + _exact_sets, + exact_expectations, +) +from tatc.tradespace.failures import Lifetime +from tatc.tradespace.histories import ( + allocate_histories, + evaluate_histories, + summarize_histories, +) +from tatc.tradespace.mission import ( + Capability, + PhaseCache, + evaluate_phases, + summarize_phases, +) +from tatc.tradespace.simulation import _Simulation +from tatc.tradespace import configure + + +def _walker(planes=1, per_plane=2): + (design,) = DesignSpace( + layout=walker_space( + inclination=55.0, planes=planes, per_plane=per_plane, relative_spacing=0 + ) + ).enumerate() + return design.layout + + +def _names(count): + return [f"satellite {k + 1}" for k in range(count)] + + +DEGRADE = RestorationPolicy(restore=False) + + +@dataclass(frozen=True) +class _Fixed(Lifetime): + """A life of a fixed duration (the first satellite only, if `first`).""" + + years: float + + def cumulative_hazard(self, age): + return np.where(np.asarray(age) >= self.years, np.inf, 0.0) + + def hazard(self, age): + return np.zeros_like(np.asarray(age, dtype=float)) + + def from_uniform(self, uniform): + return self.years + + +def _empirical(life, ages, n=40_000, seed=1): + rng = np.random.default_rng(seed) + lives = np.array([life.sample(rng) for _ in range(n)]) + return np.array([(lives > age).mean() for age in ages]) + + +class TestLifetimes(unittest.TestCase): + """ + Unit tests for distributions of life. + """ + + ages = np.array([0.5, 2.0, 5.0, 9.0]) + + def test_exponential(self): + """A constant failure rate.""" + life = Exponential(0.2) + np.testing.assert_allclose(life.survival(self.ages), np.exp(-0.2 * self.ages)) + np.testing.assert_allclose(life.hazard(self.ages), 0.2) + np.testing.assert_allclose( + _empirical(life, self.ages), life.survival(self.ages), atol=0.01 + ) + self.assertEqual(Exponential(0).sample(np.random.default_rng(0)), math.inf) + with self.assertRaises(ValueError): + Exponential(-1) + + def test_weibull(self): + """Decreasing and increasing failure rates.""" + infant, wear = Weibull(0.5, 20), Weibull(4, 6) + for life in (infant, wear): + np.testing.assert_allclose( + _empirical(life, self.ages), life.survival(self.ages), atol=0.01 + ) + self.assertGreater(infant.hazard(0.5), infant.hazard(5)) + self.assertLess(wear.hazard(0.5), wear.hazard(5)) + with self.assertRaises(ValueError): + Weibull(0, 1) + + def test_bathtub(self): + """Competing causes: hazards add, the earliest fails.""" + parts = (Weibull(0.5, 30), Exponential(0.05), Weibull(5, 7)) + life = Bathtub(*parts) + np.testing.assert_allclose( + life.hazard(self.ages), sum(p.hazard(self.ages) for p in parts) + ) + np.testing.assert_allclose( + life.survival(self.ages), + np.prod([p.survival(self.ages) for p in parts], axis=0), + ) + np.testing.assert_allclose( + _empirical(life, self.ages), life.survival(self.ages), atol=0.01 + ) + # high early, low in the middle, high late + hazard = life.hazard(np.array([0.05, 3.0, 9.0])) + self.assertTrue(hazard[0] > hazard[1] < hazard[2]) + self.assertEqual(Bathtub().sample(np.random.default_rng(0)), math.inf) + + def test_piecewise(self): + """Failure rates by intervals of age.""" + life = Piecewise([0, 1, 4], [0.3, 0.05, 0.2]) + np.testing.assert_allclose(life.hazard(np.array([0.5, 2, 6])), [0.3, 0.05, 0.2]) + expected = np.exp( + -np.array([0.15, 0.3 + 0.05, 0.3 + 0.15 + 0.2, 0.3 + 0.15 + 1.0]) + ) + np.testing.assert_allclose(life.survival(self.ages), expected) + np.testing.assert_allclose( + _empirical(life, self.ages), life.survival(self.ages), atol=0.01 + ) + never = Piecewise([0, 1], [0.5, 0.0]) + self.assertGreater( + np.mean( + [never.sample(np.random.default_rng(s)) == math.inf for s in range(400)] + ), + 0.5, + ) + for breaks, rates in ( + ([1, 2], [0.1, 0.1]), + ([0, 2], [0.1]), + ([0, 2, 1], [1, 1, 1]), + ): + with self.assertRaises(ValueError): + Piecewise(breaks, rates) + + def test_models(self): + """Lives of each type of satellite, and failures of launches.""" + model = FailureModel(life={"a": Exponential(0.1), "b": None}, launch=0.05) + self.assertEqual(model.life_of("a"), Exponential(0.1)) + self.assertIsNone(model.life_of("b")) + with self.assertRaises(ValueError): + model.life_of("c") + with self.assertRaises(ValueError): + FailureModel(launch=1.5) + + +class TestSimulation(unittest.TestCase): + """ + Unit tests for simulated missions. + """ + + def setUp(self): + # one plane of 2 satellites, launched at year 1, for a mission of 4 years + self.schedule = DeploymentSchedule( + years=4, development_years=1, production_rate=4, launch_interval=0.5 + ) + self.layout = _walker(1, 2) + self.names = _names(2) + # every satellite fails 1.5 years after it begins to operate + self.failures = FailureModel(life=_Fixed(1.5)) + + def _simulate(self, policy, failures=None, seed=0): + deployment = self.schedule.plan(self.layout, policy=policy) + return deployment.simulate(failures or self.failures, seed) + + def test_without_failures(self): + """Without failures, the history is the deployment's.""" + deployment = self.schedule.plan(self.layout) + history = deployment.simulate() + self.assertEqual(history.failures, []) + self.assertEqual( + history.operating, {(0, 0): [(1.5, 5.5)], (0, 1): [(1.5, 5.5)]} + ) + model = CostModel( + SatelliteCost(development=10, first_unit=5), + launch=LaunchCost(per_launch=3), + operations=OperationsCost(per_satellite_year=1), + ) + self.assertAlmostEqual( + model.estimate(deployment).total, model.estimate(history).total + ) + # a failure model without a seed draws no failures + self.assertEqual(deployment.simulate(self.failures, seed=None).failures, []) + self.assertEqual(history.metrics()["availability"], 1.0) + + def test_degrade(self): + """Without restoration, failed satellites stay failed.""" + history = self._simulate(RestorationPolicy(restore=False)) + # both fail at 3.0 (1.5 years after their launch at 1.5) + self.assertEqual(history.operating[0, 0], [(1.5, 3.0)]) + self.assertEqual(len(history.failures), 2) + self.assertEqual(history.restorations, []) + self.assertAlmostEqual(history.metrics()["availability"], 1.5 / 4) + phases = history.phases(self.names) + self.assertEqual( + [(p.start, p.end, len(p.satellites)) for p in phases], + [(1.5, 3.0, 2), (3.0, 5.5, 0)], + ) + + def test_restore_by_production(self): + """A failed satellite is produced, then launched at the next slot.""" + policy = RestorationPolicy(detection_years=0.1, procurement_years=0.2) + history = self._simulate(policy) + # failed at 3.0, ordered at 3.1, produced from 3.3 to 3.55 (the + # second after it, to 3.8), each launched when ready (slots 0.5 apart) + restored = sorted( + (p, failed, round(when, 6), source) + for p, failed, when, source in [ + (pos, f, r, s) for _, pos, f, r, s in history.restorations[:2] + ] + ) + self.assertEqual([r[2] for r in restored], [3.55, 4.05]) + self.assertTrue(all(r[3] == "production" for r in restored)) + purposes = [b.purpose for b in history.production] + self.assertIn("restoration", purposes) + self.assertEqual( + sorted(l.purpose for l in history.launches).count("restoration"), + sum(1 for l in history.launches if l.purpose == "restoration"), + ) + + def test_restore_from_orbit(self): + """A spare in orbit takes a failed satellite's place after drifting.""" + policy = RestorationPolicy(detection_years=0.1, drift_years=0.2, orbit_spares=1) + history = self._simulate(policy) + first = sorted(history.restorations, key=lambda r: r[3])[0] + self.assertEqual(first[4], "orbit") + self.assertAlmostEqual(first[3] - first[2], 0.3) + # the other satellite, failing at the same time, waits for production + sources = [r[4] for r in history.restorations] + self.assertIn("production", sources) + self.assertGreater(history.metrics()["spares used"], 0) + + def test_restore_from_ground(self): + """A spare on the ground is launched at the next slot.""" + policy = RestorationPolicy(detection_years=0.1, ground_spares=2) + history = self._simulate(policy) + sources = [r[4] for r in history.restorations[:2]] + self.assertEqual(sources, ["ground", "ground"]) + delays = sorted(round(r[3] - r[2], 6) for r in history.restorations[:2]) + # both known at 3.1, and launched together then + self.assertEqual(delays, [0.1, 0.1]) + restorations = [l for l in history.launches if l.purpose == "restoration"] + self.assertEqual(restorations[0].satellites, 2) + spares = [b for b in history.production if b.purpose == "spare"] + self.assertEqual(sum(b.satellites for b in spares), 2) + + def test_ground_spare_at_the_next_slot(self): + """A spare on the ground is launched at the next slot, not on a launch + booked for the plane later (such as of a spare in orbit replenished).""" + policy = RestorationPolicy( + orbit_spares=1, ground_spares=1, replenish=True, procurement_years=3 + ) + deployment = DeploymentSchedule(years=10).plan(self.layout, policy=policy) + lives = {(0, 0, 0): 1.0, (0, 1, 0): 1.5} # position 0 fails at 1, 1 at 1.5 + + def life(simulation, plane, position, generation, start=0.0): + del simulation, start + return lives.get((plane, position, generation), math.inf) + + with mock.patch.object(_Simulation, "_life", life): + history = deployment.simulate(self.failures, seed=0) + restored = {r.position: (r.source, r.restored) for r in history.restorations} + self.assertEqual(restored[0], ("orbit", 1.0 + 0.1 + 0.25)) + # known at 1.6, while the replenished spare is launched at 4.1 + self.assertEqual(restored[1][0], "ground") + self.assertAlmostEqual(restored[1][1], 1.6) + launches = [(l.purpose, round(l.time, 6)) for l in history.launches[1:]] + self.assertEqual(launches, [("restoration", 1.6), ("spare", 4.1)]) + + def test_batching(self): + """Restorations of a plane waiting within a window share a launch.""" + alone = self._simulate(RestorationPolicy(ground_spares=2)) + shared = self._simulate(RestorationPolicy(ground_spares=2, batch_years=0.2)) + count = lambda h: sum(l.purpose == "restoration" for l in h.launches) + self.assertGreater(count(alone), count(shared)) + + def test_launch_failures(self): + """A failed launch loses its satellites.""" + always = FailureModel(launch=1.0) + degraded = self._simulate(RestorationPolicy(restore=False), failures=always) + self.assertEqual(degraded.operating, {}) + self.assertTrue(all(launch.failed for launch in degraded.launches)) + self.assertEqual(degraded.metrics()["availability"], 0) + restored = self._simulate(RestorationPolicy(), failures=always) + # restorations are attempted (and fail) until the end of the mission + self.assertGreater(len(restored.launches), len(degraded.launches)) + self.assertEqual(restored.operating, {}) + + def test_planned_replacement(self): + """A planned replacement restores a degraded satellite.""" + schedule = DeploymentSchedule(years=4, design_life=2, development_years=1) + degrade = RestorationPolicy(restore=False) + history = schedule.plan(self.layout, policy=degrade).simulate( + self.failures, seed=0 + ) + # launched at 1, failed at 2.5, replaced at 3, failed at 4.5 + self.assertEqual(history.operating[0, 0], [(1, 2.5), (3, 4.5)]) + + def test_design_life_does_not_retire(self): + """A satellite whose planned replacement fails to launch operates past + its design life, and the replacement is not flown again.""" + schedule = DeploymentSchedule(years=6, design_life=2, development_years=1) + deployment = schedule.plan(self.layout, policy=RestorationPolicy(restore=False)) + launches_fail = FailureModel(launch=0.5) + for seed in range(50): + history = deployment.simulate(launches_fail, seed) + deployed = [l for l in history.launches if l.purpose == "deployment"] + replaced = [l for l in history.launches if l.purpose == "replacement"] + if not deployed[0].failed and replaced[0].failed: + break + else: + self.fail("no history with a failed replacement") + failed = replaced[0] + spans = history.operating[failed.plane, failed.first] + self.assertTrue(any(a < failed.time < b for a, b in spans)) + # only the planned replacements are launched: none is flown again + self.assertEqual( + len(replaced), sum(l.purpose == "replacement" for l in deployment.launches) + ) + + def test_common_random_numbers(self): + """The satellite at the same position fails at the same age.""" + failures = FailureModel(life=Exponential(0.3), launch=0.1) + first = self._simulate( + RestorationPolicy(restore=False), failures=failures, seed=4 + ) + other = self._simulate(RestorationPolicy(), failures=failures, seed=4) + self.assertEqual(first.failures[0], other.failures[0]) + different = self._simulate(RestorationPolicy(), failures=failures, seed=5) + self.assertNotEqual(first.failures, different.failures) + + def test_costs_of_policies(self): + """Restorations and spares cost more than degrading.""" + model = CostModel( + SatelliteCost(development=10, first_unit=5), + launch=LaunchCost(per_launch=3), + operations=OperationsCost(per_satellite_year=1), + ) + failures = FailureModel(life=Exponential(0.3)) + totals = {} + for name, policy in ( + ("degrade", RestorationPolicy(restore=False)), + ("produce", RestorationPolicy()), + ("orbit", RestorationPolicy(replenish=True, orbit_spares=1)), + ): + costs, availability = [], [] + for seed in range(100): + history = self._simulate(policy, failures=failures, seed=seed) + costs.append(model.estimate(history).total) + availability.append(history.metrics()["availability"]) + totals[name] = (np.mean(costs), np.mean(availability)) + self.assertLess(totals["degrade"][0], totals["produce"][0]) + self.assertLess(totals["degrade"][1], totals["produce"][1]) + self.assertLess(totals["produce"][0], totals["orbit"][0]) + + def test_policy_validation(self): + """Policies are validated.""" + for invalid in ( + {"detection_years": -1}, + {"drift_years": -1}, + {"procurement_years": -1}, + {"batch_years": -1}, + {"ground_spares": -1}, + {"orbit_spares": {"a": -1}}, + ): + with self.assertRaises(ValueError): + RestorationPolicy(**invalid) + with self.assertRaisesRegex(ValueError, "ground spares"): + RestorationPolicy(ground_spares={"a": 2}).ground_spares_of("b") + self.assertEqual( + RestorationPolicy(orbit_spares={"a": 2}).orbit_spares_of("a"), 2 + ) + + +class TestPolicySpace(unittest.TestCase): + """ + Unit tests for policies as decisions of designs. + """ + + def test_fragment(self): + """Policies are enumerated, without spares that are never used.""" + space = policy_space(orbit_spares=Integer(0, 1), ground_spares=Integer(0, 1)) + flats = [d.flat() for d in space.enumerate()] + self.assertEqual(len(flats), 5) + self.assertNotIn( + {"restore": False, "orbit_spares": 1, "ground_spares": 0}, flats + ) + loose = policy_space( + orbit_spares=Integer(0, 1), + ground_spares=Integer(0, 1), + require_restoration=False, + ) + self.assertEqual(len(loose.enumerate()), 8) + with self.assertRaises(ValueError): + policy_space(drift=0.1) + + def test_configure(self): + """Values of a design configure a policy or a schedule.""" + space = DesignSpace( + policy=policy_space( + restore=True, ground_spares=Integer(1, 2), drift_years=0.5 + ), + launch_interval=Integer(0, 1), + ) + design = space.enumerate()[-1] + base = RestorationPolicy(procurement_years=0.3) + policy = configure(base, design.policy) + self.assertEqual( + (policy.restore, policy.ground_spares, policy.drift_years), (True, 2, 0.5) + ) + self.assertEqual(policy.procurement_years, 0.3) + schedule = configure(DeploymentSchedule(years=5), design.values, years=6) + self.assertEqual((schedule.launch_interval, schedule.years), (1, 6)) + with self.assertRaises(ValueError): + configure(base, design.policy, unknown=1) + with self.assertRaises(TypeError): + configure(RestorationPolicy, design.policy) + + def test_trade_of_policies(self): + """Policies trade cost against availability on a front.""" + schedule = DeploymentSchedule( + years=5, development_years=1, production_rate=4, launch_capacity=3 + ) + failures = FailureModel(life=Exponential(0.3), launch=0.05) + model = CostModel( + SatelliteCost(development=10, first_unit=5), + launch=LaunchCost(per_launch=3), + operations=OperationsCost(per_satellite_year=1), + ) + space = DesignSpace( + layout=walker_space( + inclination=55.0, planes=Integer(1, 2), per_plane=2, relative_spacing=0 + ), + policy=policy_space( + orbit_spares=Integer(0, 1), ground_spares=Integer(0, 1) + ), + failure_seed=Uncertain.seed(), + ) + + def evaluate(d): + policy = configure(RestorationPolicy(), d.policy) + deployment = schedule.plan(d.layout, policy=policy) + history = deployment.simulate(failures, d.failure_seed) + return { + "cost": model.estimate(history).total, + "availability": history.metrics()["availability"], + } + + designs = space.enumerate() + self.assertEqual(len(designs), 2 * 5) + results = Study(space, lambda d: d, evaluate, replicates=30).run(designs) + summary = summarize(results, statistics=["cost", "availability"]) + front = summary[pareto_front(summary, {"cost": "min", "availability": "max"})] + policies = { + ( + row["policy.restore"], + row["policy.orbit_spares"], + row["policy.ground_spares"], + ) + for _, row in results.drop_duplicates("design") + .set_index("design") + .loc[front.design] + .iterrows() + } + # degrading is the cheapest, and a policy that restores is the most available + self.assertIn((False, 0, 0), policies) + self.assertGreater(len(policies), 1) + + +class TestManyMissions(unittest.TestCase): + """ + Unit tests for many histories of missions in a replicate, and their + evaluation with a cache. + """ + + def setUp(self): + from datetime import ( + datetime, + timezone, + ) # pylint: disable=import-outside-toplevel + + from tatc.schemas import Instrument # pylint: disable=import-outside-toplevel + + self.schedule = DeploymentSchedule( + years=5, development_years=1, production_rate=4, launch_capacity=3 + ) + self.layout = _walker(2, 2) + self.satellites = build_constellation( + self.layout, + Instrument(name="imager", field_of_regard=60), + epoch=datetime(2026, 1, 1, tzinfo=timezone.utc), + altitude=700e3, + ) + names = [s.name for s in self.satellites] + self.observations = pd.DataFrame({"satellite": names * 5, "target": range(20)}) + self.failures = FailureModel(life=Exponential(0.3), launch=0.05) + self.calls = [] + + def _metric(self, observations): + self.calls.append(len(observations)) + return {"share": 25.0 * observations["satellite"].nunique()} + + def test_simulate_many(self): + """Histories of a replicate differ, and are the same in every design.""" + deployment = self.schedule.plan(self.layout) + histories = deployment.simulate_many( + self.failures, 7, histories=10, sampling="random" + ) + self.assertEqual(len(histories), 10) + self.assertGreater(len({tuple(h.failures) for h in histories}), 1) + again = deployment.simulate(self.failures, (7, 3)) + self.assertEqual(again.failures, histories[3].failures) + degrading = self.schedule.plan(self.layout, policy=DEGRADE) + degraded = degrading.simulate_many( + self.failures, 7, histories=10, sampling="random" + ) + self.assertEqual(degraded[3].failures[0], histories[3].failures[0]) + # without a seed, the one history without failures + (unseeded,) = deployment.simulate_many(self.failures, None) + self.assertEqual(unseeded.failures, []) + with self.assertRaisesRegex(ValueError, "seed"): + deployment.simulate_many(self.failures, None, histories=10) + self.assertIs(deployment.planned(), deployment.planned()) + with self.assertRaises(ValueError): + deployment.simulate_many(self.failures, 7, histories=0) + # without a model of failures, as simulate, nothing fails + unfailing = deployment.simulate_many(seed=7, histories=3) + self.assertEqual([h.failures for h in unfailing], [[], [], []]) + # pylint: disable-next=protected-access + self.assertEqual(deployment._expected_metrics(histories=3)["availability"], 1) + + def test_phase_cache(self): + """A cache evaluates each set of satellites once, as without it.""" + deployment = self.schedule.plan(self.layout) + histories = deployment.simulate_many(self.failures, 7, histories=20) + cache = PhaseCache(self._metric) + capability = Capability(self.satellites, self.observations, cache, context="r0") + for history in histories: + phases = history.phases(self.satellites) + cached = capability.evaluate(phases) + direct = evaluate_phases(phases, self.observations, self._metric) + pd.testing.assert_frame_equal(cached, direct) + self.assertGreater(cache.hits, cache.misses) + # satellites of the same content (other names) share results + renamed = [ + s.model_copy(update={"name": f"other {k}"}) + for k, s in enumerate(self.satellites) + ] + observations = self.observations.replace( + {s.name: r.name for s, r in zip(self.satellites, renamed)} + ) + misses = cache.misses + Capability(renamed, observations, cache, context="r0").evaluate( + histories[0].phases(renamed) + ) + self.assertEqual(cache.misses, misses) + # other observations (another context) are evaluated again + Capability(self.satellites, self.observations, cache, context="r1").evaluate( + histories[0].phases(self.satellites) + ) + self.assertGreater(cache.misses, misses) + cache.clear() + self.assertEqual((cache.hits, cache.misses), (0, 0)) + + def test_phase_cache_of_identical_satellites(self): + """Satellites of the same content each count in the sets of a cache.""" + one = self.satellites[0] + twin = one.model_copy(update={"name": "twin"}) + observations = pd.DataFrame( + {"satellite": [one.name] * 3 + ["twin"] * 3, "target": [0, 1, 2] * 2} + ) + + def count(subset): + return {"observations": float(len(subset))} + + for sets in ( + [[one.name], [one.name, "twin"]], + [[one.name, "twin"], [one.name]], + ): + capability = Capability([one, twin], observations, PhaseCache(count)) + self.assertEqual( + [capability(names)["observations"] for names in sets], + [3.0 * len(names) for names in sets], + ) + + def test_evaluate_and_summarize(self): + """Histories are evaluated, priced, and summarized as one record.""" + deployment = self.schedule.plan(self.layout) + histories = deployment.simulate_many(self.failures, 7, histories=30) + model = CostModel( + SatelliteCost(development=10, first_unit=5), launch=LaunchCost(per_launch=3) + ) + capability = Capability( + self.satellites, self.observations, PhaseCache(self._metric), context="r0" + ) + missions = evaluate_histories(histories, capability, cost_model=model) + self.assertEqual(len(missions), 30) + for column in ( + "share mission", + "availability", + "failures", + "cost", + "cost present", + ): + self.assertIn(column, missions.columns) + summary = summarize_histories( + missions, + statistics=[ + Quantile("share mission", 0.1), + Quantile("share mission", 0.5), + Quantile("cost", 0.7), + Probability("share mission", ">=", 60), + ], + ) + self.assertAlmostEqual( + summary["share mission"], missions["share mission"].mean() + ) + self.assertAlmostEqual( + summary["share mission histories p10"], + missions["share mission"].quantile(0.1), + ) + self.assertIn("share mission histories p50", summary) + self.assertIn("cost histories p70", summary) + self.assertAlmostEqual( + summary["P(share mission >= 60) histories"], + (missions["share mission"] >= 60).mean(), + ) + # without a cache, the same evaluations + direct = evaluate_histories( + histories, Capability(self.satellites, self.observations, self._metric) + ) + np.testing.assert_allclose(direct["share mission"], missions["share mission"]) + + +class TestVarianceReduction(unittest.TestCase): + """ + Unit tests for stratified histories and control variates. + """ + + def setUp(self): + self.schedule = DeploymentSchedule(years=5, development_years=1) + self.layout = _walker(2, 2) + self.failures = FailureModel(life=Exponential(0.3)) + + def test_lifetimes_from_uniform(self): + """Lives drawn from uniform numbers follow their distributions.""" + uniform = np.array([0.05, 0.5, 0.95]) + for life in ( + Exponential(0.2), + Weibull(0.5, 30), + Weibull(4, 7), + Piecewise([0, 1, 4], [0.3, 0.05, 0.2]), + ): + lives = np.array([life.from_uniform([u]) for u in uniform]) + np.testing.assert_allclose(1 - life.survival(lives), uniform) + parts = (Weibull(0.5, 30), Exponential(0.05), Weibull(5, 7)) + bathtub = Bathtub(*parts) + self.assertEqual(bathtub.dimensions, 3) + self.assertEqual( + bathtub.from_uniform([0.1, 0.2, 0.3]), + min(part.from_uniform([u]) for part, u in zip(parts, (0.1, 0.2, 0.3))), + ) + self.assertEqual(Exponential(0).from_uniform([0.5]), math.inf) + + def test_strata(self): + """Each draw of the histories of a replicate takes each stratum once.""" + from tatc.tradespace.simulation import ( + _Sampler, + ) # pylint: disable=import-outside-toplevel + + count = 16 + draws = np.array([_Sampler(3, k, count)((0, 1, 2, 0), 2) for k in range(count)]) + for dimension in range(2): + strata = np.sort(np.floor(draws[:, dimension] * count).astype(int)) + np.testing.assert_array_equal(strata, np.arange(count)) + self.assertFalse(np.array_equal(draws[:, 0], draws[:, 1])) + + def test_stratified_histories(self): + """Stratified histories estimate means more precisely, without bias.""" + deployment = self.schedule.plan(self.layout) + degrading = self.schedule.plan(self.layout, policy=DEGRADE) + estimates = {} + for sampling in ("random", "stratified"): + estimates[sampling] = np.array( + [ + np.mean( + [ + h.metrics()["availability"] + for h in degrading.simulate_many( + self.failures, seed, histories=20, sampling=sampling + ) + ] + ) + for seed in range(40) + ] + ) + self.assertLess(estimates["stratified"].var(), 0.5 * estimates["random"].var()) + self.assertAlmostEqual( + estimates["stratified"].mean(), estimates["random"].mean(), delta=0.02 + ) + # common random numbers: the same failures of a slot under other policies + first = degrading.simulate_many(self.failures, 1, histories=8) + other = deployment.simulate_many(self.failures, 1, histories=8) + self.assertEqual(first[3].failures[0], other[3].failures[0]) + with self.assertRaises(ValueError): + deployment.simulate_many( + self.failures, 1, histories=8, sampling="antithetic" + ) + + def test_expected_metrics(self): + """Expected measures of a mission from many histories.""" + deployment = self.schedule.plan(self.layout) + # pylint: disable=protected-access + expected = deployment._expected_metrics(self.failures, histories=200) + self.assertTrue(0 < expected["availability"] < 1) + self.assertEqual( + deployment._expected_metrics(FailureModel(), histories=10)["availability"], + 1.0, + ) + + def test_control_variates(self): + """Control variates correct means by the deviations of the controls.""" + rng = np.random.default_rng(0) + estimates = {"plain": [], "controlled": []} + for _ in range(200): + x = rng.normal(0.8, 0.1, 20) + y = 3 * x + rng.normal(0, 0.05, 20) + missions = pd.DataFrame( + {"availability": x, "share": y, "failures": rng.poisson(2, 20)} + ) + plain = summarize_histories(missions) + controlled = summarize_histories(missions, controls={"availability": 0.8}) + self.assertEqual(controlled["availability"], 0.8) + self.assertAlmostEqual(plain["failures"], missions.failures.mean(), delta=1) + estimates["plain"].append(plain["share"]) + estimates["controlled"].append(controlled["share"]) + plain, controlled = (np.array(v) for v in estimates.values()) + # the true mean is 3 * 0.8 = 2.4; the controls remove most of the variance + self.assertAlmostEqual(controlled.mean(), 2.4, delta=0.01) + self.assertLess(controlled.var(), 0.1 * plain.var()) + # histories without a value are left out of the regression + missions = pd.DataFrame( + {"availability": [0.7, 0.8, 0.9, 1.0], "years": [np.nan, 1.0, 2.0, 3.0]} + ) + summary = summarize_histories(missions, controls={"availability": 0.85}) + self.assertTrue(np.isfinite(summary["years"])) + with self.assertRaises(ValueError): + summarize_histories(missions, controls={"cost": 1.0}) + # a time that a history never meets keeps its infinite mean + availability = rng.uniform(0.6, 1.0, 20) + time = 3 + 2 * (1 - availability) + rng.normal(0, 0.05, 20) + time[availability < 0.65] = math.inf + missions = pd.DataFrame({"availability": availability, "share time": time}) + controlled = summarize_histories(missions, controls={"availability": 0.8}) + self.assertEqual(controlled["share time"], math.inf) + + def test_statistics_with_infinite_values(self): + """Statistics over histories of equal weights are those over + replicates, also of infinite values; weighted spreads of infinite + values are missing.""" + times = [float(t) for t in range(1, 21)] + statistics = [Quantile("time", 0.1), Quantile("time", 0.5)] + finite = summarize_histories( + pd.DataFrame({"time": times[:-1] + [1e9]}), statistics=statistics + ) + never = summarize_histories( + pd.DataFrame({"time": times[:-1] + [math.inf]}), statistics=statistics + ) + # a history that never meets it (the latest) moves no lower quantile + self.assertAlmostEqual(never["time histories p10"], 2.9) + for name in ("time histories p10", "time histories p50"): + self.assertAlmostEqual(never[name], finite[name]) + spread = [StandardDeviation("time")] + with warnings.catch_warnings(): + warnings.simplefilter("error") + plain = summarize_histories( + pd.DataFrame({"time": [1.0, 2.0, math.inf]}), statistics=spread + ) + weighted = summarize_histories( + pd.DataFrame({"time": [1.0, 2.0, math.inf], "weight": [0.5, 1.0, 1.5]}), + statistics=spread, + ) + self.assertTrue(math.isnan(plain["time histories std"])) + self.assertTrue(math.isnan(weighted["time histories std"])) + self.assertEqual(weighted["time"], math.inf) + + +def _costs(replicate_seconds, history_seconds): + """The histories of a pilot of 20 and the costs of an allocation.""" + return { + "histories": 20, + "replicate_seconds": replicate_seconds, + "history_seconds": history_seconds, + } + + +class TestAllocateHistories(unittest.TestCase): + """ + Unit tests for dividing evaluations between replicates and histories. + """ + + def _pilot(self, between, within, replicates=200, histories=20, seed=0): + rng = np.random.default_rng(seed) + rows = [] + for _ in range(replicates): + expected = rng.normal(50, between) + missions = pd.DataFrame({"share": rng.normal(expected, within, histories)}) + rows.append( + summarize_histories(missions, statistics=[StandardDeviation("share")]) + ) + return pd.DataFrame(rows) + + def test_recommendation(self): + """Histories balance the variances and costs of the two levels.""" + records = self._pilot(between=2, within=6) + self.assertIn("share histories std", records.columns) + result = allocate_histories( + records, + "share", + histories=20, + replicate_seconds=100, + history_seconds=1, + standard_error=0.5, + ) + # sqrt(100 * 36 / (1 * 4)) = 30 + self.assertAlmostEqual(result["histories"], 30, delta=6) + self.assertAlmostEqual(result["between"], 2, delta=0.4) + self.assertAlmostEqual(result["within"], 6, delta=0.3) + variance = result["between"] ** 2 + result["within"] ** 2 / result["histories"] + self.assertEqual(result["replicates"], math.ceil(variance / 0.25)) + self.assertAlmostEqual( + result["seconds"], result["replicates"] * result["replicate seconds"] + ) + # costlier histories call for fewer of them + fewer = allocate_histories(records, "share", **_costs(100, 10)) + self.assertLess(fewer["histories"], result["histories"]) + + def test_limits(self): + """Without variance between replicates, the most histories.""" + records = self._pilot(between=0, within=6, replicates=50) + result = allocate_histories( + records, "share", **_costs(100, 1), max_histories=500 + ) + self.assertLessEqual(result["histories"], 500) + self.assertGreater(result["histories"], 100) + # a standard error that two replicates achieve: the fewest histories + enough = allocate_histories( + records, "share", **_costs(100, 1), standard_error=0.5 + ) + self.assertEqual(enough["replicates"], 2) + self.assertLess(enough["histories"], 100) + self.assertLessEqual( + enough["between"] ** 2 + enough["within"] ** 2 / enough["histories"], + 2 * 0.5**2 + 1e-9, + ) + # means that vary less than independent histories can (stratified) + steady = records.assign(share=50.0) + with self.assertWarns(UserWarning): + allocate_histories(steady, "share", **_costs(100, 1)) + with self.assertRaises(ValueError): + allocate_histories(records.iloc[:1], "share", **_costs(100, 1)) + with self.assertRaises(ValueError): + allocate_histories(records, "share", **_costs(0, 1)) + + +class TestExpectedMissions(unittest.TestCase): + """ + Unit tests for exact expectations of missions without restoration. + """ + + def setUp(self): + from datetime import ( + datetime, + timezone, + ) # pylint: disable=import-outside-toplevel + + from tatc.schemas import Instrument # pylint: disable=import-outside-toplevel + + self.layout = _walker(2, 2) + self.satellites = build_constellation( + self.layout, + Instrument(name="imager", field_of_regard=60), + epoch=datetime(2026, 1, 1, tzinfo=timezone.utc), + altitude=700e3, + ) + names = [s.name for s in self.satellites] + self.observations = pd.DataFrame({"satellite": names * 3, "target": range(12)}) + + @staticmethod + def _metric(observations): + # a nonlinear metric of the operating satellites (the first counts double) + names = set(observations["satellite"]) if len(observations) else set() + score = len(names) + ("satellite 1" in names) + return {"score": float(score**2)} + + def _compare(self, schedule, failures): + deployment = schedule.plan(self.layout, policy=DEGRADE) + capability = Capability( + self.satellites, self.observations, PhaseCache(self._metric) + ) + exact = exact_expectations(deployment, failures, capability) + histories = deployment.simulate_many(failures, 3, histories=4000) + missions = evaluate_histories(histories, capability) + error = missions["score mission"].std() / np.sqrt(len(missions)) + self.assertAlmostEqual( + exact["score mission"], missions["score mission"].mean(), delta=4 * error + ) + self.assertAlmostEqual( + exact["availability"], missions["availability"].mean(), delta=0.01 + ) + self.assertGreaterEqual(exact["coverage"], 0.999) + return exact + + def test_matches_simulation(self): + """Expectations are the means of many simulated histories.""" + failures = FailureModel(life=Exponential(0.2), launch=0.1) + self._compare( + DeploymentSchedule(years=5, development_years=1, production_rate=2), + failures, + ) + # planned replacements, which a failed launch leaves to the old satellites + self._compare( + DeploymentSchedule(years=6, design_life=2, development_years=1), failures + ) + bathtub = FailureModel( + life=Bathtub(Weibull(0.5, 40), Exponential(0.05), Weibull(4, 5)), + launch=0.05, + ) + self._compare(DeploymentSchedule(years=5, launch_interval=0.5), bathtub) + + def test_without_failures(self): + """Without failures, the expectation is the mission's.""" + deployment = DeploymentSchedule( + years=4, development_years=1, production_rate=2 + ).plan(self.layout, policy=DEGRADE) + capability = Capability(self.satellites, self.observations, self._metric) + exact = exact_expectations(deployment, FailureModel(), capability) + phases = deployment.phases(self.satellites) + planned = summarize_phases( + evaluate_phases(phases, self.observations, self._metric) + ) + self.assertAlmostEqual( + exact["score mission"], planned["score mission"], places=6 + ) + self.assertEqual(exact["availability"], 1.0) + # every launch fails: nothing operates + lost = exact_expectations(deployment, FailureModel(launch=1.0), capability) + self.assertEqual(lost["availability"], 0.0) + self.assertEqual(lost["score mission"], 0.0) + + def test_sets_known_before_enumerating(self): + """The sets that exact expectations enumerate are counted before they + are, so that a constellation of too many fails at once (and the + failures of a study fall back to histories, see Failures).""" + schedule = DeploymentSchedule(years=4, launch_interval=0.5) + deployment = schedule.plan(self.layout, policy=DEGRADE) + failures = FailureModel(life=Exponential(0.3), launch=0.05) + capability = Capability(self.satellites, self.observations, self._metric) + weigh = mock.Mock(wraps=expectations_module._set_weight) + with mock.patch.object(expectations_module, "_set_weight", weigh): + exact = exact_expectations(deployment, failures, capability) + self.assertEqual(weigh.call_count, _exact_sets(deployment, failures)) + self.assertGreaterEqual(exact["coverage"], 0.999) + # reliable satellites: the sets of fewer missing cover the mission + reliable = FailureModel(life=Exponential(0.001)) + self.assertLess(_exact_sets(deployment, reliable), 2**4) + # 20 satellites (of 4 planes of 5) of a few years: too many, at once + large = DeploymentSchedule(years=5).plan(_walker(4, 5), policy=DEGRADE) + failures = FailureModel(life=Exponential(0.3)) + self.assertGreater(_exact_sets(large, failures), MAX_SETS) + names = _names(20) + weigh = mock.Mock(wraps=expectations_module._set_weight) + with mock.patch.object(expectations_module, "_set_weight", weigh): + with self.assertRaisesRegex(ExactExpectationsError, "too many sets"): + exact_expectations( + large, + failures, + Capability(names, pd.DataFrame({"satellite": names}), len), + ) + weigh.assert_not_called() + + def test_limits(self): + """Sets are enumerated within limits, of missions without restoration + that are not staged.""" + schedule = DeploymentSchedule(years=4) + deployment = schedule.plan(self.layout, policy=DEGRADE) + failures = FailureModel(life=Exponential(0.5)) + capability = Capability(self.satellites, self.observations, self._metric) + with self.assertRaises(ExactExpectationsError): + exact_expectations(deployment, failures, capability, max_sets=3) + with self.assertRaises(ValueError) as caught: + exact_expectations( + deployment, + failures, + Capability(self.satellites[:3], self.observations, self._metric), + ) + self.assertNotIsInstance(caught.exception, ExactExpectationsError) + # the policy of the deployment restores failures, or it is staged + with self.assertRaisesRegex(ExactExpectationsError, "restore"): + exact_expectations(schedule.plan(self.layout), failures, capability) + staged = schedule.plan(self.layout, policy=DEGRADE, stages=[Stage(1, 1.0)]) + with self.assertRaisesRegex(ExactExpectationsError, "staged"): + exact_expectations(staged, failures, capability) + + +class TestImportanceSampling(unittest.TestCase): + """ + Unit tests for histories of stressed failures and their weights. + """ + + def test_stressed_lives(self): + """Stressed lives are weighted to their distribution, up to a horizon.""" + rng = np.random.default_rng(0) + for life in ( + Exponential(0.1), + Weibull(2, 8), + Bathtub(Weibull(0.5, 40), Exponential(0.05)), + ): + draws = [ + life.stressed(rng.random(life.dimensions), 4.0, 5.0) + for _ in range(20000) + ] + lives = np.array([d[0] for d in draws]) + weights = np.exp([d[1] for d in draws]) + self.assertAlmostEqual(weights.mean(), 1.0, delta=0.03) + # the weighted share that survives the horizon is this distribution's + survived = np.sum(weights * (lives > 5)) / weights.sum() + self.assertAlmostEqual( + survived, float(life.survival(np.array([5.0]))[0]), delta=0.02 + ) + # the stressed lives fail more often + self.assertGreater( + (lives <= 5).mean(), 1 - life.survival(np.array([5.0]))[0] + ) + + def test_rare_losses(self): + """Stress estimates the probability of a rare loss with less variance.""" + deployment = DeploymentSchedule(years=5).plan(_walker(1, 3), policy=DEGRADE) + failures = FailureModel(life=Exponential(0.01)) + p = 1 - math.exp(-0.05) + exact = 3 * p**2 * (1 - p) + p**3 + estimates = {} + for stress in (1.0, 8.0): + values = [] + for seed in range(25): + histories = deployment.simulate_many( + failures, seed, histories=200, stress=stress + ) + rows = pd.DataFrame( + [{**h.metrics(), "weight": h.weight} for h in histories] + ) + summary = summarize_histories( + rows, statistics=[Probability("failures", ">=", 2)] + ) + values.append(summary["P(failures >= 2) histories"]) + if stress > 1: + self.assertGreater(summary["effective histories"], 30) + estimates[stress] = np.array(values) + self.assertAlmostEqual(estimates[8.0].mean(), exact, delta=0.001) + self.assertLess(estimates[8.0].var(), estimates[1.0].var() / 5) + # without stress, histories are not weighted + plain = deployment.simulate_many(failures, 1, histories=5) + self.assertTrue(all(h.weight == 1.0 for h in plain)) + with self.assertRaises(ValueError): + deployment.simulate_many(failures, 1, histories=5, stress=0) + + def test_stressed_launches(self): + """Stressed launches are weighted to their probability of failure.""" + deployment = DeploymentSchedule(years=2).plan(_walker(1, 2), policy=DEGRADE) + failures = FailureModel(launch=0.02) + histories = deployment.simulate_many(failures, 4, histories=3000, stress=10.0) + weights = np.array([h.weight for h in histories]) + lost = np.array([h.launches[0].failed for h in histories]) + self.assertGreater(lost.mean(), 0.1) # stressed: failures are common + self.assertAlmostEqual( + np.sum(weights * lost) / weights.sum(), 0.02, delta=0.005 + ) + + def test_times_and_columns(self): + """Times that a history never meets are infinite in the summaries, + missing values are left out, and statistics need columns of the + histories, of the kinds that summarize histories.""" + histories = pd.DataFrame({"accurate time": [2.0, 3.0, math.inf, np.nan]}) + summary = summarize_histories( + histories, + statistics=[ + Quantile("accurate time", 0.3), + Quantile("accurate time", 0.9), + Probability("accurate time", "<=", 3), + ], + ) + self.assertEqual(summary["accurate time"], math.inf) + # linear between the known values, as over replicates + self.assertAlmostEqual(summary["accurate time histories p30"], 2.6) + self.assertEqual(summary["accurate time histories p90"], math.inf) + self.assertEqual(summary["P(accurate time <= 3) histories"], 2 / 3) + with self.assertRaisesRegex(ValueError, "other"): + summarize_histories(histories, statistics=[Quantile("other", 0.5)]) + with self.assertRaisesRegex(ValueError, "other"): + summarize_histories(histories, statistics=[Probability("other", ">", 1)]) + with self.assertRaises(TypeError): + summarize_histories(histories, statistics=[Mean("accurate time")]) + + def test_weighted_summaries(self): + """Weighted histories give weighted statistics.""" + missions = pd.DataFrame( + {"value": [1.0, 2.0, 3.0, 4.0], "weight": [4.0, 1.0, 1.0, 2.0]} + ) + summary = summarize_histories( + missions, + statistics=[ + Quantile("value", 0.5), + Probability("value", ">=", 3), + StandardDeviation("value"), + ], + ) + self.assertAlmostEqual(summary["value"], (4 + 2 + 3 + 8) / 8) + self.assertEqual(summary["value histories p50"], 1.0) # half the weight is at 1 + self.assertAlmostEqual(summary["P(value >= 3) histories"], 3 / 8) + self.assertAlmostEqual(summary["effective histories"], 64 / 22) + self.assertNotIn("weight", summary) + self.assertGreater(summary["value histories std"], 0) diff --git a/tests/tradespace/test_fingerprint.py b/tests/tradespace/test_fingerprint.py new file mode 100644 index 0000000..82935fc --- /dev/null +++ b/tests/tradespace/test_fingerprint.py @@ -0,0 +1,780 @@ +""" +Unit tests for fingerprints of the definitions of trade studies. + +@author Paul T. Grogan +""" + +import ast +import functools +import importlib +import os +import tempfile +import subprocess +import sys +import unittest +import warnings +from types import SimpleNamespace +from unittest import mock +from datetime import datetime, timedelta, timezone +from functools import partial +from pathlib import Path + +import numpy as np +import pandas as pd + +from shapely.geometry import Point, box + +from tatc.analysis import collect_observations +from tatc.generation import generate_points_fibonacci_lattice +from tatc.schemas import Instrument +from tatc.tradespace import fingerprint +from tatc.tradespace import ( + CostModel, + DesignSpace, + Integer, + Real, + SatelliteCache, + SatelliteCost, + Study, + Uncertain, +) +from tatc.tradespace.fingerprint import ( + compare_definitions, + describe, + get_definition, + get_fingerprint, + warn_stale, +) + +THRESHOLD = 4 + + +def _helper(x): + return x * THRESHOLD + + +def _uses_helper(d): + return {"value": _helper(d.a)} + + +MODEL = None +TABLE = pd.DataFrame({"a": [1.0]}) + + +class _Own: + """An object of a class of the study's own, described by its attributes.""" + + def __init__(self, value): + self.value = value + + +def _uses_table(d): + return {"value": TABLE.a.sum() * d.a} + + +def _uses_attribute(d): + # an attribute named as the global `values`, which the function does not use + return {"value": d.values} + + +values = pd.DataFrame({"a": [1.0]}) # pylint: disable=invalid-name + + +class _Cache: + """State of the study's own, kept in an attribute (not described).""" + + def __init__(self): + self.results = {} + + +CACHE = _Cache() + + +def _uses_cache(d): + if d not in CACHE.results: + CACHE.results[d] = object() + return CACHE.results[d] + + +PAYLOAD = Instrument(name="imager", field_of_regard=30) +INSTRUMENTS = {30: Instrument(name="a", field_of_regard=30)} +SCORER = _Own(3) +METRIC = partial(max, 3) + + +def _uses_payload(d): + return PAYLOAD.field_of_regard * d + + +def _uses_instruments(d): + return INSTRUMENTS[d] + + +def _uses_scorer(d): + return SCORER.value * d + + +def _uses_metric(d): + return METRIC(d) + + +@functools.lru_cache(maxsize=None) +def _cached(x): + return x * THRESHOLD + + +def _uses_cached(d): + return _cached(d) + + +def _uses_model(d): + return {"cost": MODEL.estimate(d.layout).total} + + +def _offset_cache(offset): + """A cache of an analysis of satellites that gives an offset.""" + return SatelliteCache(lambda satellite: offset) + + +SATELLITES = _offset_cache(0.0) +BASE = DesignSpace(n=Integer(1, 2)).design({"n": 1}) + + +def _uses_satellites(satellites): + return {"m": SATELLITES(satellites)} + + +def _uses_base(d): + return {"m": BASE.n * d} + + +START = datetime(2026, 1, 1, tzinfo=timezone.utc) + + +def _observe(satellite): + return collect_observations([], satellite, START, START + timedelta(days=1)) + + +def _space(high=4, fixed=1.0, spread=1.0): + return DesignSpace( + a=Integer(1, high), + b=Real(0, lambda d: d.a * 2, step=0.5), + fixed=fixed, + noise=Uncertain.normal(0, spread), + ) + + +_SCRIPT = """ +from tatc.tradespace import DesignSpace, Integer, Study, Uncertain +space = DesignSpace(a=Integer(1, 4), names={"x", "y", "z"}, noise=Uncertain.uniform(0, 1)) +study = Study(space, lambda d: d, lambda d: {"v": d.a in {"p", "q"}}) +print(study.fingerprint) +""" + + +class TestFingerprint(unittest.TestCase): + """ + Unit tests for fingerprints. + """ + + def test_same_definitions(self): + """Separately made definitions that are the same have the same fingerprint.""" + self.assertEqual(get_fingerprint(_space()), get_fingerprint(_space())) + self.assertEqual( + get_fingerprint(lambda d: d.a + 1), get_fingerprint(lambda d: d.a + 1) + ) + + def test_space_definitions(self): + """Bounds, fixed values, and distributions change the fingerprint.""" + base = get_fingerprint(_space()) + self.assertNotEqual(base, get_fingerprint(_space(high=5))) + self.assertNotEqual(base, get_fingerprint(_space(fixed=2.0))) + self.assertNotEqual(base, get_fingerprint(_space(spread=2.0))) + + def test_functions(self): + """Code, closures, defaults, and plain globals change the fingerprint.""" + self.assertNotEqual( + get_fingerprint(lambda d: d.a + 1), get_fingerprint(lambda d: d.a + 2) + ) + fingerprints = set() + for scale in (1, 2): + fingerprints.add(get_fingerprint(lambda d, s=scale: d.a * s)) + fingerprints.add(get_fingerprint(partial(max, scale))) + self.assertEqual(len(fingerprints), 4) + global THRESHOLD # pylint: disable=global-statement + before = get_fingerprint(_uses_helper) + THRESHOLD = 5 + try: + # a plain global of a function of the same module that it calls + self.assertNotEqual(before, get_fingerprint(_uses_helper)) + finally: + THRESHOLD = 4 + + def test_values(self): + """Plain values, models, and arrays are described by content.""" + start = datetime(2026, 1, 1, tzinfo=timezone.utc) + self.assertNotEqual( + get_fingerprint(start), get_fingerprint(start + timedelta(seconds=1)) + ) + self.assertNotEqual( + get_fingerprint(Instrument(name="a", field_of_regard=30)), + get_fingerprint(Instrument(name="a", field_of_regard=40)), + ) + self.assertNotEqual( + get_fingerprint(np.arange(3)), get_fingerprint(np.arange(3) + 1) + ) + self.assertEqual(get_fingerprint({1, 2, 3}), get_fingerprint({3, 2, 1})) + # data frames and series by their content (and geometries by theirs) + self.assertEqual( + get_fingerprint(pd.DataFrame({"a": [1]})), + get_fingerprint(pd.DataFrame({"a": [1]})), + ) + self.assertNotEqual( + get_fingerprint(pd.DataFrame({"a": [1]})), + get_fingerprint(pd.DataFrame({"a": [2]})), + ) + self.assertNotEqual( + get_fingerprint(pd.Series([1.0], name="a")), + get_fingerprint(pd.Series([1.0], name="b")), + ) + points = generate_points_fibonacci_lattice(count=5, rotate=True, seed=1) + moved = points.copy() + moved.loc[0, "geometry"] = Point(0, 1e-9) + self.assertEqual( + get_fingerprint(points), + get_fingerprint( + generate_points_fibonacci_lattice(count=5, rotate=True, seed=1) + ), + ) + self.assertNotEqual(get_fingerprint(points), get_fingerprint(moved)) + # other objects are described by their type only + # objects of installed classes by their type, and of the study's own + # classes by their attributes (other than mutable containers) + self.assertEqual( + get_fingerprint(SimpleNamespace(value=1)), + get_fingerprint(SimpleNamespace(value=2)), + ) + self.assertNotEqual(get_fingerprint(_Own(1)), get_fingerprint(_Own(2))) + + def test_attributes_are_not_globals(self): + """Attributes named as globals do not refer to the globals.""" + global values # pylint: disable=global-statement,invalid-name + before = get_fingerprint(_uses_attribute) + values = pd.DataFrame({"a": [2.0]}) + try: + self.assertEqual(before, get_fingerprint(_uses_attribute)) + finally: + values = pd.DataFrame({"a": [1.0]}) + + def test_data_globals(self): + """Data that functions refer to as globals is described by content.""" + global TABLE # pylint: disable=global-statement + before = get_fingerprint(_uses_table) + TABLE = pd.DataFrame({"a": [2.0]}) + try: + self.assertNotEqual(before, get_fingerprint(_uses_table)) + finally: + TABLE = pd.DataFrame({"a": [1.0]}) + + def test_global_state(self): + """State in the attributes of objects (such as caches) does not change + the fingerprint, but global containers (such as of instruments) do.""" + before = get_fingerprint(_uses_cache) + _uses_cache(1) + self.assertEqual(before, get_fingerprint(_uses_cache)) + global INSTRUMENTS # pylint: disable=global-statement + before = get_fingerprint(_uses_instruments) + INSTRUMENTS = {30: Instrument(name="a", field_of_regard=45)} + try: + self.assertNotEqual(before, get_fingerprint(_uses_instruments)) + finally: + INSTRUMENTS = {30: Instrument(name="a", field_of_regard=30)} + + def test_globals_by_content(self): + """Globals are described as the values they are: models, objects of the + study's own classes, partial functions, and decorated functions.""" + global THRESHOLD # pylint: disable=global-statement + cases = [ + ("PAYLOAD", _uses_payload, Instrument(name="imager", field_of_regard=60)), + ("SCORER", _uses_scorer, _Own(5)), + ("METRIC", _uses_metric, partial(max, 5)), + ] + for name, function, changed in cases: + with self.subTest(name=name): + original = globals()[name] + before = get_fingerprint(function) + globals()[name] = changed + try: + self.assertNotEqual(before, get_fingerprint(function)) + finally: + globals()[name] = original + # a function that a decorator wraps, by the wrapped function's code + before = get_fingerprint(_uses_cached) + THRESHOLD = 5 + try: + self.assertNotEqual(before, get_fingerprint(_uses_cached)) + finally: + THRESHOLD = 4 + + def test_one_rule(self): + """A global is described as the same value given directly is.""" + for name, function in ( + ("PAYLOAD", _uses_payload), + ("INSTRUMENTS", _uses_instruments), + ("SCORER", _uses_scorer), + ("METRIC", _uses_metric), + ("TABLE", _uses_table), + ): + with self.subTest(name=name): + described = get_definition(f=function)["values"]["f"]["globals"] + given = get_definition(globals()[name])["values"]["0"] + self.assertEqual(described[name], given) + + def test_versions(self): + """The same study with other code is found across versions of Python, + whose code orders, groups, and repeats constants differently, and a + study of other literals is not.""" + # pylint: disable=protected-access + # the constants of the same function in Python 3.10 and 3.14 + older = { + "code": "aa", + "constants": [ + "target_hash", + 0, + "sufficient", + "0.0", + 100, + {"code": "bb", "constants": [1], "names": []}, + "evaluate..", + ["sufficient", "n"], + None, + ], + "names": ["groupby"], + } + newer = { + "code": "cc", + "constants": ["target_hash", "sufficient", "0.0", "n", 0, 100, 100, 1], + "names": ["groupby", "size"], + } + self.assertEqual( + fingerprint._without_code({"f": older}), + fingerprint._without_code({"f": newer}), + ) + other = {**newer, "constants": [*newer["constants"], 4]} + self.assertNotEqual( + fingerprint._without_code({"f": older}), + fingerprint._without_code({"f": other}), + ) + # of definitions + definition = {"values": {"f": newer}} + self.assertEqual( + fingerprint._find_stale( + definition, + {"a": {"values": {"f": older}}, "b": None, "c": {"values": {}}}, + lambda key: 1, + ), + {"a": 1}, + ) + + def test_dataclasses(self): + """Dataclasses, such as cost models, are described by their fields.""" + cheap = CostModel(SatelliteCost(first_unit=10)) + dear = CostModel(SatelliteCost(first_unit=12)) + self.assertNotEqual(get_fingerprint(cheap), get_fingerprint(dear)) + global MODEL # pylint: disable=global-statement + MODEL = cheap + before = get_fingerprint(_uses_model) + MODEL = dear + # a dataclass that a function refers to as a global + self.assertNotEqual(before, get_fingerprint(_uses_model)) + + def test_study(self): + """A study's fingerprint changes with its seed and random numbers.""" + + def study(**kwargs): + return Study(_space(), lambda d: d, lambda d: {"value": d.a}, **kwargs) + + fingerprints = { + study().fingerprint, + study(seed=1).fingerprint, + study(common_random_numbers=False).fingerprint, + } + self.assertEqual(len(fingerprints), 3) + # but not with the settings of its execution + self.assertEqual(study().fingerprint, study(n_jobs=2).fingerprint) + + def test_modules(self): + """A definition has the modules of TAT-C (and resources) values depend on.""" + modules = get_definition(_observe)["modules"] + # the module that defines a function imported from a package, not + # the package, and the modules that it imports + self.assertIn("tatc.analysis.point_sampling", modules) + self.assertIn("tatc.schemas.space.satellite", modules) + self.assertNotIn("tatc.analysis", modules) + self.assertNotIn("tatc.analysis.ro_sampling", modules) + self.assertFalse(any(m.startswith("tatc.tradespace") for m in modules)) + self.assertIn("resources/defaults.yml", get_definition(_observe)["resources"]) + # studies depend on the modules of studies and their design spaces + study = Study(_space(), lambda d: d, lambda d: {"value": d.a}).definition + self.assertIn("tatc.tradespace.study", study["modules"]) + self.assertIn("tatc.tradespace.nodes", study["modules"]) + self.assertNotIn("tatc.tradespace.pareto", study["modules"]) + # plain values depend on no modules + self.assertEqual(get_definition(1, a="x")["modules"], {}) + + def test_source(self): + """The source of the modules values depend on changes the fingerprint.""" + original = fingerprint._hash # pylint: disable=protected-access + + def edited(name): + return lambda path: "edited" if path.name == name else original(path) + + before = get_fingerprint(_observe) + with mock.patch.object(fingerprint, "_hash", edited("point_sampling.py")): + self.assertNotEqual(before, get_fingerprint(_observe)) + with mock.patch.object(fingerprint, "_hash", edited("pareto.py")): + self.assertEqual(before, get_fingerprint(_observe)) + self.assertEqual(before, get_fingerprint(_observe)) + + def test_imports_resolve(self): + """Every import of a module of TAT-C resolves to modules of TAT-C.""" + # pylint: disable=protected-access + files = fingerprint._module_files() + self.assertIn("tatc.tradespace.fingerprint", files) + for module in files: + for _, other in fingerprint._imports(module): + self.assertIn(other, files, f"{other} (imported by {module})") + modules, resources = fingerprint._get_dependencies(files) + self.assertEqual(set(modules), set(files)) + self.assertTrue(resources) + # a constant of a package depends on its source only + self.assertEqual( + fingerprint._resolve_import("tatc", "__version__"), {("file", "tatc")} + ) + + def test_static_imports(self): + """Modules of TAT-C import modules by statements only (not by name).""" + # pylint: disable=protected-access + for module, path in fingerprint._module_files().items(): + tree = ast.parse(path.read_bytes()) + for node in ast.walk(tree): + if isinstance(node, ast.Call): + name = getattr(node.func, "id", getattr(node.func, "attr", None)) + self.assertNotIn(name, ("import_module", "__import__"), module) + + def test_compare(self): + """Comparisons of definitions name what differs.""" + + def study(high=4, offset=0.0, seed=0): + return Study( + _space(high=high), + lambda d: d, + lambda d, offset=offset: {"value": d.a + offset}, + seed=seed, + ).definition + + base = study() + self.assertEqual(compare_definitions(base, study()), []) + self.assertEqual( + compare_definitions(base, study(high=5)), + ["space.children.a.high: 4 -> 5"], + ) + self.assertEqual( + compare_definitions(base, study(offset=1.0)), + ["evaluate.defaults[0]: 0.0 -> 1.0"], + ) + self.assertEqual( + compare_definitions(base, study(high=5, seed=1), limit=1), + ["seed: 0 -> 1", "1 more"], + ) + other = { + **base, + "python": "cpython 0.0", + "modules": {**base["modules"], "tatc.tradespace.nodes": "edited"}, + } + self.assertEqual( + compare_definitions(base, other), + [ + f"python: {base['python']} -> cpython 0.0", + "module tatc.tradespace.nodes", + ], + ) + self.assertTrue(base["python"].endswith(f"{sys.version_info[1]}")) + + def test_stable_between_sessions(self): + """Fingerprints do not change between sessions (with other hash seeds).""" + prints = set() + for seed in ("1", "2"): + output = subprocess.run( + [sys.executable, "-c", _SCRIPT], + capture_output=True, + text=True, + check=True, + env={**os.environ, "PYTHONHASHSEED": seed}, + ) + prints.add(output.stdout.strip()) + self.assertEqual(len(prints), 1) + + +_BOX = box(0, 0, 1, 1) + + +def _uses_box(d): + return {"area": _BOX.area * d.a} + + +def _function(source, **names): + """A function `f` of source code, with globals.""" + namespace = dict(names) + exec(source, namespace) # pylint: disable=exec-used + return namespace["f"] + + +class TestDescriptions(unittest.TestCase): + """ + Unit tests for the descriptions of values that fingerprints hash. + """ + + def test_geometries(self): + """Geometries are described by their content, also as globals.""" + + def closing(geometry): + return lambda d: geometry.area * d.a + + self.assertNotEqual( + get_fingerprint(f=closing(box(0, 0, 1, 1))), + get_fingerprint(f=closing(box(0, 0, 2, 2))), + ) + self.assertEqual( + get_fingerprint(f=closing(box(0, 0, 1, 1))), + get_fingerprint(f=closing(box(0, 0, 1, 1))), + ) + described = get_definition(f=_uses_box)["values"]["f"]["globals"]["_BOX"] + self.assertIn("data", described) + + def test_docstrings(self): + """The docstrings of functions do not change fingerprints.""" + one = _function('def f(x):\n """One."""\n return x\n') + other = _function('def f(x):\n """Another."""\n return x\n') + changed = _function('def f(x):\n """One."""\n return x + 1\n') + self.assertEqual(get_fingerprint(f=one), get_fingerprint(f=other)) + self.assertNotEqual(get_fingerprint(f=one), get_fingerprint(f=changed)) + + def test_own_modules(self): + """Functions of modules that are not installed are described by code.""" + with tempfile.TemporaryDirectory() as directory: + Path(directory, "tatc_own_helpers.py").write_text( + "def helper(x):\n return x + 1\n", encoding="utf-8" + ) + sys.path.insert(0, directory) + try: + module = importlib.import_module("tatc_own_helpers") + calling = _function( + "def f(x):\n return helper(x)\n", helper=module.helper + ) + described = get_definition(f=calling)["values"]["f"]["globals"] + self.assertIn("code", described["helper"]) + # functions of installed modules by their names + installed = _function("def f(x):\n return isna(x)\n", isna=pd.isna) + described = get_definition(f=installed)["values"]["f"]["globals"] + self.assertEqual(set(described["isna"]), {"name"}) + finally: + sys.path.remove(directory) + sys.modules.pop("tatc_own_helpers", None) + + def test_own_module_attributes(self): + """Functions and values of a module of the study's own that a function + reaches through the module are described as globals.""" + with tempfile.TemporaryDirectory() as directory: + path = Path(directory, "tatc_own_attributes.py") + path.write_text( + "LIMIT = 2\n\ndef score(x):\n return x * 1\n", encoding="utf-8" + ) + sys.path.insert(0, directory) + try: + module = importlib.import_module("tatc_own_attributes") + calling = _function( + "def f(x):\n return helpers.score(x) + helpers.LIMIT\n", + helpers=module, + ) + before = get_fingerprint(f=calling) + described = get_definition(f=calling)["values"]["f"]["globals"] + self.assertEqual( + set(described["helpers"]["attributes"]), {"score", "LIMIT"} + ) + # (of another size, so that its compiled code is not reused) + path.write_text( + "LIMIT = 2\n\ndef score(x):\n return x * 20\n", encoding="utf-8" + ) + importlib.reload(module) + self.assertNotEqual(before, get_fingerprint(f=calling)) + finally: + sys.path.remove(directory) + sys.modules.pop("tatc_own_attributes", None) + + +class TestOwnClasses(unittest.TestCase): + """ + Unit tests for the descriptions of the classes and objects of a study's + own code. + """ + + def test_objects(self): + """Callable objects of the study's own classes are described by their + attributes and the code of their classes' methods.""" + + def classes(body): + namespace = {"__name__": "__main__"} + exec( # pylint: disable=exec-used + "class Score:\n" + " def __init__(self, k):\n" + " self.k = k\n" + " self.calls = []\n" + " def __call__(self, d):\n" + f" return {body}\n", + namespace, + ) + return namespace["Score"] + + score = classes("{'v': d.a * self.k}") + self.assertNotEqual(get_fingerprint(f=score(1)), get_fingerprint(f=score(3))) + self.assertEqual(get_fingerprint(f=score(1)), get_fingerprint(f=score(1))) + # mutable attributes (such as records of calls) are state, not described + counted = score(1) + counted.calls.append(1) + self.assertEqual(get_fingerprint(f=counted), get_fingerprint(f=score(1))) + # the code of the methods of the class + edited = classes("{'v': d.a + self.k}") + self.assertNotEqual(get_fingerprint(f=score(1)), get_fingerprint(f=edited(1))) + + +class _Described: + """An object that describes itself by what changes results.""" + + def __init__(self, value, calls=0): + self.value, self.calls = value, calls + + def __fingerprint__(self): + return {"value": self.value} + + +class TestSelfDescribed(unittest.TestCase): + """ + Unit tests for objects that describe themselves (by `__fingerprint__`), + such as designs and caches of satellites. + """ + + def test_hook(self): + """An object is described by what its `__fingerprint__` gives, not by + its other attributes.""" + self.assertEqual( + get_fingerprint(_Described(1)), get_fingerprint(_Described(1, calls=5)) + ) + self.assertNotEqual( + get_fingerprint(_Described(1)), get_fingerprint(_Described(2)) + ) + # the class is not described by the hook (it is not an object of it) + self.assertNotIn("fingerprint", get_definition(_Described)["values"]["0"]) + + def test_satellite_cache(self): + """A study whose function refers to a cache of satellites changes its + fingerprint with the cache's function, not with its use.""" + global SATELLITES # pylint: disable=global-statement + space = DesignSpace(n=Integer(1, 2)) + + def fingerprint_of(): + return Study(space, lambda d: [], _uses_satellites).fingerprint + + before = fingerprint_of() + SATELLITES([]) + SATELLITES.hits += 3 + self.assertEqual(fingerprint_of(), before) + try: + SATELLITES = _offset_cache(1.0) + self.assertNotEqual(fingerprint_of(), before) + finally: + SATELLITES = _offset_cache(0.0) + self.assertEqual(fingerprint_of(), before) + + def test_design(self): + """A design is described by its design space, decisions, replicate, + and scenario.""" + global BASE # pylint: disable=global-statement + space = DesignSpace(n=Integer(1, 2), u=Uncertain.uniform(0, 1)) + before = get_fingerprint(_uses_base) + try: + BASE = BASE.space.design({"n": 2}) + self.assertNotEqual(get_fingerprint(_uses_base), before) + finally: + BASE = BASE.space.design({"n": 1}) + self.assertEqual(get_fingerprint(_uses_base), before) + design = space.design({"n": 1}) + prints = { + get_fingerprint(design), + get_fingerprint(space.design({"n": 2})), + get_fingerprint(design.realize(0)), + get_fingerprint(design.realize(1)), + get_fingerprint(design.realize(0, overrides={"u": 0.5}, scenario="half")), + get_fingerprint(DesignSpace(n=Integer(1, 3)).design({"n": 1})), + } + self.assertEqual(len(prints), 6) + self.assertEqual( + get_fingerprint(design), get_fingerprint(space.design({"n": 1})) + ) + + def test_describe(self): + """A value is described as a definition describes it.""" + values = {"limit": 2.0, "names": ("a", "b")} + self.assertEqual(describe(values), get_definition(v=values)["values"]["v"]) + self.assertEqual(describe(values), {"limit": "2.0", "names": ["a", "b"]}) + + +class TestStale(unittest.TestCase): + """ + Unit tests for the results of the same study with other code. + """ + + def setUp(self): + self.older = {"values": {"f": {"code": "aa", "constants": [1], "names": []}}} + self.newer = {"values": {"f": {"code": "bb", "constants": [1], "names": []}}} + self.other = {"values": {"f": {"code": "bb", "constants": [2], "names": []}}} + + def test_stale(self): + """Definitions of the same values but other code are stale, in order, + with their numbers of results.""" + others = {"b": self.older, "c": self.other, "d": None, "a": self.older} + counts = {"a": 0, "b": 3, "c": 5, "d": 1} + # pylint: disable-next=protected-access + found = fingerprint._find_stale(self.newer, others, counts.__getitem__) + self.assertEqual(list(found.items()), [("b", 3), ("a", 0)]) + + def test_warn_stale(self): + """A warning names the stale results and the differences of the latest + of them, once if asked.""" + definitions = {"b": self.older} + with self.assertWarnsRegex( + UserWarning, r"^7 things with other code.*\(remove them\).*f\.code" + ): + warned = warn_stale( + {"a": 0, "b": 7}, + self.newer, + definitions.get, + lambda count: f"{count} things", + "remove them", + ) + self.assertTrue(warned) + with warnings.catch_warnings(): + warnings.simplefilter("error") + self.assertFalse( + warn_stale({"a": 0}, self.newer, definitions.get, str, "remove them") + ) + self.assertFalse( + warn_stale( + {"b": 7}, + self.newer, + definitions.get, + str, + "remove them", + once=lambda: False, + ) + ) diff --git a/tests/tradespace/test_layering.py b/tests/tradespace/test_layering.py new file mode 100644 index 0000000..8e5dbcb --- /dev/null +++ b/tests/tradespace/test_layering.py @@ -0,0 +1,129 @@ +""" +Unit tests for the structure of the trade space module: the general modules +of trade studies do not depend on those of constellations and missions, and +the modules import each other without cycles. + +@author Paul T. Grogan +""" + +import ast +import unittest +from pathlib import Path + +import tatc.tradespace + +PACKAGE = Path(tatc.tradespace.__file__).parent + +GENERAL = { + "alerts", + "attribution", + "comparison", + "confirmation", + "criteria", + "dominance", + "fingerprint", + "hashing", + "memory", + "nodes", + "optimization", + "pareto", + "plotting", + "references", + "refinement", + "scenarios", + "screening", + "sensitivity", + "space", + "statistics", + "store", + "study", + "summary", + "tables", + "utility", + "values", + "walks", +} +"""The modules of trade studies of any designs.""" + +MISSIONS = { + "cache", + "constellations", + "cost", + "deployment", + "events", + "expectations", + "failures", + "histories", + "mission", + "observations", + "plans", + "simulation", +} +"""The modules of constellations and their missions (and the caches of their +satellites), which may import the general modules.""" + + +def _imports(path: Path) -> set[str]: + """ + Gets the modules of the package that a module imports when it runs (at + the top or within functions, not only for type checking). + """ + found: set[str] = set() + + def visit(node: ast.AST) -> None: + if ( + isinstance(node, ast.If) + and getattr(node.test, "id", None) == "TYPE_CHECKING" + ): + return + if isinstance(node, ast.ImportFrom) and node.level == 1 and node.module: + found.add(node.module.split(".")[0]) + elif isinstance(node, ast.ImportFrom) and node.level == 1: + found.update(alias.name for alias in node.names) + for child in ast.iter_child_nodes(node): + visit(child) + + visit(ast.parse(path.read_text(encoding="utf-8"))) + return found + + +class TestLayering(unittest.TestCase): + """ + Unit tests for the dependencies between the modules of trade studies. + """ + + def setUp(self): + self.modules = { + path.stem: _imports(path) + for path in PACKAGE.glob("*.py") + if path.stem != "__init__" + } + + def test_classified(self): + """Every module is either general or of constellations and missions.""" + self.assertEqual(GENERAL & MISSIONS, set()) + self.assertEqual(GENERAL | MISSIONS, set(self.modules)) + + def test_general_modules(self): + """General modules do not import those of constellations and missions.""" + self.assertLessEqual(GENERAL, set(self.modules)) + for module in sorted(GENERAL): + with self.subTest(module=module): + self.assertLessEqual(self.modules[module], GENERAL) + + def test_no_cycles(self): + """Modules import each other without cycles.""" + state: dict[str, str] = {} + + def visit(module: str, path: list[str]) -> None: + if state.get(module) == "done": + return + if state.get(module) == "visiting": + self.fail(f"import cycle: {' -> '.join(path + [module])}") + state[module] = "visiting" + for imported in sorted(self.modules.get(module, ())): + visit(imported, path + [module]) + state[module] = "done" + + for module in sorted(self.modules): + visit(module, []) diff --git a/tests/tradespace/test_observations.py b/tests/tradespace/test_observations.py new file mode 100644 index 0000000..712eb03 --- /dev/null +++ b/tests/tradespace/test_observations.py @@ -0,0 +1,1084 @@ +""" +Unit tests for studies of the observations of constellations. + +@author Paul T. Grogan +""" + +# pylint: disable=protected-access + +import dataclasses +import importlib.util +import math +import pickle +import tempfile +import unittest +import warnings +from datetime import datetime, timedelta, timezone +from functools import partial +from pathlib import Path +from unittest import mock + +import numpy as np +import pandas as pd + +from tatc.analysis import collect_observations +from tatc.generation import generate_points_fibonacci_lattice +from tatc.schemas import Instrument +from tatc.tradespace import ( + Categorical, + Component, + CostModel, + DeploymentSchedule, + DesignSpace, + Exponential, + FailureModel, + Failures, + Fixed, + Integer, + LaunchCost, + MissionPlan, + ObservationStudy, + Observations, + Probability, + Quantile, + Real, + Requirement, + RestorationPolicy, + SatelliteCache, + SatelliteCost, + Stage, + StandardDeviation, + Study, + Targets, + Triangular, + Uncertain, + build_constellation, + count_planes, + count_satellites, + policy_space, + risk_space, + walker_space, +) +from tatc.tradespace.expectations import exact_expectations +from tatc.tradespace.fingerprint import get_fingerprint +from tatc.tradespace.histories import summarize_histories +from tatc.tradespace.mission import summarize_phases +from tatc.tradespace import configure + +HAS_JOBLIB = importlib.util.find_spec("joblib") is not None + +START = datetime(2026, 7, 1, tzinfo=timezone.utc) +HOURS = timedelta(hours=3) +N_POINTS = 20 +SPACE = DesignSpace( + altitude=Real(600e3, 700e3, step=100e3), + layout=walker_space(inclination=60, planes=Integer(1, 2), per_plane=Integer(1, 2)), + growth=Uncertain.uniform(1.0, 1.5), + points_seed=Uncertain.seed(), + failure_seed=Uncertain.seed(), +) +TARGETS = Targets( + generate_points_fibonacci_lattice, count=N_POINTS, rotate=True, seed="points_seed" +) +SCHEDULE = DeploymentSchedule(years=3, production_rate=4, launch_interval=0.5) +COSTS = CostModel(SatelliteCost(development=10, first_unit=2)) +PLAN = MissionPlan(SCHEDULE, COSTS, growth={"development": "growth"}) +FAILURES = FailureModel(life=Exponential(0.2)) +DEGRADE = dataclasses.replace(PLAN, policy=RestorationPolicy(restore=False)) + + +def _build(d): + imager = Instrument(name="imager", field_of_regard=60) + return build_constellation(d.layout, imager, epoch=START, altitude=d.altitude) + + +def _metrics(observations): + """The share (%) of the points observed.""" + if len(observations) == 0: + return {"observed": 0.0} + return {"observed": 100 * observations.target_hash.nunique() / N_POINTS} + + +def _observations(directory=None): + return Observations(TARGETS, START, HOURS, directory=directory) + + +def _grid(count, seed=None): + """Targets at the equator, of a seed (which a replicate draws).""" + del seed + return pd.DataFrame({"latitude": [0.0] * count, "longitude": range(count)}) + + +class TestTargets(unittest.TestCase): + """ + Unit tests for the targets of observations. + """ + + def test_generated(self): + """Targets generated from a seed of the design differ by replicate.""" + design = SPACE.enumerate()[0] + first, second = design.realize(0), design.realize(1) + targets = TARGETS._of(first) + pd.testing.assert_frame_equal( + targets, + generate_points_fibonacci_lattice( + count=N_POINTS, rotate=True, seed=first.points_seed + ), + ) + self.assertIs(TARGETS._of(first), targets) # kept in memory + self.assertFalse(TARGETS._of(second).equals(targets)) + self.assertEqual(pickle.loads(pickle.dumps(TARGETS))._memory, {}) + with self.assertRaises(ValueError): + TARGETS._of() + + def test_fixed(self): + """Fixed targets are the same in every replicate.""" + points = generate_points_fibonacci_lattice(count=5, rotate=True, seed=1) + targets = Targets(points) + self.assertIs(targets._of(), points) + self.assertIsNone(targets._seed_of(None)) + same = Targets(generate_points_fibonacci_lattice, count=5, rotate=True) + self.assertTrue(same._of().equals(same._of())) + with self.assertRaises(ValueError): + Targets(points, seed="points_seed") + with self.assertRaises(TypeError): + Targets([1, 2]) + + def test_fixed_seed(self): + """An integer seed generates the same targets in every replicate.""" + design = SPACE.enumerate()[0] + first, second = design.realize(0), design.realize(1) + targets = Targets( + generate_points_fibonacci_lattice, count=N_POINTS, rotate=True, seed=7 + ) + expected = generate_points_fibonacci_lattice( + count=N_POINTS, rotate=True, seed=7 + ) + pd.testing.assert_frame_equal(targets._of(first), expected) + self.assertIs(targets._of(second), targets._of(first)) + self.assertEqual(targets._seed_of(None), 7) + pd.testing.assert_frame_equal(targets._of(), expected) + # observations of a fixed seed need no design + observations = Observations(targets, START, HOURS) + satellites = _build(first) + pd.testing.assert_frame_equal( + observations(satellites), observations(satellites, second) + ) + + def test_invalid_seeds(self): + """A seed is a reference, an integer, or None.""" + for seed in (7.5, True, [1], timedelta(hours=1)): + with self.assertRaisesRegex(TypeError, "seed of targets"): + Targets(generate_points_fibonacci_lattice, count=5, seed=seed) + Targets(generate_points_fibonacci_lattice, count=5, seed=np.int64(3)) + Targets(generate_points_fibonacci_lattice, count=5, seed=lambda d: 3) + + +class TestObservations(unittest.TestCase): + """ + Unit tests for the observations of targets. + """ + + def test_matches_analysis(self): + """The observations are those of the analysis of the targets.""" + d = SPACE.enumerate()[3].realize(0) + satellites = _build(d) + observations = _observations()(satellites, d) + direct = collect_observations(TARGETS._of(d), satellites, START, START + HOURS) + columns = ["target_hash", "satellite", "epoch"] + pd.testing.assert_frame_equal( + observations.sort_values(columns, ignore_index=True)[direct.columns], + direct.sort_values(columns, ignore_index=True), + ) + self.assertEqual(_observations()._context_of(d), (d.points_seed, START, HOURS)) + + def test_disk_cache(self): + """Observations on disk are kept by the seed of the targets and the period.""" + designs = [d.realize(r) for d in SPACE.enumerate()[:2] for r in (0, 1)] + with tempfile.TemporaryDirectory() as directory: + observations = _observations(directory) + for d in designs: + observations(_build(d), d) + namespaces = sorted( + (p / "namespace.txt").read_text() for p in Path(directory).iterdir() + ) + self.assertEqual(len(namespaces), 2) # the targets of two replicates + self.assertTrue(all("targets of seed" in n for n in namespaces)) + again = _observations(directory) + again(_build(designs[0]), designs[0]) + self.assertEqual(again._cache_of(designs[0]).misses, 0) + + def test_targets_generated_when_needed(self): + """Caches on disk of generated targets are keyed by their recipe and + seed, so that opening (and pruning) them generates no targets, nor do + results on disk.""" + designs = [d.realize(r) for d in SPACE.enumerate()[:1] for r in (0, 1)] + original = Targets._of_seed # pylint: disable=protected-access + with ( + tempfile.TemporaryDirectory() as directory, + mock.patch.object( + Targets, "_of_seed", autospec=True, side_effect=original + ) as generated, + ): + first = _observations(directory) + for d in designs: + first(_build(d)[:1], d) + self.assertEqual(generated.call_count, len(designs)) + generated.reset_mock() + again = _observations(directory) + self.assertEqual(again.prune(), 0) + again(_build(designs[0])[:1], designs[0]) # from the results on disk + generated.assert_not_called() + self.assertEqual( + sorted(SatelliteCache._contexts(directory).values()), + sorted((d.points_seed, START) for d in designs), + ) + # the fingerprint of a cache follows the recipe of the targets (their + # function and its arguments), not the targets kept in memory + d = designs[0] + + def fingerprint(targets): + return get_fingerprint( + Observations(targets, START, HOURS)._cache_of(d).function + ) + + fresh = Targets(_grid, 5, seed="points_seed") + recipes = [fresh, Targets(_grid, 6, seed="points_seed"), TARGETS] + prints = [fingerprint(targets) for targets in recipes] + self.assertEqual(len(set(prints)), 3) + fresh._of(d) + self.assertEqual(fingerprint(fresh), prints[0]) + + def test_directory_not_in_fingerprint(self): + """The directory of a cache does not change the fingerprint of a study.""" + prints = { + ObservationStudy( + SPACE, _build, _observations(directory), _metrics + ).fingerprint + for directory in (None, "a", "b") + } + self.assertEqual(len(prints), 1) + other = Observations(TARGETS, START, 2 * HOURS) + self.assertNotIn( + ObservationStudy(SPACE, _build, other, _metrics).fingerprint, prints + ) + + +class TestObservationStudy(unittest.TestCase): + """ + Unit tests for studies of observations. + """ + + def test_matches_study(self): + """A study of observations matches a study of the same parts.""" + designs = SPACE.enumerate() + + def evaluate(satellites, design): + deployment = SCHEDULE.plan(design.layout) + observations = collect_observations( + TARGETS._of(design), satellites, START, START + HOURS + ) + return { + "satellites": len(satellites), + "planes": count_planes(design.layout), + **COSTS.estimate(deployment, {"development": design.growth}).metrics(), + **_metrics(observations), + } + + plain = Study(SPACE, _build, evaluate, replicates=2).run(designs) + study = ObservationStudy( + SPACE, + _build, + _observations(), + _metrics, + layout="layout", + plan=PLAN, + replicates=2, + ) + results = study.run(designs) + columns = [c for c in plain.columns if c != "seconds"] + pd.testing.assert_frame_equal(results[columns], plain[columns]) + # the parts of a design, for other analyses + d = designs[3] + self.assertEqual(len(study.satellites_of(d, 1)), count_satellites(d.layout)) + self.assertEqual(len(study.targets_of(d, 1)), N_POINTS) + self.assertGreater(len(study.observations_of(d, 1)), 0) + + def test_phases_and_failures(self): + """Studies summarize phases, or the histories of failures.""" + designs = SPACE.enumerate()[:2] + phased = ObservationStudy( + SPACE, + _build, + _observations(), + _metrics, + layout="layout", + plan=PLAN, + phases=[Requirement("observed", ">=", 50)], + ).run(designs) + self.assertIn("observed mission", phased) + self.assertIn("observed time", phased) + # the years by which the plan deploys every satellite + planned = [SCHEDULE.plan(d.layout).deployed for d in designs for _ in range(1)] + self.assertEqual(list(phased.deployed), planned) + failures = Failures(FAILURES, histories=4, seed="failure_seed") + degraded = ObservationStudy( + SPACE, + _build, + _observations(), + _metrics, + layout="layout", + plan=DEGRADE, + failures=failures, + ).run(designs) + self.assertTrue({"observed mission", "availability", "cost"} <= set(degraded)) + # the policy of each design: by default, its values `policy` + trade = DesignSpace( + **SPACE.children, policy=policy_space(orbit_spares=Integer(0, 1)) + ) + restored = ObservationStudy( + trade, _build, _observations(), _metrics, plan=PLAN, failures=failures + ).run(trade.enumerate()[:4]) + self.assertTrue(restored.feasible.all()) + spares = restored.groupby("policy.orbit_spares")["cost production"].mean() + self.assertGreater(spares[1], spares[0]) + + def test_scenarios(self): + """Metrics given the design read the values of scenarios, also of the + phases of missions (cached by scenario).""" + + def observed_at(observations, design): + """The share (%) of the points observed at least a number of times.""" + if len(observations) == 0: + return {"observed": 0.0} + counts = observations.groupby("target_hash").size() + return {"observed": 100 * (counts >= design.times).sum() / N_POINTS} + + def space(times): + return DesignSpace(**SPACE.children, times=times) + + def study(times, **options): + return ObservationStudy( + space(times), + _build, + _observations(), + observed_at, + layout="layout", + plan=DEGRADE, + failures=Failures(FAILURES, histories=4, seed="failure_seed"), + replicates=2, + **options, + ) + + scenarios = {"once": {}, "twice": {"times": 2}} + both = study(1, scenarios=scenarios).run(space(1).enumerate()) + columns = ["observed", "observed mission", "availability", "cost"] + once = both[both.scenario == "once"].reset_index(drop=True) + twice = both[both.scenario == "twice"].reset_index(drop=True) + self.assertTrue((once.observed >= twice.observed).all()) + self.assertTrue((once["observed mission"] > twice["observed mission"]).any()) + # as studies with the values of the scenarios + for times, expected in ((1, once), (2, twice)): + alone = study(times).run(space(times).enumerate()) + pd.testing.assert_frame_equal( + alone[columns], expected[columns], check_names=False + ) + + def test_epoch(self): + """The period may start at an epoch of the design, such as one drawn for + each replicate, whose observations are those of the period at that epoch.""" + later = START + timedelta(days=100) + space = DesignSpace(**SPACE.children, epoch=Uncertain.choice([START, later])) + observations = Observations(TARGETS, "epoch", HOURS) + design = space.enumerate()[3] + realized = {} + for replicate in range(10): + d = design.realize(replicate) + realized.setdefault(d.epoch, d) + self.assertEqual(set(realized), {START, later}) + for epoch, d in realized.items(): + self.assertEqual(observations.start_of(d), epoch) + self.assertEqual(observations.end_of(d), epoch + HOURS) + self.assertEqual(observations._context_of(d)[1], epoch) + satellites = _build(d) + fixed = Observations(TARGETS, epoch, HOURS)(satellites, d) + pd.testing.assert_frame_equal(observations(satellites, d), fixed) + satellites = _build(realized[START]) + self.assertFalse( + observations(satellites, realized[START]).equals( + observations(satellites, realized[later]) + ) + ) + with self.assertRaises(ValueError): + observations.start_of(None) + self.assertEqual(Observations(TARGETS, START, HOURS).end_of(), START + HOURS) + # a study with an epoch drawn for each replicate + results = ObservationStudy( + space, _build, observations, _metrics, layout="layout", replicates=4 + ).run(space.enumerate()[:2]) + self.assertEqual(set(results.epoch), {START, later}) + + def test_sizing(self): + """Plans size the schedule and costs of each design by its values, and + limit launches by the masses of the plan.""" + designs = [d for d in SPACE.enumerate() if d.layout.per_plane == 2] + + def cost_model(d): + """Satellites that cost more to develop higher (an illustrative relationship).""" + development = 10 * d.altitude / 600e3 + return CostModel( + SatelliteCost(development=development, first_unit=2), + launch=LaunchCost(per_launch=1), + ) + + def schedule(d): + """Launches that lift two satellites to 600 km, and one to 700 km.""" + capacity = 250.0 if d.altitude < 650e3 else 150.0 + return dataclasses.replace(SCHEDULE, launch_mass_capacity=capacity) + + def study(plan): + return ObservationStudy( + SPACE, _build, _observations(), _metrics, layout="layout", plan=plan + ) + + results = study(MissionPlan(schedule, cost_model, masses=100.0)).run(designs) + by_altitude = results.groupby("altitude")[["cost development", "cost launch"]] + means = by_altitude.mean() + self.assertAlmostEqual( + means.loc[700e3, "cost development"] / means.loc[600e3, "cost development"], + 7 / 6, + ) + # a launch of each plane at 600 km, and of each satellite at 700 km + planes = results.groupby("altitude")["planes"].mean() + self.assertAlmostEqual(means.loc[600e3, "cost launch"], planes[600e3]) + self.assertAlmostEqual(means.loc[700e3, "cost launch"], 2 * planes[700e3]) + # masses of each design (a reference to its values) + light = study(MissionPlan(schedule, cost_model, masses=lambda d: 50.0)) + light = light.run(designs) + self.assertAlmostEqual( + light.groupby("altitude")["cost launch"].mean()[700e3], planes[700e3] + ) + + def test_cost_risk(self): + """Plans draw the growth of the components of each design from its + scores, and resolve growth by type of satellite.""" + growth = Triangular(0.9, 1.5) + model = CostModel( + SatelliteCost( + components=[Component("imager", development=10, growth=growth)] + ), + correlation=0.5, + ) + space = SPACE.extend(cost_risk=risk_space(model)) + designs = [d for d in space.enumerate() if d.layout.per_plane == 2] + + def study(plan): + return ObservationStudy( + space, + _build, + _observations(), + _metrics, + layout="layout", + plan=plan, + replicates=2, + ) + + results = study(MissionPlan(SCHEDULE, model, scores="cost_risk")).run(designs) + score = math.sqrt(0.5) * ( + results["cost_risk.common"] + results["cost_risk.imager"] + ) + probability = 0.5 * (1 + score.map(lambda z: math.erf(z / math.sqrt(2)))) + expected = 10 * probability.map(growth.ppf) + pd.testing.assert_series_equal( + results["cost development"], expected, check_names=False + ) + # designs of a replicate share the growth (common random numbers) + self.assertEqual( + results.groupby("replicate")["cost development"].nunique().max(), 1 + ) + # without scores, the expected growth + nominal = study(MissionPlan(SCHEDULE, model)).run(designs) + self.assertTrue((nominal["cost development"] == 10 * growth.mean()).all()) + # growth by type of satellite resolves the values of the design + plan = MissionPlan( + SCHEDULE, model, growth={"development": {"a": "growth", "b": np.int64(2)}} + ) + design = designs[0].realize(0) + self.assertEqual( + plan._growth_of(design), {"development": {"a": design.growth, "b": 2}} + ) + # scores of a group nested in another + nested = SPACE.extend(risk=DesignSpace(cost_risk=risk_space(model))) + design = nested.enumerate()[0].realize(3) + plan = MissionPlan(SCHEDULE, model, scores="risk.cost_risk") + self.assertEqual(plan._cost_model_of(design), model.draw(design.risk.cost_risk)) + + def test_stages(self): + """Plans stage the deployments of designs that decide to.""" + space = DesignSpace(**SPACE.children, staged=Categorical([False, True])) + designs = [d for d in space.enumerate() if d.layout.planes == 2] + + def stages(design): + """A second plane, never deployed, for a staged design.""" + return [Stage(1, 1.0, lambda decision: False)] if design.staged else [] + + plan = MissionPlan( + SCHEDULE, COSTS, growth={"development": "growth"}, stages=stages + ) + options = {"layout": "layout", "plan": plan, "replicates": 2} + phased = ObservationStudy( + space, + _build, + _observations(), + _metrics, + phases=[Requirement("observed", ">=", 50)], + **options, + ).run(designs) + means = phased.groupby("staged")[["observed mission", "cost"]].mean() + self.assertLess( + means.loc[True, "observed mission"], means.loc[False, "observed mission"] + ) + self.assertLess(means.loc[True, "cost"], means.loc[False, "cost"]) + # the stages deployed, and when the first generation is deployed + staged = phased.groupby("staged")[["stages deployed", "deployed"]].mean() + self.assertEqual(staged.loc[True, "stages deployed"], 0.0) + self.assertTrue(np.isnan(staged.loc[False, "stages deployed"])) # no stages + self.assertLess(staged.loc[True, "deployed"], staged.loc[False, "deployed"]) + # failures without restoration: histories are sampled rather than exact + failures = Failures(FAILURES, seed="failure_seed", histories=4) + options["plan"] = dataclasses.replace( + plan, policy=RestorationPolicy(restore=False) + ) + degraded = ObservationStudy( + space, _build, _observations(), _metrics, failures=failures, **options + ).run(designs) + self.assertTrue(degraded.feasible.all()) + self.assertTrue(any("stages deployed" in column for column in degraded)) + + def test_capability_rules(self): + """Rules of stages read the capability of the satellites operating at a + decision, by the study's metrics, in phases and in histories.""" + stagings = ["delayed", "measured", "never", "never measured"] + space = DesignSpace(**SPACE.children, staging=Categorical(stagings)) + + def stages(design): + """A second plane deployed at the first launch, if a rule decides to.""" + rules = { + "delayed": None, + "measured": lambda decision: decision.capability["observed"] <= 100, + "never": lambda decision: False, + "never measured": lambda decision: decision.capability["observed"] < 0, + } + return [Stage(1, 0.0, rules[design.staging])] + + designs = [ + d + for d in space.enumerate() + if d.layout.planes == 2 and d.layout.per_plane == 1 + ] + plan = MissionPlan( + SCHEDULE, COSTS, stages=stages, policy=RestorationPolicy(restore=False) + ) + options = {"layout": "layout", "plan": plan, "replicates": 2} + failures = Failures(FAILURES, histories=4, seed="failure_seed") + for summary in ({"phases": True}, {"failures": failures}): + with self.subTest(summary=list(summary)): + results = ObservationStudy( + space, _build, _observations(), _metrics, **options, **summary + ).run(designs) + means = results.groupby("staging")[["observed mission", "cost"]].mean() + pd.testing.assert_series_equal( + means.loc["measured"], means.loc["delayed"], check_names=False + ) + pd.testing.assert_series_equal( + means.loc["never measured"], means.loc["never"], check_names=False + ) + self.assertLess( + means.loc["never", "cost"], means.loc["delayed", "cost"] + ) + + def test_metrics_of_uncertain_values(self): + """The metrics of phases that read uncertain values of the design are + those of its replicate, and shared by the designs of a replicate.""" + space = SPACE.extend(u=Uncertain.uniform(0, 1)) + fixed = Targets( + generate_points_fibonacci_lattice(count=N_POINTS, rotate=True, seed=1) + ) + + def metric(observations, design): + del observations + return {"m": design.u} + + study = ObservationStudy( + space, + _build, + Observations(fixed, START, HOURS), + metric, + plan=PLAN, + phases=True, + replicates=3, + ) + designs = space.enumerate()[:2] + results = study.run(designs) + self.assertEqual(results.u.nunique(), 3) + np.testing.assert_allclose(results["m mission"], results["m"]) + # with common random numbers, the designs of a replicate share a context + first, second = (study.realize(d, 1) for d in designs) + evaluation = study.evaluate + self.assertEqual(evaluation.context_of(first), evaluation.context_of(second)) + other = study.realize(designs[0], 2) + self.assertNotEqual(evaluation.context_of(first), evaluation.context_of(other)) + # metrics not given the design are cached by the observations alone + plain = study.replace(metrics=_metrics).evaluate + self.assertEqual(plain.context_of(first), plain.context_of(other)) + + def test_references(self): + """Every part of a plan may refer to a value of the design, by name or + by a function of the design.""" + space = SPACE.extend( + staging=Fixed((Stage(1, 1.0),)), schedule=Fixed(SCHEDULE), mass=Fixed(5.0) + ) + design = [d for d in space.enumerate() if d.layout.planes == 2][0] + plan = MissionPlan("schedule", lambda d: COSTS, stages="staging", masses="mass") + study = ObservationStudy(space, _build, _observations(), _metrics, plan=plan) + mission = study.mission_of(design) + self.assertEqual(mission.deployment.stages, (Stage(1, 1.0),)) + self.assertEqual(mission.deployment.masses, {None: 5.0}) + self.assertIs(mission.deployment.schedule, SCHEDULE) + self.assertEqual(mission.cost_model, COSTS) + + def test_staging_recorded(self): + """Studies record the stages that rules deploy (without failures), and + when the first generation is deployed, with them.""" + space = DesignSpace(**SPACE.children, go=Categorical([False, True])) + designs = [ + d + for d in space.enumerate() + if d.layout.planes == 2 and d.layout.per_plane == 1 + ] + plan = MissionPlan( + SCHEDULE, COSTS, stages=lambda d: [Stage(1, 1.0, lambda _: d.go)] + ) + study = ObservationStudy( + space, _build, _observations(), _metrics, plan=plan, phases=True + ) + results = study.run(designs) + means = results.groupby("go")[["stages deployed", "deployed"]].mean() + self.assertEqual(list(means["stages deployed"]), [0.0, 1.0]) + # the first plane launched at 0.25, the second produced from the + # decision a year later, and launched at 1.5 + self.assertEqual(list(means["deployed"]), [0.25, 1.5]) + + def test_metrics_of_every_satellite_once(self): + """With a plan, the metrics of every satellite are those of the last + phase of the mission, evaluated once.""" + calls = [] + + def metrics(observations): + if len(observations) > 0: + calls.append(frozenset(observations.satellite)) + return _metrics(observations) + + design = SPACE.enumerate()[3] + study = ObservationStudy( + SPACE, _build, _observations(), metrics, plan=PLAN, phases=True + ) + result = study.run([design]).iloc[0] + self.assertEqual(len(calls), len(set(calls))) + satellites = study.satellites_of(design) + observed = study.observations_of(design) + self.assertEqual(result["observed"], _metrics(observed)["observed"]) + self.assertIn(frozenset(s.name for s in satellites), calls) + + def test_spares_of_the_policy(self): + """The policy of each design gives its spares, which are produced + whether or not the study has failures.""" + designs = [d for d in SPACE.enumerate() if d.altitude == 600e3] + + def study(policy): + plan = dataclasses.replace(PLAN, policy=policy) + return ObservationStudy( + SPACE, _build, _observations(), _metrics, plan=plan, phases=True + ) + + plain = study(RestorationPolicy()).run(designs) + spared = study(RestorationPolicy(orbit_spares=1, ground_spares=1)) + results = spared.run(designs) + # a spare in orbit in each plane and one on the ground, of 2 each + np.testing.assert_allclose( + results["cost production"] - plain["cost production"], + 2 * (plain.planes + 1), + ) + # (whose production delays the deployment of the planes) + self.assertTrue( + (results["observed mission"] <= plain["observed mission"]).all() + ) + self.assertTrue((results["deployed"] >= plain["deployed"]).all()) + mission = spared.mission_of(designs[-1]) + self.assertEqual({p.orbit_spares for p in mission.deployment.planes}, {1}) + # a policy of each design (or type), from its values + by_type = study(lambda d: RestorationPolicy(orbit_spares={None: 2})) + mission = by_type.mission_of(designs[-1]) + self.assertEqual({p.orbit_spares for p in mission.deployment.planes}, {2}) + with self.assertRaises(TypeError): + study(lambda d: "spares").run(designs[:1]) + # a group of values that configures the default policy, or a base one + space = SPACE.extend(policy=policy_space(restore=True, orbit_spares=1)) + realized = space.enumerate()[0].realize(0) + named = dataclasses.replace(PLAN, policy="policy")._policy_of(realized) + self.assertEqual(named, RestorationPolicy(orbit_spares=1)) + base = RestorationPolicy(drift_years=1.0) + configured = dataclasses.replace( + PLAN, policy=lambda d: configure(base, d.policy) + )._policy_of(realized) + self.assertEqual(configured, RestorationPolicy(orbit_spares=1, drift_years=1.0)) + # by default, the design's values `policy`, which must configure a + # policy (others need a function that gives it), or else none + self.assertEqual(PLAN._policy_of(realized), RestorationPolicy(orbit_spares=1)) + other = SPACE.extend(policy=Categorical(["a", "b"])).enumerate()[0] + with self.assertRaisesRegex(TypeError, "policy= a function"): + PLAN._policy_of(other.realize(0)) + unset = SPACE.extend(policy=Fixed(None)).enumerate()[0] + self.assertEqual(PLAN._policy_of(unset.realize(0)), RestorationPolicy()) + self.assertEqual(PLAN._policy_of(designs[0].realize(0)), RestorationPolicy()) + + def test_failure_times(self): + """Failures give each history the time until it meets requirements on + its phases, summarized over the histories.""" + failures = Failures( + FAILURES, + seed="failure_seed", + histories=6, + statistics=[ + Quantile("observed time", 0.5), + Probability("observed time", "<=", 1), + ], + ) + phased = ObservationStudy( + SPACE, + _build, + _observations(), + _metrics, + plan=PLAN, + phases=[Requirement("observed", ">=", 50)], + ) + study = phased.replace(failures=failures) # the requirements of the study + design = SPACE.enumerate()[3] + result = study.run([design]).iloc[0] + histories = study.mission_of(design).histories() + self.assertIn("observed time", histories) + summary = summarize_histories(histories, statistics=failures.statistics) + for column in ( + "observed time", + "observed time histories p50", + "P(observed time <= 1) histories", + ): + self.assertEqual(result[column], summary[column]) + self.assertAlmostEqual( + result["P(observed time <= 1) histories"], + (histories["observed time"] <= 1).mean(), + ) + + def test_failure_validation(self): + """Failures are validated as they are made, and quantiles of costs need a + cost model.""" + for invalid in ( + {"sampling": "antithetic"}, + {"stress": 0.0}, + {"histories": 0}, + {"control_histories": 0}, + {"seed": None}, + ): + with self.subTest(invalid=invalid): + with self.assertRaises(ValueError): + Failures(FAILURES, **{"seed": "failure_seed", **invalid}) + with self.assertRaises(TypeError): + Failures(FAILURES) # pylint: disable=missing-kwoa + with self.assertRaises(TypeError): + Failures( + FAILURES, seed="failure_seed", statistics=[Requirement("x", ">", 1)] + ) + with self.assertRaises(TypeError): + ObservationStudy( + SPACE, _build, _observations(), _metrics, plan=PLAN, phases=["x"] + ) + with self.assertRaisesRegex(ValueError, "cost model"): + ObservationStudy( + SPACE, + _build, + _observations(), + _metrics, + plan=MissionPlan(SCHEDULE), + failures=Failures( + FAILURES, seed="failure_seed", statistics=[Quantile("cost", 0.7)] + ), + ) + # quantiles of other columns that the histories do not have + study = ObservationStudy( + SPACE, + _build, + _observations(), + _metrics, + plan=PLAN, + failures=Failures( + FAILURES, seed="failure_seed", statistics=[Quantile("other", 0.5)] + ), + ) + with self.assertRaisesRegex(ValueError, "other"): + study.run(SPACE.enumerate()[:1]) + + def test_replace(self): + """Variants of an observation study replace its arguments.""" + study = ObservationStudy(SPACE, _build, _observations(), _metrics) + phased = study.replace(layout="layout", plan=PLAN, phases=True) + self.assertEqual(phased.phases, ()) + self.assertIs(phased.build, study.build) + self.assertIs(phased.observations, study.observations) + results = phased.replace(replicates=2).run(SPACE.enumerate()[:1]) + self.assertEqual(len(results), 2) + self.assertIn("observed mission", results) + with self.assertRaises(TypeError): + study.replace(evaluate=_metrics) + + def test_invalid(self): + """Failures and phases need a plan, and a plan needs a layout (by + default, the value `layout` of the design space).""" + observations = _observations() + with self.assertRaises(ValueError): + ObservationStudy(SPACE, _build, observations, _metrics, phases=True) + # one requirement on the phases of each metric + with self.assertRaisesRegex(ValueError, r"metrics \['observed'\]"): + ObservationStudy( + SPACE, + _build, + observations, + _metrics, + plan=PLAN, + phases=[ + Requirement("observed", ">=", 50), + Requirement("observed", ">=", 80), + ], + ) + study = ObservationStudy(SPACE, _build, observations, _metrics, plan=PLAN) + self.assertEqual(study.layout, "layout") + shells = DesignSpace( + altitude=SPACE.children["altitude"], shell=SPACE.children["layout"] + ) + with self.assertRaises(ValueError): + ObservationStudy(shells, _build, observations, _metrics, plan=PLAN) + with self.assertRaises(ValueError): + ObservationStudy( + SPACE, + _build, + observations, + _metrics, + failures=Failures(FAILURES, seed="failure_seed"), + ) + + @unittest.skipUnless(HAS_JOBLIB, "requires joblib") + def test_parallel(self): + """Studies of observations run in parallel, with a cache on disk.""" + designs = SPACE.enumerate() + with tempfile.TemporaryDirectory() as directory: + study = partial( + ObservationStudy, + SPACE, + _build, + _observations(directory), + _metrics, + layout="layout", + replicates=2, + ) + serial = study().run(designs) + parallel = study(n_jobs=2).run(designs) + columns = [c for c in serial.columns if c != "seconds"] + pd.testing.assert_frame_equal(serial[columns], parallel[columns]) + + +class TestOneDesign(unittest.TestCase): + """ + Unit tests for the parts of the evaluations of one design. + """ + + def setUp(self): + self.study = ObservationStudy( + SPACE, + _build, + _observations(), + _metrics, + layout="layout", + plan=PLAN, + phases=True, + replicates=2, + ) + self.design = SPACE.enumerate()[3] + + def test_mission(self): + """The deployment, phases, and costs of a design are its evaluation's.""" + result = self.study.run([self.design]).iloc[1] + realized = self.study.realize(self.design, 1) + mission = self.study.mission_of(self.design, 1) + self.assertIs(mission.design.decisions, realized.decisions) + self.assertEqual(mission.design.growth, realized.growth) + deployment = mission.deployment + self.assertEqual(deployment.planes, SCHEDULE.plan(realized.layout).planes) + self.assertIs(mission.capability, deployment.capability) + phases = mission.phases() + self.assertAlmostEqual( + summarize_phases(phases)["observed mission"], result["observed mission"] + ) + self.assertAlmostEqual(mission.estimate().total, result["cost"]) + self.assertEqual(deployment.planned().deployed, result["deployed"]) + self.assertIs(deployment.planned(), deployment.planned()) + self.assertEqual(deployment.policy, RestorationPolicy()) + with self.assertRaisesRegex(ValueError, "failures"): + mission.histories() + unplanned = self.study.replace(plan=None, phases=None) + with self.assertRaisesRegex(ValueError, "plan"): + unplanned.mission_of(self.design) + + def test_realize(self): + """A study realizes designs with its seed, and in its scenarios.""" + self.assertEqual( + self.study.realize(self.design, 1).growth, self.design.realize(1).growth + ) + self.assertNotEqual( + self.study.replace(seed=3).realize(self.design, 1).growth, + self.design.realize(1).growth, + ) + slow = self.study.replace(scenarios={"slow": {"growth": 1.2}}) + self.assertEqual(slow.realize(self.design, 1, "slow").growth, 1.2) + self.assertEqual( + slow.satellites_of(self.design, 1, "slow"), + slow.satellites_of(self.design, 1), + ) + with self.assertRaises(KeyError): + slow.realize(self.design, 1, "fast") + + def test_prune(self): + """Observations remove their caches' results of the analysis with other + code, and keep those of other observations.""" + + def analysis(source): + namespace = {"collect_observations": collect_observations} + exec(source, namespace) # pylint: disable=exec-used + return namespace["analysis"] + + plain = analysis( + "def analysis(targets, satellite, start, end):\n" + " return collect_observations(targets, satellite, start, end)\n" + ) + edited = analysis( + "def analysis(targets, satellite, start, end):\n" + " found = collect_observations(targets, satellite, start, end)\n" + " return found\n" + ) + more = Targets( + generate_points_fibonacci_lattice, + count=N_POINTS + 5, + rotate=True, + seed="points_seed", + ) + with tempfile.TemporaryDirectory() as directory: + first = Observations(TARGETS, START, HOURS, plain, directory=directory) + others = Observations(more, START, HOURS, plain, directory=directory) + latest = Observations(TARGETS, START, HOURS, edited, directory=directory) + realized = self.design.realize(0) + satellites = _build(realized) + first(satellites, realized) + others(satellites, realized) + with self.assertWarnsRegex(UserWarning, "other code"): + latest(satellites, realized) + stale = first._cache_of(realized).folder + self.assertEqual(len(list(stale.glob("*.pkl"))), len(satellites)) + # a study removes them too, and counts the evaluations it removes + study = ObservationStudy(SPACE, _build, latest, _metrics) + self.assertEqual(study.prune(), 0) # (without a store) + self.assertEqual(list(stale.glob("*.pkl")), []) + self.assertEqual(latest.prune(), 0) + # the results of the other targets (another definition) are kept + kept = others._cache_of(realized).folder + self.assertEqual(len(list(kept.glob("*.pkl"))), len(satellites)) + self.assertEqual(Observations(TARGETS, START, HOURS).prune(), 0) + + def test_failure_options(self): + """Failures sample stressed histories, with controls and spreads.""" + realized = self.design.realize(0) + default = MissionPlan(SCHEDULE)._policy_of(realized) + self.assertTrue(default.restore) # restored by default + study = ObservationStudy( + SPACE, + _build, + _observations(), + _metrics, + layout="layout", + plan=PLAN, + failures=Failures( + FAILURES, + seed="failure_seed", + histories=6, + stress=2.0, + controls=["availability"], + control_histories=50, + statistics=[StandardDeviation("observed mission")], + ), + ) + result = study.run([self.design]).iloc[0] + self.assertIn("observed mission histories std", result.index) + self.assertLess(result["effective histories"], 6) + self.assertTrue(math.isfinite(result["observed mission"])) + with self.assertRaisesRegex(ValueError, "controls"): + study.replace( + failures=Failures(FAILURES, seed="failure_seed", controls=["other"]) + ).run([self.design]) + + +class TestFailureStudies(unittest.TestCase): + """ + Unit tests for the summaries of failures of observation studies. + """ + + def test_costs_and_histories(self): + """The costs of a study of failures are the means of its histories.""" + design = SPACE.enumerate()[3] + study = ObservationStudy( + SPACE, + _build, + _observations(), + _metrics, + plan=PLAN, + failures=Failures(FAILURES, histories=5, seed="failure_seed"), + ) + result = study.run([design]).iloc[0] + histories = study.mission_of(design).histories() + self.assertEqual(len(histories), 5) + self.assertAlmostEqual(result["cost"], histories["cost"].mean()) + self.assertAlmostEqual( + result["observed mission"], histories["observed mission"].mean() + ) + with self.assertRaisesRegex(ValueError, "failures"): + study.replace(failures=None).mission_of(design).histories() + + def test_exact_or_sampled(self): + """Without restoration, the means are exact expectations if the sets of + satellites are few enough, and otherwise those of the histories.""" + design = SPACE.enumerate()[3] + study = ObservationStudy( + SPACE, + _build, + _observations(), + _metrics, + plan=DEGRADE, + failures=Failures(FAILURES, histories=4, seed="failure_seed"), + ) + mission = study.mission_of(design) + exact = exact_expectations(mission.deployment, FAILURES, mission.capability) + sampled = mission.histories() + result = study.run([design]).iloc[0] + for column in ("observed mission", "availability"): + self.assertAlmostEqual(result[column], exact[column]) + bounded = partial(exact_expectations, max_sets=1) + with mock.patch("tatc.tradespace.plans.exact_expectations", bounded): + fallback = study.run([design]).iloc[0] + for column in ("observed mission", "availability"): + self.assertAlmostEqual(fallback[column], sampled[column].mean()) diff --git a/tests/tradespace/test_optimization.py b/tests/tradespace/test_optimization.py new file mode 100644 index 0000000..3e3f8ab --- /dev/null +++ b/tests/tradespace/test_optimization.py @@ -0,0 +1,668 @@ +""" +Unit tests for searches of design spaces with optimizers. + +@author Paul T. Grogan +""" + +import importlib.util +import unittest + +import numpy as np +import pandas as pd + +from tatc.tradespace import ( + Categorical, + Choice, + Criteria, + DesignSpace, + Infeasible, + Integer, + Minimum, + Real, + Repeat, + Requirement, + Study, + Uncertain, + hypervolume, + optimize_optuna, + optimize_pymoo, + pareto_front, + summarize, +) +from tatc.tradespace.optimization import ( + Evaluations, + _constraint_names, + make_pymoo_problem, +) +from tatc.tradespace.values import Scope +from tatc.tradespace.walks import _Context, _walk + +HAS_OPTUNA = importlib.util.find_spec("optuna") is not None +HAS_PYMOO = importlib.util.find_spec("pymoo") is not None + +OBJECTIVES = {"cost": "min", "value": "max"} +REFERENCE = {"cost": 30, "value": 0} + + +def _encode(space, design): + """The center of each decided level's part of [0, 1], and 0.5 for inactive paths.""" + paths = space._unit_paths() + index = {path: i for i, path in enumerate(paths)} + unit = np.full(len(index), 0.5) + + def record(path, domain, value): + unit[index[path]] = (domain.levels.index(value) + 0.5) / len(domain.levels) + return value + + _walk(space, "", Scope(), _Context(normalize=record), design.decisions) + return unit + + +def _space(): + """Constellations of planes, or a single satellite of a quality.""" + return DesignSpace( + layout=Choice( + planes=DesignSpace( + planes=Repeat( + DesignSpace(satellites=Integer(1, 4), size=Real(0.5, 2, step=0.5)), + count=Integer(1, 3), + ordered=False, + ) + ), + single=DesignSpace(quality=Categorical([1, 2, 3])), + ), + noise=Uncertain.uniform(-0.01, 0.01), + # at most 8 satellites, violated by the satellites in excess + constraints=[ + lambda d: ( + sum(p.satellites for p in d.layout.planes) - 8 + if d.layout.choice == "planes" + else True + ) + ], + ) + + +def _build(design): + if design.layout.choice == "single": + return {"cost": 2.0 * design.layout.quality, "value": design.layout.quality} + if any(p.size == 2 and p.satellites == 4 for p in design.layout.planes): + raise Infeasible("too heavy") + cost = sum(p.satellites * p.size + 1 for p in design.layout.planes) + value = sum(np.sqrt(p.satellites) * p.size for p in design.layout.planes) + return {"cost": cost, "value": value + design.noise} + + +def _study(**kwargs): + return Study(_space(), _build, lambda metrics: metrics, replicates=2, **kwargs) + + +def _partly_infeasible(): + """A study of three designs, of which the first is feasible in every + replicate, the second in some, and the third in none, and its designs.""" + space = DesignSpace(x=Integer(0, 2), noise=Uncertain.uniform(0, 1)) + + def build(d): + if d.x == 2 or (d.x == 1 and d.noise < 0.5): + raise Infeasible("unlucky") + return d + + study = Study(space, build, lambda d: {"f": d.x}, replicates=8) + return study, space.enumerate() + + +class TestEncoding(unittest.TestCase): + """ + Unit tests for encoding designs in the unit hypercube. + """ + + def test_unit_paths(self): + """Paths cover every decision, with repeated items up to the largest count.""" + paths = _space()._unit_paths() + self.assertEqual( + paths[:3], + [ + "layout", + "layout.planes.planes.count", + "layout.planes.planes[0].satellites", + ], + ) + self.assertEqual(len(paths), 1 + 1 + 3 * 2 + 1) + self.assertEqual(paths[-1], "layout.single.quality") + + def test_round_trip(self): + """Every design decodes from its encoding.""" + space = _space() + for design in space.enumerate(): + self.assertEqual(space._decode(_encode(space, design)).key, design.key) + + def test_decode_random(self): + """Random points decode to designs of the space (or infeasible ones).""" + space = _space() + keys = {design.key for design in space.enumerate()} + rng = np.random.default_rng(0) + decoded = 0 + for _ in range(200): + try: + design = space._decode(rng.random(len(space._unit_paths()))) + except Infeasible: + continue + decoded += 1 + self.assertIn(design.key, keys) + self.assertGreater(decoded, 100) + + def test_dynamic_count_bound(self): + """Counts need fixed upper bounds to be encoded.""" + space = DesignSpace( + n=Integer(1, 3), + parts=Repeat(Integer(0, 1), count=Integer(1, lambda d: d.n)), + ) + with self.assertRaises(ValueError): + space._unit_paths() + + +class TestEvaluations(unittest.TestCase): + """ + Unit tests for evaluations of searches. + """ + + def test_memo(self): + """Designs are evaluated once, and infeasible designs have no objectives.""" + evaluations = Evaluations(_study(), OBJECTIVES) + designs = _space().enumerate()[:5] + first = evaluations.evaluate(designs + designs) + self.assertEqual(first[:5], first[5:]) + evaluations.evaluate(designs) + self.assertEqual(len(evaluations.results), 5 * 2) + + def test_feasible_replicates(self): + """A design infeasible in some replicates is judged by the others, as + summaries judge it, unless a requirement on its share of feasible + replicates rejects it; a design without a feasible replicate is + infeasible.""" + study, designs = _partly_infeasible() + results = study.run(designs) + share = results[results.design == designs[1].key].feasible.mean() + self.assertGreater(share, 0) + self.assertLess(share, 1) + evaluations = Evaluations(study, {"f": "max"}) + values = evaluations.evaluate(designs) + self.assertEqual(values[:2], [(0.0,), (1.0,)]) + self.assertIsNone(values[2]) + self.assertEqual( + [evaluations.infeasibility[d.key] for d in designs], [0.0, 0.0, 1.0] + ) + # the summary of a search is that of its results (see summarize), + # with the spreads of means + search = evaluations.search(None) + pd.testing.assert_frame_equal(search.summary, summarize(results, {"f": "max"})) + self.assertEqual([d.key for d in search.designs], [designs[1].key]) + self.assertEqual(len(search.evaluated), 3) + # a requirement on the share of feasible replicates + reliable = Criteria( + {"f": "max"}, requirements=[Requirement("feasible", ">=", 1)] + ) + evaluations = Evaluations(study, reliable) + evaluations.evaluate(designs) + self.assertEqual(evaluations.violations[designs[0].key], (0.0,)) + self.assertAlmostEqual(evaluations.violations[designs[1].key][0], 1 - share) + # a search of designs without a feasible replicate finds none + none = Evaluations(study, reliable) + none.evaluate(designs[2:]) + self.assertTrue(none.search(None).summary.empty) + self.assertEqual(none.search(None).designs, []) + + def test_one_record_per_evaluation(self): + """Objectives need one record per evaluation.""" + study = Study( + _space(), + lambda d: None, + lambda built: pd.DataFrame({"cost": [1, 2], "value": [1, 2]}), + ) + with self.assertRaises(ValueError): + Evaluations(study, OBJECTIVES).evaluate(_space().enumerate()[:1]) + + def test_constraint_names(self): + """Requirements are constraints of distinct names: their statements, + their values in full where these are alike, or their order.""" + requirements = [ + Requirement("a", ">=", 2.0000001), + Requirement("a", ">=", 2.0000002), + Requirement("b", "<=", 1), + Requirement("b", "<=", 1, scale=2), + ] + self.assertEqual( + _constraint_names(requirements), + ["a >= 2.0000001", "a >= 2.0000002", "b <= 1", "b <= 1 (2)"], + ) + + +def _exact_hypervolume(): + summary = summarize(_study().run(), statistics=list(OBJECTIVES)) + return summary, hypervolume(summary, OBJECTIVES, REFERENCE) + + +@unittest.skipUnless(HAS_OPTUNA, "requires optuna") +class TestOptuna(unittest.TestCase): + """ + Unit tests for searches with Optuna. + """ + + def test_suggest(self): + """Suggestions follow the kinds of the variables.""" + import optuna # pylint: disable=import-outside-toplevel + + trial = optuna.trial.FixedTrial( + { + "layout": "planes", + "layout.planes.planes.count": 2, + "layout.planes.planes[0].satellites": 3, + "layout.planes.planes[0].size": 1.5, + "layout.planes.planes[1].satellites": 1, + "layout.planes.planes[1].size": 0.5, + } + ) + design = _space()._suggest(trial) + self.assertEqual( + [(p.satellites, p.size) for p in design.layout.planes], [(1, 0.5), (3, 1.5)] + ) + + def test_optimize(self): + """A search finds most of the hypervolume of the true front.""" + import optuna # pylint: disable=import-outside-toplevel + + from tatc.tradespace import ( + optimize_optuna, + ) # pylint: disable=import-outside-toplevel + + optuna.logging.set_verbosity(optuna.logging.WARNING) + summary, exact = _exact_hypervolume() + search = optimize_optuna( + _study(), + OBJECTIVES, + n_trials=150, + sampler=optuna.samplers.NSGAIISampler(seed=1, population_size=20), + ) + optuna_study, results = search.state, search.results + self.assertEqual(len(optuna_study.trials), 150) + found = summarize(results, statistics=list(OBJECTIVES)) + self.assertLessEqual(found.design.nunique(), 150) + self.assertGreater(hypervolume(found, OBJECTIVES, REFERENCE), 0.9 * exact) + self.assertTrue(pareto_front(summary, OBJECTIVES).any()) + + +@unittest.skipUnless(HAS_PYMOO, "requires pymoo") +class TestPymoo(unittest.TestCase): + """ + Unit tests for searches with pymoo. + """ + + def test_optimize(self): + """NSGA-II on the encoded space finds most of the hypervolume of the true front.""" + from tatc.tradespace import ( + optimize_pymoo, + ) # pylint: disable=import-outside-toplevel + + _, exact = _exact_hypervolume() + search = optimize_pymoo(_study(), OBJECTIVES, termination=("n_gen", 15), seed=1) + result, results = search.state, search.results + self.assertEqual(result.F.shape[1], 2) + self.assertEqual({d.key for d in search.evaluated}, set(results.design)) + # the designs of a search are the efficient designs it found + self.assertEqual( + [d.key for d in search.designs], + list(search.summary.design[search.summary.pareto]), + ) + self.assertEqual(search.criteria.objectives, OBJECTIVES) + found = summarize(results, statistics=list(OBJECTIVES)) + self.assertGreater(hypervolume(found, OBJECTIVES, REFERENCE), 0.9 * exact) + self.assertFalse(results.feasible.all()) # some designs were too heavy + # the summary of the feasible designs, and their front + summary = search.summary + self.assertEqual(set(summary.design), set(results.design[results.feasible])) + self.assertIn("value se", summary.columns) # with the spreads of means + np.testing.assert_array_equal( + summary.pareto, pareto_front(summary, OBJECTIVES).to_numpy() + ) + + def test_duplicates(self): + """Proposals of the same design, or of designs evaluated before, are + duplicates; proposals that violate a constraint are not.""" + from pymoo.core.population import ( # pylint: disable=import-outside-toplevel + Population, + ) + + study = _study() + problem = make_pymoo_problem(study, OBJECTIVES) + single = study.space.design({"layout": ["single", {"quality": 2}]}) + x = _encode(study.space, single) + # the same level of each variable, and other values of the branch not chosen + same = x.copy() + same[study.space._unit_paths().index("layout.single.quality")] += 0.1 + other = x.copy() + other[study.space._unit_paths().index("layout.planes.planes.count")] = 0.9 + too_many = _encode( + study.space, + study.space.design( + {"layout": ["planes", {"planes": [{"satellites": 4, "size": 0.5}] * 2}]} + ), + ) + too_many[study.space._unit_paths().index("layout.planes.planes.count")] = 0.99 + for k in range(3): + too_many[ + study.space._unit_paths().index(f"layout.planes.planes[{k}].satellites") + ] = 0.99 + with self.assertRaises(Infeasible): + study.space._decode(too_many) + pop = Population.new("X", np.array([x, same, other, too_many, too_many])) + kept = problem.duplicates.do(pop) + self.assertEqual(len(kept), 3) # one of the same design, and both infeasible + # designs evaluated before are duplicates + problem.evaluations.evaluate([single]) + self.assertEqual(len(problem.duplicates.do(pop)), 2) + + def test_distinct(self): + """Distinct searches evaluate more designs in as many generations.""" + distinct = optimize_pymoo( + _study(), OBJECTIVES, termination=("n_gen", 5), seed=1 + ) + plain = optimize_pymoo( + _study(), OBJECTIVES, termination=("n_gen", 5), seed=1, distinct=False + ) + self.assertGreater(len(distinct.evaluated), len(plain.evaluated)) + with self.assertRaises(ValueError): + optimize_pymoo(_study(), OBJECTIVES, algorithm=object(), seed=1) + + def test_algorithm_unchanged(self): + """A distinct search does not change the algorithm it is given, which + another search may take.""" + # pylint: disable-next=import-outside-toplevel + from pymoo.algorithms.moo.nsga2 import NSGA2 + + algorithm = NSGA2(pop_size=8) + own = algorithm.mating.eliminate_duplicates + optimize_pymoo( + _study(), OBJECTIVES, algorithm=algorithm, termination=("n_gen", 2), seed=1 + ) + self.assertIs(algorithm.mating.eliminate_duplicates, own) + self.assertIs(algorithm.initialization.eliminate_duplicates, own) + plain = optimize_pymoo( + _study(), + OBJECTIVES, + algorithm=algorithm, + termination=("n_gen", 2), + seed=1, + distinct=False, + ) + self.assertGreater(len(plain.evaluated), 0) + + def test_max_designs(self): + """A search stops after the generation in which it has evaluated the + most designs, or by its termination.""" + from pymoo.algorithms.moo.nsga2 import ( # pylint: disable=import-outside-toplevel + NSGA2, + ) + + search = optimize_pymoo( + _study(), + OBJECTIVES, + algorithm=NSGA2(pop_size=10), + termination=("n_gen", 50), + seed=1, + max_designs=25, + ) + evaluated = search.results.design.nunique() + self.assertGreaterEqual(evaluated, 25) + self.assertLess(evaluated, 25 + 10) + self.assertLess(search.state.algorithm.n_gen, 50) + # the termination, if first + short = optimize_pymoo( + _study(), + OBJECTIVES, + algorithm=NSGA2(pop_size=10), + termination=("n_gen", 2), + seed=1, + max_designs=1000, + ) + self.assertLessEqual(short.results.design.nunique(), 20) + with self.assertRaises(ValueError): + optimize_pymoo(_study(), OBJECTIVES, max_designs=0) + + +@unittest.skipUnless(HAS_OPTUNA, "requires optuna") +class TestOptunaConstraints(unittest.TestCase): + """ + Unit tests for constraints in searches with Optuna. + """ + + def setUp(self): + import optuna # pylint: disable=import-outside-toplevel + + optuna.logging.set_verbosity(optuna.logging.WARNING) + self.optuna = optuna + + def test_violations(self): + """Trials record the violations of their designs' constraints.""" + optuna_study = optimize_optuna( + _study(), + OBJECTIVES, + n_trials=80, + sampler=self.optuna.samplers.RandomSampler(seed=3), + ).state + states = {trial.state for trial in optuna_study.trials} + self.assertEqual(states, {self.optuna.trial.TrialState.COMPLETE}) + violations = [trial.constraints["feasibility"] for trial in optuna_study.trials] + self.assertTrue(any(v == 0 for v in violations)) + excess = [v for v in violations if v > 0] + self.assertTrue(excess) + # violations of the space count satellites in excess; the study's are 1 + for trial in optuna_study.trials: + if "error" in trial.user_attrs: + planes = [ + trial.params[f"layout.planes.planes[{k}].satellites"] + for k in range(trial.params["layout.planes.planes.count"]) + ] + self.assertEqual(trial.constraints["feasibility"], sum(planes) - 8) + + def test_pruning(self): + """Without constraints, infeasible trials are pruned.""" + optuna_study = optimize_optuna( + _study(), + OBJECTIVES, + n_trials=60, + sampler=self.optuna.samplers.RandomSampler(seed=3), + constraints=False, + ).state + states = {trial.state for trial in optuna_study.trials} + self.assertIn(self.optuna.trial.TrialState.PRUNED, states) + self.assertTrue(all(not trial.constraints for trial in optuna_study.trials)) + + +@unittest.skipUnless(HAS_PYMOO, "requires pymoo") +class TestPymooConstraints(unittest.TestCase): + """ + Unit tests for constraints of pymoo problems. + """ + + def test_violations(self): + """Violations of the space are the constraint values of the problem.""" + from pymoo.core.evaluator import ( + Evaluator, + ) # pylint: disable=import-outside-toplevel + from pymoo.core.population import ( + Population, + ) # pylint: disable=import-outside-toplevel + + space = _space() + problem = make_pymoo_problem(_study(), OBJECTIVES) + light = space.design({"layout": ["single", {"quality": 2}]}) + # three planes of four satellites: the first branch, the largest count + # and number of satellites (the last of their levels) + paths = space._unit_paths() + heavy = np.full(len(paths), 0.1) + for i, path in enumerate(paths): + if path.endswith("count") or path.endswith("satellites"): + heavy[i] = 0.99 + with self.assertRaises(Infeasible) as context: + space._decode(heavy) + self.assertEqual(context.exception.violation, 4) + x = np.array([_encode(space, light), heavy]) + population = Evaluator().eval(problem, Population.new(X=x)) + self.assertEqual(list(population.get("G")[:, 0]), [0, 4]) + + +@unittest.skipUnless(HAS_OPTUNA and HAS_PYMOO, "requires optuna and pymoo") +class TestRequirements(unittest.TestCase): + """ + Unit tests for requirements in searches. + """ + + CRITERIA = Criteria( + OBJECTIVES, + statistics={"value p0": Minimum("value")}, + requirements=[Requirement("value p0", ">=", 2)], + ) + + def test_evaluations(self): + """Evaluations give the violations of requirements on statistics.""" + evaluations = Evaluations(_study(), self.CRITERIA) + designs = [d for d in _space().enumerate() if d.layout.choice == "single"] + values = evaluations.evaluate(designs) + for design, value in zip(designs, values): + violation = evaluations.violations[design.key][0] + # the least value over replicates is the quality less the noise, + # and violations are relative to the required value + self.assertAlmostEqual(violation, max(2 - value[1], 0) / 2, delta=0.01) + with self.assertRaises(ValueError): + Evaluations(_study(), Criteria(OBJECTIVES, by="sensor")) + + def test_optuna(self): + """Trials record the violation of each requirement.""" + import optuna # pylint: disable=import-outside-toplevel + + optuna.logging.set_verbosity(optuna.logging.WARNING) + optuna_study = optimize_optuna( + _study(), + self.CRITERIA, + n_trials=40, + sampler=optuna.samplers.RandomSampler(seed=1), + ).state + keys = {tuple(sorted(trial.constraints)) for trial in optuna_study.trials} + self.assertEqual(keys, {("feasibility", "value p0 >= 2")}) + violations = [t.constraints["value p0 >= 2"] for t in optuna_study.trials] + self.assertTrue(any(v > 0 for v in violations)) + with self.assertRaises(ValueError): + optimize_optuna(_study(), self.CRITERIA, n_trials=1, constraints=False) + + def test_optuna_names(self): + """Requirements that state themselves alike are distinct constraints.""" + import optuna # pylint: disable=import-outside-toplevel + + optuna.logging.set_verbosity(optuna.logging.WARNING) + criteria = Criteria( + OBJECTIVES, + statistics={"value p0": Minimum("value")}, + requirements=[ + Requirement("value p0", ">=", 2.0000001), + Requirement("value p0", ">=", 2.5000001), + Requirement("value p0", ">=", 2.5000002), + ], + ) + optuna_study = optimize_optuna( + _study(), criteria, n_trials=10, sampler=optuna.samplers.RandomSampler(1) + ).state + names = ("value p0 >= 2", "value p0 >= 2.5000001", "value p0 >= 2.5000002") + keys = {tuple(sorted(trial.constraints)) for trial in optuna_study.trials} + self.assertEqual(keys, {("feasibility", *names)}) + + def test_pymoo(self): + """Problems have a constraint for each requirement.""" + problem = make_pymoo_problem(_study(), self.CRITERIA) + self.assertEqual(problem.n_ieq_constr, 2) + result = optimize_pymoo( + _study(), self.CRITERIA, termination=("n_gen", 3), seed=1 + ).state + self.assertEqual(result.pop.get("G").shape[1], 2) + + +@unittest.skipUnless(HAS_OPTUNA, "optuna is not installed") +class TestOptunaSearch(unittest.TestCase): + """ + Unit tests for searches with Optuna: dynamic options, batches, and budgets. + """ + + def test_dynamic_options(self): + """Categorical options that depend on earlier decisions are searched.""" + import optuna # pylint: disable=import-outside-toplevel + + space = DesignSpace( + kind=Categorical(["a", "b"]), + option=Categorical(lambda d: ["x", "y"] if d.kind == "a" else ["z"]), + ) + study = Study(space, lambda d: d, lambda d: {"f": float(d.option == "x")}) + search = optimize_optuna( + study, + {"f": "max"}, + n_trials=20, + sampler=optuna.samplers.RandomSampler(seed=1), + ) + optuna_study, results = search.state, search.results + self.assertEqual(set(results.option), {"x", "y", "z"}) + self.assertEqual(optuna_study.best_value, 1.0) + + def test_default_sampler(self): + """The default sampler lies about pending trials in batches.""" + study = Study(DesignSpace(x=Integer(0, 9)), lambda d: d, lambda d: {"f": d.x}) + batched = optimize_optuna(study, {"f": "min"}, n_trials=4, batch_size=2).state + single = optimize_optuna(study, {"f": "min"}, n_trials=2, batch_size=1).state + # pylint: disable=protected-access + self.assertTrue(batched.sampler._constant_liar) + self.assertFalse(single.sampler._constant_liar) + + def test_max_designs(self): + """The search stops once it has evaluated the most designs.""" + study = Study(DesignSpace(x=Integer(0, 2)), lambda d: d, lambda d: {"f": d.x}) + search = optimize_optuna( + study, {"f": "min"}, n_trials=50, max_designs=2, batch_size=1 + ) + optuna_study, results = search.state, search.results + self.assertEqual(results.design.nunique(), 2) + # the designs evaluated by the search, in the order of their evaluation + self.assertEqual( + [design.key for design in search.evaluated], + results.design.drop_duplicates().tolist(), + ) + self.assertLessEqual(len(optuna_study.trials), 50) + with self.assertRaises(ValueError): + optimize_optuna(study, {"f": "min"}, n_trials=5, max_designs=0) + + def test_partially_infeasible(self): + """A design without a feasible replicate violates the constraint of + feasibility; one infeasible in some replicates does not, but violates + a requirement on its share of feasible replicates.""" + study, designs = _partly_infeasible() + results = study.run(designs) + share = results[results.design == designs[1].key].feasible.mean() + reliable = Criteria( + {"f": "max"}, requirements=[Requirement("feasible", ">=", 1)] + ) + optuna_study = optimize_optuna(study, reliable, n_trials=12).state + for trial in optuna_study.trials: + x = trial.params.get("x") + feasibility = trial.constraints["feasibility"] + self.assertEqual(feasibility, 1.0 if x == 2 else 0.0) + if x == 1: + self.assertAlmostEqual(trial.constraints["feasible >= 1"], 1 - share) + + def test_records_checked_first(self): + """A study of several records per evaluation fails after one design.""" + calls = [] + + def evaluate(d): + calls.append(d.x) + return pd.DataFrame({"f": [d.x, d.x]}, index=pd.Index([0, 1], name="k")) + + study = Study(DesignSpace(x=Integer(0, 9)), lambda d: d, evaluate) + with self.assertRaises(ValueError): + Evaluations(study, {"f": "min"}).evaluate(study.space.enumerate()) + self.assertEqual(len(calls), 1) diff --git a/tests/tradespace/test_pareto.py b/tests/tradespace/test_pareto.py new file mode 100644 index 0000000..6089b52 --- /dev/null +++ b/tests/tradespace/test_pareto.py @@ -0,0 +1,344 @@ +""" +Unit tests for the Pareto efficiency of the rows of summaries of designs: +fronts, ranks, and hypervolumes, and the dominance of points with +tolerances. + +@author Paul T. Grogan +""" + +import itertools +import unittest + +import numpy as np +import pandas as pd + +from tatc.tradespace import ( + Criteria, + Requirement, + hypervolume, + hypervolume_progress, + pareto_front, + pareto_ranks, + summarize, +) +from tatc.tradespace.dominance import dominated + + +def _results(values): + """Results of designs (rows) in replicates (columns), with a cost of 1.""" + return pd.DataFrame( + [ + { + "design": f"d{i}", + "replicate": r, + "cost": 1.0, + "value": v, + "feasible": True, + } + for i, row in enumerate(values) + for r, v in enumerate(row) + ] + ) + + +def _brute_hypervolume(costs: np.ndarray, reference: np.ndarray) -> float: + """Hypervolume (to minimize) by inclusion-exclusion over subsets.""" + total = 0.0 + for size in range(1, len(costs) + 1): + for subset in itertools.combinations(range(len(costs)), size): + corner = costs[list(subset)].max(axis=0) + total += (-1) ** (size + 1) * np.prod(np.clip(reference - corner, 0, None)) + return total + + +class TestPareto(unittest.TestCase): + """ + Unit tests for Pareto efficiency. + """ + + def setUp(self): + self.frame = pd.DataFrame( + { + "cost": [1, 2, 3, 2, 4, 1], + "value": [1, 3, 4, 2, 4, 1], + }, + index=list("abcdef"), + ) + self.objectives = {"cost": "min", "value": "max"} + + def test_front(self): + """The front is the non-dominated rows, including ties.""" + front = pareto_front(self.frame, self.objectives) + self.assertEqual(list(front[front].index), ["a", "b", "c", "f"]) + flipped = pareto_front(self.frame, {"cost": "max", "value": "max"}) + self.assertEqual(list(flipped[flipped].index), ["e"]) + + def test_ranks(self): + """Ranks peel successive fronts.""" + ranks = pareto_ranks(self.frame, self.objectives) + self.assertEqual(list(ranks), [0, 0, 0, 1, 1, 0]) + + def test_hypervolume_2d(self): + """The two-dimensional hypervolume is the area of the dominated staircase.""" + # costs (cost, -value) to (5, 0): a (1,-1), b (2,-3), c (3,-4) + area = hypervolume(self.frame, self.objectives, {"cost": 5, "value": 0}) + self.assertAlmostEqual(area, 4 * 1 + 3 * 2 + 2 * 1) + self.assertEqual(hypervolume(self.frame, self.objectives, [0, 10]), 0.0) + self.assertEqual(hypervolume(self.frame.iloc[:0], self.objectives, [5, 0]), 0) + + def test_hypervolume_matches_brute_force(self): + """Hypervolumes in three and four dimensions match inclusion-exclusion.""" + rng = np.random.default_rng(4) + for dimensions in (3, 4): + costs = rng.random((9, dimensions)) + frame = pd.DataFrame(costs, columns=[f"f{i}" for i in range(dimensions)]) + objectives = {column: "min" for column in frame.columns} + reference = np.full(dimensions, 1.1) + self.assertAlmostEqual( + hypervolume(frame, objectives, reference), + _brute_hypervolume(costs, reference), + ) + + def test_invalid(self): + """Directions and references are checked.""" + with self.assertRaises(ValueError): + pareto_front(self.frame, {"cost": "lowest"}) + with self.assertRaises(ValueError): + hypervolume(self.frame, self.objectives, [1]) + + def test_tolerance(self): + """Rows within the tolerances of the front are efficient.""" + frame = pd.DataFrame( + {"cost": [1.0, 1.05, 1.5, 2.0], "value": [1.0, 1.02, 0.99, 0.5]} + ) + objectives = {"cost": "min", "value": "max"} + self.assertEqual( + list(pareto_front(frame, objectives)), [True, True, False, False] + ) + # c is worse than a and b by 0.01 and 0.03 in value, within the + # tolerance; d is not + loose = Criteria(objectives, tolerances={"value": 0.05}) + self.assertEqual(list(pareto_front(frame, loose)), [True, True, True, False]) + self.assertEqual(list(pareto_ranks(frame, loose)), [0, 0, 0, 1]) + # a larger tolerance keeps d (worse than a by 0.5 in value) + looser = Criteria(objectives, tolerances={"value": 0.6}) + self.assertTrue(pareto_front(frame, looser).all()) + + def test_requirements_and_groups(self): + """Rows that miss requirements are not efficient, and groups are separate.""" + frame = self.frame.assign( + reliability=[1.0, 1.0, 0.2, 1.0, 1.0, np.nan], sensor=list("xxxxxy") + ) + criteria = Criteria( + self.objectives, requirements=[Requirement("reliability", ">=", 0.5)] + ) + front = pareto_front(frame, criteria) + # c (efficient by its objectives) and f (unknown) miss the + # requirement, and e is efficient without c + self.assertEqual(list(front[front].index), ["a", "b", "e"]) + ranks = pareto_ranks(frame, criteria) + self.assertEqual(list(ranks[list("abde")]), [0, 0, 1, 0]) + # those that miss it rank after, in order of their violations + self.assertEqual(list(ranks[["c", "f"]]), [2, 3]) + area = hypervolume(frame, criteria, {"cost": 5, "value": 0}) + self.assertAlmostEqual(area, 4 * 1 + 3 * 2 + 1 * 1) + # f is alone in its group + grouped = Criteria(self.objectives, by="sensor") + front = pareto_front(frame, grouped) + self.assertEqual(list(front[front].index), ["a", "b", "c", "f"]) + self.assertEqual(pareto_ranks(frame, grouped)["f"], 0) + with self.assertRaises(ValueError): + hypervolume(frame, grouped, [5, 0]) + with self.assertRaises(ValueError): + pareto_front(self.frame, criteria) # no column of the requirement + + def test_missing_group(self): + """Rows without a value of a column of groups are a group of their own.""" + frame = pd.DataFrame( + {"cost": [1.0, 0.5, 2.0, 0.2], "sensor": ["x", None, "x", np.nan]} + ) + grouped = Criteria({"cost": "min"}, by="sensor") + # the rows without a sensor are judged together, not left out + self.assertEqual(list(pareto_front(frame, grouped)), [True, False, False, True]) + self.assertEqual(list(pareto_ranks(frame, grouped)), [0, 1, 1, 0]) + + +class TestRelativeTolerance(unittest.TestCase): + """ + Unit tests for tolerances proportional to objectives. + """ + + def test_relative(self): + """A percentage tolerates differences in proportion to the values.""" + frame = pd.DataFrame({"cost": [1, 1, 2, 2], "value": [100.0, 96.0, 4.0, 3.0]}) + objectives = {"cost": "min", "value": "max"} + # 5% of 96 (4.8) tolerates 96 against 100; 5% of 3 (0.15) does not + # tolerate 3 against 4 + front = pareto_front(frame, Criteria(objectives, tolerances={"value": "5%"})) + self.assertEqual(list(front), [True, True, False, False]) + # an absolute tolerance of 1 does not tolerate 96 against 100 + absolute = pareto_front(frame, Criteria(objectives, tolerances={"value": 1.0})) + self.assertEqual(list(absolute), [True, False, False, False]) + + +class TestSummaries(unittest.TestCase): + """ + Unit tests for the efficient designs of summaries (a row per design), and + the functions of summaries given the results of a study. + """ + + def setUp(self): + self.results = _results([[1, 2, 3], [5, 6, 7]]) + self.objectives = {"cost": "min", "value": "max"} + + def test_pareto(self): + """Summaries of criteria give the efficient designs, in each group.""" + results = pd.concat( + [ + _results([[10, 12, 14, 16], [5, 30, 5, 30]]).assign( + cost=2.0, size="small" + ), + _results([[1] * 4]).assign(design="d2", size="large"), + ], + ignore_index=True, + ) + criteria = Criteria(self.objectives, by="size") + summary = summarize(results, criteria) + self.assertEqual( + list(summary.pareto), + list(pareto_front(summary.drop(columns="pareto"), criteria)), + ) + # designs d0 (a mean of 13) and d1 (17.5) of the same cost, and d2 alone + self.assertEqual( + dict(zip(summary.design, summary.pareto)), + {"d0": False, "d1": True, "d2": True}, + ) + + def test_results_raise(self): + """Results with a row per replicate are not summaries of designs.""" + for function in (pareto_front, pareto_ranks): + with self.assertRaisesRegex(ValueError, "summarize"): + function(self.results, self.objectives) + with self.assertRaisesRegex(ValueError, "summarize"): + hypervolume(self.results, self.objectives, [2, 0]) + indexed = self.results.set_index("design") + with self.assertRaisesRegex(ValueError, "summarize"): + pareto_front(indexed, self.objectives) + + def test_groups_of_designs(self): + """A design may have a row in each group of the criteria's `by`.""" + summary = pd.concat( + [ + pd.DataFrame({"design": ["a", "b"], "value": [1, 2], "s": "x"}), + pd.DataFrame({"design": ["a", "b"], "value": [2, 1], "s": "y"}), + ] + ) + front = pareto_front(summary, Criteria({"value": "max"}, by="s")) + self.assertEqual(list(front), [False, True, True, False]) + with self.assertRaises(ValueError): + pareto_front(summary, {"value": "max"}) + # rows without designs are any rows + rows = pd.DataFrame({"value": [1, 1, 2]}) + self.assertEqual( + list(pareto_front(rows, {"value": "max"})), [False, False, True] + ) + + +class TestManyPoints(unittest.TestCase): + """ + Unit tests for the dominance of many points. + """ + + @staticmethod + def _every_pair(costs, tolerances=None): + """Dominance by comparing every pair of points.""" + absolute, relative = ( + np.zeros((2, costs.shape[1])) if tolerances is None else tolerances + ) + beaten = np.zeros(len(costs), dtype=bool) + for i, point in enumerate(costs): + penalized = costs + absolute + relative * np.abs(point) + no_worse = np.all(penalized <= point, axis=1) + better = np.any(penalized < point, axis=1) + beaten[i] = np.any(no_worse & better) + return beaten + + def test_matches_every_pair(self): + """Dominance, with or without tolerances, is that of every pair.""" + rng = np.random.default_rng(3) + sets = ( + rng.random((700, 3)), + rng.integers(0, 4, (700, 3)).astype(float), + np.vstack([rng.random((150, 2))] * 3), + np.column_stack([rng.integers(1, 11, 900), rng.normal(0, 30, 900)]), + ) + tolerances = ( + None, + np.array([[0.0, 0.0, 0.1], [0.0, 0.0, 0.0]]), + np.array([[0.0, 0.0, 0.0], [0.05, 0.0, 0.1]]), + ) + for costs in sets: + for tolerance in tolerances: + if tolerance is not None: + tolerance = tolerance[:, : costs.shape[1]] + np.testing.assert_array_equal( + dominated(costs, tolerance), + self._every_pair(costs, tolerance), + ) + + def test_many_points(self): + """Fronts of many points are found quickly.""" + rng = np.random.default_rng(4) + frame = pd.DataFrame(rng.random((20_000, 3)), columns=["a", "b", "c"]) + front = pareto_front(frame, {"a": "min", "b": "min", "c": "max"}) + self.assertGreater(front.sum(), 0) + tolerant = pareto_front( + frame, + Criteria({"a": "min", "b": "min", "c": "max"}, tolerances={"c": "5%"}), + ) + self.assertTrue((tolerant >= front).all()) + + +class TestHypervolumeProgress(unittest.TestCase): + """ + Unit tests for the hypervolume of searches as they proceed. + """ + + def test_progress(self): + """The hypervolume of the first designs evaluated, in steps.""" + results = pd.DataFrame( + { + "design": ["a", "a", "b", "c", "d"], + "replicate": [0, 1, 0, 0, 0], + "feasible": [True, True, True, True, False], + "x": [1.0, 3.0, 4.0, 1.0, np.nan], + "y": [4.0, 6.0, 8.0, 2.0, np.nan], + } + ) + objectives = {"x": "min", "y": "max"} + # a (2, 5) and b (4, 8) dominate 58 of the box to (10, 0), and c (1, + # 2) adds 2; the infeasible design d adds nothing + progress = hypervolume_progress(results, objectives, (10, 0), step=2) + self.assertEqual(progress.index.tolist(), [2, 4]) + np.testing.assert_allclose(progress.values, [58.0, 60.0]) + last = hypervolume_progress(results, objectives, (10, 0), step=3) + self.assertEqual(last.index.tolist(), [3, 4]) + np.testing.assert_allclose(last.values, [60.0, 60.0]) + with self.assertRaises(ValueError): + hypervolume_progress(results, objectives, (10, 0), step=0) + + +class TestMissingObjectives(unittest.TestCase): + """ + Unit tests for designs with missing objectives. + """ + + def test_not_efficient(self): + """A design with a missing objective is not efficient, and dominates none.""" + summary = pd.DataFrame( + {"design": list("abc"), "x": [1.0, np.nan, 2.0], "y": [1.0, 0.0, 0.0]} + ) + objectives = {"x": "min", "y": "min"} + self.assertEqual(list(pareto_front(summary, objectives)), [True, False, True]) + self.assertEqual(list(pareto_ranks(summary, objectives)), [0, 1, 0]) + self.assertAlmostEqual(hypervolume(summary, objectives, {"x": 3, "y": 2}), 3.0) diff --git a/tests/tradespace/test_plotting.py b/tests/tradespace/test_plotting.py new file mode 100644 index 0000000..81e7c4d --- /dev/null +++ b/tests/tradespace/test_plotting.py @@ -0,0 +1,293 @@ +""" +Unit tests for plots of the results of trade studies. + +@author Paul T. Grogan +""" + +import unittest + +import numpy as np +import pandas as pd + +from tatc.tradespace import ( + exceedance, + pareto_front, + plot_designs, + plot_exceedance, + plot_means, + plot_progress, + plot_shares, + use_style, +) + +try: + import matplotlib + + matplotlib.use("Agg") + import matplotlib.pyplot as plt +except ImportError: # pragma: no cover + plt = None + + +@unittest.skipIf(plt is None, "requires matplotlib") +class TestPlots(unittest.TestCase): + """ + Unit tests for plots. + """ + + def setUp(self): + self.summary = pd.DataFrame( + { + "design": list("abcdef"), + "satellites": [1, 2, 2, 3, 4, 4], + "planes": [1, 1, 2, 1, 2, 1], + "sufficient": [10.0, 30.0, 20.0, 50.0, 60.0, 40.0], + } + ) + + def tearDown(self): + plt.close("all") + + def test_designs(self): + """Designs are colored by group, and the efficient ones ringed and labeled.""" + objectives = {"satellites": "min", "sufficient": "max"} + self.summary["pareto"] = pareto_front(self.summary, objectives) + ax = plot_designs( + self.summary, + "satellites", + "sufficient", + by="planes", + annotate="design", + names=lambda planes: f"{planes} planes", + jitter=0.2, + ) + # a collection of each group, and of the efficient designs + self.assertEqual(len(ax.collections), 3) + efficient = int(self.summary.pareto.sum()) + self.assertEqual(len(ax.collections[-1].get_offsets()), efficient) + self.assertEqual( + sorted(t.get_text() for t in ax.texts), + sorted(self.summary.design[self.summary.pareto]), + ) + legend = [t.get_text() for t in ax.get_legend().get_texts()] + self.assertEqual(legend, ["1 planes", "2 planes", "Pareto-efficient"]) + # jitter shifts only the horizontal positions + offsets = np.concatenate([c.get_offsets() for c in ax.collections[:2]]) + self.assertTrue(np.all(np.abs(offsets[:, 0] - np.round(offsets[:, 0])) <= 0.2)) + # the front of the column `pareto` by default, or given rows + rows = pareto_front(self.summary, objectives) + plain = self.summary.drop(columns="pareto") + ax = plot_designs(plain, "satellites", "sufficient", front=rows) + self.assertEqual(len(ax.collections[-1].get_offsets()), efficient) + self.assertEqual(ax.get_xlabel(), "satellites") + # without the column, none + ax = plot_designs(plain, "satellites", "sufficient") + self.assertEqual(len(ax.collections), 1) + with self.assertRaisesRegex(ValueError, "efficient"): + plot_designs(self.summary, "satellites", "sufficient", front="best") + # labels of the efficient designs need a front + figures = len(plt.get_fignums()) + for frame, front in ((plain, "pareto"), (self.summary, None)): + with self.subTest(front=front): + with self.assertRaisesRegex(ValueError, "annotate"): + plot_designs( + frame, + "satellites", + "sufficient", + front=front, + annotate="design", + ) + self.assertEqual(len(plt.get_fignums()), figures) # before drawing + + def test_given_axes(self): + """Plots draw on given axes.""" + _, ax = plt.subplots() + self.assertIs(plot_designs(self.summary, "satellites", "sufficient", ax=ax), ax) + self.assertIsNone(ax.get_legend()) + + def test_progress(self): + """Searches are lines, labeled at their ends.""" + progress = { + "one": pd.Series([1.0, 2.0, 3.0], index=[10, 20, 30]), + "two": pd.Series([2.0, 2.5], index=[10, 20]), + } + ax = plot_progress(progress) + self.assertEqual(len(ax.lines), 2) + self.assertEqual([t.get_text() for t in ax.texts], ["one", "two"]) + self.assertEqual(ax.get_xlim()[0], 0) + + def test_means(self): + """Means over replicates, with bands, by group (feasible records only).""" + results = pd.DataFrame( + { + "satellites": [1, 1, 2, 2, 1, 2], + "sensor": ["a", "a", "a", "a", "b", "b"], + "feasible": [True, True, True, False, True, True], + "resolved": [1.0, 3.0, 4.0, np.nan, 5.0, 7.0], + } + ) + ax = plot_means(results, "satellites", "resolved", by="sensor") + self.assertEqual(len(ax.lines), 2) + self.assertEqual(len(ax.collections), 2) # the bands + np.testing.assert_allclose(ax.lines[0].get_ydata(), [2.0, 4.0]) + single = plot_means(results, "satellites", "resolved") + self.assertEqual(len(single.lines), 1) + + def test_exceedance(self): + """A matrix of the probabilities, in the order of the designs, labeled.""" + results = pd.DataFrame( + { + "design": ["a", "a", "b", "b", "c", "c"], + "replicate": [0, 1, 0, 1, 0, 1], + "cost": [1.0, 2.0, 1.5, 1.5, 3.0, 4.0], + "scenario": "nominal", + } + ) + compared = exceedance(results, "cost") + ax = plot_exceedance(compared, names={"a": "first"}) + matrix = ax.images[0].get_array() + self.assertEqual(matrix.shape, (3, 3)) + self.assertEqual(matrix[2, 0], 1.0) # c costs more than a + self.assertEqual(matrix[0, 1], 0.5) # a and b, each once + self.assertEqual( + [t.get_text() for t in ax.get_yticklabels()], ["first", "b", "c"] + ) + self.assertEqual(len(ax.figure.axes), 2) # with a color bar + twice = pd.concat([compared, compared.assign(scenario="other")]) + with self.assertRaises(ValueError): + plot_exceedance(twice) + + +@unittest.skipIf(plt is None, "requires matplotlib") +class TestHighlights(unittest.TestCase): + """ + Unit tests for plots of some designs over others. + """ + + def tearDown(self): + plt.close("all") + + def test_highlight(self): + """Highlighted designs are colored over the others, in gray.""" + summary = pd.DataFrame( + { + "x": [1.0, 2.0, 3.0, 4.0], + "y": [1.0, 2.0, 2.5, 4.0], + "pareto": [True, True, False, True], + } + ) + ax = plot_designs( + summary, + "x", + "y", + highlight=[True, False, True, False], + label="chosen", + others="the rest", + front=summary.pareto.to_numpy(), + front_label="true front", + colors={"a": "#123456"}, + ) + labels = [text.get_text() for text in ax.get_legend().get_texts()] + self.assertEqual(labels, ["the rest", "chosen", "true front"]) + self.assertEqual(len(ax.collections[1].get_offsets()), 2) + with self.assertRaises(ValueError): + plot_designs(summary, "x", "y", highlight=[True]) + + +@unittest.skipIf(plt is None, "requires matplotlib") +class TestShares(unittest.TestCase): + """ + Unit tests for plots of shares, groups of values, and the style. + """ + + def tearDown(self): + plt.close("all") + + def test_shares(self): + """Shares are grouped by factor or by metric, with their errors.""" + table = pd.DataFrame( + {"a": [0.6, 0.2], "b": [0.1, 0.5], "a se": [0.05, 0.02], "active": [1, 1]}, + index=pd.Index(["x", "y"], name="parameter"), + ) + ax = plot_shares(table, labels={"a": "first"}) + self.assertEqual(len(ax.patches), 4) # two factors, two metrics + self.assertEqual( + [text.get_text() for text in ax.get_legend().get_texts()], ["first", "b"] + ) + flipped = plot_shares( + table, groups="metrics", names={"x": "ex"}, horizontal=True + ) + self.assertEqual( + [label.get_text() for label in flipped.get_yticklabels()], ["a", "b"] + ) + with self.assertRaises(ValueError): + plot_shares(table, groups="other") + + def test_groups_of_values(self): + """Designs are colored by values given for their rows.""" + summary = pd.DataFrame({"x": [1.0, 2.0, 3.0], "y": [1.0, 2.0, 3.0]}) + ax = plot_designs(summary, "x", "y", by=[1, 1, 2], names={1: "one", 2: "two"}) + self.assertEqual( + [text.get_text() for text in ax.get_legend().get_texts()], ["one", "two"] + ) + + def test_missing_groups(self): + """Designs without a value of `by` are drawn in gray, named others.""" + from tatc.tradespace import GRAY # pylint: disable=import-outside-toplevel + from matplotlib.colors import ( # pylint: disable=import-outside-toplevel + to_rgba, + ) + + frame = pd.DataFrame( + { + "x": [1.0, 2.0, 3.0, 4.0], + "y": [1.0, 2.0, 3.0, 4.0], + "inclination": [50.0, 60.0, np.nan, np.nan], + "pareto": [False, False, True, True], + } + ) + ax = plot_designs(frame, "x", "y", by="inclination", front="pareto") + drawn = sum(len(c.get_offsets()) for c in ax.collections[:-1]) + self.assertEqual(drawn, len(frame)) + gray = ax.collections[-2] + self.assertEqual(len(gray.get_offsets()), 2) + np.testing.assert_allclose(gray.get_facecolor()[0][:3], to_rgba(GRAY)[:3]) + labels = [text.get_text() for text in ax.get_legend().get_texts()] + self.assertEqual(labels, ["50.0", "60.0", "other", "Pareto-efficient"]) + named = plot_designs(frame, "x", "y", by="inclination", others="sso") + labels = [text.get_text() for text in named.get_legend().get_texts()] + self.assertEqual(labels[-2:], ["sso", "Pareto-efficient"]) + # with highlights, the designs in gray share their name + both = plot_designs( + frame, + "x", + "y", + by="inclination", + highlight=[True, False, True, False], + others="the rest", + front=None, + ) + labels = [text.get_text() for text in both.get_legend().get_texts()] + self.assertEqual(labels, ["the rest", "50.0", "60.0"]) + # means of records without a value of `by`, in gray + results = pd.DataFrame( + { + "satellites": [1, 2, 1, 2], + "sensor": ["a", "a", None, None], + "resolved": [1.0, 2.0, 3.0, 4.0], + } + ) + ax = plot_means(results, "satellites", "resolved", by="sensor") + self.assertEqual(len(ax.lines), 2) + self.assertEqual(to_rgba(ax.lines[1].get_color()), to_rgba(GRAY)) + labels = [text.get_text() for text in ax.get_legend().get_texts()] + self.assertEqual(labels, ["a", "other"]) + + def test_style(self): + """The style of plots applies to the figures of the session.""" + import matplotlib as mpl # pylint: disable=import-outside-toplevel + + with mpl.rc_context(): + use_style() + self.assertFalse(mpl.rcParams["axes.spines.top"]) + self.assertTrue(mpl.rcParams["figure.constrained_layout.use"]) diff --git a/tests/tradespace/test_references.py b/tests/tradespace/test_references.py new file mode 100644 index 0000000..7943089 --- /dev/null +++ b/tests/tradespace/test_references.py @@ -0,0 +1,131 @@ +""" +Unit tests for reading designs: references to their values, dataclasses +configured from them, and functions given them. + +@author Paul T. Grogan +""" + +# pylint: disable=protected-access + +import dataclasses +import unittest + +from tatc.tradespace import ( + Choice, + DesignSpace, + Integer, + Real, + Uncertain, + configure, + value_of, +) +from tatc.tradespace.references import _given_design, _takes_design + +SPACE = DesignSpace( + altitude=Real(600e3, 700e3, step=100e3), + layout=DesignSpace(planes=Integer(1, 2), per_plane=Integer(1, 2)), + growth=Uncertain.uniform(1.0, 1.5), +) + + +@dataclasses.dataclass(frozen=True) +class _Policy: + """A policy of two fields.""" + + spares: int = 0 + years: float = 1.0 + + +class TestReferences(unittest.TestCase): + """ + Unit tests for references to the values of designs. + """ + + def test_value_of(self): + """References name values, paths of values, or compute them.""" + d = SPACE.enumerate()[0].realize(0) + self.assertEqual(value_of(d, "altitude"), d.altitude) + self.assertEqual(value_of(d, "layout.planes"), d.layout.planes) + self.assertEqual(value_of(d, lambda d: 2 * d.altitude), 2 * d.altitude) + self.assertIsNone(value_of(d, None)) + with self.assertRaises(KeyError): + value_of(d, "layout.other") + with self.assertRaises(TypeError): + value_of(d, 3) + + +class TestConfigure(unittest.TestCase): + """ + Unit tests for dataclasses configured from the values of designs. + """ + + def test_design(self): + """A dataclass is configured from a design, or a view of its values.""" + design = DesignSpace(spares=Integer(1, 2), other=Integer(0, 1)).enumerate()[-1] + self.assertEqual(configure(_Policy(), design), _Policy(spares=2)) + self.assertEqual(configure(_Policy(), design.values), _Policy(spares=2)) + self.assertEqual(configure(_Policy(), design, years=2.0).years, 2.0) + self.assertEqual(configure(_Policy(), {"spares": 3}), _Policy(spares=3)) + with self.assertRaisesRegex(TypeError, "values of a design"): + configure(_Policy(), 3) + with self.assertRaisesRegex(TypeError, "dataclass instance"): + configure(_Policy, design) + with self.assertRaisesRegex(ValueError, "no fields"): + configure(_Policy(), design, other=1) + + def test_choice(self): + """A choice configures by the values of its branch, which must be a + group (or a fixed `None`).""" + space = DesignSpace( + policy=Choice( + spared=DesignSpace(spares=Integer(1, 2)), + plain=Integer(1, 2), + none=None, + ) + ) + spared = space.design({"policy": ["spared", {"spares": 2}]}) + self.assertEqual(configure(_Policy(), spared.policy), _Policy(spares=2)) + none = space.design({"policy": "none"}) + self.assertEqual(configure(_Policy(), none.policy), _Policy()) + plain = space.design({"policy": ["plain", 2]}) + with self.assertRaisesRegex(TypeError, "chose 'plain', whose value is 2"): + configure(_Policy(), plain.policy) + + +class TestGivenDesign(unittest.TestCase): + """ + Unit tests for functions given the design by a keyword. + """ + + def test_takes_design(self): + """A function takes the design if it has a parameter named `design` + that may be given by keyword.""" + + def positional(x, design): + return x, design + + def keyword(x, *, design=None): + return x, design + + def only_position(x, design, /): + return x, design + + self.assertTrue(_takes_design(positional)) + self.assertTrue(_takes_design(keyword)) + self.assertFalse(_takes_design(only_position)) + self.assertFalse(_takes_design(lambda x: x)) + self.assertFalse(_takes_design(lambda x, **kwargs: x)) + self.assertFalse(_takes_design(len)) + + def test_given_design(self): + """A function that takes the design is given it; others are not.""" + design = SPACE.enumerate()[0] + self.assertEqual( + _given_design(lambda x, design: (x, design.key), design)(1), + (1, design.key), + ) + + def alone(x): + return x + + self.assertIs(_given_design(alone, design), alone) diff --git a/tests/tradespace/test_refinement.py b/tests/tradespace/test_refinement.py new file mode 100644 index 0000000..c5c3332 --- /dev/null +++ b/tests/tradespace/test_refinement.py @@ -0,0 +1,421 @@ +""" +Unit tests for adaptive replication. + +@author Paul T. Grogan +""" + +import unittest +import warnings + +import numpy as np +import pandas as pd + +from tatc.tradespace import ( + Across, + Criteria, + DesignSpace, + Fixed, + Infeasible, + Integer, + Quantile, + Study, + Uncertain, + pareto_probability, + refine, +) +from tatc.tradespace.refinement import _precise +from tatc.tradespace.tables import draw_resamples + +OBJECTIVES = {"cost": "min", "value": "max"} + + +def _study(replicates=5): + """Designs whose values are close to others' within noise for some costs.""" + space = DesignSpace( + cost=Integer(1, 8), + variant=Integer(0, 2), + noise=Uncertain.normal(0, 1), + ) + + def evaluate(d): + # variants 0 and 1 differ by a unit of noise; variant 2 is clearly worse + value = np.sqrt(d.cost) * 3 + {0: 0.0, 1: 1.0, 2: -3.0}[d.variant] + return {"cost": d.cost, "value": value + d.noise} + + # independent noise between designs, so that close designs are uncertain + return Study( + space, lambda d: d, evaluate, replicates=replicates, common_random_numbers=False + ) + + +class TestRefine(unittest.TestCase): + """ + Unit tests for adaptive replication. + """ + + def setUp(self): + self.study = _study() + self.designs = self.study.space.enumerate() + self.results = self.study.run(self.designs) + + def test_designs_of_results(self): + """Without designs, every design of the results may be refined; designs + may also be given by their keys.""" + given = refine(self.study, OBJECTIVES, self.results, self.designs) + rebuilt = refine(self.study, OBJECTIVES, self.results) + pd.testing.assert_frame_equal( + given.results.drop(columns="seconds"), + rebuilt.results.drop(columns="seconds"), + ) + self.assertEqual( + [d.key for d in rebuilt.candidates], [d.key for d in self.designs] + ) + # the designs selected for the next step: the efficient designs + summary = rebuilt.summary + self.assertEqual( + [d.key for d in rebuilt.designs], list(summary.design[summary.pareto]) + ) + self.assertEqual(rebuilt.criteria, given.criteria) + # the evaluations added, over every round + self.assertEqual(rebuilt.evaluations, len(rebuilt.results) - len(self.results)) + self.assertGreater(rebuilt.evaluations, 0) + keys = [d.key for d in self.designs[:4]] + some = refine(self.study, OBJECTIVES, self.results, keys) + added = some.results.iloc[len(self.results) :] + self.assertTrue(set(added.design) <= set(keys)) + self.assertIn("pareto_probability", some.summary.columns) + self.assertIn("variant", some.summary.columns) # the values of designs + + def test_refines_uncertain_designs(self): + """Replicates are added only to uncertain designs, which become fewer.""" + refinement = refine( + self.study, + OBJECTIVES, + self.results, + self.designs, + step=5, + max_rounds=6, + n_resamples=200, + ) + rounds = refinement.rounds + self.assertGreater(rounds.refined.iloc[0], 0) + replicates = refinement.results.groupby("design").replicate.nunique() + # the clearly worse variant is never refined + worse = [d.key for d in self.designs if d.variant == 2] + self.assertTrue((replicates[worse] == 5).all()) + self.assertGreater(replicates.max(), 5) + before = pareto_probability(self.results, OBJECTIVES, n_resamples=200) + uncertain_before = ( + (before.pareto_probability > 0.05) & (before.pareto_probability < 0.95) + ).sum() + summary = refinement.summary + unsettled = summary[summary.uncertain & ~summary.indifferent] + self.assertLess(len(unsettled), uncertain_before) + # far fewer evaluations than uniform replication to the same depth + uniform = replicates.max() * len(self.designs) + self.assertLess(len(refinement.results), 0.6 * uniform) + + def test_replicates_continue(self): + """Added replicates follow each design's own.""" + refinement = refine( + self.study, OBJECTIVES, self.results, self.designs, step=2, max_rounds=1 + ) + added = refinement.results.iloc[len(self.results) :] + self.assertTrue(set(added.replicate) <= {5, 6}) + self.assertFalse(refinement.results.duplicated(["design", "replicate"]).any()) + + def test_limits(self): + """Refinement stops at the most replicates of a design.""" + refinement = refine( + self.study, + OBJECTIVES, + self.results, + self.designs, + step=3, + max_replicates=8, + max_rounds=5, + ) + self.assertLessEqual( + refinement.results.groupby("design").replicate.nunique().max(), 8 + ) + self.assertEqual(refinement.rounds.refined.iloc[-1], 0) + with self.assertRaises(ValueError): + refine( + self.study, OBJECTIVES, self.results, self.designs, bounds=(0.9, 0.1) + ) + + def test_statistics(self): + """Refinement uses the statistics of the objectives.""" + refinement = refine( + self.study, + Criteria( + {"cost": "min", "value p25": "max"}, + statistics={"value p25": Quantile("value", 0.25)}, + ), + self.results, + self.designs, + max_rounds=1, + ) + self.assertIn("value p25", refinement.summary.columns) + + def test_tolerance(self): + """A tolerance settles designs that are within it of the front.""" + strict = pareto_probability(self.results, OBJECTIVES, n_resamples=300) + criteria = Criteria(OBJECTIVES, tolerances={"value": 2.0}) + tolerant = pareto_probability(self.results, criteria, n_resamples=300) + # designs efficient for sure, of the better variant (within 2 of each other) + self.assertGreater( + (tolerant.pareto_probability >= 0.95).sum(), + (strict.pareto_probability >= 0.95).sum(), + ) + refinement = refine( + self.study, criteria, self.results, self.designs, max_rounds=1 + ) + settled = refinement.summary.pareto_probability >= 0.95 + self.assertGreaterEqual( + settled.sum(), (tolerant.pareto_probability >= 0.95).sum() + ) + + def test_min_replicates(self): + """Designs with few replicates are refined whatever their probability.""" + space = DesignSpace( + x=Integer(0, 9), a=Uncertain.normal(0, 1), b=Uncertain.normal(0, 1) + ) + # equal designs, of which two replicates find some surely inefficient + study = Study( + space, + lambda d: d, + lambda d: {"a": d.a, "b": d.b}, + replicates=2, + common_random_numbers=False, + ) + designs = space.enumerate() + results = study.run(designs) + objectives = {"a": "min", "b": "min"} + before = pareto_probability(results, objectives, n_resamples=200) + self.assertTrue((before.pareto_probability == 0).any()) + with warnings.catch_warnings(): + warnings.simplefilter("ignore") + refinement = refine( + study, objectives, results, designs, step=3, max_rounds=1 + ) + replicates = refinement.results.groupby("design").replicate.nunique() + self.assertTrue((replicates >= 5).all()) + with self.assertRaises(ValueError): + refine(study, objectives, results, designs, max_replicates=3) + + def test_partial_step(self): + """The last step of a design adds the replicates left to its limit.""" + with warnings.catch_warnings(): + warnings.simplefilter("ignore") + refinement = refine( + self.study, + OBJECTIVES, + self.results, + self.designs, + step=4, + max_replicates=7, + max_rounds=3, + ) + replicates = refinement.results.groupby("design").replicate.nunique() + self.assertEqual(replicates.max(), 7) + self.assertTrue(set(replicates) <= {5, 7}) + + def test_warns_without_tolerance(self): + """Designs that remain uncertain without a tolerance give a warning, + at the call of the refinement.""" + with self.assertWarns(UserWarning) as context: + refine(self.study, OBJECTIVES, self.results, self.designs, max_rounds=1) + self.assertEqual(context.filename, __file__) + + def test_precision(self): + """A design about a tolerance from the front stops once precise enough.""" + space = DesignSpace(variant=Integer(0, 1), noise=Uncertain.normal(0, 1)) + # variant 1 is one tolerance below variant 0, with noise: whether it is + # within the tolerance of the front stays uncertain (with this seed) + study = Study( + space, + lambda d: d, + lambda d: {"cost": 1, "value": 10.0 - d.variant * (2.0 - d.noise)}, + replicates=5, + seed=2, + ) + designs = space.enumerate() + results = study.run(designs) + criteria = Criteria(OBJECTIVES, tolerances={"value": 2.0}) + + def refined(precision): + refinement = refine( + study, + criteria, + results, + designs, + step=5, + max_replicates=40, + precision=precision, + ) + replicates = refinement.results.groupby("design").replicate.nunique() + return refinement, replicates[designs[1].key] + + _, unlimited = refined(None) + self.assertEqual(unlimited, 40) + # a standard error below a tenth of the tolerance (0.2) takes about 25 + refinement, precise = refined(0.1) + self.assertGreaterEqual(precise, 20) + self.assertLessEqual(precise, 30) + summary = refinement.summary + self.assertEqual(summary.design[summary.indifferent].tolist(), [designs[1].key]) + self.assertFalse((summary.uncertain & ~summary.indifferent).any()) + self.assertEqual(refinement.rounds.indifferent.iloc[-1], 1) + with self.assertRaises(ValueError): + refine(study, criteria, results, designs, precision=0) + + def test_budget(self): + """A budget limits the evaluations, refining the least settled designs first.""" + with warnings.catch_warnings(): + warnings.simplefilter("ignore") + refinement = refine( + self.study, OBJECTIVES, self.results, self.designs, step=5, budget=12 + ) + nothing = refine( + self.study, OBJECTIVES, self.results, self.designs, budget=0 + ) + self.assertEqual(refinement.rounds.evaluations.sum(), 12) + replicates = refinement.results.groupby("design").replicate.nunique() + self.assertEqual(sorted(replicates[replicates > 5]), [7, 10, 10]) + # the designs whose probability was nearest 0.5 + before = pareto_probability(self.results, OBJECTIVES, n_resamples=500, seed=0) + before = before.sort_values("design") + distance = (before.pareto_probability - 0.5).abs() + nearest = before.design[distance.sort_values(kind="stable").index[:3]] + self.assertEqual(set(replicates[replicates > 5].index), set(nearest)) + self.assertEqual(len(nothing.results), len(self.results)) + + def test_budget_of_scenarios(self): + """A replicate of a study with scenarios spends an evaluation of the + budget in each scenario, as the refinement counts them.""" + space = DesignSpace( + cost=Integer(1, 6), + variant=Integer(0, 2), + shift=Fixed(0.0), + noise=Uncertain.normal(0, 1), + ) + + def evaluate(d): + value = np.sqrt(d.cost) * 3 + {0: 0.0, 1: 1.0, 2: -3.0}[d.variant] + return {"cost": d.cost, "value": value + d.shift + d.noise} + + study = Study( + space, + lambda d: d, + evaluate, + replicates=3, + common_random_numbers=False, + scenarios={"a": {}, "b": {"shift": 0.5}, "c": {"shift": -0.5}}, + ) + results = study.run(space.enumerate()) + criteria = Criteria(OBJECTIVES, across=Across(rule="mean")) + with warnings.catch_warnings(): + warnings.simplefilter("ignore") + refinement = refine( + study, criteria, results, budget=13, step=2, max_rounds=3 + ) + added = len(refinement.results) - len(results) + self.assertEqual(refinement.evaluations, added) + # four replicates of the budget's 13 evaluations, in each of 3 scenarios + self.assertEqual(added, 12) + + def test_precise(self): + """Designs are precise if each varying objective is within its tolerance.""" + probability = pd.DataFrame( + { + "cost": [1.0, 1.0, 1.0], + "cost se": [0.0, 0.0, 0.1], + "value": [100.0, 100.0, 100.0], + "value se": [1.0, 6.0, 1.0], + } + ) + # a tolerance of 10% of 100: precise below a standard error of 5 + criteria = Criteria(OBJECTIVES, tolerances={"value": "10%"}) + np.testing.assert_array_equal( + _precise(probability, criteria, 0.5), [True, False, False] + ) + np.testing.assert_array_equal( + _precise(probability, criteria, None), [False, False, False] + ) + np.testing.assert_array_equal( + _precise(probability, Criteria(OBJECTIVES), 0.5), [False, False, False] + ) + # an objective without a standard error does not vary + np.testing.assert_array_equal( + _precise(probability.drop(columns="cost se"), criteria, 0.5), + [True, False, True], + ) + # an unknown standard error is not precise + unknown = probability.assign(**{"value se": [np.nan, 1.0, np.nan]}) + np.testing.assert_array_equal( + _precise(unknown, criteria, 0.5), [False, True, False] + ) + + def test_partly_infeasible_quantile(self): + """A design infeasible in most replicates, judged by a quantile, is + refined while its efficiency is uncertain, although some resamples + draw none of its feasible replicates.""" + space = DesignSpace( + variant=Integer(0, 1), + noise=Uncertain.normal(0, 1), + gate=Uncertain.uniform(0, 1), + ) + + def evaluate(d): + if d.variant == 0 and d.gate > 0.25: + raise Infeasible("rarely feasible") + return {"value": 5.0 + 0.3 * d.variant + 2 * d.noise} + + study = Study(space, lambda d: d, evaluate, replicates=20, seed=3) + results = study.run(space.enumerate()) + rare = results[results.variant == 0] + feasible = rare.replicate[rare.feasible].to_numpy() + self.assertEqual(len(feasible), 5) # as many as min_replicates + # resamples of the first round that draw none of them + drawn = draw_resamples(20, 1000, np.random.default_rng(0)) + self.assertGreater((~np.isin(drawn, feasible).any(axis=1)).sum(), 0) + criteria = Criteria( + {"value p50": "max"}, + statistics=[Quantile("value", 0.5)], + tolerances={"value p50": 0.5}, + ) + first = pareto_probability(results, criteria, n_resamples=1000, seed=0) + first = first.set_index("variant") + self.assertTrue(np.isfinite(first.loc[0, "value p50 se"])) + self.assertTrue(0.05 < first.loc[0, "pareto_probability"] < 0.95) + with warnings.catch_warnings(): + warnings.simplefilter("ignore", UserWarning) + refinement = refine( + study, criteria, results, step=5, max_rounds=1, n_resamples=1000 + ) + self.assertEqual(refinement.rounds.indifferent.iloc[0], 0) + added = refinement.results.iloc[len(results) :] + self.assertIn(0, set(added.variant)) # the rare design is refined + + +class TestRefineInfeasible(unittest.TestCase): + """ + Unit tests for the refinement of results without a feasible design. + """ + + def test_no_feasible_design(self): + """Nothing is refined, and nothing is selected.""" + + def reject(design): + raise Infeasible("never") + + study = Study(_study().space, reject, lambda built: built, replicates=2) + with self.assertWarnsRegex(UserWarning, "feasible"): + results = study.run(study.space.enumerate()[:4]) + refinement = refine(study, OBJECTIVES, results, max_rounds=2, n_resamples=10) + self.assertTrue(refinement.summary.empty) + self.assertEqual(refinement.designs, []) + self.assertEqual(len(refinement.candidates), 4) + self.assertEqual(refinement.evaluations, 0) + self.assertEqual(len(refinement.results), len(results)) diff --git a/tests/tradespace/test_scenarios.py b/tests/tradespace/test_scenarios.py new file mode 100644 index 0000000..4a32f9e --- /dev/null +++ b/tests/tradespace/test_scenarios.py @@ -0,0 +1,528 @@ +""" +Unit tests for scenarios of studies and the robustness of designs across them. + +@author Paul T. Grogan +""" + +import importlib.util +import math +import tempfile +import unittest +from concurrent.futures import ThreadPoolExecutor +from pathlib import Path + +import numpy as np +import pandas as pd + +from tatc.tradespace import ( + Across, + Criteria, + DesignSpace, + Fixed, + Integer, + Requirement, + ResultStore, + Study, + Uncertain, + attribute_variance, + optimize_optuna, + optimize_pymoo, + pareto_front, + pareto_probability, + robustness, + summarize, +) +from tatc.tradespace.optimization import Evaluations + +HAS_OPTUNA = importlib.util.find_spec("optuna") is not None +HAS_PYMOO = importlib.util.find_spec("pymoo") is not None + +SPACE = DesignSpace(x=Integer(1, 3), level=Fixed(1.0), noise=Uncertain.uniform(0, 1)) +SCENARIOS = {"low": {}, "high": {"level": 3.0}, "pinned": {"noise": 0.5}} + + +def _evaluate(d): + return {"y": d.x * d.level + d.noise, "cost": float(d.x)} + + +class TestStudyScenarios(unittest.TestCase): + """ + Unit tests for studies in scenarios. + """ + + def setUp(self): + self.directory = tempfile.TemporaryDirectory() + self.path = Path(self.directory.name) / "results.sqlite" + self.calls = [] + + def tearDown(self): + self.directory.cleanup() + + def _study(self, scenarios=None, **options): + def evaluate(d): + self.calls.append((d.x, d.replicate)) + return _evaluate(d) + + return Study( + SPACE, lambda d: d, evaluate, replicates=2, scenarios=scenarios, **options + ) + + def test_results(self): + """Each design is evaluated in each scenario in each replicate.""" + results = self._study(SCENARIOS).run() + self.assertEqual(len(results), 3 * 3 * 2) + self.assertEqual(list(results.columns[:3]), ["design", "replicate", "scenario"]) + first = results[results.design == results.design.iloc[0]] + self.assertEqual( + list(zip(first.scenario, first.replicate)), + [(s, r) for s in SCENARIOS for r in range(2)], + ) + by = results.set_index(["design", "replicate", "scenario"]) + low, high = by.xs("low", level="scenario"), by.xs("high", level="scenario") + # the same uncertain parameters in every scenario + np.testing.assert_array_equal(low.noise, high.noise) + np.testing.assert_allclose(high.y - low.y, 2 * low.cost) + pinned = by.xs("pinned", level="scenario") + self.assertTrue((pinned.noise == 0.5).all()) + # judged in each scenario + summary = summarize(results, Criteria({"y": "max"}, by="scenario")) + self.assertEqual(len(summary), 3 * 3) + with self.assertRaises(ValueError): + summarize(results, Criteria({"y": "max"})) + + def test_without_scenarios(self): + """A study without scenarios has no column of them.""" + results = self._study().run() + self.assertNotIn("scenario", results) + self.assertEqual(len(results), 3 * 2) + + def test_parallel(self): + """Studies in scenarios run in parallel as in sequence.""" + serial = self._study(SCENARIOS).run() + with ThreadPoolExecutor(2) as executor: + parallel = self._study(SCENARIOS, executor=executor).run() + columns = [c for c in serial.columns if c != "seconds"] + pd.testing.assert_frame_equal(serial[columns], parallel[columns]) + + def test_store(self): + """The evaluations of each scenario are stored by its values.""" + store = ResultStore(self.path, namespace="scenarios") + plain = self._study(store=store).run() + self.assertEqual(len(self.calls), 6) + # a scenario without values shares the evaluations without scenarios + self.calls.clear() + both = self._study({"low": {}, "high": {"level": 3.0}}, store=store).run() + self.assertEqual(len(self.calls), 6) + low = both[both.scenario == "low"].drop(columns="scenario") + columns = [c for c in plain.columns if c != "seconds"] + pd.testing.assert_frame_equal( + low[columns].reset_index(drop=True), plain[columns] + ) + # renamed scenarios are taken from the store, changed ones evaluated + self.calls.clear() + self._study({"base": {}, "raised": {"level": 3.0}}, store=store).run() + self.assertEqual(self.calls, []) + self._study({"raised": {"level": 4.0}}, store=store).run() + self.assertEqual(len(self.calls), 6) + # the evaluations of scenarios are stored without their names + self.calls.clear() + again = self._study(store=store).run() + self.assertEqual(self.calls, []) + self.assertNotIn("scenario", again) + + def test_attribution(self): + """The variance of designs in each scenario is attributed to their + uncertain parameters.""" + store = ResultStore(self.path, namespace="scenarios") + study = self._study(SCENARIOS, store=store) + a = attribute_variance( + study, ["y"], SPACE.enumerate(), sample_size=20, by=["scenario"] + ) + shares = a.shares.set_index(["design", "scenario"])["total"] + key = SPACE.enumerate()[0].key + # y varies by its noise alone, but for the scenario that pins it + self.assertAlmostEqual(shares[key, "low"], 1.0, delta=0.5) + self.assertAlmostEqual(shares[key, "high"], 1.0, delta=0.5) + self.assertTrue(np.isnan(shares[key, "pinned"])) + self.calls.clear() + attribute_variance( + study, ["y"], SPACE.enumerate(), sample_size=20, by=["scenario"] + ) + self.assertEqual(self.calls, []) + + def test_invalid(self): + """Scenarios set fixed values and uncertain parameters alone.""" + for scenarios in ({"a": {"x": 2}}, {"a": {"other": 1}}): + with self.subTest(scenarios=scenarios): + with self.assertRaises(ValueError): + self._study(scenarios) + for scenarios in ({"a": 1}, {1: {}}, [("a", {})]): + with self.subTest(scenarios=scenarios): + with self.assertRaises(TypeError): + self._study(scenarios) + with self.assertRaisesRegex(ValueError, "reserved"): + DesignSpace(x=Integer(1, 2), scenario=Fixed("a")) + + +def _results(rows): + """Results of one replicate of designs in scenarios, from (design, + scenario, perf, cost) rows (`None` for infeasible).""" + records = [ + { + "design": design, + "replicate": 0, + "scenario": scenario, + "feasible": perf is not None, + "perf": math.nan if perf is None else perf, + "cost": math.nan if cost is None else cost, + } + for design, scenario, perf, cost in rows + ] + return pd.DataFrame(records) + + +# in s1, B dominates C (A and B are efficient); in s2, B dominates A and C +RESULTS = _results( + [ + ("A", "s1", 10, 5), + ("B", "s1", 8, 3), + ("C", "s1", 7, 4), + ("A", "s2", 6, 5), + ("B", "s2", 9, 3), + ("C", "s2", 9, 4), + ] +) +OBJECTIVES = {"perf": "max", "cost": "min"} + + +class TestRobustness(unittest.TestCase): + """ + Unit tests for the robustness of designs across scenarios. + """ + + def _robustness(self, results=RESULTS, criteria=OBJECTIVES, **options): + return robustness(results, criteria, **options).set_index("design") + + def test_trace_and_regret(self): + """The share of scenarios in which designs are efficient, and their + regret: the improvement in every objective to match the front.""" + r = self._robustness() + # each objective in each scenario (cost is the same in every one) + self.assertEqual( + list(r.columns), + [ + "s1 perf", + "s2 perf", + "cost", + "pareto_trace", + "max_regret", + "s1 regret", + "s2 regret", + ], + ) + np.testing.assert_allclose(r["pareto_trace"], [0.5, 1.0, 0.0]) + # C in s1: 1 short of B in both objectives (3 short of A in perf) + np.testing.assert_allclose(r["s1 regret"], [0, 0, 1]) + # A in s2: 3 short of B in perf (2 in cost); C: 1 short of B in cost + np.testing.assert_allclose(r["s2 regret"], [3, 0, 1]) + np.testing.assert_allclose(r["max_regret"], [3, 0, 1]) + + def test_scale(self): + """Regret is in units of the scales of the objectives.""" + r = self._robustness(scale={"perf": 2}) + np.testing.assert_allclose(r["s1 regret"], [0, 0, 1]) + np.testing.assert_allclose(r["s2 regret"], [2, 0, 1]) + with self.assertRaises(ValueError): + self._robustness(scale={"other": 1}) + with self.assertRaises(ValueError): + self._robustness(scale={"perf": 0}) + + def test_tolerance(self): + """With tolerances, designs near the front are efficient, and regret + is in tolerances by default.""" + criteria = Criteria(OBJECTIVES, tolerances={"cost": 2}) + r = self._robustness(criteria=criteria) + np.testing.assert_allclose(r["pareto_trace"], [0.5, 1.0, 1.0]) + # A in s2: 3 short of B and C in perf + np.testing.assert_allclose(r["s2 regret"], [3, 0, 0]) + + def test_requirements(self): + """Designs that miss the requirements, or are infeasible, have + infinite regret.""" + criteria = Criteria(OBJECTIVES, requirements=[Requirement("perf", ">=", 7)]) + r = self._robustness(criteria=criteria) + self.assertEqual(r.loc["A", "s2 regret"], math.inf) + self.assertEqual(r.loc["A", "max_regret"], math.inf) + infeasible = pd.concat([RESULTS, _results([("D", "s1", None, None)])]) + infeasible = pd.concat( + [infeasible, _results([("D", "s2", 9, 2)])], ignore_index=True + ) + r = self._robustness(results=infeasible) + self.assertEqual(r.loc["D", "s1 regret"], math.inf) + self.assertEqual(r.loc["D", "s2 regret"], 0) + self.assertEqual(r.loc["D", "pareto_trace"], 0.5) + + def test_invalid(self): + """Robustness needs scenarios, and criteria by them alone.""" + with self.assertRaises(ValueError): + robustness(RESULTS.drop(columns="scenario"), OBJECTIVES) + with self.assertRaises(ValueError): + robustness(RESULTS, Criteria(OBJECTIVES, by="other")) + r = robustness(RESULTS, Criteria(OBJECTIVES, by="scenario")) + self.assertEqual(len(r), 3) + with self.assertRaises(ValueError): + robustness(RESULTS, Criteria(OBJECTIVES, across=Across())) + + def test_missing_objective(self): + """A design whose objective is missing in a scenario is not efficient + there, and its regret is infinite.""" + missing = RESULTS.copy() + missing.loc[(missing.design == "C") & (missing.scenario == "s2"), "perf"] = ( + math.nan + ) + r = self._robustness(results=missing) + self.assertEqual(r.loc["C", "s2 regret"], math.inf) + self.assertEqual(r.loc["C", "max_regret"], math.inf) + self.assertEqual(r.loc["C", "pareto_trace"], 0.0) + self.assertFalse(r[["max_regret", "s1 regret", "s2 regret"]].isna().any().any()) + + def test_design_values(self): + """Only objectives that are values of designs are given once; others + are given in each scenario, even if equal in every scenario.""" + rows = [] + for replicate, noise in enumerate((-1.0, 1.0)): + for design, (perf, cost) in {"A": (10, 5), "B": (8, 3)}.items(): + for scenario in ("s1", "s2"): + rows.append( + { + "design": design, + "replicate": replicate, + "scenario": scenario, + "feasible": True, + "perf": perf + noise, + "cost": cost, + } + ) + r = self._robustness(results=pd.DataFrame(rows)) + self.assertEqual(list(r.columns[:3]), ["s1 perf", "s2 perf", "cost"]) + np.testing.assert_allclose(r["s1 perf"], r["s2 perf"]) + # a cost that varies between replicates is not a value of the designs + varying = pd.DataFrame(rows).assign(cost=lambda f: f.cost + 0.1 * f.replicate) + r = self._robustness(results=varying) + self.assertEqual( + list(r.columns[:4]), ["s1 perf", "s2 perf", "s1 cost", "s2 cost"] + ) + + def test_scenario_column(self): + """The scenarios are the column of the criteria's `by`.""" + renamed = RESULTS.rename(columns={"scenario": "field"}) + r = robustness(renamed, Criteria(OBJECTIVES, by="field")).set_index("design") + pd.testing.assert_frame_equal(r, self._robustness()) + with self.assertRaises(ValueError): + robustness(renamed, OBJECTIVES) + with self.assertRaises(ValueError): + robustness(RESULTS, Criteria(OBJECTIVES, by=["scenario", "design"])) + + def test_study(self): + """The robustness of the designs of a study in scenarios.""" + results = Study(SPACE, lambda d: d, _evaluate, scenarios=SCENARIOS).run() + r = robustness(results, {"y": "max", "cost": "min"}) + # every design trades y against cost, in every scenario + np.testing.assert_allclose(r["pareto_trace"], 1.0) + self.assertEqual(len(r), 3) + # with the values of the designs, from which they are rebuilt + self.assertEqual(len(SPACE.designs_of(r)), 3) + + +class TestAcross(unittest.TestCase): + """ + Unit tests for criteria that combine statistics across scenarios. + """ + + def _summary(self, criteria, results=RESULTS): + summary = summarize(results, criteria) + summary["pareto"] = pareto_front(summary, criteria) + return summary.set_index("design") + + def test_worst(self): + """Each objective is its worst over the scenarios, and designs are + judged once.""" + summary = self._summary(Criteria(OBJECTIVES, across=Across())) + self.assertEqual(list(summary.index), ["A", "B", "C"]) + self.assertNotIn("scenario", summary.columns) + np.testing.assert_allclose(summary.perf, [6, 8, 7]) + np.testing.assert_allclose(summary.cost, [5, 3, 4]) + np.testing.assert_array_equal(summary.replicates, [1, 1, 1]) + self.assertEqual(list(summary.pareto), [False, True, False]) + + def test_mean(self): + """Each objective is its mean over the scenarios, weighted by their + weights (normalized over the scenarios of the results).""" + summary = self._summary(Criteria(OBJECTIVES, across=Across(rule="mean"))) + np.testing.assert_allclose(summary.perf, [8, 8.5, 8]) + weighted = Across(rule="mean", weights={"s1": 3, "s2": 1, "s3": 2}) + summary = self._summary(Criteria(OBJECTIVES, across=weighted)) + np.testing.assert_allclose(summary.perf, [9, 8.25, 7.5]) + self.assertEqual(list(summary.pareto), [True, True, False]) + unweighted = Across("scenario", "mean", {"s1": 1}) + with self.assertRaises(ValueError): + summarize(RESULTS, Criteria(OBJECTIVES, across=unweighted)) + + def test_requirements(self): + """A requirement is met by the combined statistic: in every scenario, + by the worst; a statistic of another name may be combined otherwise + than the objectives.""" + required = [Requirement("perf", ">=", 7)] + criteria = Criteria(OBJECTIVES, requirements=required, across=Across()) + summary = self._summary(criteria) + self.assertEqual(list(summary.meets_requirements), [False, True, True]) + criteria = Criteria( + OBJECTIVES, + statistics={"perf floor": "perf"}, + requirements=[Requirement("perf floor", ">=", 7)], + across=Across(rule="mean", rules={"perf floor": "worst"}), + ) + summary = self._summary(criteria) + np.testing.assert_allclose(summary.perf, [8, 8.5, 8]) + np.testing.assert_allclose(summary["perf floor"], [6, 8, 7]) + self.assertEqual(list(summary.meets_requirements), [False, True, True]) + self.assertAlmostEqual(summary.loc["A", "violation"], 1 / 7) + # the worst of a requirement to stay at most a value is its largest + below = Criteria( + {"perf": "max"}, + statistics={"spent": "cost"}, + requirements=[Requirement("spent", "<=", 4)], + across=Across(), + ) + summary = self._summary(below) + self.assertEqual(list(summary.meets_requirements), [False, True, True]) + + def test_incomplete(self): + """Designs without feasible results in every scenario are not judged.""" + more = _results( + [("D", "s1", 20, 1), ("E", "s1", 20, 1), ("E", "s2", None, None)] + ) + results = pd.concat([RESULTS, more], ignore_index=True) + summary = self._summary(Criteria(OBJECTIVES, across=Across()), results) + self.assertEqual(list(summary.index), ["A", "B", "C"]) + + def test_agrees_with_scenarios(self): + """The worst and the mean of the statistics in a study's scenarios.""" + results = Study( + SPACE, lambda d: d, _evaluate, replicates=3, scenarios=SCENARIOS + ).run() + objectives = {"y": "max", "cost": "min"} + by_scenario = summarize(results, Criteria(objectives, by="scenario")) + y = by_scenario.pivot(index="design", columns="scenario", values="y") + for rule, expected in (("worst", y.min(axis=1)), ("mean", y.mean(axis=1))): + criteria = Criteria(objectives, across=Across(rule=rule)) + summary = summarize(results, criteria).set_index("design") + np.testing.assert_allclose(summary.y, expected.loc[summary.index]) + probability = pareto_probability( + results, Criteria(objectives, across=Across()), n_resamples=20 + ).set_index("design") + np.testing.assert_allclose(probability.y, y.min(axis=1).loc[probability.index]) + np.testing.assert_array_equal(probability.replicates, 3) + self.assertTrue(probability.pareto.all()) + + def test_invalid(self): + """Rules, weights, and the statistics combined by their worst are + checked.""" + with self.assertRaises(ValueError): + Across(rule="best") + with self.assertRaises(ValueError): + Across(rules={"perf": "best"}) + with self.assertRaises(ValueError): + Across(rule="mean", weights={"s1": 0}) + with self.assertRaises(TypeError): + Across(column="") + with self.assertRaises(TypeError): + Criteria(OBJECTIVES, across="scenario") + with self.assertRaises(ValueError): + Criteria(OBJECTIVES, by="scenario", across=Across()) + with self.assertRaises(ValueError): + Criteria(OBJECTIVES, across=Across(rules={"other": "mean"})) + # a statistic without a direction is combined by its mean, unless a + # rule asks for its worst, which it has none of + extra = Criteria(OBJECTIVES, statistics={"extra": "perf"}, across=Across()) + summary = summarize(RESULTS, extra).set_index("design") + means = summarize(RESULTS, Criteria(OBJECTIVES, by="scenario")) + np.testing.assert_allclose( + summary.extra, means.groupby("design", sort=False).perf.mean() + ) + with self.assertRaises(ValueError): + Criteria( + OBJECTIVES, + statistics={"extra": "perf"}, + across=Across(rules={"extra": "worst"}), + ) + # an objective and a requirement that disagree on its worst + with self.assertRaises(ValueError): + Criteria( + OBJECTIVES, + requirements=[Requirement("perf", "<=", 9)], + across=Across(), + ) + with self.assertRaises(ValueError): + summarize( + RESULTS.drop(columns="scenario"), Criteria(OBJECTIVES, across=Across()) + ) + + +def _scenario_study(): + return Study(SPACE, lambda d: d, _evaluate, replicates=2, scenarios=SCENARIOS) + + +class TestSearchAcross(unittest.TestCase): + """ + Unit tests for searches across scenarios. + """ + + def test_evaluations(self): + """A search judges each design across the scenarios, as summaries do.""" + criteria = Criteria({"y": "max", "cost": "min"}, across=Across()) + evaluations = Evaluations(_scenario_study(), criteria) + designs = SPACE.enumerate() + values = evaluations.evaluate(designs) + summary = summarize(evaluations.results, criteria).set_index("design") + for design, (y, cost) in zip(designs, values): + self.assertAlmostEqual(y, summary.loc[design.key, "y"]) + self.assertAlmostEqual(cost, summary.loc[design.key, "cost"]) + self.assertEqual(len(evaluations.results), 3 * 2 * len(SCENARIOS)) + + def test_needs_across(self): + """A search of a study with several scenarios needs criteria across them.""" + evaluations = Evaluations(_scenario_study(), {"y": "max", "cost": "min"}) + with self.assertRaisesRegex(ValueError, "across"): + evaluations.evaluate(SPACE.enumerate()[:1]) + # a study with one scenario has one record per evaluation + one = Study(SPACE, lambda d: d, _evaluate, scenarios={"high": {"level": 3.0}}) + Evaluations(one, {"y": "max", "cost": "min"}).evaluate(SPACE.enumerate()) + + @unittest.skipUnless(HAS_PYMOO, "requires pymoo") + def test_pymoo(self): + """pymoo searches across the scenarios.""" + # pylint: disable-next=import-outside-toplevel + from pymoo.algorithms.moo.nsga2 import NSGA2 + + criteria = Criteria({"y": "max", "cost": "min"}, across=Across(rule="mean")) + search = optimize_pymoo( + _scenario_study(), + criteria, + algorithm=NSGA2(pop_size=4), + termination=("n_gen", 2), + seed=1, + ) + self.assertEqual(set(search.results.scenario), set(SCENARIOS)) + self.assertGreater(len(search.designs), 0) + + @unittest.skipUnless(HAS_OPTUNA, "requires optuna") + def test_optuna(self): + """Optuna searches across the scenarios.""" + criteria = Criteria({"y": "max", "cost": "min"}, across=Across()) + search = optimize_optuna(_scenario_study(), criteria, n_trials=6) + self.assertEqual(set(search.results.scenario), set(SCENARIOS)) + + +if __name__ == "__main__": + unittest.main() diff --git a/tests/tradespace/test_screening.py b/tests/tradespace/test_screening.py new file mode 100644 index 0000000..e8202af --- /dev/null +++ b/tests/tradespace/test_screening.py @@ -0,0 +1,209 @@ +""" +Unit tests for screening with analyses of increasing fidelity. + +@author Paul T. Grogan +""" + +import unittest +import warnings + +import numpy as np + +from tatc.tradespace import ( + Criteria, + DesignSpace, + Integer, + Requirement, + Study, + Uncertain, + confirm, + pareto_front, + refine, + screen, + summarize, +) + +OBJECTIVES = {"cost": "min", "value": "max"} + + +def _space(): + return DesignSpace( + a=Integer(1, 10), + b=Integer(1, 10), + noise=Uncertain.normal(0, 1), + constraints=[lambda d: d.a + d.b <= 16], + ) + + +def _metrics(design, noise_scale): + cost = design.a + design.b + value = np.sqrt(design.a) * np.log1p(design.b) + noise_scale * design.noise + return {"cost": cost, "value": value} + + +def _study(noise_scale, replicates): + # independent noise of each design, as of a cheap analysis + return Study( + _space(), + lambda d: _metrics(d, noise_scale), + lambda metrics: metrics, + replicates=replicates, + common_random_numbers=False, + ) + + +class TestScreen(unittest.TestCase): + """ + Unit tests for screening. + """ + + def setUp(self): + self.designs = _space().enumerate() + exact = summarize(_study(0, 1).run(self.designs), statistics=list(OBJECTIVES)) + self.front = set(exact.design[pareto_front(exact, OBJECTIVES)]) + + def test_keeps_whole_fronts(self): + """Each stage keeps whole fronts until it keeps enough designs.""" + screening = screen( + [_study(0.3, 1), _study(0, 1)], OBJECTIVES, self.designs, keep=20 + ) + first = screening.summaries[screening.summaries.stage == 0] + self.assertGreaterEqual(first.kept.sum(), 20) + last_rank = first[first.kept].pareto_rank.max() + self.assertTrue((first[first.pareto_rank <= last_rank].kept).all()) + self.assertFalse((first[first.pareto_rank > last_rank].kept).any()) + self.assertEqual(len(screening.designs), first.kept.sum()) + self.assertEqual(set(screening.history.stage), {0, 1}) + self.assertEqual(len(screening.summary), len(screening.designs)) + # the results of the last stage, which other steps continue + last = screening.history[screening.history.stage == 1] + self.assertEqual(len(screening.results), len(last)) + self.assertNotIn("stage", screening.results.columns) + self.assertEqual(screening.criteria.objectives, OBJECTIVES) + # the summaries of the stages are those of summarize, with spreads + noisy = screen( + [_study(0.3, 2), _study(0.3, 2)], OBJECTIVES, self.designs, keep=20 + ) + for column in ("value std", "value se"): + self.assertIn(column, noisy.summary.columns) + self.assertIn(column, noisy.summaries.columns) + self.assertNotIn("value se", screening.summary.columns) # without noise + + def test_finds_front(self): + """A tolerance of the noise of the first stage keeps the efficient designs.""" + stages = [_study(0.3, 1), _study(0, 1)] + # about two standard deviations of the noise of the first stage + cheap = Criteria(OBJECTIVES, tolerances={"value": 0.6}) + screening = screen(stages, [cheap, OBJECTIVES], self.designs, keep=0.1) + final = screening.summary + found = set(final.design[pareto_front(final, OBJECTIVES)]) + self.assertEqual(found, self.front) + self.assertLess(len(screening.designs), 0.6 * len(self.designs)) + # without a tolerance, the noise loses efficient designs + screening = screen(stages, OBJECTIVES, self.designs, keep=0.1) + final = screening.summary + found = set(final.design[pareto_front(final, OBJECTIVES)]) + self.assertLess(len(found & self.front), len(self.front)) + + def test_three_stages(self): + """Values of keep and criteria can be given for each stage.""" + screening = screen( + [_study(0.5, 1), _study(0.1, 2), _study(0, 1)], + [Criteria(OBJECTIVES, tolerances={"value": 1.0}), OBJECTIVES, OBJECTIVES], + self.designs, + keep=[0.5, 10], + ) + counts = screening.summaries.groupby("stage").size().tolist() + self.assertEqual(counts[0], len(self.designs)) + self.assertGreaterEqual(counts[1], 0.5 * counts[0]) + self.assertGreaterEqual(counts[2], 10) + with self.assertRaises(ValueError): + screen([_study(0, 1)] * 3, OBJECTIVES, self.designs, keep=[0.5]) + with self.assertRaises(ValueError): + screen([_study(0, 1)] * 3, [OBJECTIVES] * 2, self.designs) + with self.assertRaises(ValueError): + screen([_study(0, 1)], Criteria(OBJECTIVES, by="sensor"), self.designs) + + def test_next_steps(self): + """The results and designs of a screening continue in other steps.""" + full = _study(0, 2) + screening = screen([_study(0.3, 1), full], OBJECTIVES, self.designs, keep=10) + confirmation = confirm(full, OBJECTIVES, screening.results, screening.designs) + self.assertEqual( + {d.key for d in confirmation.designs}, {d.key for d in screening.designs} + ) + confirm(full, OBJECTIVES, screening.results) + with warnings.catch_warnings(): + warnings.simplefilter("ignore", UserWarning) # designs still uncertain + refinement = refine( + full, + OBJECTIVES, + screening.results, + screening.designs, + max_rounds=1, + n_resamples=20, + ) + self.assertEqual(len(refinement.candidates), len(screening.designs)) + + def test_keep(self): + """Designs are kept by a number of at least 1, or a share of at most 1.""" + stages = [_study(0, 1), _study(0, 1)] + designs = self.designs[:20] + everything = screen(stages, OBJECTIVES, designs, keep=1.0) + self.assertEqual(len(everything.designs), len(designs)) + for keep in (0, -1, 0.0, 1.5, -0.5, [0.5, 0]): + with self.subTest(keep=keep): + stages_of = ( + stages if not isinstance(keep, list) else stages + stages[:1] + ) + with self.assertRaises(ValueError): + screen(stages_of, OBJECTIVES, designs, keep=keep) + for keep in (True, "10", None): + with self.subTest(keep=keep): + with self.assertRaises(TypeError): + screen(stages, OBJECTIVES, designs, keep=keep) + + def test_criteria_tolerance(self): + """Every stage uses the tolerance of the criteria unless given its own.""" + stages = [_study(0.3, 1), _study(0, 1)] + criteria = Criteria(OBJECTIVES, tolerances={"value": 0.6}) + tolerant = screen(stages, criteria, self.designs, keep=0.1) + overridden = screen(stages, [OBJECTIVES, criteria], self.designs, keep=0.1) + self.assertGreater(len(tolerant.designs), len(overridden.designs)) + # the last stage ranks with the criteria's tolerance + final = tolerant.summary + self.assertTrue( + (final.pareto_rank == 0).sum() >= pareto_front(final, OBJECTIVES).sum() + ) + + +class TestScreenRequirements(unittest.TestCase): + """ + Unit tests for screening with requirements. + """ + + def test_misses_ranked_last(self): + """Designs that miss requirements are ranked after those that meet them.""" + space = DesignSpace(a=Integer(1, 6), noise=Uncertain.uniform(0, 1)) + study = Study( + space, + lambda d: d, + lambda d: {"cost": d.a, "value": d.a**0.5 + d.noise}, + replicates=2, + ) + screening = screen( + [study, study], + Criteria( + {"cost": "min", "value": "max"}, + requirements=[Requirement("cost", "<=", 3)], + ), + space.enumerate(), + keep=4, + ) + summaries = screening.summaries + first = summaries[summaries.stage == 0].set_index("design") + meets = first[first.meets_requirements] + misses = first[~first.meets_requirements] + self.assertGreater(misses.pareto_rank.min(), meets.pareto_rank.max()) + # the nearest miss (cost 4) is kept to fill four designs + self.assertEqual(sorted(first[first.kept].cost), [1, 2, 3, 4]) diff --git a/tests/tradespace/test_sensitivity.py b/tests/tradespace/test_sensitivity.py new file mode 100644 index 0000000..29015da --- /dev/null +++ b/tests/tradespace/test_sensitivity.py @@ -0,0 +1,108 @@ +""" +Unit tests for sensitivity analysis. + +@author Paul T. Grogan +""" + +import unittest + +import numpy as np +import pandas as pd + +from tatc.tradespace import main_effects, sensitivity + + +class TestSensitivity(unittest.TestCase): + """ + Unit tests for sensitivity analysis. + """ + + def setUp(self): + rng = np.random.default_rng(0) + a = np.repeat([1, 2, 3, 4], 50) + b = np.tile(["x", "y"], 100) + c = rng.uniform(0, 1, 200) + branch = np.where(np.arange(200) < 100, 1.0, np.nan) + self.frame = pd.DataFrame( + { + "a": a, + "b": b, + "c": c, + "branch": branch, + # a drives the metric, b a little, c not at all + "metric": 10 * a + + np.where(b == "x", 1.0, 0.0) + + rng.normal(0, 0.1, 200), + } + ) + + def test_shares(self): + """Variables that drive a metric explain most of its variance.""" + result = sensitivity(self.frame, ["a", "b", "c", "branch"], ["metric"]) + self.assertEqual(result.index[0], "a") + self.assertGreater(result.loc["a", "metric"], 0.95) + self.assertLess(result.loc["b", "metric"], 0.05) + self.assertLess(result.loc["c", "metric"], 0.1) + self.assertEqual(result.loc["branch", "active"], 0.5) + self.assertEqual(result.loc["a", "active"], 1.0) + # a variable with one level where active explains nothing within it + self.assertAlmostEqual(result.loc["branch", "metric"], 0) + # the correlation ratios are no smaller than the adjusted shares + ratios = sensitivity(self.frame, ["a", "b", "c"], ["metric"], adjusted=False) + self.assertTrue( + (ratios.metric >= result.loc[ratios.index, "metric"] - 1e-12).all() + ) + + def test_main_effects(self): + """Main effects are the means of the metric at each level.""" + effects = main_effects(self.frame, "a", "metric") + # a name is a list of one + pd.testing.assert_frame_equal( + sensitivity(self.frame, "a", "metric"), + sensitivity(self.frame, ["a"], ["metric"]), + ) + np.testing.assert_allclose(effects["mean"], [10.5, 20.5, 30.5, 40.5], atol=0.1) + self.assertEqual(list(effects["count"]), [50] * 4) + binned = main_effects(self.frame, "c", "metric", max_levels=4) + self.assertEqual(len(binned), 4) + + def test_order_of_bins(self): + """The bins of a numeric variable are in the order of their values.""" + summary = pd.DataFrame({"altitude": range(21), "cost": range(21)}) + effects = main_effects(summary, "altitude", "cost", max_levels=4) + self.assertTrue(effects.index.is_monotonic_increasing) + self.assertEqual(list(effects["mean"]), sorted(effects["mean"])) + self.assertEqual( + [interval.right for interval in effects.index], [5, 10, 15, 20] + ) + + def test_results_raise(self): + """The results of a study (a row per replicate) are not summaries.""" + results = pd.DataFrame( + {"design": ["x", "x", "y", "y"], "a": [1, 1, 2, 2], "metric": [1, 2, 3, 4]} + ) + with self.assertRaisesRegex(ValueError, "summarize"): + sensitivity(results, ["a"], ["metric"]) + with self.assertRaisesRegex(ValueError, "summarize") as context: + main_effects(results, "a", "metric") + # summaries of designs in groups give a row of each design per group + self.assertNotIn("Criteria", str(context.exception)) + + def test_irrelevant_variable(self): + """The adjusted share of a variable that does not matter is near 0.""" + rng = np.random.default_rng(1) + adjusted, ratios = [], [] + for _ in range(100): + frame = pd.DataFrame( + {"v": rng.integers(0, 10, 20), "m": rng.normal(size=20)} + ) + adjusted.append(sensitivity(frame, ["v"], ["m"]).loc["v", "m"]) + ratios.append( + sensitivity(frame, ["v"], ["m"], adjusted=False).loc["v", "m"] + ) + # (k - 1) / (n - 1) = 9 / 19 by chance alone + self.assertGreater(np.mean(ratios), 0.35) + self.assertLess(np.mean(adjusted), 0.1) + # no more designs than levels + frame = pd.DataFrame({"v": [1, 2, 3], "m": [1.0, 2.0, 4.0]}) + self.assertTrue(np.isnan(sensitivity(frame, ["v"], ["m"]).loc["v", "m"])) diff --git a/tests/tradespace/test_space.py b/tests/tradespace/test_space.py new file mode 100644 index 0000000..4b4694d --- /dev/null +++ b/tests/tradespace/test_space.py @@ -0,0 +1,1072 @@ +""" +Unit tests for design spaces. + +@author Paul T. Grogan +""" + +import math +import unittest + +import pandas as pd + +from tatc.tradespace import ( + Categorical, + Choice, + Derived, + DesignSpace, + Fixed, + Infeasible, + Integer, + Real, + Repeat, + Uncertain, +) +from tatc.tradespace.space import RESERVED_NAMES, STATUS_COLUMNS +from tatc.tradespace.values import generic_path, is_number + + +def _planes_space(): + """Planes spread over 12 hours with a random phase, for at most 6 satellites.""" + return DesignSpace( + per_plane=Integer(1, 6), + planes=Repeat( + DesignSpace( + crossing=Derived(lambda d: (13.5 + 12 * d.index / d.planes.count) % 24), + phase=Uncertain.uniform(0, 360), + ), + count=Integer(1, 6), + ), + constraints=[lambda d: d.planes.count * d.per_plane <= 6], + ) + + +def _hierarchical_space(): + """A choice between Walker constellations and unordered sun-synchronous planes.""" + plane = DesignSpace( + crossing=Real(0, 18, step=6), + satellites=Integer(1, 2), + payload=Categorical(["atms", "cris"]), + phase=Uncertain.uniform(0, 360), + ) + return DesignSpace( + altitude=Real(700e3, 850e3, step=75e3), + layout=Choice( + walker=DesignSpace( + inclination=Real(40, 70, step=15), + planes=Integer(1, 3), + per_plane=Integer(1, 2), + relative_spacing=Integer(0, lambda d: d.planes - 1), + ), + sso=DesignSpace(planes=Repeat(plane, count=Integer(1, 2), ordered=False)), + ), + ) + + +class TestVariables(unittest.TestCase): + """ + Unit tests for design variables. + """ + + def test_levels(self): + """Discrete variables enumerate their levels, inclusive of the upper bound.""" + space = DesignSpace( + a=Real(0, 1, step=0.1), b=Integer(2, 10, step=4), c=Categorical("xyz") + ) + designs = space.enumerate() + self.assertEqual(len(designs), 11 * 3 * 3) + self.assertEqual(sorted({d.a for d in designs})[-1], 1.0) + self.assertEqual(sorted({d.b for d in designs}), [2, 6, 10]) + self.assertIsInstance(designs[0].b, int) + + def test_continuous_cannot_enumerate(self): + """A continuous variable can be sampled but not enumerated.""" + space = DesignSpace(a=Real(1, 100, log=True)) + with self.assertRaises(ValueError): + space.enumerate() + values = [d.a for d in space.sample(50, seed=0)] + self.assertTrue(all(1 <= v <= 100 for v in values)) + self.assertEqual(len(set(values)), 50) + + def test_dependent_bounds(self): + """Bounds may depend on earlier values.""" + space = DesignSpace( + planes=Integer(1, 4), spacing=Integer(0, lambda d: d.planes - 1) + ) + self.assertEqual(space.size(), 1 + 2 + 3 + 4) + + def test_empty_domain_is_infeasible(self): + """A variable without levels makes a design infeasible.""" + space = DesignSpace(a=Integer(0, 2), b=Integer(1, lambda d: d.a)) + self.assertEqual( + {(d.a, d.b) for d in space.enumerate()}, {(1, 1), (2, 1), (2, 2)} + ) + + def test_reserved_names(self): + """Names used by views cannot be children.""" + with self.assertRaises(ValueError): + DesignSpace(index=Integer(0, 1)) + + def test_representation(self): + """A logarithmic variable says so in its representation.""" + self.assertEqual( + repr(Real(1, 10, log=True)), "Real(1, 10, step=None, log=True)" + ) + self.assertEqual(repr(Real(1, 10)), "Real(1, 10, step=None)") + + +class TestDesignSpace(unittest.TestCase): + """ + Unit tests for design spaces. + """ + + def test_constraints(self): + """Constraints remove designs.""" + designs = _planes_space().enumerate() + self.assertEqual(len(designs), 14) + pairs = {(d.planes.count, d.per_plane) for d in designs} + self.assertIn((2, 3), pairs) + self.assertNotIn((2, 4), pairs) + + def test_derived_and_scope(self): + """Derived values resolve names in enclosing groups and the item index.""" + design = [d for d in _planes_space().enumerate() if d.planes.count == 4][0] + self.assertEqual([p.crossing for p in design.planes], [13.5, 16.5, 19.5, 22.5]) + self.assertEqual(design.planes[2].index, 2) + self.assertEqual(len(design.planes), 4) + + def test_hierarchical_enumeration(self): + """Choices and repetitions enumerate the designs of each branch.""" + designs = _hierarchical_space().enumerate() + walker = [d for d in designs if d.layout.choice == "walker"] + sso = [d for d in designs if d.layout.choice == "sso"] + # 3 altitudes x 3 inclinations x (1 x 2 + 2 x 2 + 3 x 2) (planes x spacing x per plane) + self.assertEqual(len(walker), 3 * 3 * 12) + # 16 plane designs (4 x 2 x 2): one plane, or two unordered planes (16 x 17 / 2) + self.assertEqual(len(sso), 3 * (16 + 136)) + self.assertEqual(len({d.key for d in designs}), len(designs)) + + def test_unordered_items_are_canonical(self): + """Designs that differ only in the order of unordered items are one design.""" + space = _hierarchical_space() + first = {"crossing": 0.0, "satellites": 1, "payload": "atms"} + second = {"crossing": 6.0, "satellites": 2, "payload": "cris"} + a = space.design( + {"altitude": 700e3, "layout": ["sso", {"planes": [first, second]}]} + ) + b = space.design( + {"altitude": 700e3, "layout": ["sso", {"planes": [second, first]}]} + ) + self.assertEqual(a.key, b.key) + self.assertEqual( + [p.payload for p in a.layout.planes], [p.payload for p in b.layout.planes] + ) + self.assertEqual(a.decisions, b.decisions) + + def test_flat(self): + """Flat values are keyed by path, without fixed values.""" + space = DesignSpace(fixed=3, layout=Choice(a=DesignSpace(x=Integer(1, 1)))) + self.assertEqual(space.enumerate()[0].flat(), {"layout": "a", "layout.a.x": 1}) + flat = _planes_space().enumerate()[1].flat() + self.assertEqual(flat["planes.count"], 2) + self.assertEqual(flat["planes[1].crossing"], 19.5) + self.assertTrue(math.isnan(flat["planes[1].phase"])) + + def test_design_from_decisions(self): + """A design is rebuilt from its decisions, and its constraints are checked.""" + space = _planes_space() + for design in space.enumerate(): + self.assertEqual(space.design(design.decisions).key, design.key) + with self.assertRaises(Infeasible): + space.design({"per_plane": 4, "planes": [{}, {}]}) + + def test_unknown_decisions(self): + """Decisions of no children (such as a misspelt name) raise, also + within groups, as do decisions of a group that are not a mapping.""" + space = DesignSpace( + a=Integer(1, 3), + b=Integer(1, 2), + g=DesignSpace(c=Integer(0, 1)), + parts=Repeat(DesignSpace(d=Integer(0, 1)), count=1), + ) + good = {"a": 1, "b": 2, "g": {"c": 0}, "parts": [{"d": 1}]} + self.assertEqual(space.design(good).decisions, good) + with self.assertRaisesRegex( + ValueError, r"no children of the design space.*typo" + ): + space.design({**good, "typo": 7}) + with self.assertRaisesRegex(ValueError, r"no children of g: \['e'\]"): + space.design({**good, "g": {"c": 0, "e": 1}}) + with self.assertRaisesRegex(ValueError, r"no children of parts\[0\]"): + space.design({**good, "parts": [{"d": 1, "e": 1}]}) + with self.assertRaisesRegex(ValueError, "a mapping"): + space.design({**good, "g": [0]}) + + def test_single_constraint(self): + """A design space (or an extension) takes a single constraint.""" + space = DesignSpace(lambda d: d.a < 3, a=Integer(1, 3)) + self.assertEqual([d.a for d in space.enumerate()], [1, 2]) + keyword = DesignSpace(a=Integer(1, 3), constraints=lambda d: d.a < 3) + self.assertEqual(len(keyword.enumerate()), 2) + extended = space.extend(lambda d: d.a > 1) + self.assertEqual([d.a for d in extended.enumerate()], [2]) + with self.assertRaisesRegex(TypeError, "a constraint is a callable"): + DesignSpace([lambda d: True, 3], a=Integer(1, 3)) + + def test_sample(self): + """Sampled designs are feasible, and Latin hypercube samples are stratified.""" + space = _planes_space() + keys = {d.key for d in space.enumerate()} + for method in ("lhs", "random"): + designs = space.sample(30, method=method, seed=3) + self.assertEqual(len(designs), 30) + self.assertTrue({d.key for d in designs} <= keys) + stratified = DesignSpace(a=Real(0, 1)).sample(10, seed=0) + self.assertEqual(sorted(int(d.a * 10) for d in stratified), list(range(10))) + + def test_constraint_violation(self): + """Constraints may give the amount of their violation.""" + space = DesignSpace( + a=Integer(0, 5), constraints=[lambda d: d.a - 3, lambda d: d.a != 1] + ) + self.assertEqual([d.a for d in space.enumerate()], [0, 2, 3]) + with self.assertRaises(Infeasible) as context: + space.design({"a": 5}) + self.assertEqual(context.exception.violation, 2) + with self.assertRaises(Infeasible) as context: + space.design({"a": 1}) + self.assertEqual(context.exception.violation, 1) + + def test_infeasible_sample(self): + """Sampling gives up on a space without feasible designs.""" + space = DesignSpace(a=Integer(0, 1), constraints=[lambda d: False]) + with self.assertRaises(Infeasible): + space.sample(1, max_tries=5) + self.assertEqual(space.enumerate(), []) + + +class TestRealize(unittest.TestCase): + """ + Unit tests for realizing designs. + """ + + def test_common_random_numbers(self): + """Uncertain parameters at the same path are common to every design.""" + designs = _planes_space().enumerate() + phases = {d.realize(2, seed=7).planes[0].phase for d in designs} + self.assertEqual(len(phases), 1) + other = designs[0].realize(3, seed=7).planes[0].phase + self.assertNotIn(other, phases) + independent = { + d.realize(2, seed=7, common_random_numbers=False).planes[0].phase + for d in designs + } + self.assertEqual(len(independent), len(designs)) + + def test_realize_is_reproducible(self): + """Realizing a design again gives the same values, and keeps its key.""" + design = _planes_space().enumerate()[5] + a, b = design.realize(1), design.realize(1) + self.assertEqual(a.flat(), b.flat()) + self.assertEqual(a.key, design.key) + self.assertEqual(a.replicate, 1) + self.assertTrue(all(0 <= p.phase < 360 for p in a.planes)) + + def test_uncertain_choice(self): + """Uncertain choices are drawn from their options.""" + space = DesignSpace(epoch=Uncertain.choice(["jan", "jul"])) + design = space.enumerate()[0] + self.assertIsNone(design.epoch) + self.assertEqual({design.realize(r).epoch for r in range(20)}, {"jan", "jul"}) + + def test_scenario(self): + """A scenario gives fixed values and uncertain parameters other values.""" + space = DesignSpace( + a=Integer(1, 2), + level=Fixed(1.0), + double=Derived(lambda d: 2 * d.level), + u=Uncertain.uniform(0, 1), + v=Uncertain.uniform(0, 1), + parts=Repeat(DesignSpace(k=Fixed(1)), count=2), + ) + design = space.enumerate()[0] + plain = design.realize(3, seed=5) + scenario = {"level": 3.0, "u": 0.25, "parts[*].k": 7} + changed = design.realize(3, seed=5, overrides=scenario) + self.assertEqual((changed.level, changed.double, changed.u), (3.0, 6.0, 0.25)) + self.assertEqual([part.k for part in changed.parts], [7, 7]) + # other parameters are drawn as without the scenario + self.assertEqual(changed.v, plain.v) + self.assertEqual((plain.level, plain.double), (1.0, 2.0)) + self.assertEqual(design.realize(3, seed=5, overrides={}).flat(), plain.flat()) + for values in ({"a": 2}, {"double": 1.0}, {"w": 1}): + with self.subTest(values=values): + with self.assertRaises(ValueError): + design.realize(3, overrides=values) + + def test_uncertain_paths(self): + """Uncertain parameters are listed by path, with [*] for items.""" + self.assertEqual(_planes_space().uncertain_paths(), ["planes[*].phase"]) + space = DesignSpace( + seed=Uncertain.seed(), + layout=Choice( + a=DesignSpace(phase=Uncertain.uniform(0, 1)), + b=DesignSpace(planes=Repeat(Uncertain.uniform(0, 1), count=2)), + ), + ) + self.assertEqual( + space.uncertain_paths(), ["seed", "layout.a.phase", "layout.b.planes[*]"] + ) + self.assertEqual(DesignSpace(a=Integer(1, 2)).uncertain_paths(), []) + + def test_uncertain_values(self): + """A design gives the values of the uncertain parameters it draws, by + path: of the branches it chooses and of its items.""" + space = DesignSpace( + planes=Repeat( + DesignSpace(phase=Uncertain.uniform(0, 1), k=Integer(0, 1)), + count=Integer(1, 2), + ), + layout=Choice( + drawn=DesignSpace(u=Uncertain.normal(0, 1)), plain=Integer(1, 2) + ), + seed=Uncertain.seed(), + fixed=1.0, + ) + design = space.design( + {"planes": [{"k": 0}, {"k": 1}], "layout": ["drawn", None]} + ) + realized = design.realize(3) + values = realized.uncertain_values() + self.assertEqual( + list(values), + ["planes[0].phase", "planes[1].phase", "layout.drawn.u", "seed"], + ) + self.assertEqual(values["planes[1].phase"], realized.planes[1].phase) + self.assertEqual(values["seed"], realized.seed) + # nominal values of a design that is not realized + self.assertTrue(math.isnan(design.uncertain_values()["layout.drawn.u"])) + # not those of branches it does not choose + plain = space.design({"planes": [{"k": 0}], "layout": ["plain", 1]}) + self.assertEqual(list(plain.uncertain_values()), ["planes[0].phase", "seed"]) + # with the values of a scenario + overridden = design.realize(3, overrides={"seed": 7}, scenario="s") + self.assertEqual(overridden.uncertain_values()["seed"], 7) + + def test_negative_indices(self): + """Replicates and the offsets of shifts are non-negative integers.""" + design = _planes_space().enumerate()[0] + with self.assertRaisesRegex(ValueError, "a replicate must be a non-negative"): + design.realize(-1) + with self.assertRaisesRegex(ValueError, "a replicate must be a non-negative"): + design.realize(1.5) + with self.assertRaisesRegex(ValueError, "offset of 'planes"): + design.realize(3, shift={"planes[*].phase": -1}) + shifted = design.realize(0, shift={"planes[*].phase": 3}) + self.assertEqual(shifted.planes[0].phase, design.realize(3).planes[0].phase) + + def test_shift(self): + """A shift draws named parameters as in other replicates.""" + space = DesignSpace( + u=Uncertain.uniform(0, 1), + v=Uncertain.uniform(0, 1), + planes=Repeat(DesignSpace(phase=Uncertain.uniform(0, 360)), count=2), + ) + design = space.enumerate()[0] + mixed = design.realize(3, seed=5, shift={"u": 10, "planes[*].phase": 1}) + self.assertEqual(mixed.u, design.realize(13, seed=5).u) + self.assertEqual(mixed.v, design.realize(3, seed=5).v) + self.assertEqual( + [p.phase for p in mixed.planes], + [p.phase for p in design.realize(4, seed=5).planes], + ) + self.assertEqual(mixed.replicate, 3) + self.assertEqual( + design.realize(3, shift={"u": 0}).flat(), design.realize(3).flat() + ) + independent = design.realize(3, common_random_numbers=False, shift={"u": 10}) + self.assertEqual( + independent.u, design.realize(13, common_random_numbers=False).u + ) + with self.assertRaises(ValueError): + design.realize(3, shift={"w": 1}) + with self.assertRaises(ValueError): + design.realize(3, shift={"planes[0].phase": 1}) + + +class TestEnumeration(unittest.TestCase): + """ + Unit tests for the enumeration of unordered repetitions, which walks only + one order of their items. + """ + + @staticmethod + def _every_walk(space): + """Enumerates by walking every order of the items.""" + # pylint: disable=import-outside-toplevel,protected-access + from tatc.tradespace.walks import _Context, _Odometer + + odometer = _Odometer() + ctx = _Context(choose=odometer.choose) + designs = {} + while True: + try: + design = space._design(ctx) + designs.setdefault(design.key, design) + except Infeasible: + pass + if not odometer.advance(): + return list(designs.values()) + + def test_same_designs(self): + """Walking one order of unordered items gives the same designs.""" + spaces = [ + DesignSpace( + parts=Repeat( + DesignSpace( + kind=Choice( + a=DesignSpace(x=Integer(0, 2)), + b=DesignSpace(y=Categorical(["p", "q"]), z=Integer(5, 12)), + ) + ), + count=Integer(0, 3), + ordered=False, + ) + ), + DesignSpace( + outer=Repeat( + DesignSpace( + inner=Repeat( + DesignSpace(v=Integer(0, 2)), + count=Integer(1, 2), + ordered=False, + ) + ), + count=Integer(1, 2), + ordered=False, + ), + constraints=[lambda d: len(d.outer) < 2 or d.outer[0].inner[0].v != 1], + ), + ] + for space in spaces: + expected = self._every_walk(space) + designs = space.enumerate() + self.assertEqual([d.key for d in designs], [d.key for d in expected]) + self.assertEqual([d.flat() for d in designs], [d.flat() for d in expected]) + self.assertEqual(space.size(), len(expected)) + + +class TestDesignsOf(unittest.TestCase): + """ + Unit tests for designs rebuilt from data frames of their values, and for + designs of extended design spaces. + """ + + def setUp(self): + self.space = _hierarchical_space() + self.designs = self.space.enumerate() + # values by path, as in the results of a study (with missing values of + # the branches a design does not choose, and integers as floats) + self.frame = pd.DataFrame( + [{"design": d.key, **d.realize(0).flat()} for d in self.designs] + ) + + def test_round_trip(self): + """Designs rebuilt from their values are the designs.""" + rebuilt = self.space.designs_of(self.frame) + self.assertEqual([d.key for d in rebuilt], [d.key for d in self.designs]) + self.assertEqual([d.flat() for d in rebuilt][5], self.designs[5].flat()) + # from a summary indexed by design, of some keys, in their order + keys = [self.designs[3].key, self.designs[1].key] + some = self.space.designs_of(self.frame.set_index("design"), keys=keys) + self.assertEqual([d.key for d in some], keys) + # a design for each row, aligned with the rows (as of results of + # several rows of a design), each design rebuilt once + twice = pd.concat([self.frame, self.frame], ignore_index=True) + aligned = self.space.designs_of(twice) + self.assertEqual(list(aligned.index), list(twice.index)) + self.assertEqual(list(aligned.map(lambda d: d.key)), list(twice.design)) + self.assertIs(aligned.iloc[0], aligned.iloc[len(self.frame)]) + # without keys, every row's design + bare = self.frame.drop(columns="design") + rebuilt = self.space.designs_of(pd.concat([bare, bare])) + self.assertEqual(len(rebuilt), 2 * len(self.designs)) + + def test_errors(self): + """Rows without the values of decisions, or of other designs, raise.""" + with self.assertRaises(KeyError): + self.space.designs_of(self.frame, keys=["unknown"]) + with self.assertRaisesRegex(ValueError, "no value of altitude"): + self.space.designs_of(self.frame.drop(columns="altitude")) + other = self.frame.assign(design=self.frame.design.iloc[::-1].to_numpy()) + with self.assertRaisesRegex(ValueError, "another design"): + self.space.designs_of(other) + wrong = self.frame.assign(altitude=1.0) + with self.assertRaisesRegex(ValueError, "not a level"): + self.space.designs_of(wrong) + + def test_extend(self): + """Extended design spaces replace or add children, and keep constraints.""" + space = DesignSpace(a=Integer(1, 3), b=2.0, constraints=[lambda d: d.a <= 2]) + extended = space.extend(c=Categorical(["x", "y"]), b=Integer(0, 1)) + self.assertEqual(list(extended.children), ["a", "b", "c"]) + self.assertEqual(len(extended.enumerate()), 2 * 2 * 2) + self.assertEqual(list(space.children), ["a", "b"]) # unchanged + design = space.enumerate()[1] + derived = extended.design(design, b=1, c="y") + self.assertEqual((derived.a, derived.b, derived.c), (2, 1, "y")) + # a design of a group's own space gives its decisions + group = DesignSpace(k=Integer(0, 1)) + nested = space.extend(g=group).design(design, g=group.enumerate()[1]) + self.assertEqual(nested.g.k, 1) + with self.assertRaisesRegex(ValueError, "no children"): + extended.design(design, z=1) + with self.assertRaises(Infeasible): + extended.design({"a": 3, "b": 0, "c": "x"}) + + def test_enumerate_extensions(self): + """The extensions of designs are those of every combination of the + decisions they lack, in their order, without the infeasible ones.""" + space = DesignSpace(a=Integer(1, 3)) + extended = space.extend( + c=Categorical(["x", "y"]), + d=Repeat(Integer(0, 1), count=Integer(1, 2), ordered=False), + constraints=[lambda d: not (d.a == 3 and d.c == "y")], + ) + bases = space.enumerate() + extensions = extended.enumerate(bases[::-1]) + expected = [ + extended.design(base, c=c, d=d) + for base in bases[::-1] + for c in ("x", "y") + for d in ([0], [1], [0, 0], [0, 1], [1, 1]) + if not (base.a == 3 and c == "y") + ] + self.assertEqual([d.key for d in extensions], [d.key for d in expected]) + self.assertTrue(all(d.space is extended for d in extensions)) + # every design of the space, from the designs of its unextended space + self.assertEqual( + {d.key for d in extended.enumerate(bases)}, + {d.key for d in extended.enumerate()}, + ) + # a design of the space itself, and repeated designs, once + self.assertEqual(extended.enumerate([expected[0]] * 2), [expected[0]]) + self.assertEqual(extended.enumerate([]), []) + # decisions of other children, or of other levels + with self.assertRaisesRegex(ValueError, "no children"): + space.enumerate([expected[0]]) + with self.assertRaisesRegex(ValueError, "not a level"): + DesignSpace(a=Integer(5, 6)).enumerate(bases) + with self.assertRaises(TypeError): + extended.enumerate([{"a": 1}]) + + +def _layouts_space(): + """A choice of a group of planes (a number) or a repetition of planes.""" + return DesignSpace( + altitude=Real(500e3, 600e3, step=100e3), + layout=Choice( + walker=DesignSpace(planes=Integer(1, 2), per_plane=Fixed(2)), + sso=DesignSpace( + planes=Repeat( + DesignSpace(crossing=Real(6, 9, step=3)), count=Categorical([1, 2]) + ) + ), + ), + ) + + +class TestValuesByPath(unittest.TestCase): + """ + Unit tests for the values of designs by their paths. + """ + + def setUp(self): + self.designs = _layouts_space().enumerate() + self.walker = next(d for d in self.designs if d.layout == "walker") + self.sso = [d for d in self.designs if d.layout == "sso"][-1] + + def test_paths(self): + """Paths of the columns of results (and of fixed values) give values.""" + self.assertEqual(self.walker["layout.walker.planes"], self.walker.layout.planes) + self.assertEqual(self.walker["layout.walker.per_plane"], 2) # fixed + self.assertEqual(self.walker["layout.walker"], self.walker.layout.value) + self.assertEqual(self.sso["layout.sso.planes.count"], 2) + self.assertEqual( + self.sso["layout.sso.planes[1].crossing"], + self.sso.layout.planes[1].crossing, + ) + for design in (self.walker, self.sso): + for path, value in design.flat().items(): + self.assertEqual(design[path], value, path) + with self.assertRaisesRegex(KeyError, "chose 'sso'"): + self.sso["layout.walker.planes"] # pylint: disable=pointless-statement + with self.assertRaisesRegex(KeyError, "2 items"): + self.sso[ + "layout.sso.planes[2].crossing" + ] # pylint: disable=pointless-statement + + def test_choices(self): + """A choice equals the name of its branch, and steps into it.""" + layout = self.walker.layout + self.assertTrue(layout == "walker") + self.assertFalse(layout == "sso") + self.assertIn("planes", layout) + self.assertNotIn("crossing", layout) + self.assertEqual(layout.walker.planes, layout.planes) + with self.assertRaisesRegex(AttributeError, "chose 'walker'"): + layout.sso # pylint: disable=pointless-statement + + def test_items(self): + """Repetitions give views of their items, also of slices.""" + planes = self.sso.layout.planes + self.assertEqual(planes[-1].crossing, planes[1].crossing) + self.assertEqual([plane.crossing for plane in planes[:1]], [planes[0].crossing]) + self.assertEqual(planes, list(planes)) + + def test_attribute_names(self): + """Designs and views list their values, and name those they lack.""" + names = dir(self.walker) + self.assertTrue({"layout", "realize", "key"} <= set(names)) + self.assertIn("planes", dir(self.walker.layout)) + self.assertIn("walker", dir(self.walker.layout)) + self.assertIn("count", dir(self.sso.layout.planes)) + self.assertIn("index", dir(self.sso.layout.planes[0])) + self.assertIn("crossing", dir(self.sso.layout.planes[0])) + with self.assertRaisesRegex(AttributeError, "no value 'layuot'") as raised: + self.walker.layuot # pylint: disable=pointless-statement + self.assertEqual(raised.exception.name, "layuot") + self.assertIs(raised.exception.obj, self.walker) + self.assertIn("it has ['altitude', 'layout']", str(raised.exception)) + with self.assertRaises(AttributeError) as raised: + self.walker.layout.plane # pylint: disable=pointless-statement + self.assertEqual(raised.exception.name, "plane") + with self.assertRaises(AttributeError) as raised: + self.sso.layout.planes[0].crosing # pylint: disable=pointless-statement + self.assertEqual(raised.exception.name, "crosing") + # getattr with a default, as of an optional value + self.assertIsNone(getattr(self.walker.layout, "altitude", None)) + + def test_constraints(self): + """The callables of a design space read values by paths too.""" + space = DesignSpace( + layout=Choice(walker=DesignSpace(planes=Integer(1, 3))), + constraints=[lambda d: d["layout.walker.planes"] <= 2], + ) + self.assertEqual(len(space.enumerate()), 2) + + +class TestReservedNames(unittest.TestCase): + """ + Unit tests for names that the views of values give otherwise. + """ + + def test_message(self): + """The error of a reserved name says why, and lists the names.""" + with self.assertRaises(ValueError) as context: + DesignSpace(items=Integer(1, 3)) + message = str(context.exception) + self.assertIn("['items']", message) + self.assertIn("views of their values", message) + self.assertIn(str(sorted(RESERVED_NAMES)), message) + + def test_status_columns(self): + """The status columns of results, and the attributes of designs, are + reserved names.""" + self.assertLessEqual(set(STATUS_COLUMNS), RESERVED_NAMES) + self.assertIn("uncertain_values", RESERVED_NAMES) + with self.assertRaisesRegex(ValueError, "reserved"): + DesignSpace(uncertain_values=Integer(1, 2)) + + def test_reserved(self): + """Children and branches may not be named as attributes of views, or + as the status columns of the results of studies.""" + for name in ("values", "items", "keys", "get", "key", "flat", "space"): + with self.assertRaisesRegex(ValueError, "reserved"): + DesignSpace(**{name: 1}) + for name in ("design", "feasible", "error", "seconds", "scenario"): + with self.assertRaisesRegex(ValueError, "reserved"): + DesignSpace(**{name: Integer(1, 2)}) + for name in ("choice", "value"): + with self.assertRaisesRegex(ValueError, "reserved"): + Choice(**{name: DesignSpace()}) + + +class TestCounts(unittest.TestCase): + """ + Unit tests for the counts of repetitions. + """ + + def test_kinds(self): + """Counts may be categorical, fixed, or derived.""" + categorical = DesignSpace( + parts=Repeat(Integer(0, 1), count=Categorical([1, 3])) + ) + designs = categorical.enumerate() + self.assertEqual(len(designs), 2 + 8) + self.assertEqual( + categorical._unit_paths(), # pylint: disable=protected-access + ["parts.count", "parts[0]", "parts[1]", "parts[2]"], + ) + rebuilt = categorical.designs_of( + pd.DataFrame([{"design": d.key, **d.flat()} for d in designs]) + ) + self.assertEqual([d.key for d in rebuilt], [d.key for d in designs]) + fixed = DesignSpace(parts=Repeat(Integer(0, 1), count=Fixed(2))) + self.assertEqual(len(fixed.enumerate()), 4) + derived = DesignSpace( + n=Integer(1, 2), parts=Repeat(Integer(0, 1), count=Derived(lambda d: d.n)) + ) + self.assertEqual(len(derived.enumerate()), 2 + 4) + with self.assertRaisesRegex(ValueError, "upper bound"): + derived._unit_paths() # pylint: disable=protected-access + + def test_invalid(self): + """Counts of other nodes, or negative, are rejected at once.""" + with self.assertRaisesRegex(TypeError, "count"): + Repeat(Integer(0, 1), count=Real(1, 2)) + with self.assertRaises(ValueError): + Repeat(Integer(0, 1), count=-1) + + +class TestDomains(unittest.TestCase): + """ + Unit tests for the decisions of designs given by their values. + """ + + def test_checked(self): + """Decisions outside their variables' domains are rejected.""" + space = DesignSpace(a=Integer(1, 6), b=Categorical(["x", "y"]), c=Real(0, 1)) + self.assertEqual(space.design({"a": 2, "b": "x", "c": 0.5}).a, 2) + for decisions in ({"a": 99}, {"b": "z"}, {"c": 2.0}): + with self.assertRaises(ValueError): + space.design({"a": 2, "b": "x", "c": 0.5, **decisions}) + + +class TestUncertainConstructors(unittest.TestCase): + """ + Unit tests for the constructors of uncertain parameters. + """ + + def test_triangular(self): + """A triangular parameter draws in its range, and names it.""" + growth = Uncertain.triangular(0.9, 1.0, 1.6) + self.assertEqual(repr(growth), "Uncertain(triangular(0.9, 1.0, 1.6))") + self.assertTrue(math.isnan(growth.nominal)) + space = DesignSpace(growth=growth) + draws = [space.enumerate()[0].realize(r).growth for r in range(50)] + self.assertTrue(all(0.9 <= draw <= 1.6 for draw in draws)) + with self.assertRaises(ValueError): + Uncertain.triangular(1.0, 0.5, 2.0) + + def test_nominal(self): + """The constructors take nominal values.""" + space = DesignSpace(x=Uncertain.uniform(0, 1, nominal=0.5)) + self.assertEqual(space.enumerate()[0].x, 0.5) + self.assertEqual(Uncertain.normal(0, 1, nominal=0.0).nominal, 0.0) + self.assertIn("seed()", repr(Uncertain.seed())) + + +class TestDecisionsAndViews(unittest.TestCase): + """ + Unit tests for decisions given by value, and the views of values. + """ + + def test_levels(self): + """Decisions given by value are the levels of their domains.""" + import numpy as np # pylint: disable=import-outside-toplevel + + space = DesignSpace(a=Integer(1, 4), b=Real(0.5, 1.5, step=0.5)) + (enumerated,) = [d for d in space.enumerate() if d.a == 2 and d.b == 0.5] + for a in (2, 2.0, np.int64(2)): + design = space.design({"a": a, "b": 0.5}) + self.assertEqual(design.key, enumerated.key) + self.assertIs(type(design.a), int) + + def test_views(self): + """Designs and scopes tell whether they have values, and choices print + as the names of their branches.""" + space = DesignSpace( + a=Integer(1, 2), + layout=Choice(walker=DesignSpace(planes=Integer(1, 2))), + constraints=[lambda d: d.get("a") >= 1 and "layout.walker.planes" in d], + ) + design = space.enumerate()[0] + self.assertIn("a", design) + self.assertIn("layout.walker.planes", design) + self.assertNotIn("other", design) + self.assertEqual(str(design.layout), "walker") + with self.assertRaises(TypeError): + list(design) + with self.assertRaisesRegex(ValueError, "reserved"): + Choice(walker=DesignSpace(value=1)) + + def test_items(self): + """Items are given by index within the repetition only.""" + space = DesignSpace(parts=Repeat(Integer(0, 1), count=3)) + parts = space.enumerate()[0].parts + self.assertEqual(parts[-1], parts[2]) + for index in (3, -4): + with self.assertRaises(IndexError): + parts[index] # pylint: disable=pointless-statement + + def test_plain_branch(self): + """A choice whose branch is a plain value (a variable) gives the + branch by its name, not the attributes of the value.""" + space = DesignSpace(x=Choice(a=Integer(1, 3), b=Real(0, 1, step=0.5))) + design = space.design({"x": ["a", 2]}) + self.assertEqual(design.x.a, 2) + self.assertEqual(design.x, "a") + for name in ("real", "bit_length", "b"): + with self.subTest(name=name): + with self.assertRaisesRegex(AttributeError, "chose 'a'"): + getattr(design.x, name) + self.assertNotIn(name, design.x) + # a branch that is a repetition gives its count + repeated = DesignSpace( + x=Choice(parts=Repeat(Integer(0, 1), count=2), none=None) + ).design({"x": ["parts", [0, 1]]}) + self.assertEqual(repeated.x.count, 2) + + def test_counts_given(self): + """Items given for a count that is not decided must match it.""" + space = DesignSpace( + n=Integer(1, 2), parts=Repeat(Integer(0, 1), count=Derived(lambda d: d.n)) + ) + with self.assertRaisesRegex(ValueError, "items are given"): + space.design({"n": 1, "parts": [0, 1]}) + + +class TestBranchNames(unittest.TestCase): + """ + Unit tests for choices given the names of their branches. + """ + + def test_override(self): + """A choice given its branch's name keeps the decisions given of it, or + decides it at its first levels.""" + space = _layouts_space() + walker = space.design({"altitude": 600e3, "layout": ["walker", {"planes": 2}]}) + sso = space.design(walker, layout="sso") + self.assertEqual(sso.layout, "sso") + self.assertEqual(sso.altitude, 600e3) + self.assertEqual( + sso.decisions["layout"], ["sso", {"planes": [{"crossing": 6.0}]}] + ) + again = space.design(walker, layout="walker") + self.assertEqual(again.key, walker.key) + # in the decisions too + first = space.design({"altitude": 500e3, "layout": "walker"}) + self.assertEqual(first.layout.planes, 1) + with self.assertRaisesRegex(ValueError, "not a level of layout"): + space.design(walker, layout="other") + + +class TestUnorderedLevels(unittest.TestCase): + """ + Unit tests for the order of the items of unordered repetitions. + """ + + def test_level_order(self): + """Unordered items are in the order of the levels of their decisions + (not of their text, as 10.5 precedes 9.0).""" + space = DesignSpace( + parts=Repeat( + DesignSpace(size=Real(9.0, 10.5, step=1.5), kind=Categorical("ba")), + count=2, + ordered=False, + ) + ) + design = space.design( + {"parts": [{"size": 10.5, "kind": "b"}, {"size": 9.0, "kind": "a"}]} + ) + self.assertEqual( + design.decisions["parts"], + [{"size": 9.0, "kind": "a"}, {"size": 10.5, "kind": "b"}], + ) + # by the first decision that differs, in the order of declaration + tied = space.design( + {"parts": [{"size": 9.0, "kind": "a"}, {"size": 9.0, "kind": "b"}]} + ) + self.assertEqual([p.kind for p in tied.parts], ["b", "a"]) + # enumerations and samples give the same order + keys = {d.key for d in space.enumerate()} + self.assertIn(design.key, keys) + self.assertLessEqual({d.key for d in space.sample(20, seed=1)}, keys) + + +class TestScenarioOverrides(unittest.TestCase): + """ + Unit tests for the overrides of scenarios, which are checked against the + constraints of design spaces. + """ + + def setUp(self): + self.space = DesignSpace( + n=Integer(1, 4), + limit=Fixed(4), + u=Uncertain.uniform(0, 1), + constraints=[lambda d: d.n - d.limit], + ) + + def test_constraints(self): + """A design that violates a constraint with the overrides is infeasible.""" + design = self.space.design({"n": 3}) + self.assertEqual(design.realize(0, overrides={"limit": 3}).limit, 3) + with self.assertRaisesRegex(Infeasible, "constraint 0"): + design.realize(0, overrides={"limit": 2}) + + def test_nan(self): + """A constraint that is NaN is not satisfied.""" + space = DesignSpace( + n=Integer(1, 4), + u=Uncertain.uniform(0, 1), + constraints=[lambda d: d.n - 10 * d.u], + ) + self.assertEqual(space.size(), 0) + with self.assertRaisesRegex(Infeasible, "NaN") as context: + space.design({"n": 1}) + self.assertEqual(context.exception.violation, 1) + + def test_equality(self): + """Realized designs are equal if of the same replicate and scenario.""" + design = self.space.design({"n": 1}) + low = design.realize(0, overrides={"limit": 1}, scenario="low") + high = design.realize(0, overrides={"limit": 4}, scenario="high") + self.assertNotEqual(low, high) + self.assertEqual(len({low, high}), 2) + again = design.realize(0, overrides={"limit": 1}, scenario="low") + self.assertEqual(low, again) + self.assertEqual(hash(low), hash(again)) + self.assertNotEqual(design.realize(0), low) + + def test_scenario_name(self): + """A realized design gives the name of its scenario.""" + design = self.space.design({"n": 1}) + self.assertIsNone(design.scenario) + self.assertIsNone(design.realize(0).scenario) + named = design.realize(0, overrides={"u": 0.5}, scenario="half") + self.assertEqual((named.scenario, named.u), ("half", 0.5)) + self.assertIn("scenario='half'", repr(named)) + + def test_checks(self): + """Paths of shifts and overrides are checked by the design space.""" + # pylint: disable=protected-access + space = _planes_space() + space._check_uncertain(["planes[*].phase"]) + space._check_overrides({"planes[*].phase": 1.0}) + self.space._check_overrides({"limit": 1, "u": 0.5}) + for paths in (["planes[0].phase"], ["per_plane"], ["planes[*]"], [1]): + with self.subTest(paths=paths): + with self.assertRaisesRegex(ValueError, "not uncertain"): + space._check_uncertain(paths) + with self.assertRaisesRegex(ValueError, "not fixed values"): + self.space._check_overrides({"n": 2}) + + def test_seed(self): + """Seeds are non-negative integers.""" + design = self.space.design({"n": 1}) + for seed in (-1, 1.5, True): + with self.subTest(seed=seed): + with self.assertRaisesRegex(ValueError, "seed"): + design.realize(0, seed=seed) + + +class TestKeywords(unittest.TestCase): + """ + Unit tests for options given by keyword only. + """ + + def test_keywords(self): + """The options of samples and realizations are keywords.""" + space = _planes_space() + with self.assertRaises(TypeError): + space.sample(5, "random") # pylint: disable=too-many-function-args + with self.assertRaises(TypeError): + space.enumerate()[0].realize(0, 1) # pylint: disable=too-many-function-args + with self.assertRaises(TypeError): + Repeat(Integer(0, 1), 2, False) # pylint: disable=too-many-function-args + frame = pd.DataFrame([{"design": d.key, **d.flat()} for d in space.enumerate()]) + with self.assertRaises(TypeError): + # pylint: disable-next=too-many-function-args + space.designs_of(frame, list(frame.design)) + + +class TestDesignsOfSpaces(unittest.TestCase): + """ + Unit tests for designs given to the functions of trade studies. + """ + + def test_other_spaces(self): + """Designs of other design spaces are the designs of their decisions.""" + # pylint: disable=import-outside-toplevel,protected-access + from tatc.tradespace.space import _designs + + space = DesignSpace(n=Integer(1, 2), altitude=Fixed(500)) + higher = space.extend(altitude=Fixed(700)) + designs = _designs(higher, space.enumerate()) + self.assertTrue(all(d.space is higher for d in designs)) + self.assertEqual([d.altitude for d in designs], [700, 700]) + same = higher.enumerate() + self.assertTrue(all(a is b for a, b in zip(_designs(higher, same), same))) + # but not designs with decisions that the design space does not have + spared = space.extend(spares=Integer(0, 1)).design({"n": 1, "spares": 1}) + with self.assertRaisesRegex(ValueError, "another design space.*spares"): + _designs(space, [spared]) + + def test_frames(self): + """Designs rebuilt from frames read the frame's keys once, and a frame + that lacks their values gives the reason.""" + # pylint: disable=import-outside-toplevel,protected-access + from tatc.tradespace.space import _designs + + class Counted(pd.DataFrame): + """A data frame that counts the reads of its keys of designs.""" + + reads = 0 + + @property + def _constructor(self): + return Counted + + def __getitem__(self, key): + if isinstance(key, str) and key == "design": + Counted.reads += 1 + return super().__getitem__(key) + + space = DesignSpace(a=Integer(0, 99), b=Integer(0, 4)) + designs = space.enumerate() + rows = pd.DataFrame( + [ + {"design": d.key, "replicate": r, **d.flat()} + for d in designs + for r in (0, 1) + ] + ) + keys = [d.key for d in designs] + rebuilt = _designs(space, keys, Counted(rows)) + self.assertEqual([d.key for d in rebuilt], keys) + self.assertLess(Counted.reads, 10) + with self.assertRaisesRegex(ValueError, "not given") as context: + _designs(space, keys[:2], rows.drop(columns="b")) + self.assertIn("no value of b", str(context.exception.__cause__)) + + +class TestPathHelpers(unittest.TestCase): + """ + Unit tests for the helpers of the paths and values of designs. + """ + + def test_generic_path(self): + """The paths of nodes name any item of a repetition by `[*]`.""" + self.assertEqual(generic_path("planes[12].phase"), "planes[*].phase") + self.assertEqual(generic_path("a[0].b[1]"), "a[*].b[*]") + self.assertEqual(generic_path("layout.walker.planes"), "layout.walker.planes") + + def test_is_number(self): + """Numbers are integers and floats (also numpy's), not booleans.""" + import numpy as np # pylint: disable=import-outside-toplevel + + for value in (1, 2.5, np.int64(3), np.float32(1.5), math.nan): + self.assertTrue(is_number(value), value) + for value in (True, np.bool_(False), "1", None): + self.assertFalse(is_number(value), value) diff --git a/tests/tradespace/test_stages.py b/tests/tradespace/test_stages.py new file mode 100644 index 0000000..0d469b3 --- /dev/null +++ b/tests/tradespace/test_stages.py @@ -0,0 +1,361 @@ +""" +Unit tests for staged deployments. + +@author Paul T. Grogan +""" + +import dataclasses +import unittest + +import numpy as np +import pandas as pd + +from tatc.tradespace import ( + CostModel, + DeploymentSchedule, + DesignSpace, + Exponential, + FailureModel, + RestorationPolicy, + SatelliteCost, + Stage, + walker_space, +) +from tatc.tradespace.expectations import exact_expectations +from tatc.tradespace.mission import Capability, PhaseCache + +# three planes of two satellites +LAYOUT = DesignSpace(layout=walker_space(inclination=60, planes=3, per_plane=2)) +SCHEDULE = DeploymentSchedule( + years=5, design_life=3, development_years=1, production_rate=4, launch_interval=0.5 +) +COSTS = CostModel(SatelliteCost(development=10, first_unit=2)) + + +def _layout(): + return LAYOUT.enumerate()[0].layout + + +NAMES = [f"s{i}" for i in range(6)] +# an observation of each satellite, so that the metric counts those operating +OBSERVATIONS = pd.DataFrame({"satellite": NAMES}) + + +def _count(observations): + """The number of satellites that observe.""" + return {"observing": float(observations.satellite.nunique())} + + +def _launches(history, plane): + return [ + (launch.time, launch.purpose) + for launch in history.launches + if launch.plane == plane + ] + + +class TestStages(unittest.TestCase): + """ + Unit tests for stages of deployments. + """ + + def test_planned_delay(self): + """A stage without a rule is deployed at its first time.""" + deployment = SCHEDULE.plan(_layout(), stages=[Stage(2, 1.0)]) + self.assertEqual({launch.plane for launch in deployment.launches}, {0, 1}) + history = deployment.simulate() + decided = deployment.begin + 1.0 + self.assertEqual(history.decided, [decided]) + # produced from the decision (after the line's earlier work) and launched + produced = [b for b in history.production if b.begin == decided] + self.assertEqual( + [(b.satellites, b.purpose) for b in produced], [(2, "deployment")] + ) + launched = _launches(history, 2) + self.assertEqual(launched[0], (decided + 2 / 4, "deployment")) + # replaced at the end of its design life, within the mission + self.assertEqual(launched[1], (decided + 2 / 4 + 3, "replacement")) + self.assertEqual(history.operating[2, 0][0][0], decided + 2 / 4) + self.assertEqual(history.metrics()["stages deployed"], 1.0) + # the first generation is deployed with the stage + self.assertEqual(history.deployed, decided + 2 / 4) + self.assertEqual(deployment.deployed, decided + 2 / 4) + self.assertLess(SCHEDULE.plan(_layout()).deployed, deployment.deployed) + + def test_sustained(self): + """A deployed stage of a sustained constellation is replaced after the + end of the mission as the other planes are: produced, not launched.""" + schedule = dataclasses.replace(SCHEDULE, design_life=3.75, sustained=True) + history = schedule.plan(_layout(), stages=[Stage(2, 1.0)]).simulate() + self.assertEqual(history.end, 6.5) + # launched at 3, its replacement needed at 6.75, after the end + self.assertEqual(_launches(history, 2), [(3.0, "deployment")]) + after = [(b.begin, b.end) for b in history.production if b.end > history.end] + self.assertEqual(after, [(6.25, 6.75)]) + # eleven units of 2: five planes launched, and half of the sixth + self.assertAlmostEqual(COSTS.estimate(history).production, 11 * 2) + + def test_not_deployed(self): + """A stage that its rule does not deploy is neither produced nor launched.""" + never = SCHEDULE.plan( + _layout(), stages=[Stage([1, 2], [0.5, 1.0], lambda d: False)] + ) + history = never.simulate() + self.assertEqual(history.decided, [None]) + self.assertEqual(_launches(history, 1) + _launches(history, 2), []) + self.assertNotIn((1, 0), history.operating) + self.assertEqual(history.metrics()["stages deployed"], 0.0) + plain = SCHEDULE.plan(_layout()) + self.assertLess(COSTS.estimate(never).total, COSTS.estimate(plain).total) + self.assertNotIn("stages deployed", plain.simulate().metrics()) + self.assertEqual(never.deployed, history.deployed) + + def test_deployed_after_the_end(self): + """A stage deployed too late to launch within the mission leaves the + deployment unfinished: the time it is deployed is infinite.""" + late = SCHEDULE.plan(_layout(), stages=[Stage(2, 4.75)]) + history = late.simulate() + self.assertEqual(history.decided, [late.begin + 4.75]) + self.assertEqual(_launches(history, 2), []) + self.assertEqual(history.deployed, float("inf")) + self.assertEqual(late.deployed, float("inf")) + # or deployed within it, or not at all + early = SCHEDULE.plan(_layout(), stages=[Stage(2, 4.0)]) + self.assertEqual(early.deployed, early.begin + 4.0 + 2 / 4) + never = SCHEDULE.plan(_layout(), stages=[Stage(2, 4.75, lambda d: False)]) + self.assertLess(never.deployed, never.end) + + def test_cost_of_the_option(self): + """A type of satellite whose planes are all staged costs its + development, whether or not they are deployed: the cost of the option.""" + plane = ( + DesignSpace(layout=walker_space(inclination=60, planes=1, per_plane=2)) + .enumerate()[0] + .layout + ) + model = CostModel( + { + "a": SatelliteCost(development=10, first_unit=1), + "b": SatelliteCost(development=50, first_unit=1), + } + ) + never = DeploymentSchedule(years=5, development_years=1).plan( + {"a": plane, "b": plane}, stages=[Stage(1, 0.0, lambda decision: False)] + ) + estimate = model.estimate(never) + self.assertEqual(never.simulate().decided, [None]) + self.assertEqual(estimate.units, {"a": 2}) + self.assertEqual(estimate.development, 10 + 50) + + def test_decisions(self): + """Rules decide at their times, until they deploy, from what is known.""" + seen = [] + + def rule(decision): + seen.append(decision) + return decision.since_launch >= 1.0 + + stages = [Stage(1, 0.25), Stage(2, [0.5, 1.0, 1.5], rule)] + history = SCHEDULE.plan(_layout(), stages=stages).simulate() + self.assertEqual([d.since_launch for d in seen], [0.5, 1.0]) + self.assertEqual({d.stage for d in seen}, {1}) + self.assertEqual(seen[0].stages_deployed, (0,)) + # the satellites of the first plane operate (those of the second are + # still being produced) + self.assertEqual(seen[0].satellites_operating, 2) + begin = min(launch.time for launch in history.launches) + # times are from the start of development, as every time of a mission + self.assertEqual([d.time for d in seen], [begin + 0.5, begin + 1.0]) + self.assertEqual(history.decided, [begin + 0.25, begin + 1.0]) + + def test_contingency(self): + """A rule on failures deploys a stage in the histories that need it.""" + failures = FailureModel(life=Exponential(0.1)) + policy = RestorationPolicy(restore=False) + stage = Stage(2, [0.5, 1.0, 1.5, 2.0], lambda d: d.satellites_operating < 4) + deployment = SCHEDULE.plan(_layout(), policy=policy, stages=[stage]) + self.assertEqual(deployment.simulate().decided, [None]) + histories = deployment.simulate_many(failures, seed=1, histories=20) + deployed = [h.decided[0] is not None for h in histories] + self.assertTrue(any(deployed) and not all(deployed)) + for history in histories: + failed = [t for t, *_ in history.failures] + if history.decided[0] is not None: + self.assertLess(min(failed), history.decided[0]) + # the satellites of a stage count in the availability of the + # histories that deploy it (and only of those) + self.assertLessEqual(history.metrics()["availability"], 1.0) + # the same history draws the same failures again + again = deployment.simulate_many(failures, seed=1, histories=20) + self.assertEqual([h.decided for h in again], [h.decided for h in histories]) + + def test_capability(self): + """Rules read the capability of the satellites operating at a decision.""" + seen = [] + + def rule(decision): + seen.append( + ( + decision.since_launch, + decision.satellites_operating, + decision.capability, + ) + ) + return decision.capability["observing"] < 4 + + capability = Capability(NAMES, OBSERVATIONS, _count) + deployment = SCHEDULE.plan( + _layout(), stages=[Stage(2, [0.0, 0.5], rule)], capability=capability + ) + self.assertIs(deployment.capability, capability) + history = deployment.simulate() + # the first plane alone at the first launch (the second is launched later) + self.assertEqual(seen, [(0.0, 2, {"observing": 2.0})]) + self.assertEqual(history.decided, [deployment.begin]) + # the planned history reads it too + self.assertEqual(history.metrics()["stages deployed"], 1.0) + self.assertEqual(deployment.planned().decided, [deployment.begin]) + later = SCHEDULE.plan( + _layout(), stages=[Stage(2, 0.5, rule)], capability=capability + ) + self.assertEqual(later.simulate().decided, [None]) + # without a capability, a rule cannot read it + unmeasured = SCHEDULE.plan(_layout(), stages=[Stage(2, 0.0, rule)]) + with self.assertRaisesRegex(ValueError, "capability"): + unmeasured.simulate() + + def test_capability_of_failures(self): + """The capability at a decision follows failures, as rules on them do.""" + failures = FailureModel(life=Exponential(0.1)) + policy = RestorationPolicy(restore=False) + by_count = SCHEDULE.plan( + _layout(), + policy=policy, + stages=[ + Stage(2, [0.5, 1.0, 1.5, 2.0], lambda d: d.satellites_operating < 4) + ], + ) + cache = PhaseCache(_count) + measured = SCHEDULE.plan( + _layout(), + policy=policy, + stages=[ + Stage( + 2, + [0.5, 1.0, 1.5, 2.0], + lambda d: d.capability["observing"] < 4, + ) + ], + capability=Capability(NAMES, OBSERVATIONS, cache, context="replicate"), + ) + expected = by_count.simulate_many(failures, seed=1, histories=20) + histories = measured.simulate_many(failures, seed=1, histories=20) + self.assertEqual([h.decided for h in histories], [h.decided for h in expected]) + self.assertTrue(any(h.decided[0] is not None for h in histories)) + # each set of satellites read at a decision is evaluated once + self.assertGreater(cache.hits, 0) + + def test_capability_reads(self): + """A capability evaluates sets of satellites by name, or by position, only + when read.""" + # pylint: disable=protected-access + calls = [] + + def metric(observations): + calls.append(len(observations)) + return _count(observations) + + capability = Capability(NAMES, OBSERVATIONS, metric) + self.assertEqual(capability(["s0", "s3"]), {"observing": 2.0}) + planes = SCHEDULE.plan(_layout()).planes + self.assertEqual(capability._at(planes, [(1, 0), (2, 1)]), {"observing": 2.0}) + self.assertEqual(capability(set()), {"observing": 0.0}) + self.assertEqual(calls, [2, 2, 0]) + # a rule that does not read it does not evaluate it + deployment = SCHEDULE.plan( + _layout(), stages=[Stage(2, 0.0, lambda d: True)], capability=capability + ) + deployment.simulate() + self.assertEqual(len(calls), 3) + with self.assertRaises(ValueError): + capability(["s9"]) + with self.assertRaises(ValueError): + Capability(NAMES[:4], OBSERVATIONS, metric)._at(planes, [(0, 0)]) + # a cache keys satellites given by name by their names + cache = PhaseCache(_count) + cached = Capability(NAMES, OBSERVATIONS, cache) + cached(["s0", "s1"]) + cached(["s1", "s0"]) + self.assertEqual((cache.hits, cache.misses), (1, 1)) + # which the cache gives by their keys (and the context) + keys = {"s0": "s0", "s1": "s1"} + self.assertEqual(cache._metrics_of(keys, OBSERVATIONS), {"observing": 2.0}) + self.assertEqual((cache.hits, cache.misses), (2, 1)) + cache._metrics_of(keys, OBSERVATIONS, context="other") + self.assertEqual((cache.hits, cache.misses), (2, 2)) + + def test_lead_and_launches(self): + """A lead time delays production, and launch capacity splits launches.""" + schedule = DeploymentSchedule( + years=5, development_years=1, production_rate=4, launch_capacity=1 + ) + deployment = schedule.plan( + _layout(), + policy=RestorationPolicy(orbit_spares=1), + stages=[Stage(2, 1.0, lead_years=0.5)], + ) + history = deployment.simulate() + # the line is free by the end of the lead time + decided = history.decided[0] + launched = [l for l in history.launches if l.plane == 2] + self.assertEqual([l.satellites for l in launched], [1, 1, 1]) + self.assertEqual(launched[0].time, decided + 0.5 + 3 / 4) + # the spare of the staged plane waits in orbit + self.assertTrue( + any(start >= launched[0].time for start, _, _ in history.parked) + ) + + def test_exact_expectations(self): + """Exact expectations need a deployment that is not staged.""" + deployment = SCHEDULE.plan( + _layout(), + policy=RestorationPolicy(restore=False), + stages=[Stage(2, 1.0)], + ) + with self.assertRaisesRegex(ValueError, "staged"): + exact_expectations( + deployment, + FailureModel(life=Exponential(0.2)), + Capability([], None, len), + ) + + def test_invalid(self): + """Stages are of distinct planes of the layout, after some planned ones.""" + for stages in ( + [Stage(1), Stage([1, 2])], + [Stage(3)], + [Stage([0, 1, 2])], + ): + with self.subTest(stages=stages): + with self.assertRaises(ValueError): + SCHEDULE.plan(_layout(), stages=stages) + for arguments in (([],), ([1, 1],), ([-1],), (1, -1.0), (1, [])): + with self.subTest(arguments=arguments): + with self.assertRaises(ValueError): + Stage(*arguments) + with self.assertRaises(ValueError): + Stage(1, lead_years=-1) + + def test_numpy_values(self): + """Stages take integers and arrays of numpy as planes and times.""" + stage = Stage(np.int64(1), np.float64(0.5)) + self.assertEqual((stage.planes, stage.times), ((1,), (0.5,))) + stage = Stage(np.array([2, 1]), np.array([1.0, 0.0])) + self.assertEqual((stage.planes, stage.times), ((2, 1), (0.0, 1.0))) + self.assertEqual(Stage([1], range(3)).times, (0.0, 1.0, 2.0)) + deployment = SCHEDULE.plan(_layout(), stages=[Stage(np.int64(2), 1.0)]) + self.assertEqual(deployment.simulate().decided, [deployment.begin + 1.0]) + + +if __name__ == "__main__": + unittest.main() diff --git a/tests/tradespace/test_statistics.py b/tests/tradespace/test_statistics.py new file mode 100644 index 0000000..e970711 --- /dev/null +++ b/tests/tradespace/test_statistics.py @@ -0,0 +1,128 @@ +""" +Unit tests for statistics of the metrics of designs over their replicates. + +@author Paul T. Grogan +""" + +import unittest +import warnings + +import numpy as np + +from tatc.tradespace import ( + Maximum, + Mean, + Minimum, + Probability, + Quantile, + StandardDeviation, + Statistic, +) +from tatc.tradespace.fingerprint import get_fingerprint +from tatc.tradespace.statistics import _standard_error + +VALUES = np.array( + [[1.0, 2.0, 3.0, np.nan], [4.0, np.nan, np.nan, np.nan], [np.nan] * 4] +) + + +class TestStatistics(unittest.TestCase): + """ + Unit tests for statistics. + """ + + def test_reductions(self): + """Statistics ignore missing replicates.""" + np.testing.assert_allclose(Mean("x").reduce(VALUES), [2, 4, np.nan]) + np.testing.assert_allclose(Minimum("x").reduce(VALUES), [1, 4, np.nan]) + np.testing.assert_allclose(Maximum("x").reduce(VALUES), [3, 4, np.nan]) + np.testing.assert_allclose(Quantile("x", 0.25).reduce(VALUES), [1.5, 4, np.nan]) + np.testing.assert_allclose( + StandardDeviation("x").reduce(VALUES), [1, np.nan, np.nan] + ) + # the standard error of the mean, of the spreads of summaries + np.testing.assert_allclose( + _standard_error(VALUES), [1 / np.sqrt(3), np.nan, np.nan] + ) + np.testing.assert_allclose( + Probability("x", ">=", 2).reduce(VALUES), [2 / 3, 1, np.nan] + ) + np.testing.assert_allclose( + Probability("x", "<", 2).reduce(VALUES), [1 / 3, 0, np.nan] + ) + + def test_quantiles_with_missing_values(self): + """Quantiles are numpy's, of the values of each design.""" + rng = np.random.default_rng(5) + values = rng.normal(size=(200, 12)) + values[rng.random(values.shape) < 0.4] = np.nan + values[0] = np.nan + values[1, 1:] = np.nan + for q in (0, 0.1, 0.5, 0.7, 1): + with warnings.catch_warnings(): + warnings.simplefilter("ignore", RuntimeWarning) + expected = np.nanquantile(values, q, axis=1) + np.testing.assert_allclose(Quantile("x", q).reduce(values), expected) + + def test_invalid(self): + """Quantiles and operators are checked.""" + with self.assertRaises(ValueError): + Quantile("x", 1.5) + with self.assertRaises(ValueError): + Probability("x", "==", 1) + + def test_equality(self): + """Statistics of the same kind and parameters are equal.""" + self.assertEqual(Quantile("x", 0.2), Quantile("x", 0.2)) + self.assertNotEqual(Quantile("x", 0.2), Quantile("x", 0.3)) + self.assertNotEqual(Mean("x"), Maximum("x")) + self.assertEqual(len({Mean("x"), Mean("x"), Mean("y")}), 2) + self.assertIsInstance(Mean("x"), Statistic) + + def test_fingerprints(self): + """Statistics are fingerprinted by their kind and parameters.""" + self.assertNotEqual( + get_fingerprint(Quantile("c", 0.7)), get_fingerprint(Quantile("c", 0.9)) + ) + self.assertNotEqual( + get_fingerprint(Probability("c", ">=", 50)), + get_fingerprint(Probability("c", ">=", 80)), + ) + self.assertNotEqual( + get_fingerprint(Probability("c", ">=", 50)), + get_fingerprint(Probability("c", "<=", 50)), + ) + self.assertNotEqual(get_fingerprint(Mean("c")), get_fingerprint(Mean("d"))) + self.assertNotEqual(get_fingerprint(Mean("c")), get_fingerprint(Maximum("c"))) + # equal statistics, equal fingerprints + self.assertEqual( + get_fingerprint(Quantile("c", 0.7)), get_fingerprint(Quantile("c", 0.7)) + ) + self.assertEqual( + get_fingerprint(Probability("c", ">=", 50)), + get_fingerprint(Probability("c", ">=", 50)), + ) + + +class TestNames(unittest.TestCase): + """ + Unit tests for the conventional names of statistics. + """ + + def test_names(self): + """Statistics are named by convention.""" + self.assertEqual(Mean("cost").name, "cost") + self.assertEqual(StandardDeviation("cost").name, "cost std") + self.assertEqual(Minimum("cost").name, "cost min") + self.assertEqual(Maximum("cost").name, "cost max") + self.assertEqual(Quantile("cost", 0.7).name, "cost p70") + self.assertEqual(Probability("cost", "<=", 150).name, "P(cost <= 150)") + + def test_columns(self): + """A statistic needs the column of its metric.""" + self.assertEqual(Quantile("cost", 0.7).columns, ("cost",)) + self.assertEqual(Quantile("cost", 0.7).metric, "cost") + + +if __name__ == "__main__": + unittest.main() diff --git a/tests/tradespace/test_store.py b/tests/tradespace/test_store.py new file mode 100644 index 0000000..3df9d68 --- /dev/null +++ b/tests/tradespace/test_store.py @@ -0,0 +1,403 @@ +""" +Unit tests for persistent stores of results. + +@author Paul T. Grogan +""" + +# pylint: disable=protected-access + +import importlib.util +import json +import math +import sqlite3 +import tempfile +import unittest +from types import SimpleNamespace +import warnings +from concurrent.futures import ThreadPoolExecutor +from contextlib import closing +from datetime import date, datetime, time, timedelta, timezone +from pathlib import Path + +import numpy as np +import pandas as pd + +from tatc.tradespace import ( + DesignSpace, + Integer, + ResultStore, + Study, + Uncertain, +) +from tatc.tradespace.fingerprint import compare_definitions + +HAS_JOBLIB = importlib.util.find_spec("joblib") is not None + + +class _Interrupt(Exception): + """An interruption of a study.""" + + +def _stop_at_four(d): + if d.a == 4: + raise ValueError("stop") + return {"value": d.a} + + +class TestResultStore(unittest.TestCase): + """ + Unit tests for stores of results. + """ + + def setUp(self): + self.directory = tempfile.TemporaryDirectory() + self.path = Path(self.directory.name) / "results.sqlite" + self.space = DesignSpace(a=Integer(1, 4), noise=Uncertain.uniform(0, 1)) + self.calls = [] + # the state of the study's evaluations, which their fingerprint does not + # see (an object of an installed class is described by its type) + self.state = SimpleNamespace(fail_at=None) + + def tearDown(self): + self.directory.cleanup() + + def _study(self, store, **kwargs): + def evaluate(d): + if self.state.fail_at is not None and len(self.calls) == self.state.fail_at: + raise _Interrupt() + self.calls.append((d.a, d.noise)) + return {"value": d.a + d.noise} + + return Study( + self.space, lambda d: d, evaluate, replicates=3, store=store, **kwargs + ) + + def test_store_and_get(self): + """Records are stored and retrieved by design and replicate.""" + store = ResultStore(self.path, namespace="x") + store._put([("d1", 0, [{"value": 1}]), ("d1", 1, [{"value": 2}])]) + self.assertEqual(len(store), 2) + self.assertEqual( + store._get([("d1", 1), ("d2", 0)]), {("d1", 1): [{"value": 2}]} + ) + # records of another context are separate + store._put([("d1", 1, [{"value": 3}])], context="c") + self.assertEqual(store._get([("d1", 1)], "c"), {("d1", 1): [{"value": 3}]}) + self.assertEqual(store._get([("d1", 1)])[("d1", 1)], [{"value": 2}]) + self.assertEqual(store._contexts(), {"": 2, "c": 1}) + other = ResultStore(self.path, namespace="y") + self.assertEqual(len(other), 0) + store.clear() + self.assertEqual(len(store), 0) + # a store without a namespace has its own records + self.assertEqual(len(ResultStore(self.path)), 0) + # the namespace is a keyword + with self.assertRaises(TypeError): + ResultStore(self.path, "x") # pylint: disable=too-many-function-args + self.assertIn("namespace='y'", repr(other)) + + def test_resume(self): + """An interrupted study resumes, evaluating only what is not stored.""" + store = ResultStore(self.path, namespace="study") + self.state.fail_at = 5 + with self.assertRaises(_Interrupt): + self._study(store).run() + self.assertEqual(len(store), 5) + self.state.fail_at = None + resumed = self._study(store).run() + self.assertEqual(len(self.calls), 12) # 5 before, 7 after + complete = self._study(None).run() + columns = [c for c in complete.columns if c != "seconds"] + pd.testing.assert_frame_equal(resumed[columns], complete[columns]) + # a later run takes every evaluation from the store + self.calls.clear() + self._study(store).run() + self.assertEqual(self.calls, []) + + def test_more_replicates(self): + """Extending a study evaluates only the new replicates.""" + store = ResultStore(self.path, namespace="study") + self._study(store).run() + self.calls.clear() + results = self._study(store).run(replicate_indices=range(5)) + self.assertEqual(len(self.calls), 4 * 2) + self.assertEqual(len(results), 4 * 5) + + @unittest.skipUnless(HAS_JOBLIB, "requires joblib") + def test_parallel(self): + """Parallel studies store their evaluations as chunks complete.""" + store = ResultStore(self.path, namespace="study") + study = Study( + self.space, + lambda d: d, + lambda d: {"value": d.a + d.noise}, + replicates=3, + store=store, + n_jobs=2, + ) + results = study.run() + self.assertEqual(len(store), 12) + again = study.run() + pd.testing.assert_frame_equal(results, again) + + def test_other_definitions(self): + """Records of studies of other definitions are not reused, and studies + of other values share a store's namespace without a warning.""" + store = ResultStore(self.path, namespace="study") + self._study(store).run() + self.calls.clear() + self._study(store).run() + self.assertEqual(self.calls, []) + # another seed draws other uncertain values + with warnings.catch_warnings(): + warnings.simplefilter("error") + reseeded = self._study(store, seed=1).run() + self.assertEqual(len(self.calls), 12) + self.assertNotEqual( + reseeded.noise.tolist(), self._study(None).run().noise.tolist() + ) + # another fixed value of the design space + self.calls.clear() + self.space = DesignSpace(a=Integer(1, 4), b=2.0, noise=Uncertain.uniform(0, 1)) + with warnings.catch_warnings(): + warnings.simplefilter("error") + self._study(store).run() + self.assertEqual(len(self.calls), 12) + # another value that the evaluation closes over + self.calls.clear() + + def study(offset): + return Study( + self.space, + lambda d: d, + lambda d, offset=offset: self.calls.append(1) or {"value": offset}, + store=ResultStore(self.path, namespace="closure"), + ) + + study(0.0).run() + with warnings.catch_warnings(): + warnings.simplefilter("error") + study(1.0).run() + self.assertEqual(len(self.calls), 8) + + def test_other_code(self): + """A study warns of records of the same study with other code.""" + store = ResultStore(self.path, namespace="code") + + def study(evaluate): + return Study(self.space, lambda d: d, evaluate, replicates=2, store=store) + + study(lambda d: {"value": d.a + d.a}).run() + with self.assertWarnsRegex(UserWarning, "other code.*evaluate.code"): + edited = study(lambda d: {"value": d.a * d.a}).run() + self.assertEqual(list(edited.value[:2]), [1, 1]) + # other studies share the namespace: of other settings, and of other + # constants (such as the numbers of a constraint), without a warning + other = study(lambda d: {"value": d.a * d.a}).replace(seed=1) + other.run() + with warnings.catch_warnings(): + warnings.simplefilter("error") + constant = study(lambda d: {"value": d.a * d.a + 10}) + constant.run() + # pruning removes the study's evaluations with other code, only + current = study(lambda d: {"value": d.a * d.a}) + self.assertEqual(current.prune(), 8) + self.assertEqual( + store._contexts(), + {current.fingerprint: 8, other.fingerprint: 8, constant.fingerprint: 8}, + ) + self.assertEqual(current.prune(), 0) + self.assertEqual(constant.prune(), 0) + + def test_warning_location(self): + """The warning of evaluations with other code points at the run.""" + store = ResultStore(self.path, namespace="where") + + def study(evaluate): + return Study(self.space, lambda d: d, evaluate, store=store) + + study(lambda d: {"value": d.a + 1}).run() + with warnings.catch_warnings(record=True) as caught: + warnings.simplefilter("always") + study(lambda d: {"value": d.a * 1}).run() + (warning,) = [w for w in caught if "other code" in str(w.message)] + self.assertEqual(Path(warning.filename).resolve(), Path(__file__).resolve()) + + def test_prune_definitions(self): + """Definitions kept without evaluations (of a study whose evaluations + all failed) are of the study's contexts, which pruning removes.""" + store = ResultStore(self.path, namespace="failed") + + def study(evaluate, **kwargs): + return Study(self.space, lambda d: d, evaluate, store=store, **kwargs) + + broken = study(lambda d: {"value": d.a / 0}, errors="record") + with self.assertWarnsRegex(UserWarning, "none of the 4 designs"): + broken.run() + self.assertEqual(store._contexts(), {broken.fingerprint: 0}) + self.assertEqual(len(store), 0) + # the same study with other code (of the same constants) + fixed = study(lambda d: {"value": d.a * 0}) + with warnings.catch_warnings(): + warnings.simplefilter("error") # no evaluations to warn of + fixed.run() + self.assertEqual(fixed.prune(), 0) + self.assertEqual(store._contexts(), {fixed.fingerprint: 4}) + self.assertIsNone(store._definition(broken.fingerprint)) + + def test_records_as_json(self): + """Records are kept as JSON, and read as they were written.""" + record = { + "float": 1.5, + "nan": float("nan"), + "infinite": -math.inf, + "numpy": np.float64(2.5), + "integer": np.int64(3), + "flag": np.bool_(True), + "none": None, + "when": datetime(2026, 1, 1, 12, tzinfo=timezone.utc), + "naive": datetime(2026, 1, 1, 12, 30), + "day": date(2026, 1, 2), + "time": time(13, 30), + "duration": timedelta(days=1, microseconds=5), + "pair": (1, "a"), + "list": [1, (2, 3)], + "nested": {"a": {"b": 1}}, + "keys": {1: "a", ("x", 2): "b"}, + "tagged": {"$float": "x"}, + "array": np.arange(3), + } + store = ResultStore(self.path, namespace="x") + store._put([("d1", 0, [record])]) + read = store._get([("d1", 0)])[("d1", 0)][0] + self.assertEqual(set(read), set(record)) + self.assertTrue(math.isnan(read.pop("nan"))) + np.testing.assert_array_equal(read.pop("array"), record["array"]) + for key, value in read.items(): + # numpy scalars are read as Python's + written = record[key] + written = written.item() if isinstance(written, np.generic) else written + self.assertEqual(value, written, key) + self.assertIs(type(value), type(written), key) + # the records are JSON, which SQLite reads + with closing(sqlite3.connect(self.path)) as connection: + text, value = connection.execute( + "SELECT records, json_extract(records, '$[0].float') FROM results" + ).fetchone() + self.assertEqual(json.loads(text)[0]["integer"], 3) + self.assertEqual(value, 1.5) + + def test_definitions(self): + """A store keeps the definitions of studies, which explain changes.""" + store = ResultStore(self.path, namespace="study") + study = self._study(store) + study.run() + self.assertEqual(store._definition(study.fingerprint), study.definition) + self.assertIsNone(store._definition("other")) + reseeded = self._study(store, seed=1) + reseeded.run() + self.assertEqual( + compare_definitions(study.definition, reseeded.definition), + ["seed: 0 -> 1"], + ) + # contexts in the order they were defined, the latest last + self.assertEqual( + list(store._contexts()), [study.fingerprint, reseeded.fingerprint] + ) + # the records of a context are removed + self.assertEqual(store._remove(study.fingerprint), 12) + self.assertEqual(store._contexts(), {reseeded.fingerprint: 12}) + self.assertIsNone(store._definition(study.fingerprint)) + store.clear() + self.assertIsNone(store._definition(reseeded.fingerprint)) + + def test_parallel_interruption(self): + """Workers store each evaluation as it completes, before an error.""" + store = ResultStore(self.path, namespace="interrupted") + # an executor that waits for the chunks in progress as it shuts down + with ThreadPoolExecutor(2) as executor: + study = Study( + DesignSpace(a=Integer(1, 8)), + lambda d: d, + _stop_at_four, + store=store, + executor=executor, + chunks_per_job=1, + ) + with self.assertRaises(ValueError): + study.run() + # the designs evaluated before the error in its chunk (1 to 4) are kept + designs = study.space.enumerate() + stored = store._get(((d.key, 0) for d in designs), study.fingerprint) + values = sorted(records[0]["value"] for records in stored.values()) + self.assertEqual(values[:3], [1, 2, 3]) + self.assertNotIn(4, values) + + def test_variants(self): + """Variants of replicates are kept apart from plain replicates.""" + store = ResultStore(self.path, namespace="x") + store._put([("d1", 0, [{"value": 1}])]) + store._put([("d1", 0, [{"value": 2}])], variant='{"u": 5}') + self.assertEqual(store._get([("d1", 0)]), {("d1", 0): [{"value": 1}]}) + self.assertEqual( + store._get([("d1", 0)], variant='{"u": 5}'), {("d1", 0): [{"value": 2}]} + ) + self.assertEqual(store._get([("d1", 0)], variant='{"u": 6}'), {}) + self.assertEqual(len(store), 2) + + def test_shifted_runs(self): + """Shifted replicates are stored and reused apart from plain ones.""" + store = ResultStore(self.path, namespace="study") + plain = self._study(store).run() + shifted = self._study(store).run(shift={"noise": 3}) + self.assertEqual(len(self.calls), 2 * 4 * 3) + self.assertEqual(list(shifted.replicate), list(plain.replicate)) + later = self._study(store).run(replicate_indices=range(3, 6)) + np.testing.assert_array_equal(shifted.noise, later.noise) + self.calls.clear() + again = self._study(store).run(shift={"noise": 3}) + self.assertEqual(self.calls, []) + pd.testing.assert_frame_equal( + again.drop(columns="seconds"), shifted.drop(columns="seconds") + ) + unshifted = self._study(store).run(shift={"noise": 0}) + self.assertEqual(self.calls, []) + pd.testing.assert_frame_equal( + unshifted.drop(columns="seconds"), plain.drop(columns="seconds") + ) + with self.assertRaises(ValueError): + self._study(store).run(shift={"other": 1}) + + def test_table_without_variants(self): + """Evaluations stored before replicates had variants are plain.""" + with closing(sqlite3.connect(self.path)) as connection: + with connection: + connection.execute( + "CREATE TABLE results (namespace TEXT, context TEXT, design TEXT, " + + "replicate INTEGER, records TEXT, " + + "PRIMARY KEY (namespace, context, design, replicate))" + ) + connection.execute( + "INSERT INTO results VALUES ('x', '', 'd1', 0, '[{\"value\": 1}]')" + ) + store = ResultStore(self.path, namespace="x") + self.assertEqual(store._get([("d1", 0)]), {("d1", 0): [{"value": 1}]}) + store._put([("d1", 0, [{"value": 2}])], variant="v") + self.assertEqual(len(store), 2) + self.assertEqual(len(ResultStore(self.path, namespace="x")), 2) + + def test_earlier_format(self): + """Files with evaluations of an earlier format are read as empty.""" + with closing(sqlite3.connect(self.path)) as connection: + with connection: + connection.execute( + "CREATE TABLE evaluations (namespace TEXT, context TEXT, " + + "design TEXT, replicate INTEGER, records BLOB)" + ) + connection.execute( + "INSERT INTO evaluations VALUES ('x', '', 'd1', 0, x'00')" + ) + store = ResultStore(self.path, namespace="x") + self.assertEqual(len(store), 0) + store._put([("d1", 0, [{"value": 1}])]) + self.assertEqual(store._get([("d1", 0)]), {("d1", 0): [{"value": 1}]}) diff --git a/tests/tradespace/test_study.py b/tests/tradespace/test_study.py new file mode 100644 index 0000000..9485aab --- /dev/null +++ b/tests/tradespace/test_study.py @@ -0,0 +1,766 @@ +""" +Unit tests for trade studies. + +@author Paul T. Grogan +""" + +import importlib.util +import math +import tempfile +import unittest +from types import SimpleNamespace +import warnings +from pathlib import Path +from concurrent.futures import ThreadPoolExecutor +from datetime import datetime, time, timezone + +import numpy as np +import pandas as pd + +from tatc.schemas import ( + CircularOrbit, + Satellite, + SunSynchronousOrbit, + WalkerConstellation, +) +from tatc.tradespace import ( + Derived, + DesignSpace, + Fixed, + Infeasible, + Integer, + Real, + ResultStore, + Study, + Uncertain, + summarize, +) + +HAS_JOBLIB = importlib.util.find_spec("joblib") is not None + + +class TestStudy(unittest.TestCase): + """ + Unit tests for trade studies. + """ + + def setUp(self): + self.space = DesignSpace( + planes=Integer(1, 3), + per_plane=Integer(1, 3), + noise=Uncertain.uniform(0, 1), + ) + + def test_run_records(self): + """Every design is evaluated in every replicate, with its values and metrics.""" + study = Study( + self.space, + build=lambda d: (d.planes, d.per_plane, d.noise), + evaluate=lambda built: { + "satellites": built[0] * built[1], + "score": built[0] + built[2], + }, + replicates=4, + ) + results = study.run() + self.assertEqual(len(results), 9 * 4) + self.assertTrue(results.feasible.all()) + self.assertTrue( + (results.satellites == results.planes * results.per_plane).all() + ) + # common random numbers: the same noise in the same replicate of every design + self.assertEqual(results.groupby("replicate").noise.nunique().max(), 1) + self.assertEqual(results.groupby("design").noise.nunique().min(), 4) + + def test_independent_draws(self): + """Without common random numbers, designs draw independently.""" + study = Study( + self.space, + build=lambda d: d.noise, + evaluate=lambda noise: {"noise_out": noise}, + replicates=2, + common_random_numbers=False, + ) + results = study.run() + self.assertEqual(results.groupby("replicate").noise.nunique().min(), 9) + + def test_frame_outcomes_and_duplicates(self): + """Data frame outcomes give a record per row, and repeated designs run once.""" + designs = self.space.enumerate()[:2] * 3 + study = Study( + self.space, + build=lambda d: d.planes, + evaluate=lambda planes: pd.DataFrame( + {"sensor": ["a", "b"], "value": [planes, 2 * planes]} + ).set_index("sensor"), + ) + results = study.run(designs) + self.assertEqual(len(results), 2 * 2) + self.assertEqual(list(results.sensor), ["a", "b", "a", "b"]) + + def test_infeasible_designs(self): + """Designs rejected by validation are recorded as infeasible.""" + epoch = datetime(2026, 1, 1, tzinfo=timezone.utc) + space = DesignSpace( + altitude=Real(500e3, 600e3, step=100e3), + planes=Integer(1, 3), + satellites=Integer(1, 2), + ) + + def build(d): + return WalkerConstellation( + name="walker", + orbit=CircularOrbit(altitude=d.altitude, inclination=60, epoch=epoch), + number_planes=d.planes, + number_satellites=d.satellites, + ).generate_members() + + study = Study(space, build, lambda members: {"members": len(members)}) + results = study.run() + self.assertEqual(len(results), 12) + infeasible = results[~results.feasible] + # more planes than satellites + self.assertEqual(len(infeasible), 2 * 3) + self.assertTrue(infeasible.error.str.contains("number planes").all()) + feasible = results[results.feasible] + self.assertTrue((feasible.members == feasible.satellites).all()) + self.assertIsInstance(build(space.enumerate()[0])[0], Satellite) + + def test_design_argument(self): + """An evaluation with a parameter named design is given the realized design.""" + build = lambda d: d.planes # pylint: disable=unnecessary-lambda-assignment + given = Study( + self.space, + build, + lambda planes, design: {"score": planes + design.noise}, + replicates=2, + ).run() + np.testing.assert_allclose(given.score, given.planes + given.noise) + + def keyword(planes, *, design): + return {"satellites": planes * design.per_plane} + + results = Study(self.space, build, keyword).run() + self.assertTrue( + (results.satellites == results.planes * results.per_plane).all() + ) + # functions without the parameter, or without signatures, are given the + # built object only + Study(self.space, build, lambda planes: {"score": planes}).run() + results = Study(self.space, lambda d: {"value": d.planes}, dict).run() + self.assertEqual(list(results.value), list(results.planes)) + + def test_progress(self): + """Progress is reported as evaluations complete.""" + calls = [] + Study( + self.space, + build=lambda d: None, + evaluate=lambda built: {}, + replicates=2, + ).run(progress=lambda done, total: calls.append((done, total))) + self.assertEqual(calls[0], (1, 18)) + self.assertEqual(calls[-1], (18, 18)) + + def _noise_study(self, **kwargs): + return Study( + self.space, + build=lambda d: (d.planes, d.per_plane, d.noise), + evaluate=lambda built: {"score": built[0] * built[1] + built[2]}, + replicates=3, + **kwargs, + ) + + @unittest.skipUnless(HAS_JOBLIB, "requires joblib") + def test_parallel_matches_sequential(self): + """Evaluations in worker processes give the results of a sequential run.""" + sequential = self._noise_study().run() + parallel = self._noise_study(n_jobs=2).run() + columns = [c for c in sequential.columns if c != "seconds"] + pd.testing.assert_frame_equal(sequential[columns], parallel[columns]) + + def test_executor(self): + """Evaluations run on a given executor, in the order of the designs.""" + with ThreadPoolExecutor(max_workers=3) as executor: + threaded = self._noise_study(executor=executor).run() + sequential = self._noise_study().run() + pd.testing.assert_series_equal(threaded.score, sequential.score) + self.assertEqual(self._noise_study(executor=executor).workers, 3) + + def test_summarize(self): + """Summaries give the mean and spread of metrics over replicates.""" + results = self._noise_study().run() + summary = summarize(results, statistics=["score"]) + self.assertEqual(len(summary), 9) + self.assertIn("planes", summary.columns) + self.assertNotIn("noise", summary.columns) + self.assertTrue((summary.replicates == 3).all()) + first = results[results.design == summary.design[0]] + self.assertAlmostEqual(summary["score"][0], first.score.mean()) + self.assertAlmostEqual(summary["score std"][0], first.score.std()) + self.assertAlmostEqual(summary["score se"][0], first.score.std() / np.sqrt(3)) + self.assertNotIn("score sem", summary.columns) + # a metric may also be a value of the design + overlap = summarize(results, statistics=["score", "planes"]) + self.assertEqual(list(overlap.columns).count("planes"), 1) + + def test_replace_and_frames(self): + """Variants of a study replace arguments; designs may be data frames.""" + study = Study( + self.space, + lambda d: d, + lambda d: {"score": d.planes + d.noise}, + replicates=2, + seed=3, + ) + more = study.replace(replicates=4) + self.assertEqual((more.replicates, more.seed), (4, 3)) + self.assertIs(more.evaluate, study.evaluate) + self.assertEqual(study.replicates, 2) + results = more.run() + self.assertEqual(len(results), 9 * 4) + with self.assertRaisesRegex(TypeError, "no arguments"): + study.replace(replicate=3) + # designs given by a data frame of their values (such as a summary) + summary = summarize(results, statistics=["score"]) + best = summary.nlargest(2, "score") + again = study.run(best) + self.assertEqual(list(again.design.unique()), list(best.design)) + with self.assertRaisesRegex(ValueError, "not given"): + study.run(list(best.design)) + + def test_summarize_by(self): + """Summaries group the records of an evaluation.""" + study = Study( + self.space, + build=lambda d: d.planes, + evaluate=lambda planes: pd.DataFrame( + {"sensor": ["a", "b"], "value": [planes, 2 * planes]} + ).set_index("sensor"), + replicates=2, + ) + summary = summarize(study.run(), statistics=["value"], by=["sensor"]) + self.assertEqual(len(summary), 18) + b = summary[(summary.sensor == "b") & (summary.planes == 3)] + self.assertTrue((b.value == 6).all()) + + +class TestErrors(unittest.TestCase): + """ + Unit tests for errors of evaluations. + """ + + def setUp(self): + self.space = DesignSpace(a=Integer(1, 4)) + # the state of the evaluations, which their fingerprint does not see + # (an object of an installed class is described by its type) + self.state = SimpleNamespace(fail=True) + + def _evaluate(self, d): + if self.state.fail and d.a == 3: + raise RuntimeError("diverged") + return {"value": d.a} + + def test_raise(self): + """Errors other than rejections of designs are raised by default.""" + with self.assertRaises(RuntimeError): + Study(self.space, lambda d: d, self._evaluate).run() + with self.assertRaises(ValueError): + Study(self.space, lambda d: d, self._evaluate, errors="ignore") + + def test_record(self): + """Errors are recorded as infeasible evaluations, which are not stored.""" + with tempfile.TemporaryDirectory() as directory: + store = ResultStore(Path(directory) / "results.sqlite", namespace="errors") + study = Study( + self.space, lambda d: d, self._evaluate, errors="record", store=store + ) + results = study.run() + failed = results[~results.feasible] + self.assertEqual(list(failed.a), [3]) + self.assertEqual(failed.error.iloc[0], "RuntimeError: diverged") + self.assertFalse([c for c in results.columns if c.startswith("_")]) + self.assertEqual(len(store), 3) + # a later run evaluates the failed evaluation again + self.state.fail = False + again = study.run() + self.assertTrue(again.feasible.all()) + self.assertEqual(len(store), 4) + + def test_realization(self): + """Errors of the realization of a design (such as of a value derived + from a drawn uncertain parameter) are recorded too, with the values of + the design.""" + space = DesignSpace( + n=Integer(1, 2), + u=Uncertain.uniform(-1, 1), + root=Derived(lambda d: math.sqrt(d.u)), + ) + with tempfile.TemporaryDirectory() as directory: + store = ResultStore(Path(directory) / "results.sqlite", namespace="draws") + study = Study( + space, + lambda d: d.n, + lambda n: {"m": n}, + replicates=8, + errors="record", + store=store, + ) + results = study.run() + failed = results[~results.feasible] + self.assertTrue(len(failed) > 0) + self.assertTrue(failed.error.str.startswith("ValueError: ").all()) + self.assertEqual(sorted(failed.n.unique()), [1, 2]) + self.assertEqual(len(store), int(results.feasible.sum())) + with self.assertRaises(ValueError): + study.replace(errors="raise", store=None).run() + + +class TestFeasibility(unittest.TestCase): + """ + Unit tests for designs that studies reject, and mistakes in their functions. + """ + + def setUp(self): + self.space = DesignSpace(a=Integer(1, 4)) + self.mistaken = True + self.built = [] + + @staticmethod + def _store(directory: str) -> ResultStore: + return ResultStore(Path(directory) / "results.sqlite", namespace="feasibility") + + def test_rejected(self): + """Designs that either function rejects with Infeasible are stored as infeasible.""" + + def build(d): + if d.a == 1: + raise Infeasible("too small") + return d.a + + def evaluate(a): + if a == 2: + raise Infeasible("too slow") + return {"value": a} + + with tempfile.TemporaryDirectory() as directory: + store = self._store(directory) + results = Study(self.space, build, evaluate, store=store).run() + self.assertEqual(list(results.feasible), [False, False, True, True]) + self.assertEqual(list(results.error[:2]), ["too small", "too slow"]) + self.assertEqual(len(store), 4) + + def _build_orbit(self, d): + self.built.append(d.a) + return SunSynchronousOrbit( + altitude=d.a * 2000e3, + equator_crossing_time=time(10, 30), + epoch=datetime(2026, 1, 1, tzinfo=timezone.utc), + ) + + def test_validation_not_stored(self): + """Designs that fail validation are infeasible, and evaluated again later.""" + with tempfile.TemporaryDirectory() as directory: + store = self._store(directory) + study = Study( + self.space, + self._build_orbit, + lambda orbit: {"inclination": orbit.get_inclination()}, + store=store, + ) + results = study.run() + # too high to be sun-synchronous + self.assertEqual(list(results.feasible), [True, True, False, False]) + self.assertTrue(results.error[2:].str.contains("altitude").all()) + self.assertEqual(len(store), 2) + self.built.clear() + again = study.run() + self.assertEqual(self.built, [3, 4]) + self.assertEqual(list(again.feasible), list(results.feasible)) + + def _build_mistaken(self, d): + if self.mistaken: + # pylint: disable-next=unbalanced-tuple-unpacking,unused-variable + first, second = [d.a] + return d.a + + def test_mistakes_not_infeasible(self): + """Other errors, such as a ValueError of a mistake, fail rather than reject designs.""" + + def evaluate(a): + return {"value": a} + + with self.assertRaisesRegex(ValueError, "not enough values to unpack"): + Study(self.space, self._build_mistaken, evaluate).run() + with tempfile.TemporaryDirectory() as directory: + store = self._store(directory) + study = Study( + self.space, + self._build_mistaken, + evaluate, + errors="record", + store=store, + ) + with self.assertWarnsRegex(UserWarning, "none of the 4 designs"): + failed = study.run() + self.assertTrue(failed.error.str.startswith("ValueError: not enough").all()) + self.assertEqual(len(store), 0) + # a fix that the study's fingerprint cannot see + self.mistaken = False + self.assertTrue(study.run().feasible.all()) + self.assertEqual(len(store), 4) + + def test_warning_without_feasible(self): + """A run of several designs, none feasible, warns with the most common error.""" + + def build(d): + raise Infeasible("never" if d.a > 1 else "once") + + study = Study(self.space, build, lambda built: {}) + with self.assertWarnsRegex(UserWarning, r"\(3 of 4 evaluations\): never"): + study.run() + with warnings.catch_warnings(): + warnings.simplefilter("error") + # a single design, or any feasible design + study.run(self.space.enumerate()[:1]) + Study(self.space, lambda d: d, lambda d: {}).run() + + +class TestMetricNames(unittest.TestCase): + """ + Unit tests for the names of the metrics of evaluations. + """ + + def test_reserved_names(self): + """Metrics named as status columns, or replacing values of designs, raise errors.""" + space = DesignSpace(a=Integer(1, 2), noise=Uncertain.uniform(0, 1)) + # also `scenario` (and the marker of unstored records) without scenarios + for metrics in ( + {"replicate": 0}, + {"error": 0.1}, + {"a": 9}, + {"noise": 0.5}, + {"scenario": "mine"}, + {"_unstored": False}, + ): + for errors in ("raise", "record"): + with self.subTest(metrics=metrics, errors=errors): + study = Study( + space, lambda d: d, lambda d, m=metrics: m, errors=errors + ) + with self.assertRaisesRegex(ValueError, "metrics named"): + study.run() + + def test_restated_values(self): + """A metric may restate a value of the design, such as a variable that is an objective.""" + space = DesignSpace(a=Integer(1, 2), noise=Uncertain.uniform(0, 1)) + study = Study( + space, + lambda d: d, + lambda d: {"a": float(d.a), "noise": d.noise, "value": 2 * d.a}, + replicates=2, + ) + results = study.run() + self.assertEqual(list(results.a), [1, 1, 2, 2]) + self.assertEqual(list(results.value), [2, 2, 4, 4]) + + def test_reserved_index(self): + """Named indices of data frame outcomes are metrics too.""" + space = DesignSpace(a=Integer(1, 2)) + frame = pd.DataFrame({"value": [1]}, index=pd.Index([0], name="a")) + with self.assertRaisesRegex(ValueError, r"\['a'\]"): + Study(space, lambda d: d, lambda d: frame).run() + # other names are kept + renamed = frame.rename_axis("sensor") + results = Study(space, lambda d: d, lambda d: renamed).run() + self.assertEqual(list(results.a), [1, 2]) + self.assertEqual(list(results.sensor), [0, 0]) + + +class TestDesignsOfOtherSpaces(unittest.TestCase): + """ + Unit tests for designs of other design spaces given to a study. + """ + + def test_evaluated_in_study_space(self): + """Designs of another design space are evaluated as the designs of the + study's design space, also with a store and new uncertain parameters.""" + space = DesignSpace(n=Integer(1, 2), altitude=Fixed(500)) + designs = space.enumerate() + higher = space.extend(altitude=Fixed(700)) + with tempfile.TemporaryDirectory() as directory: + store = ResultStore(Path(directory) / "results.sqlite") + study = Study( + higher, lambda d: d.altitude * d.n, lambda x: {"score": x}, store=store + ) + self.assertEqual(list(study.run(designs).score), [700, 1400]) + self.assertEqual(list(study.run().score), [700, 1400]) + self.assertEqual(study.realize(designs[0], 0).altitude, 700) + risky = space.extend(growth=Uncertain.uniform(1, 2)) + results = Study(risky, lambda d: d.n * d.growth, lambda x: {"s": x}).run( + designs + ) + self.assertTrue(results.growth.between(1, 2).all()) + + def test_other_decisions(self): + """Designs with decisions that the study's design space does not have + (such as of a design space that extends it) raise, rather than being + evaluated without them.""" + base = DesignSpace(a=Integer(1, 2)) + spared = base.extend(spares=Integer(0, 1)).design({"a": 1, "spares": 1}) + study = Study(base, lambda d: d.a, lambda a: {"m": a}) + with self.assertRaisesRegex(ValueError, "another design space.*spares"): + study.run([spared]) + with self.assertRaisesRegex(ValueError, "another design space.*spares"): + study.realize(spared) + + +class TestStudyScenarios(unittest.TestCase): + """ + Unit tests for the constraints of design spaces in the scenarios of a + study, and the names of scenarios of realized designs. + """ + + def test_infeasible_in_scenario(self): + """A design that violates a constraint in a scenario is infeasible in it.""" + space = DesignSpace( + n=Integer(1, 4), limit=Fixed(4), constraints=[lambda d: d.n - d.limit] + ) + study = Study( + space, + lambda d: d.n, + lambda x: {"score": x}, + scenarios={"strict": {"limit": 2}, "loose": {}}, + ) + results = study.run() + feasible = results.pivot(index="n", columns="scenario", values="feasible") + self.assertEqual(list(feasible.loose), [True] * 4) + self.assertEqual(list(feasible.strict), [True, True, False, False]) + errors = results[~results.feasible].error + self.assertTrue(errors.str.contains("constraint 0").all()) + # with the values of the design, from which designs are rebuilt + rebuilt = space.designs_of(results) + self.assertEqual(list(rebuilt.map(lambda d: d.n)), list(results.n)) + with self.assertRaises(Infeasible): + study.realize(space.design({"n": 4}), 0, "strict") + + def test_scenario_of_design(self): + """An evaluation is given the design realized in its scenario.""" + space = DesignSpace(n=Integer(1, 2), level=Fixed(1.0)) + study = Study( + space, + lambda d: d, + lambda d, design: {"named": design.scenario, "level": design.level}, + scenarios={"high": {"level": 3.0}, "low": {}}, + ) + results = study.run() + self.assertEqual(list(results.named), list(results.scenario)) + self.assertEqual(set(results[results.scenario == "high"].level), {3.0}) + self.assertEqual( + study.realize(space.enumerate()[0], 0, "high").scenario, "high" + ) + self.assertIsNone( + Study(space, lambda d: d, dict).realize(space.enumerate()[0]).scenario + ) + + +class TestArguments(unittest.TestCase): + """ + Unit tests for the arguments of studies. + """ + + def test_seed(self): + """A seed is a non-negative integer, checked by the study.""" + space = DesignSpace(n=Integer(1, 2), u=Uncertain.uniform(0, 1)) + with self.assertRaisesRegex(ValueError, "seed"): + Study(space, lambda d: d.u, lambda x: {"s": x}, seed=-1) + + def test_keywords(self): + """The settings of a study, and the options of a run, are keywords.""" + space = DesignSpace(n=Integer(1, 2)) + with self.assertRaises(TypeError): + Study(space, lambda d: d, dict, 3) # pylint: disable=too-many-function-args + study = Study(space, lambda d: d.n, lambda n: {"m": n}) + with self.assertRaises(TypeError): + study.run(None, print) # pylint: disable=too-many-function-args + + def test_indices(self): + """Replicate indices and the offsets of shifts are checked before any + evaluation.""" + calls = [] + space = DesignSpace(n=Integer(1, 2), u=Uncertain.uniform(0, 1)) + study = Study(space, lambda d: d.n, lambda n: calls.append(n) or {"m": n}) + for options in ( + {"replicate_indices": [0, -1]}, + {"replicate_indices": [0.5]}, + {"shift": {"u": -1}}, + {"shift": {"u": 1.5}}, + ): + with self.subTest(options=options): + with self.assertRaisesRegex(ValueError, "non-negative integer"): + study.run(**options) + self.assertEqual(calls, []) + shifted = study.run(replicate_indices=[2], shift={"u": 1}) + plain = study.run(replicate_indices=[3]) + self.assertEqual(list(shifted.u), list(plain.u)) + + +class TestEmptyResults(unittest.TestCase): + """ + Unit tests for evaluations without records and runs without evaluations. + """ + + def setUp(self): + self.space = DesignSpace(n=Integer(0, 2)) + + @staticmethod + def _evaluate(n): + # a record per sensor, of which a design may have none + frame = pd.DataFrame({"sensor": list(range(n)), "score": [1.0] * n}) + return frame.set_index("sensor") + + def test_empty_frame(self): + """An evaluation that gives an empty data frame raises an error.""" + for errors in ("raise", "record"): + with self.subTest(errors=errors): + study = Study(self.space, lambda d: d.n, self._evaluate, errors=errors) + with self.assertRaisesRegex(ValueError, "empty data frame"): + study.run() + + def test_no_designs(self): + """A run of no designs gives the status columns of results.""" + results = Study(self.space, lambda d: d.n, self._evaluate).run([]) + self.assertEqual( + list(results.columns), + ["design", "replicate", "feasible", "error", "seconds"], + ) + self.assertEqual(len(results), 0) + scenarios = Study( + self.space, lambda d: d.n, self._evaluate, scenarios={"a": {}} + ).run([]) + self.assertEqual( + list(scenarios.columns)[:3], ["design", "replicate", "scenario"] + ) + + +class TestWarningLocation(unittest.TestCase): + """ + Unit tests for the location of the warnings of studies. + """ + + def test_no_feasible_designs(self): + """The warning of no feasible designs points at the run.""" + + def build(d): + raise Infeasible("never") + + study = Study(DesignSpace(a=Integer(1, 2)), build, dict) + with self.assertWarnsRegex(UserWarning, "none of the 2 designs") as context: + study.run() + self.assertEqual(Path(context.filename).resolve(), Path(__file__).resolve()) + + +class TestDescriptions(unittest.TestCase): + """ + Unit tests for the descriptions of designs in the results of studies. + """ + + def setUp(self): + self.space = DesignSpace( + planes=Integer(1, 2), + per_plane=Integer(1, 2), + noise=Uncertain.uniform(0, 1), + ) + self.calls = [] + + def describe(d): + self.calls.append(d.key) + return f"{d.planes} x {d.per_plane}" + + self.describe = describe + + def _study(self, **options): + return Study( + self.space, + lambda d: d, + lambda d: {"satellites": d.planes * d.per_plane, "score": d.noise}, + replicates=3, + describe=self.describe, + **options, + ) + + def test_column(self): + """A description of each design follows its values, given once per design + (of the design, not its replicates), and summaries keep it.""" + results = self._study().run() + columns = list(results.columns) + self.assertEqual(columns.index("description"), columns.index("feasible") - 1) + self.assertEqual(columns.index("description"), columns.index("noise") + 1) + labels = [f"{p} x {s}" for p in (1, 2) for s in (1, 2)] + self.assertEqual(list(results.description), [x for x in labels for _ in "abc"]) + self.assertEqual(len(self.calls), 4) + summary = summarize(results, {"satellites": "min", "score": "max"}) + self.assertEqual(list(summary.description), labels) + # without a function, no descriptions + self.assertNotIn("description", self._study().replace(describe=None).run()) + with self.assertRaises(TypeError): + self._study().replace(describe="planes") + + def test_not_stored(self): + """Descriptions are not stored, nor part of the fingerprint, so that + another function needs no new evaluations.""" + with tempfile.TemporaryDirectory() as directory: + store = ResultStore(Path(directory) / "results.sqlite") + study = self._study(store=store) + first = study.run() + other = study.replace(describe=lambda d: f"{d.planes} planes") + self.assertEqual(other.fingerprint, study.fingerprint) + progress = [] + again = other.run(progress=lambda done, total: progress.append(done)) + self.assertEqual(progress, []) # every evaluation from the store + self.assertEqual(list(again.description.unique()), ["1 planes", "2 planes"]) + pd.testing.assert_frame_equal( + again.drop(columns="description"), first.drop(columns="description") + ) + records = store._get( # pylint: disable=protected-access + [(key, 0) for key in first.design.unique()], study.fingerprint + ) + self.assertEqual(len(records), 4) + self.assertTrue( + all("description" not in r for rs in records.values() for r in rs) + ) + + def test_other_spaces_and_scenarios(self): + """Designs of another design space are described as designs of the + study's, in each scenario.""" + extended = self.space.extend(limit=Fixed(1)) + study = self._study().replace( + space=extended, scenarios={"a": {}, "b": {"limit": 2}} + ) + results = study.run(self.space.enumerate()[:2]) + self.assertEqual(list(results.description.unique()), ["1 x 1", "1 x 2"]) + self.assertEqual(len(self.calls), 2) + self.assertEqual(list(results.columns[:3]), ["design", "replicate", "scenario"]) + + def test_names(self): + """Metrics and values may not be named as the descriptions.""" + study = Study( + self.space, + lambda d: d, + lambda d: {"description": "a metric"}, + describe=self.describe, + ) + with self.assertRaisesRegex(ValueError, "description"): + study.run() + # but may without descriptions + self.assertIn("description", study.replace(describe=None).run()) + with self.assertRaisesRegex(ValueError, "named 'description'"): + self._study().replace(space=self.space.extend(description=Fixed("x"))) + + def test_no_designs(self): + """A run of no designs gives the column of descriptions.""" + results = self._study().run([]) + self.assertEqual( + list(results.columns), + ["design", "replicate", "description", "feasible", "error", "seconds"], + ) diff --git a/tests/tradespace/test_summary.py b/tests/tradespace/test_summary.py new file mode 100644 index 0000000..cf21b2b --- /dev/null +++ b/tests/tradespace/test_summary.py @@ -0,0 +1,809 @@ +""" +Unit tests for summaries of the results of studies: the statistics of each +design over its replicates and their spreads (`summarize`), its judgment by +criteria, and the probability that it is efficient (`pareto_probability`). + +@author Paul T. Grogan +""" + +import unittest +import warnings + +import numpy as np +import pandas as pd + +from tatc.tradespace import ( + Across, + Criteria, + Probability, + Quantile, + Requirement, + StandardDeviation, + pareto_probability, + summarize, +) + + +def _results(): + """Results of three designs in four replicates.""" + values = {"a": [10, 12, 14, 16], "b": [5, 30, 5, 30], "c": [1, 1, 1, 1]} + return pd.DataFrame( + [ + { + "design": key, + "replicate": r, + "feasible": True, + "cost": {"a": 2, "b": 2, "c": 1}[key], + "value": v, + "size": {"a": "small", "b": "small", "c": "large"}[key], + } + for key, row in values.items() + for r, v in enumerate(row) + ] + ) + + +def _partly_infeasible(scenario=None, shares=None): + """Results of three designs in four replicates: a is feasible in every + replicate, b in two, and c in none (whose records lack metrics).""" + values = {"a": [1, 2, 3, 4], "b": [10, None, 30, None], "c": [None] * 4} + values.update(shares or {}) + return pd.DataFrame( + [ + { + "design": key, + "replicate": r, + **({} if scenario is None else {"scenario": scenario}), + "feasible": v is not None, + "cost": ( + {"a": 2.0, "b": 1.0, "c": 1.0}[key] if v is not None else np.nan + ), + "value": np.nan if v is None else float(v), + } + for key, row in values.items() + for r, v in enumerate(row) + ] + ) + + +def _replicates(values, cost=1.0): + """Results of designs (rows) in replicates (columns), with a cost.""" + return pd.DataFrame( + [ + { + "design": f"d{i}", + "replicate": r, + "cost": cost, + "value": v, + "feasible": True, + } + for i, row in enumerate(values) + for r, v in enumerate(row) + ] + ) + + +def _scenarios(values): + """Results of a design in scenarios (by name), from its values in each + replicate (in order).""" + return pd.DataFrame( + [ + { + "design": "d", + "replicate": r, + "scenario": scenario, + "feasible": True, + "v": float(v), + } + for scenario, row in values.items() + for r, v in enumerate(row) + ] + ) + + +class TestSummary(unittest.TestCase): + """ + Unit tests for summaries of the statistics of designs. + """ + + def test_statistics(self): + """Statistics and design values are summarized, without violations.""" + frame = summarize( + _results(), + statistics={ + "value": "value", + "value p25": Quantile("value", 0.25), + "cost": "cost", + }, + ).set_index("design") + self.assertEqual(frame.loc["a", "value"], 13) + self.assertAlmostEqual(frame.loc["b", "value p25"], 5) + self.assertEqual(frame.loc["c", "size"], "large") + self.assertTrue((frame.replicates == 4).all()) + self.assertNotIn("violation", frame.columns) + means = summarize(_results(), statistics=["value"]) + self.assertEqual(list(means.value), [13, 17.5, 1]) + # a mapping of statistics by name is not one of objectives + with self.assertRaisesRegex(ValueError, "statistics"): + summarize(_results(), {"value p25": Quantile("value", 0.25)}) + # a misspelled direction is one, which criteria reject + for direction in ("minimize", "value"): + with self.subTest(direction=direction): + with self.assertRaisesRegex(ValueError, "must be 'min' or 'max'"): + summarize(_results(), {"value": direction}) + with self.assertRaises(ValueError): + summarize(_results()) + + def test_forms(self): + """Criteria are criteria or a mapping of directions, and statistics a + sequence or a mapping: metrics are given as statistics.""" + for metrics in (["value"], "value"): + with self.subTest(metrics=metrics): + with self.assertRaisesRegex(TypeError, "statistics=\\['value'\\]"): + summarize(_results(), metrics) + for single in ("value", Quantile("value", 0.5)): + with self.subTest(single=single): + with self.assertRaisesRegex(TypeError, "sequence"): + summarize(_results(), statistics=single) + with self.assertRaisesRegex(TypeError, "sequence"): + Criteria({"value": "max"}, statistics=single) + with self.assertRaisesRegex(TypeError, "statistics"): + pareto_probability(_results(), ["value"]) + + def test_objectives(self): + """A mapping of objectives are criteria of their means, with others.""" + frame = summarize( + _results(), + {"value": "max"}, + statistics={"value p25": Quantile("value", 0.25)}, + ).set_index("design") + self.assertEqual(frame.loc["a", "value"], 13) + self.assertAlmostEqual(frame.loc["b", "value p25"], 5) + self.assertTrue(frame.meets_requirements.all()) + # statistics that the criteria name otherwise + with self.assertRaisesRegex(ValueError, "otherwise"): + summarize( + _results(), {"value": "max"}, statistics={"value": Quantile("value", 1)} + ) + # a statistic the criteria name the same way is not a clash + same = summarize(_results(), {"value": "max"}, statistics={"value": "value"}) + self.assertEqual(list(same.value), [13, 17.5, 1]) + # objectives grouped by a column + self.assertEqual(len(summarize(_results(), {"value": "max"}, by="size")), 3) + + def test_criteria(self): + """Criteria add the violations of their requirements, relative to them.""" + criteria = Criteria( + {"cost": "min", "value": "max"}, + statistics={"value p25": Quantile("value", 0.25)}, + requirements=[ + Requirement("value p25", ">=", 5), + Requirement("cost", "<=", 1.5), + ], + ) + frame = summarize(_results(), criteria, spread=False).set_index("design") + self.assertEqual( + list(frame.columns[-8:]), + [ + "cost", + "value", + "value p25", + "replicates", + "feasible", + "violation", + "meets_requirements", + "pareto", + ], + ) + self.assertAlmostEqual(frame.loc["a", "violation"], 0.5 / 1.5) + self.assertAlmostEqual(frame.loc["c", "violation"], 4 / 5) + self.assertEqual(list(frame.meets_requirements), [False, False, False]) + # none meets the requirements, so that none is efficient + self.assertEqual(list(frame.pareto), [False, False, False]) + with self.assertRaises(ValueError): + summarize(_results(), criteria, by=["size"]) + + def test_requirement_on_metric(self): + """A requirement on a metric is on its mean.""" + criteria = Criteria( + {"value": "max"}, requirements=[Requirement("cost", "<=", 1)] + ) + frame = summarize(_results(), criteria) + self.assertIn("cost", frame.columns) + self.assertEqual(list(frame.meets_requirements), [False, False, True]) + # a requirement on a metric that the results do not have + missing = Criteria({"value": "max"}, requirements=[Requirement("w", ">=", 1)]) + with self.assertRaises(ValueError): + summarize(_results(), missing) + + def test_statistics_of_names(self): + """Statistics given by names are the means of the metrics, and other + statistics are named by convention.""" + summary = summarize(_results(), {"value": "max"}, statistics=["cost"]) + self.assertEqual(list(summary.cost), [2.0, 2.0, 1.0]) + self.assertEqual( + list(summarize(_results(), statistics=[Quantile("value", 0.25)]).columns)[ + -3: + ], + ["value p25", "replicates", "feasible"], + ) + + def test_names_of_columns(self): + """A statistic of the name of a column of the results is its mean.""" + results = _results().assign(**{"P(value >= 10)": 0.5}) + statistic = Probability("value", ">=", 10) + criteria = Criteria({"P(value >= 10)": "max"}, statistics=[statistic]) + for function in (summarize, pareto_probability): + with self.subTest(function=function.__name__): + with self.assertRaisesRegex(ValueError, "P\\(value >= 10\\)"): + function(results, criteria) + # the mean of the column, of its name + summary = summarize(results, {"P(value >= 10)": "max"}) + np.testing.assert_allclose(summary["P(value >= 10)"], 0.5) + renamed = Criteria({"reliable": "max"}, statistics={"reliable": statistic}) + np.testing.assert_allclose( + summarize(results, renamed).reliable, [1.0, 0.5, 0.0] + ) + # nor do the columns that summaries add + with self.assertRaisesRegex(ValueError, "value se"): + summarize(_results().assign(**{"value se": 1.0}), statistics=["value"]) + with self.assertRaisesRegex(ValueError, "value se"): + pareto_probability(_results().assign(**{"value se": 1.0}), {"value": "max"}) + + def test_records_of_groups(self): + """Several records of an evaluation need the columns that separate them.""" + results = pd.concat([_results().assign(sensor=s) for s in ("x", "y")]) + with self.assertRaisesRegex(ValueError, r"by.*\['sensor'\]"): + summarize(results, statistics=["value"]) + with self.assertRaisesRegex(ValueError, "sensor"): + pareto_probability(results, {"value": "max"}) + frame = summarize(results, Criteria({"value": "max"}, by="sensor")) + self.assertEqual(len(frame), 6) + self.assertEqual(len(summarize(results, statistics=["value"], by="sensor")), 6) + + def test_missing_group(self): + """Records without a value of a column of groups are a group of their + own, rather than left out.""" + results = _results().assign(sensor="x") + results.loc[results.design == "c", "sensor"] = None + frame = summarize(results, Criteria({"value": "max"}, by="sensor")) + self.assertEqual(sorted(frame.design), ["a", "b", "c"]) + # c is alone in its group, and so efficient + self.assertTrue(frame.set_index("design").loc["c", "pareto"]) + self.assertTrue(frame.set_index("design").loc["c", ["sensor"]].isna().all()) + means = summarize(results, statistics=["value"], by="sensor") + self.assertEqual(sorted(means.design), ["a", "b", "c"]) + + +class TestSpreads(unittest.TestCase): + """ + Unit tests for summaries with the spread of the means of metrics. + """ + + def test_summarize_criteria(self): + """Summaries of criteria add the spread of their means of metrics.""" + criteria = Criteria( + {"cost": "min", "value": "max"}, + statistics={"value p25": Quantile("value", 0.25)}, + ) + summary = summarize(_results(), criteria) + for column in ("value std", "value se", "pareto"): + self.assertIn(column, summary.columns) + self.assertNotIn("value p25 se", summary.columns) + # without spreads + plain = summarize(_results(), criteria, spread=False) + self.assertNotIn("value std", plain.columns) + self.assertNotIn("value se", plain.columns) + grouped = summarize(_results(), {"value": "max"}, by="size") + self.assertEqual(len(grouped), 3) + with self.assertRaises(ValueError): + summarize(_results(), Criteria({"value": "max"}), by="size") + + def test_infinite_values(self): + """The spread of a metric with infinite values is missing, without warnings.""" + results = _results().assign(time=np.inf) + results.loc[results.replicate == 0, "time"] = 4.0 + with warnings.catch_warnings(): + warnings.simplefilter("error") + summary = summarize(results, statistics=["time", StandardDeviation("time")]) + self.assertTrue(np.isinf(summary["time"]).all()) + self.assertTrue(summary["time std"].isna().all()) + + def test_summarize_statistics(self): + """Summaries take other statistics, with the spread of their means.""" + results = _results().assign(cost=lambda f: f.cost + 0.1 * f.replicate) + summary = summarize(results, {"value": "max"}, statistics=["cost"]) + for column in ("value", "value se", "cost", "cost std", "cost se", "pareto"): + self.assertIn(column, summary.columns) + # each mean followed by its spread, with criteria or without + followed = [ + "value", + "value std", + "value se", + "cost", + "cost std", + "cost se", + "replicates", + "feasible", + ] + alone = summarize(results, statistics=["value", "cost"]) + self.assertEqual(list(alone.columns[-8:]), followed) + judged = summarize(results, {"value": "max", "cost": "min"}) + self.assertEqual(list(judged.columns[-11:-3]), followed) + + def test_constant_spreads(self): + """The spreads of metrics that are the same in every replicate of each + design are left out.""" + summary = summarize(_results(), statistics=["value", "cost"]) + self.assertNotIn("cost std", summary.columns) + self.assertNotIn("cost se", summary.columns) + spread = summary.set_index("design")[["value std", "value se"]] + np.testing.assert_allclose(spread.loc["c"].to_numpy(dtype=float), 0.0) + # of designs of one replicate, as of summaries without designs + single = summarize(_results()[_results().replicate == 0], statistics=["value"]) + self.assertNotIn("value se", single.columns) + empty = summarize(_results().iloc[:0], statistics=["value"]) + self.assertIn("value se", empty.columns) + # as are those of the probabilities of efficiency + probability = pareto_probability(_results(), {"cost": "min", "value": "max"}) + self.assertNotIn("cost se", probability.columns) + self.assertIn("value se", probability.columns) + + def test_spread_of_worst(self): + """Across groups, the spread of the worst is that of its group, as + the probabilities of efficiency give it.""" + results = _scenarios({"a": [10] * 8, "b": [5, 9] * 4}) + worst = Criteria({"v": "max"}, across=Across()) + summary = summarize(results, worst).iloc[0] + b = results[results.scenario == "b"].v + self.assertEqual(summary.v, 7.0) + self.assertAlmostEqual(summary["v std"], b.std()) + self.assertAlmostEqual(summary["v se"], b.std() / np.sqrt(8)) + probability = pareto_probability(results, worst, n_resamples=50).iloc[0] + self.assertAlmostEqual(probability["v std"], b.std()) + self.assertAlmostEqual(probability["v se"], b.std() / np.sqrt(8)) + + def test_spread_of_mean(self): + """Across groups, the spread of a weighted mean is that of the + weighted sum of each replicate's values, of groups that share + replicates, and that of independent groups otherwise.""" + rng = np.random.default_rng(2) + x = rng.normal(0, 1, 30) + weights = {"s1": 3, "s2": 1} + mean = Criteria({"v": "max"}, across=Across(rule="mean", weights=weights)) + # the same replicates, of correlated values + paired = _scenarios({"s1": x, "s2": 2 * x + rng.normal(0, 0.1, 30)}) + summary = summarize(paired, mean).iloc[0] + wide = paired.pivot(index="replicate", columns="scenario", values="v") + combined = 0.75 * wide.s1 + 0.25 * wide.s2 + self.assertAlmostEqual(summary.v, combined.mean()) + self.assertAlmostEqual(summary["v std"], combined.std()) + self.assertAlmostEqual(summary["v se"], combined.std() / np.sqrt(30)) + probability = pareto_probability(paired, mean, n_resamples=50) + self.assertAlmostEqual(probability["v se"].iloc[0], summary["v se"]) + # replicates that no other group shares: independent groups + independent = paired.assign( + replicate=paired.replicate + 100 * (paired.scenario == "s2") + ) + summary = summarize(independent, mean).iloc[0] + errors = wide.std() / np.sqrt(30) + self.assertAlmostEqual( + summary["v se"], + np.sqrt(0.75**2 * errors.s1**2 + 0.25**2 * errors.s2**2), + ) + self.assertAlmostEqual( + summary["v std"], + np.sqrt(0.75**2 * wide.s1.var() + 0.25**2 * wide.s2.var()), + ) + # what the groups share cancels + cancel = Criteria({"v": "max"}, across=Across(rule="mean")) + steady = _scenarios({"s1": range(6), "s2": [10 - r for r in range(6)]}) + summary = summarize(steady, cancel) + self.assertEqual(summary.v.iloc[0], 5.0) + self.assertNotIn("v se", summary.columns) + self.assertNotIn("v se", pareto_probability(steady, cancel, n_resamples=50)) + + +class TestFeasibility(unittest.TestCase): + """ + Unit tests for the judgment of designs by their feasible replicates. + """ + + def test_feasible_share(self): + """Designs are judged by their feasible replicates, of which + `replicates` is the number and `feasible` the share; designs without a + feasible replicate are left out.""" + summary = summarize(_partly_infeasible(), {"cost": "min", "value": "max"}) + summary = summary.set_index("design") + self.assertEqual(list(summary.index), ["a", "b"]) + self.assertEqual(summary.loc["b", "value"], 20) + self.assertEqual(list(summary.replicates), [4, 2]) + self.assertEqual(list(summary.feasible), [1.0, 0.5]) + # b, cheaper and better in its feasible replicates, dominates a + self.assertEqual(list(summary.pareto), [False, True]) + self.assertEqual( + list(summary.columns[-5:]), + ["replicates", "feasible", "violation", "meets_requirements", "pareto"], + ) + + def test_requirement(self): + """Requirements on `feasible` judge the share of feasible replicates + over every replicate of a design.""" + every = Criteria( + {"cost": "min", "value": "max"}, + requirements=[Requirement("feasible", ">=", 1)], + ) + summary = summarize(_partly_infeasible(), every).set_index("design") + self.assertEqual(list(summary.feasible), [1.0, 0.5]) + self.assertEqual(list(summary.meets_requirements), [True, False]) + self.assertAlmostEqual(summary.loc["b", "violation"], 0.5) + self.assertEqual(list(summary.pareto), [True, False]) + half = Criteria( + {"cost": "min", "value": "max"}, + requirements=[Requirement("feasible", ">=", 0.5)], + ) + summary = summarize(_partly_infeasible(), half) + self.assertTrue(summary.meets_requirements.all()) + # its spread is not summarized + summary = summarize(_partly_infeasible(), every) + self.assertNotIn("feasible se", summary.columns) + self.assertEqual(list(summary.feasible), [1.0, 0.5]) + + def test_groups(self): + """Infeasible records without a value of a group (such as a sensor) + count in every group of the design.""" + results = _partly_infeasible() + feasible = results[results.feasible] + records = pd.concat( + [ + feasible.assign(sensor="x"), + feasible.assign(sensor="y", value=feasible.value + 1), + results[~results.feasible], + ], + ignore_index=True, + ) + summary = summarize(records, statistics=["value"], by="sensor") + summary = summary.set_index(["sensor", "design"]) + self.assertEqual(summary.loc[("y", "b"), "value"], 21) + self.assertEqual(summary.loc[("x", "b"), "feasible"], 0.5) + self.assertEqual(summary.loc[("y", "b"), "feasible"], 0.5) + self.assertEqual(summary.loc[("y", "a"), "feasible"], 1.0) + + def test_across(self): + """Across groups, `feasible` is over the replicates of every group + together, and designs need feasible replicates in every group.""" + results = pd.concat( + [ + _partly_infeasible("s1", {"b": [10, 20, 30, 40]}), + _partly_infeasible("s2"), + ], + ignore_index=True, + ) + for rule in ("worst", "mean"): + with self.subTest(rule=rule): + criteria = Criteria( + {"cost": "min", "value": "max"}, + requirements=[Requirement("feasible", ">=", 0.7)], + across=Across(rule=rule), + ) + summary = summarize(results, criteria).set_index("design") + self.assertEqual(list(summary.index), ["a", "b"]) + self.assertEqual(summary.loc["b", "feasible"], 0.75) + self.assertEqual(summary.loc["b", "replicates"], 2) + self.assertTrue(summary.meets_requirements.all()) + + def test_no_feasible_design(self): + """Results without a feasible record have empty summaries.""" + results = _partly_infeasible() + infeasible = results[results.design == "c"].drop(columns=["cost", "value"]) + criteria = Criteria({"cost": "min", "value": "max"}, by="size") + for summary in ( + summarize(infeasible, {"cost": "min", "value": "max"}), + summarize(infeasible.assign(size=1), criteria), + summarize(infeasible.iloc[:0], {"cost": "min", "value": "max"}), + ): + self.assertTrue(summary.empty) + self.assertEqual( + list(summary.columns[-5:]), + ["replicates", "feasible", "violation", "meets_requirements", "pareto"], + ) + # of the types of their columns, which select rows + self.assertEqual(summary.pareto.dtype, bool) + self.assertTrue(summary[summary.pareto].empty) + self.assertTrue(summarize(infeasible, statistics=["value"]).empty) + across = Criteria({"cost": "min", "value": "max"}, across=Across(rule="mean")) + scenarios = pd.concat( + [_partly_infeasible("s1"), _partly_infeasible("s2")], ignore_index=True + ) + self.assertEqual(len(summarize(scenarios, across)), 2) + self.assertTrue(summarize(scenarios.iloc[:0], across).empty) + + +class TestParetoProbability(unittest.TestCase): + """ + Unit tests for the probability of Pareto efficiency. + """ + + def test_settled(self): + """Designs separated in every replicate are efficient or not for sure.""" + results = _replicates([[1, 2, 3], [5, 6, 7]]) + probability = pareto_probability(results, {"cost": "min", "value": "max"}) + self.assertEqual(list(probability.pareto_probability), [0, 1]) + self.assertEqual(list(probability.pareto), [False, True]) + self.assertEqual(list(probability.value), [2, 6]) + + def test_common_random_numbers(self): + """Designs that differ by a constant in every replicate are settled.""" + rng = np.random.default_rng(0) + common = rng.normal(0, 5, 8) + results = _replicates([common, common + 0.1]) + probability = pareto_probability(results, {"cost": "min", "value": "max"}) + self.assertEqual(list(probability.pareto_probability), [0, 1]) + + def test_unsettled(self): + """Designs whose order changes between replicates are uncertain.""" + # equal means: d0 varies between replicates, d1 does not + results = _replicates([[0, 2] * 4, [1] * 8]) + probability = pareto_probability( + results, {"cost": "min", "value": "max"}, n_resamples=300 + ) + p = probability.pareto_probability + self.assertTrue(((p > 0.05) & (p < 0.95)).all()) + + def test_groups(self): + """Fronts of groups are found separately.""" + results = pd.concat( + [ + _replicates([[1, 2], [3, 4]]).assign(sensor="a"), + _replicates([[3, 4], [1, 2]]).assign(sensor="b"), + ] + ) + probability = pareto_probability( + results, Criteria({"cost": "min", "value": "max"}, by=["sensor"]) + ) + winners = probability[probability.pareto_probability == 1] + self.assertEqual( + sorted(zip(winners.sensor, winners.design)), [("a", "d1"), ("b", "d0")] + ) + + def test_design_values(self): + """Probabilities keep the values of the designs, as summaries do.""" + results = _replicates([[1, 2], [3, 4]]) + results["size"] = results["design"].map({"d0": "small", "d1": "large"}) + results["seed"] = results["replicate"] # an uncertain parameter + probability = pareto_probability(results, {"cost": "min", "value": "max"}) + self.assertEqual(list(probability["size"]), ["small", "large"]) + self.assertNotIn("seed", probability.columns) + + def test_quantile_objective(self): + """A pessimistic objective prefers the design with less spread.""" + objectives = {"cost": "min", "value": "max"} + by_mean = pareto_probability(_results(), objectives).set_index("design") + self.assertTrue(by_mean.loc["b", "pareto"]) # b has the larger mean + pessimistic = pareto_probability( + _results(), + Criteria( + {"cost": "min", "value q": "max"}, + statistics={"value q": Quantile("value", 0.25)}, + ), + ).set_index("design") + self.assertTrue(pessimistic.loc["a", "pareto"]) + self.assertFalse(pessimistic.loc["b", "pareto"]) + + def test_requirements(self): + """Designs that miss a requirement are not efficient.""" + probability = pareto_probability( + _results(), + Criteria( + {"cost": "min", "value": "max"}, + requirements=[Requirement("reliable", ">=", 0.75)], + statistics={"reliable": Probability("value", ">=", 10)}, + ), + ).set_index("design") + self.assertEqual(list(probability.meets_requirements), [True, False, False]) + # a is efficient unless b meets the requirement (and dominates it) + self.assertEqual(probability.loc["a", "requirements_probability"], 1) + self.assertGreater(probability.loc["a", "pareto_probability"], 0.5) + self.assertLess(probability.loc["a", "pareto_probability"], 1) + self.assertEqual(probability.loc["c", "pareto_probability"], 0) + # b meets the threshold in half of its replicates: it meets the + # requirement in some resamples, and is then efficient + self.assertGreater(probability.loc["b", "requirements_probability"], 0.1) + self.assertLess(probability.loc["b", "requirements_probability"], 0.9) + self.assertEqual(probability.loc["c", "requirements_probability"], 0) + + def test_unequal_replicates(self): + """Designs may have different replicates.""" + results = _results() + results = results[~((results.design == "c") & (results.replicate > 0))] + probability = pareto_probability(results, {"cost": "min", "value": "max"}) + self.assertEqual(list(probability.replicates), [4, 4, 1]) + self.assertEqual( + probability.set_index("design").loc["c", "pareto_probability"], 1 + ) + + def test_standard_errors(self): + """The standard error of an objective that is a mean is that of + summaries, and that of others that of the bootstrap.""" + rng = np.random.default_rng(0) + results = pd.DataFrame( + [ + { + "design": design, + "replicate": r, + "feasible": True, + "x": float(i), + "y": i + rng.normal(0, 2), + } + for i, design in enumerate("ab") + for r in range(40) + ] + ) + probability = pareto_probability( + results, {"x": "min", "y": "max"}, n_resamples=50 + ) + # x is the same in every replicate of each design + self.assertNotIn("x se", probability.columns) + summary = summarize(results, {"x": "min", "y": "max"}) + for column in ("y std", "y se"): + np.testing.assert_allclose(probability[column], summary[column]) + # the standard deviation of the 0.2 quantile over the resamples + quantile = Criteria( + {"x": "min", "y p20": "max"}, statistics=[Quantile("y", 0.2)] + ) + probability = pareto_probability(results, quantile, n_resamples=2000) + self.assertEqual( + list(probability.columns[1:5]), ["x", "y p20", "y p20 se", "replicates"] + ) + # about that of a normal distribution of a standard deviation of 2: + # sqrt(q (1 - q) / n) over the density at the quantile (of a sample) + z = -0.8416 + density = np.exp(-(z**2) / 2) / np.sqrt(2 * np.pi) / 2 + expected = np.sqrt(0.2 * 0.8 / 40) / density + ratio = probability["y p20 se"].to_numpy() / expected + self.assertTrue(((ratio > 0.4) & (ratio < 2.5)).all(), ratio) + + def test_resamples_share_replicates(self): + """A bootstrap draws each replicate in every scenario at once.""" + results = _scenarios({"s1": range(6), "s2": [10 - r for r in range(6)]}) + mean = Criteria({"v": "max"}, across=Across(rule="mean")) + probability = pareto_probability(results, mean, n_resamples=50) + self.assertAlmostEqual(probability["v"].iloc[0], 5.0) + # the mean of every resample is 5 + self.assertNotIn("v se", probability.columns) + worst = Criteria({"v": "max"}, across=Across()) + probability = pareto_probability(results, worst, n_resamples=50) + self.assertGreater(probability["v se"].iloc[0], 0.0) + + +class TestFeasibleProbability(unittest.TestCase): + """ + Unit tests for the probability of efficiency of designs infeasible in + some replicates. + """ + + @staticmethod + def _results(feasible): + """Two designs in eight replicates: d1, better, is feasible only where + given.""" + return pd.DataFrame( + [ + { + "design": design, + "replicate": r, + "feasible": True if design == "d0" else feasible[r], + "cost": 1.0, + "value": 1.0 if design == "d0" else 2.0, + } + for design in ("d0", "d1") + for r in range(len(feasible)) + ] + ) + + def test_feasible_requirement(self): + """A requirement on the share of feasible replicates is uncertain in + the bootstrap.""" + results = self._results([True, False] * 4) + criteria = Criteria( + {"cost": "min", "value": "max"}, + requirements=[Requirement("feasible", ">=", 0.5)], + ) + probability = pareto_probability(results, criteria, n_resamples=200) + probability = probability.set_index("design") + self.assertEqual(probability.loc["d1", "feasible"], 0.5) + self.assertEqual(probability.loc["d1", "replicates"], 4) + met = probability.loc["d1", "requirements_probability"] + self.assertGreater(met, 0.2) + self.assertLess(met, 0.9) + self.assertEqual(probability.loc["d0", "requirements_probability"], 1.0) + # without the requirement, d1 is judged by its feasible replicates, + # but for the few resamples that draw none of them (1 in 256) + plain = pareto_probability(results, {"cost": "min", "value": "max"}) + plain = plain.set_index("design") + self.assertGreater(plain.loc["d1", "pareto_probability"], 0.98) + self.assertAlmostEqual( + plain.loc["d0", "pareto_probability"], + 1 - plain.loc["d1", "pareto_probability"], + ) + + def test_infeasible_draws(self): + """A design whose drawn replicates are all infeasible is not judged + by its undrawn replicates.""" + rows = [] + for r in range(5): + rows.append( + { + "design": "rare", + "replicate": r, + "feasible": r == 0, + "value": 10.0 if r == 0 else np.nan, + } + ) + rows.append( + {"design": "steady", "replicate": r, "feasible": True, "value": 9.0} + ) + results = pd.DataFrame(rows) + probability = pareto_probability( + results, {"value": "max"}, n_resamples=4000, seed=1 + ).set_index("design") + # rare is efficient in the resamples that draw its replicate 0 + drawn = 1 - 0.8**5 + self.assertAlmostEqual( + probability.loc["rare", "pareto_probability"], drawn, delta=0.03 + ) + self.assertAlmostEqual( + probability.loc["steady", "pareto_probability"], 1 - drawn, delta=0.03 + ) + # nor does it meet the requirements without a feasible drawn replicate + self.assertAlmostEqual( + probability.loc["rare", "requirements_probability"], drawn, delta=0.03 + ) + self.assertEqual(probability.loc["steady", "requirements_probability"], 1.0) + + def test_infeasible_draws_standard_error(self): + """The bootstrap standard error of an objective that is not a mean is + over the resamples in which a design is judged.""" + rng = np.random.default_rng(3) + results = pd.DataFrame( + [ + { + "design": design, + "replicate": r, + # d0 is feasible in 5 of 15 replicates + "feasible": design == "d1" or r % 3 == 0, + "value": 5.0 + rng.normal(), + } + for design in ("d0", "d1") + for r in range(15) + ] + ) + criteria = Criteria({"value p50": "max"}, statistics=[Quantile("value", 0.5)]) + probability = pareto_probability( + results, criteria, n_resamples=1000, seed=0 + ).set_index("design") + # some resamples draw none of d0's feasible replicates (about 2 in + # 1000), which do not judge it, rather than making its error unknown + errors = probability["value p50 se"] + self.assertTrue(np.isfinite(errors).all()) + self.assertGreater(errors["d0"], errors["d1"]) + + def test_no_feasible_design(self): + """Results without a feasible record have an empty summary.""" + results = self._results([False] * 4) + results = results[results.design == "d1"].drop(columns=["cost", "value"]) + with warnings.catch_warnings(): + warnings.simplefilter("error") + probability = pareto_probability(results, {"cost": "min", "value": "max"}) + self.assertTrue(probability.empty) + self.assertEqual( + list(probability.columns[-6:]), + [ + "feasible", + "violation", + "meets_requirements", + "pareto", + "pareto_probability", + "requirements_probability", + ], + ) + self.assertIn("value se", probability.columns) diff --git a/tests/tradespace/test_tables.py b/tests/tradespace/test_tables.py new file mode 100644 index 0000000..6232f13 --- /dev/null +++ b/tests/tradespace/test_tables.py @@ -0,0 +1,114 @@ +""" +Unit tests for the tables of trade studies: the results of studies and the +summaries of their designs. + +@author Paul T. Grogan +""" + +import unittest + +import numpy as np +import pandas as pd + +from tatc.tradespace import Mean +from tatc.tradespace.tables import ( + check_records, + check_summary, + design_values, + draw_resamples, + efficient_keys, + feasible_records, + groups, + matrices, + names, + value_columns, +) + + +def _results(): + """Results of two designs in two replicates, one infeasible.""" + return pd.DataFrame( + { + "design": ["a", "a", "b", "b"], + "replicate": [0, 1, 0, 1], + "feasible": [True, True, True, False], + "size": [1, 1, 2, 2], + "seed": [7, 8, 7, 8], + "value": [1.0, 3.0, 2.0, np.nan], + } + ) + + +class TestTables(unittest.TestCase): + """ + Unit tests for tables of results and summaries. + """ + + def test_names(self): + """Names are given as a name or a sequence of names.""" + self.assertEqual(names("a"), ["a"]) + self.assertEqual(names(("a", "b")), ["a", "b"]) + + def test_groups(self): + """Groups are the positions of the rows of each value.""" + frame = _results() + self.assertEqual([key for key, _ in groups(frame, ())], [()]) + found = {key: list(rows) for key, rows in groups(frame, ["size"])} + self.assertEqual(found, {(1,): [0, 1], (2,): [2, 3]}) + with self.assertRaises(ValueError): + list(groups(frame, ["sensor"])) + + def test_records(self): + """Results need one record per evaluation, and a summary one row per + design.""" + results = _results() + check_records(results) + doubled = pd.concat([results, results.assign(sensor="y", value=0.0)]) + with self.assertRaisesRegex(ValueError, r"as `by`, such as \['sensor'\]$"): + check_records( + doubled.fillna({"sensor": "x"}), hint="as `by`", metrics=["value"] + ) + # columns of the evaluation, and metrics, do not separate them + check_records(doubled, ["design", "replicate", "sensor"]) + with self.assertRaisesRegex(ValueError, "summarize"): + check_summary(results) + check_summary(results, by=["replicate"]) + + def test_matrices(self): + """The values of metrics of designs in replicates.""" + designs, replicates, values = matrices(_results(), ["value"]) + self.assertEqual(list(designs), ["a", "b"]) + self.assertEqual(list(replicates), [0, 1]) + np.testing.assert_array_equal(values["value"], [[1.0, 3.0], [2.0, np.nan]]) + with self.assertRaises(ValueError): + matrices(_results(), ["cost"]) + + def test_values_of_designs(self): + """The values of designs are the columns of their feasible records that + do not vary.""" + feasible, infeasible = feasible_records(_results()) + self.assertEqual((len(feasible), len(infeasible)), (3, 1)) + statistics = {"value": Mean("value")} + self.assertEqual(value_columns(_results(), statistics, (), None), ["size"]) + self.assertEqual(value_columns(_results(), statistics, ("size",), None), []) + self.assertEqual( + value_columns(_results(), {}, (), ["size", "value"]), ["size", "value"] + ) + frame = design_values(_results(), ["b", "a"], ["size"]) + self.assertEqual(frame.to_dict("list"), {"design": ["b", "a"], "size": [2, 1]}) + + def test_resamples(self): + """Resamples draw replicates with replacement.""" + drawn = draw_resamples(5, 3, 0) + self.assertEqual(drawn.shape, (3, 5)) + self.assertTrue(((drawn >= 0) & (drawn < 5)).all()) + np.testing.assert_array_equal(drawn, draw_resamples(5, 3, 0)) + with self.assertRaises(ValueError): + draw_resamples(5, 1, 0) + + def test_efficient_keys(self): + """The efficient designs of a summary, each once, in order.""" + summary = pd.DataFrame( + {"design": ["b", "a", "b", "c"], "pareto": [True, False, True, True]} + ) + self.assertEqual(efficient_keys(summary), ["b", "c"]) diff --git a/tests/tradespace/test_utility.py b/tests/tradespace/test_utility.py new file mode 100644 index 0000000..eb8e02a --- /dev/null +++ b/tests/tradespace/test_utility.py @@ -0,0 +1,234 @@ +""" +Unit tests for utilities of the metrics of designs. + +@author Paul T. Grogan +""" + +import math +import unittest + +import numpy as np +import pandas as pd + +from tatc.tradespace import ( + Criteria, + ExponentialUtility, + LinearUtility, + Mean, + PiecewiseUtility, + Probability, + Quantile, + Requirement, + StandardDeviation, + Utility, + pareto_front, + summarize, +) + + +class TestSingleAttribute(unittest.TestCase): + """ + Unit tests for single-attribute utilities. + """ + + def test_linear(self): + """Linear utilities are 0 at the worst value and 1 at the best.""" + u = LinearUtility(0, 100) + np.testing.assert_allclose( + u([-10, 0, 50, 100, 120, np.nan]), [0, 0, 0.5, 1, 1, np.nan] + ) + # a metric to minimize + self.assertAlmostEqual(float(LinearUtility(10, 2)(6)), 0.5) + with self.assertRaises(ValueError): + LinearUtility(1, 1) + + def test_exponential(self): + """Exponential utilities are concave if averse, convex if seeking.""" + np.testing.assert_allclose(ExponentialUtility(0, 10, 2)([0, 10]), [0, 1]) + averse = float(ExponentialUtility(0, 10, 2)(5)) + self.assertAlmostEqual(averse, (1 - math.exp(-1)) / (1 - math.exp(-2))) + self.assertGreater(averse, 0.5) + self.assertLess(float(ExponentialUtility(0, 10, -2)(5)), 0.5) + np.testing.assert_allclose( + ExponentialUtility(0, 10)([2, 7]), LinearUtility(0, 10)([2, 7]) + ) + self.assertTrue(np.isnan(ExponentialUtility(0, 10, 2)(np.nan))) + + def test_piecewise(self): + """Piecewise utilities interpolate between points.""" + u = PiecewiseUtility([(50, 0.8), (0, 0), (100, 1)]) + np.testing.assert_allclose(u([-5, 25, 50, 75, 200]), [0, 0.4, 0.8, 0.9, 1]) + decreasing = PiecewiseUtility([(0, 1), (10, 0)]) + self.assertAlmostEqual(float(decreasing(2.5)), 0.75) + self.assertTrue(np.isnan(u(np.nan))) + for points in ([(0, 0)], [(0, 0), (0, 1)], [(0, 0), (1, 2)]): + with self.subTest(points=points): + with self.assertRaises(ValueError): + PiecewiseUtility(points) + + +class TestUtility(unittest.TestCase): + """ + Unit tests for multi-attribute utilities. + """ + + def setUp(self): + self.attributes = {"a": LinearUtility(0, 1), "b": LinearUtility(0, 1)} + + def test_additive(self): + """Additive utilities are weighted sums, by normalized weights.""" + u = Utility(self.attributes, {"a": 3, "b": 1}) + np.testing.assert_allclose( + u.evaluate( + {"a": np.array([1.0, 0.0, 0.5]), "b": np.array([0.0, 1.0, 0.5])} + ), + [0.75, 0.25, 0.5], + ) + self.assertEqual(u.scaling, 0.0) + self.assertEqual(u.columns, ("a", "b")) + + def test_multiplicative(self): + """Multiplicative utilities solve their scaling constant from the + weights: complements if they sum to less than 1, substitutes if more.""" + complements = Utility(self.attributes, {"a": 0.5, "b": 0.3}, "multiplicative") + # 1 + K = (1 + 0.5 K)(1 + 0.3 K) + self.assertAlmostEqual(complements.scaling, 4 / 3, places=9) + substitutes = Utility(self.attributes, {"a": 0.7, "b": 0.6}, "multiplicative") + self.assertAlmostEqual(substitutes.scaling, -0.3 / 0.42, places=9) + for u in (complements, substitutes): + values = { + "a": np.array([0.0, 1.0, 1.0, 0.0]), + "b": np.array([0.0, 1.0, 0.0, 1.0]), + } + weights = u.weights + np.testing.assert_allclose( + u.evaluate(values), [0, 1, weights["a"], weights["b"]], atol=1e-9 + ) + # complements reward doing well in both, substitutes in either + half = {"a": np.array([0.5]), "b": np.array([0.5])} + self.assertLess(complements.evaluate(half)[0], substitutes.evaluate(half)[0]) + # weights that sum to 1 are additive + additive = Utility(self.attributes, {"a": 0.4, "b": 0.6}, "multiplicative") + self.assertEqual(additive.scaling, 0.0) + + def test_frame(self): + """Utilities of the rows of a data frame.""" + u = Utility(self.attributes, {"a": 1, "b": 1}) + frame = pd.DataFrame({"a": [1.0, 0.0], "b": [1.0, 0.5]}, index=["x", "y"]) + pd.testing.assert_series_equal( + u(frame), pd.Series([1.0, 0.25], index=["x", "y"], name="utility") + ) + with self.assertRaises(ValueError): + u(frame.drop(columns="b")) + + def test_invalid(self): + """Utilities need a positive weight of each attribute.""" + for weights, form in ( + ({"a": 1}, "additive"), + ({"a": 1, "b": 1, "c": 1}, "additive"), + ({"a": 0, "b": 1}, "additive"), + ({"a": 1, "b": 1}, "other"), + ({"a": 1.5, "b": 0.5}, "multiplicative"), + ): + with self.subTest(weights=weights, form=form): + with self.assertRaises(ValueError): + Utility(self.attributes, weights, form) + with self.assertRaises(ValueError): + Utility({}, {}) + + +def _results(): + """Two designs in two replicates: x varies between replicates, y does not + (with the same mean of a).""" + return pd.DataFrame( + { + "design": ["x", "x", "y", "y"], + "replicate": [0, 1, 0, 1], + "feasible": True, + "a": [0.0, 1.0, 0.5, 0.5], + "cost": [1.0, 1.0, 2.0, 2.0], + } + ) + + +class TestStatistics(unittest.TestCase): + """ + Unit tests for statistics of utilities. + """ + + def setUp(self): + self.utility = Utility({"a": ExponentialUtility(0, 1, 2)}, {"a": 1}) + + def test_expected_utility(self): + """The mean of a utility is its expected value over the replicates, + which penalizes the spread of a risk-averse utility.""" + criteria = Criteria({"utility": "max"}, statistics={"utility": self.utility}) + self.assertEqual(criteria.metrics, ["a"]) + summary = summarize(_results(), criteria).set_index("design") + expected = (0 + 1) / 2 + self.assertAlmostEqual(summary.loc["x", "utility"], expected) + self.assertAlmostEqual( + summary.loc["y", "utility"], float(ExponentialUtility(0, 1, 2)(0.5)) + ) + # the utility of the means is the same for both + means = summarize(_results(), statistics=["a"]).set_index("design") + np.testing.assert_allclose(self.utility(means), self.utility(means).iloc[0]) + + def test_statistics(self): + """Utilities are metrics of any statistic.""" + statistics = { + "worst": Quantile(self.utility, 0), + "reliable": Probability(self.utility, ">=", 0.5), + "expected": Mean(self.utility), + } + summary = summarize(_results(), statistics=statistics).set_index("design") + self.assertEqual(summary.loc["x", "worst"], 0.0) + self.assertEqual(summary.loc["x", "reliable"], 0.5) + self.assertEqual(summary.loc["y", "reliable"], 1.0) + self.assertEqual(Mean(self.utility), Mean(self.utility)) + self.assertEqual(len({Mean(self.utility), Mean(self.utility)}), 1) + + def test_summarize(self): + """Summaries give the spread of the mean of a utility, as of a column.""" + criteria = Criteria( + {"utility": "max", "cost": "min"}, statistics=[Mean(self.utility)] + ) + summary = summarize(_results(), criteria).set_index("design") + for column in ("utility std", "utility se"): + self.assertIn(column, summary.columns) + # the cost of each design is the same in every replicate + for column in ("cost std", "cost se"): + self.assertNotIn(column, summary.columns) + # as of the statistic + spread = summarize( + _results(), + criteria, + statistics={"utility std": StandardDeviation(self.utility)}, + spread=False, + ).set_index("design") + pd.testing.assert_series_equal(summary["utility std"], spread["utility std"]) + self.assertEqual(summary.loc["y", "utility std"], 0.0) + + def test_utility_against_cost(self): + """Designs trade the utility of their metrics against cost.""" + criteria = Criteria( + {"utility": "max", "cost": "min"}, + statistics={"utility": self.utility}, + requirements=[Requirement("worst", ">=", 0.1)], + ) + # a requirement on a statistic that the criteria do not name + with self.assertRaises(ValueError): + summarize(_results(), criteria) + criteria = Criteria( + {"utility": "max", "cost": "min"}, + statistics={"utility": self.utility, "worst": Quantile(self.utility, 0)}, + requirements=[Requirement("worst", ">=", 0.1)], + ) + summary = summarize(_results(), criteria) + front = summary[pareto_front(summary, criteria)] + # x is cheaper, but misses the requirement on its worst replicate + self.assertEqual(list(front.design), ["y"]) + + +if __name__ == "__main__": + unittest.main()