Supervised learning (SL)

Supervised learning (SL)#

The SL layer composes objective-owned losses with a common optimizer update and offline run lifecycle. Batches retain their tensor-tree structure and causal masks; source adapters, objectives and downstream execution define their semantics. Importing this package does not initialize simulation or reinforcement learning.

embodichain.learning.sl#

`LossResult`	An objective-owned scalar loss and sample-weighted observations.
`SupervisedBatch`	Separate measured inputs, supervision and masks without imposing axes.
`SupervisedObjective`	Compute task-specific losses without owning optimizer or data lifecycle.
`SupervisedLearner`	Own one optimizer while objectives own mathematical and graph semantics.
`SupervisedSource`	Owned batches drawn with an explicit caller-owned CPU sampling RNG.
`TensorBatchSource`	Fixed tensor-tree examples with explicit content identity.
`SupervisedTrainer`	Compose sampling and a learner without owning acquisition or simulation.
`SupervisedTrainerCfg`	Configure an offline, single-device supervised run.

class embodichain.learning.sl.LossResult[source]#

An objective-owned scalar loss and sample-weighted observations.

Parameters:

loss (Tensor) – Scalar connected to the parameters to optimize.
metrics (Mapping[str, Tensor | float]) – Scalar diagnostics; they do not enter backward automatically.
weight (float) – Effective observation count for evaluation aggregation. Loss reduction and sequence weighting remain the objective’s decision.

Methods:

__init__(loss[, metrics, weight])

__init__(loss, metrics=<factory>, weight=1.0)#

class embodichain.learning.sl.SupervisedBatch[source]#

Separate measured inputs, supervision and masks without imposing axes.

Parameters:

inputs (Any) – Tensor or nested tensor tree supplied to the objective.
targets (Any) – Supervision tree. Its history may differ from the input history.
masks (Mapping[str, Tensor]) – Named masks interpreted by the objective, not the optimizer.
metadata (Mapping[str, Any]) – Source identities, units, timing and other host-side context.

The producer owns storage and causal alignment. This container does not detach tensors: differentiable multi-step objectives retain their graph.

Methods:

`__init__`(inputs, targets[, masks, metadata])
`to`(device)	Move tensor trees, preserving dtypes and host metadata.

__init__(inputs, targets, masks=<factory>, metadata=<factory>)#

to(device)[source]#

Move tensor trees, preserving dtypes and host metadata.

Parameters:: device (str | device) – Destination for inputs, targets and masks.
Return type:: SupervisedBatch
Returns:: A batch whose differentiable tensor transfers preserve gradients.

class embodichain.learning.sl.SupervisedObjective[source]#

Compute task-specific losses without owning optimizer or data lifecycle.

Methods:

`__init__`(args, *kwargs)
`compute_loss`(model, batch)	Build a scalar objective, optionally unrolling a differentiable model.

__init__(*args, **kwargs)#

compute_loss(model, batch)[source]#

Build a scalar objective, optionally unrolling a differentiable model.

Parameters:

model (Module) – Trainable module, already on the batch’s device.
batch (SupervisedBatch) – Explicit inputs, targets, masks and sample context.

Return type:

LossResult

Returns:

Loss and statistics using this objective’s numerical conventions.

class embodichain.learning.sl.SupervisedLearner[source]#

Own one optimizer while objectives own mathematical and graph semantics.

Parameters:

model (Module) – Caller-constructed model on its intended device.
objective (SupervisedObjective) – Loss builder, including any sequence unrolling or integration.
optimizer (Optimizer) – Optimizer over the model’s trainable parameters.
max_grad_norm (float) – Positive clipping bound, or zero to measure without clipping.
amp_dtype (dtype | None) – Optional bfloat16 autocast for the forward objective. Numerical objectives may explicitly leave autocast for FP32 state integration.
clip_grad (Callable[[Iterable[Parameter], float], Tensor] | None) – Optional numerical-profile-specific clipping implementation.
numerical_context (Callable[[], AbstractContextManager[Any]] | None) – Context factory spanning forward, backward and clipping.

Sampling, normalizer updates, learning-rate schedules and model publication belong to callers. An update is committed only after optimizer.step succeeds.

Methods:

