BTEC

Building

BTEC uses CMake to generate its build files. In theory, CMake can be used to generate build files on multiple platforms. It supports creating makefiles for Linux/Unix, xcode projects for Mac, and Visual Studio projects for Windows. However, BTEC is only tested on Linux.

To build BTEC using cmake, you just need to create a build/ directory, generate a makefile, and then run make.

 mkdir build
 cd build
 cmake ..
 make

Configuring

Sensors

Currently, BTEC supports using sensors to monitor the thermal grid and laser irradiance. Thermal sensors are added to the main BTEC configuration file, irradiance sensors are added to the emitter files. A damage sensor is available, which monitors the thermal grid and computes the damage integral. The most common sensor configuration includes one or more thermal sensors to monitor the temperature at different locations of interest and a damage sensor that will be used to determine the damage threshold.

Assume we have one damage sensor to compute the damage integral at the surface of the tissue, configured in the file sensor-damage-surface.btec, and two temperature sensors, configured in sensor-temp-surface.btec and sensor-temp-100um.btec to monitor the temperature at the tissue surface, and at a depth of 100 microns.

$ ls sensor-*btec
   sensor-damage-surface.btec
   sensor-temp-surface.btec
   sensor-temp-100um.btec

These config files are specified in the main BTEC config file. In the main config file, there will be a section similar to this

# BTEC main config
...
Sensor[0] = "sensor-damage-surface.btec"
Sensor[1] = "sensor-temp-surface.btec"
SEnsor[2] = "sensor-temp-100um.btec"
...

Running

Output Files

BTEC can (and will) generate many different output files. What BTEC outputs, and how often it does so, can be configured (see Configuring). The output files can be separated into two categories: Sensor output and non-Sensor output.

(Warning: historical digression follows)

Originally, BTEC's output comparability was a single log interval, so that the user could tell BTEC how often to output data, but all data files were output at each log interval. This caused several problems, including inconvenience, so the ability to specify a log interval for each type of data separately. This allowed the user to "turn off" logging of some data types that were not important for their applications. This also made it possible to output the data of interest at a shorter log interval than the other data types (for example, writing the temperature distribution every time step, while only writing the laser source term every 1000 time steps) so that high resolution graphs could be created without filling the hard drive (Lt. Wooddell once filled an entire 2 TB hard drive by running BTEC with all logging turned on and leaving the simulation to run over night.) While this new capability was a great improvement, it still generated much more data than was typically needed. A common use scenario for BTEC involved running BTEC for several different laser beam configurations and plotting the temperature at a specific point (such as the point at the center of the beam on the tissue surface) as a function of time.

Sensors where introduced to solve this problem. A Sensor is an object that monitors a sub-section of the overall grid (like a sensor embedded in the tissue) and can log data. For example, a temperature sensor can be configured to monitor the volume contained in 0 < r < 0.1, 0.1 < z < 0.2, and then used to log the temperature within this volume. The sensor can log both the entire temperature distribution within the volume at each time step, or log just the maximum temperature in the volume. Multiple sensor can be configured to monitor different volumes in the tissue, and logging of the entire volume and the maximum value in the volume can be controlled separately.

End of historical recall

Sensors are the preferred method for logging data in BTEC because they can be configured to only log the data that will be needed for post processing. However, not all data types can be monitored with a sensor (such as the source term), so the old logging system is still in place.

When running BTEC, the second argument specifies a datafile prefix that is used to name all output files. If a "Threshold Search" is ran, BTEC will include an iteration in the output file names which indicates which iteration of the search the files correspond to. The general pattern for output filenames is

${prefix}.${datatype}.iter.${j}.t.${time}.btlog  # threshold search
${prefix}.${datatype}.t.${time}.btlog            # single run 

In the following description of output files, we will assume that BTEC has been ran as

$ BTECthermal main.btec __prefix

Sensor Log Files

__prefix.Sensor-${i}-maxScal.btlog

__prefix.Sensor-${i}-maxScal.iter.${j}.btlog

