docs: document runtime compilation options

docs/source/reference/api.md

@@ -15,6 +15,9 @@ Defined in `batdetect2.api_v2`.
 - `BatDetect2API.from_config(model_config=..., targets_config=..., ...)`
   - build a full model stack from config objects.
 
+Both constructors accept `compile_model=True` to compile the detector after the
+API is built.
+
 ## Common tasks
 
 - Load a checkpoint and run prediction on one file.
@@ -22,6 +25,8 @@ Defined in `batdetect2.api_v2`.
 - Save predictions in one of the supported output formats.
 - Evaluate a model on labelled data.
 - Fine-tune an existing checkpoint on new targets.
+- Compile the detector explicitly with `BatDetect2API.compile()` when you want
+  to opt into PyTorch runtime compilation from Python.
 
 ## Generated reference
 

docs/source/reference/configs/inference/inference-config.md

@@ -7,6 +7,8 @@ Defined in `batdetect2.inference.config`.
 
 ## Top-level fields
 
+- `compile_model`
+  - compile the detector before batch prediction. This is off by default.
 - `loader`
   - data-loader settings for inference.
 - `clipping`
@@ -34,8 +36,19 @@ Override `InferenceConfig` when:
 
 - long recordings need different clipping behavior,
 - you want to tune batch size for your hardware,
+- you want to opt into runtime model compilation for repeated predictions,
 - you need reproducible prediction settings across runs.
 
+## Runtime compilation
+
+Set `compile_model: true` to compile the detector before batch inference. This
+can help when you run repeated predictions with stable input shapes. For a
+single short run, the compile step can cost more time than it saves.
+
+In Python, you can also compile explicitly with `BatDetect2API.compile()` or by
+passing `compile_model=True` to `BatDetect2API.from_checkpoint(...)` or
+`BatDetect2API.from_config(...)`.
+
 ## Related pages
 
 - Tune inference clipping:

docs/source/reference/configs/training/training-config.md

@@ -7,6 +7,10 @@ Defined in `batdetect2.train.config`.
 
 ## Top-level fields
 
+- `compile_model`
+  - compile the detector before training starts. This is off by default.
+- `precision`
+  - optional float32 matrix multiplication precision setting passed to PyTorch.
 - `train_loader`
   - training data loading and clipping settings.
 - `val_loader`
@@ -33,10 +37,22 @@ Use `TrainingConfig` when you want to change things like:
 - batch size,
 - augmentation,
 - optimiser and scheduler settings,
+- runtime options such as model compilation and matrix multiplication
+  precision,
 - number of epochs,
 - validation frequency,
 - checkpoint behaviour.
 
+## Runtime options
+
+Use `compile_model: true` to call `torch.compile` on the detector used during
+training. This can help on longer runs with stable tensor shapes, but it may be
+slower for short CPU-only experiments because PyTorch has to compile the graph
+before it can reuse it.
+
+Use `precision` to set PyTorch's float32 matrix multiplication precision before
+training starts. Supported values are `medium` and `high`.
+
 Example files live under `example_data/configs/`, including
 `example_data/configs/training.yaml`.
 

src/batdetect2/api_v2.py

@@ -241,6 +241,9 @@ class BatDetect2API:
             Training logger config override.
         logging_callbacks : Sequence[LoggingCallback[TrainLoggingContext]], optional
             Extra logging callbacks to run during training setup.
+        train_logger : Logger | None, optional
+            Pre-built Lightning logger to use for training. If omitted, one is
+            built from ``logger_config``.
 
         Returns
         -------