reax 0.6.14.dev1__tar.gz → 0.7.0.dev1__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 (99) hide show
  1. {reax-0.6.14.dev1 → reax-0.7.0.dev1}/PKG-INFO +3 -2
  2. {reax-0.6.14.dev1 → reax-0.7.0.dev1}/pyproject.toml +49 -28
  3. {reax-0.6.14.dev1 → reax-0.7.0.dev1}/src/reax/__init__.py +1 -1
  4. {reax-0.6.14.dev1 → reax-0.7.0.dev1}/src/reax/_engine.py +2 -3
  5. {reax-0.6.14.dev1 → reax-0.7.0.dev1}/src/reax/data/__init__.py +6 -2
  6. reax-0.7.0.dev1/src/reax/data/_datasource_manager.py +180 -0
  7. {reax-0.6.14.dev1 → reax-0.7.0.dev1}/src/reax/data/_datasources.py +20 -6
  8. {reax-0.6.14.dev1 → reax-0.7.0.dev1}/src/reax/data/_loaders.py +4 -2
  9. {reax-0.6.14.dev1 → reax-0.7.0.dev1}/src/reax/data/collate.py +4 -2
  10. {reax-0.6.14.dev1 → reax-0.7.0.dev1}/src/reax/data/datamodules.py +15 -11
  11. {reax-0.6.14.dev1 → reax-0.7.0.dev1}/src/reax/data/datasets.py +3 -2
  12. {reax-0.6.14.dev1 → reax-0.7.0.dev1}/src/reax/data/fetchers.py +33 -12
  13. {reax-0.6.14.dev1 → reax-0.7.0.dev1}/src/reax/data/samplers.py +73 -101
  14. {reax-0.6.14.dev1 → reax-0.7.0.dev1}/src/reax/demos/boring_classes.py +5 -5
  15. {reax-0.6.14.dev1 → reax-0.7.0.dev1}/src/reax/demos/mnist.py +21 -20
  16. {reax-0.6.14.dev1 → reax-0.7.0.dev1}/src/reax/listeners/early_stopping.py +2 -2
  17. {reax-0.6.14.dev1 → reax-0.7.0.dev1}/src/reax/listeners/model_checkpoint.py +28 -8
  18. {reax-0.6.14.dev1 → reax-0.7.0.dev1}/src/reax/listeners/progress/progress_bar.py +2 -3
  19. {reax-0.6.14.dev1 → reax-0.7.0.dev1}/src/reax/listeners/progress/rich_progress.py +2 -2
  20. {reax-0.6.14.dev1 → reax-0.7.0.dev1}/src/reax/loggers/csv_logs.py +2 -2
  21. {reax-0.6.14.dev1 → reax-0.7.0.dev1}/src/reax/loggers/logger.py +4 -3
  22. {reax-0.6.14.dev1 → reax-0.7.0.dev1}/src/reax/loggers/pandas.py +3 -3
  23. {reax-0.6.14.dev1 → reax-0.7.0.dev1}/src/reax/loggers/tensorboard.py +2 -2
  24. {reax-0.6.14.dev1 → reax-0.7.0.dev1}/src/reax/metrics/_classification.py +32 -37
  25. {reax-0.6.14.dev1 → reax-0.7.0.dev1}/src/reax/metrics/_metric.py +3 -3
  26. {reax-0.6.14.dev1 → reax-0.7.0.dev1}/src/reax/metrics/aggregation.py +8 -2
  27. {reax-0.6.14.dev1 → reax-0.7.0.dev1}/src/reax/metrics/collections.py +2 -2
  28. {reax-0.6.14.dev1 → reax-0.7.0.dev1}/src/reax/metrics/jm/types.py +3 -3
  29. {reax-0.6.14.dev1 → reax-0.7.0.dev1}/src/reax/metrics/jm/utils.py +1 -1
  30. {reax-0.6.14.dev1 → reax-0.7.0.dev1}/src/reax/metrics/regression.py +1 -1
  31. {reax-0.6.14.dev1 → reax-0.7.0.dev1}/src/reax/metrics/utils.py +44 -48
  32. {reax-0.6.14.dev1 → reax-0.7.0.dev1}/src/reax/modules.py +17 -1
  33. {reax-0.6.14.dev1 → reax-0.7.0.dev1}/src/reax/plugins.py +1 -1
  34. {reax-0.6.14.dev1 → reax-0.7.0.dev1}/src/reax/results.py +1 -1
  35. {reax-0.6.14.dev1 → reax-0.7.0.dev1}/src/reax/saving.py +2 -1
  36. {reax-0.6.14.dev1 → reax-0.7.0.dev1}/src/reax/stages/_timer.py +2 -2
  37. {reax-0.6.14.dev1 → reax-0.7.0.dev1}/src/reax/stages/common.py +9 -18
  38. {reax-0.6.14.dev1 → reax-0.7.0.dev1}/src/reax/stages/fit.py +6 -4
  39. {reax-0.6.14.dev1 → reax-0.7.0.dev1}/src/reax/stages/predict.py +1 -1
  40. {reax-0.6.14.dev1 → reax-0.7.0.dev1}/src/reax/stages/stages.py +18 -10
  41. {reax-0.6.14.dev1 → reax-0.7.0.dev1}/src/reax/stages/test.py +2 -2
  42. {reax-0.6.14.dev1 → reax-0.7.0.dev1}/src/reax/stages/train.py +1 -1
  43. {reax-0.6.14.dev1 → reax-0.7.0.dev1}/src/reax/stages/validation.py +2 -2
  44. reax-0.7.0.dev1/src/reax/strategies/__init__.py +8 -0
  45. {reax-0.6.14.dev1 → reax-0.7.0.dev1}/src/reax/strategies/_jax.py +10 -10
  46. {reax-0.6.14.dev1 → reax-0.7.0.dev1}/src/reax/strategies/_parallel.py +9 -14
  47. {reax-0.6.14.dev1 → reax-0.7.0.dev1}/src/reax/strategies/_strategies.py +3 -5
  48. {reax-0.6.14.dev1 → reax-0.7.0.dev1}/src/reax/strategies/_utils.py +1 -1
  49. {reax-0.6.14.dev1 → reax-0.7.0.dev1}/src/reax/testing.py +0 -2
  50. {reax-0.6.14.dev1 → reax-0.7.0.dev1}/src/reax/training/trainer.py +22 -27
  51. {reax-0.6.14.dev1 → reax-0.7.0.dev1}/src/reax/utils/containers.py +3 -3
  52. {reax-0.6.14.dev1 → reax-0.7.0.dev1}/src/reax/utils/events.py +5 -1
  53. reax-0.6.14.dev1/src/reax/data/_datasource_manager.py +0 -130
  54. reax-0.6.14.dev1/src/reax/strategies/__init__.py +0 -7
  55. {reax-0.6.14.dev1 → reax-0.7.0.dev1}/LICENSE.txt +0 -0
  56. {reax-0.6.14.dev1 → reax-0.7.0.dev1}/README.rst +0 -0
  57. {reax-0.6.14.dev1 → reax-0.7.0.dev1}/src/reax/_module_hooks.py +0 -0
  58. {reax-0.6.14.dev1 → reax-0.7.0.dev1}/src/reax/data/_types.py +0 -0
  59. {reax-0.6.14.dev1 → reax-0.7.0.dev1}/src/reax/data/dataloaders.py +0 -0
  60. {reax-0.6.14.dev1 → reax-0.7.0.dev1}/src/reax/data/kfold.py +0 -0
  61. {reax-0.6.14.dev1 → reax-0.7.0.dev1}/src/reax/data/utils.py +0 -0
  62. {reax-0.6.14.dev1 → reax-0.7.0.dev1}/src/reax/demos/__init__.py +0 -0
  63. {reax-0.6.14.dev1 → reax-0.7.0.dev1}/src/reax/exceptions.py +0 -0
  64. {reax-0.6.14.dev1 → reax-0.7.0.dev1}/src/reax/hooks.py +0 -0
  65. {reax-0.6.14.dev1 → reax-0.7.0.dev1}/src/reax/keys.py +0 -0
  66. {reax-0.6.14.dev1 → reax-0.7.0.dev1}/src/reax/lightning/LICENSE +0 -0
  67. {reax-0.6.14.dev1 → reax-0.7.0.dev1}/src/reax/lightning/__init__.py +0 -0
  68. {reax-0.6.14.dev1 → reax-0.7.0.dev1}/src/reax/lightning/rank_zero.py +0 -0
  69. {reax-0.6.14.dev1 → reax-0.7.0.dev1}/src/reax/listeners/__init__.py +0 -0
  70. {reax-0.6.14.dev1 → reax-0.7.0.dev1}/src/reax/listeners/checkpointer.py +0 -0
  71. {reax-0.6.14.dev1 → reax-0.7.0.dev1}/src/reax/listeners/progress/__init__.py +0 -0
  72. {reax-0.6.14.dev1 → reax-0.7.0.dev1}/src/reax/listeners/progress/tqdm_progress.py +1 -1
  73. {reax-0.6.14.dev1 → reax-0.7.0.dev1}/src/reax/listeners/utils.py +0 -0
  74. {reax-0.6.14.dev1 → reax-0.7.0.dev1}/src/reax/loggers/__init__.py +0 -0
  75. {reax-0.6.14.dev1 → reax-0.7.0.dev1}/src/reax/loggers/_utils.py +0 -0
  76. {reax-0.6.14.dev1 → reax-0.7.0.dev1}/src/reax/loggers/mlflow.py +0 -0
  77. {reax-0.6.14.dev1 → reax-0.7.0.dev1}/src/reax/metrics/__init__.py +0 -0
  78. {reax-0.6.14.dev1 → reax-0.7.0.dev1}/src/reax/metrics/_evaluators.py +0 -0
  79. {reax-0.6.14.dev1 → reax-0.7.0.dev1}/src/reax/metrics/_globals.py +0 -0
  80. {reax-0.6.14.dev1 → reax-0.7.0.dev1}/src/reax/metrics/_registry.py +2 -2
  81. {reax-0.6.14.dev1 → reax-0.7.0.dev1}/src/reax/metrics/jm/__init__.py +0 -0
  82. {reax-0.6.14.dev1 → reax-0.7.0.dev1}/src/reax/optimizers.py +0 -0
  83. {reax-0.6.14.dev1 → reax-0.7.0.dev1}/src/reax/profilers/__init__.py +0 -0
  84. {reax-0.6.14.dev1 → reax-0.7.0.dev1}/src/reax/profilers/jax_profiler.py +0 -0
  85. {reax-0.6.14.dev1 → reax-0.7.0.dev1}/src/reax/profilers/profiler.py +0 -0
  86. {reax-0.6.14.dev1 → reax-0.7.0.dev1}/src/reax/random.py +0 -0
  87. {reax-0.6.14.dev1 → reax-0.7.0.dev1}/src/reax/stages/__init__.py +0 -0
  88. {reax-0.6.14.dev1 → reax-0.7.0.dev1}/src/reax/stages/stats.py +0 -0
  89. {reax-0.6.14.dev1 → reax-0.7.0.dev1}/src/reax/strategies/_factory.py +0 -0
  90. {reax-0.6.14.dev1 → reax-0.7.0.dev1}/src/reax/strategies/_single_device.py +0 -0
  91. {reax-0.6.14.dev1 → reax-0.7.0.dev1}/src/reax/training/__init__.py +0 -0
  92. {reax-0.6.14.dev1 → reax-0.7.0.dev1}/src/reax/training/_checkpoint_connector.py +0 -0
  93. {reax-0.6.14.dev1 → reax-0.7.0.dev1}/src/reax/training/_checkpointing.py +0 -0
  94. {reax-0.6.14.dev1 → reax-0.7.0.dev1}/src/reax/training/_deprecated.py +0 -0
  95. {reax-0.6.14.dev1 → reax-0.7.0.dev1}/src/reax/training/_logger_connector.py +0 -0
  96. {reax-0.6.14.dev1 → reax-0.7.0.dev1}/src/reax/types.py +0 -0
  97. {reax-0.6.14.dev1 → reax-0.7.0.dev1}/src/reax/utils/__init__.py +0 -0
  98. {reax-0.6.14.dev1 → reax-0.7.0.dev1}/src/reax/utils/arrays.py +0 -0
  99. {reax-0.6.14.dev1 → reax-0.7.0.dev1}/src/reax/utils/grads.py +0 -0
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.4
2
2
  Name: reax
