astro-emulators-toolkit 0.2.1__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.1/src/astro_emulators_toolkit.egg-info → astro_emulators_toolkit-0.2.2}/PKG-INFO +73 -1
  2. {astro_emulators_toolkit-0.2.1 → astro_emulators_toolkit-0.2.2}/README.md +72 -0
  3. astro_emulators_toolkit-0.2.2/src/astro_emulators_toolkit/_version.py +1 -0
  4. {astro_emulators_toolkit-0.2.1 → astro_emulators_toolkit-0.2.2}/src/astro_emulators_toolkit/bundle/card.py +5 -1
  5. {astro_emulators_toolkit-0.2.1 → astro_emulators_toolkit-0.2.2}/src/astro_emulators_toolkit/bundle/versions.py +12 -0
  6. {astro_emulators_toolkit-0.2.1 → astro_emulators_toolkit-0.2.2}/src/astro_emulators_toolkit/experimental/models/__init__.py +20 -3
  7. astro_emulators_toolkit-0.2.2/src/astro_emulators_toolkit/experimental/models/mhe.py +302 -0
  8. astro_emulators_toolkit-0.2.2/src/astro_emulators_toolkit/experimental/models/mhe_config.py +242 -0
  9. astro_emulators_toolkit-0.2.2/src/astro_emulators_toolkit/experimental/models/mhe_layers.py +177 -0
  10. {astro_emulators_toolkit-0.2.1 → astro_emulators_toolkit-0.2.2/src/astro_emulators_toolkit.egg-info}/PKG-INFO +73 -1
  11. {astro_emulators_toolkit-0.2.1 → astro_emulators_toolkit-0.2.2}/src/astro_emulators_toolkit.egg-info/SOURCES.txt +3 -0
  12. astro_emulators_toolkit-0.2.1/src/astro_emulators_toolkit/_version.py +0 -1
  13. {astro_emulators_toolkit-0.2.1 → astro_emulators_toolkit-0.2.2}/LICENSE +0 -0
  14. {astro_emulators_toolkit-0.2.1 → astro_emulators_toolkit-0.2.2}/pyproject.toml +0 -0
  15. {astro_emulators_toolkit-0.2.1 → astro_emulators_toolkit-0.2.2}/setup.cfg +0 -0
  16. {astro_emulators_toolkit-0.2.1 → astro_emulators_toolkit-0.2.2}/src/astro_emulators_toolkit/__init__.py +0 -0
  17. {astro_emulators_toolkit-0.2.1 → astro_emulators_toolkit-0.2.2}/src/astro_emulators_toolkit/_typing.py +0 -0
  18. {astro_emulators_toolkit-0.2.1 → astro_emulators_toolkit-0.2.2}/src/astro_emulators_toolkit/_vendor/__init__.py +0 -0
  19. {astro_emulators_toolkit-0.2.1 → astro_emulators_toolkit-0.2.2}/src/astro_emulators_toolkit/_vendor/get_soap_jax.py +0 -0
  20. {astro_emulators_toolkit-0.2.1 → astro_emulators_toolkit-0.2.2}/src/astro_emulators_toolkit/_vendor/soap_jax/LICENSE +0 -0
  21. {astro_emulators_toolkit-0.2.1 → astro_emulators_toolkit-0.2.2}/src/astro_emulators_toolkit/_vendor/soap_jax/README.txt +0 -0
  22. {astro_emulators_toolkit-0.2.1 → astro_emulators_toolkit-0.2.2}/src/astro_emulators_toolkit/_vendor/soap_jax/__init__.py +0 -0
  23. {astro_emulators_toolkit-0.2.1 → astro_emulators_toolkit-0.2.2}/src/astro_emulators_toolkit/_vendor/soap_jax/soap.py +0 -0
  24. {astro_emulators_toolkit-0.2.1 → astro_emulators_toolkit-0.2.2}/src/astro_emulators_toolkit/bundle/__init__.py +0 -0
  25. {astro_emulators_toolkit-0.2.1 → astro_emulators_toolkit-0.2.2}/src/astro_emulators_toolkit/bundle/artifact.py +0 -0
  26. {astro_emulators_toolkit-0.2.1 → astro_emulators_toolkit-0.2.2}/src/astro_emulators_toolkit/bundle/bundle.py +0 -0
  27. {astro_emulators_toolkit-0.2.1 → astro_emulators_toolkit-0.2.2}/src/astro_emulators_toolkit/bundle/extras.py +0 -0
  28. {astro_emulators_toolkit-0.2.1 → astro_emulators_toolkit-0.2.2}/src/astro_emulators_toolkit/bundle/hub.py +0 -0
  29. {astro_emulators_toolkit-0.2.1 → astro_emulators_toolkit-0.2.2}/src/astro_emulators_toolkit/bundle/integrity.py +0 -0
  30. {astro_emulators_toolkit-0.2.1 → astro_emulators_toolkit-0.2.2}/src/astro_emulators_toolkit/bundle/loaded_state.py +0 -0
  31. {astro_emulators_toolkit-0.2.1 → astro_emulators_toolkit-0.2.2}/src/astro_emulators_toolkit/bundle/metadata.py +0 -0
  32. {astro_emulators_toolkit-0.2.1 → astro_emulators_toolkit-0.2.2}/src/astro_emulators_toolkit/bundle/minmax_sidecars.py +0 -0
  33. {astro_emulators_toolkit-0.2.1 → astro_emulators_toolkit-0.2.2}/src/astro_emulators_toolkit/bundle/provenance.py +0 -0
  34. {astro_emulators_toolkit-0.2.1 → astro_emulators_toolkit-0.2.2}/src/astro_emulators_toolkit/bundle/publish.py +0 -0
  35. {astro_emulators_toolkit-0.2.1 → astro_emulators_toolkit-0.2.2}/src/astro_emulators_toolkit/bundle/readme.py +0 -0
  36. {astro_emulators_toolkit-0.2.1 → astro_emulators_toolkit-0.2.2}/src/astro_emulators_toolkit/bundle/release.py +0 -0
  37. {astro_emulators_toolkit-0.2.1 → astro_emulators_toolkit-0.2.2}/src/astro_emulators_toolkit/bundle/safetensors_io.py +0 -0
  38. {astro_emulators_toolkit-0.2.1 → astro_emulators_toolkit-0.2.2}/src/astro_emulators_toolkit/cli.py +0 -0
  39. {astro_emulators_toolkit-0.2.1 → astro_emulators_toolkit-0.2.2}/src/astro_emulators_toolkit/config/__init__.py +0 -0
  40. {astro_emulators_toolkit-0.2.1 → astro_emulators_toolkit-0.2.2}/src/astro_emulators_toolkit/config/io.py +0 -0
  41. {astro_emulators_toolkit-0.2.1 → astro_emulators_toolkit-0.2.2}/src/astro_emulators_toolkit/config/migrations.py +0 -0
  42. {astro_emulators_toolkit-0.2.1 → astro_emulators_toolkit-0.2.2}/src/astro_emulators_toolkit/config/parsing.py +0 -0
  43. {astro_emulators_toolkit-0.2.1 → astro_emulators_toolkit-0.2.2}/src/astro_emulators_toolkit/config/schema.py +0 -0
  44. {astro_emulators_toolkit-0.2.1 → astro_emulators_toolkit-0.2.2}/src/astro_emulators_toolkit/data/__init__.py +0 -0
  45. {astro_emulators_toolkit-0.2.1 → astro_emulators_toolkit-0.2.2}/src/astro_emulators_toolkit/data/array_dataset.py +0 -0
  46. {astro_emulators_toolkit-0.2.1 → astro_emulators_toolkit-0.2.2}/src/astro_emulators_toolkit/data/loader.py +0 -0
  47. {astro_emulators_toolkit-0.2.1 → astro_emulators_toolkit-0.2.2}/src/astro_emulators_toolkit/data/mapped_dataset.py +0 -0
  48. {astro_emulators_toolkit-0.2.1 → astro_emulators_toolkit-0.2.2}/src/astro_emulators_toolkit/data/npy_table.py +0 -0
  49. {astro_emulators_toolkit-0.2.1 → astro_emulators_toolkit-0.2.2}/src/astro_emulators_toolkit/data/preprocess.py +0 -0
  50. {astro_emulators_toolkit-0.2.1 → astro_emulators_toolkit-0.2.2}/src/astro_emulators_toolkit/data/protocols.py +0 -0
  51. {astro_emulators_toolkit-0.2.1 → astro_emulators_toolkit-0.2.2}/src/astro_emulators_toolkit/data/subset.py +0 -0
  52. {astro_emulators_toolkit-0.2.1 → astro_emulators_toolkit-0.2.2}/src/astro_emulators_toolkit/data/toy.py +0 -0
  53. {astro_emulators_toolkit-0.2.1 → astro_emulators_toolkit-0.2.2}/src/astro_emulators_toolkit/data/toy_utils.py +0 -0
  54. {astro_emulators_toolkit-0.2.1 → astro_emulators_toolkit-0.2.2}/src/astro_emulators_toolkit/emulator.py +0 -0
  55. {astro_emulators_toolkit-0.2.1 → astro_emulators_toolkit-0.2.2}/src/astro_emulators_toolkit/emulator_runtime.py +0 -0
  56. {astro_emulators_toolkit-0.2.1 → astro_emulators_toolkit-0.2.2}/src/astro_emulators_toolkit/experimental/__init__.py +0 -0
  57. {astro_emulators_toolkit-0.2.1 → astro_emulators_toolkit-0.2.2}/src/astro_emulators_toolkit/experimental/models/explicit_wavelength_mlp.py +0 -0
  58. {astro_emulators_toolkit-0.2.1 → astro_emulators_toolkit-0.2.2}/src/astro_emulators_toolkit/experimental/models/mlp_2d_regression.py +0 -0
  59. {astro_emulators_toolkit-0.2.1 → astro_emulators_toolkit-0.2.2}/src/astro_emulators_toolkit/experimental/models/siren.py +0 -0
  60. {astro_emulators_toolkit-0.2.1 → astro_emulators_toolkit-0.2.2}/src/astro_emulators_toolkit/experimental/runtime_adapters.py +0 -0
  61. {astro_emulators_toolkit-0.2.1 → astro_emulators_toolkit-0.2.2}/src/astro_emulators_toolkit/experimental/tasks/__init__.py +0 -0
  62. {astro_emulators_toolkit-0.2.1 → astro_emulators_toolkit-0.2.2}/src/astro_emulators_toolkit/experimental/tasks/classification.py +0 -0
  63. {astro_emulators_toolkit-0.2.1 → astro_emulators_toolkit-0.2.2}/src/astro_emulators_toolkit/inference/__init__.py +0 -0
  64. {astro_emulators_toolkit-0.2.1 → astro_emulators_toolkit-0.2.2}/src/astro_emulators_toolkit/inference/compose.py +0 -0
  65. {astro_emulators_toolkit-0.2.1 → astro_emulators_toolkit-0.2.2}/src/astro_emulators_toolkit/io_trees.py +0 -0
  66. {astro_emulators_toolkit-0.2.1 → astro_emulators_toolkit-0.2.2}/src/astro_emulators_toolkit/models/__init__.py +0 -0
  67. {astro_emulators_toolkit-0.2.1 → astro_emulators_toolkit-0.2.2}/src/astro_emulators_toolkit/models/activations.py +0 -0
  68. {astro_emulators_toolkit-0.2.1 → astro_emulators_toolkit-0.2.2}/src/astro_emulators_toolkit/models/cannon.py +0 -0
  69. {astro_emulators_toolkit-0.2.1 → astro_emulators_toolkit-0.2.2}/src/astro_emulators_toolkit/models/canonical_wrappers.py +0 -0
  70. {astro_emulators_toolkit-0.2.1 → astro_emulators_toolkit-0.2.2}/src/astro_emulators_toolkit/models/dtypes.py +0 -0
  71. {astro_emulators_toolkit-0.2.1 → astro_emulators_toolkit-0.2.2}/src/astro_emulators_toolkit/models/mlp.py +0 -0
  72. {astro_emulators_toolkit-0.2.1 → astro_emulators_toolkit-0.2.2}/src/astro_emulators_toolkit/models/runtime_adapters.py +0 -0
  73. {astro_emulators_toolkit-0.2.1 → astro_emulators_toolkit-0.2.2}/src/astro_emulators_toolkit/models/transformer_payne.py +0 -0
  74. {astro_emulators_toolkit-0.2.1 → astro_emulators_toolkit-0.2.2}/src/astro_emulators_toolkit/models/transformer_payne_batch.py +0 -0
  75. {astro_emulators_toolkit-0.2.1 → astro_emulators_toolkit-0.2.2}/src/astro_emulators_toolkit/optimizers/__init__.py +0 -0
  76. {astro_emulators_toolkit-0.2.1 → astro_emulators_toolkit-0.2.2}/src/astro_emulators_toolkit/optimizers/_soap.py +0 -0
  77. {astro_emulators_toolkit-0.2.1 → astro_emulators_toolkit-0.2.2}/src/astro_emulators_toolkit/presets/__init__.py +0 -0
  78. {astro_emulators_toolkit-0.2.1 → astro_emulators_toolkit-0.2.2}/src/astro_emulators_toolkit/presets/cannon.py +0 -0
  79. {astro_emulators_toolkit-0.2.1 → astro_emulators_toolkit-0.2.2}/src/astro_emulators_toolkit/presets/mlp.py +0 -0
  80. {astro_emulators_toolkit-0.2.1 → astro_emulators_toolkit-0.2.2}/src/astro_emulators_toolkit/presets/transformer_payne.py +0 -0
  81. {astro_emulators_toolkit-0.2.1 → astro_emulators_toolkit-0.2.2}/src/astro_emulators_toolkit/py.typed +0 -0
  82. {astro_emulators_toolkit-0.2.1 → astro_emulators_toolkit-0.2.2}/src/astro_emulators_toolkit/resolver.py +0 -0
  83. {astro_emulators_toolkit-0.2.1 → astro_emulators_toolkit-0.2.2}/src/astro_emulators_toolkit/spec.py +0 -0
  84. {astro_emulators_toolkit-0.2.1 → astro_emulators_toolkit-0.2.2}/src/astro_emulators_toolkit/tasks/__init__.py +0 -0
  85. {astro_emulators_toolkit-0.2.1 → astro_emulators_toolkit-0.2.2}/src/astro_emulators_toolkit/tasks/common.py +0 -0
  86. {astro_emulators_toolkit-0.2.1 → astro_emulators_toolkit-0.2.2}/src/astro_emulators_toolkit/tasks/regression.py +0 -0
  87. {astro_emulators_toolkit-0.2.1 → astro_emulators_toolkit-0.2.2}/src/astro_emulators_toolkit/training/__init__.py +0 -0
  88. {astro_emulators_toolkit-0.2.1 → astro_emulators_toolkit-0.2.2}/src/astro_emulators_toolkit/training/callbacks.py +0 -0
  89. {astro_emulators_toolkit-0.2.1 → astro_emulators_toolkit-0.2.2}/src/astro_emulators_toolkit/training/checkpoint.py +0 -0
  90. {astro_emulators_toolkit-0.2.1 → astro_emulators_toolkit-0.2.2}/src/astro_emulators_toolkit/training/fit_backends.py +0 -0
  91. {astro_emulators_toolkit-0.2.1 → astro_emulators_toolkit-0.2.2}/src/astro_emulators_toolkit/training/paths.py +0 -0
  92. {astro_emulators_toolkit-0.2.1 → astro_emulators_toolkit-0.2.2}/src/astro_emulators_toolkit/training/solvers.py +0 -0
  93. {astro_emulators_toolkit-0.2.1 → astro_emulators_toolkit-0.2.2}/src/astro_emulators_toolkit/training/state.py +0 -0
  94. {astro_emulators_toolkit-0.2.1 → astro_emulators_toolkit-0.2.2}/src/astro_emulators_toolkit/training/trainer.py +0 -0
  95. {astro_emulators_toolkit-0.2.1 → astro_emulators_toolkit-0.2.2}/src/astro_emulators_toolkit/utils/__init__.py +0 -0
  96. {astro_emulators_toolkit-0.2.1 → astro_emulators_toolkit-0.2.2}/src/astro_emulators_toolkit/utils/tree.py +0 -0
  97. {astro_emulators_toolkit-0.2.1 → astro_emulators_toolkit-0.2.2}/src/astro_emulators_toolkit.egg-info/dependency_links.txt +0 -0
  98. {astro_emulators_toolkit-0.2.1 → astro_emulators_toolkit-0.2.2}/src/astro_emulators_toolkit.egg-info/entry_points.txt +0 -0
  99. {astro_emulators_toolkit-0.2.1 → astro_emulators_toolkit-0.2.2}/src/astro_emulators_toolkit.egg-info/requires.txt +0 -0
  100. {astro_emulators_toolkit-0.2.1 → 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.1
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
@@ -833,6 +833,78 @@ cfg = load_config("runs/demo/config.yaml")
833
833
 
834
834
  Prototype model families and tasks live under `experimental/...`. They are useful for research and development but are intentionally outside the stable public contract.
835
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
+
836
908
  ### Transformer-specific notes
837
909
 
838
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:
@@ -794,6 +794,78 @@ cfg = load_config("runs/demo/config.yaml")
794
794
 
795
795
  Prototype model families and tasks live under `experimental/...`. They are useful for research and development but are intentionally outside the stable public contract.
796
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
+
797
869
  ### Transformer-specific notes
798
870
 
799
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:
@@ -0,0 +1 @@
1
+ __version__ = "0.2.2"
@@ -34,7 +34,11 @@ GENERATED_END = "<!-- aemu:generated:end -->"
34
34
  TODO_MARKER = "<!-- aemu:todo"
35
35
 
36
36
  # Families whose wavelength handling needs JAX float64.
37
- _X64_FAMILY_PREFIXES = ("transformer_payne",)
37
+ _X64_FAMILY_PREFIXES = (
38
+ "transformer_payne",
39
+ "experimental_mhe_mlp_",
40
+ "experimental_mhe_transformer_payne_",
41
+ )
38
42
 
39
43
  _AUTHOR_SECTIONS = (
40
44
  (
@@ -114,6 +114,13 @@ FIRST_LOADING_TOOLKIT: dict[str, dict[Any, str]] = {
114
114
  }
115
115
 
116
116
 
117
+ # New model families can require a newer runtime without changing bundle stamps.
118
+ _MODEL_FIRST_LOADING_TOOLKIT = {
119
+ "experimental_mhe_mlp_v1": "0.2.2",
120
+ "experimental_mhe_transformer_payne_v1": "0.2.2",
121
+ }
122
+
123
+
117
124
  def _version_key(version: str) -> tuple[int, ...]:
118
125
  return tuple(int(part) for part in version.split("."))
119
126
 
@@ -137,6 +144,11 @@ def minimum_loading_toolkit_version(metadata: dict[str, Any]) -> str | None:
137
144
  if stamp not in table:
138
145
  return None
139
146
  needed.append(table[stamp])
147
+ family_minimum = _MODEL_FIRST_LOADING_TOOLKIT.get(
148
+ str(metadata.get("model_family_id") or "")
149
+ )
150
+ if family_minimum is not None:
151
+ needed.append(family_minimum)
140
152
  provenance = metadata.get("provenance") or {}
141
153
  if wrote_v2_meaning(provenance.get("toolkit_version")):
142
154
  # 0.2.0 pre-releases stamped config schema v1 but wrote keys that
@@ -3,16 +3,33 @@ from __future__ import annotations
3
3
  from typing import Any
4
4
 
5
5
  from ...models import ModelRegistryEntry
6
- from .explicit_wavelength_mlp import ExplicitWavelengthMLP, ExplicitWavelengthMLPConfig
7
- from .mlp_2d_regression import MLP2DRegression, MLP2DRegressionConfig
8
- from .siren import Siren, SirenConfig
6
+ from ...models.runtime_adapters import TransformerPayneRuntimeAdapter
9
7
  from ..runtime_adapters import (
10
8
  ExplicitWavelengthMLPRuntimeAdapter,
11
9
  MLP2DRegressionRuntimeAdapter,
12
10
  SirenRuntimeAdapter,
13
11
  )
12
+ from .explicit_wavelength_mlp import ExplicitWavelengthMLP, ExplicitWavelengthMLPConfig
13
+ from .mhe import MHEMLP, MHETransformerPayne
14
+ from .mhe_config import MHEMLPConfig, MHETransformerPayneConfig
15
+ from .mlp_2d_regression import MLP2DRegression, MLP2DRegressionConfig
16
+ from .siren import Siren, SirenConfig
14
17
 
15
18
  _EXPERIMENTAL_MODEL_REGISTRY: dict[str, ModelRegistryEntry] = {
19
+ "mhe_mlp": ModelRegistryEntry(
20
+ public_name="experimental/mhe_mlp",
21
+ family_id="experimental_mhe_mlp_v1",
22
+ config_cls=MHEMLPConfig,
23
+ model_cls=MHEMLP,
24
+ runtime=TransformerPayneRuntimeAdapter(),
25
+ ),
26
+ "mhe_transformer_payne": ModelRegistryEntry(
27
+ public_name="experimental/mhe_transformer_payne",
28
+ family_id="experimental_mhe_transformer_payne_v1",
29
+ config_cls=MHETransformerPayneConfig,
30
+ model_cls=MHETransformerPayne,
31
+ runtime=TransformerPayneRuntimeAdapter(),
32
+ ),
16
33
  "explicit_wavelength_mlp": ModelRegistryEntry(
17
34
  public_name="experimental/explicit_wavelength_mlp",
18
35
  family_id="experimental_explicit_wavelength_mlp_v1",
@@ -0,0 +1,302 @@
1
+ """MHE networks with a shared parameter trunk and independent wavelength queries.
2
+
3
+ Adapted from exojax_emulator.mhe_models. Trained parameter names and numerical
4
+ operations are retained for reference comparisons.
5
+ """
6
+
7
+ from __future__ import annotations
8
+
9
+ from typing import NamedTuple
10
+ import jax
11
+ import jax.numpy as jnp
12
+ from flax import nnx
13
+
14
+ from .mhe_config import MHETransformerPayneConfig, MHEMLPConfig, positive_int
15
+ from .mhe_layers import (
16
+ MHEHashEncoding,
17
+ MHEWavelengthEncoding,
18
+ activation,
19
+ linear,
20
+ rms_norm,
21
+ )
22
+
23
+
24
+ def _validate_dims(in_dim, out_dim):
25
+ positive_int("in_dim", in_dim)
26
+ if out_dim != 1:
27
+ raise ValueError(
28
+ "MHE models require output init size 1; wavelength is an explicit input axis."
29
+ )
30
+
31
+
32
+ def _labels(labels, in_dim, dtype):
33
+ labels = jnp.asarray(labels, dtype=dtype)
34
+ if labels.ndim != 2 or labels.shape[1] != in_dim:
35
+ raise ValueError(f"parameters must have shape (batch, {in_dim})")
36
+ return labels
37
+
38
+
39
+ def _waves(waves, batch, *, one=False):
40
+ # Match TransformerPayne's float64 coordinate path. Callers must preserve
41
+ # precision before this point; promoting an already rounded array cannot restore it.
42
+ waves = jnp.asarray(waves, dtype=jnp.float64)
43
+ if one:
44
+ if waves.ndim == 0:
45
+ waves = jnp.broadcast_to(waves, (batch,))
46
+ if waves.shape != (batch,):
47
+ raise ValueError(
48
+ "predict_one expects a scalar or one wavelength per atmosphere"
49
+ )
50
+ else:
51
+ if waves.ndim == 1:
52
+ waves = jnp.broadcast_to(waves, (batch, waves.shape[0]))
53
+ if waves.ndim != 2 or waves.shape[0] != batch:
54
+ raise ValueError("queries must have shape (queries,) or (batch, queries)")
55
+ return waves
56
+
57
+
58
+ class TransformerContext(NamedTuple):
59
+ """Differentiable per-block K/V without a wavelength axis."""
60
+
61
+ keys_values: tuple
62
+
63
+
64
+ class CrossAttention(nnx.Module):
65
+ def __init__(self, cfg, *, rngs):
66
+ self.heads, self.head_dim, self.alpha_att = (
67
+ (cfg.dim // cfg.dim_head),
68
+ cfg.dim_head,
69
+ cfg.alpha_att,
70
+ )
71
+ options = dict(
72
+ rngs=rngs,
73
+ bias=cfg.bias_attention,
74
+ dtype=cfg.dtype,
75
+ initializer=cfg.kernel_init,
76
+ sigma=cfg.sigma,
77
+ )
78
+ self.q = linear(cfg.dim, cfg.dim, zero=cfg.init_att_q == "zero", **options)
79
+ self.k = linear(cfg.dim, cfg.dim, **options)
80
+ self.v = linear(cfg.dim, cfg.dim, **options)
81
+ self.out = linear(cfg.dim, cfg.dim, zero=cfg.init_att_o == "zero", **options)
82
+
83
+ def prepare_context(self, tokens):
84
+ shape = (*tokens.shape[:-1], self.heads, self.head_dim)
85
+ return self.k(tokens).reshape(shape), self.v(tokens).reshape(shape)
86
+
87
+ def __call__(self, queries, context):
88
+ k, v = context
89
+ q = self.q(queries).reshape(*queries.shape[:-1], self.heads, self.head_dim)
90
+ scores = jnp.einsum("bqhd,bthd->bhqt", q, k) / self.head_dim
91
+ if self.alpha_att != 1.0:
92
+ scores = scores * self.alpha_att
93
+ values = jnp.einsum("bhqt,bthd->bqhd", jax.nn.softmax(scores, axis=-1), v)
94
+ return self.out(values.reshape(queries.shape))
95
+
96
+
97
+ class Block(nnx.Module):
98
+ def __init__(self, cfg, width, *, rngs):
99
+ self.attention = CrossAttention(cfg, rngs=rngs)
100
+ options = dict(
101
+ rngs=rngs,
102
+ bias=cfg.bias("feed_forward"),
103
+ dtype=cfg.dtype,
104
+ initializer=cfg.kernel_init,
105
+ sigma=cfg.sigma,
106
+ )
107
+ self.ff_in = linear(cfg.dim, width, **options)
108
+ self.ff_out = linear(width, cfg.dim, zero=cfg.ff_init == "zero", **options)
109
+ self.activation, self.epsilon, self.residual_scale = (
110
+ cfg.activation,
111
+ cfg.rms_epsilon,
112
+ cfg.residual_scale,
113
+ )
114
+
115
+ def __call__(self, h, context):
116
+ update = self.attention(rms_norm(h, self.epsilon), context)
117
+ h = h + (update if self.residual_scale == 1.0 else self.residual_scale * update)
118
+ update = self.ff_out(
119
+ activation(self.activation, self.ff_in(rms_norm(h, self.epsilon)))
120
+ )
121
+ return h + (
122
+ update if self.residual_scale == 1.0 else self.residual_scale * update
123
+ )
124
+
125
+
126
+ class MHETransformerPayne(nnx.Module):
127
+ """Shared atmospheric tokens/KV, with independent wavelength predictions.
128
+
129
+ Inputs: labels (B,D), float64 wavelength queries (Q,) or (B,Q).
130
+ Outputs: (B,Q) or (B,Q,C). Rebuild prepared context if labels or weights change.
131
+ """
132
+
133
+ def __init__(
134
+ self,
135
+ *,
136
+ in_dim: int,
137
+ out_dim: int,
138
+ cfg: MHETransformerPayneConfig,
139
+ rngs: nnx.Rngs,
140
+ ):
141
+ _validate_dims(in_dim, out_dim)
142
+ self.in_dim = in_dim
143
+ self.config = cfg
144
+ self.dim, self.parameter_tokens = cfg.dim, cfg.no_tokens
145
+ options = dict(
146
+ rngs=rngs, dtype=cfg.dtype, initializer=cfg.kernel_init, sigma=cfg.sigma
147
+ )
148
+ width = cfg.parameter_hidden_dim or cfg.dim
149
+ self.label_in = linear(
150
+ in_dim, width, bias=cfg.bias("parameter_embedding"), **options
151
+ )
152
+ self.label_out = linear(
153
+ width,
154
+ cfg.no_tokens * cfg.dim,
155
+ bias=cfg.bias("parameter_embedding"),
156
+ zero=cfg.emb_init == "zero",
157
+ **options,
158
+ )
159
+ widths = (
160
+ cfg.ff_hidden_sizes or (cfg.dim * cfg.dim_ff_multiplier,) * cfg.no_layers
161
+ )
162
+ self.blocks = nnx.List([Block(cfg, width, rngs=rngs) for width in widths])
163
+ width = cfg.head_hidden_dim or cfg.dim
164
+ self.head_in = linear(cfg.dim, width, bias=cfg.bias("output_head"), **options)
165
+ self.head_out = linear(
166
+ width,
167
+ cfg.channels,
168
+ bias=cfg.bias("output_head"),
169
+ zero=cfg.head_init == "zero",
170
+ **options,
171
+ )
172
+ self.wavelength_encoder = MHEWavelengthEncoding(
173
+ cfg.dim,
174
+ rngs=rngs,
175
+ min_period=cfg.min_period,
176
+ max_period=cfg.max_period,
177
+ cfg=cfg.mhe,
178
+ dtype=cfg.dtype,
179
+ )
180
+
181
+ def encode_wavelength(self, wavelengths):
182
+ return self.wavelength_encoder(wavelengths)
183
+
184
+ def prepare_context(self, labels):
185
+ labels = _labels(labels, self.in_dim, self.config.dtype)
186
+ tokens = self.label_out(
187
+ activation(self.config.activation, self.label_in(labels))
188
+ )
189
+ tokens = tokens.reshape(labels.shape[0], self.parameter_tokens, self.dim)
190
+ if self.config.alpha_emb != 1.0:
191
+ tokens = self.config.alpha_emb * tokens
192
+ tokens = rms_norm(tokens, self.config.rms_epsilon)
193
+ return TransformerContext(
194
+ tuple(block.attention.prepare_context(tokens) for block in self.blocks)
195
+ )
196
+
197
+ def predict_one(self, context, wavelengths):
198
+ """One wavelength per atmosphere, with the trunk already evaluated."""
199
+ if len(context.keys_values) != len(self.blocks):
200
+ raise ValueError("Context must contain K/V for every transformer block")
201
+ wave = _waves(wavelengths, context.keys_values[0][0].shape[0], one=True)
202
+ h = self.encode_wavelength(wave[:, None])
203
+ for block, kv in zip(self.blocks, context.keys_values):
204
+ h = block(h, kv)
205
+ h = self.head_out(
206
+ activation(
207
+ self.config.activation,
208
+ self.head_in(rms_norm(h, self.config.rms_epsilon)),
209
+ )
210
+ )
211
+ h = activation(self.config.output_activation, h)[:, 0, :]
212
+ return h[:, 0] if self.config.channels == 1 else h
213
+
214
+ def predict_queries(self, context, wavelengths):
215
+ if len(context.keys_values) != len(self.blocks):
216
+ raise ValueError("Context must contain K/V for every transformer block")
217
+ waves = _waves(wavelengths, context.keys_values[0][0].shape[0])
218
+ return jax.vmap(
219
+ lambda wave: self.predict_one(context, wave), in_axes=1, out_axes=1
220
+ )(waves)
221
+
222
+ def __call__(self, x, *, train: bool = False, rngs: nnx.Rngs | None = None):
223
+ del train, rngs
224
+ labels, wavelengths = x
225
+ return self.predict_queries(self.prepare_context(labels), wavelengths)
226
+
227
+
228
+ class MHEMLP(nnx.Module):
229
+ """Shared parameter MLP; MHE features enter each vmapped query layer.
230
+
231
+ GELU is the default; alternative activations are explicit ablations.
232
+ Context and query shape conventions match MHETransformerPayne.
233
+ """
234
+
235
+ def __init__(self, *, in_dim: int, out_dim: int, cfg: MHEMLPConfig, rngs: nnx.Rngs):
236
+ _validate_dims(in_dim, out_dim)
237
+ self.in_dim = in_dim
238
+ self.config = cfg
239
+ assert cfg.mhe is not None and cfg.parameter_hidden_sizes is not None
240
+ self.wavelength_encoder = MHEHashEncoding(
241
+ rngs=rngs,
242
+ min_period=cfg.min_period,
243
+ max_period=cfg.max_period,
244
+ cfg=cfg.mhe,
245
+ dtype=cfg.dtype,
246
+ )
247
+ features = cfg.mhe.levels * cfg.mhe.features_per_level
248
+ options = dict(
249
+ rngs=rngs, dtype=cfg.dtype, initializer=cfg.kernel_init, sigma=cfg.sigma
250
+ )
251
+ sizes = (in_dim, *cfg.parameter_hidden_sizes)
252
+ self.parameter_layers = nnx.List(
253
+ [
254
+ linear(a, b, bias=cfg.bias_parameter_embedding, **options)
255
+ for a, b in zip(sizes[:-1], sizes[1:])
256
+ ]
257
+ )
258
+ sizes = (cfg.parameter_hidden_sizes[-1], *cfg.hidden_sizes)
259
+ self.layers = nnx.List(
260
+ [
261
+ linear(a + features, b, bias=cfg.bias_decoder, **options)
262
+ for a, b in zip(sizes[:-1], sizes[1:])
263
+ ]
264
+ + [
265
+ linear(
266
+ cfg.hidden_sizes[-1],
267
+ cfg.channels,
268
+ bias=cfg.bias_output_head,
269
+ **options,
270
+ )
271
+ ]
272
+ )
273
+
274
+ def encode_parameters(self, labels):
275
+ h = _labels(labels, self.in_dim, self.config.dtype)
276
+ for layer in self.parameter_layers:
277
+ h = activation(self.config.activation, layer(h))
278
+ return h
279
+
280
+ def prepare_context(self, labels):
281
+ return self.encode_parameters(labels)
282
+
283
+ def predict_one(self, context, wavelengths):
284
+ wave = _waves(wavelengths, context.shape[0], one=True)
285
+ features, h = self.wavelength_encoder(wave[:, None]), context[:, None, :]
286
+ for layer in self.layers[:-1]:
287
+ h = activation(
288
+ self.config.activation, layer(jnp.concatenate((h, features), axis=-1))
289
+ )
290
+ h = activation(self.config.output_activation, self.layers[-1](h))[:, 0, :]
291
+ return h[:, 0] if self.config.channels == 1 else h
292
+
293
+ def predict_queries(self, context, wavelengths):
294
+ waves = _waves(wavelengths, context.shape[0])
295
+ return jax.vmap(
296
+ lambda wave: self.predict_one(context, wave), in_axes=1, out_axes=1
297
+ )(waves)
298
+
299
+ def __call__(self, x, *, train: bool = False, rngs: nnx.Rngs | None = None):
300
+ del train, rngs
301
+ labels, wavelengths = x
302
+ return self.predict_queries(self.prepare_context(labels), wavelengths)