Merge remote-tracking branch 'refs/remotes/origin/Ver.2.0_alpha' into…

… Ver.2.0_alpha

doc/tex_src/controls_CALYPSO.tex

@@ -51,7 +51,7 @@ \subsection{Block {\tt data\_files\_def}}
 \paragraph{\tt sph\_file\_fmt\_ctl}
 \label{href_t:sph_file_fmt_ctl}
 \verb|[sph_formayt]| \\
-File format of spherical harmonics indexing and FEM mesh file \verb|[sph_format]| is defined by text. Following data formats can be defined. Extensions of each data format is listed in Table \ref{table:mesh_format}.
+File format of spherical harmonics indexing and FEM mesh file \verb|[sph_format]| is defined by text. Following data formats can be defined. Flags of each data format is listed in Table \ref{table:mesh_format}.
 %
 \begin{description}
 \item{\tt ascii: }   Distributed ASCII data
@@ -73,7 +73,7 @@ \subsection{Block {\tt data\_files\_def}}
 \paragraph{\tt restart\_file\_fmt\_ctl}
 \label{href_t:restart_file_fmt_ctl}
 \verb|[rst_format]| \\
-File format of restart files \verb|[rst_format]| is defined by text. Following data formats can be defined. Extensions of each data format is listed in Table \ref{table:restart_format}.
+File format of restart files \verb|[rst_format]| is defined by text. Following data formats can be defined. Flags of each data format is listed in Table \ref{table:restart_format}.
 %
 \begin{description}
 \item{\tt ascii: }   Distributed ASCII data
@@ -144,7 +144,7 @@ \subsubsection{\tt num\_domain\_ctl}
 \paragraph{\tt num\_horizontal\_domain\_ctl}
 \label{href_t:num_horizontal_domain_ctl} 
 \verb|[Ndomain]| \\
-Number of subdomains in the horizontal direction. The number will be the number of subdomains for the meridional directios for the spherical grid $(r, \theta, \phi)$ and Fourier transform $(r, \theta, m)$. For Legendre transform $(r, \theta, m)$ and $(r, l, m)$, the number will be the number of subdomains for the h.armonics ordedr $m$.
+Number of subdomains in the horizontal direction. The number will be the number of subdomains for the meridional directios for the spherical grid $(r, \theta, \phi)$ and Fourier transform $(r, \theta, m)$. For Legendre transform $(r, \theta, m)$ and $(r, l, m)$, the number will be the number of subdomains for the harmonics ordedr $m$.
 
 
 \paragraph{\color{magenta} \tt num\_domain\_sph\_grid    [Direction]    [Ndomain]}
@@ -163,34 +163,54 @@ \subsubsection{\tt num\_domain\_ctl}
 Definition of number of subdomains for spectrum data in $(r, l, m)$. Direction {\tt  modes} is set in the \verb|[Direction]| field, and number of subdomains \verb|[Ndomain]| are defined in the integer field.
 
 
-\subsubsection{\tt num\_grid\_sph}
+\subsubsection{{\tt shell\_define\_ctl} (Previously {\tt num\_grid\_sph})}
 \label{href_t:num_grid_sph}
-Spatial resolution of the spherical shell is defined in this block. \\
+Spatial resolution of the spherical shell is defined in this block. Old block name \verb|num_grid_sph| is also accept as this block label.\\
 \hyperref[href_i:num_grid_sph]{(Back to {\tt control\_sph\_shell})}
 
+\paragraph{\tt sph\_center\_coef\_ctl}
+\label{href_t:sph_center_coef_ctl}
+\verb|[TYPE]| \\
+Set flag \verb|with_center| into \verb|[type]| to include spherical harmonics coefficient for $l = m = 0$. This fliag is required when temperature or composition is solved to the center.
+
+\paragraph{\tt sph\_grid\_type\_ctl}
+\label{href_t:sph_grid_type_ctl}
+\verb|[TYPE]| \\
+Set spherical shell grid type for visualization. The follwing types are avaiable. Default value is \verb|no_pole|. The following flags are avaiable.
+%
+\begin{description}
+    \item{\tt no\_pole} Spherical shell grid is only generated from grids on Gauss-Legendle points on latitude. Corequently, small empty tube (circle on a sphere surface) has to be made in visualization.
+    \item{\tt with\_pole} Grid points are added at poles in the grids. There is still empty sphere in the whole sphre grid.
+    \item{\tt with\_center}  Grid at poles and centere is added in the grid. The mesh inceludes center is degenerated from hexahedral mesh to pyramid mesh. This mode increases initialization time.
+\end{description}
+%
+
 \paragraph{\tt truncation\_level\_ctl}
 \label{href_t:truncation_level_ctl}
 \verb|[Lmax]| \\
 Truncation level $L$ is defined by integer. Spherical harmonics is truncated by triangular $0 \le l \le L$ and $0 <m < l$.
 
