marathon-train 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 (53) hide show
  1. marathon_train-0.2.2/PKG-INFO +141 -0
  2. marathon_train-0.2.2/README.md +101 -0
  3. {marathon_train-0.2.0 → marathon_train-0.2.2}/pyproject.toml +2 -1
  4. marathon_train-0.2.0/PKG-INFO +0 -37
  5. {marathon_train-0.2.0 → marathon_train-0.2.2}/LICENSE +0 -0
  6. {marathon_train-0.2.0 → marathon_train-0.2.2}/marathon/README.md +0 -0
  7. {marathon_train-0.2.0 → marathon_train-0.2.2}/marathon/__init__.py +0 -0
  8. {marathon_train-0.2.0 → marathon_train-0.2.2}/marathon/data/README.md +0 -0
  9. {marathon_train-0.2.0 → marathon_train-0.2.2}/marathon/data/__init__.py +0 -0
  10. {marathon_train-0.2.0 → marathon_train-0.2.2}/marathon/data/batching.py +0 -0
  11. {marathon_train-0.2.0 → marathon_train-0.2.2}/marathon/data/properties.py +0 -0
  12. {marathon_train-0.2.0 → marathon_train-0.2.2}/marathon/data/sample.py +0 -0
  13. {marathon_train-0.2.0 → marathon_train-0.2.2}/marathon/data/sizes.py +0 -0
  14. {marathon_train-0.2.0 → marathon_train-0.2.2}/marathon/data/splits.py +0 -0
  15. {marathon_train-0.2.0 → marathon_train-0.2.2}/marathon/elemental.py +0 -0
  16. {marathon_train-0.2.0 → marathon_train-0.2.2}/marathon/emit/README.md +0 -0
  17. {marathon_train-0.2.0 → marathon_train-0.2.2}/marathon/emit/__init__.py +0 -0
  18. {marathon_train-0.2.0 → marathon_train-0.2.2}/marathon/emit/checkpoint.py +0 -0
  19. {marathon_train-0.2.0 → marathon_train-0.2.2}/marathon/emit/log.py +0 -0
  20. {marathon_train-0.2.0 → marathon_train-0.2.2}/marathon/emit/plot.py +0 -0
  21. {marathon_train-0.2.0 → marathon_train-0.2.2}/marathon/emit/pretty.py +0 -0
  22. {marathon_train-0.2.0 → marathon_train-0.2.2}/marathon/emit/properties.py +0 -0
  23. {marathon_train-0.2.0 → marathon_train-0.2.2}/marathon/evaluate/README.md +0 -0
  24. {marathon_train-0.2.0 → marathon_train-0.2.2}/marathon/evaluate/__init__.py +0 -0
  25. {marathon_train-0.2.0 → marathon_train-0.2.2}/marathon/evaluate/loss.py +0 -0
  26. {marathon_train-0.2.0 → marathon_train-0.2.2}/marathon/evaluate/metrics.py +0 -0
  27. {marathon_train-0.2.0 → marathon_train-0.2.2}/marathon/evaluate/predict.py +0 -0
  28. {marathon_train-0.2.0 → marathon_train-0.2.2}/marathon/evaluate/properties.py +0 -0
  29. {marathon_train-0.2.0 → marathon_train-0.2.2}/marathon/extra/__init__.py +0 -0
  30. {marathon_train-0.2.0 → marathon_train-0.2.2}/marathon/extra/edge_to_edge/README.md +0 -0
  31. {marathon_train-0.2.0 → marathon_train-0.2.2}/marathon/extra/edge_to_edge/__init__.py +0 -0
  32. {marathon_train-0.2.0 → marathon_train-0.2.2}/marathon/extra/edge_to_edge/batching.py +0 -0
  33. {marathon_train-0.2.0 → marathon_train-0.2.2}/marathon/extra/edge_to_edge/neighborlist.py +0 -0
  34. {marathon_train-0.2.0 → marathon_train-0.2.2}/marathon/extra/hermes/__init__.py +0 -0
  35. {marathon_train-0.2.0 → marathon_train-0.2.2}/marathon/extra/hermes/data_source.py +0 -0
  36. {marathon_train-0.2.0 → marathon_train-0.2.2}/marathon/extra/hermes/pain.py +0 -0
  37. {marathon_train-0.2.0 → marathon_train-0.2.2}/marathon/grain/README.md +0 -0
  38. {marathon_train-0.2.0 → marathon_train-0.2.2}/marathon/grain/__init__.py +0 -0
  39. {marathon_train-0.2.0 → marathon_train-0.2.2}/marathon/grain/data_source/README.md +0 -0
  40. {marathon_train-0.2.0 → marathon_train-0.2.2}/marathon/grain/data_source/__init__.py +0 -0
  41. {marathon_train-0.2.0 → marathon_train-0.2.2}/marathon/grain/data_source/data_source.py +0 -0
  42. {marathon_train-0.2.0 → marathon_train-0.2.2}/marathon/grain/data_source/flatten_atoms.py +0 -0
  43. {marathon_train-0.2.0 → marathon_train-0.2.2}/marathon/grain/data_source/prepare.py +0 -0
  44. {marathon_train-0.2.0 → marathon_train-0.2.2}/marathon/grain/data_source/properties.py +0 -0
  45. {marathon_train-0.2.0 → marathon_train-0.2.2}/marathon/grain/transforms/README.md +0 -0
  46. {marathon_train-0.2.0 → marathon_train-0.2.2}/marathon/grain/transforms/__init__.py +0 -0
  47. {marathon_train-0.2.0 → marathon_train-0.2.2}/marathon/grain/transforms/transforms.py +0 -0
  48. {marathon_train-0.2.0 → marathon_train-0.2.2}/marathon/io/README.md +0 -0
  49. {marathon_train-0.2.0 → marathon_train-0.2.2}/marathon/io/__init__.py +0 -0
  50. {marathon_train-0.2.0 → marathon_train-0.2.2}/marathon/io/dicts.py +0 -0
  51. {marathon_train-0.2.0 → marathon_train-0.2.2}/marathon/io/msgpack.py +0 -0
  52. {marathon_train-0.2.0 → marathon_train-0.2.2}/marathon/io/yaml.py +0 -0
  53. {marathon_train-0.2.0 → marathon_train-0.2.2}/marathon/utils.py +0 -0
