DeepSharp.Charts 0.5.0

<img src="https://raw.githubusercontent.com/xkqg/DeepSharp/main/assets/icon.png" width="96" align="right" alt="" />

DeepSharp — deep learning in C#

The best of three worlds: TensorFlow's way of describing a network, PyTorch's way of running it, and ML.NET's way of learning from a table.

DeepSharp is the C# layer over the engines that already exist: you describe, train and use a network in C#, and the arithmetic runs on .NET's own vector maths out of the box or on libtorch, the engine under PyTorch, through TorchSharp — swapping between them does not change a line of your model. What it adds is everything around the engine: getting your data in, the layers, the training loop, the checkpoints and the pictures. And a table that a tree learns better than a network does not have to become a network: the same prepared data is meant for ML.NET's trainers too.

0.5.0 learns on the engine you choose, and reads what others trained. A network trains, is measured by its pipeline's report and serves on the light engine DeepSharp ships or on libtorch, on the processor or a graphics card, without a line of it changing; and a model PyTorch, Keras or an ONNX exporter saved is read into the same network, to serve, to measure or to train further. The pipeline reads Parquet files, Excel workbooks and JSON files as it reads a comma-separated one, and runs for the learner that learns from it, saying which steps that learner does without. Beneath them stands what came before: layers, losses and optimizers; a training loop that stops once the validation rows no longer improve; networks described in Keras's words or written as code, saved with their pipeline as one file; the pipeline's report and the charts; tensors whose gradients are worked out automatically, the data half — which proposes what each column holds and names what should not be there — and a notebook to see the data in, whose report block draws what the cell that trains a model hands back. The roadmap says what comes next, and the changelog records what each release added.

dotnet add package DeepSharp
dotnet add package DeepSharp.Pipelines
dotnet add package DeepSharp.Learners.Networks

using DeepSharp.Learners.Networks;
using DeepSharp.Networks;
using DeepSharp.Pipelines;

var prepared = Pdd.Create()
    .ReadCsv("btceur-1d.csv")                                // declared, not opened
    .Declare(schema => schema
        .Timestamp("timestamp")
        .Number("close")
        .Optional("trades", ColumnKind.Number))              // a column that may have gaps
    .OrderBy("timestamp")
    .SplitByTime("timestamp", train: 0.70, validation: 0.15, gap: 1) // test is the rest
    .Ahead("close", 1, AheadAs.Return)                       // the answer: tomorrow's return
    .FillMissing("trades", With.Mean)                        // only offered after the split
    .Normalise("close", Scale.MidRange)                      // the training rows land between -1 and 1
    .Normalise("trades", Scale.MidRange)
    .Drop("timestamp")
    .Report(report => report.Measure(Metric.Rmse).On(Part.Validation, Part.Test).As(Shown.Numbers))
    .Build()
    .Run();

var trained = new Sequential().Dense(8).Relu().Dense(1)     // Keras's words: the widths come from the rows
    .Compile(new Adam(), new MeanSquaredError())
    .Fit(prepared, new FitOptions(seed: 42) { Epochs = 20 });

var file = trained.ToJson();                                 // the network and its pipeline, one file

btceur-1d.csv is a file of your own, and none ships here: a day a row of bitcoin's price in euros, as an exchange exports its daily candles, under a header that names timestamp, close and trades — when the day starts, the price it closed at, and how many trades it saw, empty on a day the exchange did not count them. The samples below run the same verbs on published data.

The course from raw data to a validated model is declared once as an artefact and replayed, and anything that learns from the data is fitted on the training rows alone. That is the whole idea, and PDD is where it is explained.

The network learns from the training rows and is judged by the validation rows; the test rows reach it only when the report measures it, each measure beside what predicting the training rows' average would score. trained.Predict(rows) answers rows that arrive later in the answer's own units — here, a return comes back as a price — and its Unfamiliar names, for each row, the features it moves away from the one value every training row held there, which the network learned nothing about; the report counts such rows in each part it measures. TrainedNetwork.FromJson(file, NetworkCatalog.BuiltIn(), StepCatalog.BuiltIn()) reads the network and its pipeline back in a program that has never seen the data, refusing the network beside any other fit of its pipeline, however alike their columns are. DeepSharp.Charts draws the loss curve, the measures and a confusion matrix, as SVG, and trained.Measures!.Report() renders the whole report as HTML.

