QDP File Operations (qdp)¶

Module: utils_qdp

Overview¶

Provides utilities for working with QDP (Quick Data Plot) files, a simple ASCII format used for plotting data in SPEX and other astronomical software.

Key Features¶

Simple ASCII-based data format
Easy to read and write
Human-readable format
Suitable for quick data exchange
Integration with SPEX plotting system

Types¶

qdp_set

Individual data set structure:

Component	Type	Description
`n`	integer	Number of rows in set
`x, x1, x2`	real(dp), allocatable	X-axis data arrays
`y, y1, y2`	real(dp), allocatable	Y-axis data arrays
`z`	real(dp), allocatable	Z-axis data array
`b`	real(dp), allocatable	Additional data array

qdp

Main QDP container:

Component	Type	Description
`nset`	integer	Number of data sets
`set`	type(qdp_set), allocatable	Array of data sets
`type`	character(5)	QDP type identifier

API Reference¶

Methods¶

init

qdp_handler%init(nset, type)

Initialize QDP object

Parameters:

nset – Number of data sets (integer, in)
type – QDP type (character(5), in)

Returns:

None

Allocates memory for specified number of data sets.

init_col

qdp_handler%init_col(iset, n, col)

Initialize data set column

Parameters:

iset – Data set index (integer, in)
n – Number of data points (integer, in)
col – Column identifier (character(1), in)

Returns:

None

Allocates memory for specified column in data set.

setcol

qdp_handler%setcol(iset, n, col, a, a1, a2)

Set data set column values

Parameters:

iset – Data set index (integer, in)
n – Number of data points (integer, in)
col – Column identifier (character(1), in)
a – Main data array (real(dp)(n), in)
a1 – Optional error array (real(dp)(n), in, optional)
a2 – Optional second error array (real(dp)(n), in, optional)

Returns:

None

Sets values for specified column in data set.

read

qdp_handler%read(filename, type, status)

Read QDP data from file

Parameters:

filename – QDP filename (character(*), in)
type – QDP type (character(5), in)
status – Error status (integer, inout)

Returns:

None

Loads QDP data from file into object.

write

qdp_handler%write(filename, type, status)

Write QDP data to file

Parameters:

filename – QDP filename (character(*), in)
type – QDP type (character(5), in)
status – Error status (integer, inout)

Returns:

None

Saves QDP data from object to file.

final

qdp_handler%final()

Clean up QDP object

Returns:: None

Deallocates all memory used by QDP object.

Usage Examples¶

Basic QDP Initialization

use utils_qdp
type(qdp) :: qdp_handler
integer :: status

! Initialize QDP object for 2 data sets
call qdp_handler%init(2, 'SPEX', status)

if (status == 0) then
   write(*,*) 'QDP object initialized for', qdp_handler%nset, 'data sets'
endif

Setting Up Data Columns

use utils_qdp
use utils_cspex, only: dp
type(qdp) :: qdp_handler
integer :: status, n_points
real(dp), dimension(100) :: energy, flux, error

! Initialize QDP object
call qdp_handler%init(1, 'SPEX', status)

if (status == 0) then
   ! Set up data set 1 with 100 points
   n_points = 100
   call qdp_handler%init_col(1, n_points, 'x', status)
   call qdp_handler%init_col(1, n_points, 'y', status)

   ! Fill with sample data
   energy = [(0.1_dp + (i-1)*0.01_dp, i=1,100)]
   flux = exp(-energy) * sin(energy*10.0_dp)
   error = flux * 0.1_dp

   ! Set X and Y columns
   call qdp_handler%setcol(1, n_points, 'x', energy, status)
   call qdp_handler%setcol(1, n_points, 'y', flux, error, status)

   write(*,*) 'Data columns set successfully'
endif

Reading QDP File

use utils_qdp
type(qdp) :: qdp_handler
integer :: status

! Read QDP data from file
call qdp_handler%read('spectrum.qdp', 'SPEX', status)

