reax 0.6.13.dev1__tar.gz → 0.6.13.dev2__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 (97) hide show
  1. {reax-0.6.13.dev1 → reax-0.6.13.dev2}/PKG-INFO +1 -1
  2. {reax-0.6.13.dev1 → reax-0.6.13.dev2}/src/reax/__init__.py +1 -1
  3. {reax-0.6.13.dev1 → reax-0.6.13.dev2}/src/reax/modules.py +16 -0
  4. {reax-0.6.13.dev1 → reax-0.6.13.dev2}/src/reax/results.py +64 -10
  5. {reax-0.6.13.dev1 → reax-0.6.13.dev2}/src/reax/stages/fit.py +5 -3
  6. {reax-0.6.13.dev1 → reax-0.6.13.dev2}/src/reax/stages/stages.py +3 -0
  7. {reax-0.6.13.dev1 → reax-0.6.13.dev2}/src/reax/training/trainer.py +2 -0
  8. {reax-0.6.13.dev1 → reax-0.6.13.dev2}/src/reax/types.py +5 -1
  9. {reax-0.6.13.dev1 → reax-0.6.13.dev2}/LICENSE.txt +0 -0
  10. {reax-0.6.13.dev1 → reax-0.6.13.dev2}/README.rst +0 -0
  11. {reax-0.6.13.dev1 → reax-0.6.13.dev2}/pyproject.toml +0 -0
  12. {reax-0.6.13.dev1 → reax-0.6.13.dev2}/src/reax/_engine.py +0 -0
  13. {reax-0.6.13.dev1 → reax-0.6.13.dev2}/src/reax/_module_hooks.py +0 -0
  14. {reax-0.6.13.dev1 → reax-0.6.13.dev2}/src/reax/data/__init__.py +0 -0
  15. {reax-0.6.13.dev1 → reax-0.6.13.dev2}/src/reax/data/_datasource_manager.py +0 -0
  16. {reax-0.6.13.dev1 → reax-0.6.13.dev2}/src/reax/data/_datasources.py +0 -0
  17. {reax-0.6.13.dev1 → reax-0.6.13.dev2}/src/reax/data/_loaders.py +0 -0
  18. {reax-0.6.13.dev1 → reax-0.6.13.dev2}/src/reax/data/_types.py +0 -0
  19. {reax-0.6.13.dev1 → reax-0.6.13.dev2}/src/reax/data/collate.py +0 -0
  20. {reax-0.6.13.dev1 → reax-0.6.13.dev2}/src/reax/data/dataloaders.py +0 -0
  21. {reax-0.6.13.dev1 → reax-0.6.13.dev2}/src/reax/data/datamodules.py +0 -0
  22. {reax-0.6.13.dev1 → reax-0.6.13.dev2}/src/reax/data/datasets.py +0 -0
  23. {reax-0.6.13.dev1 → reax-0.6.13.dev2}/src/reax/data/fetchers.py +0 -0
  24. {reax-0.6.13.dev1 → reax-0.6.13.dev2}/src/reax/data/kfold.py +0 -0
  25. {reax-0.6.13.dev1 → reax-0.6.13.dev2}/src/reax/data/samplers.py +0 -0
  26. {reax-0.6.13.dev1 → reax-0.6.13.dev2}/src/reax/data/utils.py +0 -0
  27. {reax-0.6.13.dev1 → reax-0.6.13.dev2}/src/reax/demos/__init__.py +0 -0
  28. {reax-0.6.13.dev1 → reax-0.6.13.dev2}/src/reax/demos/boring_classes.py +0 -0
  29. {reax-0.6.13.dev1 → reax-0.6.13.dev2}/src/reax/demos/mnist.py +0 -0
  30. {reax-0.6.13.dev1 → reax-0.6.13.dev2}/src/reax/exceptions.py +0 -0
  31. {reax-0.6.13.dev1 → reax-0.6.13.dev2}/src/reax/hooks.py +0 -0
  32. {reax-0.6.13.dev1 → reax-0.6.13.dev2}/src/reax/keys.py +0 -0
  33. {reax-0.6.13.dev1 → reax-0.6.13.dev2}/src/reax/lightning/LICENSE +0 -0
  34. {reax-0.6.13.dev1 → reax-0.6.13.dev2}/src/reax/lightning/__init__.py +0 -0
  35. {reax-0.6.13.dev1 → reax-0.6.13.dev2}/src/reax/lightning/rank_zero.py +0 -0
  36. {reax-0.6.13.dev1 → reax-0.6.13.dev2}/src/reax/listeners/__init__.py +0 -0
  37. {reax-0.6.13.dev1 → reax-0.6.13.dev2}/src/reax/listeners/checkpointer.py +0 -0
  38. {reax-0.6.13.dev1 → reax-0.6.13.dev2}/src/reax/listeners/early_stopping.py +0 -0
  39. {reax-0.6.13.dev1 → reax-0.6.13.dev2}/src/reax/listeners/model_checkpoint.py +0 -0
  40. {reax-0.6.13.dev1 → reax-0.6.13.dev2}/src/reax/listeners/progress/__init__.py +0 -0
  41. {reax-0.6.13.dev1 → reax-0.6.13.dev2}/src/reax/listeners/progress/progress_bar.py +0 -0
  42. {reax-0.6.13.dev1 → reax-0.6.13.dev2}/src/reax/listeners/progress/rich_progress.py +0 -0
  43. {reax-0.6.13.dev1 → reax-0.6.13.dev2}/src/reax/listeners/progress/tqdm_progress.py +0 -0
  44. {reax-0.6.13.dev1 → reax-0.6.13.dev2}/src/reax/listeners/utils.py +0 -0
  45. {reax-0.6.13.dev1 → reax-0.6.13.dev2}/src/reax/loggers/__init__.py +0 -0
  46. {reax-0.6.13.dev1 → reax-0.6.13.dev2}/src/reax/loggers/_utils.py +0 -0
  47. {reax-0.6.13.dev1 → reax-0.6.13.dev2}/src/reax/loggers/csv_logs.py +0 -0
  48. {reax-0.6.13.dev1 → reax-0.6.13.dev2}/src/reax/loggers/logger.py +0 -0
  49. {reax-0.6.13.dev1 → reax-0.6.13.dev2}/src/reax/loggers/mlflow.py +0 -0
  50. {reax-0.6.13.dev1 → reax-0.6.13.dev2}/src/reax/loggers/pandas.py +0 -0
  51. {reax-0.6.13.dev1 → reax-0.6.13.dev2}/src/reax/loggers/tensorboard.py +0 -0
  52. {reax-0.6.13.dev1 → reax-0.6.13.dev2}/src/reax/metrics/__init__.py +0 -0
  53. {reax-0.6.13.dev1 → reax-0.6.13.dev2}/src/reax/metrics/_classification.py +0 -0
  54. {reax-0.6.13.dev1 → reax-0.6.13.dev2}/src/reax/metrics/_evaluators.py +0 -0
  55. {reax-0.6.13.dev1 → reax-0.6.13.dev2}/src/reax/metrics/_globals.py +0 -0
  56. {reax-0.6.13.dev1 → reax-0.6.13.dev2}/src/reax/metrics/_metric.py +0 -0
  57. {reax-0.6.13.dev1 → reax-0.6.13.dev2}/src/reax/metrics/_registry.py +0 -0
  58. {reax-0.6.13.dev1 → reax-0.6.13.dev2}/src/reax/metrics/aggregation.py +0 -0
  59. {reax-0.6.13.dev1 → reax-0.6.13.dev2}/src/reax/metrics/collections.py +0 -0
  60. {reax-0.6.13.dev1 → reax-0.6.13.dev2}/src/reax/metrics/jm/__init__.py +0 -0
  61. {reax-0.6.13.dev1 → reax-0.6.13.dev2}/src/reax/metrics/jm/types.py +0 -0
  62. {reax-0.6.13.dev1 → reax-0.6.13.dev2}/src/reax/metrics/jm/utils.py +0 -0
  63. {reax-0.6.13.dev1 → reax-0.6.13.dev2}/src/reax/metrics/regression.py +0 -0
  64. {reax-0.6.13.dev1 → reax-0.6.13.dev2}/src/reax/metrics/utils.py +0 -0
  65. {reax-0.6.13.dev1 → reax-0.6.13.dev2}/src/reax/optimizers.py +0 -0
  66. {reax-0.6.13.dev1 → reax-0.6.13.dev2}/src/reax/plugins.py +0 -0
  67. {reax-0.6.13.dev1 → reax-0.6.13.dev2}/src/reax/profilers/__init__.py +0 -0
  68. {reax-0.6.13.dev1 → reax-0.6.13.dev2}/src/reax/profilers/jax_profiler.py +0 -0
  69. {reax-0.6.13.dev1 → reax-0.6.13.dev2}/src/reax/profilers/profiler.py +0 -0
  70. {reax-0.6.13.dev1 → reax-0.6.13.dev2}/src/reax/random.py +0 -0
  71. {reax-0.6.13.dev1 → reax-0.6.13.dev2}/src/reax/saving.py +0 -0
  72. {reax-0.6.13.dev1 → reax-0.6.13.dev2}/src/reax/stages/__init__.py +0 -0
  73. {reax-0.6.13.dev1 → reax-0.6.13.dev2}/src/reax/stages/_timer.py +0 -0
  74. {reax-0.6.13.dev1 → reax-0.6.13.dev2}/src/reax/stages/common.py +0 -0
  75. {reax-0.6.13.dev1 → reax-0.6.13.dev2}/src/reax/stages/predict.py +0 -0
  76. {reax-0.6.13.dev1 → reax-0.6.13.dev2}/src/reax/stages/stats.py +0 -0
  77. {reax-0.6.13.dev1 → reax-0.6.13.dev2}/src/reax/stages/test.py +0 -0
  78. {reax-0.6.13.dev1 → reax-0.6.13.dev2}/src/reax/stages/train.py +0 -0
  79. {reax-0.6.13.dev1 → reax-0.6.13.dev2}/src/reax/stages/validation.py +0 -0
  80. {reax-0.6.13.dev1 → reax-0.6.13.dev2}/src/reax/strategies/__init__.py +0 -0
  81. {reax-0.6.13.dev1 → reax-0.6.13.dev2}/src/reax/strategies/_factory.py +0 -0
  82. {reax-0.6.13.dev1 → reax-0.6.13.dev2}/src/reax/strategies/_jax.py +0 -0
  83. {reax-0.6.13.dev1 → reax-0.6.13.dev2}/src/reax/strategies/_parallel.py +0 -0
  84. {reax-0.6.13.dev1 → reax-0.6.13.dev2}/src/reax/strategies/_single_device.py +0 -0
  85. {reax-0.6.13.dev1 → reax-0.6.13.dev2}/src/reax/strategies/_strategies.py +0 -0
  86. {reax-0.6.13.dev1 → reax-0.6.13.dev2}/src/reax/strategies/_utils.py +0 -0
  87. {reax-0.6.13.dev1 → reax-0.6.13.dev2}/src/reax/testing.py +0 -0
  88. {reax-0.6.13.dev1 → reax-0.6.13.dev2}/src/reax/training/__init__.py +0 -0
  89. {reax-0.6.13.dev1 → reax-0.6.13.dev2}/src/reax/training/_checkpoint_connector.py +0 -0
  90. {reax-0.6.13.dev1 → reax-0.6.13.dev2}/src/reax/training/_checkpointing.py +0 -0
  91. {reax-0.6.13.dev1 → reax-0.6.13.dev2}/src/reax/training/_deprecated.py +0 -0
  92. {reax-0.6.13.dev1 → reax-0.6.13.dev2}/src/reax/training/_logger_connector.py +0 -0
  93. {reax-0.6.13.dev1 → reax-0.6.13.dev2}/src/reax/utils/__init__.py +0 -0
  94. {reax-0.6.13.dev1 → reax-0.6.13.dev2}/src/reax/utils/arrays.py +0 -0
  95. {reax-0.6.13.dev1 → reax-0.6.13.dev2}/src/reax/utils/containers.py +0 -0
  96. {reax-0.6.13.dev1 → reax-0.6.13.dev2}/src/reax/utils/events.py +0 -0
  97. {reax-0.6.13.dev1 → reax-0.6.13.dev2}/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.13.dev1
