> ## Documentation Index
> Fetch the complete documentation index at: https://docs.quantspace.limex.pro/llms.txt
> Use this file to discover all available pages before exploring further.

# run_dl_job

> Train a PyTorch neural network and generate return predictions

## Overview

`run_dl_job` trains a PyTorch network on features and produces return predictions — the deep-learning alternative to [`run_ml_job`](/tools/ml-job).

Optional: only needed when you want neural forecasts as μ. Default QuantLab path stays data → PO → trading.

***

## Parameters

<ParamField body="feature_url" type="string" required>
  Blob storage URL pointing to a `feature_engine_*.json` file.

  This is the `output_url` returned by `run_feature_worker`.
</ParamField>

<ParamField body="data_extractor_url" type="string" required>
  Blob storage URL pointing to a `data_extractor_*.json` file.

  This is the `output_url` returned by `run_data_extraction`. Required alongside `feature_url`
  for proper train/test date alignment.
</ParamField>

<ParamField body="config" type="object" required>
  Neural network configuration.

  <Expandable title="config fields">
    <ParamField body="NN params" type="object" required>
      Top-level container for all neural network settings.

      <Expandable title="NN params fields">
        <ParamField body="Dot prediction" type="object" required>
          Training and architecture configuration.

          <Expandable title="Dot prediction fields">
            <ParamField body="status" type="boolean">
              Enable or disable this prediction block. Default: `true`.
            </ParamField>

            <ParamField body="current option" type="string" required>
              Model architecture to use. Supported values:

              | Value                     | Architecture                                   |
              | ------------------------- | ---------------------------------------------- |
              | `"lstm"`                  | Multi-layer LSTM (per-ticker)                  |
              | `"cnn"`                   | 1D Convolutional Network (per-ticker)          |
              | `"transformer"`           | Transformer Encoder (per-ticker)               |
              | `"mlp"`                   | Multi-layer Perceptron (per-ticker)            |
              | `"portfolio_lstm"`        | LSTM trained across all tickers jointly        |
              | `"portfolio_transformer"` | Transformer trained across all tickers jointly |
            </ParamField>

            <ParamField body="global_settings" type="object">
              Runtime settings.

              <Expandable title="global_settings fields">
                <ParamField body="device" type="string">
                  Compute device. `"auto"` selects CUDA if available, else CPU. Default: `"auto"`.
                </ParamField>

                <ParamField body="seed" type="integer">
                  Random seed for reproducibility. Default: `42`.
                </ParamField>
              </Expandable>
            </ParamField>

            <ParamField body="data_processing" type="object">
              Data preparation settings.

              <Expandable title="data_processing fields">
                <ParamField body="scaler" type="string">
                  Feature scaler. Options: `"standard"`, `"minmax"`, `"robust"`, `"maxabs"`. Default: `"robust"`.
                </ParamField>

                <ParamField body="lookback" type="integer">
                  Sequence window length (number of past days fed to the model). Default: `10`.
                </ParamField>

                <ParamField body="batch_size" type="integer">
                  Mini-batch size for training. Default: `64`.
                </ParamField>
              </Expandable>
            </ParamField>

            <ParamField body="training_params" type="object">
              Optimizer and training loop settings.

              <Expandable title="training_params fields">
                <ParamField body="epochs" type="integer">
                  Maximum number of training epochs. Default: `20`.
                </ParamField>

                <ParamField body="learning_rate" type="number">
                  Learning rate. Default: `0.001`.
                </ParamField>

                <ParamField body="patience" type="integer">
                  Early stopping patience (epochs without validation improvement). Default: `5`.
                </ParamField>

                <ParamField body="optimizer" type="string">
                  Optimizer. Options: `"adam"`, `"sgd"`, `"rmsprop"`. Default: `"adam"`.
                </ParamField>

                <ParamField body="weight_decay" type="number">
                  L2 regularization coefficient. Default: `0.0`.
                </ParamField>

                <ParamField body="loss_type" type="string">
                  Loss function. Options: `"mse"`, `"mae"`, `"huber"`, `"directional"`, `"r2"`, `"mahalanobis"`.
                  Default: `"r2"`. Unknown values fall back to MSE with a warning.
                </ParamField>

                <ParamField body="grad_clip" type="number">
                  Gradient clipping max-norm. Default: `1.0`.
                </ParamField>
              </Expandable>
            </ParamField>

            <ParamField body="models_params" type="object">
              Architecture-specific hyperparameters. Only the block matching `current option` is used.

              <Expandable title="Per-architecture fields">
                **lstm / portfolio\_lstm**

                * `hidden_dims` (int array) — hidden layer sizes, e.g. `[64, 32]`
                * `dropout` (float) — dropout rate, e.g. `0.2`

                **cnn**

                * `filters` (int array) — number of filters per conv layer, e.g. `[32, 64]`
                * `kernel_size` (int) — convolution kernel size, default `3`
                * `dropout` (float) — dropout rate
                * `pool_size` (int) — max-pool size, default `2`

                **transformer / portfolio\_transformer**

                * `d_model` (int) — model embedding dimension, e.g. `64`
                * `nhead` (int) — number of attention heads, e.g. `4`
                * `num_layers` (int) — number of encoder layers, e.g. `2`
                * `dim_feedforward` (int) — feedforward dimension, e.g. `128`
                * `dropout` (float) — dropout rate

                **mlp**

                * `hidden_dims` (int array) — hidden layer sizes, e.g. `[128, 64]`
                * `dropout` (float) — dropout rate
              </Expandable>
            </ParamField>
          </Expandable>
        </ParamField>
      </Expandable>
    </ParamField>
  </Expandable>
