update docs

Author: filchristou

docs/make.jl

@@ -58,8 +58,8 @@ makedocs(
     modules = [MINDFul],
     pages = [
         "Introduction" => "index.md",
+        "Architecture" => "architecture.md",
         "Developing" => "dev.md",
-        "ROADMap" => "roadmap.md",
         "API" => "API.md",
         "Distributed Operation" => [
             "HTTP-API" => "HTTP.md",

docs/src/architecture.md

@@ -0,0 +1,43 @@
+# Architecture and Concepts
+
+MINDFul.jl models IP-optical routing, modulation, and spectrum assignment (RMSA) operations where high-level connectivity intents are recursively compiled into lower-level intents down to router and OXC configurations.
+
+## IBN-over-SDN
+
+When designing a multi-domain IBN system, MINDFul.jl embraces the **IBN-over-SDN** architecture. This approach decouples intent handling from the underlying SDN paradigm. The intent handling is separated into its own dedicated framework, operating independently and utilizing the underlying SDN controller strictly as a device driver for physical deployment. This separation of concerns fosters modularity and allows each layer to evolve independently.
+
+## IP-Optical Layer Model
+
+The architecture modeled by MINDFul.jl holds on to the pure IP-optical architecture signified by two layers:
+- **Electrical Layer:** Composed of IP routers and virtual links.
+- **Optical Layer:** Composed of Optical Cross Connects (OXCs) and physical fiber links.
+
+Currently, the library focuses on 3 primary devices:
+- The network node as a whole
+- The IP router
+- The optical cross connect (OXC)
+
+## Intent DAGs and Delegation
+
+MINDFul.jl uses **intent DAGs** (Directed Acyclic Graphs) to represent relationships between different intents. This hierarchical structure connects higher-level intents, which have a logical objective (e.g., establishing a connectivity service), with low-level intents (LLIs), which are responsible for resource allocation and hardware configurations on the specific devices.
+
+If an intent spans multiple domains, it is split at border nodes, and the external portion is securely **delegated** to the adjacent domain without exposing internal topological details. This structure enables seamless interoperability between domains.
+
+## Intent States and Operations
+
+Intents are highly dynamic and transition through several states during their lifecycle. MINDFul.jl commonly identifies four core intent states:
+- `uncompiled`: Unprocessed intents inside the system.
+- `compiled`: Processed intents with a well-defined implementation derived.
+- `installed`: Active intents whose implementation has been realized in the appropriate network devices.
+- `failed`: Active intents that malfunction after some failure during operation.
+
+To enable state transitions, several operations and algorithms are modeled:
+- **Intent Compilation:** Deriving an intent implementation and transitioning an intent to the `compiled` state.
+- **Intent Monitoring:** Ensuring that the installed intents satisfy all the requirements and triggering fallbacks in case of failure.
+- **Intent Conflict Resolution:** Handling situations when several intents require the same resources.
+
+## References
+
+- [F. Christou, "Decentralized Intent-driven Coordination of Multi-Domain IP-Optical Networks," 2022 18th International Conference on Network and Service Management (CNSM), Thessaloniki, Greece, 2022, pp. 359-363, doi: 10.23919/CNSM55787.2022.9964606](https://ieeexplore.ieee.org/document/9964606/)
+- [F. Christou and A. Kirstaedter, "Grooming Connectivity Intents in IP-Optical Networks Using Directed Acyclic Graphs," Photonic Networks; 24th ITG-Symposium, Berlin, 2023, pp. 1-4.](https://ieeexplore.ieee.org/document/10173072)
+- [F. Christou and A. Kirstädter, "Using Intent Directed Acyclic Graphs in Multi-Domain IP-Optical Networks," 2023 33rd International Telecommunication Networks and Applications Conference, Melbourne, Australia, 2023, pp. 176-179, doi: 10.1109/ITNAC59571.2023.10368533](https://ieeexplore.ieee.org/document/10368533)

docs/src/dev.md

@@ -1,47 +1,50 @@
-# Notes for developes and contributors
-
-## Mental classification of functions per functionality
-(must clarify these notes)
-To expand upon:
-allocate - deallocate
-reserve - unreserve
-function getters
-get... -> get field
-new... -> construct something new
-prioritize -> return a vector of indices
-choose -> return a specific (scalar) index
-comp -> compilation
-
-
-## How to read variables
-transmission -> trans\
-module -> mdl\
-mode -> mode\
-index -> idx\
-uuid -> id\
-ibn framework -> ibnf\
-
-## Create a new availability-aware IP-Optical Algorithm
-Look at `src/IBNLayer/ibn_bestempiricalavailabilitymatch.jl` where the algorithm `BestEmpiricalAvailabilityCompilation` is defined.
-More specifically, assume your new algorithm is a struct `MyNewAlgorithm`.
-We suggest you make it a subtype of `<: IntentCompilationAlgorithmWithMemory` and contain the following fields in your struct:
+# Developer Guide
+
+Welcome to the MINDFul.jl developer documentation. This section covers common conventions, how to extend MINDFul.jl algorithms, and how to run tests.
+
+## Variable Naming Conventions
+
+To keep the codebase consistent and readable, MINDFul.jl uses the following abbreviations for common variables:
+
+| Abbreviation | Meaning |
+| :--- | :--- |
+| `trans` | transmission |
+| `mdl` | module |
+| `mode` | mode |
+| `idx` | index |
+| `id` | uuid |
+| `ibnf` | IBN framework |
+
+## Creating a new Availability-Aware IP-Optical Algorithm
+
+MINDFul.jl is designed to be easily extensible. You can define your own intent compilation algorithms. As an example, look at `src/IBNLayer/ibn_bestempiricalavailabilitymatch.jl` where the algorithm `BestEmpiricalAvailabilityCompilation` is defined.
+
+To create a new algorithm `MyNewAlgorithm`, we recommend making it a subtype of `<: IntentCompilationAlgorithmWithMemory` and including the following fields:
+
 ```julia
+struct MyNewAlgorithm <: IntentCompilationAlgorithmWithMemory
     "How many k paths to check"
     candidatepathsnum::Int
-    """
-    How many m paths to consider for joint protection.
-    It investigates all possible pair of the first m paths
-    """
+    "How many m paths to consider for joint protection."
     pathsforprotectionnum::Int
-    "cached information"
+    "Cached information"
     cachedresults::CachedResults
     "The algorithm memory that is updated"
     basicalgmem::BasicAlgorithmMemory
+end
+```
+
+### 1. Define an IBNFramework alias
+
+Define a constant for your new framework configuration:
+```julia
+const IBNFrameworkMNA = IBNFramework{A,B,C,D,MyNewAlgorithm} where {A,B,C,D}
 ```
 
-1. Define a `const IBNFrameworkMNA = IBNFramework{A,B,C,D,MyNewAlgorithm} where {A,B,C,D}` to use it later
+### 2. Define Constructors
+
+Provide convenient constructors to initialize your algorithm's memory and cache:
 
-2. Define 3 cosntructors
 ```julia
 function MyNewAlgorithm(ibnag::IBNAttributeGraph, candidatepathsnum::Int, pathforprotectionnum::Int)
     cachedresults = CachedResults(ibnag, candidatepathsnum)
@@ -57,25 +60,37 @@ function MyNewAlgorithm(mna::MyNewAlgorithm, cachedresults::CachedResults)
 end
 ```
 
-3. Define a `compileintent!` for your new type `@recvtime function compileintent!(ibnf::IBNFrameworkMNA, idagnode::IntentDAGNode{<:ConnectivityIntent}; verbose::Bool = false)`
-Inside your function you can use [`MINDFul.intradomaincompilationtemplate`](@ref) and [`MINDFul.compileintenttemplate!](@ref) for easier development.
-Read the docs of the two functions for a better understanding. Now that's all.
-For multi-domain availability research the most important configurations you might want to add are `prioritizepaths` from `intradomaincompilationtemplate` and `prioritizesplitbordernodes` from `compileintenttemplate!`.
-The first one determines the internal domain paths and the second the split border nodes between the domains.
+### 3. Define the Compilation Function
+
+Define the `compileintent!` function for your new algorithm type. You can use the provided templates `intradomaincompilationtemplate` and `compileintenttemplate!` to jumpstart your development.
+
+```julia
+@recvtime function compileintent!(ibnf::IBNFrameworkMNA, idagnode::IntentDAGNode{<:ConnectivityIntent}; verbose::Bool = false)
+    # Your compilation logic here using intradomaincompilationtemplate and compileintenttemplate!
+end
+```
+
+For multi-domain availability research, the most important configurations to hook into are:
+- `prioritizepaths` (from `intradomaincompilationtemplate`): Determines the internal domain paths.
+- `prioritizesplitbordernodes` (from `compileintenttemplate!`): Determines the split border nodes between domains.
+
+## Event-Based Simulations and Visualizations
 
-## Further APIs
+MINDFul.jl provides a hackable interface designed to conduct event-based simulations under diverse scenarios. You can interact with the API to change intent states and monitor network resources over time. 
+
+Additionally, the companion package `MINDFulMakie.jl` can be used to visualize your simulations, draw intent DAGs, or render a compiled connectivity intent across the network topology.
 
 ## Testing
 
-Usefull testing functions are in the `TestModule` weak dependency.
-To access them you first need to load `Test` and `JET` and then use `Base.get_extention`.
+Useful testing functions are located in the `TestModule` weak dependency. To access them, first load `Test` and `JET`, and then use `Base.get_extension`.
+
 ```julia
-# get the test module from MINDFul
 import Test, JET
 TestModule = Base.get_extension(MINDFul, :TestModule)
-@test !isnothing(TM)
+@test !isnothing(TestModule)
 ```
-Now, with dot notation (`TestModule.`) you can access all the following functions. 
+
+Now, you can access testing utilities with dot notation (`TestModule.`).
 
 ### Testing API
 

docs/src/index.md

@@ -1,16 +1,14 @@
-Welcome to `MINDFul.jl` documentation
+# Welcome to MINDFul.jl
 
+MINDFul.jl is an open-source Julia library designed to facilitate research on multi-domain Intent-Based Networking (IBN), specifically focusing on pure IP-optical networks. It fills a noticeable gap in currently available tools by providing a stateful, modular representation of common IP-optical network equipment as well as common intent operations.
 
-MINDFul.jl is an open source tool for studying IP-optical intent-based networking.
+Network coordination across multiple domains is a complex task requiring seamless communication between network entities. While Software-Defined Networking (SDN) allows for efficient centralized control within domains, multi-domain networking often remains decentralized. MINDFul.jl tackles this by utilizing an intent-driven approach, which offers higher flexibility of interactions and support for much wider network capabilities than traditional protocols like BGP. 
 
-Intents are compiled down to further lower level intets forming an Directed Acyclic Graph (DAG).
-The leafs of the DAG are called "low level intents" and are basically hardware configurations for the devices.
+## Key Features
 
-There are currently 3 devices to consider:
-- the node as a whole
-- the router
-- the optical cross connect (OXC)
+- **IBN-over-SDN Architecture:** Separates intent handling into its own dedicated framework, utilizing the underlying SDN controller strictly as a device driver for physical deployment.
+- **Intent DAGs & Delegation:** Uses Directed Acyclic Graphs (DAGs) to represent relationships between different intents, linking logical objectives to low-level resource allocations. If an intent spans multiple domains, it can be securely delegated to adjacent domains.
+- **Event-Based Simulations:** Provides a hackable interface designed to accelerate algorithmic research and conduct (event-based) simulations under diverse scenarios.
+- **Visualizations:** The companion package `MINDFulMakie.jl` offers out-of-the-box visualizations for intent DAGs and network topologies.
 
-For each of those devices a LLI is corresponding
-
-MINDFul.jl was rewritten. Better docs soon.
+MINDFul.jl provides the foundation to develop experimental intent system architectures and customized algorithms to advance the adaptation of IBN in modern multi-domain networks.