Update README.md

README.md

@@ -2,11 +2,13 @@
 license: gpl-3.0
 ---
 
-# Model Card for ClotSimNet
+# Model Card for PoreSimNet
 
 <!-- Provide a quick summary of what the model is/does. -->
 
-This is the HuggingFace storage location for all of the models for the ClotSimNet project. They include several base models as well as their tuned variants. All models were trained in PyTorch.
+This is the HuggingFace storage location for all of the models for the PoreSimNet project. They include several base models as well as their tuned variants. All models were trained in PyTorch.
+
+The PoreSimNet GitHub repository can be found [here](https://github.com/flowlabcu/ClotSimNet).
 
 ## Model Details
 
@@ -15,20 +17,15 @@ This is the HuggingFace storage location for all of the models for the ClotSimNe
 There are several models that were trained on the ClotSimNet dataset:
 
 * EfficientNet (B0, B3, B7)
-* ResNet (50, 152)
-* ConvNeXt-Large
+* ResNet (18, 50, 152)
+* ConvNeXt-Tiny
 
-<!-- Provide a longer summary of what this model is. -->
+The EfficientNet and ResNet models were chosen due to their precedence in the biomedical imaging field. ConvNeXt-Tiny was selected to explore a new architecture based on vision transformers to assess its performance relative to the more conventional CNN architectures.
 
 
 
 - **Developed by:** Josh Gregory
-- **Funded by [optional]:** [More Information Needed]
-- **Shared by [optional]:** [More Information Needed]
-- **Model type:** [More Information Needed]
-- **Language(s) (NLP):** [More Information Needed]
-- **License:** [More Information Needed]
-- **Finetuned from model [optional]:** [More Information Needed]
+
 
 ### Model Sources [optional]
 
@@ -36,106 +33,44 @@ Each model was imported using the instructions from the [PyTorch documentation](
 
 * [EfficientNet](https://proceedings.mlr.press/v97/tan19a.html)
 * [ResNet](https://ieeexplore.ieee.org/document/7780459)
-* [ConvNeXt-Large](https://ieeexplore.ieee.org/document/9879745)
+* [ConvNeXt-Tiny](https://ieeexplore.ieee.org/document/9879745)
 
 ## Uses
 
 These models are intended to be used to predict permeabilities from porous simulations, such as those found in blood clots or other porous media. The training set was exclusively computational fluid dynamics (CFD) simulations of blood clots, however these models could be fine-tuned on other porous media datasets.
 
-<!-- Address questions around how the model is intended to be used, including the foreseeable users of the model and those affected by the model. -->
-
 ### Direct Use
 
-<!-- This section is for the model use without fine-tuning or plugging into a larger ecosystem/app. -->
-
-[More Information Needed]
-
-### Downstream Use [optional]
-
-<!-- This section is for the model use when fine-tuned for a task, or when plugged into a larger ecosystem/app -->
-
-[More Information Needed]
+These models are intended to predict permeability of porous media in environments with low Reynolds numbers (Re < 10).
 
 ### Out-of-Scope Use
 
-As of this publication, these models are not intended to treat, diagnose, or prevent any disease. They have not been approved by the FDA and are not intended for clinical or human use.
+As of this publication, these models are not intended to treat, diagnose, or prevent any disease and have not been approved by the FDA.
 
 ## How to Get Started with the Model
 
-There are two flavors of each model. The base variants all had the same learning rate, weight decay, etc. Specifically for the CNNs:
-
-* Learning rate: 1e-3
-* Weight decay: 1e-5
-* Kernel size: 3
-* Stride: 2
-* Padding: 1
-* Use ImageNet pre-trained weights: True
-* Batch size: 2
-* Num workers: 70
-* Epochs: 500
-* Use image augmentation transforms: True
-* Learning rate reduction factor: 0.1
-* Learning rate reduction patience: 10
-* Learning rate reduction threshold: 1e-4
-
-For the MLPs, obviously things like the stride and padding are not applicable. Instead, the number of neurons per hidden layer and the number of hidden layers were set as:
+Each model was exported in [ONNX](https://onnx.ai/) (`.onnx`) and [Safetensors](https://huggingface.co/docs/safetensors/index) (`.safetensors`).
 
-* Number of hidden layers: 3
-* Size of each hidden layer: 128
-
-Each model was exported in [ONNX](https://onnx.ai/) (`.onnx`) and [Safetensors](https://huggingface.co/docs/safetensors/index) (`.safetensors`). 
+See the `inference_examples` directory for how to inference these models in safetensors format. For futher examples in ONNX, refer to the GitHub repository, with examples located in the path `/poresimnet/ml/inference`.
 
 ### Loading the Models
 
-To import the ONNX (`.onnx`) file:
-
-```python
-import onnx
-import onnxruntime as ort
-import numpy as np
-
-
-# Load ONNX model
-model = onnx.load('path_to_model/model.onnx')
-
-# Validate model
-onnx.checker.check_model(onnx_model)
-
-# Create an inference session
-session = ort.InferenceSession('path_to_model/model.onnx')
-```
-
-TODO: Update inference to work with images
-
-
-[More Information Needed]
+See the `inference_examples` directory. Models in the safetensors format were used the most for internal inference work.
 
 ## Training Details
 
 ### Training Data
 
-<!-- This should link to a Dataset Card, perhaps with a short stub of information on what the training data is all about as well as documentation related to data pre-processing or additional filtering. -->
-
-[More Information Needed]
+All of the data can be found [here](link to Dataset card once it becomes public). Refer to the Dataset card to find the relevant training data, as different kinds exist.
 
 ### Training Procedure
 
-<!-- This relates heavily to the Technical Specifications. Content here should link to that section when it is relevant to the training procedure. -->
-
-#### Preprocessing [optional]
-
-[More Information Needed]
+All models were trained for 350 epochs with an early stopping patience of 70 epochs. Each model was then hyperparameter tuned for 24 hours and retrained with its tuned hyperparameters. For base hyperparameters, refer to each model's class in the `model_classes` directory.
 
 
 #### Training Hyperparameters
 
-- **Training regime:** [More Information Needed] <!--fp32, fp16 mixed precision, bf16 mixed precision, bf16 non-mixed precision, fp16 non-mixed precision, fp8 mixed precision -->
-
-#### Speeds, Sizes, Times [optional]
-
-<!-- This section provides information about throughput, start/end time, checkpoint size if relevant, etc. -->
-
-[More Information Needed]
+All models were trained in bf16 mixed precision and were tuned for 24 hours on an NVIDIA GH200.
 
 ## Evaluation
 
@@ -147,13 +82,7 @@ TODO: Update inference to work with images
 
 <!-- This should link to a Dataset Card if possible. -->
 
-[More Information Needed]
-
-#### Factors
-
-<!-- These are the things the evaluation is disaggregating by, e.g., subpopulations or domains. -->
-
-[More Information Needed]
+Refer to the Dataset card to find the relevant testing data, as different kinds exist.
 
 #### Metrics
 
@@ -163,11 +92,11 @@ TODO: Update inference to work with images
 
 ### Results
 
-[More Information Needed]
+The ResNet-50 and ResNet-152 architectures were found to work the best for our task, as they were the only two that were able to generalize between the augmented training data and the un-augmented validation data.
 
 #### Summary
 
-
+The `base` directory contains all trained models with base hyperparameters. The `tuned` directory contains the models after hyperparameter tuning. The `hyperparameters` folder itself contains each model's tuned hyperparameters in a JSON file, and the `inference_examples` directory contains examples for how to inference our models in safetensors format.
 
 ## Model Examination [optional]
 
@@ -183,27 +112,25 @@ Carbon emissions can be estimated using the [Machine Learning Impact calculator]
 
 - **Hardware Type:** [More Information Needed]
 - **Hours used:** [More Information Needed]
-- **Cloud Provider:** [More Information Needed]
-- **Compute Region:** [More Information Needed]
 - **Carbon Emitted:** [More Information Needed]
 
-## Technical Specifications [optional]
+## Technical Specifications
 
 ### Model Architecture and Objective
 
-[More Information Needed]
+Several architectures were considered. Both MLPs and CNNs were selected due to the fundamental difference in which they would estimate permeability. 
 
 ### Compute Infrastructure
 
-[More Information Needed]
+This work utilized the Alpine high performance computing resource at the University of Colorado Boulder. Alpine is jointly funded by the University of Colorado Boulder, the University of Colorado Anschutz, and Colorado State University and with support from NSF grants OAC-2201538 and OAC-2322260
 
 #### Hardware
 
-[More Information Needed]
+A single NVIDIA GH200 was used to train and tune all models, coupling an NVIDIA H100 GPU with the 72-core Grace CPU.
 
 #### Software
 
-[More Information Needed]
+All models were written in PyTorch Lightning.
 
 ## Citation [optional]
 
@@ -227,10 +154,10 @@ Carbon emissions can be estimated using the [Machine Learning Impact calculator]
 
 [More Information Needed]
 
-## Model Card Authors [optional]
+## Model Card Authors
 
-[More Information Needed]
+Josh Gregory
 
 ## Model Card Contact
 
-[More Information Needed]
+Debanjan Mukherjee: debanjan@colorado.edu