Updated Documentation

jaywyawhare · jaywyawhare · commit 8944728f8fa2 · 2025-03-29T09:47:33.000+05:30
diff --git a/docs/README.md b/docs/README.md
@@ -35,7 +35,7 @@ C-ML is a lightweight and modular machine learning library designed for educatio
 
 - **Layers**: Dense, Dropout
 - **Activations**: ReLU, Sigmoid, Tanh, Softmax, ELU, Leaky ReLU, Linear
-- **Loss Functions**: Mean Squared Error, Binary Cross-Entropy, Focal Loss, etc.
+- **Loss Functions**: Mean Squared Error, Binary Cross-Entropy, Focal Loss, Huber Loss, KLD Loss, Log-Cosh Loss, Poisson Loss, Smooth L1 Loss, Tversky Loss, Cosine Similarity Loss, etc.
 - **Optimizers**: SGD, Adam, RMSprop
 - **Preprocessing**: Label Encoding, One-Hot Encoding, Standard Scaler, Min-Max Scaler
 - **Regularizers**: L1, L2, Combined L1-L2
@@ -103,39 +103,78 @@ C-ML/
 
 ## Usage
 
-The `main.c` file demonstrates how to use the library to create a simple neural network. Below is an example:
+The `main.c` file demonstrates how to use the library to create a simple neural network with a dense layer, ReLU activation, and mean squared error loss.
 
 ```c
 #include <stdio.h>
 #include <stdlib.h>
-#include <math.h>
-#include "../src/Layers/dense.h"
-#include "../src/Activations/relu.h"
-#include "../src/Loss_Functions/meanSquaredError.h"
+#include <time.h>
+#include "include/Core/training.h"
 
 int main()
 {
-    float input[] = {1.0, 2.0, 3.0};
-    int input_size = 3;
+    srand(time(NULL));
+    NeuralNetwork *network = create_neural_network(2);
 
-    float target[] = {0.0, 1.0};
-    int output_size = 2;
+    build_network(network, OPTIMIZER_ADAM, 0.01f, LOSS_MSE, 0.0f, 0.0f);
+    model_add(network, LAYER_DENSE, ACTIVATION_RELU, 2, 4, 0.0f, 0, 0);
+    model_add(network, LAYER_DENSE, ACTIVATION_TANH, 4, 4, 0.0f, 0, 0);
+    model_add(network, LAYER_DENSE, ACTIVATION_SIGMOID, 4, 1, 0.0f, 0, 0);
 
-    DenseLayer dense_layer = {NULL, NULL, 0, 0};
-    initializeDense(&dense_layer, input_size, output_size);
+    int num_samples = 4;
+    float **X_train = (float **)cm_safe_malloc(num_samples * sizeof(float *), __FILE__, __LINE__);
+    float **y_train = (float **)cm_safe_malloc(num_samples * sizeof(float *), __FILE__, __LINE__);
 
-    float dense_output[2];
-    forwardDense(&dense_layer, input, dense_output);
+    for (int i = 0; i < num_samples; i++)
+    {
+        X_train[i] = (float *)cm_safe_malloc(2 * sizeof(float), __FILE__, __LINE__);
+        y_train[i] = (float *)cm_safe_malloc(1 * sizeof(float), __FILE__, __LINE__);
+    }
+
+    X_train[0][0] = 0.0f;
+    X_train[0][1] = 0.0f;
+    y_train[0][0] = 0.0f;
+    X_train[1][0] = 0.0f;
+    X_train[1][1] = 1.0f;
+    y_train[1][0] = 1.0f;
+
+    X_train[2][0] = 1.0f;
+    X_train[2][1] = 0.0f;
+    y_train[2][0] = 1.0f;
+
+    X_train[3][0] = 1.0f;
+    X_train[3][1] = 1.0f;
+    y_train[3][0] = 1.0f;
+
+    summary(network);
+    train_network(network, X_train, y_train, num_samples, 2, 1, 1, 300);
+
+    MetricType metrics[] = {METRIC_R2_SCORE};
 
-    for (int i = 0; i < output_size; i++)
+    int num_metrics = sizeof(metrics) / sizeof(metrics[0]);
+    float results[num_metrics];
+
+    test_network(network, X_train, y_train, num_samples, 2, 1, (int *)metrics, num_metrics, results);
+    printf("R2 Score: %.2f\n", results[0]);
+
+    for (int i = 0; i < num_samples; i++)
     {
-        dense_output[i] = relu(dense_output[i]);
+        float prediction = 0.0f;
+        forward_pass(network, X_train[i], &prediction, 2, 1, 0);
+        printf("Input: [%.0f, %.0f], Expected: %.0f, Predicted: %.4f\n",
+               X_train[i][0], X_train[i][1], y_train[i][0], prediction);
     }
 
-    float loss = meanSquaredError(target, dense_output, output_size);
-    printf("Loss: %f\n", loss);
+    free_neural_network(network);
+
+    for (int i = 0; i < num_samples; i++)
+    {
+        cm_safe_free((void **)&X_train[i]);
+        cm_safe_free((void **)&y_train[i]);
+    }
+    cm_safe_free((void **)&X_train);
+    cm_safe_free((void **)&y_train);
 
-    freeDense(&dense_layer);
     return 0;
 }
 ```
