DarnDmap

Elixir bindings for reading SuperDARN DMAP data using the Rust darn-dmap library.

Status: Early 0.1.x release. The public API may evolve as the library matures.

Features

• Read SuperDARN DMAP files from disk or memory
• Automatically reads .bz2-compressed DMAP files
• Supports FITACF, RAWACF, IQDAT, GRID, MAP, SND, and generic DMAP records
• Automatically recognizes record variants (e.g. FITEX, FITACF, FITACF3) and decodes them into a common representation
• Supports indexed reads for efficient random access
• Decode vectors as Elixir lists, Nx.Tensor values, or raw tagged fields
• Native Rust implementation via Rustler

Requirements

darn_dmap includes a Rustler NIF.

Building the library from source requires a working Rust toolchain. Once compiled, applications using darn_dmap do not require Rust at runtime.

Installation

Add darn_dmap to your dependencies:

def deps do
  [
    {:darn_dmap, "~> 0.1.0"}
  ]
end

Then fetch dependencies:

mix deps.get

Usage

The record type (:fitacf, :grid, etc.) identifies the logical data product rather than a specific on-disk version. For example, :fitacf can be used to read FITEX, FITACF, FITACF2, or FITACF3 files.

Read all records from a compressed FITACF3 file:

{:ok, records} =
  DarnDmap.read(
    "/path/to/20150505.2201.bks.fitacf3.bz2",
    :fitacf
  )

Read all records from a FITACF file:

{:ok, records} =
  DarnDmap.read(
    "/path/to/20150505.2201.bks.fitacf",
    :fitacf
  )

The explicit path source form is also supported:

{:ok, records} =
  DarnDmap.read(
    {:path, "/path/to/20150505.2201.bks.fitacf"},
    :fitacf
  )

Read records directly from bytes:

bytes = File.read!("/path/to/20150505.2201.bks.fitacf")

{:ok, records} =
  DarnDmap.read(
    {:bytes, bytes},
    :fitacf
  )

Use the raising variant when failure should raise:

records =
  DarnDmap.read!(
    "/path/to/20150505.2201.bks.fitacf",
    :fitacf
  )

Read selected records by zero-based index:

{:ok, records} =
  DarnDmap.read(
    "/path/to/20150505.2201.bks.fitacf",
    :fitacf,
    indices: [0, 10, 25]
  )

Decode vector fields as Nx.Tensor values:

{:ok, records} =
  DarnDmap.read(
    "/path/to/20150505.2201.bks.fitacf",
    :fitacf,
    decode_mode: :nx
  )

Return the raw tagged DMAP representation:

{:ok, records} =
  DarnDmap.read(
    "/path/to/20150505.2201.bks.fitacf",
    :fitacf,
    decode_mode: :raw
  )

Perform a lax read and report the first unreadable byte position:

{:ok, {records, bad_byte: byte_offset}} =
  DarnDmap.read(
    "/path/to/20150505.2201.bks.fitacf",
    :fitacf,
    lax?: true
  )

When no unreadable byte is encountered, a lax read returns the records directly:

{:ok, records} =
  DarnDmap.read(
    "/path/to/20150505.2201.bks.fitacf",
    :fitacf,
    lax?: true
  )

Supported record types are:

:iqdat
:rawacf
:fitacf
:grid
:map
:snd
:dmap

License

Licensed under the GNU Lesser General Public License v3.0 or later.

See the LICENSE file for details.