if (status == 0) then
   write(*,*) 'QDP file loaded successfully'
   write(*,*) 'Number of data sets:', qdp_handler%nset
   write(*,*) 'Data set 1 points:', qdp_handler%set(1)%n
endif

Writing QDP File

use utils_qdp
use utils_cspex, only: dp
type(qdp) :: qdp_handler
integer :: status, i, n_points
real(dp), dimension(50) :: x, y

! Initialize and set up data
call qdp_handler%init(1, 'SPEX', status)
n_points = 50

! Create sample data
do i = 1, n_points
   x(i) = 0.1_dp + (i-1)*0.02_dp
   y(i) = exp(-x(i)) * cos(x(i)*5.0_dp)
enddo

! Set up columns and data
call qdp_handler%init_col(1, n_points, 'x', status)
call qdp_handler%init_col(1, n_points, 'y', status)
call qdp_handler%setcol(1, n_points, 'x', x, status)
call qdp_handler%setcol(1, n_points, 'y', y, status)

! Write to file
call qdp_handler%write('output.qdp', 'SPEX', status)

if (status == 0) then
   write(*,*) 'QDP file written successfully'
endif

Multiple Data Sets

use utils_qdp
use utils_cspex, only: dp
type(qdp) :: qdp_handler
integer :: status, i, n_points
real(dp), dimension(50) :: x, y1, y2

! Initialize for 2 data sets
call qdp_handler%init(2, 'SPEX', status)
n_points = 50

! Create sample data
do i = 1, n_points
   x(i) = 0.1_dp + (i-1)*0.02_dp
   y1(i) = exp(-x(i))
   y2(i) = x(i)**2
enddo

! Set up data set 1
call qdp_handler%init_col(1, n_points, 'x', status)
call qdp_handler%init_col(1, n_points, 'y', status)
call qdp_handler%setcol(1, n_points, 'x', x, status)
call qdp_handler%setcol(1, n_points, 'y', y1, status)

! Set up data set 2
call qdp_handler%init_col(2, n_points, 'x', status)
call qdp_handler%init_col(2, n_points, 'y', status)
call qdp_handler%setcol(2, n_points, 'x', x, status)
call qdp_handler%setcol(2, n_points, 'y', y2, status)

! Write to file
call qdp_handler%write('multi_dataset.qdp', 'SPEX', status)

if (status == 0) then
   write(*,*) 'Multi-dataset QDP file created'
endif

Cleanup Example

use utils_qdp
type(qdp) :: qdp_handler
integer :: status

! Initialize and use QDP object
call qdp_handler%init(1, 'SPEX', status)
! ... work with QDP data ...

! Clean up when done
call qdp_handler%final()

write(*,*) 'QDP object cleaned up'

Notes¶

QDP Data Structure

qdp object contains multiple qdp_set objects
Each qdp_set represents one data series
Columns: x, y, z, b with optional error arrays
Type identifier specifies QDP format version

Column Identifiers

Identifier	Description	Typical Usage
`'x'`	X-axis data	Energy, wavelength, time
`'y'`	Y-axis data	Flux, counts, intensity
`'z'`	Z-axis data	Secondary values
`'b'`	Background	Background data

Error Handling

status parameter for error reporting
status = 0 indicates success
Non-zero values indicate specific errors
Check status after each operation

Memory Management

init() allocates memory
final() deallocates memory
Always call final() when done
Prevents memory leaks

Performance

Fast data access
Efficient memory usage
Suitable for medium-sized datasets
ASCII format limits performance

Best Practices

Initialize before use with init()
Set up columns before adding data
Use appropriate column types for data
Clean up with final() when done
Check status after each operation

Common QDP Types

Type	Description	Usage
`'SPEX'`	SPEX QDP format	Standard SPEX data
`'QDP'`	Generic QDP format	Compatible with other tools
`'PLOT'`	Plotting format	Simple XY plots

SPEX 4.0 documentation

QDP File Operations (qdp)¶

Overview¶

Key Features¶

Types¶

API Reference¶

Methods¶

Usage Examples¶

Notes¶

See Also¶