------------------------------------------------------------
SimTools 0.7          25.01.2013
http://www.gwoptics.org/simtools

SimTools is a collection of Matlab utility functions 
to be used for optical simulations or together with various 
simulation programs in the gravitational wave community.

2006 - 2013 Andreas Freise, Charlotte Bond
------------------------------------------------------------

Summary
----------------

SimTools is simply a collection of Matlab m files,
containing utility functions or example scripts.
This set of files was originally written to be used with 
Finesse (www.gwoptics.org/finesse), providing Matlab 
functions to read, write and edit Finesse input files
automatically. Since then this package has been extended 
with numerous files related to optics and simulations.
In particular, it includes an extensive set of Matlab 
functions and scripts regarding Gaussian optics
and higher-order modes. Furthermore, Simtools includes 
many contributed functions from several other people, such as,
for example a slightly rewritten version of OSCAR by 
Jerome Degallaix:
http://www.mathworks.com/matlabcentral/fileexchange/20607
Feel free to send us your own Matlab function to be included 
in the Simtools package!

Installation
----------------
To install, just copy these files into a directory
which is in your Matlab path. A list of functions can be 
printed using FT_help. Try 'FT_help()' to get started. 


Documentation
----------------
SimTools does not come with a manual. However, we tried
to keep the individual files clear and somewhat commented.
This code will help you doing optical simulations but it will
not do them for you!

All Simtools functions start with the prefix FT_...
and example scripts are named as FTE_...
To get started we recommend that you look for and run
some of the example scripts.

Many of these functions have been tested by many people many
times and should work correctly. However, the code is
not automatically tested, so there is always a chance that
a type has sneaked in. Also, some of the functions might
be new additions and not fully tested. So, please use
at your own risk and try to perform simple tests before
trying to generate any important or significant result.


Use with Finesse
----------------
If you want to use SimTools with Finesse you need to 
specify the path to the Finesse binary in the file with the
command:
FT=FT_init_Finesse(...);

