Merge pull request #8 from una-auxme/dev

Updated docs & Project.toml
una-auxme · Apr 10, 2024 · 9e09662 · 9e09662 · JulianTrommer · Apr 10, 2024
2 parents d566d1b + ff80624
commit 9e09662
Show file tree

Hide file tree

Showing 7 changed files with 36 additions and 17 deletions.
diff --git a/Project.toml b/Project.toml
@@ -1,7 +1,7 @@
 name = "MeshGraphNets"
 uuid = "f7b4726d-4195-44ab-b39c-37bbdadae004"
 authors = ["JT <julian.trommer@uni-a.de>"]
-version = "0.2.0"
+version = "0.3.0"
 
 [deps]
 CUDA = "052768ef-5323-5732-b1bb-66c8b64840ba"

diff --git a/docs/make.jl b/docs/make.jl
@@ -28,7 +28,8 @@ makedocs(sitename = "MeshGraphNets.jl",
                 "CylinderFlow" => "cylinder_flow.md"
             ],
             "Reference" => [
-                "Training Strategies" => "strategies.md"
+                "Training Strategies" => "strategies.md",
+                "Utilities" => "util.md",
                 "GraphNetCore.jl" => "graph_net_core.md"
             ]
         ]

diff --git a/docs/src/overview.md b/docs/src/overview.md
@@ -16,4 +16,5 @@ References for training strategies and the core package [*GraphNetCore.jl*](http
 **Reference**
 
 - [Training Strategies](https://una-auxme.github.io/MeshGraphNets.jl/dev/strategies): Different training strategies that can be used for training.
+- [Utilities](https://una-auxme.github.io/MeshGraphNets.jl/dev/util): Utility functions for better user experience.
 - [GraphNetCore.jl](https://una-auxme.github.io/MeshGraphNets.jl/dev/graph_net_core): Documentation of the core package.
diff --git a/docs/src/train_eval.md b/docs/src/train_eval.md
@@ -1,4 +1,4 @@
-# Training and evaluating the system
+# Training and Evaluating the System
 
 ```@docs
 train_network

diff --git a/docs/src/training_data.md b/docs/src/training_data.md
@@ -7,11 +7,10 @@ If you want to train your own network via *MeshGraphNets.jl* you have to provide
 Your files have to be placed inside the same folder so that *MeshGraphNets.jl* can find them. The structure of your files should for example look like this:
 
     - data
-        - datasets
-            - meta.json
-            - test.h5 (or test.tfrecord)
-            - train.h5 (or train.tfrecord)
-            - valid.h5 (or valid.tfrecord)
+      - meta.json
+      - test.h5 (or test.tfrecord)
+      - train.h5 (or train.tfrecord)
+      - valid.h5 (or valid.tfrecord)
 
 ## Files for Training, Evaluation and Testing
 
@@ -33,6 +32,8 @@ Your data files should have the following structure:
   - ...
 - ...
 
+The name of the trajectories can be chosen arbitrarily whereas the keys of the features have to match the ones provided in the metadata file (see [File for Metadata](#file-for-metadata-metajson)).
+
 ## File for Metadata (`meta.json`)
 
 Your metadata file also has to follow a defined structure. Since the metadata file for the [CylinderFlow](https://una-auxme.github.io/MeshGraphNets.jl/dev/cylinder_flow) example is handled differently, two files are explained in the following.
@@ -49,6 +50,11 @@ The default structure that you should use for your metadata is the following (ex
         5,
         3
     ],
+    "edges": {                                  # minimum and maximum value of edge features (optional)
+      "data_min": -0.2,
+      "data_max": 0.2
+    },
+    "no_edges_node_types": [],                  # node types that should not have a connection inside the mesh (optional)
     "feature_names": [                          # names of all features, mesh_pos and node_type are required
         "mesh_pos",
         "node_type",
@@ -78,21 +84,25 @@ The default structure that you should use for your metadata is the following (ex
             "key": "cl_mesh[%d,%d].velocity",
             "dim": 2,
             "type": "dynamic",
-            "dtype": "float32"
+            "dtype": "float32",
+            "output_min": -0.25,                # minimum value of the derivative of the feature (optional, required if "data_max" specified)
+            "output_max": 0.75                  # maximum value of the derivative of the feature (optional, required if "data_min" specified)
         }
     }
 }
 ```
 
 Here is a detailed description of each possible metadata:
 
-| Metadata            | Data type       | Description                                                                                    |
-|---------------------|-----------------|------------------------------------------------------------------------------------------------|
-| `"dt"`                | String          | each trajectory needs to have an entry for timesteps with the given key                      |
-| `"trajectory_length"` | Integer         | each trajectory needs to have the same length i.e. the same amount of steps                  |
-| `"dims"`              | Vector{Integer} | dimensions can be 1-, 2- or 3-dimensional                                                    |
-| `"feature_names"`     | Vector{String}  | list all features that are also used as an input of the network                              |
-| `"target_features"`   | Vector{String}  | list all features that the network should predict, they have to be part of `"feature_names"` |
+| Metadata                | Data type       | Description                                                                                    |
+|-------------------------|-----------------|------------------------------------------------------------------------------------------------|
+| `"dt"`                  | String          | each trajectory needs to have an entry for timesteps with the given key                        |
+| `"trajectory_length"`   | Integer         | each trajectory needs to have the same length i.e. the same amount of steps                    |
+| `"dims"`                | Vector{Integer} | dimensions can be 1-, 2- or 3-dimensional                                                      |
+| `"edges"`               | -               | if you specify `"data_min"` and `"data_max"`, offline normalization is used, online otherwise  |
+| `"no_edges_node_types"` | Vector{Integer} | if you want to exclude node types from the mesh, include them here
+| `"feature_names"`       | Vector{String}  | list all features that are also used as an input of the network                                |
+| `"target_features"`     | Vector{String}  | list all features that the network should predict, they have to be part of `"feature_names"`   |
 
 Each feature has its own metadata:
 
@@ -108,6 +118,8 @@ Each feature has its own metadata:
 | `"data_max"`       | Float   | see `"data_min"`                                                                                     |
 | `"target_min"`     | Float   | equivalent to `"data_min"` and `"data_max"`, specifies interval for normalization target             |
 | `"target_max"`     | Float   | see `"target_min"`                                                                                   |
+| `"output_min"`     | Float   | equivalent to `"data_min"` and `data_max`, specifices the interval of the derivative of the feature  |
+| `"output_max"`     | Float   | see `"output_min"`                                                                                   |
 
 The structure for the `HDF5` key has to follow one rule:
 

diff --git a/docs/src/util.md b/docs/src/util.md
@@ -0,0 +1,5 @@
+# Utility Functions 
+
+```@docs
+der_minmax
+```
diff --git a/src/MeshGraphNets.jl b/src/MeshGraphNets.jl
@@ -169,7 +169,7 @@ Starts the training process with the given configuration.
 - `cell_idxs = [0]`: Indices of cells that are plotted during validation (if enabled).
 - `solver_valid = Tsit5()`: Which solver should be used for validation during training.
 - `solver_valid_dt = nothing`: If set, the solver for validation will use fixed timesteps.
-- `wandb_logger` = nothing: If set, a [Wandb.WandbLogger](@ref) will be used for logging the training.
+- `wandb_logger` = nothing: If set, a [Wandb](https://github.com/avik-pal/Wandb.jl) WandbLogger will be used for logging the training.
 
 ## Training Strategies
 - `Collocation`