3
+ Version: 0.6.13.dev2
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>
@@ -68,4 +68,4 @@ __all__ = (
68
68
  )
69
69
  )
70
70
 
71
- __version__ = "0.6.13.dev1"
71
+ __version__ = "0.6.13.dev2"
@@ -171,12 +171,27 @@ class Module(
171
171
  logger: bool | None = None,
172
172
  on_step=True,
173
173
  on_epoch=True,
174
+ reduce_fn: "reax.types.ReduceFn" = "mean",
174
175
  ) -> None:
175
176
  """Log a key, value pair.
176
177
 
177
178
  Example::
178
179
 
179
180
  self.log('train_loss', loss)
181
+
182
+ A raw (i.e. non-metric) ``value`` is logged once per batch and the values are reduced to a
183
+ single number at the end of the epoch. Use the default ``reduce_fn="mean"`` when each
184
+ batch measures the same quantity, and ``"sum"`` when each batch contributes part of a
185
+ whole::
186
+
187
+ self.log('train_loss', loss) # typical loss over the epoch
188
+ self.log('samples_seen', len(batch), reduce_fn='sum') # samples seen this epoch
189
+
190
+ Nothing else is assumed about the value: it is taken at face value and, in particular, is
191
+ not rescaled by the batch size. Log a `reax.Metric` if the reduction needs to account for
192
+ what the numbers actually are, e.g. an average over samples rather than over batches.
193
+
194
+ Metric instances know how to combine themselves, so ``reduce_fn`` doesn't apply to them.
180
195
  """
