<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook V3.1//EN" [
<!ENTITY version SYSTEM "version">
]>
<!--
  Copyright (c) 2004 Ecole centrale de Lyon
 
  This program is free software; you can redistribute it and/or modify
  it under the terms of the GNU General Public License as published by
  the Free Software Foundation, version 2.

  This program is distributed in the hope that it will be useful,
  but WITHOUT ANY WARRANTY; without even the implied warranty of
  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  GNU General Public License for more details.

  You should have received a copy of the GNU General Public License
  along with this program; if not, write to the Free Software
  Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
-->
<article lang="en" id="quickref">
  <title>Tessa quick reference guide</title>
  <artheader>
    <author>
      <firstname>Josselin</firstname>
      <surname>Mouette</surname>
      <affiliation>
	<orgname>&Eacute;cole centrale de Lyon</orgname>
	<address><email>josselin.mouette@ec-lyon.fr</email></address>
      </affiliation>
    </author>
    <productname>Tessa</productname>
    <productnumber>&version;</productnumber>
    <pubdate>version &version;, 07 July 2004</pubdate>
    <abstract>
      <para>This guide describes how to get quickly started with Tessa and run your first FDTD simulations. It doesn't describe how Tessa works, neither is it a complete description of Tessa's features.</para>
    </abstract>
  </artheader>

  <sect1>
    <title>Installing Tessa</title>
    <para>When Tessa is not available as a binary package for your system, installation is done through GNU autotools:</para>
    <blockquote><programlisting>./configure
make
<emphasis>(as root) </emphasis>make install</programlisting></blockquote>
    <para>You will need as prerequisites:<itemizedlist>
	<listitem>
	  <para>The <ulink url="http://hdf.ncsa.uiuc.edu/HDF5/">Hierarchical Data Format 5</ulink> library which is used to read and store all the data used by Tessa.</para>
	</listitem>
	<listitem>
	  <para><ulink url="http://www.gzip.org/zlib/">Zlib</ulink>, which is a prerequisite for HDF5 anyway.</para>
	</listitem>
	<listitem>
	  <para>Necessary only if you use the provided module to generate the optical structures:<itemizedlist>
	      <listitem>
		<para><ulink url="http://www.python.org/">Python</ulink>, the scripting language used to generate the structures.</para>
	      </listitem>
	      <listitem>
		<para><ulink url="http://sourceforge.net/projects/numpy">NumPy</ulink>, the Numeric Python extension. Numarray is not yet supported because it is too slow.</para>
	      </listitem>
	      <listitem>
        	<para><ulink url="http://pytables.sourceforge.net/">PyTables</ulink>, which brings in HDF5 support for Python.</para>
	      </listitem>
	    </itemizedlist></para>
	</listitem>
        <listitem>
	  <para><emphasis>(optional)</emphasis> <ulink url="http://ab-initio.mit.edu/h5utils/">h5utils</ulink>, a set of tools to manipulate HDF5 files, for e.g. cartography extraction.</para>
	</listitem>
	<listitem>
	  <para><emphasis>(optional)</emphasis> The <ulink url="http://www.fftw.org/">Fastest Fourier Transform of the West</ulink> library, version 3, which allows to output frequency spectrums.</para>
	</listitem>
      </itemizedlist>