Contains the maximum value in the volume monitored by sensor ${i} for each time step that was logged. Only one of these files is created for a given sensor. For each time step that is logged (controlled by ScalarMaxLogInterval) one line is written to this file.

For example, if Sensor[0] in the main config files specifies an "AbsThermalKelvin" over the volume 0 < r < 0.001, 0 < z < 0.001, then __prefix.Sensor-0-maxScal.btlog will contain the maximum absolute temperature in Kelvin within the volume 0 < r < 0.001, 0 < z < 0.001 at each time step logged. The comments will contain the r and z coordinates of the maximum temperature (if the volume is very large, it is possible for the position of the maximum temperature to "move" around the volume).

The file format follows the pattern

t0 f(t0)  # z0 r0
t1 f(t1)  # z1 r1
...

This file can be plotted in gnuplot with the plot command,

gnuplot> plot __prefix.Sensor-0-maxScal.btlog

This will plot the maximum scalar value as a function of time.

__prefix.Senosr-${i}-Scal.t.${time}.btlog

__prefix.Senosr-${i}-Scal.iter.${j}.t.${time}.btlog

Contains entire volume monitored by sensor ${i} at the time ${time}. Several of these files may be written for each sensor during a simulation, one files is written for each time step that is logged.

The file format is as follows

z0 r0 f(z0,r0)
z0 r1 f(z0,r1)
...
z0 rN f(z0,rN)

z1 r0 f(z1,r0)
...

This file can be plotted in gnuplot with the splot command,

gnuplot> splot __prefix.Sensor-0-Scal.t.0.btlog

This will plot the scalar function over the entire sensor volume for time = 0.

Non-Sensor Log Files

__prefix.thermal.t.${time}.btlog

__prefix.thermal.iter.${j}.t.${time}.btlog

Contains the entire thermal grid (a function of r and z) at a specific time.

__prefix.sourceTerm.t.${time}.btlog

__prefix.sourceTerm.iter.${j}.t.${time}.btlog

Contains the source term to the heat equation (the power absorbed by the tissue) at a specific time.

__prefix.axialTemp.t.${time}.btlog

__prefix.axialTemp.iter.${j}.t.${time}.btlog

Contains the temperature on the z-axis (r = 0) at a specific time. This data is included in the "thermal" output file, but could be logged even when logging the entire thermal grid is turned off.

__prefix.maxTemp.btlog

__prefix.maxTemp.iter.${j}.btlog

Contains the maximum temperature within the entire thermal grid at each time step. The data logged here is equivalent to what would be logged by the maxScal data of a sensor that covered the entire simulation volume.

__prefix.state.out

Contains the entire configuration for the run. This serves as a record for the input associated with a specific run. The actual input files can be modified to run different configurations and as long as different prefix's are used, the input used to generate each output file set will be known. This file is also very handy for post processing because scripts can easily extract information about the simulation configuration.

__prefix.summary.out

Contains a copy of the standard output printed by BTEC.

BTECtools

Many times, it is necessary to run BTEC for multiple different exposure configurations. For example, we may want to predict the trend for damage threshold irradiance as a function of exposure time, so we run a given BTEC configuration with multiple exposure durations. Even though we are only changing one configuration parameter (the "duration" key in the emitter configuration file), this will require us to create a separate emitter file for each exposure duration. On top of that, we will have to create a separate top-level configuration file for each run as well, since the top-level configuration file specifies which emitter file will be used. This is an example of a simple task that can be very repetitive, tedious, and error prone. Enter BTECTools...

BTECtools is a collection of scripts (mostly written in python and bash) that greatly simplify the processes of configuring, running, and post-processing multiple BTEC exposure configurations. With BTECtools, you can

1. generate multiple BTEC configuration files that vary one or more parameters automatically.
2. create a BTEC "project directory", a self contained folder containing BTEC configuration files than can be copied to another location, remote or local.
3. generate a tables summarizing the data files generate by multiple BTEC runs.