tradespace 0.1.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (125) hide show
  1. tradespace-0.1.0/.gitignore +32 -0
  2. tradespace-0.1.0/CHANGELOG.md +147 -0
  3. tradespace-0.1.0/LICENSE +21 -0
  4. tradespace-0.1.0/PKG-INFO +74 -0
  5. tradespace-0.1.0/README.md +44 -0
  6. tradespace-0.1.0/pyproject.toml +79 -0
  7. tradespace-0.1.0/src/tradespace/__init__.py +30 -0
  8. tradespace-0.1.0/src/tradespace/coordinates.py +152 -0
  9. tradespace-0.1.0/src/tradespace/datasets.py +258 -0
  10. tradespace-0.1.0/src/tradespace/estimator.py +852 -0
  11. tradespace-0.1.0/src/tradespace/gaps.py +218 -0
  12. tradespace-0.1.0/src/tradespace/plotting.py +1468 -0
  13. tradespace-0.1.0/src/tradespace/preconditioning.py +314 -0
  14. tradespace-0.1.0/src/tradespace/predictive.py +252 -0
  15. tradespace-0.1.0/src/tradespace/py.typed +0 -0
  16. tradespace-0.1.0/src/tradespace/solvers.py +1413 -0
  17. tradespace-0.1.0/src/tradespace/tensions.py +573 -0
  18. tradespace-0.1.0/src/tradespace/tuning.py +142 -0
  19. tradespace-0.1.0/tests/_env.py +45 -0
  20. tradespace-0.1.0/tests/conftest.py +74 -0
  21. tradespace-0.1.0/tests/data/g18_equal_slack_fixture.npz +0 -0
  22. tradespace-0.1.0/tests/data/soft_fit_default_reference.npz +0 -0
  23. tradespace-0.1.0/tests/data/v2_first_designs_of_record.csv +21 -0
  24. tradespace-0.1.0/tests/data/wp45/amniote/test-record.md +134 -0
  25. tradespace-0.1.0/tests/data/wp45/perovskite/test-record.md +120 -0
  26. tradespace-0.1.0/tests/data/wp45/wheat/test-record.md +135 -0
  27. tradespace-0.1.0/tests/data/wp57/assumptions-queue.md +16 -0
  28. tradespace-0.1.0/tests/data/wp78/actions__permissions__workflow.json +1 -0
  29. tradespace-0.1.0/tests/data/wp78/collaborators__danlessa__permission.json +1 -0
  30. tradespace-0.1.0/tests/data/wp78/collaborators__jshorish__permission.json +1 -0
  31. tradespace-0.1.0/tests/data/wp78/collaborators__mzargham__permission.json +1 -0
  32. tradespace-0.1.0/tests/data/wp78/collaborators__rororowyourboat__permission.json +1 -0
  33. tradespace-0.1.0/tests/data/wp78/environments.json +1 -0
  34. tradespace-0.1.0/tests/data/wp78/environments__github-pages__deployment-branch-policies.json +1 -0
  35. tradespace-0.1.0/tests/data/wp78/environments__paper-release__deployment-branch-policies.json +1 -0
  36. tradespace-0.1.0/tests/data/wp78/environments__pypi__deployment-branch-policies.json +1 -0
  37. tradespace-0.1.0/tests/data/wp78/environments__testpypi__deployment-branch-policies.json +1 -0
  38. tradespace-0.1.0/tests/data/wp78/pages.json +1 -0
  39. tradespace-0.1.0/tests/data/wp78/rulesets.json +1 -0
  40. tradespace-0.1.0/tests/data/wp78/rulesets__27470804.json +1 -0
  41. tradespace-0.1.0/tests/data/wp78/rulesets__27471737.json +1 -0
  42. tradespace-0.1.0/tests/data/wp78/rulesets__27471794.json +1 -0
  43. tradespace-0.1.0/tests/data/wp78/rulesets__27471877.json +1 -0
  44. tradespace-0.1.0/tests/fixtures/user-tests/ANSWERS.md +22 -0
  45. tradespace-0.1.0/tests/fixtures/user-tests/README.md +19 -0
  46. tradespace-0.1.0/tests/fixtures/user-tests/export_pump_table.py +72 -0
  47. tradespace-0.1.0/tests/fixtures/user-tests/make_plain_table.py +51 -0
  48. tradespace-0.1.0/tests/fixtures/user-tests/plain_table.csv +251 -0
  49. tradespace-0.1.0/tests/fixtures/user-tests/pump_table.csv +201 -0
  50. tradespace-0.1.0/tests/fixtures/user-tests/pump_trade.sysml +54 -0
  51. tradespace-0.1.0/tests/test_adcs_case.py +254 -0
  52. tradespace-0.1.0/tests/test_adcs_enrichment.py +361 -0
  53. tradespace-0.1.0/tests/test_admissibility.py +289 -0
  54. tradespace-0.1.0/tests/test_bridge_page.py +26 -0
  55. tradespace-0.1.0/tests/test_build_generated.py +502 -0
  56. tradespace-0.1.0/tests/test_case.py +977 -0
  57. tradespace-0.1.0/tests/test_case_model_howto.py +324 -0
  58. tradespace-0.1.0/tests/test_check_designs.py +120 -0
  59. tradespace-0.1.0/tests/test_check_script.py +89 -0
  60. tradespace-0.1.0/tests/test_ci_shards.py +96 -0
  61. tradespace-0.1.0/tests/test_claims_register.py +311 -0
  62. tradespace-0.1.0/tests/test_container.py +83 -0
  63. tradespace-0.1.0/tests/test_contributing_links.py +51 -0
  64. tradespace-0.1.0/tests/test_coordinates.py +66 -0
  65. tradespace-0.1.0/tests/test_cost_model.py +360 -0
  66. tradespace-0.1.0/tests/test_cubesat_model.py +596 -0
  67. tradespace-0.1.0/tests/test_cubesat_oracle.py +638 -0
  68. tradespace-0.1.0/tests/test_datasets.py +132 -0
  69. tradespace-0.1.0/tests/test_derivation.py +1155 -0
  70. tradespace-0.1.0/tests/test_diagnostic_pair.py +131 -0
  71. tradespace-0.1.0/tests/test_docs.py +295 -0
  72. tradespace-0.1.0/tests/test_estimator.py +911 -0
  73. tradespace-0.1.0/tests/test_experiments.py +561 -0
  74. tradespace-0.1.0/tests/test_fleet_coverage.py +74 -0
  75. tradespace-0.1.0/tests/test_gaps.py +257 -0
  76. tradespace-0.1.0/tests/test_index.py +199 -0
  77. tradespace-0.1.0/tests/test_interface_contract.py +1229 -0
  78. tradespace-0.1.0/tests/test_k_terms_case.py +78 -0
  79. tradespace-0.1.0/tests/test_ledger_gate_wp30.py +82 -0
  80. tradespace-0.1.0/tests/test_legacy_oracle.py +181 -0
  81. tradespace-0.1.0/tests/test_line_endings.py +46 -0
  82. tradespace-0.1.0/tests/test_matches_derivation.py +310 -0
  83. tradespace-0.1.0/tests/test_model_checking_v2.py +1021 -0
  84. tradespace-0.1.0/tests/test_model_coverage.py +490 -0
  85. tradespace-0.1.0/tests/test_mutation_v2.py +129 -0
  86. tradespace-0.1.0/tests/test_narrative.py +210 -0
  87. tradespace-0.1.0/tests/test_noise_lemmas.py +238 -0
  88. tradespace-0.1.0/tests/test_noise_ridge.py +344 -0
  89. tradespace-0.1.0/tests/test_package.py +8 -0
  90. tradespace-0.1.0/tests/test_paper.py +4852 -0
  91. tradespace-0.1.0/tests/test_paper_model.py +544 -0
  92. tradespace-0.1.0/tests/test_paper_slot.py +450 -0
  93. tradespace-0.1.0/tests/test_paper_sources.py +133 -0
  94. tradespace-0.1.0/tests/test_paper_static_figures.py +79 -0
  95. tradespace-0.1.0/tests/test_plotting.py +591 -0
  96. tradespace-0.1.0/tests/test_preconditioning.py +255 -0
  97. tradespace-0.1.0/tests/test_predictive.py +161 -0
  98. tradespace-0.1.0/tests/test_proof_map.py +1271 -0
  99. tradespace-0.1.0/tests/test_references.py +157 -0
  100. tradespace-0.1.0/tests/test_release_checks.py +208 -0
  101. tradespace-0.1.0/tests/test_release_cleanup.py +170 -0
  102. tradespace-0.1.0/tests/test_release_version.py +34 -0
  103. tradespace-0.1.0/tests/test_release_workflows.py +233 -0
  104. tradespace-0.1.0/tests/test_repo_settings.py +390 -0
  105. tradespace-0.1.0/tests/test_residuals.py +229 -0
  106. tradespace-0.1.0/tests/test_sensitivity.py +297 -0
  107. tradespace-0.1.0/tests/test_site.py +2136 -0
  108. tradespace-0.1.0/tests/test_site_metadata.py +331 -0
  109. tradespace-0.1.0/tests/test_sklearn_compat.py +150 -0
  110. tradespace-0.1.0/tests/test_soft_fit.py +417 -0
  111. tradespace-0.1.0/tests/test_solver_discovery.py +30 -0
  112. tradespace-0.1.0/tests/test_solvers.py +521 -0
  113. tradespace-0.1.0/tests/test_system_model_v2.py +984 -0
  114. tradespace-0.1.0/tests/test_system_model_v2_r1.py +606 -0
  115. tradespace-0.1.0/tests/test_temperature_path.py +195 -0
  116. tradespace-0.1.0/tests/test_tensions.py +509 -0
  117. tradespace-0.1.0/tests/test_text_encoding.py +93 -0
  118. tradespace-0.1.0/tests/test_toolkit.py +296 -0
  119. tradespace-0.1.0/tests/test_tuning.py +96 -0
  120. tradespace-0.1.0/tests/test_user_test_fixtures.py +76 -0
  121. tradespace-0.1.0/tests/test_v2_data.py +427 -0
  122. tradespace-0.1.0/tests/test_verification_pointers.py +103 -0
  123. tradespace-0.1.0/tests/test_vocabulary.py +270 -0
  124. tradespace-0.1.0/tests/test_wp30_cost_ladders.py +141 -0
  125. tradespace-0.1.0/tests/test_wp45_examples.py +192 -0
