panic/include/neural_network/model/model.hpp

/**++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 *
 *                                              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 <config/types.hpp>                     // panic::types::uint_t, int_t and real_t
#include <tensor/matrix.hpp>                    // panic::tensor::real_matrix

#include <neural_network/layer/layer.hpp>       // Base layer struct
#include <neural_network/layer/layer_dense.hpp> // fully connected dense layer

//---------------------------------------------------------------------------------------------------------------------------
// 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 a pointer to a pointer of layers
     *
     *      An example:
     *          layers[0] points to a layer_dense
     *          layers[1] points to an actication function
     *          layers[2] points to another layer_dense
     * 
     * @note The model owns these layers and deletes them in clear().
     * 
     */
    layer** layers;

    // Number of layers currently stored in the model.
    /**
     * @brief Stores the number of layers
     *
     */
    panic::types::uint_t layer_count;

    // model output (may be deleted and also used for debug)
    panic::tensor::real_matrix outputs;

    /**
     * @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* new_layer);

    // Create and add a dense 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 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);

    // Delete all layers and reset the model.

    /**
     * @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