Please have a look at the examples in the sub-folder
`finesse/example' to understand the use of SimTools with
Finesse.

Future Development
------------------
By default all useful Matlab functions which are developed in our 
research group and are related to optical simulations
will eventually be moved into the SimTools package. This is
a slow but consistent process. In addition, we are happy to
include contributed code to make the package more useful.
Please contact us via http://www.gwoptics.org if you have
questions or suggestions.

Copyright notice
------------------

The MIT License

SimTools, Copyright (c) 2006 onwards, Andreas Freise, Charlotte Bond

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in
all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
THE SOFTWARE.


List of included functions
--------------------------

 - FT_function_template: (no description)
 - FT_help: (no description)
 - FT_ABCD_lens: Computes the ABCD Matrix for a thin lens of focal lengh f
 - FT_ABCD_mirror: Computes the ABCD Matrix for the reflection of a curved mirror
   or beam splitter
 - FT_ABCD_space: Computes the ABCD Matrix for a free space propagation of length L
 - FT_ABCD_trace_beam: (no description)
 - FT_cavity_ABCD_to_q: Computes the Gaussian beam parameter of cavity eigenmodes
 - FT_check_cavity_ABCD: computes the stability parameter m from the ABCD matrix of an
   optical resonator
 - FT_compute_cavity_ABCD: Computes the ABCD matrix and stability parameter
   for an optical resonator
 - FT_invert_ABCD: Computes the inverse of an ABCD matrix
 - FT_multiply_ABCDs: Multiplies two ABCD matrices
 - FT_q_ABCD_q: Transforms a Gaussian beam parameter by an ABCD matrix
 - FT_HermitePoly: (no description)
 - FT_FFT_cavity_scan: Reads temporary files and computes the circulating power
   as a function of the cavity tuning
 - FT_FFT_lens: Computes the effect of a lens on a 2D complex light field
 - FT_FFT_mirror: Computes the effect of a mirror on a 2D complex light field
 - FT_FFT_plot_field: Plots 2D arrays of a light field amplitude in the x-y plane
 - FT_FFT_precompute_roundtrips: Computes fields inside a cavity and saves result in
   temporary data files
 - FT_FFT_propagate: Performs FFT propagation of a 2D complex light field
 - FT_FFT_reorganise_tmp_files: Reads temporary files saved by FT_FFT_precompute_roundtrips
   and saves them in a new format for FT_FFT_cavity_scan
 - FT_FFT_required_cavity_roundtrips: Estimates required number of roundtrips to achieve requested
   accuracy in computing the circulating power
 - FT_FFT_required_scan_accuracy: Estimates the required number of steps in a full cavity scan
   to find peaks
 - FT_FFT_results_buildup: Reads temporary files saved by FT_FFT_precompute_roundtrips
   and saves in a new format for FT_FFT_cavity_scan
 - FT_FFT_results_cavity_fields: Computes the reflected and transmitted fields of a cavity
 - FT_FFT_scan_range: Creates a vector of positions (tunings) for a cavity scan
 - FT_hanning_window2D: (no description)
 - FT_init_grid: Creates a structure grid for storing useful information
 - FT_tilt_map: Computes a tilted mirror map
 - FTE_FFT_premodecleaner: (no description)
 - FTE_FFT_results_premodecleaner: (no description)
 - FT_check_for_kat_binary: (no description)
 - FT_convert_finesse_4D: (no description)
 - FT_create_new_FT: (no description)
 - FT_create_new_kat_run: (no description)
 - FT_init_Finesse: Creates a new "FT" structure
 - FT_kat_clean: (no description)
 - FT_make_finesse_video: Reads finesse output file with x3axis and creates video output
 - FT_min_max: (no description)
 - FT_prepare_kat_filename: (no description)
 - FT_run_kat_simulation: (no description)
 - FT_save_finesse_map: (no description)
 - FT_set_kat_filenames: (no description)
 - FTE_finesse_01: Example for using SimTools with Finesse: find the kat binary.
 - FTE_finesse_02: Example for using SimTools with Finesse: read and write a Finesse input file.
 - FTE_finesse_03: Example for using SimTools with Finesse: finding specific parameters.
 - FTE_finesse_04: Example for using SimTools with Finesse: changing value of a constant.
 - FTE_finesse_ad_nm: Example for using SimTools with Finesse: get mode coefficients of output beam
 - FTE_finesse_ccd: Example for using SimTools with Finesse: get mode coefficients of output beam
 - FT_add_line_to_block: (no description)
 - FT_comment_block: (no description)
 - FT_comment_lines_in_block: (no description)
 - FT_copy_block: (no description)
 - FT_copy_lines_block_to_block: (no description)
 - FT_create_new_block: (no description)
 - FT_find_element_in_active_block: (no description)
 - FT_find_element_in_all_blocks: (no description)
 - FT_find_element_in_block: (no description)
 - FT_find_text_in_active_block: (no description)
 - FT_find_text_in_all_blocks: (no description)
 - FT_find_text_in_block: (no description)
 - FT_index_of_block: (no description)
 - FT_list_block_names: (no description)
 - FT_print_block: (no description)
 - FT_read_blocks_from_file: (no description)
 - FT_read_kat_constant: (no description)
 - FT_remove_comment_char_in_block: (no description)
 - FT_remove_lines_from_block: (no description)
 - FT_search_string_for_block_commands: (no description)
 - FT_uncomment_block: (no description)
 - FT_uncomment_lines_in_block: (no description)
 - FT_write_blocks_into_file: (no description)
 - FT_write_kat_constant: (no description)
 - FT_read_kat_output_data: (no description)
 - FT_read_kat_output_header: (no description)
 - FT_CON_field: Fills a 2D grip with the field amplitudes for 
   a conical beam at the waist
 - FT_conv_fields: Computes the scalar product between two complex 2D data arrays
 - FT_gauss_coefficients_to_field: Computes a complex field array from 
   a set of Gaussian mode coefficients
 - FT_get_mode_coefficient: Returns the value of a mode coefficient in a structure "gc"
 - FT_HG_field: Fills a 2D grid with complex field amplitudes for a Hermite-Gauss beam
 - FT_init_gauss_coefficients: Returns an empty array for storing mode coefficients
 - FT_init_gauss_param: Creates a structure "gp" storing the Gaussian beam parameter "q"
 - FT_LG_cos_field: Fills a 2D grid with complex field amplitudes for
   a (co-)sinusoidal Laguerre-Gauss beam
 - FT_LG_field: Fills a 2D grid with complex field amplitudes 
   for a Laguerre-Gauss beam
 - FT_mode_coefficients_to_field: Computes a complex field array from a set of Gaussian mode coefficients
 - FT_new_mode_coefficients: Returns an empty array for storing mode coefficients
 - FT_power_in_field: Computes the total power in a complex field array
 - FT_q_to_Psi: Computes the Gouy Phase Psi(z) from the Gaussian beam parameter q
 - FT_q_to_Rc: Computes the radius of curvature of a phase front from the Gaussian 
   beam parameter q
 - FT_q_to_w: Computes the beam radius from the Gaussian beam parameter q
 - FT_q_to_w0z: Computes the waist radius and waist position from the Gaussian beam
   parameter q
 - FT_q_to_zr: Computes the Rayleigh range from the Gaussian beam parameter q
 - FT_Rcw_to_w0z: Computes the waist radius and waist position from beam size w(z)
   and radius of curvature Rc(z)
 - FT_SG_field: Fills a 2D grip with the field amplitudes
   for a super-Gaussian beam at its waist
 - FT_ulp: Computes the field amplitude of a Laguerre-Gauss mode (helical)
 - FT_ulp_cos: Computes the field amplitude of a Laguerre-Gauss mode (sinusoidal)
 - FT_un: Computes the field amplitude of a 1D Hermite-Gauss mode
 - FT_unm: Computes the field amplitude of a Hermite-Gauss mode
 - FT_update_gauss_param: Computes the parameters of a Gaussian beam from the beam parameter
 - FT_clipping_loss_LG: Computes the clipping loss experienced by a 
   helical LG beam on a circular mirror
 - FT_fit_beam_size: Fits the beam size function to a set of measured sizes of a Gaussian
   beam to determine the beam waist size and position.
 - FT_fit_GaussBeam: Fits a Gaussian mode shape to a 2D data grid
 - FT_fit_GaussBeam_intensity: Fits a Gaussian mode shape to a 2D data grid
 - FT_fit_LG: Fits a helical LG mode shape to a 2D data grid
 - FT_fit_LG_cos: Fits an LG mode shape to a 2D data grid
 - FT_guess_center_LG: Guesses the center of an LG mode shape in a given 2D array
 - FT_guess_size_LG: Tries to guess the size of an LG mode shape in a given 2D array
 - FT_lg2hg: (no description)
 - FT_mode_content: Computes the deconvolution of a given field distribution,
   field_in, into Gaussian modes
 - FT_print_gauss_coefficients: Prints the content of a mode coefficient structure "gc"
 - FT_print_gauss_coefficients_to_file: Prints the content of a mode coefficient structure "gc"
 - FT_print_mode_coefficients: Prints the content of a mode coefficient structure "gc"
 - FT_set_mode_coefficient: Sets the value of a mode coefficient in a structure "gc"
 - FTE_fit_LG: Example for fitting an LG mode shape to an CCD image
 - FTE_lg2hg_example: (no description)
 - FTE_make_test: (no description)
 - FTE_mode_contribution: Example for fitting modal decomposition of a Gauss beam
 - FTE_plot_Gauss: Example for plotting a Gaussian beam profile
 - FTE_power_in_field: Example for using computing the total power in a complex field array.
 - FT_Agilent6000_bin_to_ascii: Reads a binary file saved by an Agilent 6000 scope and saves
   the data as an ascii file
 - FT_read_Agilent6000_ascii: Reads an ascii data file saved by an Agilent 6000 scope
 - FT_read_Agilent6000_bin: Reads a binary data file saved by an Agilent 6000 scope
 - FT_read_Agilent6000_info: Reads info file saved by an Agilent 6000 scope
 - FT_read_HPNA_ascii: Reads an ascii data file saved by an HP network analyser
 - FT_read_WinCamD_ascii: Reads an ascii data file saved by an WinCamD beam analyzer
 - FT_calibrate_map_diameter: calibrates the delta x, y values of a map
 - FT_create_aperture_map: computes and writes an aperture (absorption) map
 - FT_create_elliptical_aperture_map: (no description)
 - FT_create_sphere_for_map: (no description)
 - FT_find_map_radius: estimates the radius of a mirror given a mirror map
 - FT_invert_mirror_map: inverts (flips) a mirror map
 - FT_map_rms: Computes the rms surface distortion of a mirror surface map
 - FT_new_surface_map: (no description)
 - FT_plot_mirror_map: plots a mirror surface map
 - FT_read_surface_map: (no description)
 - FT_read_zygo_map: Reads a mirror surface map in Zygo interferometer format
 - FT_recenter_mirror_map: recenters a mirror map by computing the center of gravity
 - FT_remove_curvature_from_mirror_map: fits a curvature to a mirror map and removes it
 - FT_remove_elements_from_map: (no description)
 - FT_remove_elements_outside_map: Removes outer ring of NaN data from a mirror map
 - FT_remove_offset_from_mirror_map: removes an offset from a mirror map
 - FT_remove_piston_from_mirror_map: fits a tilted plane to a mirror map and removes it
 - FT_select_area_in_map: (no description)
 - FT_write_map_fit_results: writes a the results of a surface fit to a map
 - FT_write_surface_map: writes a mirror map into a file in Finesse readable format
 - FT_convert_ligo_map_for_finesse: (no description)
 - FT_read_ligo_map: (no description)
 - FT_convert_virgo_map_for_finesse: converts a Virgo mirror map into Finess readable format
 - FT_plot_virgo_map: (no description)
 - FT_read_virgo_map: (no description)
 - FT_virgo_aperture_map: (no description)
 - FTE_zygo_map_01: Example for reading a Zygo mirror map
 - FTE_zygo_map_02: Example for reading a Zygo mirror map
 - FTE_zygo_map_03: Example for reading a Zygo mirror map
 - FTE_zygo_map_04: Example for reading a Zygo mirror map
 - FT_add_mirror_map: Computes mirror maps for reflection and transmission of a mirror
 - FT_cavity_fields: Computes the fields of a two mirror cavity
 - FT_cavity_roundtrip_Gouy: Computes the roundtrip Gouy phase of a cavity eigenmode
 - FT_cavity_throughput: Computes the throughput of a cavity as a function of power
   transmittance and cavity finesse
 - FT_cavity_w2Rc: Computes mirror radius of curvature from beamsize for
   a linear, symmetric cavity
 - FT_fit_cavity_finesse: Fits the Airy function of a cavity to a measured scan of
   cavity throughput
 - FT_init_cavity: Creates "cavity" structure for storing parameters of cavity
 - FT_init_mirror: Creates "mirror" structure for storing parameters of a mirror
 - FT_init_space: Creates "space" structure for storing parameters of a free space
 - FT_add_comment_char_to_line: (no description)
 - FT_get_element_from_line: (no description)
 - FT_parse_line: (no description)
 - FT_remove_comment_char_from_line: (no description)
 - FT_remove_comment_from_line: (no description)
 - FT_remove_comment_line: (no description)
 - FT_remove_phrase_from_string: (no description)
 - FT_replace_underscores: (no description)
 - FT_replace_value_in_line: (no description)
 - FT_split_line: (no description)
 - FT_uncomment_line: (no description)
 - FT_blur_data: Blurs a 2D data array with a Gaussian filter
 - FT_box_data: Selects a subset of a 2D data grid,
   such that it contains all data > threshold
 - FT_center_of_mass: Computes the center of mass of a data array and returns the coordinates
 - FT_create_tmp_filename: Creates a name for temporary files using the current datestring
 - FT_datestring: Creates datestring of current date and time
 - FT_message: prints a message to stdout
 - FT_normalise_data: Normalises a data set so that max/min values are those given by user
 - FT_remove_piston_data: Removes a tilt from a 2D data array
 - FT_rotate_2D: Rotates a 2D data grid by a given angle
 - FT_warning: prints a message to stdout
 - FT_flip_colormap: Returns colormap, good for bipolar signals
 - FT_neg_colormap: Returns negative part of FT_flip_colormap
 - FT_pos_colormap: Returns positive part of FT_flip_colormap
 - FTE_rotate: (no description)
 - FT_check_for_gzip: Checks if a filename ends in .gz and if so unzips it
 - FT_delete_file: (no description)
 - FT_files_in_folder: Lists all files with a given extension in a folder
 - FT_find_text_in_file: (no description)
 - FT_make_backup: (no description)
 - FT_remove_file_extension: (no description)
 - FT_bincoeff: (no description)
 - FT_binomial: (no description)
 - FT_JacobiPol: computes the Jacobi polynomial
 - FT_kd: Computes the Kronecker delta function
 - FT_LaguerrePol: (no description)
 - FT_log_ticks: Generates a string for setting major tick marks in a plot
 - FT_print_progress: Prints a progress statement in a loop