</para>
  </sect1>


  <sect1>
    <title>Creating your optical structure</title>
    <para>The first step before running the simulation is to "draw" the structure you want to simulate. You can generate it as you like, as long as it is in the HF5 format. If you already have tools that generate e.g. three-dimensional data files in text format, you can convert them to HDF5 using <command>h5fromtxt</command> from the <emphasis>h5utils</emphasis> package.</para>
    <para>If you start from scratch, you can use the python module provided with Tessa to generate a wide range of structures. First, create a file named e.g. <filename>tchat.py</filename> (the <filename>.py</filename> extension is for python scripts). This file should look like follows.</para>
    <para>First, import the Tessa module.</para>
    <blockquote><programlisting>from tessa import *</programlisting></blockquote>
    <para>Then, create an <command>IndexFile</command> instance, name it as you want.</para>
    <blockquote><programlisting>asv=IndexFile(5,4,2.4,index=1.444)</programlisting></blockquote>
    <para>The 3 first arguments are the size of the structure. It is generally convenient to express them in micrometers or meters, but it is not necessary. The optional <command>index</command> parameter is the default index in the structure.</para>
    <para>You can now fill your structure with geometric objects, e.g. cylinders.</para>
    <blockquote><programlisting>asv.addobj(Cylinder(2.5,2,1,None,1,1.4,index=3.5))
asv.addobj(Cylinder(2.5,2,.7,None,1,1.4,index=1.444))</programlisting></blockquote>
    <para>The two first required arguments for the <command>Cylinder</command> constructor tell the position of its center, the two following are the radii (the second radius being <parameter>None</parameter>, it is taken equal to the first), and the two final tell the vertical limitation for the cylinder. Order does matter: the second cylinder here will actually replace the first one where it is drawn. We obtain here a micro-ring.</para>
    <blockquote><programlisting>asv.addobj(Block(1,1.3,-1,6,1,1.4,index=3.5))
asv.addobj(Block(3.7,4,-1,6,1,1.4,index=3.5))</programlisting></blockquote>
    <para>These two blocks describe waveguides used to bring some optical signal to our micro-ring. The arguments are three couples of coordinates delimiting the block: <parameter>x1, x2, y1, y2, z1, z2</parameter>.</para>
    <para>Note that you can also use absorbing materials. Just add a <command>absor</command>&nbsp;=&nbsp;<parameter>value</parameter> parameter, with <parameter>value</parameter> being the absorption coefficient in m<superscript>-1</superscript>.</para>
    <para>Finally, we write the structure to HDF5 files.</para>
    <blockquote><programlisting>asv.write("tchat1",delta_x=.05)
