root/www/docbook/nekcem.xml

<?xml version="1.0"?>
<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN" "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd">
<article>

        <articleinfo>
                <title>NEKCEM</title>
                <abstract>
                        <para>In the software package  NEKCEM  (Nekton for Computational ElectroMagnetics) the spectral element discontinuous Galerkin  (SEDG)  method is employed on a conformal spectral-element mesh. NEKCEM features geometric flexibility, spectrally accurate numerical convergence, and an efficient parallel implementation. </para>
                        <para> This package consists of the components of meshing, Maxwell time domain solver, electrostatic poisson solver, and visualization tools. It supports the computational domain boundary with perfectly matched layer, perfect conductor, and periodic material. </para>
                </abstract>
        </articleinfo>
        
        <sect1>
                <title>Getting started with NEKCEM</title>
                <para>The following sections describe the process for downloading and building the NEKCEM package. It is assumed the user is comfortable with using <ulink url="http://subversion.tigris.org/"><citetitle>Subversion</citetitle></ulink>, as well as with compiling Fortran and C programs.</para>

                <sect2>
                        <title> Getting the source</title>
                        <para>
                                NEKCEM is available for download via <ulink url="https://trac.mcs.anl.gov/projects/NEKCEM"><citetitle> the Subversion repository</citetitle></ulink>:
                                <programlisting>svn co https://svn.mcs.anl.gov/repos/NEKCEM</programlisting>
                        </para>
                        <para> 
                                Other utilities are available  <ulink url="http://www-unix.mcs.anl.gov/~mmin/nekcem/nek-helpful-software.tar"><citetitle>here</citetitle></ulink>. This utilities collection contains the following: 
                                <itemizedlist> 
                                <listitem><para>prex: description goes here...</para></listitem>
                                <listitem><para>postx: description goes here...</para></listitem>
                                <listitem><para>genmap: description goes here...</para></listitem>
                                <listitem><para>n2to3: description goes here...</para></listitem>
                                </itemizedlist>
                        </para>
                        <para> It is also recommended to download <ulink url="http://www.paraview.org/New/index.html"><citetitle>ParaView</citetitle></ulink> and <ulink url="http://cens.ioc.ee/projects/pyvtk/"><citetitle>PyVTK</citetitle></ulink>.  </para>
                </sect2>

                <sect2>
                        <title>Contents of the NEKCEM package</title>
                        <para>The NEKCEM package contains the source code, examples (generated by prex and genmap), libraries used, and documentation.</para>

                        <itemizedlist> 
                                <listitem><para>bin: a collection of scripts for building and running NEKCEM</para>
                                        <itemizedlist> 
                                                <listitem><para>makenek: builds the nekcem package. Run from an 'example' directory via ../../bin/makenek. See makenek --help for options</para></listitem>
                                                <listitem><para>nek: runs the nekcem package with 'reasonable' defaults for the platform. See nek --help for options</para></listitem>
                                                <listitem><para>arch-settings: contains architecture-specific settings for building NEKCEM. Used by makenek</para></listitem>
                                                <listitem><para>run_paraview: used for visualization. MORE DESCRIPTION GOES HERE</para></listitem>
                                                <listitem><para>post2vtk: convert a .dat dump from FORTRAN into a VTK file for use in paraview</para></listitem>
                                        </itemizedlist> 
                                </listitem>
                                <listitem><para>examples: sample problems generated by prex, genmap</para>
                                        <itemizedlist> 
                                                <listitem><para>tube: DESCRIPTION GOES HERE</para></listitem>
                                                <listitem><para>tube-mw: DESCRIPTION GOES HERE</para></listitem>
                                        </itemizedlist> 
                                </listitem>
                                <listitem><para>libs: BLAS and LAPACK can be placed here if not already installed on your system</para></listitem>
                                <listitem><para>src: source code</para></listitem>
                                <listitem><para>doc: documentation</para></listitem>
                        </itemizedlist>
                </sect2>

        </sect1>

        <sect1>
                <title>Building and Running NEKCEM</title>
                <para>Building and using NEKCEM consist of creating an appropriate mesh and building the package for that mesh</para>

                <sect2>
                        <title>Mesh generation</title>
                        <orderedlist>
                                <listitem>
                                        <para>Invoke the prex GUI tool to generate a mesh from directory where you want the generated files to be stored:
                                                <programlisting>
                                                        cd example/2dnanocyl
                                                        ../../bin/prex 
                                                </programlisting>
                                        </para>
                                </listitem>
                                <listitem><para>specify the name to be used for the mesh in prex (i.e. 2dnanocyl) </para></listitem>
                                <listitem><para>use prex to specify the geometry and boundary conditions of the mesh</para></listitem>
                                <listitem><para>OTHER INSTRUCTIONS GO HERE</para></listitem>
                        </orderedlist>
                </sect2>

                <sect2>
                        <title>Compiling NEKCEM</title>
                        <para>To compile the package, run the makenek script from the directory of the example just created:
                                <programlisting>
                                        ../../bin/makenek
                                </programlisting>
                                See makenek -h for compile options. The most useful option is probably -d, which builds in debug mode (debug symbols and no optimization).
                        </para>
                        <para>A few files will get moved around during the compile process:
                                <itemizedlist>
                                        <listitem><para> The 2dnanocyl.usr file will get copied into the ../../src directory as subuser.F.  </para></listitem>
                                        <listitem><para> The SIZEu file will get copied into the ../../src directory as SIZE.  </para></listitem>
                                </itemizedlist>
                        </para>
                </sect2>

                <sect2>
                        <title>Running NEKCEM</title>
                        <para>To run on the current example, use the nek script 
                                <programlisting>
                                        ../../bin/nek 2dnanocyl
                                </programlisting>
                                See nek -h for options. You'll probably want to use -n for controlling the number of nodes, and -t for the walltime.
                        </para>
                        <para>A few files will get generated during the execution: 
                                <itemizedlist>
                                        <listitem><para>DESCRIPTION OF LOG FILES GOES HERE</para></listitem>
                                        <listitem><para>Field files will be generated in a format 2dnanocyl001.dat in the vtk directory (also created). After conversion with post2vtk these can be viewed in paraview</para></listitem>
                                </itemizedlist>
                        </para>
                </sect2>

                <sect2>
                        <title>Viewing Results</title>
                        <para>Paraview can be used to view the results for each processor and timestep. The vtk directory contains the files needed by paraview. For more information, see the <ulink url="http://www.paraview.org/New/index.html">ParaView website.</ulink></para>
                </sect2>

        </sect1>
        
        <sect1>
                <title>Documentation</title>
                <para>The rea-file.txt file located in /doc describes the format of the .rea file generated by prex</para>
        </sect1>

        <index><title>Index</title>
                <indexdiv><title>D</title>
                        <indexentry>
                          <primaryie>database (bibliographic), 253, 255</primaryie>
                          <secondaryie>structure, 255</secondaryie>
                          <secondaryie>tools, 259</secondaryie>
                        </indexentry>
                        <indexentry>
                          <primaryie>dates (language specific), 179</primaryie>
                        </indexentry>
                        <indexentry>
                          <primaryie>DC fonts, <emphasis>172</emphasis>, 177</primaryie>
                          <secondaryie>Math fonts, 177</secondaryie>
                        </indexentry>
                </indexdiv>
        </index>


</article>