The steps and what they learned are one file: prepared.ToJson() writes it, and PreparedData.FromJson(text, StepCatalog.BuiltIn()) reads it back in a program that has never seen the data. The catalog is the list of verbs the reader knows — add .WithIndicators() for a file that holds indicators, which read the rows in their order and so need that order said first, with .OrderBy("timestamp"); and .WithParquet(), .WithExcel() or .WithJson() for one that reads its rows with those packages' readers.

Reading the data, and running it for the learner

.ReadCsv(path) is one of four readers of a file. DeepSharp.Pipelines.Parquet adds .ReadParquet(path), DeepSharp.Pipelines.Excel adds .ReadExcel(path) and .ReadExcel(path, sheet), and DeepSharp.Pipelines.Json adds .ReadJson(path), for an array of records as an API hands them back; each is a verb of the pipeline's file as well, replayed as the comma-separated file is, and the Titanic passenger list in each of the four formats gives the same rows under the same keys in the same parts. DeepSharp.Pipelines.DataFrame reads Microsoft's data frame, and through it a database query. A Parquet file and a database say what each column holds, and the proposal of kinds takes what they say.

A pipeline runs for the learner that learns from it. Needs says what that learner needs of its features: pipeline.RunFor(Needs.NoScale) leaves out a step that only scales a feature, for a tree indifferent to scale, and RunFor(Needs.Categories) also hands each category over as its place in the list the training rows held, for a learner that splits on categories itself. A step an answer's way back runs through, one whose column a step below reads, and a scale that refuses what it was not fitted on are always taken. PreparedData.Skipped names what a run left out, and its file writes it, so a replay leaves out the same. On the wiki's Titanic pipeline a run for Categories hands a passenger over as nine numbers where the network's run hands over fourteen, and the report measures both learners on the same 623, 133 and 135 rows. Run() takes every step, as it always did, and a learner is handed only a run it can take.

On the engine you choose

The arithmetic runs on the light engine DeepSharp ships unless you name another, and naming it is one line: new FitOptions(seed: 42) { Backend = engine } trains the network on it, judges it by the validation rows and takes the report's measures there, and trained.Predict(rows, engine) serves on it. DeepSharp.Backends.TorchSharp is that engine on libtorch — TorchBackend.OnCpu() on the processor, TorchBackend.OnGpu(0) on the first graphics card:

dotnet add package DeepSharp.Backends.TorchSharp
dotnet add package libtorch-cpu-win-x64 --version 2.10.0

The package brings TorchSharp 0.107.0 and nothing native, so your application brings libtorch: libtorch-cpu-win-x64, libtorch-cpu-linux-x64 or libtorch-cpu-osx-arm64 2.10.0 for the processor, TorchSharp-cpu for all three, or TorchSharp-cuda-windows or TorchSharp-cuda-linux 0.107.0 for an NVIDIA card; made where there is none, the engine names those packages. The processor's libtorch is 56.9 MB to 128.2 MB to download, depending on the platform, and a card's runs to gigabytes, which is why no package of DeepSharp's brings it.

Which engine is the faster depends on the size of the work. Measured side by side on one machine, a Titanic training step took 38.8 µs on the light engine and 336 µs on libtorch, which spends longer handing each small operation over than the operation takes; a step of a small convolution took 12.1 ms on the light engine and 3.5 ms on libtorch on one thread, 2.2 on sixteen; and a convolution over 256 images with 32 filters took 345 ms on the light engine, 27.5 on libtorch on the processor and 5.0 on an RTX 5070 Ti. Every engine is held to the light one operation by operation and step by step — a total within three roundings of the size of its terms — and not run by run, since two engines that add up in another order drift apart over many steps: the networks sample's Titanic run kept the same epoch and got the same 0.815 of the test passengers right on all three, and ended with weights 0.08 from the light engine's on libtorch's processor and 2.4e−7 from them on the card. The network holds no engine and its file names none, so a network trained on one engine is served on another; network.Predict(features, loss, engine) is the one evaluation every door answers rows through.

