astro-emulators-toolkit 0.2.0__tar.gz → 0.2.2__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 (100) hide show
  1. {astro_emulators_toolkit-0.2.0/src/astro_emulators_toolkit.egg-info → astro_emulators_toolkit-0.2.2}/PKG-INFO +135 -3
  2. {astro_emulators_toolkit-0.2.0 → astro_emulators_toolkit-0.2.2}/README.md +134 -2
  3. {astro_emulators_toolkit-0.2.0 → astro_emulators_toolkit-0.2.2}/pyproject.toml +3 -0
  4. astro_emulators_toolkit-0.2.2/src/astro_emulators_toolkit/_version.py +1 -0
  5. {astro_emulators_toolkit-0.2.0 → astro_emulators_toolkit-0.2.2}/src/astro_emulators_toolkit/bundle/__init__.py +12 -0
  6. astro_emulators_toolkit-0.2.2/src/astro_emulators_toolkit/bundle/card.py +523 -0
  7. astro_emulators_toolkit-0.2.2/src/astro_emulators_toolkit/bundle/publish.py +769 -0
  8. {astro_emulators_toolkit-0.2.0 → astro_emulators_toolkit-0.2.2}/src/astro_emulators_toolkit/bundle/versions.py +59 -2
  9. astro_emulators_toolkit-0.2.2/src/astro_emulators_toolkit/cli.py +188 -0
  10. {astro_emulators_toolkit-0.2.0 → astro_emulators_toolkit-0.2.2}/src/astro_emulators_toolkit/config/schema.py +17 -2
  11. {astro_emulators_toolkit-0.2.0 → astro_emulators_toolkit-0.2.2}/src/astro_emulators_toolkit/emulator.py +18 -2
  12. {astro_emulators_toolkit-0.2.0 → astro_emulators_toolkit-0.2.2}/src/astro_emulators_toolkit/experimental/models/__init__.py +20 -3
  13. astro_emulators_toolkit-0.2.2/src/astro_emulators_toolkit/experimental/models/mhe.py +302 -0
  14. astro_emulators_toolkit-0.2.2/src/astro_emulators_toolkit/experimental/models/mhe_config.py +242 -0
  15. astro_emulators_toolkit-0.2.2/src/astro_emulators_toolkit/experimental/models/mhe_layers.py +177 -0
  16. {astro_emulators_toolkit-0.2.0 → astro_emulators_toolkit-0.2.2/src/astro_emulators_toolkit.egg-info}/PKG-INFO +135 -3
  17. {astro_emulators_toolkit-0.2.0 → astro_emulators_toolkit-0.2.2}/src/astro_emulators_toolkit.egg-info/SOURCES.txt +7 -0
  18. astro_emulators_toolkit-0.2.2/src/astro_emulators_toolkit.egg-info/entry_points.txt +2 -0
  19. astro_emulators_toolkit-0.2.0/src/astro_emulators_toolkit/_version.py +0 -1
  20. {astro_emulators_toolkit-0.2.0 → astro_emulators_toolkit-0.2.2}/LICENSE +0 -0
  21. {astro_emulators_toolkit-0.2.0 → astro_emulators_toolkit-0.2.2}/setup.cfg +0 -0
  22. {astro_emulators_toolkit-0.2.0 → astro_emulators_toolkit-0.2.2}/src/astro_emulators_toolkit/__init__.py +0 -0
  23. {astro_emulators_toolkit-0.2.0 → astro_emulators_toolkit-0.2.2}/src/astro_emulators_toolkit/_typing.py +0 -0
  24. {astro_emulators_toolkit-0.2.0 → astro_emulators_toolkit-0.2.2}/src/astro_emulators_toolkit/_vendor/__init__.py +0 -0
  25. {astro_emulators_toolkit-0.2.0 → astro_emulators_toolkit-0.2.2}/src/astro_emulators_toolkit/_vendor/get_soap_jax.py +0 -0
  26. {astro_emulators_toolkit-0.2.0 → astro_emulators_toolkit-0.2.2}/src/astro_emulators_toolkit/_vendor/soap_jax/LICENSE +0 -0
  27. {astro_emulators_toolkit-0.2.0 → astro_emulators_toolkit-0.2.2}/src/astro_emulators_toolkit/_vendor/soap_jax/README.txt +0 -0
  28. {astro_emulators_toolkit-0.2.0 → astro_emulators_toolkit-0.2.2}/src/astro_emulators_toolkit/_vendor/soap_jax/__init__.py +0 -0
  29. {astro_emulators_toolkit-0.2.0 → astro_emulators_toolkit-0.2.2}/src/astro_emulators_toolkit/_vendor/soap_jax/soap.py +0 -0
  30. {astro_emulators_toolkit-0.2.0 → astro_emulators_toolkit-0.2.2}/src/astro_emulators_toolkit/bundle/artifact.py +0 -0
  31. {astro_emulators_toolkit-0.2.0 → astro_emulators_toolkit-0.2.2}/src/astro_emulators_toolkit/bundle/bundle.py +0 -0
  32. {astro_emulators_toolkit-0.2.0 → astro_emulators_toolkit-0.2.2}/src/astro_emulators_toolkit/bundle/extras.py +0 -0
  33. {astro_emulators_toolkit-0.2.0 → astro_emulators_toolkit-0.2.2}/src/astro_emulators_toolkit/bundle/hub.py +0 -0
  34. {astro_emulators_toolkit-0.2.0 → astro_emulators_toolkit-0.2.2}/src/astro_emulators_toolkit/bundle/integrity.py +0 -0
  35. {astro_emulators_toolkit-0.2.0 → astro_emulators_toolkit-0.2.2}/src/astro_emulators_toolkit/bundle/loaded_state.py +0 -0
  36. {astro_emulators_toolkit-0.2.0 → astro_emulators_toolkit-0.2.2}/src/astro_emulators_toolkit/bundle/metadata.py +0 -0
  37. {astro_emulators_toolkit-0.2.0 → astro_emulators_toolkit-0.2.2}/src/astro_emulators_toolkit/bundle/minmax_sidecars.py +0 -0
  38. {astro_emulators_toolkit-0.2.0 → astro_emulators_toolkit-0.2.2}/src/astro_emulators_toolkit/bundle/provenance.py +0 -0
  39. {astro_emulators_toolkit-0.2.0 → astro_emulators_toolkit-0.2.2}/src/astro_emulators_toolkit/bundle/readme.py +0 -0
  40. {astro_emulators_toolkit-0.2.0 → astro_emulators_toolkit-0.2.2}/src/astro_emulators_toolkit/bundle/release.py +0 -0
  41. {astro_emulators_toolkit-0.2.0 → astro_emulators_toolkit-0.2.2}/src/astro_emulators_toolkit/bundle/safetensors_io.py +0 -0
  42. {astro_emulators_toolkit-0.2.0 → astro_emulators_toolkit-0.2.2}/src/astro_emulators_toolkit/config/__init__.py +0 -0
  43. {astro_emulators_toolkit-0.2.0 → astro_emulators_toolkit-0.2.2}/src/astro_emulators_toolkit/config/io.py +0 -0
  44. {astro_emulators_toolkit-0.2.0 → astro_emulators_toolkit-0.2.2}/src/astro_emulators_toolkit/config/migrations.py +0 -0
  45. {astro_emulators_toolkit-0.2.0 → astro_emulators_toolkit-0.2.2}/src/astro_emulators_toolkit/config/parsing.py +0 -0
  46. {astro_emulators_toolkit-0.2.0 → astro_emulators_toolkit-0.2.2}/src/astro_emulators_toolkit/data/__init__.py +0 -0
  47. {astro_emulators_toolkit-0.2.0 → astro_emulators_toolkit-0.2.2}/src/astro_emulators_toolkit/data/array_dataset.py +0 -0
  48. {astro_emulators_toolkit-0.2.0 → astro_emulators_toolkit-0.2.2}/src/astro_emulators_toolkit/data/loader.py +0 -0
  49. {astro_emulators_toolkit-0.2.0 → astro_emulators_toolkit-0.2.2}/src/astro_emulators_toolkit/data/mapped_dataset.py +0 -0
  50. {astro_emulators_toolkit-0.2.0 → astro_emulators_toolkit-0.2.2}/src/astro_emulators_toolkit/data/npy_table.py +0 -0
  51. {astro_emulators_toolkit-0.2.0 → astro_emulators_toolkit-0.2.2}/src/astro_emulators_toolkit/data/preprocess.py +0 -0
  52. {astro_emulators_toolkit-0.2.0 → astro_emulators_toolkit-0.2.2}/src/astro_emulators_toolkit/data/protocols.py +0 -0
  53. {astro_emulators_toolkit-0.2.0 → astro_emulators_toolkit-0.2.2}/src/astro_emulators_toolkit/data/subset.py +0 -0
  54. {astro_emulators_toolkit-0.2.0 → astro_emulators_toolkit-0.2.2}/src/astro_emulators_toolkit/data/toy.py +0 -0
  55. {astro_emulators_toolkit-0.2.0 → astro_emulators_toolkit-0.2.2}/src/astro_emulators_toolkit/data/toy_utils.py +0 -0
  56. {astro_emulators_toolkit-0.2.0 → astro_emulators_toolkit-0.2.2}/src/astro_emulators_toolkit/emulator_runtime.py +0 -0
  57. {astro_emulators_toolkit-0.2.0 → astro_emulators_toolkit-0.2.2}/src/astro_emulators_toolkit/experimental/__init__.py +0 -0
  58. {astro_emulators_toolkit-0.2.0 → astro_emulators_toolkit-0.2.2}/src/astro_emulators_toolkit/experimental/models/explicit_wavelength_mlp.py +0 -0
  59. {astro_emulators_toolkit-0.2.0 → astro_emulators_toolkit-0.2.2}/src/astro_emulators_toolkit/experimental/models/mlp_2d_regression.py +0 -0
  60. {astro_emulators_toolkit-0.2.0 → astro_emulators_toolkit-0.2.2}/src/astro_emulators_toolkit/experimental/models/siren.py +0 -0
  61. {astro_emulators_toolkit-0.2.0 → astro_emulators_toolkit-0.2.2}/src/astro_emulators_toolkit/experimental/runtime_adapters.py +0 -0
  62. {astro_emulators_toolkit-0.2.0 → astro_emulators_toolkit-0.2.2}/src/astro_emulators_toolkit/experimental/tasks/__init__.py +0 -0
  63. {astro_emulators_toolkit-0.2.0 → astro_emulators_toolkit-0.2.2}/src/astro_emulators_toolkit/experimental/tasks/classification.py +0 -0
  64. {astro_emulators_toolkit-0.2.0 → astro_emulators_toolkit-0.2.2}/src/astro_emulators_toolkit/inference/__init__.py +0 -0
  65. {astro_emulators_toolkit-0.2.0 → astro_emulators_toolkit-0.2.2}/src/astro_emulators_toolkit/inference/compose.py +0 -0
  66. {astro_emulators_toolkit-0.2.0 → astro_emulators_toolkit-0.2.2}/src/astro_emulators_toolkit/io_trees.py +0 -0
  67. {astro_emulators_toolkit-0.2.0 → astro_emulators_toolkit-0.2.2}/src/astro_emulators_toolkit/models/__init__.py +0 -0
  68. {astro_emulators_toolkit-0.2.0 → astro_emulators_toolkit-0.2.2}/src/astro_emulators_toolkit/models/activations.py +0 -0
  69. {astro_emulators_toolkit-0.2.0 → astro_emulators_toolkit-0.2.2}/src/astro_emulators_toolkit/models/cannon.py +0 -0
  70. {astro_emulators_toolkit-0.2.0 → astro_emulators_toolkit-0.2.2}/src/astro_emulators_toolkit/models/canonical_wrappers.py +0 -0
  71. {astro_emulators_toolkit-0.2.0 → astro_emulators_toolkit-0.2.2}/src/astro_emulators_toolkit/models/dtypes.py +0 -0
  72. {astro_emulators_toolkit-0.2.0 → astro_emulators_toolkit-0.2.2}/src/astro_emulators_toolkit/models/mlp.py +0 -0
  73. {astro_emulators_toolkit-0.2.0 → astro_emulators_toolkit-0.2.2}/src/astro_emulators_toolkit/models/runtime_adapters.py +0 -0
  74. {astro_emulators_toolkit-0.2.0 → astro_emulators_toolkit-0.2.2}/src/astro_emulators_toolkit/models/transformer_payne.py +0 -0
  75. {astro_emulators_toolkit-0.2.0 → astro_emulators_toolkit-0.2.2}/src/astro_emulators_toolkit/models/transformer_payne_batch.py +0 -0
  76. {astro_emulators_toolkit-0.2.0 → astro_emulators_toolkit-0.2.2}/src/astro_emulators_toolkit/optimizers/__init__.py +0 -0
  77. {astro_emulators_toolkit-0.2.0 → astro_emulators_toolkit-0.2.2}/src/astro_emulators_toolkit/optimizers/_soap.py +0 -0
  78. {astro_emulators_toolkit-0.2.0 → astro_emulators_toolkit-0.2.2}/src/astro_emulators_toolkit/presets/__init__.py +0 -0
  79. {astro_emulators_toolkit-0.2.0 → astro_emulators_toolkit-0.2.2}/src/astro_emulators_toolkit/presets/cannon.py +0 -0
  80. {astro_emulators_toolkit-0.2.0 → astro_emulators_toolkit-0.2.2}/src/astro_emulators_toolkit/presets/mlp.py +0 -0
  81. {astro_emulators_toolkit-0.2.0 → astro_emulators_toolkit-0.2.2}/src/astro_emulators_toolkit/presets/transformer_payne.py +0 -0
  82. {astro_emulators_toolkit-0.2.0 → astro_emulators_toolkit-0.2.2}/src/astro_emulators_toolkit/py.typed +0 -0
  83. {astro_emulators_toolkit-0.2.0 → astro_emulators_toolkit-0.2.2}/src/astro_emulators_toolkit/resolver.py +0 -0
  84. {astro_emulators_toolkit-0.2.0 → astro_emulators_toolkit-0.2.2}/src/astro_emulators_toolkit/spec.py +0 -0
  85. {astro_emulators_toolkit-0.2.0 → astro_emulators_toolkit-0.2.2}/src/astro_emulators_toolkit/tasks/__init__.py +0 -0
  86. {astro_emulators_toolkit-0.2.0 → astro_emulators_toolkit-0.2.2}/src/astro_emulators_toolkit/tasks/common.py +0 -0
  87. {astro_emulators_toolkit-0.2.0 → astro_emulators_toolkit-0.2.2}/src/astro_emulators_toolkit/tasks/regression.py +0 -0
  88. {astro_emulators_toolkit-0.2.0 → astro_emulators_toolkit-0.2.2}/src/astro_emulators_toolkit/training/__init__.py +0 -0
  89. {astro_emulators_toolkit-0.2.0 → astro_emulators_toolkit-0.2.2}/src/astro_emulators_toolkit/training/callbacks.py +0 -0
  90. {astro_emulators_toolkit-0.2.0 → astro_emulators_toolkit-0.2.2}/src/astro_emulators_toolkit/training/checkpoint.py +0 -0
  91. {astro_emulators_toolkit-0.2.0 → astro_emulators_toolkit-0.2.2}/src/astro_emulators_toolkit/training/fit_backends.py +0 -0
  92. {astro_emulators_toolkit-0.2.0 → astro_emulators_toolkit-0.2.2}/src/astro_emulators_toolkit/training/paths.py +0 -0
  93. {astro_emulators_toolkit-0.2.0 → astro_emulators_toolkit-0.2.2}/src/astro_emulators_toolkit/training/solvers.py +0 -0
  94. {astro_emulators_toolkit-0.2.0 → astro_emulators_toolkit-0.2.2}/src/astro_emulators_toolkit/training/state.py +0 -0
  95. {astro_emulators_toolkit-0.2.0 → astro_emulators_toolkit-0.2.2}/src/astro_emulators_toolkit/training/trainer.py +0 -0
  96. {astro_emulators_toolkit-0.2.0 → astro_emulators_toolkit-0.2.2}/src/astro_emulators_toolkit/utils/__init__.py +0 -0
  97. {astro_emulators_toolkit-0.2.0 → astro_emulators_toolkit-0.2.2}/src/astro_emulators_toolkit/utils/tree.py +0 -0
  98. {astro_emulators_toolkit-0.2.0 → astro_emulators_toolkit-0.2.2}/src/astro_emulators_toolkit.egg-info/dependency_links.txt +0 -0
  99. {astro_emulators_toolkit-0.2.0 → astro_emulators_toolkit-0.2.2}/src/astro_emulators_toolkit.egg-info/requires.txt +0 -0
  100. {astro_emulators_toolkit-0.2.0 → astro_emulators_toolkit-0.2.2}/src/astro_emulators_toolkit.egg-info/top_level.txt +0 -0
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.4
2
2
  Name: astro-emulators-toolkit
