Earthworm Migration Guide v6.3 -> v7.X
February 21, 2007
This is a quick and dirty guide to what you need to know to migrate
from V6.3 to V7.X in Earthworm. The biggest change in this migration is
that stations are now not just identified by a 3 tuple of Station,
Channel, Network, but by a 4 tuple which also includes Location code.
You will hear this referred to as SCN vs SCNL. Location code is simply
a 2 character "tie-breaker" for when you have multiple channels of the
same type at a given station. Location codes can be any convention that
the operators desire, but the location code must be limited to numbers
or letters. If location codes are not being used, the operator should
use dash dash as a placeholder for any configuration files "--". Refer
to the SEED manual at the IRIS DMC. Refer to the programmer notes
for which earthworm messages changed to accomodate SCNL vs SCN.
In addition to the SCNL change, there were 2 new features added in
the v7.X release that require new message types be added to the
earthworm.d file. The first feature, introduced in v7.0 is the reconfigure command which requires a
TYPE_RECONFIGURE message type
be added in. This feature allows an operator to modify a startstop.d
file with new modules or new rings, and have those changes be effected
without having to stop and restart all of Earthworm. The second
feature, added in v7.1, allows an operator to stop a given module using
the stopmodule command. The
stopmodule implementation requires that a TYPE_STOP message be
added to your earthworm.d. See the documentation on startstop for more
information on how to use these new features.
It is okay to run v6.3 and v7.X modules together, but if you plan on
running new modules in an old configuration you will not be able to
take advantage of the new features. Further, if you run new modules on
the old system, you will need to bring in any new message types to your
earthworm_global.d and into your earthworm.d files.
Frequently Asked Questions:
- Which modules care about SCNL vs SCN?
Can I use v7.X modules in a v6.3 environment?
- The simple answer is any module that deals with Tracebuf, Pick,
or Coda messages cares. Thus, you will need to review the documentation
for each module and see how it is affected. In short, look at your
data_source modules and make sure that you have decided on a SCNL
scheme and get them configured first. Then work your way downstream
through your processing chain. The fir and pick_ew modules are next,
followed by the binder module, and ultimately hypoinverse (aka
hyp2000). Note that example SCNL .d files are provided in the src dir
with each module.
Can I use my old v6.X module in a v7.0 environment?
- Yes, you can intermix
messages since all V7.X messages are new types, so old and new can
reside on the same rings. However you need to take care that you rename
module names so that they do not collide with old versions. It is best
to limit those running newer versions of the modules and newer
messages to reside on different rings.
How can I get old messages into the new format?
- Yes, you can intermix, but
realize that the v6.X module will only look for SCN message types and
thus you will need to use a converter (scnl2scn) to get the SCNL data
onto a separate ring in SCN format so that the v6.X module can operate.
How can I import v7.X waveform data into my v6.X environment?
- Easy, there are 2 converters
that go forward and backward: scn2scnl and scnl2scn that will map all
messages to the new or old format. They can be found in the
data_exchange module directory.
startstop v7.X won't work with my old configuration because it
complains about missing messages, what did I miss?
- Simply grab the v7.X module
you need to use to import the data (any of the data_exchange modules or
data_source modules) and make sure it is named uniquely (so that it
doesn't overwrite a v6.X version) and install it on your v6.3 system in
the bin directory. Also grab the scnl2scn
converter from v7.X and install that. Then, update your
earthworm_global.d with the new message types found in v7.X (see the
earthworm_global.d from the distro). Import the data into a new ring
called WAVE_RING_SCNL and then setup scnl2scn to convert the data to
where you want the waveforms.
How do I deal with my old v6.X SCN wave_serverV tanks?
- Because new features were
added into startstop, Earthworm's core module, you need to add in new
message types to your old earthworm.d and earthworm_global.d files. Add
in the new message types, by doing a diff on the files
- If you have only a small
amount of data you need to move from v6.X to v7.X, you can use
waveman2disk to write the section of data you need in tankplayer
format, then use the tankplayer module to replay that data back into a
ring. Once it's in a ring, you can convert it with scn2scnl, and then
import the converted tracebufs into a v7.X wave_serverV tank.
Tankplayer doesn't have a fast forward mode, so this may take some time.
- If you have months or years
worth of data in a v6.X wave_serverV tank, you may want to keep running
your v6.X wave_serverV, and start a new wave_serverV recording v7.X
SCNL tracebufs in parallel. Once the v7.X wave_serverV has been running
long enough for you to be able to search for all the historical data
you need, you can turn off your v6.X wave_serverV. Note that the wave
viewer application Swarm
is one of the few wave server clients that will allow accessing either
SCN or SCNL packets, and therefore can talk to a v6.X or a v7.X
wave_serverV server. Almost all of the earthworm modules will only deal
with with SCN if they're from v6.X and SCNL if they're from v7.X. So if
you do run with dual waveservers, you'll probably need two different
versions of each earthworm module.
Contact: earthworm mailing list