Checkpoints are taken every epoch, or only when the validation loss improves, and CheckpointFile.Write(compiled, prepared, checkpoint) writes one as the network's file with what its run needs to go on. It records what the run went under — the seed, the batch size, the early stopping, and the engine with the version and the device an engine that implements INamesItsVersionAndDevice names — and a run that goes on from it under anything else is refused before anything is put back, naming each difference: on the engine it was taken on, a run goes on to the bit, and on another it would be another run under the same seed. CheckpointFile.Read(text, NetworkCatalog.BuiltIn(), prepared) reads one back in one reading of its file, holding it to its pipeline, and NetworkDocument.ReadCheckpoint reads one kept under keys of your own. The one file holds a network of up to about 45 million parameters, and a checkpoint under Adam one of about 14 million; a network's file is read at 36 bytes a parameter, a checkpoint under Adam at 96.

Reading what others trained

network.Load(entries) puts numbers trained somewhere else into a network by the path of each slot — 1.weight, 1.running_mean — all of them or none, as PyTorch's load_state_dict does with strict=True, every fault named at once in a SlotLoadException. IImporter is the seam a reader of another framework's files implements, and three packages implement it, each handing back a SavedNetwork — the network and the loss it answers through:

using DeepSharp.Import.Keras;
using DeepSharp.Import.Onnx;
using DeepSharp.Import.PyTorch;
using DeepSharp.Networks;
using DeepSharp.Tensors;

using var keras = File.OpenRead("titanic.keras");
var described = new KerasFile().Read(keras);                         // the network its file describes, and its loss

using var graph = File.OpenRead("titanic.onnx");
var exported = new OnnxFile(new BinaryCrossEntropy()).Read(graph);  // a graph names no loss, so it is handed one

using var state = File.OpenRead("titanic.pt");
var network = new Sequential().Dense(16).Relu().Dense(1).Lower(new Shape(14), new RandomStream(7));
var numbers = new TorchSaveFile(network, new BinaryCrossEntropy()).Read(state);   // numbers alone, into a network written here

DeepSharp.Import.Keras reads the .keras archive Keras 3 saves a model to and the .h5 file it saved one to before; DeepSharp.Import.Onnx the graphs torch.onnx.export, Keras's model.export(format="onnx") and tf2onnx write; DeepSharp.Import.PyTorch a safetensors file, SafetensorsFile, or the file torch.save(model.state_dict(), file) writes, TorchSaveFile. Each number is turned into the layout its slot keeps, as the layer that holds it says. The Titanic network PyTorch trained answers the 135 test passengers within five roundings of a single-precision number of PyTorch's chances, from a safetensors file, a .pt file or either exporter's graph, and the one Keras trained within five of Keras's from its archive, its HDF5 file or its graph; what no network here is built of — pooling, a branch, a dilated window — is refused at the layer or the node that says it, every one at once. The pickle torch.save writes is a program, so it is read by an interpreter that carries out only what PyTorch's own weights-only reader carries out, and builds nothing a file names but what a state dictionary is made of: any other name is refused where the file names it, before anything is looked up, built or run. A model read so is trained further behind a pipeline as any network is — described.Network.Compile(new Adam(0.001), described.Loss).Fit(prepared, options) — and kept with that pipeline as the one file.

Samples

Two programs and a notebook in Samples run all of this on published data, and a test runs each as it stands:

dotnet run --project Samples/DeepSharp.Sample.Pipelines -c Release -f net10.0
dotnet run --project Samples/DeepSharp.Sample.Networks -c Release -f net10.0

The first asks the Titanic passenger list what each of its columns holds before anything is declared, has a profile say what should not be there and how each is answered, and prepares the passengers and a price series. The second trains a network on each of three datasets — whether a passenger survived, a price five days on, a day's bikes hour by hour — has each pipeline's report measure it, saves it as its one file, reads it back and serves a row, and writes its charts. The notebook, Samples/titanic.verso, writes the Titanic pipeline block by block; its C# cell trains a network on what the blocks hand over, and its report block then draws the measures.

