/**++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ * * PANIC * Portable Algorithms and Numerics In C++ * * Scientific computing from scratch, with feeling. * * Copyright (c) 2026 Michelle Bausager * * This file is part of PANIC. * * PANIC is free software licensed under the GNU General Public License v3.0 or later. * You may redistribute and/or modify it under the terms of the GPL. * * PANIC is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; * without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. * See the LICENSE file for the full license text. * * SPDX-License-Identifier: GPL-3.0-or-later * *++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ * * Project Name: PANIC * Module Name: neural_network * File Name: model.hpp * Revision: 0.1.0 * Date: 25-06-2026 * Author: Michelle Bausager * * Description: * Defines the base model struct used in in neural network * *++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++*/ #pragma once //--------------------------------------------------------------------------------------------------------------------------- // INCLUDE DESCRIPTION //--------------------------------------------------------------------------------------------------------------------------- #include // panic::types::uint_t, int_t and real_t #include // panic::tensor::real_matrix #include // Base layer struct #include #include // fully connected dense layer #include #include #include #include //--------------------------------------------------------------------------------------------------------------------------- // TYPE DESCRIPTION //--------------------------------------------------------------------------------------------------------------------------- namespace panic{ namespace neural_network{ /** * @brief Basic neural network model. * * The model owns an array of layer pointers * * @note * layer_count stores how many layers the model currently has. * * layers is a "pointer to pointers" -> layer** layers; * That means it points to an array where each element is a layer* * * The struct is used for PANIC neural_network library. */ struct model{ /** * @brief Array of pointers to all model layers. * * Example: * layers[0] points to a layer_dense * layers[1] points to an activation_ReLU * layers[2] points to another layer_dense * * @note The model owns every object referenced by this array. * clear() deletes each layer and then deletes the array. */ layer** layers; /** * @brief Number of layers currently stored in layers. */ panic::types::uint_t layer_count; /** * @brief Array of pointers to the trainable layers. * * @note These pointers refer to objects already owned through layers. * Do not delete the individual objects through this array. * Only the pointer array itself is owned separately. */ trainable_layer** trainable_layers; /** * @brief Number of trainable-layer pointers. */ panic::types::uint_t trainable_layer_count; /** * @brief Configured loss function. * * @note The model owns this object and deletes it in clear(). */ loss* loss_function; /** * @brief Configured optimizer. * * @note The model owns this object and deletes it in clear(). */ optimizer* optimizer_function; /** * @brief Optimized backward helper for the combination of * Softmax and categorical cross-entropy. * * This is a normal member object, not a dynamically allocated object. */ activation_softmax_loss_categorical_crossentropy softmax_classifier_output; /** * @brief Whether the optimized Softmax + categorical * cross-entropy backward path should be used. */ bool use_softmax_classifier_output; /** * @brief Output of the final model layer. */ panic::tensor::real_matrix outputs; /** * @brief Gradient with respect to the model input. */ panic::tensor::real_matrix dinputs; /** * @brief Empthy constructor * */ model(); /** * @brief De-constructor * * @note Calls clear() to delete all layers and releases the layer pointer array * */ ~model(); // Add an already-created layer to the model. // Helper function for e.g. model.add_dense(5,5) /** * @brief Helper function for adding layers * * Computes: * @code * layer_dense* new_layer = new layer_dense(3, 4); * add(new_layer) * @endcode * * @note it adds an already-inplemented layer to the model. * */ bool add_layer(layer* new_layer); /** * @brief Helper function for adding layers * * Computes: * @code * layer_dense* new_layer = new layer_dense(3, 4); * add(new_layer) * @endcode * * @note it adds an already-inplemented layer to the model. * */ bool add_trainable_layer(trainable_layer* new_layer); /** * @brief Adds a dense layer to the model. * * Computes: * @code * model.add_layer_dense(3,4); * @endcode * * @param inputs_size Input size of the data. * @param neuron_count Number of neurons in the layer. * * @return true if layer is added * * @note This function is convenient, but it allocates a new layer. */ bool add_layer_dense( panic::types::uint_t input_size, panic::types::uint_t neuron_count ); /** * @brief Adds a activation ReLU layer to the model. * * Computes: * @code * model.add_activation_relu(3,4); * @endcode * * * @return true if layer is added * * @note This function is convenient, but it allocates a new layer. */ bool add_activation_relu(); /** * @brief Adds a activation Softmax layer to the model. * * Computes: * @code * model.add_activation_softmax(3,4); * @endcode * * * @return true if layer is added * * @note This function is convenient, but it allocates a new layer. */ bool add_activation_softmax(); /** * @brief Loops over all layers forward function * * Computes: * @code * model.forward(input_data_matrix) * @endcode * * @param inputs Input data. * * @return true looped over every layer. * * @note It takes the privious layer outputs and uses it as * the next layers input in the forward function. * */ bool forward(const panic::tensor::real_matrix& inputs); /** * @brief Loops over all layers backward function * * Computes: * @code * model.backward(model_output, y_true_values) * @endcode * * @param output Model output. * @param y_true True values for data. * * @return true looped over every layer. * */ bool backward(const panic::tensor::real_matrix& output, const panic::tensor::uint_vector& y_true); /** * @brief Loops over all layers backward function * * Computes: * @code * model.backward(model_output, y_true_values) * @endcode * * @param output Model output. * @param y_true True values for data. * * @return true looped over every layer. * */ bool backward(const panic::tensor::real_matrix& output, const panic::tensor::real_matrix& y_true); /** * @brief Add loss for categorical crossentropy. * * Computes: * @code * model.add_loss_categorical_crossentropy(); * @endcode * * * @return true if loss is added * * @note This function is convenient, but it allocates a new layer. */ bool add_loss_categorical_crossentropy(); /** * @brief Adds optimizer_sgd to the model * * Computes: * @code * model.optimizer_sgd(1e-4) * @endcode * * @param learning_rate Learning rate for update_param (default 1e-3). * * @return true If looped and optimized every trainable layer. * * */ bool add_optimizer_sgd(const panic::types::real_t learning_rate = static_cast(1)); /** * @brief Finalizes the model configuration. * * Detects whether the model can use the optimized * Softmax + categorical-cross-entropy backward pass. * * @return true if the model configuration is valid. */ bool finalize(); /** * @brief Optimizes the model with parameters on trainable layers * * Computes: * @code * model.optimize() * @endcode * * @return true if optimization is done correctly. * */ bool optimize(); /** * @brief Trains the model with input data * * Computes: * @code * model.backward(input_data_matrix) * @endcode * * @param X_train Input X data for training. * @param epochs Number of training iterations. * @param print_every Prints every n iteration. * * * @return true if training is done correctly. * * */ bool train(const panic::tensor::real_matrix& X_train, const panic::tensor::uint_vector& y_train, const panic::types::uint_t epochs, const panic::types::uint_t print_every); /** * @brief Clears and deletes all layers and resets the model * * Computes: * @code * model.clear(); * @endcode * * @note Primary used in the de-construtor. * */ void clear(); }; } // namespace neural_network } // namespace panic