3
- Version: 0.6.14.dev1
3
+ Version: 0.7.0.dev1
4
4
  Summary: REAX: A simple training framework for JAX-based projects
5
5
  Keywords: machine learning,jax,research
6
6
  Author-email: Martin Uhrin <martin.uhrin.10@ucl.ac.uk>
@@ -30,7 +30,6 @@ Requires-Dist: stevedore
30
30
  Requires-Dist: tensorboardX
31
31
  Requires-Dist: tqdm
32
32
  Requires-Dist: typing-extensions
33
- Requires-Dist: black ; extra == "dev"
34
33
  Requires-Dist: cloudpickle ; extra == "dev"
35
34
  Requires-Dist: flit ; extra == "dev"
36
35
  Requires-Dist: ipython ; extra == "dev"
@@ -39,8 +38,10 @@ Requires-Dist: pandas ; extra == "dev"
39
38
  Requires-Dist: pytest ; extra == "dev"
40
39
  Requires-Dist: pytest-cov ; extra == "dev"
41
40
  Requires-Dist: pytest-env ; extra == "dev"
41
+ Requires-Dist: pytest-timeout ; extra == "dev"
42
42
  Requires-Dist: pre-commit ; extra == "dev"
43
43
  Requires-Dist: pylint ; extra == "dev"