3
- Version: 0.2.0
3
+ Version: 0.2.2
4
4
  Summary: General-purpose astrophysical emulators: spectra, isochrones, and more.
5
5
  Author: Tomasz Rozanski
6
6
  License-Expression: MIT
@@ -104,6 +104,7 @@ If you are training your own emulator, start with:
104
104
  3. [Training a new emulator](#training-a-new-emulator)
105
105
  4. [Recording the scientific contract of the emulator](#recording-the-scientific-contract-of-the-emulator)
106
106
  5. [Preparing a release bundle for collaborators](#preparing-a-release-bundle-for-collaborators)
107
+ 6. [Publishing a bundle on the Hugging Face Hub](#publishing-a-bundle-on-the-hugging-face-hub)
107
108
 
108
109
  If you are extending the library, also read:
109
110
 
@@ -142,7 +143,7 @@ uv add "astro-emulators-toolkit[viz]"
142
143
 
143
144
  Base installation already includes local bundle loading, Hugging Face bundle download, training, bundle export, safetensors serialization, JSON/YAML config I/O, and the stable model/task/runtime surface.
144
145
 
145
- Hugging Face support in the stable public API is **download-only** through `Emulator.from_pretrained(...)`.
146
+ On the Hugging Face Hub, `Emulator` itself only downloads (`Emulator.from_pretrained(...)`). Publishing a bundle is a separate, explicit step with the `aemu` command installed with the package; see [Publishing a bundle on the Hugging Face Hub](#publishing-a-bundle-on-the-hugging-face-hub).
146
147
 
147
148
  ## Main public components
148
149
 
@@ -237,6 +238,13 @@ Release-oriented helpers for shared artifacts:
237
238
  - `verify_bundle_fingerprint_evaluation(...)`
238
239
  - `load_bundle_fingerprint_evaluation(...)`
239
240
 
241
+ and for publishing a released bundle on the Hugging Face Hub (also available as the `aemu` command):
242
+
243
+ - `write_model_card(...)`
244
+ - `check_bundle_for_publishing(...)`
245
+ - `plan_bundle_upload(...)`
246
+ - `publish_bundle(...)`
247
+
240
248
  ## Load a shared bundle and predict
241
249
 
242
250
  The first supported user workflow is: load a bundle, apply explicit preprocessing if required, and call `predict(...)`.
@@ -681,6 +689,58 @@ These are not the same thing.
681
689
 
682
690
  A release fingerprint is a useful reproducibility smoke test. It is not a substitute for physical validation.
683
691
 
692
+ ## Publishing a bundle on the Hugging Face Hub
693
+
694
+ A released bundle directory can be published as a Hub model repository with the `aemu` command, which is installed with the package. Each subcommand wraps a function in `astro_emulators_toolkit.bundle`, so the same steps can be scripted from Python.
695
+
696
+ ```bash
697
+ aemu card dist/my_flux_bundle_released # create README.md (the model card)
698
+ # ...write your sections in README.md...
699
+ aemu check dist/my_flux_bundle_released # the pre-publish checklist
700
+ aemu publish dist/my_flux_bundle_released my-org/my-flux-emulator --dry-run
701
+ aemu publish dist/my_flux_bundle_released my-org/my-flux-emulator
702
+ ```
703
+
704
+ `aemu publish` refreshes the generated part of the card, uploads the directory in one commit, tags it `v<release_version>`, and then downloads it back to check that it loads, has the same `bundle_id`, and reproduces its fingerprint. It authenticates with your Hugging Face login (`hf auth login`) or `HF_TOKEN`. The token needs write access: a `Write` token, or a fine-grained token with write permission on the target repository (to create a new repository, on your whole namespace or organization); `aemu publish` checks this before changing anything, and `--dry-run` reports it too. Also, `--private` creates a private repository, which `from_pretrained(...)` reads with the same login. `aemu` enables `JAX_ENABLE_X64` itself, which TransformerPayne bundles need.
705
+
706
+ ### What belongs in the directory
707
+
708
+ - **Bundle contract**: the files listed in `bundle_integrity.json` plus the manifest itself (`config.json`, `metadata.json`, `README.txt`, `weights/`, and the sidecars the metadata refers to). They are verified on every load; do not edit them after `prepare_bundle_release(...)`.
709
+ - **Documentation**: anything else you add, such as the `README.md` model card, `LICENSE`, `CITATION.cff`, or a `docs/` folder with figures and validation notes. Loading ignores these files, so you can document as much as you like. Keep them out of the contract folders (`weights/`, `extras/`, `fingerprint_evaluation/`); `aemu check` refuses files there.
710
+ - **Not uploaded**: hidden files, `__pycache__`, and training state (`checkpoints/`, `checkpoints_best/`, `runs/`). Internal run state is not the sharing contract.
711
+
712
+ ### The model card
713
+
714
+ The Hub shows `README.md` as the model card. `aemu card` writes a default one with three parts:
715
+
716
+ 1. YAML front matter with `library_name: astro-emulators-toolkit`, which lists the model under this library on the Hub. Add `license:` and, if the training set is on the Hub, `datasets:`.
717
+ 2. Your sections: an introduction, intended use and domain, training data, model and training, validation, known limitations, citation and contact. Each starts as an `<!-- aemu:todo ... -->` prompt to replace with your own text.
718
+ 3. A generated block between `<!-- aemu:generated:begin -->` and `<!-- aemu:generated:end -->`, built from the bundle metadata: the input/output table (names, meanings, units, intended domain), a usage snippet with the pinned revision, the requirements (the oldest toolkit version that loads the bundle, and `JAX_ENABLE_X64` where needed), release and provenance, and the contract files. `aemu card` and `aemu publish` rebuild only this block; your text is never touched.
719
+
720
+ The generated table is only as good as the recorded metadata: set channel names, meanings and units in `io` and record an `input_domain` before saving the bundle.
721
+
722
+ ### Before you publish
723
+
724
+ `aemu check` runs this checklist; errors block publishing, warnings do not.
725
+
726
+ - **Errors**: the bundle does not load or fails its integrity check; it has no release identity or fingerprint (run `prepare_bundle_release(...)`); the fingerprint does not reproduce (`--allow-fingerprint-mismatch` accepts that, for example for a fingerprint recorded on another platform); documentation files sit inside contract folders; `README.md` is missing, lacks `library_name`, or still has `aemu:todo` prompts.
727
+ - **Warnings**: an input or output leaf without names, meanings or units; no `input_domain`; no `license:`; files that will not be uploaded.
728
+
729
+ These are portability and documentation checks. The scientific validation you write in the card (held-out errors, residual structure, behavior at the domain edges, comparison with the expensive model) is yours to provide; a fingerprint that reproduces is not evidence of physical accuracy.
730
+
731
+ ### Versions on the Hub
732
+
733
+ - Each release is one commit on `main` plus the tag `v<release_version>`, using the version given to `prepare_bundle_release(...)`. Users pin a release with `Emulator.from_pretrained("my-org/my-flux-emulator", revision="v1.2.0")`; without `revision` they get the latest `main`.
734
+ - Tags are not moved: publishing an existing tag is refused unless you pass `--overwrite-tag` deliberately (for example to fix a broken release before anyone used it).
735
+ - A release older than the latest tagged one is refused, since `main` would move backwards.
736
+ - A change of the interface since the latest release (input/output structure, channel names, units) needs a new major version, for example `2.0.0` after `1.4.0`; `--allow-interface-change` overrides this.
737
+ - `--no-tag` publishes a documentation-only update to `main` (a better card, a new figure). It is refused if any contract file differs from what `main` already has.
738
+ - By default files you deleted locally stay on the Hub (and are listed); `--mirror` deletes them too.
739
+
740
+ ### Downloading and the cache
741
+
742
+ `Emulator.from_pretrained(...)` downloads into the toolkit's own cache, `~/.cache/astro_emulators_toolkit/hub` (or `$ASTRO_EMU_CACHE_DIR/hub`, or `$XDG_CACHE_HOME/astro_emulators_toolkit/hub`), unless you pass `cache_dir=...`. The loaded emulator records where it came from in `emu.bundle_metadata["hub_source"]`: the repository, the requested revision, and the resolved commit.
743
+
684
744
  ## API reference: the `Emulator` surface
685
745
 
686
746
  ### Construction
@@ -726,7 +786,7 @@ Use `from_config(...)` when building a new emulator. Use `from_bundle(...)` or `
726
786
  - `training`: workdir, batch size, step schedule, logging/evaluation cadence, and other run controls;
727
787
  - `io`: canonical input/output structure plus optional metadata, scaling, and domain;
728
788
  - `bundle`: bundle-export options;
729
- - `hub`: Hugging Face bundle source metadata.
789
+ - `hub`: deprecated and ignored (removed in 0.3.0); pass `repo_id`/`revision` to `from_pretrained(...)` or `aemu publish` instead.
730
790
 
731
791
  A good default pattern is to start from a preset and then update the pieces
732
792
  you need with `with_updates(...)`. A section can be given as a dict of field
@@ -773,6 +833,78 @@ cfg = load_config("runs/demo/config.yaml")
773
833
 
774
834
  Prototype model families and tasks live under `experimental/...`. They are useful for research and development but are intentionally outside the stable public contract.
775
835
 
836
+ The wavelength-explicit MHE (multiresolution hash encoding) families are:
837
+
838
+ - `experimental/mhe_mlp`: a shared parameter MLP followed by a wavelength
839
+ decoder that receives learned hash features at every hidden layer.
840
+ - `experimental/mhe_transformer_payne`: parameter tokens and cross-attention,
841
+ with a learned hash encoding and projection for wavelength queries.
842
+
843
+ Both reuse the `transformer_payne` runtime adapter: the same canonical input/output
844
+ keys, channel metadata, custom nested leaf names, flux/intensity device batch
845
+ transforms, `fit`, `predict`, JAX composition, and portable bundle APIs. Parameters
846
+ have shape `(batch, parameter_dim)` and public wavelengths have shape
847
+ `(batch, n_wavelength)`. Outputs have shape `(batch, n_wavelength)` for one channel,
848
+ or `(batch, n_wavelength, channels)` otherwise. Initialize from an example batch
849
+ or `init_hints={"parameter_dim": ...}`.
850
+
851
+ Start from the existing flux or intensity preset and replace the model spec:
852
+
853
+ ```python
854
+ from dataclasses import replace
855
+ from astro_emulators_toolkit import Emulator
856
+ from astro_emulators_toolkit.presets import transformer_payne_flux
857
+
858
+ cfg = transformer_payne_flux(profile="smoke")
859
+ cfg = replace(cfg, model=replace(
860
+ cfg.model,
861
+ name="experimental/mhe_transformer_payne",
862
+ params={**cfg.model.params,
863
+ "mhe": {"levels": 8, "log2_hashmap_size": 12,
864
+ "wavelength_range": [0.0, 1.0]}},
865
+ ))
866
+ emu = Emulator.from_config(cfg)
867
+ # Use explicitly preprocessed data and emu.make_device_batch_transform(...)
868
+ # with emu.fit(...), just as for transformer_payne.
869
+ ```
870
+
871
+ For `experimental/mhe_mlp`, replace the model name and parameter dictionary with,
872
+ for example, `{"hidden_sizes": [128, 128, 128], "parameter_hidden_sizes": [128, 128],
873
+ "min_period": 1e-4, "max_period": 2.0, "mhe": {"wavelength_range": [0.0, 1.0]}}`.
874
+ The transformer uses the usual `dim`, `dim_head`, `no_tokens`, `no_layers`, and
875
+ `dim_ff_multiplier`, plus optional `parameter_hidden_dim`, per-block
876
+ `ff_hidden_sizes`, and `head_hidden_dim`. Architecture parameters and the stable
877
+ models' optional `si`/`mup`/`mup_depth` LR policies are not interchangeable: use
878
+ `lr_scaling=None` or an explicit Optax optimizer for the MHE families.
879
+
880
+ MHE preprocessing is explicit. `mhe.wavelength_range` (default `[0, 1]`),
881
+ `min_period`, and `max_period` are in the wavelength coordinates actually supplied
882
+ to the model, whether physical, normalized, or logarithmic. Neither model takes a
883
+ logarithm or applies reference scaling automatically. Record transforms, units,
884
+ scaling, and intended-use bounds in the usual I/O metadata. Enable
885
+ `JAX_ENABLE_X64=1` and preserve float64 wavelengths even with float32 weights.
886
+
887
+ The nested `mhe` configuration also accepts `levels`, `features_per_level`,
888
+ `log2_hashmap_size`, and `table_init_scale`. Each level linearly interpolates
889
+ learned features with cell widths geometrically spaced from `max_period / 2` to
890
+ `min_period / 2`. Power-of-two tables are capped at `2 ** log2_hashmap_size`, with
891
+ wrapped indices. The range sets the grid origin and allocation; it does not clip
892
+ queries or define a safe extrapolation policy. Wavelength derivatives are
893
+ piecewise defined at grid boundaries. The transformer also supports
894
+ `projection_hidden_dim`, `projection_activation`, `projection_bias`, and optional
895
+ `normalize_output` inside `mhe`; normalization acts on encoded features, not
896
+ physical spectra, and defaults to off.
897
+
898
+ These families require toolkit 0.2.2 or newer, including when loading their bundles.
899
+ They train entirely within aemu without the original development project
900
+ or pretrained weights. Implementation comparisons and bundle round trips establish
901
+ numerical parity and portability; held-out residuals, boundaries, and realistic
902
+ inference tests remain separate scientific validation work.
903
+
904
+ Run [the MHE flux example](examples/experimental/08_train_mhe_flux.py) with
905
+ `--model mhe_mlp` or `--model mhe_transformer_payne` for a complete native workflow
906
+ with explicit input normalization and bundle export.
907
+
776
908
  ### Transformer-specific notes
777
909
 
778
910
  The `transformer_payne` family **requires** `JAX_ENABLE_X64=1`: wavelengths are always handled in float64 up to the embedding cast, and model construction fails without it. Enable it before building or loading these models:
@@ -65,6 +65,7 @@ If you are training your own emulator, start with:
65
65
  3. [Training a new emulator](#training-a-new-emulator)
66
66
  4. [Recording the scientific contract of the emulator](#recording-the-scientific-contract-of-the-emulator)
67
67
  5. [Preparing a release bundle for collaborators](#preparing-a-release-bundle-for-collaborators)
68
+ 6. [Publishing a bundle on the Hugging Face Hub](#publishing-a-bundle-on-the-hugging-face-hub)
68
69
 
69
70
  If you are extending the library, also read:
70
71
 
@@ -103,7 +104,7 @@ uv add "astro-emulators-toolkit[viz]"
103
104
 
104
105
  Base installation already includes local bundle loading, Hugging Face bundle download, training, bundle export, safetensors serialization, JSON/YAML config I/O, and the stable model/task/runtime surface.
105
106
 
106
- Hugging Face support in the stable public API is **download-only** through `Emulator.from_pretrained(...)`.
107
+ On the Hugging Face Hub, `Emulator` itself only downloads (`Emulator.from_pretrained(...)`). Publishing a bundle is a separate, explicit step with the `aemu` command installed with the package; see [Publishing a bundle on the Hugging Face Hub](#publishing-a-bundle-on-the-hugging-face-hub).
107
108
 
108
109
  ## Main public components
109
110
 
@@ -198,6 +199,13 @@ Release-oriented helpers for shared artifacts:
198
199
  - `verify_bundle_fingerprint_evaluation(...)`
199
200
  - `load_bundle_fingerprint_evaluation(...)`
200
201
 
202
+ and for publishing a released bundle on the Hugging Face Hub (also available as the `aemu` command):
203
+
204
+ - `write_model_card(...)`
205
+ - `check_bundle_for_publishing(...)`
206
+ - `plan_bundle_upload(...)`
207
+ - `publish_bundle(...)`
208
+
201
209
  ## Load a shared bundle and predict
202
210
 
203
211
  The first supported user workflow is: load a bundle, apply explicit preprocessing if required, and call `predict(...)`.
@@ -642,6 +650,58 @@ These are not the same thing.
642
650
 
643
651
  A release fingerprint is a useful reproducibility smoke test. It is not a substitute for physical validation.
644
652
 
653
+ ## Publishing a bundle on the Hugging Face Hub
654
+
655
+ A released bundle directory can be published as a Hub model repository with the `aemu` command, which is installed with the package. Each subcommand wraps a function in `astro_emulators_toolkit.bundle`, so the same steps can be scripted from Python.
656
+
657
+ ```bash
658
+ aemu card dist/my_flux_bundle_released # create README.md (the model card)
659
+ # ...write your sections in README.md...
660
+ aemu check dist/my_flux_bundle_released # the pre-publish checklist
661
+ aemu publish dist/my_flux_bundle_released my-org/my-flux-emulator --dry-run
662
+ aemu publish dist/my_flux_bundle_released my-org/my-flux-emulator
663
+ ```
664
+
665
+ `aemu publish` refreshes the generated part of the card, uploads the directory in one commit, tags it `v<release_version>`, and then downloads it back to check that it loads, has the same `bundle_id`, and reproduces its fingerprint. It authenticates with your Hugging Face login (`hf auth login`) or `HF_TOKEN`. The token needs write access: a `Write` token, or a fine-grained token with write permission on the target repository (to create a new repository, on your whole namespace or organization); `aemu publish` checks this before changing anything, and `--dry-run` reports it too. Also, `--private` creates a private repository, which `from_pretrained(...)` reads with the same login. `aemu` enables `JAX_ENABLE_X64` itself, which TransformerPayne bundles need.
666
+
667
+ ### What belongs in the directory
668
+
669
+ - **Bundle contract**: the files listed in `bundle_integrity.json` plus the manifest itself (`config.json`, `metadata.json`, `README.txt`, `weights/`, and the sidecars the metadata refers to). They are verified on every load; do not edit them after `prepare_bundle_release(...)`.
670
+ - **Documentation**: anything else you add, such as the `README.md` model card, `LICENSE`, `CITATION.cff`, or a `docs/` folder with figures and validation notes. Loading ignores these files, so you can document as much as you like. Keep them out of the contract folders (`weights/`, `extras/`, `fingerprint_evaluation/`); `aemu check` refuses files there.
671
+ - **Not uploaded**: hidden files, `__pycache__`, and training state (`checkpoints/`, `checkpoints_best/`, `runs/`). Internal run state is not the sharing contract.
672
+
673
+ ### The model card
674
+
675
+ The Hub shows `README.md` as the model card. `aemu card` writes a default one with three parts:
676
+
677
+ 1. YAML front matter with `library_name: astro-emulators-toolkit`, which lists the model under this library on the Hub. Add `license:` and, if the training set is on the Hub, `datasets:`.
678
+ 2. Your sections: an introduction, intended use and domain, training data, model and training, validation, known limitations, citation and contact. Each starts as an `<!-- aemu:todo ... -->` prompt to replace with your own text.
679
+ 3. A generated block between `<!-- aemu:generated:begin -->` and `<!-- aemu:generated:end -->`, built from the bundle metadata: the input/output table (names, meanings, units, intended domain), a usage snippet with the pinned revision, the requirements (the oldest toolkit version that loads the bundle, and `JAX_ENABLE_X64` where needed), release and provenance, and the contract files. `aemu card` and `aemu publish` rebuild only this block; your text is never touched.
680
+
681
+ The generated table is only as good as the recorded metadata: set channel names, meanings and units in `io` and record an `input_domain` before saving the bundle.
682
+
683
+ ### Before you publish
684
+
685
+ `aemu check` runs this checklist; errors block publishing, warnings do not.
686
+
687
+ - **Errors**: the bundle does not load or fails its integrity check; it has no release identity or fingerprint (run `prepare_bundle_release(...)`); the fingerprint does not reproduce (`--allow-fingerprint-mismatch` accepts that, for example for a fingerprint recorded on another platform); documentation files sit inside contract folders; `README.md` is missing, lacks `library_name`, or still has `aemu:todo` prompts.
688
+ - **Warnings**: an input or output leaf without names, meanings or units; no `input_domain`; no `license:`; files that will not be uploaded.
689
+
690
+ These are portability and documentation checks. The scientific validation you write in the card (held-out errors, residual structure, behavior at the domain edges, comparison with the expensive model) is yours to provide; a fingerprint that reproduces is not evidence of physical accuracy.
691
+
692
+ ### Versions on the Hub
693
+
694
+ - Each release is one commit on `main` plus the tag `v<release_version>`, using the version given to `prepare_bundle_release(...)`. Users pin a release with `Emulator.from_pretrained("my-org/my-flux-emulator", revision="v1.2.0")`; without `revision` they get the latest `main`.
695
+ - Tags are not moved: publishing an existing tag is refused unless you pass `--overwrite-tag` deliberately (for example to fix a broken release before anyone used it).
696
+ - A release older than the latest tagged one is refused, since `main` would move backwards.
697
+ - A change of the interface since the latest release (input/output structure, channel names, units) needs a new major version, for example `2.0.0` after `1.4.0`; `--allow-interface-change` overrides this.
698
+ - `--no-tag` publishes a documentation-only update to `main` (a better card, a new figure). It is refused if any contract file differs from what `main` already has.
699
+ - By default files you deleted locally stay on the Hub (and are listed); `--mirror` deletes them too.
700
+
701
+ ### Downloading and the cache
702
+
703
+ `Emulator.from_pretrained(...)` downloads into the toolkit's own cache, `~/.cache/astro_emulators_toolkit/hub` (or `$ASTRO_EMU_CACHE_DIR/hub`, or `$XDG_CACHE_HOME/astro_emulators_toolkit/hub`), unless you pass `cache_dir=...`. The loaded emulator records where it came from in `emu.bundle_metadata["hub_source"]`: the repository, the requested revision, and the resolved commit.
704
+
645
705
  ## API reference: the `Emulator` surface
646
706
 
647
707
  ### Construction
@@ -687,7 +747,7 @@ Use `from_config(...)` when building a new emulator. Use `from_bundle(...)` or `
687
747
  - `training`: workdir, batch size, step schedule, logging/evaluation cadence, and other run controls;
688
748
  - `io`: canonical input/output structure plus optional metadata, scaling, and domain;
689
749
  - `bundle`: bundle-export options;
690
- - `hub`: Hugging Face bundle source metadata.
750
+ - `hub`: deprecated and ignored (removed in 0.3.0); pass `repo_id`/`revision` to `from_pretrained(...)` or `aemu publish` instead.
691
751
 
692
752
  A good default pattern is to start from a preset and then update the pieces
693
753
  you need with `with_updates(...)`. A section can be given as a dict of field
@@ -734,6 +794,78 @@ cfg = load_config("runs/demo/config.yaml")
734
794
 
735
795
  Prototype model families and tasks live under `experimental/...`. They are useful for research and development but are intentionally outside the stable public contract.
736
796
 
797
+ The wavelength-explicit MHE (multiresolution hash encoding) families are:
798
+
799
+ - `experimental/mhe_mlp`: a shared parameter MLP followed by a wavelength
800
+ decoder that receives learned hash features at every hidden layer.
801
+ - `experimental/mhe_transformer_payne`: parameter tokens and cross-attention,
802
+ with a learned hash encoding and projection for wavelength queries.
803
+
804
+ Both reuse the `transformer_payne` runtime adapter: the same canonical input/output
805
+ keys, channel metadata, custom nested leaf names, flux/intensity device batch
806
+ transforms, `fit`, `predict`, JAX composition, and portable bundle APIs. Parameters
807
+ have shape `(batch, parameter_dim)` and public wavelengths have shape
808
+ `(batch, n_wavelength)`. Outputs have shape `(batch, n_wavelength)` for one channel,
809
+ or `(batch, n_wavelength, channels)` otherwise. Initialize from an example batch
810
+ or `init_hints={"parameter_dim": ...}`.
811
+
812
+ Start from the existing flux or intensity preset and replace the model spec:
813
+
814
+ ```python
815
+ from dataclasses import replace
816
+ from astro_emulators_toolkit import Emulator
817
+ from astro_emulators_toolkit.presets import transformer_payne_flux
818
+
819
+ cfg = transformer_payne_flux(profile="smoke")
820
+ cfg = replace(cfg, model=replace(
821
+ cfg.model,
822
+ name="experimental/mhe_transformer_payne",
823
+ params={**cfg.model.params,
824
+ "mhe": {"levels": 8, "log2_hashmap_size": 12,
825
+ "wavelength_range": [0.0, 1.0]}},
826
+ ))
827
+ emu = Emulator.from_config(cfg)
828
+ # Use explicitly preprocessed data and emu.make_device_batch_transform(...)
829
+ # with emu.fit(...), just as for transformer_payne.
830
+ ```
831
+
832
+ For `experimental/mhe_mlp`, replace the model name and parameter dictionary with,
833
+ for example, `{"hidden_sizes": [128, 128, 128], "parameter_hidden_sizes": [128, 128],
834
+ "min_period": 1e-4, "max_period": 2.0, "mhe": {"wavelength_range": [0.0, 1.0]}}`.
835
+ The transformer uses the usual `dim`, `dim_head`, `no_tokens`, `no_layers`, and
836
+ `dim_ff_multiplier`, plus optional `parameter_hidden_dim`, per-block
837
+ `ff_hidden_sizes`, and `head_hidden_dim`. Architecture parameters and the stable
838
+ models' optional `si`/`mup`/`mup_depth` LR policies are not interchangeable: use
839
+ `lr_scaling=None` or an explicit Optax optimizer for the MHE families.
840
+
841
+ MHE preprocessing is explicit. `mhe.wavelength_range` (default `[0, 1]`),
842
+ `min_period`, and `max_period` are in the wavelength coordinates actually supplied
843
+ to the model, whether physical, normalized, or logarithmic. Neither model takes a
844
+ logarithm or applies reference scaling automatically. Record transforms, units,
845
+ scaling, and intended-use bounds in the usual I/O metadata. Enable
846
+ `JAX_ENABLE_X64=1` and preserve float64 wavelengths even with float32 weights.
847
+
848
+ The nested `mhe` configuration also accepts `levels`, `features_per_level`,
849
+ `log2_hashmap_size`, and `table_init_scale`. Each level linearly interpolates
850
+ learned features with cell widths geometrically spaced from `max_period / 2` to
851
+ `min_period / 2`. Power-of-two tables are capped at `2 ** log2_hashmap_size`, with
852
+ wrapped indices. The range sets the grid origin and allocation; it does not clip
853
+ queries or define a safe extrapolation policy. Wavelength derivatives are
854
+ piecewise defined at grid boundaries. The transformer also supports
855
+ `projection_hidden_dim`, `projection_activation`, `projection_bias`, and optional
856
+ `normalize_output` inside `mhe`; normalization acts on encoded features, not
857
+ physical spectra, and defaults to off.
858
+
859
+ These families require toolkit 0.2.2 or newer, including when loading their bundles.
860
+ They train entirely within aemu without the original development project
861
+ or pretrained weights. Implementation comparisons and bundle round trips establish
862
+ numerical parity and portability; held-out residuals, boundaries, and realistic
863
+ inference tests remain separate scientific validation work.
864
+
865
+ Run [the MHE flux example](examples/experimental/08_train_mhe_flux.py) with
866
+ `--model mhe_mlp` or `--model mhe_transformer_payne` for a complete native workflow
867
+ with explicit input normalization and bundle export.
868
+
737
869
  ### Transformer-specific notes
738
870
 
739
871
  The `transformer_payne` family **requires** `JAX_ENABLE_X64=1`: wavelengths are always handled in float64 up to the embedding cast, and model construction fails without it. Enable it before building or loading these models:
@@ -39,6 +39,9 @@ dependencies = [
39
39
  ]
40
40
  requires-python = ">=3.11"
41
41
 
42
+ [project.scripts]
43
+ aemu = "astro_emulators_toolkit.cli:main"
44
+
42
45
  [project.optional-dependencies]
43
46
  blackjax = [
44
47
  "blackjax>=1.2.5",
@@ -0,0 +1 @@
1
+ __version__ = "0.2.2"
@@ -1,4 +1,11 @@
1
1
  # src/astro_emulators_toolkit/bundle/__init__.py
2
+ from .card import write_model_card
3
+ from .publish import (
4
+ PublishError,
5
+ check_bundle_for_publishing,
6
+ plan_bundle_upload,
7
+ publish_bundle,
8
+ )
2
9
  from .release import (
3
10
  load_bundle_fingerprint_evaluation,
4
11
  prepare_bundle_release,
@@ -6,7 +13,12 @@ from .release import (
6
13
  )
7
14
 
8
15
  __all__ = [
16
+ "PublishError",
17
+ "check_bundle_for_publishing",
9
18
  "load_bundle_fingerprint_evaluation",
19
+ "plan_bundle_upload",
10
20
  "prepare_bundle_release",
21
+ "publish_bundle",
11
22
  "verify_bundle_fingerprint_evaluation",
23
+ "write_model_card",
12
24
  ]