v2026.11.2
All Bundles
Bundle

Convolutional neural networks on the CPU: layers with forward and backward passes, the Adam and SGD optimizers, an image dataset with train, validation and test splits and on-the-fly augmentation, and a training loop that records the metrics of every epoch. The layers are native (libobjk_ml, Eigen plus a small thread pool); this library holds the model API, the dataset and the trainer. Compile with -lib ml_cnn,ml,ml_lab,opencv,csv,json,cipher,gen_collect. Design, validation and measurements: docs/AI.md, "Convolutional networks (System.ML.Cnn)".

CnnTrainer

The training loop. Fit shuffles the training subset every epoch (seeded), trains on mini-batches (the last one may be smaller), then evaluates the validation subset, and records the metrics of every epoch in a TrainingHistory. Evaluate scores a subset (the test set) after training.

Example

trainer := CnnTrainer->New(model, train, validation, 64, 42);
history := trainer->Fit(10);
history->SaveCsv("history.csv");
test_result := trainer->Evaluate(test);
test_result->GetAccuracy()->PrintLine();

Operations

Evaluate #

Scores a subset in evaluation mode (no dropout, no augmentation): loss, accuracy, precision, recall, F1 and the confusion matrix, with class 1 positive and a 0.5 threshold.

method : public : Evaluate(subset:ImageSubset) ~ CnnEvaluation

Parameters

NameTypeDescription
subsetImageSubsetthe images to score

Return

TypeDescription
CnnEvaluationthe evaluation, or Nil if the subset is empty or an image cannot be loaded

Fit #

Trains for a number of epochs.

method : public : Fit(epochs:Int) ~ TrainingHistory

Parameters

NameTypeDescription
epochsIntepochs to run, 1 or more

Return

TypeDescription
TrainingHistorythe history; it holds the epochs that finished and GetError says why it stopped early (the history is Nil only for unusable arguments)

GetError #

Why the last call refused.

method : public : GetError() ~ String

Return

TypeDescription
Stringthe reason

GetPrefetch #

Is loading overlapped with training?

method : public : GetPrefetch() ~ Bool

Return

TypeDescription
Booltrue if prefetching

New # constructor

Creates a trainer.

New(model:CnnModel, train:ImageSubset, validation:ImageSubset, batch_size:Int, seed:Int)

Parameters

NameTypeDescription
modelCnnModela compiled model
trainImageSubsettraining subset
validationImageSubsetvalidation subset, or Nil for none (its columns then read 0)
batch_sizeIntimages per step, 1 or more
seedIntseed of the per-epoch shuffle

SetPrefetch #

Decode the next batch of images while the current one trains (default on). The images, the training order and the results are the same either way; only the wall time changes. It helps when images are decoded from files and are not cached, and does nothing for images held in memory. The decoding runs on the threads of ImageDataset->SetThreads.

method : public : SetPrefetch(prefetch:Bool) ~ Nil

Parameters

NameTypeDescription
prefetchBooltrue to overlap loading with training

SetVerbose #

Print one line per epoch while training.

method : public : SetVerbose(verbose:Bool) ~ Nil

Parameters

NameTypeDescription
verboseBooltrue to print