1r"""
  2# What it is
  3
  4**PyNondimensionalizer** is a simple little command line program in python to help find nondimensional numbers, such as the Reynold's number, Rossby number, and more.
  5
  6# Installation
  7
  8To install **PyNondimensionalizer**, use `pip`:
  9
 10```
 11$ pip install pynondimensionalizer
 12```
 13
 14# Basic Usage
 15
 16## Fundamentals
 17
 18This program is based off the [essay by Dr. James Price](https://www.whoi.edu/science/PO/people/jprice/class/DA_SSSA.pdf) but also takes from dimensional analysis in general. Dimensional analysis allows you to remove units and scales from the process you're studying, so that you may understand it in a universal way that does not depend upon scale.
 19
 20To use this program, we will use the pendulum example from Price's essay, where we want to find dimensionless numbers to represent the 2nd order differential equation of a simple, inviscid pendulum, so that the resulting solution is independent of scale.
 21
 22First, we want to make a matrix with the variables of the problem and the dimensions:
 23
 24$$
 25\\begin{matrix}
 26& \\begin{matrix}\\phi & t & M & L & g & \\phi_0\\end{matrix} \\\
 27\\begin{matrix}m \\\ l \\\ t\end{matrix} &
 28\\begin{bmatrix}
 290 & 0 & 1 & 0 & 0 & 0 \\\
 300 & 0 & 0 & 1 & 1 & 0 \\\
 310 & 1 & 0 & 0 & -2 & 0
 32\\end{bmatrix}
 33\\end{matrix}
 34$$
 35
 36The top row contains the variables of the problem. In the case of the pendulum example, $\\phi$ is the angle of the line, with length $L$, swinging a weight of mass $M$. $t$ is time and $g$ is gravity. $\\phi_0$ is the initial angle of the pendulum at $t=0$. The first column contains the dimensions: $m$ for mass, $l$ for length, and $t$ for time. The matrix holds the corresponding dimensions for each variable. For example, $\\phi$ and $\\phi_0$ don't have units and can be represented by the dimensions of $m^0l^0t^0$, whereas $g$ has 1 dimension of length, $l$, and -2 dimensions of time, $t$, and can be represented as $m^0l^1t^{-2}$. The remaining variables can be represented in a similar way.
 37
 38The dimensional matrix is the above matrix, minus the labeling:
 39
 40$$
 41\\mathbb{D} =
 42\\begin{bmatrix}
 430 & 0 & 1 & 0 & 0 & 0 \\\ 
 440 & 0 & 0 & 1 & 1 & 0 \\\ 
 450 & 1 & 0 & 0 & -2 & 0
 46\\end{bmatrix}
 47$$
 48
 49To find the dimensionless numbers for this example, we want to find the nullspace, $\\mathbb{S}$, of the dimensional matrix. Any linear combinations of the $N$ vectors that make up the nullspace can be used to find dimensionless numbers. For example, if we visualize the nullspace, $\\mathbb{S}$:
 50
 51$$
 52\\mathbb{S} = \left[ S_1, S_2, S_3, ...,S_N \right]
 53$$
 54
 55$S_1 + S_2$ is still in the nullspace, as well as $S_1 + a S_2$, where $a$ is some constant being multiplied to $S_2$. $N$ will be equal to the number of variables, $q$, minus dimensions, $k$ ($N = q - k$), in accordance with the [Buckingham $\\Pi$ theorem](https://en.wikipedia.org/wiki/Buckingham_%CF%80_theorem). For this example, our variables are ${\\phi, t, M, L, g, \\phi_0}$ so $q = 6$ and our dimensions are ${m, l, t}$ so $k = 3$, therefore $N = 6 - 3 = 3$.
 56
 57The nullspace for our pendulum dimensional matrix looks like this (from Price):
 58
 59$$
 60\\mathbb{S} = 
 61\\begin{bmatrix}
 621 & 0 & 0 \\\
 630 & 1 & 0 \\\
 640 & 0 & 0 \\\
 650 & -1/2 & 0 \\\
 660 & 1/2 & 1 \\\
 67\\end{bmatrix} =
 68\\begin{bmatrix}
 69\\left[ \\begin{matrix}1 \\\ 0 \\\ 0 \\\ 0 \\\ 0 \\\ 0\\end{matrix} \\right], &
 70\\left[ \\begin{matrix}0 \\\ 1 \\\ 0 \\\ -1/2 \\\ 1/2 \\\ 0\\end{matrix} \\right], &
 71\\left[ \\begin{matrix}0 \\\ 0 \\\ 0 \\\ 0 \\\ 0 \\\ 1\\end{matrix} \\right]
 72\\end{bmatrix}
 73$$
 74
 75which, when labeled, looks like this:
 76
 77$$
 78\\mathbb{S} = 
 79\\begin{matrix}
 80\\begin{matrix}\\phi \\\ t \\\ M \\\ L \\\ g \\\ \\phi_0\end{matrix} &
 81\\begin{bmatrix}
 82\\left[ \\begin{matrix}1 \\\ 0 \\\ 0 \\\ 0 \\\ 0 \\\ 0\\end{matrix} \\right], &
 83\\left[ \\begin{matrix}0 \\\ 1 \\\ 0 \\\ -1/2 \\\ 1/2 \\\ 0\\end{matrix} \\right], &
 84\\left[ \\begin{matrix}0 \\\ 0 \\\ 0 \\\ 0 \\\ 0 \\\ 1\\end{matrix} \\right]
 85\\end{bmatrix}
 86\\end{matrix}
 87$$
 88
 89Each vector gives us a nondimensional parameter, $\\Pi_n$:
 90
 91$$
 92S_1 = \\left[ \\begin{matrix}1 \\\ 0 \\\ 0 \\\ 0 \\\ 0 \\\ 0\\end{matrix} \\right] \\Rightarrow \\Pi_1 = \\phi^1 t^0 M^0 L^0 g^0 \\phi_0^0 = \\phi
 93$$
 94
 95$$
 96S_2 = \\left[ \\begin{matrix}0 \\\ 1 \\\ 0 \\\ -1/2 \\\ 1/2 \\\ 0\\end{matrix} \\right] \\Rightarrow \\Pi_2 = \\phi^0 t^1 M^0 L^{-1/2} g^{1/2} \\phi_0^0 = \\frac{t}{\\sqrt{L/g}}
 97$$
 98
 99$$
100S_3 = \\left[ \\begin{matrix}0 \\\ 0 \\\ 0 \\\ 0 \\\ 0 \\\ 1\\end{matrix} \\right] \\Rightarrow \\Pi_3 = \\phi^0 t^0 M^0 L^0 g^0 \\phi_0^1 = \\phi_0
101$$
102
103In Price, $\\Pi_3$ is used as the nondimensional parameter of time to collapse all variations of the period due to the length of the line, $L$. With another nondimensional number (not shown here) to nondimensionalize the tension of the string with respect to time, the different possible time series of tension collapse onto one time series that only changes with different initial angles of $\\phi_0$. This "collapsing" is the removal of the scale's effect from affecting the resulting solution.
104
105## Using **PyNondimensionalizer**
106
107A `csv` file containing the dimensional matrix, in this case for the above pendulum example, is the input file for **PyNondimensionalizer**, and should look like this:
108
109```
110 ,phi,  t,  M,  L,  g,  phi0
111m,  0,  0,  1,  0,  0,  0
112l,  0,  0,  0,  1,  1,  0
113t,  0,  1,  0,  0, -2,  0
114```
115
116**The variables and dimensions should be included!**
117
118On the command line, enter the following, with the proper input file and output file location in place of `input_file.csv` and `output_file.txt`:
119
120```
121$ pynondim -i input_file.csv -o output_file.txt
122```
123
124The following output will be saved to the output file:
125
126```
127Dimensions = 
128
129m l t
130
131Variables = 
132
133phi t M L g phi0
134
135D = 
136
137⎡0  0  1  0  0   0⎤
138⎢                 ⎥
139⎢0  0  0  1  1   0⎥
140⎢                 ⎥
141⎣0  1  0  0  -2  0⎦
142
143S = 
144
145⎡⎡1⎤  ⎡0 ⎤  ⎡0⎤⎤
146⎢⎢ ⎥  ⎢  ⎥  ⎢ ⎥⎥
147⎢⎢0⎥  ⎢2 ⎥  ⎢0⎥⎥
148⎢⎢ ⎥  ⎢  ⎥  ⎢ ⎥⎥
149⎢⎢0⎥  ⎢0 ⎥  ⎢0⎥⎥
150⎢⎢ ⎥, ⎢  ⎥, ⎢ ⎥⎥
151⎢⎢0⎥  ⎢-1⎥  ⎢0⎥⎥
152⎢⎢ ⎥  ⎢  ⎥  ⎢ ⎥⎥
153⎢⎢0⎥  ⎢1 ⎥  ⎢0⎥⎥
154⎢⎢ ⎥  ⎢  ⎥  ⎢ ⎥⎥
155⎣⎣0⎦  ⎣0 ⎦  ⎣1⎦⎦
156
157𝚷 = 
158
159𝚷 0	= phi^(1) 
160𝚷 1	= t^(2) L^(-1) g^(1) 
161𝚷 2	= phi0^(1) 
162```
163
164*If no output file is given, the result is printed in the terminal.*
165
166You may notice that $S_2$ here is different from $S_2$ above. However, recall that any linear combination of the nullspace vectors is also in the nullspace and, therefore, another nullspace vector. In this case, $S_2$ is just the $S_2$ above multiplied by 2.
167"""
168
169__docformat__ = 'numpy'
170__version__ = '0.1.2'