@@ -0,0 +1,32 @@
1
+ # Python
2
+ __pycache__/
3
+ *.py[cod]
4
+ *.egg-info/
5
+ build/
6
+ dist/
7
+ .pytest_cache/
8
+ .ruff_cache/
9
+ .coverage
10
+ htmlcov/
11
+ .ipynb_checkpoints/
12
+
13
+ # uv / environments
14
+ .venv/
15
+
16
+ # site builds and generated docs pages
17
+ _site/
18
+ _stage/
19
+ docs/generated/
20
+
21
+ # OS / editors
22
+ .DS_Store
23
+ .vscode/
24
+ .idea/
25
+
26
+ # WP45 example caches (hash-checked downloads; nothing redistributed)
27
+ examples/perovskite/data/
28
+ examples/amniote/data/
29
+ examples/wheat/data/
30
+
31
+ # local copies of removed work-package documents
32
+ work-packages/archive/
@@ -0,0 +1,147 @@
1
+ # Changelog
2
+
3
+ All notable changes to this project are recorded here, in the format of
4
+ [Keep a Changelog](https://keepachangelog.com/en/1.1.0/). The project follows
5
+ [Semantic Versioning](https://semver.org/). Entries are drawn from the work-package index
6
+ (`work-packages/INDEX.md`) and the git history; the package that made each change is named in parentheses.
7
+
8
+ ## [0.1.0] - 2026-11-17
9
+
10
+ ### Added
11
+
12
+ - Two release lifecycles. The software (the package, the docs and the root page) is released by the merge of a
13
+ pull request from `dev` into `main`: the release workflow checks admissibility, runs the suite, builds, creates
14
+ the tag `v<version>`, publishes to PyPI by trusted publishing, deploys the site and publishes the GitHub release;
15
+ a failure is named in the run, cleaned up by `scripts/release_cleanup.py` and reported in an issue; a merge
16
+ without a new version redeploys the site only. The paper has its own branch (`paper`), tags (`paper-*`, published
17
+ as GitHub releases on a code owner's approval) and change record (`paper/CHANGES.md`); its tests run in its own
18
+ workflow and leave the software's suite. `/paper/` serves the mode named in `paper/mode.toml`, which is
19
+ `abstract` (the title, the author and the abstract) (WP65, WP66).
20
+ - Release engineering and governance: the release workflow with trusted publishing, a software bill of materials
21
+ and the version and changelog gates; five enforcement workflows; `CONTRIBUTING.md`, `CODE_OF_CONDUCT.md`,
22
+ `SECURITY.md`, code owners, and issue and pull-request templates with their admissibility conditions (WP47).
23
+ - Lint and the Linux fast shard run on every push to `dev`; the full matrix runs on the release pull request and
24
+ when the release workflow calls it (WP67).
25
+ - Governance as executable: the repository's settings (rulesets, environments, Pages, the code owners' access, the
26
+ workflow permissions) declared in `.github/governance.toml`, checked against the live repository by
27
+ `scripts/check_repo_settings.py` in a `controls` job that runs first in the Tests and Release workflows, and
28
+ attested in each release's notes; `GOVERNANCE.md` states the release rules, the two reviews and the repository's
29
+ secondary rules (WP78).
30
+ - The paper's own contribution route: a `/paper/` line in `.github/CODEOWNERS` names the paper's approvers apart from
31
+ the code owners, a pull request into `paper` is merged by an approver who is not its author, the pull request
32
+ template has a paper section, and "Contributing to the paper" in `CONTRIBUTING.md` and "The paper's route" in
33
+ `GOVERNANCE.md` say how the paper is edited, approved, published and reaches the site (WP79).
34
+ - Public-link metadata on every page of the site: a description, a canonical address, Open Graph and Twitter card
35
+ fields with a preview image, structured data for the software and the site, `robots.txt` and a sitemap, from
36
+ one source of values (WP80).
37
+ - Windows as a third platform for the fast and slow test shards, run on dispatch and at gates; the paper's tests
38
+ run in the paper's workflow (WP34).
39
+ - The package `tradespace` (alias `hts`): the posynomial invariant form for a trade
40
+ space, with the scikit-learn estimator `HyperbolicTradeSpace` (fit, `transform`,
41
+ `inverse_transform`, `score_samples`), the frontier chart (Helmert and additive-log-ratio
42
+ coordinates) and the entropic (log-mean-exp) soft maximum (WP2).
43
+ - The K = 1 (monomial) fit with its solvers, and tests under scikit-learn's estimator checks (WP2).
44
+ - The several-term (K > 1) posynomial fit with sharp term assignment, a mean-slack objective and
45
+ a sparsity option (WP9), and the fit with soft weights (WP17).
46
+ - Certificates and a stopping declaration printed by a fit (WP13).
47
+ - Conditioning and analysis tools: `LogAffinePreconditioner`, `frontier_in_original_units`,
48
+ `select_temperature`, `TradeSpaceRegressor`, holes and frontier targets (`find_holes`,
49
+ `frontier_targets`, `knn_gap_scores`) (WP3).
50
+ - `trade_off_report`: the tensions that define the trade-offs, with elasticities (WP3, WP13; named
51
+ `tension_report` until WP42).
52
+ - The fit temperature as a path: `temperature_path` and `plot_temperature_path`, the user-guide page "The fit
53
+ temperature", and the small-temperature lemma L22 (WP46).
54
+ - Plotting: the log plane, the 3-D frontier surface, frontier coordinates, tensions, and ternary
55
+ plots documented in the examples (WP3, WP18).
56
+ - The derivation ledger: plain-SymPy lemma scripts L1 to L22 in `derivation/`, an axioms ledger, a
57
+ proof-map checker and its committed record (WP1, WP9, WP13, WP17, WP29, WP42, WP46).
58
+ - The noise result: lemma scripts L18 to L20 (the noise covariance under the conditioning map, the shift bound,
59
+ noise as a ridge on the exponents) with planted-data tests (WP29).
60
+ - The documentation site (MkDocs): getting started, user guide, theory, API reference generated
61
+ from docstrings, generated glossary and derivation pages, further reading and a bibliography
62
+ with resolved references (WP5, WP6, WP8a).
63
+ - A root page and one-command local staging of the site (WP8a, WP14); the root page recast as why, what and
64
+ how, with the three-metric triangle shaded by the trade-off that binds there and the pairwise slices, both
65
+ generated at build time from a planted table (WP51).
66
+ - A history and acknowledgements page on the root site, its dated reference list rendered from `history.yaml`
67
+ at build time (WP37), with the governance lineage on it (WP52).
68
+ - Journeys and signposting: the docs home leads with the five need links, the user guide has a router page, the
69
+ README carries the package-only install line and the paper link, and the package docstring names the docs
70
+ site (WP33).
71
+ - User-guide pages checked by package-user tests: four tasks run from the docs as written, with their fixtures
72
+ (a plain CSV, a pump SysML v2 model, an export script and its exported table) under `tests/fixtures/user-tests/`
73
+ (WP32).
74
+ - The bridge page, from the chart back to a design (WP41); a user-guide page on the routes back from a
75
+ tension (WP42).
76
+ - Two sentences on the limitations page: a proof in a theorem prover would fix each lemma's statement over the
77
+ reals and would not bound the double-precision error, which the certificates check (WP36).
78
+ - Three public case studies, perovskite solar cells, amniote life histories and Broadbalk wheat, each fetched
79
+ with a hash check, conditioned, fitted and read (WP45), with their conditioning ladders and chains (WP59);
80
+ their example pages (WP60), redrafted to one template with an arc (WP63); the wheat page's level V against
81
+ biomass (WP71).
82
+ - Stable reference keys from the docsite into the paper: `[text](paper:key)` names a label the paper
83
+ defines, the docs build turns it into a link to the paper page and anchor and fails on an undefined
84
+ key; the paper's article theme is pinned so a clean checkout builds the paper (WP8b).
85
+ - A user-guide page, "Choosing K": the checks that bear on the number of terms, what each can and cannot say,
86
+ a temperature recipe with `select_temperature`, and worked examples on planted tables and the cubesat (WP31).
87
+ - The interface contract between the technical and presentation sides, with its manifest
88
+ (WP14).
89
+ - The case study (a SysML-modelled illustrative cubesat attitude-control design space): the
90
+ simulation port, design space, seeded dataset, the SysML v2 model with an experiment ledger,
91
+ and the experiments module (WP4, WP4b, WP15).
92
+ - The paper as an executed notebook (mystmd), with a supporting-material notebook of
93
+ computationally verifiable appendices and a container definition (`Dockerfile`) for the
94
+ environment of record (WP10).
95
+ - The estimator keyword `term_aggregation` (`"sum"` default, `"mean"`), the count `n_distinct_terms`
96
+ on the termination record, and the bound stated for both aggregations (WP21).
97
+ - The case model in two views, configuration and assessment, in one SysML v2 model: requirements,
98
+ verification cases and a trace from configuration variables to assessed attributes to the traded
99
+ metrics (WP22); the model-realism loop that added total mass with launch cost as its measure of
100
+ effectiveness, so every design choice reaches at least one metric (WP23).
101
+ - The case model read in the OpenMBEE view editor, with a harness note for loading and reading it
102
+ there (WP26), and a stakeholder layer: two stakeholders, one tied to price and one to
103
+ performance in the operational life, their concerns traced to the requirements and the
104
+ metrics (WP27).
105
+ - Figures chosen by section, each with the purpose it serves and what it does not show (WP19).
106
+ - Developer tooling for verification in tiers: a fast test suite, a path-to-tests map
107
+ (`scripts/check.py`), parallel workers and a sharded Linux run (WP20).
108
+ - `LICENSE` (MIT, copyright 2026 Dynamical Systems Group) and this changelog.
109
+
110
+ ### Changed
111
+
112
+ - The package is named `tradespace` (import name `tradespace`, distribution name `tradespace`); it was
113
+ `hyperbolic-trade-space` during development and was never released under that name (WP77).
114
+ - The case study moves onto the model of record: the nine-attribute datasets, the settling time by
115
+ event detection, and the K = 1, 2, 3 record and the paper's numbers regenerated on them inside
116
+ the container of record; every moved number is listed with its cause in
117
+ [`work-packages/swap-evidence.md`](https://github.com/DynamicalSystemsGroup/tradespace/blob/4f81a4ea3649ff844cff2acdf9d447285cbb0fc5/work-packages/swap-evidence.md), and the earlier data stays as the cited comparison (WP16,
118
+ WP23).
119
+ - The word "facet" is gone from every surface, including the package's public names: the model's
120
+ objects are monomial terms (term assignment, distinct terms, per-term shares), the paper, the
121
+ docs, the glossary, the derivations and the interface contract follow (WP24).
122
+ - The tension matrix and the elasticity vocabulary across the package and the docs: `tension_report` becomes
123
+ `trade_off_report`, with `tension_matrix` and `design_tensions` beside it (WP42).
124
+ - The case study revised: momentum headroom as the ninth traded metric, the fleet-size variable and the cost
125
+ model; the datasets regenerated at 3,000 designs per regime and the cost ladders written from them (WP30).
126
+ - The residual pass: patterns that read as machine-written removed from the docs, the glossary and the example
127
+ pages, with a checker and its baseline (`scripts/check_residuals.py`) (WP38).
128
+ - Improvement by subtraction: one pass over the paper and the docs removed figures, arguments and
129
+ paragraphs that did not advance the narrative, each deletion recorded with what it no longer
130
+ did (WP28); repository tidiness passes removed unused files and closed drift between the docs,
131
+ the glossary and the code (WP25); release thinning and the repository's organization (WP40); live guidance
132
+ moved to `notes/` and `docs/superpowers` retired (WP62); the process record left the tree before 0.1, each
133
+ document indexed with the hash it is read at (WP73).
134
+ - The response to the independent assessment: the paper and docs keep three claims apart
135
+ (certificate, observed geometry, usefulness outside the observations) (WP21).
136
+ - The fit's formal statements made exact in the derivations and the ledger, following the
137
+ response to the external review (WP13).
138
+
139
+ ### Fixed
140
+
141
+ - The case model's views generator accepts a requirement usage under either type name,
142
+ `SatisfyRequirementUsage` or `VerifyRequirementUsage` (the external review's finding 7) (WP74).
143
+
144
+ ### Notes
145
+
146
+ - Not part of 0.1.0: the trade-off-aware search (WP12, after 0.1); an image on a registry; the
147
+ PDF export.
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Dynamical Systems Group
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
@@ -0,0 +1,74 @@
1
+ Metadata-Version: 2.5
2
+ Name: tradespace
3
+ Version: 0.1.0
4
+ Summary: Learns the shape of a design trade space from evaluated designs, with estimators that work in scikit-learn pipelines.
5
+ Project-URL: Homepage, https://dynamicalsystemsgroup.github.io/tradespace/
6
+ Project-URL: Documentation, https://dynamicalsystemsgroup.github.io/tradespace/docs/
7
+ Project-URL: Repository, https://github.com/DynamicalSystemsGroup/tradespace
8
+ Project-URL: Issues, https://github.com/DynamicalSystemsGroup/tradespace/issues
9
+ Project-URL: Changelog, https://github.com/DynamicalSystemsGroup/tradespace/blob/main/CHANGELOG.md
10
+ Author: Michael Zargham
11
+ License-Expression: MIT
12
+ License-File: LICENSE
13
+ Keywords: Pareto frontier,geometric programming,posynomial,scikit-learn,systems engineering,trade space
14
+ Classifier: Development Status :: 3 - Alpha
15
+ Classifier: Intended Audience :: Developers
16
+ Classifier: Intended Audience :: Science/Research
17
+ Classifier: Operating System :: OS Independent
18
+ Classifier: Programming Language :: Python :: 3
19
+ Classifier: Programming Language :: Python :: 3.12
20
+ Classifier: Topic :: Scientific/Engineering
21
+ Classifier: Topic :: Scientific/Engineering :: Mathematics
22
+ Requires-Python: <3.13,>=3.12
23
+ Requires-Dist: matplotlib>=3.8
24
+ Requires-Dist: numpy>=1.26
25
+ Requires-Dist: pandas>=2.0
26
+ Requires-Dist: scikit-learn>=1.8
27
+ Requires-Dist: scipy>=1.12
28
+ Requires-Dist: sympy>=1.12
29
+ Description-Content-Type: text/markdown
30
+
31
+ # tradespace
32
+
33
+ For analysts with a table of evaluated designs, to learn which metrics trade. See the
34
+ [docs](https://dynamicalsystemsgroup.github.io/tradespace/docs/),
35
+ [the paper](https://dynamicalsystemsgroup.github.io/tradespace/paper/) and `examples/adcs/` for a
36
+ case study.
37
+
38
+ ```bash
39
+ git clone https://github.com/DynamicalSystemsGroup/tradespace
40
+ cd tradespace && uv sync
41
+ # package only: uv sync --no-default-groups; uv run --no-default-groups
42
+ ```
43
+
44
+ ```python
45
+ from tradespace import (
46
+ HyperbolicTradeSpace,
47
+ LogAffinePreconditioner,
48
+ make_frontier_data,
49
+ trade_off_report,
50
+ )
51
+
52
+ A, _ = make_frontier_data(300, 3, random_state=0)
53
+ A[:, 1] = 10 / A[:, 1] # pretend column 1: smaller is better
54
+ M = LogAffinePreconditioner(orientation=[1, -1, 1]).fit_transform(A)
55
+ ts = HyperbolicTradeSpace(temperature=20.0).fit(M) # real table: `select_temperature`
56
+ print(trade_off_report(ts, M).exponents.round(2))
57
+ ```
58
+
59
+ ## Layout
60
+
61
+ - `src/tradespace/`: the Python package (fit a frontier, read its trade-offs).
62
+ - `docs/`: the user guide and API reference, built into the docs site.
63
+ - `paper/`: the paper as two notebooks and what rebuilds them; `site/` is the root page that links the docs and the paper.
64
+ - `examples/adcs/`: the cubesat attitude-control case study the paper uses: model, data, experiments, system model.
65
+ - `derivation/`: the proofs of the method's results as SymPy scripts, one per lemma.
66
+ - `tests/`: the test suite; `scripts/`: build and check tools.
67
+ - `claims_register.toml`: each claim the paper and docs make and what backs it.
68
+ - `glossary.yaml`: the terms, one name per object; `history.yaml`: the record behind the history and acknowledgements page.
69
+ - `CHANGELOG.md`: what changed, by work package.
70
+ - `work-packages/`: the build's record; not needed to use the method.
71
+ - `GOVERNANCE.md`: the release rules, the file that declares their settings (`.github/governance.toml`) and the check that runs first in CI.
72
+ - `CLAUDE.md`: conventions for contributors working with Claude Code.
73
+ - `mkdocs.yml`, `Dockerfile`, `pyproject.toml`, `uv.lock`, `.python-version`: build and environment files.
74
+ - `LICENSE`, `.github/` (CI workflows) and the dot-files `.gitattributes`, `.gitignore`, `.dockerignore`: license and repository settings.
@@ -0,0 +1,44 @@
1
+ # tradespace
2
+
3
+ For analysts with a table of evaluated designs, to learn which metrics trade. See the
4
+ [docs](https://dynamicalsystemsgroup.github.io/tradespace/docs/),
5
+ [the paper](https://dynamicalsystemsgroup.github.io/tradespace/paper/) and `examples/adcs/` for a
6
+ case study.
7
+
8
+ ```bash
9
+ git clone https://github.com/DynamicalSystemsGroup/tradespace
10
+ cd tradespace && uv sync
11
+ # package only: uv sync --no-default-groups; uv run --no-default-groups
12
+ ```
13
+
14
+ ```python
15
+ from tradespace import (
16
+ HyperbolicTradeSpace,
17
+ LogAffinePreconditioner,
18
+ make_frontier_data,
19
+ trade_off_report,
20
+ )
21
+
22
+ A, _ = make_frontier_data(300, 3, random_state=0)
23
+ A[:, 1] = 10 / A[:, 1] # pretend column 1: smaller is better
24
+ M = LogAffinePreconditioner(orientation=[1, -1, 1]).fit_transform(A)
25
+ ts = HyperbolicTradeSpace(temperature=20.0).fit(M) # real table: `select_temperature`
26
+ print(trade_off_report(ts, M).exponents.round(2))
27
+ ```
28
+
29
+ ## Layout
30
+
31
+ - `src/tradespace/`: the Python package (fit a frontier, read its trade-offs).
32
+ - `docs/`: the user guide and API reference, built into the docs site.
33
+ - `paper/`: the paper as two notebooks and what rebuilds them; `site/` is the root page that links the docs and the paper.
34
+ - `examples/adcs/`: the cubesat attitude-control case study the paper uses: model, data, experiments, system model.
35
+ - `derivation/`: the proofs of the method's results as SymPy scripts, one per lemma.
36
+ - `tests/`: the test suite; `scripts/`: build and check tools.
37
+ - `claims_register.toml`: each claim the paper and docs make and what backs it.
38
+ - `glossary.yaml`: the terms, one name per object; `history.yaml`: the record behind the history and acknowledgements page.
39
+ - `CHANGELOG.md`: what changed, by work package.
40
+ - `work-packages/`: the build's record; not needed to use the method.
41
+ - `GOVERNANCE.md`: the release rules, the file that declares their settings (`.github/governance.toml`) and the check that runs first in CI.
42
+ - `CLAUDE.md`: conventions for contributors working with Claude Code.
43
+ - `mkdocs.yml`, `Dockerfile`, `pyproject.toml`, `uv.lock`, `.python-version`: build and environment files.
44
+ - `LICENSE`, `.github/` (CI workflows) and the dot-files `.gitattributes`, `.gitignore`, `.dockerignore`: license and repository settings.
@@ -0,0 +1,79 @@
1
+ [project]
2
+ name = "tradespace"
3
+ version = "0.1.0"
4
+ description = "Learns the shape of a design trade space from evaluated designs, with estimators that work in scikit-learn pipelines."
5
+ readme = "README.md"
6
+ authors = [{ name = "Michael Zargham" }]
7
+ requires-python = ">=3.12,<3.13"
8
+ license = "MIT"
9
+ license-files = ["LICENSE"]
10
+ keywords = ["trade space", "posynomial", "geometric programming", "Pareto frontier", "scikit-learn", "systems engineering"]
11
+ classifiers = [
12
+ "Development Status :: 3 - Alpha",
13
+ "Intended Audience :: Science/Research",
14
+ "Intended Audience :: Developers",
15
+ "Operating System :: OS Independent",
16
+ "Programming Language :: Python :: 3",
17
+ "Programming Language :: Python :: 3.12",
18
+ "Topic :: Scientific/Engineering",
19
+ "Topic :: Scientific/Engineering :: Mathematics",
20
+ ]
21
+ dependencies = [
22
+ "numpy>=1.26",
23
+ "scipy>=1.12",
24
+ "sympy>=1.12",
25
+ "scikit-learn>=1.8",
26
+ "pandas>=2.0",
27
+ "matplotlib>=3.8",
28
+ ]
29
+
30
+ [project.urls]
31
+ Homepage = "https://dynamicalsystemsgroup.github.io/tradespace/"
32
+ Documentation = "https://dynamicalsystemsgroup.github.io/tradespace/docs/"
33
+ Repository = "https://github.com/DynamicalSystemsGroup/tradespace"
34
+ Issues = "https://github.com/DynamicalSystemsGroup/tradespace/issues"
35
+ Changelog = "https://github.com/DynamicalSystemsGroup/tradespace/blob/main/CHANGELOG.md"
36
+
37
+ [dependency-groups]
38
+ dev = [
39
+ "pytest>=8",
40
+ "pytest-cov>=5",
41
+ "pytest-xdist>=3.8.0",
42
+ "ruff>=0.6",
43
+ "build>=1.2",
44
+ "twine>=5",
45
+ ]
46
+ docs = ["mkdocs-material>=9.5", "mkdocs-jupyter>=0.24", "mkdocstrings[python]>=0.26", "mkdocs-bibtex>=2.16"]
47
+ notebooks = ["jupyter>=1.0", "nbconvert>=7"]
48
+ paper = ["mystmd>=1.9", "ipykernel>=6", "nbclient>=0.10"]
49
+ case = ["opensysml>=0.12.1", "z3-solver>=4.13"]
50
+
51
+ [tool.uv]
52
+ default-groups = ["dev", "case", "docs", "paper"]
53
+
54
+ [build-system]
55
+ requires = ["hatchling"]
56
+ build-backend = "hatchling.build"
57
+
58
+ [tool.hatch.build.targets.wheel]
59
+ packages = ["src/tradespace"]
60
+
61
+ # The sdist carries the package, the tests, the licence, the readme and the changelog, and nothing else.
62
+ [tool.hatch.build.targets.sdist]
63
+ include = ["/src/tradespace", "/tests", "/LICENSE", "/README.md", "/CHANGELOG.md", "/pyproject.toml"]
64
+
65
+ [tool.pytest.ini_options]
66
+ testpaths = ["tests", "src"]
67
+ addopts = "--doctest-modules"
68
+ doctest_optionflags = "NORMALIZE_WHITESPACE"
69
+ pythonpath = [".", "src", "examples/adcs"]
70
+
71
+ [tool.ruff]
72
+ line-length = 100
73
+ target-version = "py312"
74
+ # Research-spike folders and the views generator hold throwaway-style scripts kept for reproducibility, and the package-user cells' returns are
75
+ # evidence kept verbatim (their code blocks are the cells' own); neither is package code.
76
+ extend-exclude = ["docs/superpowers/notes/spike-horopca", "docs/superpowers/notes/spike-facet-refit", "scripts/sysml_project.py", "work-packages/spikes", "work-packages/WP32-cells/round-*"]
77
+
78
+ [tool.ruff.lint]
79
+ select = ["E", "F", "W", "I", "UP", "B", "SIM", "RUF"]
@@ -0,0 +1,30 @@
1
+ """Hyperbolic trade space: learn the shape of a design trade space (the posynomial invariant form).
2
+
3
+ A scikit-learn estimator that fits a posynomial frontier to a table of conditioned metrics and
4
+ reports which of them trade off and how steeply.
5
+
6
+ Documentation: https://dynamicalsystemsgroup.github.io/tradespace/docs/
7
+ """
8
+
9
+ from .datasets import make_configured_frontier_data, make_frontier_data
10
+ from .estimator import HyperbolicTradeSpace
11
+ from .preconditioning import LogAffinePreconditioner, frontier_in_original_units
12
+ from .predictive import TradeSpaceRegressor
13
+ from .tensions import design_tensions, tension_matrix, trade_off_report
14
+ from .tuning import select_temperature
15
+
16
+ __version__ = "0.1.0"
17
+
18
+ __all__ = [
19
+ "HyperbolicTradeSpace",
20
+ "LogAffinePreconditioner",
21
+ "TradeSpaceRegressor",
22
+ "__version__",
23
+ "design_tensions",
24
+ "frontier_in_original_units",
25
+ "make_configured_frontier_data",
26
+ "make_frontier_data",
27
+ "select_temperature",
28
+ "tension_matrix",
29
+ "trade_off_report",
30
+ ]
@@ -0,0 +1,152 @@
1
+ """Invertible chart of log-metric space: ``log V`` and ``d - 1`` log-ratio coordinates ``Z``.
2
+
3
+ With ``u = log m`` and a basis ``B`` of shape ``(d-1, d)`` whose rows span ``1^perp`` (``B 1 = 0``),
4
+ ``Z = B u`` is blind to the common shift ``u + c 1`` (a shift along the diagonal) and ``log V = w.u
5
+ - beta`` carries the scale. For the ILR (Helmert) basis ``B B^T = I`` (orthonormal rows), so ``u =
6
+ B^T Z + (log V + beta - w.B^T Z) 1``; the ALR basis is invertible but not orthonormal.
7
+ """
8
+
9
+ from __future__ import annotations
10
+
11
+ import numpy as np
12
+
13
+ __all__ = ["alr_basis", "from_frontier_coordinates", "helmert_basis", "to_frontier_coordinates"]
14
+
15
+
16
+ def helmert_basis(d):
17
+ """Helmert (ILR) basis: rows ``(1,..,1,-k,0,..)/sqrt(k(k+1))`` for ``k = 1..d-1``.
18
+
19
+ Parameters
20
+ ----------
21
+ d : int
22
+ Number of metrics, ``d >= 1``.
23
+
24
+ Returns
25
+ -------
26
+ ndarray of shape (d-1, d)
27
+ ``B B^T = I`` and ``B 1 = 0`` (orthonormal rows spanning the zero-sum subspace). For
28
+ ``d = 1`` the shape is ``(0, 1)``.
29
+
30
+ Examples
31
+ --------
32
+ >>> import numpy as np
33
+ >>> B = helmert_basis(3)
34
+ >>> bool(np.allclose(B @ B.T, np.eye(2))), bool(np.allclose(B.sum(axis=1), 0))
35
+ (True, True)
36
+ """
37
+ if d < 1:
38
+ raise ValueError("d must be >= 1")
39
+ B = np.zeros((d - 1, d))
40
+ for k in range(1, d):
41
+ B[k - 1, :k] = 1.0
42
+ B[k - 1, k] = -float(k)
43
+ B[k - 1] /= np.sqrt(k * (k + 1.0))
44
+ return B
45
+
46
+
47
+ def alr_basis(d):
48
+ """Additive log-ratio basis with the last metric as reference: ``Z_j = u_j - u_d``.
49
+
50
+ Parameters
51
+ ----------
52
+ d : int
53
+ Number of metrics, ``d >= 1``.
54
+
55
+ Returns
56
+ -------
57
+ ndarray of shape (d-1, d)
58
+ ``[I | -1]``; ``B 1 = 0`` but ``B B^T != I`` (not orthonormal).
59
+
60
+ Examples
61
+ --------
62
+ >>> alr_basis(3).tolist()
63
+ [[1.0, 0.0, -1.0], [0.0, 1.0, -1.0]]
64
+ """
65
+ if d < 1:
66
+ raise ValueError("d must be >= 1")
67
+ return np.hstack([np.eye(d - 1), -np.ones((d - 1, 1))])
68
+
69
+
70
+ def to_frontier_coordinates(U, w, beta, B):
71
+ """Map log metrics to chart coordinates ``(Z, log V)``.
72
+
73
+ Parameters
74
+ ----------
75
+ U : ndarray of shape (n, d)
76
+ Log metrics; rows with ``-inf`` (zero metrics) give ``Z = nan`` and ``log V = -inf``.
77
+ w : ndarray of shape (d,)
78
+ Exponents on the simplex.
79
+ beta : float
80
+ Offset.
81
+ B : ndarray of shape (d-1, d)
82
+ Chart basis.
83
+
84
+ Returns
85
+ -------
86
+ Z : ndarray of shape (n, d-1)
87
+ ``U @ B.T``.
88
+ log_v : ndarray of shape (n,)
89
+ ``U @ w - beta``.
90
+
91
+ Examples
92
+ --------
93
+ >>> import numpy as np
94
+ >>> U = np.array([[0.0, 1.0], [2.0, 2.0]])
95
+ >>> Z, lv = to_frontier_coordinates(
96
+ ... U, np.array([0.5, 0.5]), 0.5, helmert_basis(2))
97
+ >>> Z.round(4).tolist(), lv.round(4).tolist()
98
+ ([[-0.7071], [0.0]], [0.0, 1.5])
99
+ """
100
+ U = np.atleast_2d(np.asarray(U, dtype=float))
101
+ w = np.asarray(w, dtype=float)
102
+ bad = (-np.inf == U).any(axis=1)
103
+ Uf = np.where(bad[:, None], 0.0, U)
104
+ Z = Uf @ B.T
105
+ log_v = Uf @ w - beta
106
+ Z[bad] = np.nan
107
+ log_v[bad] = -np.inf
108
+ return Z, log_v
109
+
110
+
111
+ def from_frontier_coordinates(Z, log_v, w, beta, B):
112
+ """Inverse of ``to_frontier_coordinates``: ``u = C Z + (log V + beta - w.C Z) 1``.
113
+
114
+ Parameters
115
+ ----------
116
+ Z : ndarray of shape (n, d-1)
117
+ log_v : ndarray of shape (n,)
118
+ w : ndarray of shape (d,)
119
+ Exponents on the simplex (``sum w = 1``).
120
+ beta : float
121
+ B : ndarray of shape (d-1, d)
122
+
123
+ Returns
124
+ -------
125
+ ndarray of shape (n, d)
126
+ Log metrics ``U``. Rows with non-finite ``Z`` or ``log V`` are returned as ``nan``.
127
+
128
+ Notes
129
+ -----
130
+ ``C = pinv(B)`` (``B^T`` for ILR) satisfies ``B C = I``, and ``u - C Z`` lies in
131
+ ``span(1)``; the scale is fixed by ``w.u = log V + beta``.
132
+
133
+ Examples
134
+ --------
135
+ >>> import numpy as np
136
+ >>> B, w = helmert_basis(3), np.array([0.2, 0.3, 0.5])
137
+ >>> U = np.array([[0.1, -0.4, 0.7]])
138
+ >>> Z, lv = to_frontier_coordinates(U, w, 0.2, B)
139
+ >>> bool(np.allclose(from_frontier_coordinates(Z, lv, w, 0.2, B), U))
140
+ True
141
+ """
142
+ Z = np.asarray(Z, dtype=float).reshape(np.size(log_v), np.shape(B)[0])
143
+ log_v = np.atleast_1d(np.asarray(log_v, dtype=float))
144
+ w = np.asarray(w, dtype=float)
145
+ d = w.size
146
+ bad = ~np.isfinite(log_v) | ~np.isfinite(Z).all(axis=1)
147
+ Zf = np.where(bad[:, None], 0.0, Z)
148
+ base = Zf @ np.linalg.pinv(B).T if d > 1 else np.zeros((Z.shape[0], 1))
149
+ shift = np.where(bad, 0.0, log_v) + beta - base @ w
150
+ U = base + shift[:, None]
151
+ U[bad] = np.nan
152
+ return U