181
196
  trainer = self._trainer
182
197
  if trainer is None:
@@ -206,6 +221,7 @@ class Module(
206
221
  logger=logger,
207
222
  on_step=on_step,
208
223
  on_epoch=on_epoch,
224
+ reduce_fn=reduce_fn,
209
225
  )
210
226
 
211
227
  def log_dict(
@@ -1,6 +1,7 @@
1
1
  import dataclasses
2
2
  from typing import TYPE_CHECKING, Generic, TypeVar
3
3
 
4
+ import equinox
4
5
  import jax
5
6
  import jax.numpy as jnp
6
7
  import jaxtyping as jt
@@ -28,44 +29,91 @@ class Metadata:
28
29
 
29
30
 
30
31
  class ArrayResultMetric(_metric.Metric[jax.Array]):
32
+ """Accumulate raw logged values, reducing them over the batches of an epoch.
33
+
34
+ With ``reduce_fn="sum"`` the values are simply added up. With ``"mean"`` each is weighted by
35
+ the ``batch_size`` it was logged with, so the result is the average over all the samples seen
36
+ rather than over the batches, and a short final batch counts for the samples it actually holds.
37
+ Where the batch size isn't known every value counts once, giving the mean over the batches.
38
+ """
39
+
31
40
  value: jax.Array = 0 # Redefine here so the typing hinting works
32
- cumulated_batch_size: int = 0
41
+ weight: jax.Array = 0
42
+ reduce_fn: "reax.types.ReduceFn" = equinox.field(static=True, default="mean")
33
43
 
34
44
  @classmethod
35
45
  def create(
36
46
  # pylint: disable=arguments-differ
37
47
  cls,
38
48
  value: jt.ArrayLike,
39
- batch_size: int,
49
+ batch_size: int | None = None,
50
+ reduce_fn: "reax.types.ReduceFn" = "mean",
40
51
  ) -> "ArrayResultMetric":
41
52
  """Create function."""
42
- return ArrayResultMetric(value=jnp.asarray(value), cumulated_batch_size=batch_size)
53
+ reduce_fn = _check_reduce_fn(reduce_fn)
54
+ weight = _weight(batch_size, reduce_fn)
55
+
56
+ return ArrayResultMetric(
57
+ value=jnp.asarray(value) * weight, weight=weight, reduce_fn=reduce_fn
58
+ )
43
59
 
44
60
  @override
45
61
  def update(
46
62
  # pylint: disable=arguments-differ
47
63
  self,
48
64
  value: jt.ArrayLike,
49
- batch_size: int,
65
+ batch_size: int | None = None,
50
66
  ) -> "ArrayResultMetric":
51
67
  """Update function."""
68
+ weight = _weight(batch_size, self.reduce_fn)
69
+
52
70
  return ArrayResultMetric(
53
- value=self.value + jnp.asarray(value),
54
- cumulated_batch_size=self.cumulated_batch_size + batch_size,
71
+ value=self.value + jnp.asarray(value) * weight,
72
+ weight=self.weight + weight,
73
+ reduce_fn=self.reduce_fn,
55
74
  )
56
75
 
57
76
  @override
58
77
  def merge(self, other: "ArrayResultMetric") -> "ArrayResultMetric":
59
78
  """Merge function."""
79
+ if other.reduce_fn != self.reduce_fn:
80
+ raise ValueError(
81
+ f"Cannot merge results that are reduced differently, got '{self.reduce_fn}' and "
82
+ f"'{other.reduce_fn}'"
83
+ )
84
+
60
85
  return ArrayResultMetric(
61
86
  value=self.value + other.value,
62
- cumulated_batch_size=self.cumulated_batch_size + other.cumulated_batch_size,
87
+ weight=self.weight + other.weight,
88
+ reduce_fn=self.reduce_fn,
63
89
  )
64
90
 
65
91
  @override
66
92
  def compute(self) -> jax.Array:
67
93
  """Compute function."""
68
- return self.value / self.cumulated_batch_size
94
+ if self.reduce_fn == "sum":
95
+ return self.value
96
+
97
+ return self.value / self.weight
98
+
99
+
100
+ def _weight(batch_size: int | None, reduce_fn: "reax.types.ReduceFn") -> int:
101
+ """How much a value logged with ``batch_size`` counts for.
102
+
103
+ Totals are added up as they are, so they carry no weight. Averages are weighted by the number
104
+ of samples behind them, falling back to counting once each when that isn't known.
105
+ """
106
+ if reduce_fn == "sum" or batch_size is None:
107
+ return 1
108
+
109
+ return batch_size
110
+
111
+
112
+ def _check_reduce_fn(reduce_fn: "reax.types.ReduceFn") -> "reax.types.ReduceFn":
113
+ if reduce_fn not in ("sum", "mean"):
114
+ raise ValueError(f"`reduce_fn` must be one of 'sum' or 'mean', got {reduce_fn!r}")
115
+
116
+ return reduce_fn
69
117
 
70
118
 
71
119
  class ResultEntry(Generic[_OutT]):
@@ -115,15 +163,21 @@ class ResultCollection(dict[str, ResultEntry]):
115
163
  on_step: bool = False,
116
164
  on_epoch: bool = True,
117
165
  batch_size: int | None = None,
166
+ reduce_fn: "reax.types.ReduceFn" = "mean",
118
167
  ):
