NAME
SYNOPSIS
DESCRIPTION
EXAMPLE
SEE ALSO
- REFERENCES
NOTES
DIAGNOSTICS
RESTRICTIONS
AUTHOR
HISTORY
COPYRIGHT

NAME

Nuvel1A - Relative plate motion tools in Perl

SYNOPSIS

    # be smart
    use strict;
    # import required symbols
    use Nuvel1A qw(:tag func $scalar);
    # your code goes here

DESCRIPTION

Nuvel1A is a Perl module which provides easy access to the NUVEL1A poles of relative plate motion,

No symbols are exported into the caller's namespace, but in stead, all required symbols should be explicitly imported, or referred to by using the package name. For ease of use, the export tags CONSTANTS, VARIABLES, and FUNCTIONS are defined.

DATA

This module already contains the data from the Nuvel1A data set. It is available when you 'use' the module. All poles are contained in a hash which is keyed in a particular way. These keys also pertain to the routines that provide access to the data. All keys are of the form MOV-REF, where MOV is the three alphanumeric character acronym for the moving plate, and REF is the three alphanumeric character acronym of the reference plate. The following acronyms are defined:

AFR - the African plate

ANT - the Antarctican plate

ARA - the Arabian plate

AUS - the Australian plate

CAR - the Caribean plate

COC - the Cocos plate

EUR - the Eurasian plate

IND - the Indian plate

JFU - the Juan de Fuca plate

NAM - the North American plate

NAZ - the Nazca plate

NNR - the no-net-rotation reference frame

PAC - the Pacific plate

PHI - the Phillipine plate

RIV - the Rivera plate

SAM - the South American plate

SCO - the Scotia plate

As an example, AFR-EUR refers to data concerning the motion of Africa with respect to Eurasia.

Currently the uncertainties in the data are not implemented.

CONSTANTS

Nuvel1A defines the following constants. Since use strict; limits the way in which barewords can be used, it is probably best to get used to appending () to the constant identifiers, as is done here.

The identifiers for hash value access will help avoid clashes with elements that are added later. Internally, these start with an underscore, but the actual content might be subject to change or extension.

LON(): longitude
LAT(): latitude
VEL(): angular velocity
POLE(): carthesian rotation vector
TRAILER(): trailing information in data files

VARIABLES

Nuvel1A defines the following variables.

$VERBOSE: The flag that indicates whether verbose messages should be printed. It can be directly modified, but the module also provides the &verbose() subroutine. Verbose mode is on by default. This variable is not exported, and can only be called through a full package reference.

SUBROUTINES

list_poles(): List the available poles. Returns a hash of pole id's and their opposites. Relative motion poles that are not present in the data set can be determined through the equality AAA-CCC = AAA-BBB + BBB-CCC.
get_nuvel1a_pole($id): Get a Nuvel1A rotation pole by id. Returns a vector, or an empty list.
get_nuvel1a_data($id, $key1[, key2, ...]): Retrieve specific information from the Nuvel1A data set. Returns the requested data, or an empty list. See Constants for the available keys. Note that this routine always returns a list, and interpreting the return type in a scalar context will only give you the number of data items. If a key is not defined in the data, one undefined scalar will be added to the returned list. If a key refers to a non-scalar type, a reference to that type is returned.
verbose($flag): Sets verbose mode for this module to the logical value of the first parameter passed. If no argument is given, verbose mode is toggled. Returns true if verbose mode is set, false otherwize. Verbose mode is on by default. This subroutine is not exported, and can only be called through a full package reference.

EXAMPLE

    #!/usr/bin/perl

NOTES

Evangelization bit: to avoid namespace clashes, typing errors and lots of other problems, I strongly recommend using strict.

DIAGNOSTICS

Most subroutines perform some level of error checking (vagueness intentional). Error messages are printed on STDERR if verbose mode is set, and should be self-explanatory. Furthermore, the value a subroutine returns is a good indication whether something went wrong, so check it.

RESTRICTIONS

I've run across a problem with Perl 5.004_02, where trigonometric functions return incorrect results. I can't put my finger on the exact origin, but to be on the safe side, this module requires Perl 5.004_04 or better.

AUTHOR

Joor Loohuis, loohuis@geo.uu.nl

HISTORY

You can determine which version of Nuvel1A you are using, by printing the $Nuvel1A::VERSION variable from within your script.

Version numbering follows a scheme which is rapidly becoming accepted, in which the version minor (the first number after the first period) indicates whether a stable (even version minor) or a development version (odd version minor) is meant. Version majors (first number before first period) of 0 (zero) are all more in development than others.