`__init__`(model, objective, optimizer, *[, ...])
`load_state_dict`(state)	Restore an update boundary after checking model tensor compatibility.
`state_dict`()	Return model, optimizer and committed update state.
`update`(batch)	Backpropagate one objective and commit one finite parameter update.

__init__(model, objective, optimizer, *, max_grad_norm=0.0, amp_dtype=None, clip_grad=None, numerical_context=None)[source]#

load_state_dict(state)[source]#

Restore an update boundary after checking model tensor compatibility.

Parameters:: state (Mapping[str, Any]) – State produced by state_dict().
Return type:: None

state_dict()[source]#

Return model, optimizer and committed update state.

Return type:: dict[str, Any]
Returns:: A PyTorch-style state mapping; callers serialize it before mutation.

update(batch)[source]#

Backpropagate one objective and commit one finite parameter update.

Parameters:: batch (SupervisedBatch) – Owned training inputs and supervision on the model’s device.
Return type:: dict[str, float | int]
Returns:: Loss, pre-clipping gradient norm, effective weight, update count and objective metrics. Returned statistics do not retain the graph.
Raises:: FloatingPointError – Loss or gradient norm is not finite; optimizer parameters and the committed update counter are not advanced.

class embodichain.learning.sl.SupervisedSource[source]#

Owned batches drawn with an explicit caller-owned CPU sampling RNG.

Methods:

`__init__`(args, *kwargs)
`sample`(batch_size, *, generator)	Draw a batch without hidden waits, production or lifecycle changes.

__init__(*args, **kwargs)#

sample(batch_size, *, generator)[source]#

Draw a batch without hidden waits, production or lifecycle changes.

Parameters:

batch_size (int) – Number of training examples.
generator (Generator) – Caller-owned sampling generator.

Return type:

SupervisedBatch

Returns:

An independently owned batch with source-specific tensor axes.

class embodichain.learning.sl.TensorBatchSource[source]#

Fixed tensor-tree examples with explicit content identity.

Parameters:

batch (SupervisedBatch) – Resident CPU examples; every tensor has the same first batch axis.
source_id (str) – Optional durable corpus identity. A content hash is always retained so reusing an ID cannot silently replace training data.

Batch metadata must be finite JSON data so units and feature declarations enter content identity. Mapping keys in tensor trees retain their types. Construction takes a detached owned snapshot. This source has no simulator, action-schema, sequence-length or image-layout assumption.

Methods:

`__init__`(batch, *[, source_id])
`iter_batches`(batch_size)	Visit all examples once in stable source order, retaining the tail.
`sample`(batch_size, *, generator)	Sample examples with replacement using an explicit RNG.

__init__(batch, *, source_id='tensor')[source]#

iter_batches(batch_size)[source]#

Visit all examples once in stable source order, retaining the tail.

Parameters:: batch_size (int) – Positive maximum batch size.
Yields:: Owned consecutive batches, including the final partial batch.
Return type:: Iterator[SupervisedBatch]

sample(batch_size, *, generator)[source]#

Sample examples with replacement using an explicit RNG.

Parameters:

batch_size (int) – Positive number of examples.
generator (Generator) – CPU sampling RNG.

Return type:

SupervisedBatch

Returns:

Owned tensor trees and sampled source indices.

class embodichain.learning.sl.SupervisedTrainer[source]#

Compose sampling and a learner without owning acquisition or simulation.

Parameters:

learner (SupervisedLearner) – Shared single-update learner.
source (SupervisedSource) – Fixed data source with explicit identity and RNG-based sampling.
cfg (SupervisedTrainerCfg | None) – Update budget, device and observation settings.
signature (Mapping[str, Any] | None) – Recipe semantics, including feature/action units, frames, model configuration and numerical policy where applicable.
scheduler (Any) – Optional scheduler stepped after each successful update.
evaluate (Callable[[SupervisedLearner], Mapping[str, float]] | None) – Optional callback receiving the committed learner. It owns validation metrics and must not select a model on a test split.

Methods:

`__init__`(learner, source[, cfg, signature, ...])
`fit`(*[, stop_after])	Train up to the configured or an earlier committed update boundary.
`resume`(path)	Restore the same run after validating data, recipe and configuration.
`save`(path)	Atomically save a complete committed learning and sampling boundary.

