document matrix exponentiation

others/matrix_exponentiation.cpp

@@ -1,20 +1,24 @@
-/*
+/**
-Matrix Exponentiation.
+@file
+@brief Matrix Exponentiation.
+
 The problem can be solved with DP but constraints are high.
-ai = bi (for i <= k)
+<br/>\f$a_i = b_i\f$ (for \f$i <= k\f$)
-ai = c1*ai-1 + c2*ai-2 + ... + ck*ai-k (for i > k)
+<br/>\f$a_i = c_1 a_{i-1} + c_2 a_{i-2} + ... + c_k a_{i-k}\f$ (for \f$i > k\f$)
-Taking the example of Fibonacci series, K=2
+<br/>Taking the example of Fibonacci series, \f$k=2\f$
-b1 = 1, b2=1
+<br/>\f$b_1 = 1,\; b_2=1\f$
-c1 = 1, c2=1
+<br/>\f$c_1 = 1,\; c_2=1\f$
-a = 0 1 1 2 ....
+<br/>\f$a = \begin{bmatrix}0& 1& 1& 2& \ldots\end{bmatrix}\f$
-This way you can find the 10^18 fibonacci number%MOD.
+<br/>This way you can find the \f$10^{18}\f$ fibonacci number%MOD.
 I have given a general way to use it. The program takes the input of B and C
 matrix.
+
 Steps for Matrix Expo
 1. Create vector F1 : which is the copy of B.
 2. Create transpose matrix (Learn more about it on the internet)
-3. Perform T^(n-1) [transpose matrix to the power n-1]
+3. Perform \f$T^{n-1}\f$ [transpose matrix to the power n-1]
-4. Multiply with F to get the last matrix of size (1xk).
+4. Multiply with F to get the last matrix of size (1\f$\times\f$k).
+
 The first element of this matrix is the required result.
 */
 
@@ -25,16 +29,36 @@ using std::cin;
 using std::cout;
 using std::vector;
 
+/*! shorthand definition for `int64_t` */
 #define ll int64_t
-#define endl '\n'
+
+/*! shorthand definition for `std::endl` */
+#define endl std::endl
+
+/*! shorthand definition for `int64_t` */
 #define pb push_back
 #define MOD 1000000007
-ll ab(ll x) { return x > 0LL ? x : -x; }
+
+/** returns absolute value */
+inline ll ab(ll x) { return x > 0LL ? x : -x; }
+
+/** global variable k
+ * @todo @stepfencurryxiao add documetnation
+ */
 ll k;
+
+/** global vector variables
+ * @todo @stepfencurryxiao add documetnation
+ */
 vector<ll> a, b, c;
 
-// To multiply 2 matrix
+/** To multiply 2 matrices
-vector<vector<ll>> multiply(vector<vector<ll>> A, vector<vector<ll>> B) {
+ * \param [in] A matrix 1 of size (m\f$\times\f$n)
+ * \param [in] B \p matrix 2 of size (p\f$\times\f$q)\n\note \f$p=n\f$
+ * \result matrix of dimension (m\f$\times\f$q)
+ */
+vector<vector<ll>> multiply(const vector<vector<ll>> &A,
+                            const vector<vector<ll>> &B) {
     vector<vector<ll>> C(k + 1, vector<ll>(k + 1));
     for (ll i = 1; i <= k; i++) {
         for (ll j = 1; j <= k; j++) {
@@ -46,9 +70,15 @@ vector<vector<ll>> multiply(vector<vector<ll>> A, vector<vector<ll>> B) {
     return C;
 }
 
-// computing power of a matrix
+/** computing integer power of a matrix using recursive multiplication.
-vector<vector<ll>> power(vector<vector<ll>> A, ll p) {
+ * @note A must be a square matrix for this algorithm.
-    if (p == 1) return A;
+ * \param [in] A base matrix
+ * \param [in] p exponent
+ * \return matrix of same dimension as A
+ */
+vector<vector<ll>> power(const vector<vector<ll>> &A, ll p) {
+    if (p == 1)
+        return A;
     if (p % 2 == 1) {
         return multiply(A, power(A, p - 1));
     } else {
@@ -57,10 +87,15 @@ vector<vector<ll>> power(vector<vector<ll>> A, ll p) {
     }
 }
 
-// main function
+/*! Wrapper for Fibonacci
+ * \param[in] n \f$n^\text{th}\f$ Fibonacci number
+ * \return \f$n^\text{th}\f$ Fibonacci number
+ */
 ll ans(ll n) {
-    if (n == 0) return 0;
+    if (n == 0)
-    if (n <= k) return b[n - 1];
+        return 0;
+    if (n <= k)
+        return b[n - 1];
     // F1
     vector<ll> F1(k + 1);
     for (ll i = 1; i <= k; i++) F1[i] = b[i - 1];
@@ -90,8 +125,7 @@ ll ans(ll n) {
     return res;
 }
 
-// 1 1 2 3 5
+/** Main function */
-
 int main() {
     cin.tie(0);
     cout.tie(0);