A notebook to see it in

DeepSharp.Verso.Notebooks writes the same pipeline as a Verso notebook, one block per step, each block the step's own JSON — edited as text, or field by field in Verso's properties panel. The first block reads the rows from a comma-separated file, a Parquet file, a sheet of an Excel workbook or a JSON file: the notebook brings those readers with it, as it brings the indicators and the charts. "Show the data here" on a block runs the pipeline down to it and shows the rows there, each column coloured over the training rows and every row marked with the part it lands in. A box on the grid leaves a column out — it turns black — or makes it a category, and the notebook writes the step that does it. "Choose the columns" lists every column of the source with its first values and what its cells propose it holds: tick it in, and it comes in so, or out; pick its kind, make it the answer and set the answer's own values — or tick a range, and seventy bands of a flock are taken in, or made the answer, with two ticks. A profile under a block names what should not be there, and where the answer is a change to the columns — a column that hands a model the answer left out, a fare of 0 said to stand for a gap — a box beside it makes it. What the blocks decide about their columns is saved beside the notebook, and the toolbar takes a saved file over again, listing every change before it makes one and every saved decision it cannot make. It also runs the whole pipeline and exports it as the same file the chain writes, and where a notebook comes back from Jupyter or Markdown with its blocks as text — as Verso's browser editor opens such a file — it makes blocks of them again.

Install it from Verso's Extensions panel with the notebook open: Verso loads a package installed there for a notebook that names it among the extensions it needs, and installing it into the open notebook writes that notebook's name for it, so it is loaded there from then on — install it the same way into each notebook that does not name it yet, the sample among them. The same package runs in Verso's VS Code extension, in the browser editor verso serve opens, and inside an application of your own, through DeepSharp.Verso.Api — the Notebook page says what each needs. Or let DeepSharp's own server show it in your browser, with nothing else to install — here the sample, from the repository's folder:

dotnet tool install --global DeepSharp.Verso.Serve
deepsharp-serve Samples/titanic.verso

It listens on this computer alone and answers only the address it prints, token and all.

A C# cell in the same notebook reads what the blocks declare, as text — it is there after "Show the data here" or the toolbar's run, and taken back whenever the blocks may no longer make it. The cell reads it through a catalog that knows every verb a block can hold, so it brings the packages the notebook brings:

#r "nuget: DeepSharp.Pipelines.Indicators"
#r "nuget: DeepSharp.Pipelines.Parquet"
#r "nuget: DeepSharp.Pipelines.Excel"
#r "nuget: DeepSharp.Pipelines.Json"
using DeepSharp.Pipelines;

if (Variables.TryGet<string>("deepsharp.pipeline", out var text))
{
    var folder = Variables.TryGet<string>("deepsharp.folder", out var saved) ? SourceFolder.Of(saved) : SourceFolder.WorkingDirectory;
    var catalog = StepCatalog.BuiltIn().WithIndicators().WithParquet().WithExcel().WithJson();
    var declaration = PipelineDeclaration.FromJson(text, catalog);
    var prepared = new Pipeline(declaration, rows: null, folder).Run();
}

The notebook trains nothing, so a report block's measures come from the cell that trains a model: it hands back what the report measured, Variables.Set("deepsharp.predictions", trained.Measures!.PredictionsToJson()), and "Show the data here" at the report block measures those predictions on the notebook's own run of its blocks and draws them as the report says, refusing predictions made behind any other fit — a block edited since the cell ran, say — with the words to run the cell again. A cell that ends with trained.Measures!.Report() shows the same report, and one that ends with trained.History!.LossCurve() the loss curve.

Read on

The packages

dotnet pack DeepSharp.slnx makes all sixteen. They run on .NET 8 and .NET 10. MIT — see LICENSE; each library a package brings comes under the licence its own package states. The page deepsharp-serve serves carries Mermaid and KaTeX, each under its own MIT licence, and DOMPurify under the Apache License 2.0, and the tool's third-party notices name those and every library the tool carries — Verso and its engine, the C# compiler, NuGet's client, Markdig, and the readers' libraries — each with its version, where it comes from, its copyright and its licence.