README.md

NLLGrid

Python class for reading and writing NonLinLoc grid files.

(c) 2015-2024 Claudio Satriano, Natalia Poiata, Robert Pickle

Installation

Using Anaconda

If you use Anaconda, the latest release of nllgrid is available via conda-forge.

To install, simply run:

conda install -c conda-forge nllgrid

Using pip and PyPI

The latest release of nllgrid is available on the Python Package Index.

You can install it easily through pip:

pip install nllgrid

From nllgrid GitHub releases

Download the latest release from the releases page, in zip or tar.gz format, then:

pip install nllgrid-X.Y.zip

or

pip install nllgrid-X.Y.tar.gz

Where, X.Y is the version number (e.g., 1.3). You don't need to uncompress the release files yourself.

From nllgrid GitHub repository

If you need a recent feature that is not in the latest release (see the unreleased section in CHANGELOG), you want to use the source code from the nllgrid GitHub repository.

For that, clone the project:

git clone https://github.com/claudiodsf/nllgrid.git

(avoid using the "Download ZIP" option from the green "Code" button, since version number is lost), then install the code from within the nllgrid main directory by running:

pip install .

(use pip install -e . to install in developer mode).

Getting Started

Reading a NLL grid

A NLL grid is composed of two files (.hdr and .buf).

To read a NLL grid, do:

>>> from nllgrid import NLLGrid
>>> grd = NLLGrid('somegrid.hdr')

or, using the .buf filename:

>>> grd = NLLGrid('somegrid.buf')

or even without any extension:

>>> grd = NLLGrid('somegrid')

A grid description can be obtained by:

>>> print(grd)

The grid data array is accessed by grd.array. The grid can be plotted doing:

>>> grd.plot()

Use Python introspection (e.g. dir(grd)) to see all the available methods and attributes.

Creating a NLL grid

Suppose that you have a 3D data array stored into a NumPy array called mydata.

First, create an empty NLL grid object:

>>> from nllgrid import NLLGrid
>>> grd = NLLGrid()

then, add the data array and information on grid sampling and grid origin, e.g.:

>>> grd.array = mydata
>>> grd.dx = 0.5  #km
>>> grd.dy = 0.5  #km
>>> grd.dz = 0.5  #km
>>> grd.x_orig = -10  #km
>>> grd.y_orig = -20. #km
>>> grd.z_orig = -1.  #km

Optionally, add a grid type and/or a geographic transformation:

>>> grd.type = 'VELOCITY'
>>> grd.orig_lat = 40.63
>>> grd.orig_lon = 15.80
>>> grd.proj_name = 'LAMBERT'
>>> grd.first_std_paral = 38.
>>> grd.second_std_paral = 42.
>>> grd.proj_ellipsoid = 'WGS-84'

Finally, give a basename and write to disk:

>>> grd.basename = 'mygrid'
>>> grd.write_hdr_file()
>>> grd.write_buf_file()

This will create the two files mygrid.hdr and mygrid.buf.

If you want to save your grid in double precision (required for instance by NLDiffLoc), change grd.float_type to 'DOUBLE' before saving the grid (default is 'FLOAT'):

>>> grd.float_type = 'DOUBLE'

Note that if you want to use your grid as input for NonLinLoc Grid2Time code, the grid type has to be SLOW_LEN and your grid array has to be transformed into slowness (in s/km) and multiplied by the grid step (in km).