From 360c1a217ea5819f55c8b73563d4a27eedc95a95 Mon Sep 17 00:00:00 2001
From: Ewan Miller <ewan.miller@kcl.ac.uk>
Date: Sat, 6 Jul 2024 09:37:04 -0400
Subject: [PATCH] Add main page README and improve doxygen for Tensor a bit

---
 README.md                 |  3 +++
 doc/doxygen.config        |  4 ++--
 nuTens/tensors/tensor.hpp | 45 +++++++++++++++++++++++++++++++++++++++
 3 files changed, 50 insertions(+), 2 deletions(-)
 create mode 100644 README.md

diff --git a/README.md b/README.md
new file mode 100644
index 0000000..367c6af
--- /dev/null
+++ b/README.md
@@ -0,0 +1,3 @@
+# nuTens
+
+A lightweight library for calculating neutrino oscillation probabilities using tensors typically used in machine learning.
\ No newline at end of file
diff --git a/doc/doxygen.config b/doc/doxygen.config
index 0d58458..c3100c5 100644
--- a/doc/doxygen.config
+++ b/doc/doxygen.config
@@ -829,7 +829,7 @@ WARN_LOGFILE           =
 # spaces. See also FILE_PATTERNS and EXTENSION_MAPPING
 # Note: If this tag is empty the current directory is searched.
 
-INPUT                  = ../nuTens
+INPUT                  = ../nuTens ../README.md
 
 # This tag can be used to specify the character encoding of the source files
 # that doxygen parses. Internally doxygen uses the UTF-8 encoding. Doxygen uses
@@ -1022,7 +1022,7 @@ FILTER_SOURCE_PATTERNS =
 # (index.html). This can be useful if you have a project on for instance GitHub
 # and want to reuse the introduction page also for the doxygen output.
 
-USE_MDFILE_AS_MAINPAGE =
+USE_MDFILE_AS_MAINPAGE = ../README.md
 
 #---------------------------------------------------------------------------
 # Configuration options related to source browsing
diff --git a/nuTens/tensors/tensor.hpp b/nuTens/tensors/tensor.hpp
index 4701fac..3854b97 100644
--- a/nuTens/tensors/tensor.hpp
+++ b/nuTens/tensors/tensor.hpp
@@ -11,6 +11,26 @@
 
 class Tensor{
 
+    /*!
+    * @class Tensor
+    * @brief Basic tensor class 
+    * 
+    * Tensor defines a basic interface for creating and manipulating tensors.
+    * To create tensors you should use the Initialisers. These can be used on their own or chained together with the Setters to create the desired tensor.
+    * 
+    * For example 
+    * \code{.cpp}
+    *   Tensor t;
+    *   t.ones({3,3}).dType(NTdtypes::kFloat).device(NTdtypes::kGPU);
+    * \endcode
+    * will get you a 3x3 tensor of floats that lives on the GPU.
+    * This is equivalent to 
+    * \code{.cpp}
+    *   Tensor t;
+    *   t.ones({3,3}, NTdtypes::kFloat, NTdtypes::kGPU);
+    * \endcode
+    */
+
     public:
         /// @name Initialisers
         /// Use these methods to initialise the tensor
@@ -20,19 +40,27 @@ class Tensor{
         /// @arg length The length of the intitalised tensor
         /// @arg type The data type of the initialised tensor
         Tensor& ones(int length, NTdtypes::scalarType type, NTdtypes::deviceType device = NTdtypes::kCPU, bool requiresGrad = true);
+        /// @brief Initialise this tensor with ones
+        /// @arg shape The desired shape of the intitalised tensor
+        /// @arg type The data type of the initialised tensor
         Tensor& ones(const std::vector<long int> &shape, NTdtypes::scalarType type, NTdtypes::deviceType device = NTdtypes::kCPU, bool requiresGrad = true);
 
         /// @brief Initialise this tensor with zeros
         /// @arg length The length of the intitalised tensor
         /// @arg type The data type of the initialised tensor
         Tensor &zeros(int length, NTdtypes::scalarType type, NTdtypes::deviceType device = NTdtypes::kCPU, bool requiresGrad = true);
+        /// @brief Initialise this tensor with zeros
+        /// @arg shape The desired shape of the intitalised tensor
+        /// @arg type The data type of the initialised tensor
         Tensor &zeros(const std::vector<long int> &shape, NTdtypes::scalarType type, NTdtypes::deviceType device = NTdtypes::kCPU, bool requiresGrad = true);
 
         /// @}
 
         /// @name Setters
         /// @{
+        /// @brief Set the underlying data type of this tensor
         Tensor& dType(NTdtypes::scalarType type);
+        /// @brief Set the device that this tensor lives on
         Tensor& device(NTdtypes::deviceType device);
         /// @}
 
@@ -44,11 +72,28 @@ class Tensor{
         /// @arg t1 Left hand tensor
         /// @arg t2 Right hand tensor
         static Tensor matmul(const Tensor &t1, const Tensor &t2);
+        
+        /// @brief Scale a matrix by some scalar
+        /// @arg s The scalar
+        /// @arg t The tensor
+        static Tensor scale(float s, const Tensor &t);
+        /// @brief Scale a matrix by some complex scalar
+        /// @arg s The scalar
+        /// @arg t The tensor
+        static Tensor scale(std::complex<float> s, const Tensor &t);
 
         /// @brief Inline matrix multiplication
         /// @arg t2 Right hand matrix to multiply with this one
         void matmul_(const Tensor &t2);
 
+        
+        /// @brief Inline matrix scaling
+        /// @arg s The scalar
+        void scale_(float s);
+        /// @brief Inline complex matrix scaling
+        /// @arg s The scalar
+        void scale_(std::complex<float> s);
+
         /// @}
 
         /// @name Mathematical