__init__(learner, source, cfg=None, *, signature=None, scheduler=None, evaluate=None)[source]#

fit(*, stop_after=None)[source]#

Train up to the configured or an earlier committed update boundary.

Parameters:: stop_after (int | None) – Optional absolute early-stop update for resumable runs.
Return type:: dict[str, Any]
Returns:: Completed update count, final metrics and last-checkpoint path.

resume(path)[source]#

Restore the same run after validating data, recipe and configuration.

Parameters:: path (str | Path) – Trusted training checkpoint from this trainer.
Return type:: None

save(path)[source]#

Atomically save a complete committed learning and sampling boundary.

Parameters:: path (str | Path) – Local checkpoint destination, replaced atomically.
Return type:: None

class embodichain.learning.sl.SupervisedTrainerCfg[source]#

Configure an offline, single-device supervised run.

Parameters:

total_updates (int) – Absolute optimizer-update budget, including resumed work.
batch_size (int) – Source examples per update.
device (str) – Tensor destination; runtime adapters remain caller-owned.
seed (int) – Independent source-sampling seed. Initialize models before building the trainer using the recipe’s explicitly chosen model seed.
output_dir (str) – Local metrics and checkpoint directory.
checkpoint_interval (int) – Periodic save frequency; zero saves only at the end.
validation_interval (int) – Optional validation callback frequency.

Methods:

`__init__`([total_updates, batch_size, ...])
`copy`(**kwargs)	Return a new object replacing specified fields with new values.
`replace`(**kwargs)	Return a new object replacing specified fields with new values.
`to_dict`()	Convert an object into dictionary recursively.
`validate`([prefix])	Check the validity of configclass object.

__init__(total_updates=<factory>, batch_size=<factory>, device=<factory>, seed=<factory>, output_dir=<factory>, checkpoint_interval=<factory>, validation_interval=<factory>)#

copy(**kwargs)#

Return a new object replacing specified fields with new values.

This is especially useful for frozen classes. Example usage:

@configclass(frozen=True)
class C:
    x: int
    y: int

c = C(1, 2)
c1 = c.replace(x=3)
assert c1.x == 3 and c1.y == 2

Parameters:

obj (object) – The object to replace.
**kwargs – The fields to replace and their new values.

Return type:

object

Returns:

The new object.

replace(**kwargs)#

Return a new object replacing specified fields with new values.

This is especially useful for frozen classes. Example usage:

@configclass(frozen=True)
class C:
    x: int
    y: int

c = C(1, 2)
c1 = c.replace(x=3)
assert c1.x == 3 and c1.y == 2

Parameters:

obj (object) – The object to replace.
**kwargs – The fields to replace and their new values.

Return type:

object

Returns:

The new object.

to_dict()#

Convert an object into dictionary recursively.

Note

Ignores all names starting with “__” (i.e. built-in methods).

Parameters:: obj (object) – An instance of a class to convert.
Raises:: ValueError – When input argument is not an object.
Return type:: dict[str, Any]
Returns:: Converted dictionary mapping.

validate(prefix='')#

Check the validity of configclass object.

This function checks if the object is a valid configclass object. A valid configclass object contains no MISSING entries.

Parameters:

obj (object) – The object to check.
prefix (str) – The prefix to add to the missing fields. Defaults to ‘’.

Return type:

list[str]

Returns:

A list of missing fields.

Raises:

TypeError – When the object is not a valid configuration object.

embodichain.learning.sl.learner#

SupervisedLearner

Own one optimizer while objectives own mathematical and graph semantics.

class embodichain.learning.sl.learner.SupervisedLearner[source]#

Own one optimizer while objectives own mathematical and graph semantics.

Parameters:

model (Module) – Caller-constructed model on its intended device.
objective (SupervisedObjective) – Loss builder, including any sequence unrolling or integration.
optimizer (Optimizer) – Optimizer over the model’s trainable parameters.
max_grad_norm (float) – Positive clipping bound, or zero to measure without clipping.
amp_dtype (dtype | None) – Optional bfloat16 autocast for the forward objective. Numerical objectives may explicitly leave autocast for FP32 state integration.
clip_grad (Callable[[Iterable[Parameter], float], Tensor] | None) – Optional numerical-profile-specific clipping implementation.
numerical_context (Callable[[], AbstractContextManager[Any]] | None) – Context factory spanning forward, backward and clipping.

