✨ feat(examples): simple vgg trained on cifar

.gitattributes

@@ -0,0 +1 @@
+Tests/MAExamples/Base/data/* filter=lfs diff=lfs merge=lfs -text

.github/workflows/examples.yml

@@ -0,0 +1,45 @@
+name: examples
+
+on:
+  workflow_dispatch:
+  push:
+    branches:
+      - main
+      - release**
+
+jobs:
+  MAExamples:
+    runs-on: self-hosted
+    defaults:
+      run:
+        shell: bash -l {0}
+
+    steps:
+      - uses: actions/checkout@v3
+        with:
+          lfs: true
+      - name: Pull lfs
+        run: git lfs pull
+
+      - name: Setup Conda Environment
+        run: |
+          conda create --name maexamples-ci python=3.7
+          conda env list
+
+      - name: Install Python Library
+        working-directory: Tests/MAExamples/Base
+        run: |
+          conda activate maexamples-ci
+          pip="$(dirname `which python`)"/pip
+          $pip install -e .
+
+      - name: Test
+        run: |
+          conda activate maexamples-ci
+          swift test --filter MAExamples
+
+      - name: Remove Conda Environment
+        if: always()
+        run: |
+          conda deactivate
+          conda env remove --name maexamples-ci

.github/workflows/mr_validation.yml → .github/workflows/unit-tests.yml

@@ -1,9 +1,9 @@
-name: Swift
+name: unit-tests
 
 on: [push]
 
 jobs:
-  Tests:
+  MAKit:
     runs-on: self-hosted
 
     steps:
@@ -14,4 +14,4 @@ jobs:
       - name: Build
         run: swift build
       - name: Test
-        run: swift test
+        run: swift test --filter MAKitTests

.swiftpm/xcode/xcshareddata/xcschemes/MAKit.xcscheme

@@ -62,6 +62,48 @@
                ReferencedContainer = "container:">
             </BuildableReference>
          </BuildActionEntry>
+         <BuildActionEntry
+            buildForTesting = "YES"
+            buildForRunning = "YES"
+            buildForProfiling = "YES"
+            buildForArchiving = "YES"
+            buildForAnalyzing = "YES">
+            <BuildableReference
+               BuildableIdentifier = "primary"
+               BlueprintIdentifier = "MATestsUtils"
+               BuildableName = "MATestsUtils"
+               BlueprintName = "MATestsUtils"
+               ReferencedContainer = "container:">
+            </BuildableReference>
+         </BuildActionEntry>
+         <BuildActionEntry
+            buildForTesting = "YES"
+            buildForRunning = "YES"
+            buildForProfiling = "YES"
+            buildForArchiving = "YES"
+            buildForAnalyzing = "YES">
+            <BuildableReference
+               BuildableIdentifier = "primary"
+               BlueprintIdentifier = "MAData"
+               BuildableName = "MAData"
+               BlueprintName = "MAData"
+               ReferencedContainer = "container:">
+            </BuildableReference>
+         </BuildActionEntry>
+         <BuildActionEntry
+            buildForTesting = "YES"
+            buildForRunning = "YES"
+            buildForProfiling = "YES"
+            buildForArchiving = "YES"
+            buildForAnalyzing = "YES">
+            <BuildableReference
+               BuildableIdentifier = "primary"
+               BlueprintIdentifier = "MAKit_MAExamples"
+               BuildableName = "MAKit_MAExamples"
+               BlueprintName = "MAKit_MAExamples"
+               ReferencedContainer = "container:">
+            </BuildableReference>
+         </BuildActionEntry>
       </BuildActionEntries>
    </BuildAction>
    <TestAction
@@ -80,6 +122,16 @@
                ReferencedContainer = "container:">
             </BuildableReference>
          </TestableReference>
+         <TestableReference
+            skipped = "NO">
+            <BuildableReference
+               BuildableIdentifier = "primary"
+               BlueprintIdentifier = "MAExamples"
+               BuildableName = "MAExamples"
+               BlueprintName = "MAExamples"
+               ReferencedContainer = "container:">
+            </BuildableReference>
+         </TestableReference>
       </Testables>
    </TestAction>
    <LaunchAction

Package.resolved

@@ -0,0 +1,14 @@
+{
+  "pins" : [
+    {
+      "identity" : "pythonkit",
+      "kind" : "remoteSourceControl",
+      "location" : "https://github.com/pvieito/PythonKit",
+      "state" : {
+        "branch" : "master",
+        "revision" : "060e1c8b0d14e4d241b3623fdbe83d0e3c81a993"
+      }
+    }
+  ],
+  "version" : 2
+}

Package.swift

@@ -12,10 +12,15 @@ let package = Package(
         // Products define the executables and libraries a package produces, and make them visible to other packages.
         .library(
             name: "MAKit",
-            targets: ["MAKit", "MAKitTestsUtils"]
+            targets: ["MAKit", "MATestsUtils"]
+        ),
+    ],
+    dependencies: [
+        .package(
+            url: "https://github.com/pvieito/PythonKit",
+            branch: "master"
         ),
     ],
-    dependencies: [],
     targets: [
         // Targets are the basic building blocks of a package. A target can define a module or a test suite.
         // Targets can depend on other targets in this package, and on products in packages this package depends on.
@@ -27,12 +32,16 @@ let package = Package(
             ]
         ),
         .target(
-            name: "MAKitTestsUtils",
+            name: "MATestsUtils",
             dependencies: ["MAKit"]
         ),
         .testTarget(
             name: "MAKitTests",
-            dependencies: ["MAKit", "MAKitTestsUtils"]
+            dependencies: ["MAKit", "MATestsUtils"]
+        ),
+        .testTarget(
+            name: "MAExamples",
+            dependencies: ["MAKit", "PythonKit"]
         ),
     ]
 )

README.md

@@ -1,4 +1,75 @@
 # MAKit
 
 Maximal Activation Kit. 
-A deep-learning framework for computer vision interpretability.
+A deep-learning framework for computer vision.
+
+It aims at promoting a total control and understanding of the main 
+operations needed to train deep learning models. 
+
+The `Layer` is the essential component needed to build an explicit graph of 
+operations from the data input to the ground truth. 
+
+The `Model` is a component that wraps the different layers together to 
+call functions in a simple way. 
+
+The API explicitly exposes the following functions: 
+
+- forward pass
+- backward pass
+- forward pass for the gradient checking.
+
+## Model
+
+## Layer
+
+# MAExamples
+
+`MAExamples` contains examples that show how to interact with `MAKit`. 
+The examples are organised as tests so as to demonstrate some capabilities. 
+They may be run in local (Xcode or command line) 
+or in the CI (release/main branches or explicit trigger).
+
+The following examples are currently available: 
+
+- VGGExample
+
+## VGG Example
+
+This example trains a simple model on the GPU. 
+The dataset used is CIFAR 10. 
+We want to train the model to discriminate between 2 labels 
+(not the 10 available).
+
+### Setup
+
+This example has some Python dependencies. In order to run 
+the example, we first have to setup the environment: 
+
+```bash
+conda create --name maexamples python=3.7
+conda activate maexamples
+cd Tests/MAExamples/Base
+pip install -e .
+```
+
+Then you should be able to run the tests right from XCode or 
+with a `bash` command:
+
+```bash
+swift test --filter MAExamples
+```
+
+You may eventually clean the environment with:
+
+```bash     
+conda deactivate
+conda env remove --name maexamples
+```
+
+### Steps
+
+1. Dump the training and testing datasets.
+2. Evaluate a random model on the testing dataset: watch a bad performance.  
+3. Train a model on the training dataset.
+4. Evaluate the trained model on the testing dataset: 
+   watch a better performance.

Sources/MAKit/Core/Layer/LayerNormalization.swift

@@ -149,20 +149,38 @@ public class BatchNormalization: BatchNormalizationBase
     /// Slight modification to avoid "divide by 0" errors.
     let _Ɛ: Double = 1e-5
 
+    ///
     /// Arrays of weights to scale the normalization result.
+    /// Shape ~ (nbNeurons,).
+    ///
     var _Ɣ: WeightArrays! = nil
+    ///
     /// Arrays of biases to add to the normalization result.
+    /// Shape ~ (nbNeurons,).
+    ///
     var _β: WeightArrays! = nil
 
+    ///
     /// List of deviations of data for the different independent batch normalization units.
+    /// Shape ~ (nbNeurons,).
+    ///
     var _σ2 = [Double]()
 
+    ///
     /// List of global averages of data for the different independent batch normalization units.
+    /// Shape ~ (nbNeurons,).
+    ///
     var _Eμ = [Double]()
+    ///
     /// List of global deviations of data for the different independent batch normalization units.
+    /// Shape ~ (nbNeurons,).
+    ///
     var _Eσ2 = [Double]()
 
+    ///
     /// The list of data normalized without taking into account the biases and the weights.
+    /// Shape ~ (nbNeurons, (batch x height x width)).
+    ///
     var _xHat = [[Double]]()
 
     /// Weights in the CPU execution context.
@@ -504,26 +522,53 @@ public class BatchNormalization: BatchNormalizationBase
 /// A layer that applies batch normalization in the GPU execution context.
 class BatchNormalizationGPU: BatchNormalizationBase
 {
+    ///
     /// Buffers of weights to scale the normalization result.
+    /// Shape ~ (nbNeurons,).
+    ///
     var _ƔBuffers: IWeightBuffers! = nil
+    ///
     /// Buffers of biases to add to the normalization result.
+    /// Shape ~ (nbNeurons,).
+    ///
     var _βBuffers: IWeightBuffers! = nil
 
+    ///
     /// Buffer of averages of data for the different independent batch normalization units.
+    /// Shape ~ (nbNeurons,).
+    ///
     var _μ: MetalBuffer<Float>! = nil
+    ///
     /// Buffer of global averages of data for the different independent batch normalization units.
+    /// Shape ~ (nbNeurons,).
+    ///
     var _Eμ: MetalPrivateBuffer<Float>! = nil
+    ///
     /// Buffer of deviations of data for the different independent batch normalization units.
+    /// Shape ~ (nbNeurons,).
+    ///
     var _σ2: MetalBuffer<Float>! = nil
+    ///
     /// Buffer of global deviations of data for the different independent batch normalization units.
+    /// Shape ~ (nbNeurons,).
+    ///
     var _Eσ2: MetalPrivateBuffer<Float>! = nil
 
+    ///
     /// Buffer of data normalized without taking into account the biases and the weights.
+    /// Shape ~ (batch, nbNeurons, height, width).
+    ///
     var _xHat: MetalBuffer<Float>! = nil
 
+    ///
     /// Buffer used to compute backward pass.
+    /// Shape ~ (nbNeurons,).
+    ///
     var _sum1: MetalBuffer<Float>! = nil
+    ///
     /// Buffer used to compute backward pass.
+    /// Shape ~ (nbNeurons,).
+    ///
     var _sum2: MetalBuffer<Float>! = nil
 
     /// GPU device on which model is executed.

Sources/MAKit/Core/Model/Model.swift

@@ -265,7 +265,35 @@ public class Model: BaseModel
         }
     }
 
-    // TODO: add elements here.
+    /// Downscale factor of the resolution (height and width).
+    public var strideFactor: Double?
+    {
+        get {
+            for layer in layers.reversed()
+            {
+                if let layer2D = layer as? Layer2D
+                {
+                    return layer2D.strideFactor
+                }
+            }
+            return nil
+        }
+    }
+
+    /// The size of the input image this layer is looking at.
+    public var receptiveField: Int?
+    {
+        get {
+            for layer in layers.reversed()
+            {
+                if let layer2D = layer as? Layer2D
+                {
+                    return layer2D.receptiveField
+                }
+            }
+            return nil
+        }
+    }
 
     /// Get/Set the weights of the different layers.
     public var weights: [[Float]]