expanded documentation; added guide

README.md

@@ -1,36 +1,55 @@
-# MNN
+# MNN.jl
 
 [![Dev](https://img.shields.io/badge/docs-dev-blue.svg)](https://alexander-reimer.github.io/Simulation-of-MNNs/dev/)
 [![Build Status](https://github.com/alexander-reimer/Simulation-of-MNNs/actions/workflows/CI.yml/badge.svg?branch=main)](https://github.com/alexander-reimer/Simulation-of-MNNs/actions/workflows/CI.yml?query=branch%3Amain)
 [![Coverage](https://codecov.io/gh/alexander-reimer/Simulation-of-MNNs/branch/main/graph/badge.svg)](https://codecov.io/gh/alexander-reimer/Simulation-of-MNNs)
 [![Code Style: Blue](https://img.shields.io/badge/code%20style-blue-4495d1.svg)](https://github.com/invenia/BlueStyle)
 
-The German papers describing this project can be found in the [paper
-branch](https://github.com/Alexander-Reimer/Simulation-of-MNNs/tree/paper).
-
-## Summary (German)
-
-Wir wollen uns mit dem neuen, vergleichsweise wenig erforschtem Bereich der
-Mechanical Neural Networks, kurz MNNs, beschäftigen. Während die bisherige
-Forschung sich auf die technische, physische Implementation dieser Netzwerke
-fokussiert hat, wollen wir das Trainingsverfahren optimieren. Dazu wollen wir
-die bisher verwendeten Algorithmen (evolutionäres Lernen und Pattern Search)
-selbst implementieren und genauer sowie mit neuen Parametern auszuprobieren und
-zu vergleichen. Außerdem wollen wir versuchen, eine Methode für Backpropagation
-bei MNNs zu entwickeln und implementieren, da eine solche unserer Recherche nach
-noch nicht ausprobiert wurde.
-
-Dafür werden wir uns jedoch auf die Anwendung dieser Algorithmen in einer
-Simulation beschränken. Die Ergebnisse sollten dennoch einen guten Startpunkt
-für reale MNNs bieten.
-
-## Usage
-
-### NixOS
-
-When using NixOS, activating the development shell is necessary to make GLMakie work:
-
-```bash
-cd /path/to/this/project
-nix-shell .
-```
+We (Matteo Friedrich and Alexander Reimer) are currently participating in Jugend
+forscht 2024 (a German youth science competition). For our project, we needed a
+library capable of simulating, optimizing and visualizing Mechanical Neural
+Networks (MNNs). Since we couldn't find one, we decided to develop and publish
+our own: MNN.jl. The source code is available in our [GitHub
+repository](https://github.com/Alexander-Reimer/Simulation-of-MNNs).
+
+While this repository is hosted on the profile of Alexander Reimer
+(alexander.reimer2357@gmail.com), [Matteo
+Friedrich](https://github.com/MatteoFriedrich) (matteo.r.friedrich@gmail.com)
+has equally contributed to this project.
+
+## What Are MNNs?
+
+Mechanical Neural Networks (MNNs for short) are networks made of mass points
+connected by springs with variable spring constants. With a large enough
+network, a MNN can be trained to exhibit almost any behaviour desired by setting
+the spring constants appropiately. Importantly, they can be trained with
+multiple behaviours at once to exhibit different reactions depending on the
+"inputs" (forces acting on them). This makes them potentially useful for
+airplane wings which adjust theirs shape depending on the force and angle of the
+wind, body armor absorbing shock, better seat cushions or better wind turbine
+blades. Besides these examples of shape morphing behaviours, adjusting the
+resonance curves of MNNs is also possible and opens the door for applications
+like earthquake safe buildings, better music instruments, objects like walls
+capable of strengthening or weakening acoustic signals at will.
+
+We based our research and knowledge of MNNs on the 2022 paper ["Mechanical
+neural networks: Architected materials that learn
+behaviors"](https://www.science.org/doi/10.1126/scirobotics.abq7278) by Ryan H.
+Lee, Erwin A. B. Mulder and Jonathan B. Hopkins. They are, as far as we are
+aware, the first to describe such Mechanical Neural Networks. Ntwork.
+
+## Features of this library
+
+- Simulation of MNNs
+- Evaluating the performance of MNNs for shape morphing and resonance behaviour
+  with MSE
+- Optimizing the spring constants with Partial Pattern Search or an evolutionary
+  algorithm
+
+## Our Research
+
+For detailed papers (only in German), see the [paper branch on
+GitHub](https://github.com/Alexander-Reimer/Simulation-of-MNNs/tree/paper). The
+most recent one available is from our participation at the state-level
+competition in Lower Saxony:
+[paper.pdf](https://github.com/Alexander-Reimer/Simulation-of-MNNs/blob/paper/2024/JuFo_Niedersachsen/main.pdf)

docs/make.jl

@@ -13,13 +13,22 @@ makedocs(;
         canonical="https://Alexander-Reimer.github.io/Simulation-of-MNNs",
         edit_link="main",
         assets=String[],
+        repolink="https://github.com/Alexander-Reimer/Simulation-of-MNNs"
     ),
     pages=[
         "Home" => "index.md",
-    ],
+        "Manual" => Any[
+            "Guide"=>"man/guide.md",
+            "man/customize-simulation.md",
+        ],
+        "Reference" => Any[
+            "Public API"=>"lib/public.md",
+            "Internals"=>"lib/internals.md",
+        ],
+    ]
 )
 
 deploydocs(;
     repo="github.com/Alexander-Reimer/Simulation-of-MNNs",
-    devbranch="main",
+    devbranch="main"
 )

docs/previewDocs.sh

@@ -1,2 +1,2 @@
 # using https://github.com/tlienart/LiveServer.jl/#serve-docs
-julia --project=docs -e 'using MNN, LiveServer; servedocs()'
+julia --project=docs -ie 'using Revise, MNN, LiveServer; servedocs()'

docs/src/index.md

@@ -2,84 +2,91 @@
 CurrentModule = MNN
 ```
 
-# MNN
-
-Documentation for [MNN](https://github.com/Alexander-Reimer/Simulation-of-MNNs).
-
-This project was created for Jugend Forscht 2024 (a German STEM competition).
+# MNN.jl
+
+!!! warning
+    Please note that this project is still in development. It is already usable,
+    but there will probably be frequent breaking changes in the future as we
+    expand and refactor this library.
+
+We (Matteo Friedrich and Alexander Reimer) are currently participating in Jugend
+forscht 2024 (a German youth science competition). For our project, we needed a
+library capable of simulating, optimizing and visualizing Mechanical Neural
+Networks (MNNs). Since we couldn't find one, we decided to develop and publish
+our own: MNN.jl. The source code is available in our [GitHub
+repository](https://github.com/Alexander-Reimer/Simulation-of-MNNs).
+
+## What Are MNNs?
+
+Mechanical Neural Networks (MNNs for short) are networks made of mass points
+connected by springs with variable spring constants. With a large enough
+network, a MNN can be trained to exhibit almost any behaviour desired by setting
+the spring constants appropiately. Importantly, they can be trained with
+multiple behaviours at once to exhibit different reactions depending on the
+"inputs" (forces acting on them). This makes them potentially useful for
+airplane wings which adjust theirs shape depending on the force and angle of the
+wind, body armor absorbing shock, better seat cushions or better wind turbine
+blades. Besides these examples of shape morphing behaviours, adjusting the
+resonance curves of MNNs is also possible and opens the door for applications
+like earthquake safe buildings, better music instruments, objects like walls
+capable of strengthening or weakening acoustic signals at will.
+
+We based our research and knowledge of MNNs on the 2022 paper ["Mechanical
+neural networks: Architected materials that learn
+behaviors"](https://www.science.org/doi/10.1126/scirobotics.abq7278) by Ryan H.
+Lee, Erwin A. B. Mulder and Jonathan B. Hopkins. They are, as far as we are
+aware, the first to describe such Mechanical Neural Networks.
+
+## Features of this library
+
+- Simulation of MNNs
+- Evaluating the performance of MNNs for shape morphing and resonance behaviour
+  with MSE
+- Optimizing the spring constants with Partial Pattern Search or an evolutionary
+  algorithm
+
+## Our Research
+
+For detailed papers (only in German), see the [paper branch on
+GitHub](https://github.com/Alexander-Reimer/Simulation-of-MNNs/tree/paper). The
+most recent one available is from our participation at the state-level
+competition in Lower Saxony:
+[paper.pdf](https://github.com/Alexander-Reimer/Simulation-of-MNNs/blob/paper/2024/JuFo_Niedersachsen/main.pdf)
+
+### Summary
+
+#### What We Did
+
+- Both confirmed existing results and how representative our simulation is by
+  analysing the correlation between different hyperparameters and training
+  success, which mostly fit the existing research by Lee et al.
+  - Unlike Lee et al., we used the optimization algorithms applicable to
+    physical MNNs like Partial Pattern Search and/or evolutionary algorithms
+    instead of a gradient descent based approach
+- Successfully optimized the resonance curve of MNNs; we believe to be the first
+  to do this, as we couldn't find anything else available online
+
+#### What We Didn't Do (Yet)
+
+- Build our own MNN mechanically
+- Build a ressource intensive, physically accurate simulation
+  - the goal is to provide starting points for the optimization of real MNNs and
+    figure out the effects of parameters & different optimization algorithms
+  - specifically, we haven't (yet) incorparated checking spring and neuron
+    position limits, meaning that using very large input forces / goal position
+    vectors can result in mass points and springs phasing through each other
 
 ## Project Summary (German)
 
-Wir wollen uns mit dem neuen, noch vergleichsweise wenig erforschten Bereich der
-*mechanical neural networks*, kurz MNNs, beschäftigen. MNNs sind programmierbare
-Materialien, welchen verschiedene Verhaltensweisen, wie zum Beispiel ein
-bestimmtes Verformungsverhalten, antrainiert werden können. Sie bestehen aus
-Massepunkten (genannt Neuronen), welche durch Federn miteinander verbunden
-werden. Ihr Verhalten ergibt sich durch die Steifheiten der Federn. Die
-grundlegende Annahme von MNNs ist, dass diese Federkonstanten in zukünftigen
-Materialien einzeln angepasst werden können. In Analogie zu künstlichen
-neuronalen Netzwerken wäre es dann prinzipiell möglich, durch eine geeignet
-gewählte Konfiguration an Federkonstanten verschiedene Verhaltensweisen auf
-externe Kräfte anzutrainieren. Während sich die bisherige Forschung auf die
-technische, physische Implementation dieser Netzwerke fokussiert hat, wollen wir
-das Trainingsverfahren optimieren. Dazu haben wir bereits eine Simulation eines
-MNNs umgesetzt, die bisher verwendeten Algorithmen (evolutionäres Lernen und
-Pattern Search) selbst implementiert, sowie mit neuen Parametern ausprobiert und
-verglichen. Dafür haben wir uns jedoch auf die Anwendung dieser Algorithmen in
-Simulationsrechnungen beschränkt. Die Ergebnisse sollten dennoch einen guten
-Startpunkt für reale MNNs bieten. Der von uns entwickelte Code ist die erste
-öffentlich verfügbare Implementation eines MNNs. Unsere Ergebnisse zeigen, dass
-MNNs mehrere komplexe Verhaltensweisen lernen können. Diese intelligenten
-Materialien eröffnen vielfältige zukünftige technologische
-Anwendungsmöglichkeiten.
-
-## Installation
-
-Open the Julia REPL, then
-
-```
-julia> # type ] to open package manager
-
-pkg> add https://github.com/Alexander-Reimer/Simulation-of-MNNs
-```
-
-This should install the MNN package and all dependencies automatically.
-
-### NixOS
-
-When using NixOS, activating the development shell is necessary to make GLMakie work:
-
-```bash
-cd /path/to/this/project
-nix-shell .
-```
-
-## Usage
-
-To use MNN.jl in you project, you should first import it with
-
-```julia
-using MNN
-```
-
-You can then create your first MNN (see [`MNN.get_user_behaviour`](@ref) for
-instructions on how to use the GUI):
-
-```julia
-# create a MNN  with 5 columns and 4 rows
-net = Network(5, 4) 
-# show the network
-vis = Visualizer(net)
-# create a behaviour to simulate using a GUI
-b = get_user_behaviour(network::Network)
-# simulate network with forces determined by b applied for 500 time steps
-simulate!(net, Diff(500), b, vis = vis)
-```
-
-
-```@index
-```
-
-```@autodocs
-Modules = [MNN]
-```
+Wir haben uns mit dem neuen Bereich der *mechanical neural networks* (MNNs)
+beschäftigt - programmierbare Materialien, die aus mit Federn verbundenen
+Massenpunkten bestehen. Ihnen können durch Anpassung der Federhärten
+verschiedene Verhaltensweisen gleichzeitig antrainiert werden, was viele
+Anwendungsmöglichkeiten eröffnet, wie z.B. Flugzeugflügel, deren Form sich
+optimal an Windgeschwindigkeit und -richtung anpasst. In unserem Projekt haben
+wir die Trainingsverfahren und den Einfluss verschiedener Parameter analysiert
+und dafür in einer eigenen Softwarebibliothek die Simulation, Optimierung,
+Bewertung und Visualisierung von MNNs umgesetzt. Außerdem haben wir als Erste
+erfolgreich die Resonanzkurven von MNNs optimiert, was auch den Einsatz für z.B.
+erdbebensichere Strukturen ermöglicht. Die von uns erkannten Einflüsse von
+Parametern decken sich, wo vorhanden, mit der bisherigen Forschung.

docs/src/lib/internals.md

@@ -0,0 +1,23 @@
+# Internal Documentation
+
+Documentation for the internals of `MNN.jl`. These are subject to change.
+
+## Contents
+
+```@contents
+Pages = ["internals.md"]
+Depth = 2:2
+```
+
+## Index
+
+```@index
+Pages = ["internals.md"]
+```
+
+## Public Interface
+
+```@autodocs
+Modules = [MNN]
+Public = false
+```

docs/src/lib/public.md

@@ -0,0 +1,25 @@
+# Public Documentation
+
+Documentation for `MNN.jl`'s public interface.
+
+See the Internals section of the manual for internal package docs covering all submodules.
+
+## Contents
+
+```@contents
+Pages = ["public.md"]
+Depth = 2:2
+```
+
+## Index
+
+```@index
+Pages = ["public.md"]
+```
+
+## Public Interface
+
+```@autodocs
+Modules = [MNN]
+Private = false
+```

docs/src/man/customize-simulation.md

@@ -0,0 +1 @@
+# Adding Your Own Simulation