+\paragraph{\tt longitude\_symmetry\_ctl    [M\_sym]}
+\label{href_t:longitude_symmetry_ctl}
+Longitudinal folding symmtery \verb|[M_sym]| is defeined by integer.
+
 \paragraph{\tt ngrid\_meridonal\_ctl}
 \label{href_t:ngrid_meridonal_ctl}
 \verb|[Ntheta]| \\
-Number of grid in the meridional direction \verb|[Ntheta]| is defined by integer
-\paragraph{\tt ngrid\_zonal\_ctl}
+Number of grid in the meridional direction $N_{\theta}$ is defined by integer \verb|[Ntheta]|. $N_{\theta}$ needs to satisfy $N_{\theta} > 1.5 L$.\paragraph{\tt ngrid\_zonal\_ctl}
 \label{href_t:ngrid_zonal_ctl}
 \verb|[Nphi]| \\
-Number of grid in the zonal direction \verb|[Nphi]| is defined by integer.
+Number of grid in the zonal direction $N_{\phi}$ is defined by integer [Nphi]. $N_{\phi}$ needs to satisfy $N_{\phi} = 2 N_{\theta}$.
 
 \paragraph{\tt raidal\_grid\_type\_ctl}
 \label{href_t:radial_grid_type_ctl}
 \verb|[explicit, Chebyshev, or equi_distance]| \\
 Type of the radial grid spacing is defined by text. The following types are supported in Calypso.
 %
 \begin{description}
-	\item{\tt explicit}  Equi-distance grid
 	\item{\tt Chebyshev} Chebyshev collocation points
-	\item{\tt equi\_distance} Set explicitly by \verb|r_layer| array
+	\item{\tt equi\_distance} Equi-distance grid
+    \item{\tt explicit}  Set explicitly by \verb|r_layer| array
 \end{description}
 %
 
@@ -224,12 +244,17 @@ \subsubsection{\tt num\_grid\_sph}
 (This option works with \verb|radial_grid_type_ctl| is {\tt explicit} or {\tt Chebyshev}.)
 Maximum radius of the domains \verb|[Rmax]| is defined by real. If this value is not defined, CMB becomes outer boundary of the domain.
 