@@ -0,0 +1,141 @@
1
+ Metadata-Version: 2.4
2
+ Name: marathon-train
3
+ Version: 0.2.2
4
+ Summary: experimental tooling for training machine learning interatomic potentials in jax
5
+ License: MIT
6
+ License-File: LICENSE
7
+ Author: Marcel Langer
8
+ Author-email: dev@marcel.science
9
+ Requires-Python: >=3.7
10
+ Classifier: License :: OSI Approved :: MIT License
11
+ Classifier: Programming Language :: Python :: 3
12
+ Classifier: Programming Language :: Python :: 3.7
13
+ Classifier: Programming Language :: Python :: 3.8
14
+ Classifier: Programming Language :: Python :: 3.9
15
+ Classifier: Programming Language :: Python :: 3.10
16
+ Classifier: Programming Language :: Python :: 3.11
17
+ Classifier: Programming Language :: Python :: 3.12
18
+ Classifier: Programming Language :: Python :: 3.13
19
+ Classifier: Programming Language :: Python :: 3.14
20
+ Provides-Extra: all
21
+ Provides-Extra: dev
22
+ Provides-Extra: grain
23
+ Provides-Extra: plot
24
+ Provides-Extra: wandb
25
+ Requires-Dist: PyYAML
26
+ Requires-Dist: ase
27
+ Requires-Dist: flax
28
+ Requires-Dist: grain ; extra == "all" or extra == "grain"
29
+ Requires-Dist: matplotlib ; extra == "all" or extra == "plot"
30
+ Requires-Dist: mmap_ninja ; extra == "all" or extra == "grain"
31
+ Requires-Dist: numba ; extra == "all" or extra == "grain"
32
+ Requires-Dist: opsis
33
+ Requires-Dist: pytest ; extra == "all" or extra == "dev"
34
+ Requires-Dist: ruff ; extra == "all" or extra == "dev"
35
+ Requires-Dist: scipy ; extra == "all" or extra == "grain"
36
+ Requires-Dist: vesin (>=0.3.2)
37
+ Requires-Dist: wandb ; extra == "all" or extra == "wandb"
38
+ Description-Content-Type: text/markdown
39
+
40
+ <p align="center">
41
+ <picture>
42
+ <source media="(prefers-color-scheme: dark)" srcset="https://data.marcel.science/marathon/logo.png">
43
+ <img src="https://data.marcel.science/marathon/logo-dark.png" alt="marathon" width="300">
44
+ </picture>
45
+ </p>
46
+
47
+ <h1 align="center">marathon</h1>
48
+
49
+ <p align="center">
50
+ <em>modular training infrastructure for machine-learning interatomic potentials in JAX</em>
51
+ </p>
52
+
53
+ <p align="center">
54
+ <img alt="status: experimental" src="https://img.shields.io/badge/status-experimental-orange">
55
+ <img alt="code style: black" src="https://img.shields.io/badge/code%20style-black-000000.svg">
56
+ </p>
57
+
58
+ <p align="center">
59
+ <em>pheidippides would be a great name for a message-passing neural network</em>
60
+ </p>
61
+
62
+ ---
63
+
64
+ `marathon` is an experimental `jax/flax`-oriented toolkit for prototyping machine-learning interatomic potentials. It does not provide a finished and polished training loop; instead it provides a few composable parts that can be assembled and adapted as needed for experiments. It's therefore not intended as user-facing production code, instead it aims to make experiments faster and more pleasant.
65
+
66
+ | Module | Description |
67
+ |--------|-------------|
68
+ | `marathon.data` | Process `ase.Atoms` into padded batches with a flexible properties system |
69
+ | `marathon.evaluate` | Predict energy, forces, stress; compute loss (MSE/Huber) and metrics (MAE, RMSE, R2) |
70
+ | `marathon.emit` | Checkpointing, logging (text, W&B), diagnostic plots |
71
+ | `marathon.io` | Read/write `msgpack` and `yaml`; serialize `flax.nn.Module` instances |
72
+ | `marathon.elemental` | Per-element energy baselines via linear regression |
73
+ | `marathon.grain` | Scalable data pipelines with [grain](https://github.com/google/grain) for large datasets |
74
+ | `marathon.extra.edge_to_edge` | Fixed-size neighborhood batching for PET-style edge transformers |
75
+
76
+ Since the library is aimed at active research and is used and adapted as needed, there is no documentation beyond `README.md` files at each module level explaining terminology, notation, and sometimes the idea behind the design of a subpackage. This avoids the risk of documentation and code going out of sync -- at the cost of requiring more code reading. (Luckily, the computers can do some of the reading nowadays...)
77
+
78
+ Anyhow, you are encouraged to fork and adapt `marathon` for your personal experiments. PRs with self-contained and reusable features are welcome.
79
+
80
+ ## Installation
81
+
82
+ The main dependency is `jax`; detailed installation instructions are [here](https://github.com/jax-ml/jax/?tab=readme-ov-file#installation). Typically, the standard install works fairly well:
83
+
84
+ ```bash
85
+ pip install "jax[cuda13]" # or jax[cpu] for CPU-only
86
+ pip install -e .
87
+ ```
88
+
89
+ `marathon` provides a number of extras, installable via `pip install -e ".[all]"`. They are required to run some parts of the code but not automatically installed to avoid dependency resolution hell in HPC systems.
90
+
91
+ ```bash
92
+ pip install -e ".[grain]" # grain pipelines: grain, mmap_ninja, numba
93
+ pip install -e ".[dev]" # development: pytest, ruff
94
+ pip install -e ".[wandb]" # Weights & Biases logging
95
+ pip install -e ".[plot]" # plotting: matplotlib, scipy
96
+ ```
97
+
98
+ For convenience, `marathon` looks for an environment variable named `DATASETS` and turns it into a `Path` at `marathon.data.datasets`. If the variable is not set, it defaults to the current working directory.
99
+
100
+ ## Quick start
101
+
102
+ For datasets that can be fully fit into (GPU) memory (do this ahead of time to fixed size and shuffle on GPU):
103
+
104
+ ```python
105
+ from marathon.data import to_sample, batch_samples, determine_max_sizes
106
+
107
+ samples = [to_sample(atoms, cutoff=5.0) for atoms in my_atoms]
108
+ num_atoms, num_pairs = determine_max_sizes(samples, batch_size=4)
109
+ batch = batch_samples(samples, num_atoms, num_pairs, keys=["energy", "forces"])
110
+ ```
111
+
112
+ For large-scale training with [`grain`](https://github.com/google/grain) pipelines (streaming data from disk through a series of transforms):
113
+
114
+ ```python
115
+ from marathon.grain import DataSource, DataLoader, IndexSampler, ToSample, ToFixedLengthBatch
116
+
117
+ ds = DataSource("path/to/prepared/dataset")
118
+ sampler = IndexSampler(len(ds), shuffle=True, seed=0)
119
+ loader = DataLoader(
120
+ data_source=ds,
121
+ sampler=sampler,
122
+ operations=[ToSample(cutoff=5.0), ToFixedLengthBatch(batch_size=4)],
123
+ )
124
+ ```
125
+
126
+ ## Development
127
+
128
+ ```bash
129
+ pip install -e ".[dev]"
130
+ ruff format . && ruff check --fix .
131
+ python -m pytest
132
+ ```
133
+
134
+ Linting and formatting is done by `ruff`. We use a line length of 92, but it is not enforced by the linter, only by the formatter. This avoids hassle when lines can't be shortened automatically. We also suppress some rules that get in the way of research code: short variable names (`E741`), lambdas (`E731`), and non-top-level imports (`E402`). Import ordering groups `numpy` and `jax` before other third-party packages.
135
+
136
+ The code itself tends towards concise and functional: descriptive names, minimal docstrings (only where behaviour isn't obvious from context), and liberal use of lambdas and comprehensions. Many modules include inline tests at the bottom that run on import.
137
+
138
+ ***
139
+
140
+ Logo designed by [`overripemango`](https://overripe.design).
141
+
@@ -0,0 +1,101 @@
1
+ <p align="center">
2
+ <picture>
3
+ <source media="(prefers-color-scheme: dark)" srcset="https://data.marcel.science/marathon/logo.png">
4
+ <img src="https://data.marcel.science/marathon/logo-dark.png" alt="marathon" width="300">
5
+ </picture>
6
+ </p>
7
+
8
+ <h1 align="center">marathon</h1>
9
+
10
+ <p align="center">
11
+ <em>modular training infrastructure for machine-learning interatomic potentials in JAX</em>
12
+ </p>
13
+
14
+ <p align="center">
15
+ <img alt="status: experimental" src="https://img.shields.io/badge/status-experimental-orange">
16
+ <img alt="code style: black" src="https://img.shields.io/badge/code%20style-black-000000.svg">
17
+ </p>
18
+
19
+ <p align="center">
20
+ <em>pheidippides would be a great name for a message-passing neural network</em>
21
+ </p>
22
+
23
+ ---
24
+
25
+ `marathon` is an experimental `jax/flax`-oriented toolkit for prototyping machine-learning interatomic potentials. It does not provide a finished and polished training loop; instead it provides a few composable parts that can be assembled and adapted as needed for experiments. It's therefore not intended as user-facing production code, instead it aims to make experiments faster and more pleasant.
26
+
27
+ | Module | Description |
28
+ |--------|-------------|
29
+ | `marathon.data` | Process `ase.Atoms` into padded batches with a flexible properties system |
30
+ | `marathon.evaluate` | Predict energy, forces, stress; compute loss (MSE/Huber) and metrics (MAE, RMSE, R2) |
31
+ | `marathon.emit` | Checkpointing, logging (text, W&B), diagnostic plots |
32
+ | `marathon.io` | Read/write `msgpack` and `yaml`; serialize `flax.nn.Module` instances |
33
+ | `marathon.elemental` | Per-element energy baselines via linear regression |
34
+ | `marathon.grain` | Scalable data pipelines with [grain](https://github.com/google/grain) for large datasets |
35
+ | `marathon.extra.edge_to_edge` | Fixed-size neighborhood batching for PET-style edge transformers |
36
+
37
+ Since the library is aimed at active research and is used and adapted as needed, there is no documentation beyond `README.md` files at each module level explaining terminology, notation, and sometimes the idea behind the design of a subpackage. This avoids the risk of documentation and code going out of sync -- at the cost of requiring more code reading. (Luckily, the computers can do some of the reading nowadays...)
38
+
39
+ Anyhow, you are encouraged to fork and adapt `marathon` for your personal experiments. PRs with self-contained and reusable features are welcome.
40
+
41
+ ## Installation
42
+
43
+ The main dependency is `jax`; detailed installation instructions are [here](https://github.com/jax-ml/jax/?tab=readme-ov-file#installation). Typically, the standard install works fairly well:
44
+
45
+ ```bash
46
+ pip install "jax[cuda13]" # or jax[cpu] for CPU-only
47
+ pip install -e .
48
+ ```
49
+
50
+ `marathon` provides a number of extras, installable via `pip install -e ".[all]"`. They are required to run some parts of the code but not automatically installed to avoid dependency resolution hell in HPC systems.
51
+
52
+ ```bash
53
+ pip install -e ".[grain]" # grain pipelines: grain, mmap_ninja, numba
54
+ pip install -e ".[dev]" # development: pytest, ruff
55
+ pip install -e ".[wandb]" # Weights & Biases logging
56
+ pip install -e ".[plot]" # plotting: matplotlib, scipy
57
+ ```
58
+
59
+ For convenience, `marathon` looks for an environment variable named `DATASETS` and turns it into a `Path` at `marathon.data.datasets`. If the variable is not set, it defaults to the current working directory.
60
+
61
+ ## Quick start
62
+
63
+ For datasets that can be fully fit into (GPU) memory (do this ahead of time to fixed size and shuffle on GPU):
64
+
65
+ ```python
66
+ from marathon.data import to_sample, batch_samples, determine_max_sizes
67
+
68
+ samples = [to_sample(atoms, cutoff=5.0) for atoms in my_atoms]
69
+ num_atoms, num_pairs = determine_max_sizes(samples, batch_size=4)
70
+ batch = batch_samples(samples, num_atoms, num_pairs, keys=["energy", "forces"])
71
+ ```
72
+
73
+ For large-scale training with [`grain`](https://github.com/google/grain) pipelines (streaming data from disk through a series of transforms):
74
+
75
+ ```python
76
+ from marathon.grain import DataSource, DataLoader, IndexSampler, ToSample, ToFixedLengthBatch
77
+
78
+ ds = DataSource("path/to/prepared/dataset")
79
+ sampler = IndexSampler(len(ds), shuffle=True, seed=0)
80
+ loader = DataLoader(
81
+ data_source=ds,
82
+ sampler=sampler,
83
+ operations=[ToSample(cutoff=5.0), ToFixedLengthBatch(batch_size=4)],
84
+ )
85
+ ```
86
+
87
+ ## Development
88
+
89
+ ```bash
90
+ pip install -e ".[dev]"
91
+ ruff format . && ruff check --fix .
92
+ python -m pytest
93
+ ```
94
+
95
+ Linting and formatting is done by `ruff`. We use a line length of 92, but it is not enforced by the linter, only by the formatter. This avoids hassle when lines can't be shortened automatically. We also suppress some rules that get in the way of research code: short variable names (`E741`), lambdas (`E731`), and non-top-level imports (`E402`). Import ordering groups `numpy` and `jax` before other third-party packages.
96
+
97
+ The code itself tends towards concise and functional: descriptive names, minimal docstrings (only where behaviour isn't obvious from context), and liberal use of lambdas and comprehensions. Many modules include inline tests at the bottom that run on import.
98
+
99
+ ***
100
+
101
+ Logo designed by [`overripemango`](https://overripe.design).
@@ -1,9 +1,10 @@
1
1
  [tool.poetry]
2
2
  name = "marathon-train"
3
- version = "0.2.0"
3
+ version = "0.2.2"
4
4
  description = "experimental tooling for training machine learning interatomic potentials in jax"
5
5
  authors = ["Marcel Langer <dev@marcel.science>"]
6
6
  license = "MIT"
7
+ readme = "README.md"
7
8
  packages = [{include = "marathon"}]
8
9
 
9
10
  [tool.poetry.dependencies]
@@ -1,37 +0,0 @@
1
- Metadata-Version: 2.4
2
- Name: marathon-train
3
- Version: 0.2.0
4
- Summary: experimental tooling for training machine learning interatomic potentials in jax
5
- License: MIT
6
- License-File: LICENSE
7
- Author: Marcel Langer
8
- Author-email: dev@marcel.science
9
- Requires-Python: >=3.7
10
- Classifier: License :: OSI Approved :: MIT License
11
- Classifier: Programming Language :: Python :: 3
12
- Classifier: Programming Language :: Python :: 3.7
13
- Classifier: Programming Language :: Python :: 3.8
14
- Classifier: Programming Language :: Python :: 3.9
15
- Classifier: Programming Language :: Python :: 3.10
16
- Classifier: Programming Language :: Python :: 3.11
17
- Classifier: Programming Language :: Python :: 3.12
18
- Classifier: Programming Language :: Python :: 3.13
19
- Classifier: Programming Language :: Python :: 3.14
20
- Provides-Extra: all
21
- Provides-Extra: dev
22
- Provides-Extra: grain
23
- Provides-Extra: plot
24
- Provides-Extra: wandb
25
- Requires-Dist: PyYAML
26
- Requires-Dist: ase
27
- Requires-Dist: flax
28
- Requires-Dist: grain ; extra == "all" or extra == "grain"
29
- Requires-Dist: matplotlib ; extra == "all" or extra == "plot"
30
- Requires-Dist: mmap_ninja ; extra == "all" or extra == "grain"
31
- Requires-Dist: numba ; extra == "all" or extra == "grain"
32
- Requires-Dist: opsis
33
- Requires-Dist: pytest ; extra == "all" or extra == "dev"
34
- Requires-Dist: ruff ; extra == "all" or extra == "dev"
35
- Requires-Dist: scipy ; extra == "all" or extra == "grain"
36
- Requires-Dist: vesin (>=0.3.2)
37
- Requires-Dist: wandb ; extra == "all" or extra == "wandb"
File without changes