Sampling, normalizer updates, learning-rate schedules and model publication belong to callers. An update is committed only after optimizer.step succeeds.

Methods:

`__init__`(model, objective, optimizer, *[, ...])
`load_state_dict`(state)	Restore an update boundary after checking model tensor compatibility.
`state_dict`()	Return model, optimizer and committed update state.
`update`(batch)	Backpropagate one objective and commit one finite parameter update.

__init__(model, objective, optimizer, *, max_grad_norm=0.0, amp_dtype=None, clip_grad=None, numerical_context=None)[source]#

load_state_dict(state)[source]#

Restore an update boundary after checking model tensor compatibility.

Parameters:: state (Mapping[str, Any]) – State produced by state_dict().
Return type:: None

state_dict()[source]#

Return model, optimizer and committed update state.

Return type:: dict[str, Any]
Returns:: A PyTorch-style state mapping; callers serialize it before mutation.

update(batch)[source]#

Backpropagate one objective and commit one finite parameter update.

Parameters:: batch (SupervisedBatch) – Owned training inputs and supervision on the model’s device.
Return type:: dict[str, float | int]
Returns:: Loss, pre-clipping gradient norm, effective weight, update count and objective metrics. Returned statistics do not retain the graph.
Raises:: FloatingPointError – Loss or gradient norm is not finite; optimizer parameters and the committed update counter are not advanced.

embodichain.learning.sl.sources#

`SupervisedSource`	Owned batches drawn with an explicit caller-owned CPU sampling RNG.
`TensorBatchSource`	Fixed tensor-tree examples with explicit content identity.

class embodichain.learning.sl.sources.SupervisedSource[source]#

Owned batches drawn with an explicit caller-owned CPU sampling RNG.

Methods:

`__init__`(args, *kwargs)
`sample`(batch_size, *, generator)	Draw a batch without hidden waits, production or lifecycle changes.

__init__(*args, **kwargs)#

sample(batch_size, *, generator)[source]#

Draw a batch without hidden waits, production or lifecycle changes.

Parameters:

batch_size (int) – Number of training examples.
generator (Generator) – Caller-owned sampling generator.

Return type:

SupervisedBatch

Returns:

An independently owned batch with source-specific tensor axes.

class embodichain.learning.sl.sources.TensorBatchSource[source]#

Fixed tensor-tree examples with explicit content identity.

Parameters:

batch (SupervisedBatch) – Resident CPU examples; every tensor has the same first batch axis.
source_id (str) – Optional durable corpus identity. A content hash is always retained so reusing an ID cannot silently replace training data.

Batch metadata must be finite JSON data so units and feature declarations enter content identity. Mapping keys in tensor trees retain their types. Construction takes a detached owned snapshot. This source has no simulator, action-schema, sequence-length or image-layout assumption.

Methods:

`__init__`(batch, *[, source_id])
`iter_batches`(batch_size)	Visit all examples once in stable source order, retaining the tail.
`sample`(batch_size, *, generator)	Sample examples with replacement using an explicit RNG.

__init__(batch, *, source_id='tensor')[source]#

iter_batches(batch_size)[source]#

Visit all examples once in stable source order, retaining the tail.

Parameters:: batch_size (int) – Positive maximum batch size.
Yields:: Owned consecutive batches, including the final partial batch.
Return type:: Iterator[SupervisedBatch]

sample(batch_size, *, generator)[source]#

Sample examples with replacement using an explicit RNG.

Parameters:

batch_size (int) – Positive number of examples.
generator (Generator) – CPU sampling RNG.

Return type:

SupervisedBatch

Returns:

Owned tensor trees and sampled source indices.

embodichain.learning.sl.trainer#

`SupervisedTrainerCfg`	Configure an offline, single-device supervised run.
`SupervisedTrainer`	Compose sampling and a learner without owning acquisition or simulation.

class embodichain.learning.sl.trainer.SupervisedTrainerCfg[source]#

