ObjectiveModel

Defined in fynance.models.objective

class ObjectiveModel(net=None, *, n_assets=None, layers=(16, 8), loss=None, optimizer=torch.optim.Adam, lr=1e-3, epochs=80, batch_size=None, shuffle=True, position_fn=torch.tanh, cost=0.0, seed=0)

Bases: object

Train a net to maximize a differentiable financial objective.

Parameters:

nettorch.nn.Module, optional

Architecture mapping a feature matrix (T, F) to a position book (T, N) (N = number of assets; (T, 1) for the single-asset case). Defaults to an MLP built lazily on the first fit (so it learns F and N). Pass any nn.Module (e.g. a TCN/LSTM) to use a custom architecture; a custom net receives X as the 2-D matrix (T, F) (a 3-D panel (T, N, M) is flattened to (T, N*M) first).

n_assetsint, optional

Number of assets N in the position book. None (default) infers it at fit: from the 2nd dimension of a 2-D y (T, N), or from the 2nd dimension of a 3-D X (T, N, M), falling back to 1 for a 1-D y (the single-asset case).

layerstuple of int

Hidden sizes of the default MLP (ignored when net is given).

lossBaseLoss, optional

Differentiable financial loss applied to the strategy returns positions * returns. Defaults to SharpeLoss.

optimizertype[torch.optim.Optimizer]

Optimizer class (default Adam).

lrfloat

Learning rate.

epochsint

Passes over the data per fit. With full-batch (batch_size None) this is the number of optimizer steps; with mini-batches it is epochs * ceil(T / batch_size) steps — far more updates, which the objective usually needs to converge on long series.

batch_sizeint, optional

Train on contiguous mini-batches of this many bars (order preserved so the turnover penalty stays meaningful). None (default) = full batch. Mini-batching is the practical way to actually train on long (e.g. minute) series — full-batch gives only epochs gradient steps total.

shufflebool

When mini-batching, shuffle the order of the contiguous chunks each epoch (rows within a chunk stay ordered). Improves SGD; default True.

position_fncallable

Maps the net output to a position; default tanh (positions in [-1, 1]).

costfloat

Per-bar proportional turnover cost penalized during training (e.g. 0.0026 for 26 bps). When non-zero the objective is computed on the net-of-cost return positions * returns - cost * |Δpositions|, so the net learns to hold positions instead of churning — the anti-churn brick for high-cost / high-frequency settings. Use the same value as the backtest’s ProportionalCost. Default 0 (no penalty, original behaviour).

seedint

Seed for reproducible initialization/training.

Notes

The net is warm-started across successive fit calls (so a walk-forward refit adapts online). Build a fresh model for an independent run.

fit(X, y)

Train the net to maximize the objective of the net-of-cost return.

Parameters:

Xarray-like, shape (T, F) or (T, N, M)

Feature matrix. A 3-D panel (T, N, M) (N assets, M features each) is flattened to (T, N*M) for the default dense net.

yarray-like, shape (T,) or (T, N)

Realized per-bar returns aligned with X (not a supervised label). A 2-D y carries the per-asset returns of the position book; a 1-D y is the single-asset case (N == 1).

Returns:

ObjectiveModel

self.

predict(X)

Return the position book for X, shape (T, N).

Accepts a 2-D X (T, F) or a 3-D panel (T, N, M) (flattened to (T, N*M) for the default net). The output is a position book with one column per asset ((T, 1) in the single-asset case). With the default position_fn (tanh) positions are bounded in [-1, 1]; a custom position_fn may produce unbounded values.