44
+ Requires-Dist: ruff ; extra == "dev"
44
45
  Requires-Dist: docutils ; extra == "docs"
45
46
  Requires-Dist: jupyter ; extra == "docs"
46
47
  Requires-Dist: myst-nb ; extra == "docs"
@@ -56,7 +56,6 @@ docs = [
56
56
  'sphinx-autobuild',
57
57
  ]
58
58
  dev = [
59
- 'black',
60
59
  'cloudpickle',
61
60
  'flit',
62
61
  'ipython',
@@ -65,8 +64,10 @@ dev = [
65
64
  'pytest',
66
65
  'pytest-cov',
67
66
  'pytest-env',
67
+ 'pytest-timeout',
68
68
  'pre-commit',
69
69
  'pylint',
70
+ 'ruff',
70
71
  ]
71
72
  examples = [
72
73
  "lightning",
@@ -96,16 +97,48 @@ mse = "reax.metrics:MeanSquaredError"
96
97
  rmse = "reax.metrics:RootMeanSquareError"
97
98
  mae = "reax.metrics:MeanAbsoluteError"
98
99
 
99
- [tool.flynt]
100
+ [tool.ruff]
100
101
  line-length = 100
101
- fail-on-change = true
102
+ target-version = "py310"
103
+ exclude = [
104
+ 'migrations',
105
+ ]
106
+
107
+ [tool.ruff.lint]
108
+ select = [
109
+ 'B',
110
+ 'B9',
111
+ 'C90',
112
+ 'E',
113
+ 'F',
114
+ 'I',
115
+ 'S',
116
+ 'UP',
117
+ 'W',
118
+ ]
119
+ ignore = [
120
+ 'E203',
121
+ 'E266',
122
+ 'E501',
123
+ 'F401',
124
+ 'F403',
125
+ 'F722',
126
+ 'F821',
127
+ 'S101',
128
+ 'S603',
129
+ 'S607',
130
+ ]
131
+
132
+ [tool.ruff.lint.isort]
133
+ force-sort-within-sections = true
134
+
135
+ [tool.ruff.lint.mccabe]
136
+ max-complexity = 18
102
137
 
103
- [tool.isort]
104
- profile = "black"
105
- force_sort_within_sections = true
106
- include_trailing_comma = true
107
- line_length = 100
108
- multi_line_output = 3
138
+ [tool.ruff.lint.per-file-ignores]
139
+ 'src/reax/lightning/*.py' = [
140
+ 'C90',
141
+ ]
109
142
 
110
143
  [tool.pylint.MASTER]
111
144
  ignore-paths = '^src/reax/lightning/.*$' # These are copy-paste from lightning, so don't lint
@@ -136,15 +169,6 @@ max-returns = 8
136
169
  max-positional-arguments = 10
137
170
  max-public-methods = 22
138
171
 
139
- [tool.bandit]
140
- skips = [
141
- "B101",
142
- "B404" # This warns on import of subprocess
143
- ]
144
-
145
- [tool.black]
146
- line-length = 100
147
-
148
172
  [tool.doc8]
149
173
  max-line-length = 100
150
174
 
@@ -158,26 +182,23 @@ log_cli_level = "DEBUG"
158
182
 
159
183
  [tool.pytest_env]
160
184
  XLA_PYTHON_CLIENT_PREALLOCATE = false # Don't allow JAX to preallocate memory
185
+ JAX_PLATFORMS = "cpu" # Force tests to run on the CPU
161
186
 
162
187
  [tool.pytest.ini_options]
163
188
  minversion = '6.0'
164
189
  testpaths = [
165
- 'test',
190
+ 'tests',
166
191
  ]
167
192
  filterwarnings = [
168
193
  'ignore::DeprecationWarning:frozendict:',
169
194
  ]
195
+ markers = [
196
+ 'multiproc: tests that spawn multiple JAX DDP subprocesses',
197
+ ]
198
+ timeout = 600
199
+ timeout_method = 'thread'
170
200
  #addopts = "--jaxtyping-packages=reax,beartype.beartype"
171
201
 
172
- [tool.yapf]
173
- align_closing_bracket_with_visual_indent = true
174
- based_on_style = 'google'
175
- coalesce_brackets = true
176
- column_limit = 100
177
- dedent_closing_brackets = true
178
- indent_dictionary_value = false
179
- split_arguments_when_comma_terminated = true
180
-
181
202
  [tool.tox]
182
203
  legacy_tox_ini = """
183
204
  [tox]
@@ -68,4 +68,4 @@ __all__ = (
68
68
  )
69
69
  )
70
70
 
71
- __version__ = "0.6.14.dev1"
71
+ __version__ = "0.7.0.dev1"
@@ -12,10 +12,9 @@ import jax
12
12
  import jaxtyping as jt
13
13
 
14
14
  from . import data as data_
15
- from . import hooks
15
+ from . import hooks, modules, optimizers, profilers, strategies
16
16
  from . import loggers as loggers_
17
17
  from . import metrics as metrics_
18
- from . import modules, optimizers, profilers, strategies
19
18
  from .data import DeviceDataLoader
20
19
  from .training import _logger_connector
21
20
  from .utils import events
@@ -61,7 +60,7 @@ class Engine:
61
60
  logger: "reax.Logger | Iterable[reax.Logger] | bool | None" = True,
62
61
  listeners: "list[reax.TrainerListener] | reax.TrainerListener | None" = None,
63
62
  deterministic: bool = False,
64
- rngs: nnx.Rngs = None,
63
+ rngs: nnx.Rngs | None = None,
65
64
  default_root_dir: "reax.types.Path | None" = None,
66
65
  profiler: "reax.Profiler | str | None" = None,
67
66
  metric_evaluator: "reax.MetricEvaluator | None" = None,
@@ -6,6 +6,7 @@ from . import (
6
6
  dataloaders,
7
7
  datamodules,
8
8
  datasets,
9
+ fetchers,
9
10
  kfold,
10
11
  samplers,
11
12
  utils,
@@ -23,7 +24,7 @@ from .utils import *
23
24
 
24
25
  __all__ = (
25
26
  _datasources.__all__
26
- + _datasource_manager.___all__
27
+ + _datasource_manager.__all__
27
28
  + datasets.__all__
28
29
  + dataloaders.__all__
29
30
  + datamodules.__all__
@@ -32,5 +33,8 @@ __all__ = (
32
33
  + _types.__all__
33
34
  + utils.__all__
34
35
  + kfold.__all__
35
- + ("samplers",)
36
+ + (
37
+ "fetchers",
38
+ "samplers",
39
+ )
36
40
  )
@@ -0,0 +1,180 @@
1
+ import abc
2
+ from typing import TYPE_CHECKING
3
+
4
+ from lightning_utilities.core import overrides
5
+
6
+ from .. import modules
7
+ from . import _datasources, datamodules
8
+
9
+ if TYPE_CHECKING:
10
+ import reax
11
+
12
+
13
+ __all__ = ("DataSourceManager", "create_manager")
14
+
15
+
16
+ class DataSourceManager(abc.ABC): # noqa: B024
17
+ """Coordinator that fronts a :class:`~reax.data.DataSource` (a :class:`~reax.DataModule` or
18
+ :class:`~reax.Module`) and hands out ready-to-use dataloaders.
19
+
20
+ The manager is bound to a :class:`reax.Engine` once at construction time. It is responsible
21
+ for running the source's lifecycle hooks (:meth:`prepare_data`, :meth:`setup`,
22
+ :meth:`teardown`, :meth:`on_exception`) and for wrapping any dataloaders returned by the
23
+ source with the engine's device/distributed logic via
24
+ :meth:`~reax.Engine.setup_dataloaders`.
25
+
26
+ Attributes:
27
+ source: The wrapped :class:`~reax.data.DataSource` (or ``None`` if the manager was
28
+ created with pre-supplied loaders only).
29
+ """
30
+
31
+ def __init__(
32
+ self,
33
+ source: _datasources.DataSource | None,
34
+ engine: "reax.Engine",
35
+ **loaders: "reax.data.DataLoader",
36
+ ) -> None:
37
+ """Create a manager.
38
+
39
+ Args:
40
+ source: A :class:`~reax.DataModule` or :class:`~reax.Module` providing the dataloaders
41
+ and lifecycle hooks, or ``None`` if dataloaders are passed directly.
42
+ engine: The :class:`reax.Engine` to use for device placement and distributed setup.
43
+ Bound once here and reused for every :meth:`setup`/:meth:`teardown` call.
44
+ **loaders: Optional pre-supplied dataloaders keyed by stage name (e.g.
45
+ ``train=..., val=...``). These bypass the source and are wrapped directly.
46
+ """
47
+ self._datasource: _datasources.DataSource | None = source
48
+ self._engine = engine
49
+ self._loaders: dict[str, reax.data.DataLoader] = {
50
+ name: self._setup_dataloader(loaders) for name, loaders in loaders.items()
51
+ }
52
+ self._from_datasource: dict[str, reax.data.DataLoader] = {}
53
+
54
+ @property
55
+ def _source_base_type(
56
+ self,
57
+ ) -> "type[reax.DataModule] | type[reax.Module]":
58
+ if isinstance(self._datasource, datamodules.DataModule):
59
+ return datamodules.DataModule
60
+ if isinstance(self._datasource, modules.Module):
61
+ return modules.Module
62
+
63
+ raise RuntimeError("expected datasource to be a DataModule or Module")
64
+
65
+ def has_dataloader(self, name: str) -> bool:
66
+ """Returns `True` if this source provides the name dataloader, `False` otherwise"""
67
+ if name in self._loaders:
68
+ return True
69
+
70
+ if name in self._from_datasource:
71
+ return True
72
+
73
+ return overrides.is_overridden(
74
+ f"{name}_dataloader", self._datasource, self._source_base_type
75
+ )
76
+
77
+ def get_dataloader(self, name: str) -> "reax.data.DataLoader":
78
+ """Get the dataloader of the given name"""
79
+ try:
80
+ return self._loaders[name]
81
+ except KeyError:
82
+ pass
83
+
84
+ try:
85
+ return self._from_datasource[name]
86
+ except KeyError:
87
+ pass
88
+
89
+ loader = self._request_dataloader(name)
90
+ self._from_datasource[name] = loader
91
+ return loader
92
+
93
+ @property
94
+ def source(self) -> "reax.data.DataSource | None":
95
+ """The original source of the dataloader (if there is one)"""
96
+ return self._datasource
97
+
98
+ def prepare_data(self) -> None:
99
+ """Tell the data source to prepare the data for use"""
100
+ if self._datasource is not None and overrides.is_overridden(
101
+ "prepare_data", self._datasource, self._source_base_type
102
+ ):
103
+ self._datasource.prepare_data()
104
+
105
+ def setup(self, /, *, stage: str | None = None) -> None:
106
+ """Call ``setup`` on the wrapped source.
107
+
108
+ The :class:`reax.Engine` bound at construction is forwarded to the source.
109
+
110
+ Args:
111
+ stage: Name of the stage being set up (e.g. ``"fit"``, ``"validate"``, ``"test"``).
112
+ """
113
+ if self._datasource is None:
114
+ return
115
+ self._datasource.setup(self._engine, stage=stage)
116
+
117
+ def on_exception(self, exception: BaseException) -> None:
118
+ """Tell the data source that an exception has occurred"""
119
+
120
+ if self._datasource is not None:
121
+ self._datasource.on_exception(exception)
122
+
123
+ def teardown(self, /, *, stage: str | None = None) -> None:
124
+ """Call ``teardown`` on the wrapped source.
125
+
126
+ Args:
127
+ stage: Name of the stage being torn down (e.g. ``"fit"``, ``"validate"``, ``"test"``).
128
+ """
129
+ if self._datasource is None:
130
+ return
131
+ self._datasource.teardown(self._engine, stage=stage)
132
+
133
+ def reset(self):
134
+ """Reset the cache so dataloaders get reloaded"""
135
+ self._from_datasource = {}
136
+
137
+ def _request_dataloader(self, name: str) -> "reax.DataLoader":
138
+ """Get the dataloader directly from the source"""
139
+ loader_name = f"{name}_dataloader"
140
+ loader = getattr(self._datasource, loader_name)()
141
+ loader = self._setup_dataloader(loader)
142
+ return loader
143
+
144
+ def _setup_dataloader(self, loader: "reax.DataLoader") -> "reax.DataLoader":
145
+ """Wrap a dataloader with the bound engine's device/distributed logic."""
146
+ return self._engine.setup_dataloaders(loader)
147
+
148
+
149
+ def create_manager(
150
+ engine: "reax.Engine",
151
+ module: _datasources.DataSource | None = None,
152
+ datamodule: datamodules.DataModule | None = None,
153
+ **loaders,
154
+ ) -> DataSourceManager:
155
+ """Create a :class:`DataSourceManager` for a source and engine.
156
+
157
+ Args:
158
+ engine: The :class:`reax.Engine` to bind to the manager for device placement.
159
+ Required — the manager will call ``engine.setup_dataloaders`` for every
160
+ dataloader it hands out.
161
+ module: Optional :class:`~reax.Module` to source dataloaders from.
162
+ datamodule: Optional :class:`~reax.DataModule` to source dataloaders from.
163
+ Takes priority over ``module`` if both are provided.
164
+ **loaders: Pre-supplied dataloaders keyed by name (e.g. ``train=dl``) that
165
+ bypass the source and are wrapped directly by the engine.
166
+
167
+ Returns:
168
+ A :class:`DataSourceManager` ready to be used with the :class:`reax.Trainer`.
169
+ """
170
+ # Filter out any loaders that are `None` as this makes calling this method easier
171
+ passed_loaders = {name: loader for name, loader in loaders.items() if loader is not None}
172
+
173
+ if datamodule is not None:
174
+ source = datamodule
175
+ elif module is not None:
176
+ source = module
177
+ else:
178
+ source = None
179
+
180
+ return DataSourceManager(source, engine, **passed_loaders)
@@ -78,7 +78,7 @@ class DataSource(Generic[_T_co, U]):
78
78
 
79
79
  model.prepare_data()
80
80
  initialize_distributed()
81
- model.setup(stage)
81
+ model.setup(engine, stage="fit")
82
82
  model.train_dataloader()
83
83
  model.val_dataloader()
84
84
  model.test_dataloader()
@@ -86,15 +86,23 @@ class DataSource(Generic[_T_co, U]):
86
86
 
87
87
  """
88
88
 
89
- def setup(self, stage: "reax.Stage", /) -> None:
89
+ def setup(self, engine: "reax.Engine", /, *, stage: str | None = None) -> None:
90
90
  """Called at the beginning of a trainer stage. This is a good hook when you need to
91
91
  build models dynamically or adjust something about them. This hook is called on every
92
92
  process when using DDP.
93
93
 
94
+ Args:
95
+ engine: The :class:`reax.Engine` providing device, RNG and distributed primitives.
96
+ Use ``engine.rngs`` for reproducible splits or ``engine.default_device()`` for
97
+ device placement.
98
+ stage: Optional name of the stage being set up (e.g. ``"fit"``, ``"validate"``,
99
+ ``"test"``, ``"predict"``).
100
+
94
101
  Example::
95
102
 
96
- class LitModel(...):
103
+ class MyDataModule(reax.DataModule):
97
104
  def __init__(self):
105
+ super().__init__()
98
106
  self.l1 = None
99
107
 
100
108
  def prepare_data(self):
@@ -104,14 +112,20 @@ class DataSource(Generic[_T_co, U]):
104
112
  # don't do this
105
113
  self.something = else
106
114
 
107
- def setup(self, stage):
115
+ def setup(self, engine, *, stage):
108
116
  data = load_data(...)
109
117
  self.l1 = nn.Linear(28, data.num_classes)
110
118
 
111
119
  """
112
120
 
113
- def teardown(self, stage: "reax.Stage", /) -> None:
114
- """Called at the end of a trainer stage"""
121
+ def teardown(self, engine: "reax.Engine", /, *, stage: str | None = None) -> None:
122
+ """Called at the end of a trainer stage. Use this to free resources, delete temporary
123
+ files, or otherwise clean up any state created in :meth:`setup`.
124
+
125
+ Args:
126
+ engine: The :class:`reax.Engine` that was passed to :meth:`setup`.
127
+ stage: Optional name of the stage being torn down.
128
+ """
115
129
 
116
130
  def on_exception(self, exception: BaseException, /) -> None:
117
131
  """Called when the stage execution is interrupted by an exception."""
@@ -1,5 +1,5 @@
1
1
  from collections.abc import Iterable, Iterator
2
- from typing import TYPE_CHECKING, Final, Optional, TypeVar
2
+ from typing import TYPE_CHECKING, Final, TypeVar
3
3
 
4
4
  import beartype
5
5
  import jax
@@ -62,6 +62,8 @@ class FetcherDataLoader(_types.DataLoader[_T_co, _U]):
62
62
  fetcher = fetchers.create_fetcher(self._dataset, collate_fn=self._collate_fn)
63
63
  try:
64
64
  for indices in self.sampler:
65
+ if not indices:
66
+ continue
65
67
  yield fetcher.fetch(indices)
66
68
  except StopIteration:
67
69
  pass
@@ -105,7 +107,7 @@ class ArrayLoader(_types.DataLoader[ArrayOrArrayTuple, ArrayOrArrayTuple]):
105
107
  arrays: ArrayOrArrayTuple,
106
108
  batch_size: int = 1,
107
109
  shuffle=False,
108
- sampler: "Optional[reax.data.Sampler]" = None,
110
+ sampler: "reax.data.Sampler | None" = None,
109
111
  ):
110
112
  # Params
111
113
  self._batch_size: int = batch_size
@@ -62,7 +62,7 @@ class Collator:
62
62
  # or `__init__(iterable)`.
63
63
  return {key: self.collate([d[key] for d in batch]) for key in elem}
64
64
  elif isinstance(elem, tuple) and hasattr(elem, "_fields"): # namedtuple
65
- return elem_type(*(self.collate(samples) for samples in zip(*batch)))
65
+ return elem_type(*(self.collate(samples) for samples in zip(*batch, strict=False)))
66
66
  elif isinstance(elem, Sequence):
67
67
  # check to make sure that the elements in batch have consistent size
68
68
  it = iter(batch)
@@ -70,7 +70,9 @@ class Collator:
70
70
  if not all(len(elem) == elem_size for elem in it):
71
71
  raise RuntimeError("each element in list of batch should be of equal size")
72
72
  # else:
73
- transposed = list(zip(*batch)) # It may be accessed twice, so we use a list.
73
+ transposed = list(
74
+ zip(*batch, strict=False)
75
+ ) # It may be accessed twice, so we use a list.
74
76
 
75
77
  if isinstance(elem, tuple):
76
78
  return [self.collate(samples) for samples in transposed] # Backwards compatibility.
@@ -1,7 +1,6 @@
1
1
  from collections.abc import Iterable
2
2
  from typing import TYPE_CHECKING, Any, Generic, TypeVar
3
3
 
4
- from flax import nnx
5
4
  from typing_extensions import override
6
5
 
7
6
  from . import _datasources, _loaders
@@ -18,17 +17,14 @@ U = TypeVar("U")
18
17
 
19
18
 
20
19
  class DataModule(Generic[_T_co, U], _datasources.DataSource[_T_co, U]):
21
- def __init__(self):
22
- super().__init__()
23
- self._rngs = nnx.Rngs(0)
20
+ """Encapsulates all data-related logic: downloading, splitting, and batch construction.
24
21
 
25
- @property
26
- def rngs(self) -> nnx.Rngs:
27
- return self._rngs
22
+ A :class:`DataModule` is the primary interface for providing data to a
23
+ :class:`reax.Module` via the :class:`reax.Trainer`.
28
24
 
29
- @rngs.setter
30
- def rngs(self, rngs: nnx.Rngs):
31
- self._rngs = rngs
25
+ Attributes:
26
+ rngs: The :class:`flax.nnx.Rngs` shared with the engine for reproducible splits.
27
+ """
32
28
 
33
29
  @classmethod
34
30
  def from_datasets(
@@ -40,7 +36,15 @@ class DataModule(Generic[_T_co, U], _datasources.DataSource[_T_co, U]):
40
36
  *,
41
37
  batch_size: int = 1,
42
38
  ) -> "DataModule[_T_co, U]":
43
- """From datasets."""
39
+ """Create a :class:`FromDatasets` data module from in-memory datasets.
40
+
41
+ Args:
42
+ train_dataset: Training data (array, ``array.array``, or list of them).
43
+ val_dataset: Validation data.
44
+ test_dataset: Test data.
45
+ predict_dataset: Prediction data.
46
+ batch_size: Global batch size.
47
+ """
44
48
  return FromDatasets(
45
49
  train_dataset, val_dataset, test_dataset, predict_dataset, batch_size=batch_size
46
50
  )
@@ -178,7 +178,8 @@ def random_split(
178
178
  for i, length in enumerate(lengths):
179
179
  if length == 0:
180
180
  warnings.warn(
181
- f"Length of split at index {i} is 0. " f"This might result in an empty dataset."
181
+ f"Length of split at index {i} is 0. This might result in an empty dataset.",
182
+ stacklevel=2,
182
183
  )
183
184
 
184
185
  # Cannot verify that dataset is Sized
@@ -189,7 +190,7 @@ def random_split(
189
190
  lengths = cast(Sequence[int], lengths)
190
191
  return [
191
192
  Subset(dataset, indices[offset - length : offset])
192
- for offset, length in zip(itertools.accumulate(lengths), lengths)
193
+ for offset, length in zip(itertools.accumulate(lengths), lengths, strict=False)
193
194
  ]
194
195
 
195
196
 
@@ -4,6 +4,8 @@ import contextlib
4
4
  import functools
5
5
  from typing import Generic, TypeVar
6
6
 
7
+ import jax
8
+
7
9
  from . import _types
8
10
 
9
11
  _T_co = TypeVar("_T_co", covariant=True)
@@ -11,7 +13,7 @@ _U = TypeVar("_U")
11
13
  CollateFn = Callable[[Sequence[_T_co]], _U]
12
14
 
13
15
 
14
- class _BaseFetcher(Generic[_T_co, _U]):
16
+ class BaseFetcher(Generic[_T_co, _U]):
15
17
  def __init__(self, dataset: _types.Dataset[_T_co], collate_fn: CollateFn):
16
18
  """Init function."""
17
19
  self._dataset = dataset
@@ -22,7 +24,7 @@ class _BaseFetcher(Generic[_T_co, _U]):
22
24
  """Fetch the batch."""
23
25
 
24
26
 
25
- class _IterableFetcher(_BaseFetcher, Generic[_T_co, _U]):
27
+ class _IterableFetcher(BaseFetcher, Generic[_T_co, _U]):
26
28
  def __init__(self, dataset: _types.Dataset[_T_co], collate_fn: CollateFn):
27
29
  """Init function."""
28
30
  super().__init__(dataset, collate_fn)
@@ -49,7 +51,7 @@ class _IterableFetcher(_BaseFetcher, Generic[_T_co, _U]):
49
51
  return self._collate_fn(data)
50
52
 
51
53
 
52
- class _MapFetcher(_BaseFetcher, Generic[_T_co, _U]):
54
+ class _MapFetcher(BaseFetcher, Generic[_T_co, _U]):
53
55
  def fetch(self, possibly_batched_index) -> _U:
54
56
  """Fetch function."""
55
57
  if hasattr(self._dataset, "__getitems__") and self._dataset.__getitems__:
@@ -61,24 +63,22 @@ class _MapFetcher(_BaseFetcher, Generic[_T_co, _U]):
61
63
 
62
64
 
63
65
  @functools.singledispatch
64
- def create_fetcher(
65
- dataset: _types.Dataset[_T_co], collate_fn: CollateFn[_T_co, _U]
66
- ) -> _BaseFetcher[_T_co, _U]:
67
- """Create fetcher."""
66
+ def _create_fetcher(dataset: _types.Dataset[_T_co], collate_fn: CollateFn) -> BaseFetcher:
67
+ """Create fetcher (internal singledispatch)."""
68
68
  raise TypeError(f"Unsupported type {type(dataset).__name__}")
69
69
 
70
70
 
71
71
  with contextlib.suppress(ImportError):
72
72
  import torch.utils.data
73
73
 
74
- @create_fetcher.register(torch.utils.data.IterableDataset)
74
+ @_create_fetcher.register(torch.utils.data.IterableDataset)
75
75
  def create_torch_iterable_dataset_fetcher(
76
76
  dataset: torch.utils.data.IterableDataset[_T_co], collate_fn: CollateFn
77
77
  ):
78
78
  """Create torch iterable dataset fetcher."""
79
79
  return create_iterable_fetcher(dataset, collate_fn)
80
80
 
81
- @create_fetcher.register(torch.utils.data.Dataset)
81
+ @_create_fetcher.register(torch.utils.data.Dataset)
82
82
  def create_torch_dataset_fetcher(
83
83
  dataset: torch.utils.data.Dataset[_T_co], collate_fn: CollateFn
84
84
  ):
@@ -86,15 +86,36 @@ with contextlib.suppress(ImportError):
86
86
  return create_sequence_fetcher(dataset, collate_fn)
87
87
 
88
88
 
89
- @create_fetcher.register(Sequence)
90
- def create_sequence_fetcher(dataset: Sequence[_T_co], collate_fn: CollateFn) -> _MapFetcher:
89
+ @_create_fetcher.register(Sequence)
90
+ def create_sequence_fetcher(
91
+ dataset: Sequence[_T_co], collate_fn: CollateFn[_T_co, _U]
92
+ ) -> _MapFetcher:
91
93
  """Create sequence fetcher."""
92
94
  return _MapFetcher(dataset, collate_fn)
93
95
 
94
96
 
95
- @create_fetcher.register(Iterable)
97
+ @_create_fetcher.register(Iterable)
96
98
  def create_iterable_fetcher(
97
99
  dataset: Iterable[_T_co], collate_fn: CollateFn
98
100
  ) -> _IterableFetcher[_T_co, _U]:
99
101
  """Create iterable fetcher."""
100
102
  return _IterableFetcher(dataset, collate_fn)
103
+
104
+
105
+ def create_fetcher(
106
+ dataset: _types.Dataset[_T_co], collate_fn: CollateFn[_T_co, _U]
107
+ ) -> BaseFetcher[_T_co, _U]:
108
+ """Create fetcher.
109
+
110
+ A ``jax.Array`` is registered as a (concrete) ``Iterable`` but not a ``Sequence``, and
111
+ CPython's singledispatch C3 linearization places the ``Iterable`` abstract base class before
112
+ the concrete ``jax.Array`` in the composed MRO. Registering a ``jax.Array`` handler therefore
113
+ would never be selected and the array would be handled by the iterable fetcher, which ignores
114
+ the sampler indices and yields the dataset sequentially. We disambiguate with an explicit
115
+ ``isinstance`` check (mirroring the equivalent special case in ``create_sampler``) so the array
116
+ is treated as a ``_MapFetcher`` and the sampler indices are actually used.
117
+ """
118
+ if isinstance(dataset, jax.Array):
119
+ return _MapFetcher(dataset, collate_fn)
120
+
121
+ return _create_fetcher(dataset, collate_fn)