Configure an offline, single-device supervised run.

Parameters:

total_updates (int) – Absolute optimizer-update budget, including resumed work.
batch_size (int) – Source examples per update.
device (str) – Tensor destination; runtime adapters remain caller-owned.
seed (int) – Independent source-sampling seed. Initialize models before building the trainer using the recipe’s explicitly chosen model seed.
output_dir (str) – Local metrics and checkpoint directory.
checkpoint_interval (int) – Periodic save frequency; zero saves only at the end.
validation_interval (int) – Optional validation callback frequency.

Methods:

`__init__`([total_updates, batch_size, ...])
`copy`(**kwargs)	Return a new object replacing specified fields with new values.
`replace`(**kwargs)	Return a new object replacing specified fields with new values.
`to_dict`()	Convert an object into dictionary recursively.
`validate`([prefix])	Check the validity of configclass object.

__init__(total_updates=<factory>, batch_size=<factory>, device=<factory>, seed=<factory>, output_dir=<factory>, checkpoint_interval=<factory>, validation_interval=<factory>)#

copy(**kwargs)#

Return a new object replacing specified fields with new values.

This is especially useful for frozen classes. Example usage:

@configclass(frozen=True)
class C:
    x: int
    y: int

c = C(1, 2)
c1 = c.replace(x=3)
assert c1.x == 3 and c1.y == 2

Parameters:

obj (object) – The object to replace.
**kwargs – The fields to replace and their new values.

Return type:

object

Returns:

The new object.

replace(**kwargs)#

Return a new object replacing specified fields with new values.

This is especially useful for frozen classes. Example usage:

@configclass(frozen=True)
class C:
    x: int
    y: int

c = C(1, 2)
c1 = c.replace(x=3)
assert c1.x == 3 and c1.y == 2

Parameters:

obj (object) – The object to replace.
**kwargs – The fields to replace and their new values.

Return type:

object

Returns:

The new object.

to_dict()#

Convert an object into dictionary recursively.

Note

Ignores all names starting with “__” (i.e. built-in methods).

Parameters:: obj (object) – An instance of a class to convert.
Raises:: ValueError – When input argument is not an object.
Return type:: dict[str, Any]
Returns:: Converted dictionary mapping.

validate(prefix='')#

Check the validity of configclass object.

This function checks if the object is a valid configclass object. A valid configclass object contains no MISSING entries.

Parameters:

obj (object) – The object to check.
prefix (str) – The prefix to add to the missing fields. Defaults to ‘’.

Return type:

list[str]

Returns:

A list of missing fields.

Raises:

TypeError – When the object is not a valid configuration object.

class embodichain.learning.sl.trainer.SupervisedTrainer[source]#

Compose sampling and a learner without owning acquisition or simulation.

Parameters:

learner (SupervisedLearner) – Shared single-update learner.
source (SupervisedSource) – Fixed data source with explicit identity and RNG-based sampling.
cfg (SupervisedTrainerCfg | None) – Update budget, device and observation settings.
signature (Mapping[str, Any] | None) – Recipe semantics, including feature/action units, frames, model configuration and numerical policy where applicable.
scheduler (Any) – Optional scheduler stepped after each successful update.
evaluate (Callable[[SupervisedLearner], Mapping[str, float]] | None) – Optional callback receiving the committed learner. It owns validation metrics and must not select a model on a test split.

Methods:

`__init__`(learner, source[, cfg, signature, ...])
`fit`(*[, stop_after])	Train up to the configured or an earlier committed update boundary.
`resume`(path)	Restore the same run after validating data, recipe and configuration.
`save`(path)	Atomically save a complete committed learning and sampling boundary.

__init__(learner, source, cfg=None, *, signature=None, scheduler=None, evaluate=None)[source]#

fit(*, stop_after=None)[source]#

Train up to the configured or an earlier committed update boundary.

Parameters:: stop_after (int | None) – Optional absolute early-stop update for resumable runs.
Return type:: dict[str, Any]
Returns:: Completed update count, final metrics and last-checkpoint path.

resume(path)[source]#

Restore the same run after validating data, recipe and configuration.

Parameters:: path (str | Path) – Trusted training checkpoint from this trainer.
Return type:: None