</ParamField>

<Note>
  Dates come from data extraction: sample **start** and **end**, with an optional train cut (`Learning_end`) inside that window for fit vs score. This job does not take its own testing-end calendar.
</Note>

***

## Returns

```json theme={null}
{
  "status": "Succeeded",
  "output_url": "https://stqsnpprod.blob.core.windows.net/data/nn_engine_9f8e7d6c5b4a.json",
  "output_name": "nn_engine_9f8e7d6c5b4a.json",
  "execution_name": "dl-job-abc123xyz"
}
```

| Field            | Description                                              |
| ---------------- | -------------------------------------------------------- |
| `status`         | Job terminal status (`Succeeded`)                        |
| `output_url`     | Full HTTPS URL to the output blob — pass to `run_po_job` |
| `output_name`    | Blob filename                                            |
| `execution_name` | Job execution ID for audit/debugging                     |

***

## Example — LSTM (per-ticker)

```json theme={null}
{
  "feature_url": "https://stqsnpprod.blob.core.windows.net/data/feature_engine_a1c3e5f70912.json",
  "data_extractor_url": "https://stqsnpprod.blob.core.windows.net/data/data_extractor_2b510101b9b7.json",
  "config": {
    "NN params": {
      "Dot prediction": {
        "status": true,
        "current option": "lstm",
        "global_settings": { "device": "auto", "seed": 42 },
        "data_processing": { "scaler": "robust", "lookback": 10, "batch_size": 64 },
        "training_params": {
          "epochs": 20,
          "learning_rate": 0.001,
          "patience": 5,
          "optimizer": "adam",
          "weight_decay": 0.0,
          "loss_type": "r2",
          "grad_clip": 1.0
        },
        "models_params": {
          "lstm": { "hidden_dims": [64, 32], "dropout": 0.2 }
        }
      }
    }
  }
}
```

## Example — Portfolio Transformer

```json theme={null}
{
  "feature_url": "...",
  "data_extractor_url": "...",
  "config": {
    "NN params": {
      "Dot prediction": {
        "status": true,
        "current option": "portfolio_transformer",
        "global_settings": { "device": "auto", "seed": 42 },
        "data_processing": { "scaler": "minmax", "lookback": 12, "batch_size": 64 },
        "training_params": {
          "epochs": 5,
          "learning_rate": 0.0005,
          "patience": 10,
          "optimizer": "sgd",
          "weight_decay": 0.0001,
          "loss_type": "r2",
          "grad_clip": 1.0
        },
        "models_params": {
          "portfolio_transformer": {
            "d_model": 64,
            "nhead": 4,
            "num_layers": 2,
            "dropout": 0.4
          }
        }
      }
    }
  }
}
```

***

## Resources

| Resource           | Value                                         |
| ------------------ | --------------------------------------------- |
| Container Apps Job | `dl-job`                                      |
| Container name     | `dl-job`                                      |
| Env vars injected  | `FEATURE_URL`, `DATA_EXTRACTOR_URL`, `CONFIG` |
| Output blob prefix | `nn_engine_`                                  |

***

## Next Step

Pass `output_url` to [`run_po_job`](/tools/po-job) as `input_url`.

<Note>
  If you prefer classical machine learning, use [`run_ml_job`](/tools/ml-job) instead — it produces
  an `ml_engine_*.json` blob equally compatible with `run_po_job`.
</Note>