Setting up MATLAB Frame File
Software
The present utilities for reading Frame File data with MATLAB
include
1) The FrameL functions frgetvect
and frextract
from Ligotools
2) The Channel
class and structure from Matapps.
Install and setup FrameL
Install Channel for
local files
Setup Channel for use with LDR
The Channel class requires the Ligotools functions, so you need to
install it for either packages.
Setup of
Ligotools
MATLAB functions
Note that often Ligotools will already be installed on your
system. Ligotools are
now installed on the LHO GC computers and LHO Grid computers.
If using a different computer, at present Ligotools is known to work
under
Linux and Solaris. To install Ligotools under Mac OS X, you need
to
follow some additional instructions, which may work. Work is
underway to
setup Ligotools under Windows.
Make sure you install the Fr
and Frv
packages from Ligotools.
2) Add Ligotools initialization to your startup profile.
On the LHO GC computers this is already done. On the LHO
LDAS
computers,
you should add the following to your .bash_profile
or .cshrc
file.
#
Ligotools setup
eval
`/usr/local/ligotools/bin/use_ligotools`
On other systems, add a similar use_ligotools invocation depending
on where it was installed.
3) Check your FrameL installation.
On LHO LDAS, this will require either (a) logging out and back in
to
run the .bash_profile script, or
(b) running the use_ligotools script as above.
At your command shell prompt, type FrDump which should print
out the help text as below:
[thorne@lcgt~]FrDump
This program reads frames from one or more input files, and
print
the requested
information.
--------------------------------------------------------------------
Syntax is: FrDump -i <input
file>
-f <first frame: (run # frame #) or (GPS time)>
-l <last frame: (run # frame #) or (GPS time)>
-t <list of tag
channels>
-d <debug
level>
-c -1 to leave the data
uncompressed
-h (to get this
help)
...
4) Add FrameL functions to MATLAB path
To call FrameL function from within MATLAB, it is easiest
to add their location to your MATLAB path. After the Ligotools
setup is done, an environment variable (LIGOTOOLS)
points to
the Ligotools directory. The links to frgetvect, frextract are in
the matlab
sub-directory.
Use the following to add FrameL to your MATLAB path from
within MATLAB. At the MATLAB prompt, do the following:
>>
toolDir = getenv('LIGOTOOLS');
>>
matDir = strcat(toolDir,filesep,'matlab');
>>
addpath(matDir);
This can also be added to a 'startup.m'
file you created in a
'matlab'
sub-directory off your home directory to automatically
add it when MATLAB is started.
5) Check that FrameL functions can be called from MATLAB
Check that this is working by getting the frgetvect help text from
within
MATLAB. Enter 'help frgetvect' at the MATLAB prompt as below,
and the help text should be displayed.
>>
help frgetvect
FRGETVECT - Read a data vector from a frame file
by B. Mours Caltech&LAPP May 2, 2002
This Matlab mex file extract from a frame file the data for one
vector (ADC ot Proc or Sim data) (this is for Matlab version 5)
The input arguments are:
1) file name
2) vector name
3) (optional) starting GPS time(default= first frame in the file)
4) (optional) number of frame (default = 1 Frames)
...
Install Channel class for local files
The MATLAB `Channel' class software is now available under
'matapps'
project in the lscsoft CVS repository operated by DASWG. It
is
also available as a separate tar-ball.
The Channel class software works with the frgetvect function to
retrieve a time-series of arbitrary length from one or more frame files.
On computers which do not have directory access to an LDR
database of frame files (like the LHO GC computers or a laptop),
only this basic installation is needed.
1) Get Channel software
The Channel software is under matapps/src/utilities/Channel
in the
lscsoft repository. See the DASWG
webpage on
lscsoft CVS
for instructions on retrieving this update.
The Channel software (now version 3.1) is also available in a tar-ball from PSU.
The tar-ball expands into a 'MatlabChannel'
sub-directory.
The package has a root directory with sub-directories @Channel
for the class definition, documentation which has
the
sofware specification and test.
2) Add Channel package to MATLAB path
As with FrameL, it is easiest to add this software to your path
inside MATLAB. As above, we use the addpath command
>>
addpath <path_to_Channel>
where <path_to_Channel> is the directory the Channel
software is in, If the lscsoft is off your home directory,
this could be `/lscsoft/src/matapps/src/utilities/Channel'
Again, add this to a startup.m file.
Here is an example startup.m file
with both Ligotools and Channel.
3) Check that Channel can be called from MATLAB
After adding the path above, try the Channel and chanstruct
help text at the MATLAB prompt
>>
help Channel
CHANNEL
- Channel class contructor
chanObj = Channel(chanName[,startTime]) creates an IGWD Channel object
using
the channel name 'chanName'
The syntax of valid channel names (i.e. H2:LSC-AS_Q)
Xn:Name X is site (H Hanford, L Livingston, V Virgo)
n is detector number (0 for environment monitoring)
Name is detector channel name, usually a location and
signal type
'startTime' [OPTIONAL] Set a base GPS Start time for TimeSeries objects
pulled from the channel
>>
help chanstruct
CHANSTRUCT
- Channel structure contructor
chStruct = chanstruct(chanName[,startTime]) creates an IGWD Channel
structure using the channel name 'chanName'
The syntax of valid channel names (i.e. H2:LSC-AS_Q)
Xn:Name X is IFO location (H Hanford, L Livingston, V Virgo)
n is detector number (0 for environment monitoring)
Name is detector channel name, usually a location and
signal type
startTime - [OPTIONAL] Sets a base GPS start time (gpsStart) so that
all time-series ranges are offset from this base (instead of base = 0)
chStruct has the following structure
name - channel name (from chanName input)
statusCode - 0 if name syntax OK, 1 otherwise
site - data location (default LDR) **UNUSED AT PRESENT**
instrument - IFO site (default first letter of channel name)
type - frame data type (default RDS_R_L1)
gpsStart - base GPS start time (default = 0)
rate - channel sample rate (default = 0)
Setup Channel for use with
LDR
The Channel class and structure are specifically designed to work
with
a searchable database to located frame files. The initial
implementation
is for the LDR database used by the LIGO Tier 1 and 2 'grid' computers
to
distribute frame files. To set this up, a number of environment
variables
must be defined to tell Channel where the MySQL libraries are and
how to access the local LDR database.
**This setup is
NOT done on systems without LDR (LHO GC, laptops, etc.)**
The good news is that this should only need to be done once on a system
if
you add it to the .bash_profile or .cshrc.
1) Define location of MySQL library, includes
At present, Channel uses MySQL functions to open a socket to
LDR's MySQL database for queries.
On the LHO Grid machines, the following in .bash_profile
will
define these locations.
#
MySQL setup
export
MYSQL_LIB=/tmp/mysql/lib
export
MYSQL_INC=/tmp/mysql/include
LD_LIBRARY_PATH=$LD_LIBRARY_PATH:$MYSQL_LIB
export
LD_LIBRARY_PATH
2) Build mlframequery MEX file in Channel
Once the MySQL libraries are located, the OS-specific MEX file
must be created for Channel.
a) Change to the directory where Channel is installed. An example
when it is in lscsoft is
$
cd ~/lscsoft/matapps/src/utilities/Channel
b) Startup MATLAB (typically with the 'matlab'
command).
You won't need a graphical window, so simply use
$
matlab -nodisplay
c) At the MATLAB prompt, use the 'makechannelmex' function
to build the mlframequery MEX file. After a pause, a successful
build should be reported.
>>
makechannelmex;
On Linux systems, this will be file mlframequery.mexglx. On
Mac OS X, this will be file mlframequery.mexmac.
3) Define location and access to LDR
To query the LDR database, the software needs to know where
the LDR host is, the name of the local metadata table, and the
username and password for a read-only MySQL account on
that LDR database.
On the LHO Grid computers, use the following in .bash_profile
#
LDR setup
export
LDR_SQL_HOST=ldas-gridmoni
export
LDR_METADATA=ldr_table_LDAS_LHO
export
LDR_SQL_USER=lho_reader
export
LDR_SQL_PWD=reader_only
** Here is a copy of an example .bash_profile on ldas-pcdev1 **
4) Test Channel setup and connection to LDR
With the LDR location variables defined as above, we
can run the Channel class and structure tests.
** For the LHO
Grid computers at present, only the Level 3
RDS files
(RDS_R_L3), Thus special variants of the
test need to be
used **
a) Change to the test sub-directory of the Channel package
$
cd test
b) Start up MATLAB
$
matlab -nodisplay
c) At the MATLAB prompt, invoke the class tests
>>
chanclasstests('RDS_R_L3');
d) Then run the structure tests
>>
chanstructtests('RDS_R_L3');
If these pass, then you are ready to use Channel on the grid
computers.
Keith Thorne
Last modified: Sat Aug 21 2004
1:45PM PDT