asv.write("tchat2",delta_x=.1,oversampling=1)</programlisting></blockquote>
    <para>Two files are written here: <filename>tchat1.h5</filename> and <filename>tchat2.h5</filename>. You can write as many as you want, with a <command>delta_x</command> parameter defining the space step for the FDTD simulation. Be careful to use the same unit you used to define the size of the structure. Here, the second file is written using an oversampling of 1 instead of the default (which is 4). This is useful if you want to see the result immediately (the script will run 64 times faster), but the HDF5 file won't be accurate enough for launchinga simulation. Use it when designing the structures.</para>
    <para>You can draw several other types of geometric objects with this module. The complete documentation is accessible through python's internal help. Just run <filename>python</filename> in a shell, and, in the interpreter, type "<filename>import tessa; help(tessa)</filename>" (without the quotes). You can also easily make complex structures, such as photonic crystals, using loops just like in any other python script. If you don't know how to program in python, <ulink url="http://www.python.org/doc/current/tut/">learn it</ulink>. Even if you don't know how to program at all, achieving such things is easy.</para>
    <para>Once you have your script, process it:</para>
    <blockquote><programlisting>python tchat.py</programlisting></blockquote>
    <para>It can take several minutes, but you only have to run it once. This will generate the HDF5 file(s). You can control the result using <command>h5ls</command>, <command>h5totxt</command> and <command>h5topng</command>.</para>
  </sect1>


  <sect1>
    <title>Describing the simulation</title>
    <para>Once you have a HDF5 file containing the structure you want to simulate, you have to fill the <emphasis>simulation file</emphasis>. So, create e.g. <filename>tchat.fdtd</filename>. The <filename>.fdtd</filename> extension is purely for convenience, but it is generally a good idea. This file is a simple list of <filename><parameter>variable</parameter>&nbsp;=&nbsp;<parameter>value</parameter></filename> lines.</para>

    <sect2>
      <title>Required parameters</title>
      <itemizedlist>
	<listitem>
	  <para><filename>index_file = <parameter>tchat.h5</parameter></filename></para>
	  <para>Defines the HDF5 file containing the simulated structure. Incidentally defines the size of the simulation.</para>
	</listitem>
	<listitem>
	  <para><filename>delta_x = <parameter>0.1e-6</parameter></filename></para>
	  <para>The spatial step of the simulation, in meters. Always use meters here, whatever unit you used when making the HDF5 file.</para>
	</listitem>
	<listitem>
	  <para><filename>it_max = <parameter>100000</parameter></filename></para>
	  <para>The total number of iterations.</para>
	</listitem>
	<listitem>
	  <para>One of the following:</para>
	  <itemizedlist>
	    <listitem>
	      <para><filename>freq = <parameter>2e14</parameter></filename></para>
	      <para>The frequency around which the simulation is achieved, in Hz.</para>
	    </listitem>
	    <listitem>
	      <para><filename>lambda = <parameter>1.5e-6</parameter></filename></para>
	      <para>Ditto, but using the correspounding wavelength in meters.</para>
	    </listitem>
	  </itemizedlist>
	</listitem>
      </itemizedlist>
    </sect2>

    <sect2>
      <title>Optional parameters</title>
      <itemizedlist>
	<listitem>
	  <para><filename>delta_t = <parameter>1.11e-16</parameter></filename></para>
	  <para>The time step of an iteration. Defaults to a value slightly shorter than the maximum acceptable value for a stable simulation.</para>
	</listitem>
	<listitem>
	  <para><filename>block_size = <parameter>10</parameter></filename></para>
	  <para>The size of the basic calculation block, in cells (that means, in units of <filename>delta_x</filename>. It affects performance when too small or too large. Defaults to 10.</para>
	</listitem>
	<listitem>
	  <para><filename>num_pml = <parameter>10</parameter></filename></para>
	  <para>The size of the perfectly matched layers, in cells. Defaults to 10. Note that the PMLs are added outside the working space, so this parameter doesn't change the size of the actually computed structure.</para>
	</listitem>
	<listitem>
	  <para><filename>pml_refl = <parameter>1.e-3</parameter></filename></para>
	  <para>The theoretical reflection of the perfectly matched layers under normal incidence. Defaults to 1.e-3, that is 0.1&nbsp;%.</para>
	</listitem>
	<listitem>
	  <para>One of the following:</para>
	  <itemizedlist>
	    <listitem>
	      <para><filename>injection = <parameter>sinus 10</parameter></filename></para>
	      <para>Set the injection to a single frequency. The parameter gives the number of periods during which the signal takes place.</para>
	    </listitem>
	    <listitem>
	      <para><filename>injection = <parameter>gauss 20</parameter></filename></para>
	      <para>Set the injection to a gaussian spectrum around the base frequency. The parameter gives the relative frequency width in percent.</para>
	    </listitem>
	    <listitem>
	      <para><filename>injection_file = <parameter>kikoo.dat</parameter></filename></para>
	      <para>Use the contents of a file as the amplitude of the injected signal. The file should be ASCII data, with one value per line, meaning one value per iteration.</para>
	    </listitem>
	  </itemizedlist>
	  <para>The default injection is a sinus with 10 periods of starting time.</para>
	</listitem>
	<listitem>
	  <para><filename>injection_pos = <parameter>10,50,25</parameter></filename></para>
	  <para>The position of the injection, in cells. Defaults to the center of the simulation area. Currently, only dipole injection is supported.</para>
	</listitem>
	<listitem>
	  <para><filename>injection_dir = <parameter>0.707,-0.707,0</parameter></filename></para>
	  <para>The direction and maximal amplitude of the injection, in C.m.
	  The computed injection is multiplied by each of these factors
	  for the directions x, y and z respectively. Defaults to 0,0,1.
	  As a consequence, by default, the computed numerical values
	  are normalized for a dipole moment equal to 1&nbsp;C.m.</para>
	</listitem>
      </itemizedlist>
    </sect2>

    <sect2>
      <title>Defining the output</title>
      <para>Each of these parameters can be used as many times as you want, to have multiple outputs.</para>
      <itemizedlist>
	<listitem>
	  <para><filename>output_cartoE = <parameter>0-2000/100</parameter></filename></para>
	  <para>Output cartographies for the electric field (all three components), in the HDF5 format. The parameter explains at which iterations the output should be made. The above example makes this output every 100 iterations during the first 2000 iterations. Any of these parameters can be omitted, defaulting respectively to zero, the last iteration and 100.</para>
	</listitem>
	<listitem>
	  <para><filename>output_cartoH = <parameter>/1000</parameter></filename></para>
	  <para>Same as above, but for the magnetic field.</para>
	</listitem>
	<listitem>
	  <para><filename>output_ponctE = <parameter>60,70,25</parameter></filename></para>
	  <para>Output the three components of the electric field at each iteration, at the point defined by the three coordinates, in unit cells. The output file has 4 columns: the time in seconds, and the field in the 3 directions. If Tessa was built with support for discrete Fourier transforms, a file containing the Fourier transform is output as well, the first column containing the frequency in hertz.</para>
	</listitem>
	<listitem>
	  <para><filename>output_ponctH = <parameter>60,70,25</parameter></filename></para>
	  <para>Same as above, but for the magnetic field.</para>
	</listitem>
	<listitem>
	  <para><filename>output_poynting = <parameter>45-55,70,45-55</parameter></filename></para>
	  <para>Output the flow of the Poynting vector through a rectangular surface. The size of the surface is defined by two couples of coordinates and its position is defined by one single coordinate, in unit cells. The coordinates are always in the x, y, z order; the one being alone defines the direction of the plane.</para>
	</listitem>
	<listitem>
	  <para><filename>total_loss = <parameter>1</parameter></filename></para>
	  <para>Output the flow of the Poynting vector through all external surfaces. This is the total power lost by the system. Defaults to 0 (disabled).</para>
	</listitem>
      </itemizedlist>
    </sect2>
  </sect1>


  <sect1>
    <title>Invoking Tessa</title>
    <para>Run the simulation you defined above by typing <filename>tessa tchat.fdtd</filename> and wait. Tessa is believed to run faster than commercial implementation of the FDTD algorithm, but this algorithm is nevertheless slow.</para>
  </sect1>


  <sect1>
    <title>Extracting the results</title>
    <sect2>
      <title>Viewing cartographies</title>
      <para>The HDF5 format used for the output contains three-dimensional data. It is possible to directly view this data using tools like <ulink url="http://vis5d.sourceforge.net/">Vis5d+</ulink> or <ulink url="http://mayavi.sourceforge.net/">MayaVi</ulink>, but it is generally more convenient to extract it as two-dimensional pictures. You can do it very easily using <command>h5topng</command> from the <emphasis>h5utils</emphasis> package. For example, to extract the data for the <parameter>y</parameter> component of the electric field at <parameter>z = 25</parameter> (in unit cells), just run:</para>
      <blockquote>
	<programlisting>h5topng -Z -c bluered -S 3 -C tchat1.h5 -d y_comp -z 25 E*.h5</programlisting>
      </blockquote>
      <para>You can refer to the <ulink url="http://ab-initio.mit.edu/h5utils/h5topng-man.html"><command>h5topng</command> manual</ulink> for more information.</para>
    </sect2>

    <sect2>
      <title>Viewing spectra</title>
      <para>The <filename>.dat</filename> files where spectra are written can be directly used for visualization. Just import them in a spreadsheet, or use <ulink url="http://plasma-gate.weizmann.ac.il/Grace/">xmgrace</ulink>.</para>
    </sect2>
  </sect1>
</article>