save(path)[source]#

Atomically save a complete committed learning and sampling boundary.

Parameters:: path (str | Path) – Local checkpoint destination, replaced atomically.
Return type:: None

embodichain.learning.sl.types#

`SupervisedBatch`	Separate measured inputs, supervision and masks without imposing axes.
`LossResult`	An objective-owned scalar loss and sample-weighted observations.
`SupervisedObjective`	Compute task-specific losses without owning optimizer or data lifecycle.

class embodichain.learning.sl.types.SupervisedBatch[source]#

Separate measured inputs, supervision and masks without imposing axes.

Parameters:

inputs (Any) – Tensor or nested tensor tree supplied to the objective.
targets (Any) – Supervision tree. Its history may differ from the input history.
masks (Mapping[str, Tensor]) – Named masks interpreted by the objective, not the optimizer.
metadata (Mapping[str, Any]) – Source identities, units, timing and other host-side context.

The producer owns storage and causal alignment. This container does not detach tensors: differentiable multi-step objectives retain their graph.

Methods:

`__init__`(inputs, targets[, masks, metadata])
`to`(device)	Move tensor trees, preserving dtypes and host metadata.

__init__(inputs, targets, masks=<factory>, metadata=<factory>)#

to(device)[source]#

Move tensor trees, preserving dtypes and host metadata.

Parameters:: device (str | device) – Destination for inputs, targets and masks.
Return type:: SupervisedBatch
Returns:: A batch whose differentiable tensor transfers preserve gradients.

class embodichain.learning.sl.types.LossResult[source]#

An objective-owned scalar loss and sample-weighted observations.

Parameters:

loss (Tensor) – Scalar connected to the parameters to optimize.
metrics (Mapping[str, Tensor | float]) – Scalar diagnostics; they do not enter backward automatically.
weight (float) – Effective observation count for evaluation aggregation. Loss reduction and sequence weighting remain the objective’s decision.

Methods:

__init__(loss[, metrics, weight])

__init__(loss, metrics=<factory>, weight=1.0)#

class embodichain.learning.sl.types.SupervisedObjective[source]#

Compute task-specific losses without owning optimizer or data lifecycle.

Methods:

`__init__`(args, *kwargs)
`compute_loss`(model, batch)	Build a scalar objective, optionally unrolling a differentiable model.

__init__(*args, **kwargs)#

compute_loss(model, batch)[source]#

Build a scalar objective, optionally unrolling a differentiable model.

Parameters:

model (Module) – Trainable module, already on the batch’s device.
batch (SupervisedBatch) – Explicit inputs, targets, masks and sample context.

Return type:

LossResult

Returns:

Loss and statistics using this objective’s numerical conventions.

embodichain.learning.sl.workflow#

`train_from_config`(config, *[, resume])	Build a recipe and run the common offline trainer.
`cli`([argv])	Train a supervised recipe from a YAML/JSON file and optional checkpoint.

embodichain.learning.sl.workflow.train_from_config(config, *, resume=None)[source]#

Build a recipe and run the common offline trainer.

Parameters:

config (dict[str, Any]) – JSON/YAML recipe with factory: module:function and model, data, objective, optimizer, trainer and evaluation recipe settings. The factory receives this mapping and returns a SupervisedTrainer.
resume (str | None) – Optional trusted training checkpoint.

Return type:

dict[str, Any]

Returns:

The trainer’s committed update and artifact report.

embodichain.learning.sl.workflow.cli(argv=None)[source]#

Train a supervised recipe from a YAML/JSON file and optional checkpoint.

Parameters:: argv (Sequence[str] | None) – Explicit CLI arguments, or the current process arguments.
Return type:: None

Model-specific recipes#

Concrete models own their physical codecs, objectives and source adapters in the official model library. The NeRD recipe connects committed trajectory windows to this common trainer without loading simulation or requiring the example runner.

Supervised learning (SL)

Contents

Supervised learning (SL)#

embodichain.learning.sl#

embodichain.learning.sl.learner#

embodichain.learning.sl.sources#

embodichain.learning.sl.trainer#

embodichain.learning.sl.types#

embodichain.learning.sl.workflow#

Model-specific recipes#