====== FieldSymmetry ======

The FieldSymmetry class represents the symmetry group of FlowFields. Specifically, the periodic in 
x,z and polynomial in y expansions inherent in FlowFields allow the follow symmetries

<latex> $ \begin{align*}
  [u,v,w](x,y,z) &\rightarrow [-u,-v,-w](x,y,z) \\
  [u,v,w](x,y,z) &\rightarrow [-u, v, w](-x,y,z) \\
  [u,v,w](x,y,z) &\rightarrow [ u, -v, w](x,-y,z) \\
  [u,v,w](x,y,z) &\rightarrow [ u, v, -w](x, y,-z) \\
  [u,v,w](x,y,z) &\rightarrow [ u, v, w](x+\ell_x, y, z+\ell_z) 
\end{align*} $ </latex>

Let G be the group generated by these symmetries. Specific choice of boundary conditions at the walls 
might constrain the symmetry group of a specific flow to a subgroup G. But for generality,the FieldSymmetry 
class can represent any symmetry in G. The FieldSymmetry class parameterizes symmetries σ ⊂ G symmetries 
as follows. Any element of the symmetry group is defined by six parameters

<latex> $ \begin{align*}
  \sigma &= (s_x, s_y, s_x, a_x, a_z, s)\\
  s_x, s_y, s_z, s &= \pm 1\\
  a_x, a_z &\in [-0.5, 0.5)
\end{align*} $ </latex>

with the action of σ on a velocity field u as

<latex>
  \sigma [u, v, w](x,y,z) = s (s_x u, s_y v, s_z w)(s_x x + a_x L_x, s_y y, s_z z + a_z L_z)
</latex>

The following is a brief overview of FieldSymmetry functionality. For a complete description,
see the header file {{:librarycode:symmetry.h}}.
===== Constructors / Initialization =====

In C++ code, elements of the symmetry group can initialized as follows,
where %%sx,sy,sz%% are of type %%int%% and %%ax, az%% are of type %%Real%%. 

<code c++>
  FieldSymmetry sigma0(sx, sy, sz, ax, az, s);

  FieldSymmetry sigma1(sx, sy, sz, ax, az);  // the s argument s defaults to 1

  FieldSymmetry sigma2(sx, sy, sz);          // s defaults to 1; ax,az to 0

  FieldSymmetry tau(ax, az);                 // pure translation: s,sx,sy,sz default to 1

  FieldSymmetry identity;                    // the identity: s defaults to 1; ax,az to 0; sx,sy,sz to 1
</code>

===== Operations =====

FieldSymmetries act on each other and velocity fields as follows

<code c++>
  FieldSymmetry sigma4 = sigma2 * sigma1;     // group multiplication

  sigma4 *= sigma3;                           // sigma4 now equals sigma3*sigma2*sigma1 ---note order!

  FlowField u("u");                           // read velocity field u from disk

  FlowField v = sigma1 * u;                   // Make new field v = sigma1 u

  v *= sigma2;                                // v now equals sigma2 * sigma1 * u
</code>

FieldSymmetries can be saved to / read from disk...

<code c++>
  sigma1.save("sigma1");                      // saves to ASCII file sigma1.asc

  FieldSymmetry sigma7("sigma1");             // make a new symmetry element sigma7 == sigma1
</code>

...compared to each other...

<code c++>
  if (sigma1 != identity) 
    ...
  else if (sigma1 == sigma7)
    ...
</code>
===== ASCII IO ===== 

==== FieldSymmetry ====

The FieldSymmetry uses ASCII input-output. The storage format is 

  s sx sy sz ax az

Thus, the following C++ channelflow code 

<code c++>
FieldSymmetry sigma(-1, -1, -1, 0.3, 0.1);
sigma.save("sigma");
</code>

produces the ASCII file ''sigma.asc'' with contents

  1 -1 -1 -1 0.3 0.1

which can then be read back into a channeflow program with 

<code c++>
FieldSymmetry sigma("sigma");
</code>

Note that  the order of parameters in the ASCII file is different than the order in the ''FieldSymmetry'' constructor: the overall multiplicative sign ''s'' goes first in the file and last in the C++ constructor. I apologize for this. The reasons for the difference are are historical. The next release of channelflow will have order (s, sx, sy, sz, ax, az) for both.

==== SymmetryList ====

The ''SymmetryList'' class is a essentially an array of ''FieldSymmetry'' objects with simple ASCII IO methods. The ASCII format is 

   % N
   s0 sx0 sy0 sz0 ax0 az0
   s1 sx1 sy1 sz1 ax1 az1
   ...

where N is the number of symmetries listed in the file. Thus the file ''S.asc'' with contents 

   % 2
   1  1  1 -1  0.5  0.0
   1 -1 -1  1  0.5  0.5

represents the symmetries σ0 = (1, 1, 1, -1, 0.5, 0.0) and σ1 = (1, -1, -1,  1,  0.5,  0.5). These are the generators of the S 
[[docs:math:symmetry#isotropy_groups_of_known_solutions|S symmetry group]]. The generators can be loaded into channelflow, used, and saved as follows

<code c++>
SymmetryList S("S");      // load generators from ASCII file
FlowField foo = S[0](u);  // apply (1,  1,  1, -1, 0.5, 0.0) to u
FlowField bar = S[1](u);  // apply (1, -1, -1,  1, 0.5, 0.5) to u
S.save("Q");              // save generators into another file

SymmetryList P(4);        // Create another symmetry group
P[0] = FieldSymmetry(1,1,1, 0.2, 0.0); 
P[1] = etc.;
</code>