-\paragraph{\tt r\_layer}
+\paragraph{\tt array r\_layer}
 \label{href_t:r_layer}
 \verb|[Layer #]   [Radius]| \\
 (This option works with \verb|[radial_grid_type_ctl]| is {\tt explicit}.)
 List of the radial grid points in the simulation domain. Index of the radial point \verb|[Layer #]| is defined by integer, and radius \verb|[Radius]| is defined by real.
 
+\paragraph{\tt array add\_external\_layer}
+\label{href_t:add_external_layer}
+\verb|[Radius]| \\
+List of additional radial grid points. More grid points can be added in the Chebyshev or equi-distance grid. Radius of the additional points \verb|[Radius]| is defined by real.
+
 \paragraph{\tt array boundaries\_ctl}
 \verb|[Boundary_name]  [Layer #]| \\
 \label{href_t:boundaries_ctl} 
@@ -296,7 +321,7 @@ \subsection{\tt phys\_values\_ctl}
 \hline \hline
 \tt viscous\_diffusion & Viscous diffusion
 & $-\nu \nabla \times \nabla \times \bvec{u}$ \\
-\tt inertia & Inertia term &  $ \bvec{\omega} \times \bvec{u} $ \\
+\tt inertia & Inertia term &  $ -\bvec{\omega} \times \bvec{u} $ \\
 \tt buoyancy                   & Thermal buoyancy &  $ -\alpha_{T} T \bvec{g}  $ \\
 \tt composite\_buoyancy & Compositional buoyancy &  $ -\alpha_{C} C\bvec{g}  $\\
 \tt Lorentz\_force & Lorentz force &  $ \bvec{J} \times \bvec{B} $ \\
@@ -332,7 +357,7 @@ \subsection{\tt phys\_values\_ctl}
 \begin{tabular}{|c|c|c|}
 \hline
 \tt [Name] & field name & Description \\ \hline \hline
-\tt rot\_inertia & Curl of inertia &  $ \nabla \times \left(\bvec{\omega} \times \bvec{u}\right) $ \\
+\tt rot\_inertia & Curl of inertia &  $ -\nabla \times \left(\bvec{\omega} \times \bvec{u}\right) $ \\
 \tt rot\_Lorentz\_force & Curl of Lorentz force &  $ \nabla \times \left(\bvec{J} \times \bvec{B}\right) $ \\
 \tt rot\_Coriolis\_force & Curl of Coriolis force &  $ -2 \Omega \nabla \times \left(\hat{z} \times \bvec{u} \right) $ \\
 \tt rot\_buoyancy                   & Curl of thermal buoyancy &  $ - \nabla \times \left(\alpha_{T} T \bvec{g}\right)  $ \\

doc/tex_src/install_CALYPSO.tex

@@ -219,9 +219,10 @@ \subsubsection{Compile}
 sph_add_initial_field*  sph_mhd*       tests/
 sph_initial_field*      sph_snapshot*  utilities/
 $ ls -F utilities/
-assemble_sph*   make_f90depends*  t_ave_monitor_data*
-field_to_VTK*   sectioning*       three_vizualizations*
-gen_sph_grids*  section_to_vtk*
+./                    field_to_VTK*       sectioning*
+../                   gen_sph_grids*      t_ave_monitor_data*
+assemble_sph*         make_f90depends*    three_vizualizations*
+check_control_mhd*    section_to_vtk*
 \end{verbatim}
 %
 %
@@ -241,6 +242,8 @@ \subsubsection{Compile}
 \begin{description}
 \item{\tt assemble\_sph:     }\\
  Data transfer program to change number of subdomains.
+\item{\tt check\_control\_mhd:     }\\
+ Quick check program for control data consistency.
 \item{\tt gen\_sph\_grids:    }\\
  Preprocessing program for data transfer for spherical harmonics transform
 \item{\tt t\_ave\_monitor\_data:     }\\
@@ -306,20 +309,20 @@ \subsubsection{Distclean}
 % make distclean
 \end{verbatim}
 
+
 \subsubsection{Install}
  The executive files are copied to the install directory \verb|$(INSTDIR)/bin|. The install directory \verb|$(INSTDIR)| is defined in Makefile, and can also set by  \verb|${--prefix}| option for \verb|configure| command. Alternatively, you can use the programs in \verb|${SRCDIR}/bin| directory without running \verb|make install|. If directory \verb|${PREFIX}| does not exist, \verb|make install | creates  \verb|${PREFIX}|,  \verb|${PREFIX}/lib|,  \verb|${PREFIX}/bin|, and  \verb|${PREFIX}/include| directories. No files are installed in \verb|${PREFIX}/lib| and \verb|${PREFIX}/include|.
 
+
 \subsubsection{Construct dependecies (only for developper)}
-The build process of Calypso consists of three steps:
+Actual build process of Calypso by \verb|% make| consists of three steps:
 %
 \begin{enumerate}
 \item Construct dependency of source files {\tt Makefile.depends} in each directory by  {\tt make depends} command.
 \item Construct {\tt Makefile} in {\tt [WORKDIR]} directory by {\tt make makemake} command.
 \item Move into  {\tt [WORKDIR]}  and run {\tt make} command in {\tt [WORKDIR]} directory ({\tt cd [WORKDIR]; make})
 \end{enumerate}
 %
-gmake supports parallel build by using {\tt -j [\# of process]} option, but the step 1 and 2 do not work correctly under the parallel build, but the step 3 (build under {\tt [WORKDIR} support the parallel build. Consequently, build time can be significantly reduced by run the step 3 sepalately with {\tt -j} option. 
-{\color{red} (Caution) Many large computer system does not recommend to use parallel build on the login nodes. Please check the computer center's documentations}
 
 Fortran90 routines need to be build after modules which are used in the routines. C source files also need dependency among include files. Consequently, list of dependency of source files are saved in the file \verb|Makefile.depends| in each directory. When you modify the source files with changing the module usage,  \verb|Makefile.depends| files need to be updated. To update the  \verb|Makefile.depends|files, use the  \verb|make| command at the \verb|[CALYPSO_HOME]| directory as \\
 %
@@ -329,6 +332,11 @@ \subsubsection{Construct dependecies (only for developper)}
 
 This process generate dependencies of the Fortran modules by program \verb|make_f90depends|. For C source files, the dependency is generated by the gcc with \verb|-MM -w -DDEPENDENCY_CHECK| option. Consequently, the dependencies need to be generated by the environment with gcc or compatible compiler. After generating the dependency, you can transfer the modified package and build without using gcc.
 
+\subsection{Parallel build}
+gmake supports parallel build by using {\tt -j [\# of process]} option. Calypso's build process supports purallel build. it may reduce the compile time. (We checked on Ubuntu and Mac OS.) \\
+{\color{red} (Caution) Many large computer centers do not recommend to use parallel build on their login nodes. Please check the computer center's if you can use parallel builds}
+
+
 \subsection{Install without using configure}
 \label{section:no_configure}
 It is possible to compile Calypso without using the \verb|configure| command. To do this, you need to edit the \verb|Makefile|. First, copy \verb|Makefile| from template \verb|Makefile.in| as