@@ -248,15 +287,10 @@ Each module has a corresponding test file in the `test/` directory. The tests va
 
 ## Contributing
 
-Contributions are welcome! Please follow these steps:
-
-1. Fork the repository.
-2. Create a new branch for your feature or bug fix.
-3. Commit your changes with clear messages.
-4. Submit a pull request.
+Contributions are welcome! Feel free to open issues or submit pull requests.
 
 ---
 
 ## License
 
-This project is licensed under the DBaJ-NC-CFL License. See the [LICENSE](../LICENCE.md) file for details.
+This project is licensed under the DBaJ-NC-CFL [License](./LICENCE.md).
diff --git a/docs/modules/core.md b/docs/modules/core.md
@@ -0,0 +1,29 @@
+# Core Modules
+
+This section documents the core modules of the C-ML library, which provide essential functionalities for building and training neural networks.
+
+## Training Module
+
+- **Description**: Provides functions for creating, building, training, and evaluating neural networks.
+- **Functions**:
+    - `NeuralNetwork *create_neural_network(int input_size)`: Creates a new neural network.
+    - `CM_Error build_network(NeuralNetwork *network, OptimizerType optimizer_type, float learning_rate, int loss_function, float l1_lambda, float l2_lambda)`: Builds the neural network by setting the optimizer, loss function, and regularization parameters.
+    - `CM_Error add_layer(NeuralNetwork *network, LayerConfig config)`: Adds a layer to the neural network.
+    - `CM_Error model_add(NeuralNetwork *network, LayerType type, ActivationType activation, int input_size, int output_size, float rate, int kernel_size, int stride)`: Adds a layer to the neural network using a simplified interface.
+    - `CM_Error forward_pass(NeuralNetwork *network, float *input, float *output, int input_size, int output_size, int is_training)`: Performs a forward pass through the network.
+    - `float calculate_loss(float *predicted, float *actual, int size, LossType loss_type)`: Calculates the loss between predicted and actual values.
+    - `void calculate_loss_gradient(float *predicted, float *actual, float *gradient, int size, LossType loss_type)`: Calculates the gradient of the loss function.
+    - `CM_Error train_network(NeuralNetwork *network, float **X_train, float **y_train, int num_samples, int input_size, int output_size, int batch_size, int epochs)`: Trains the neural network.
+    - `CM_Error evaluate_network(NeuralNetwork *network, float **X_test, float **y_test, int num_samples, int input_size, int output_size, int *metrics, int num_metrics, float *results)`: Evaluates the neural network on a given dataset.
+    - `CM_Error test_network(NeuralNetwork *network, float **X_test, float **y_test, int num_samples, int input_size, int output_size, int *metrics, int num_metrics, float *results)`: Tests the neural network (alias for evaluate_network).
+    - `CM_Error free_neural_network(NeuralNetwork *network)`: Frees memory allocated for the neural network.
+    - `void summary(NeuralNetwork *network)`: Prints a summary of the neural network architecture.
+- **File**: [`training.c`](https://github.com/jaywyawhare/C-ML/tree/master/src/Core/training.c)
+
+## Memory Management Module
+
+- **Description**: Provides safe memory allocation and deallocation functions.
+- **Functions**:
+    - `void *cm_safe_malloc(size_t size, const char *file, int line)`: Allocates memory safely and logs the file and line number in case of failure.
+    - `void cm_safe_free(void **ptr)`: Frees allocated memory safely and sets the pointer to NULL.
+- **File**: [`memory_management.c`](https://github.com/jaywyawhare/C-ML/tree/master/src/Core/memory_management.c)
diff --git a/docs/modules/loss_functions.md b/docs/modules/loss_functions.md
@@ -34,3 +34,38 @@
 - **Description**: Computes the mean of an array of values.
 - **Function**: `reduce_mean(float *loss, int size)`
 - **File**: [`reduce_mean.c`](https://github.com/jaywyawhare/C-ML/tree/master/src/Loss_Functions/reduce_mean.c)
+
+## Huber Loss
+- **Description**: Huber Loss function.
+- **Function**: `huber_loss(float *y, float *yHat, int n)`
+- **File**: [`huber_loss.c`](https://github.com/jaywyawhare/C-ML/tree/master/src/Loss_Functions/huber_loss.c)
+
+## KLD Loss
+- **Description**: Kullback-Leibler Divergence Loss function.
+- **Function**: `kld_loss(float *p, float *q, int n)`
+- **File**: [`kld_loss.c`](https://github.com/jaywyawhare/C-ML/tree/master/src/Loss_Functions/kld_loss.c)
+
+## Log-Cosh Loss
+- **Description**: Log-Cosh Loss function.
+- **Function**: `log_cosh_loss(float *y, float *yHat, int n)`
+- **File**: [`log_cosh_loss.c`](https://github.com/jaywyawhare/C-ML/tree/master/src/Loss_Functions/log_cosh_loss.c)
+
+## Poisson Loss
+- **Description**: Poisson Loss function.
+- **Function**: `poisson_loss(float *y, float *yHat, int n)`
+- **File**: [`poisson_loss.c`](https://github.com/jaywyawhare/C-ML/tree/master/src/Loss_Functions/poisson_loss.c)
+
+## Smooth L1 Loss
+- **Description**: Smooth L1 Loss function.
+- **Function**: `smooth_l1_loss(float *y, float *yHat, int n)`
+- **File**: [`smooth_l1_loss.c`](https://github.com/jaywyawhare/C-ML/tree/master/src/Loss_Functions/smooth_l1_loss.c)
+
+## Tversky Loss
+- **Description**: Tversky Loss function.
+- **Function**: `tversky_loss(float *y, float *yHat, int n)`
+- **File**: [`tversky_loss.c`](https://github.com/jaywyawhare/C-ML/tree/master/src/Loss_Functions/tversky_loss.c)
+
+## Cosine Similarity Loss
+- **Description**: Cosine Similarity Loss function.
+- **Function**: `cosine_similarity_loss(float *y, float *yHat, int n)`
+- **File**: [`cosine_similarity_loss.c`](https://github.com/jaywyawhare/C-ML/tree/master/src/Loss_Functions/cosine_similarity_loss.c)
diff --git a/docs/modules/metrics.md b/docs/modules/metrics.md
@@ -0,0 +1,92 @@
+# Metrics
+
+## Accuracy
+- **Description**: Calculates the accuracy of the model.
+- **Function**: `accuracy(float *y, float *yHat, int n)`
+- **File**: [`accuracy.c`](https://github.com/jaywyawhare/C-ML/tree/master/src/Metrics/accuracy.c)
+
+---
+
+## Balanced Accuracy
+- **Description**: Calculates the balanced accuracy of the model.
+- **Function**: `balanced_accuracy(float *y, float *yHat, int n)`
+- **File**: [`balanced_accuracy.c`](https://github.com/jaywyawhare/C-ML/tree/master/src/Metrics/balanced_accuracy.c)
+
+---
+
+## Cohen's Kappa
+- **Description**: Calculates Cohen's Kappa coefficient.
+- **Function**: `cohens_kappa(float *y, float *yHat, int n)`
+- **File**: [`cohens_kappa.c`](https://github.com/jaywyawhare/C-ML/tree/master/src/Metrics/cohens_kappa.c)
+
+---
+
+## F1 Score
+- **Description**: Calculates the F1 score of the model.
+- **Function**: `f1_score(float *y, float *yHat, int n)`
+- **File**: [`f1_score.c`](https://github.com/jaywyawhare/C-ML/tree/master/src/Metrics/f1_score.c)
+
+---
+
+## IOU (Intersection over Union)
+- **Description**: Calculates the Intersection over Union.
+- **Function**: `iou(float *y, float *yHat, int n)`
+- **File**: [`iou.c`](https://github.com/jaywyawhare/C-ML/tree/master/src/Metrics/iou.c)
+
+---
+
+## MCC (Matthews Correlation Coefficient)
+- **Description**: Calculates the Matthews Correlation Coefficient.
+- **Function**: `mcc(float *y, float *yHat, int n)`
+- **File**: [`mcc.c`](https://github.com/jaywyawhare/C-ML/tree/master/src/Metrics/mcc.c)
+
+---
+
+## Mean Absolute Error
+- **Description**: Calculates the Mean Absolute Error.
+- **Function**: `mean_absolute_error(float *y, float *yHat, int n)`
+- **File**: [`mean_absolute_error.c`](https://github.com/jaywyawhare/C-ML/tree/master/src/Metrics/mean_absolute_error.c)
+
+---
+
+## Mean Absolute Percentage Error
+- **Description**: Calculates the Mean Absolute Percentage Error.
+- **Function**: `mean_absolute_percentage_error(float *y, float *yHat, int n)`
+- **File**: [`mean_absolute_percentage_error.c`](https://github.com/jaywyawhare/C-ML/tree/master/src/Metrics/mean_absolute_percentage_error.c)
+
+---
+
+## Precision
+- **Description**: Calculates the precision of the model.
+- **Function**: `precision(float *y, float *yHat, int n)`
+- **File**: [`precision.c`](https://github.com/jaywyawhare/C-ML/tree/master/src/Metrics/precision.c)
+
+---
+
+## R2 Score
+- **Description**: Calculates the R2 score (coefficient of determination).
+- **Function**: `r2_score(float *y_true, float *y_pred, int size)`
+- **File**: [`r2_score.c`](https://github.com/jaywyawhare/C-ML/tree/master/src/Metrics/r2_score.c)
+
+---
+
+## Recall
+- **Description**: Calculates the recall of the model.
+- **Function**: `recall(float *y, float *yHat, int n)`
+- **File**: [`recall.c`](https://github.com/jaywyawhare/C-ML/tree/master/src/Metrics/recall.c)
+
+---
+
+## Root Mean Squared Error
+- **Description**: Calculates the Root Mean Squared Error.
+- **Function**: `root_mean_squared_error(float *y, float *yHat, int n)`
+- **File**: [`root_mean_squared_error.c`](https://github.com/jaywyawhare/C-ML/tree/master/src/Metrics/root_mean_squared_error.c)
+
+---
+
+## Specificity
+- **Description**: Calculates the Specificity.
+- **Function**: `Specificity(float *y, float *yHat, int n)`
+- **File**: [`Specificity.c`](https://github.com/jaywyawhare/C-ML/tree/master/src/Metrics/Specificity.c)
+
+---
diff --git a/docs/usage.md b/docs/usage.md
diff --git a/mkdocs.yml b/mkdocs.yml
