Top / Optics / Software / tessa / quickreference

Tessa quick reference guide

Josselin Mouette

École centrale de Lyon


version 0.3.1 , 07 July 2004

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.

Installing Tessa

When Tessa is not available as a binary package for your system, installation is done through GNU autotools:

   (as root) make install

You will need as prerequisites:

  • The Hierarchical Data Format 5 library which is used to read and store all the data used by Tessa.
  • Zlib, which is a prerequisite for HDF5 anyway.
  • Necessary only if you use the provided module to generate the optical structures:
    • Python, the scripting language used to generate the structures.
    • NumPy?, the Numeric Python extension. Numarray is not yet supported because it is too slow.
    • PyTables?, which brings in HDF5 support for Python.
  • (optional) h5utils, a set of tools to manipulate HDF5 files, for e.g. cartography extraction.
  • (optional) The Fastest Fourier Transform of the West library, version 3, which allows to output frequency spectrums.

Creating your optical structure

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 h5fromtxt from the h5utils package.

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. (the .py extension is for python scripts). This file should look like follows.

First, import the Tessa module.

   from tessa import *

Then, create an IndexFile? instance, name it as you want.


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 index parameter is the default index in the structure.

You can now fill your structure with geometric objects, e.g. cylinders.


The two first required arguments for the Cylinder constructor tell the position of its center, the two following are the radii (the second radius being None, 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.


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: x1, x2, y1, y2, z1, z2.

Note that you can also use absorbing materials. Just add a absor = value parameter, with value being the absorption coefficient in m-1.

Finally, we write the structure to HDF5 files.


Two files are written here: tchat1.h5 and tchat2.h5. You can write as many as you want, with a delta_x 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.

You can draw several other types of geometric objects with this module. The complete documentation is accessible through python's internal help. Just run python in a shell, and, in the interpreter, type "import tessa; help(tessa)" (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, learn it. Even if you don't know how to program at all, achieving such things is easy.

Once you have your script, process it:


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 h5ls, h5totxt and h5topng.

Describing the simulation

Once you have a HDF5 file containing the structure you want to simulate, you have to fill the simulation file. So, create e.g. tchat.fdtd. The .fdtd extension is purely for convenience, but it is generally a good idea. This file is a simple list of variable = value lines.

Required parameters

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

Optional parameters

delta_t = 1.11e-16
The time step of an iteration. Defaults to a value slightly shorter than the maximum acceptable value for a stable simulation.
block_size = 10
The size of the basic calculation block, in cells (that means, in units of delta_x. It affects performance when too small or too large. Defaults to 10.
num_pml = 10
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.
pml_refl = 1.e-3
The theoretical reflection of the perfectly matched layers under normal incidence. Defaults to 1.e-3, that is 0.1 %.
One of the following:
injection = sinus 10
Set the injection to a single frequency. The parameter gives the number of periods during which the signal takes place.
injection = gauss 20
Set the injection to a gaussian spectrum around the base frequency. The parameter gives the relative frequency width in percent.
injection_file = kikoo.dat
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.

The default injection is a sinus with 10 periods of starting time.>

injection_pos = 10,50,25
The position of the injection, in cells. Defaults to the center of the simulation area. Currently, only dipole injection is supported.
injection_dir = 0.707,-0.707,0
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 C.m.

Defining the output

Each of these parameters can be used as many times as you want, to have multiple outputs.

output_cartoE = 0-2000/100
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.
output_cartoH = /1000
Same as above, but for the magnetic field.
output_ponctE = 60,70,25
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.
output_ponctH = 60,70,25
Same as above, but for the magnetic field.
output_poynting = 45-55,70,45-55
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.
total_loss = 1
Output the flow of the Poynting vector through all external surfaces. This is the total power lost by the system. Defaults to 0 (disabled).

Invoking Tessa

Run the simulation you defined above by typing tessa tchat.fdtd and wait. Tessa is believed to run faster than commercial implementation of the FDTD algorithm, but this algorithm is nevertheless slow.

Extracting the results

Viewing cartographies

The HDF5 format used for the output contains three-dimensional data. It is possible to directly view this data using tools like Vis5d+ or MayaVi?, but it is generally more convenient to extract it as two-dimensional pictures. You can do it very easily using h5topng from the h5utils package. For example, to extract the data for the y component of the electric field at z = 25 (in unit cells), just run:

   h5topng -Z -c bluered -S 3 -C tchat1.h5 -d y_comp -z 25 E*.h5

You can refer to the h5topng manual for more information.

Viewing spectra

The .dat files where spectra are written can be directly used for visualization. Just import them in a spreadsheet, or use xmgrace.

トップ   編集 凍結 差分 バックアップ 添付 複製 名前変更 リロード   新規 一覧 単語検索 最終更新   ヘルプ   最終更新のRSS
Last-modified: 2009-04-28 (火) 17:36:54 (4196d)