119
- """Log function."""
168
+ """Log function.
169
+
170
+ ``reduce_fn`` says how raw values logged over an epoch should be reduced to a single value,
171
+ with ``batch_size`` weighting them when taking their mean. Both are ignored for metric
172
+ instances, which know how to combine themselves.
173
+ """
120
174
  key = f"{fx}.{name}"
121
175
 
122
176
  if isinstance(value, types.MetricInstance):
123
177
  metric = value
124
178
  else:
125
179
  try:
126
- metric = ArrayResultMetric.create(value, batch_size)
180
+ metric = ArrayResultMetric.create(value, batch_size, reduce_fn)
127
181
  except TypeError:
128
182
  raise TypeError(
129
183
  f"Value must be a `reax.Metric` or a raw value, got {type(value).__name__}"
@@ -258,12 +258,13 @@ class FitEpoch(train.Train):
258
258
  logger: bool = False,
259
259
  on_step=False,
260
260
  on_epoch=True,
261
+ reduce_fn: "reax.types.ReduceFn" = "mean",
261
262
  ) -> None:
262
263
  """Log function."""
263
264
  if self._child is not None:
264
- self._child.log(name, value, batch_size, prog_bar, logger, on_step, on_epoch)
265
+ self._child.log(name, value, batch_size, prog_bar, logger, on_step, on_epoch, reduce_fn)
265
266
  else:
266
- super().log(name, value, batch_size, prog_bar, logger, on_step, on_epoch)
267
+ super().log(name, value, batch_size, prog_bar, logger, on_step, on_epoch, reduce_fn)
267
268
 
268
269
  def _should_check_val(self) -> bool:
269
270
  """Decide if we should run validation based on the current mode and progress."""
@@ -555,6 +556,7 @@ class Fit(stages.Stage):
555
556
  logger: bool = False,
556
557
  on_step=False,
557
558
  on_epoch=True,
559
+ reduce_fn: "reax.types.ReduceFn" = "mean",
558
560
  ) -> None:
559
561
  """Log function."""
560
562
  if self._child is None:
@@ -563,7 +565,7 @@ class Fit(stages.Stage):
563
565
  "so cannot currently log anything"
564
566
  )
565
567
 
566
- self._child.log(name, value, batch_size, prog_bar, logger, on_step, on_epoch)
568
+ self._child.log(name, value, batch_size, prog_bar, logger, on_step, on_epoch, reduce_fn)
567
569
 
568
570
  @override
569
571
  def _on_iteration_starting(self):
@@ -252,6 +252,7 @@ class Stage(abc.ABC):
252
252
  logger: bool = False,
253
253
  on_step=False,
254
254
  on_epoch=True,
255
+ reduce_fn: "reax.types.ReduceFn" = "mean",
255
256
  ) -> None:
256
257
  """Log a result while the stage is running."""
257
258
 
@@ -503,6 +504,7 @@ class EpochStage(Stage, abc.ABC):
503
504
  logger: bool = False,
504
505
  on_step=False,
505
506
  on_epoch=True,
507
+ reduce_fn: "reax.types.ReduceFn" = "mean",
506
508
  ) -> None:
507
509
  """Log metrics during the current epoch."""
508
510
  assert self._batch is not None
@@ -519,6 +521,7 @@ class EpochStage(Stage, abc.ABC):
519
521
  batch_idx=self._iter,
520
522
  on_step=on_step,
521
523
  on_epoch=on_epoch,
524
+ reduce_fn=reduce_fn,
522
525
  )
523
526
 
524
527
  @override
@@ -395,6 +395,7 @@ class Trainer(stages.StageListener, _deprecated.TrainerDeprecatedMixin):
395
395
  logger: bool = None,
396
396
  on_step=True,
397
397
  on_epoch=True,
398
+ reduce_fn: "reax.types.ReduceFn" = "mean",
398
399
  ) -> None:
399
400
  """Log function."""
400
401
  if self._stage is None:
@@ -412,6 +413,7 @@ class Trainer(stages.StageListener, _deprecated.TrainerDeprecatedMixin):
412
413
  batch_size=batch_size,
413
414
  on_step=on_step,
414
415
  on_epoch=on_epoch,
416
+ reduce_fn=reduce_fn,
415
417
  )
416
418
 
417
419
  # region Stages
@@ -1,5 +1,5 @@
1
1
  import pathlib
2
- from typing import Protocol, TypeVar, runtime_checkable
2
+ from typing import Literal, Protocol, TypeVar, runtime_checkable
3
3
 
4
4
  import jax.typing
5
5
  import jaxtyping as jt
@@ -11,6 +11,10 @@ Path = str | bytes | pathlib.Path
11
11
  ArrayMask = jt.Int[jt.ArrayLike, "..."] | jt.Bool[jt.ArrayLike, "..."]
12
12
  MetricsDict = dict[str, jax.typing.ArrayLike]
13
13
 
14
+ #: How the raw (i.e. non-metric) values logged over the batches of an epoch should be reduced to a
15
+ #: single value at the end of it: either their mean, or their total.
16
+ ReduceFn = Literal["sum", "mean"]
17
+
14
18
 
15
19
  @runtime_checkable
16
20
  class MetricType(Protocol[_OutT]):
File without changes
File without changes
File without changes
File without changes
File without changes