SCT datatypes

C M pynasonde.vipir.riq.datatypes.sct — SctType and sub-type dataclasses (StationType, TimingType, etc.), plus read_dtype.

Dataclasses modeling VIPIR SCT header-format header block.

pynasonde.vipir.riq.datatypes.sct

SCT (sounder configuration table) datatypes for VIPIR/RIQ.

This module defines the in-memory datatypes used to represent a station/sounder configuration (SCT) including station, timing, frequency, receiver, exciter and monitor sub-structures. It also provides a small helper,: func:read_dtype, used by the binary readers to populate these dataclasses from VIPIR binary files.

The docstrings in this module are written to be machine-readable for documentation generation (mkdocstrings) and to give callers clear contracts for the read/clean helpers.

StationType dataclass

Station metadata and antenna layout.

Holds station-level configuration such as coordinates, antenna counts and arrays of per-antenna properties. The read_station_from_file_pointer method populates these fields from a binary SCT block.

Parameters:

Name	Type	Description	Default
file_id	str	str Name of station settings file.	''
ursi_id	str	str URSI standard station ID code.	''
rx_name	str	str Receiver station name.	''
rx_latitude	np.float64	np.float64 Receive array reference latitude (degrees North).	0.0
rx_longitude	np.float64	np.float64 Receive array reference longitude (degrees East).	0.0
rx_altitude	np.float64	np.float64 Receive array altitude (m above mean sea level).	0.0
rx_count	np.int32	np.int32 Number of defined receive antennas.	0
rx_antenna_type	List[str]	List[str] Text descriptors for each receive antenna.	field(default_factory=lambda : [''] * 16)
rx_position	List[List[float]]	List[List[float]] 3xN list of X,Y,Z positions (East,North,Up) for each Rx (m).	field(default_factory=lambda : [[0.0] * 32 for _ in range(3)])
rx_direction	List[List[float]]	List[List[float]] 3xN list of direction vectors for each Rx (unitless / m).	field(default_factory=lambda : [[0.0] * 32 for _ in range(3)])
rx_height	List[float]	List[float] Height above ground for each Rx (m).	field(default_factory=lambda : [0.0] * 32)
rx_cable_length	List[float]	List[float] Physical length of receive cables (m).	field(default_factory=lambda : [0.0] * 32)
frontend_atten	np.float64	np.float64 Front-end attenuator setting (dB or unitless depending on device).	0.0
tx_name	str	str Transmitter station name.	''
tx_latitude	np.float64	np.float64 Transmit antenna latitude (degrees North).	0.0
tx_longitude	np.float64	np.float64 Transmit antenna longitude (degrees East).	0.0
tx_altitude	np.float64	np.float64 Transmit antenna altitude (m).	0.0
tx_antenna_type	str	str Text descriptor for transmit antenna type.	''
tx_vector	List[float]	List[float] Transmit antenna direction vector (3 elements).	field(default_factory=lambda : [0.0] * 3)
tx_height	np.float64	np.float64 Transmit antenna height above reference ground (m).	0.0
tx_cable_length	np.float64	np.float64 Physical length of transmit cables (m).	0.0
drive_band_count	np.int32	np.int32 Number of antenna drive bands defined.	0
drive_band_bounds	List[List[float]]	List[List[float]] List of start/stop frequency bounds for each drive band (kHz).	field(default_factory=lambda : [[0.0] * 64 for _ in range(2)])
drive_band_atten	List[float]	List[float] Antenna drive attenuation per band (dB).	field(default_factory=lambda : [0.0] * 64)
rf_control	np.int32	np.int32 RF control mode (-1=none, 0=drive/quiet, 1=full, 2=only quiet, 3=only atten).	-1
ref_type	str	str Reference oscillator type description.	''
clock_type	str	str Source of absolute UT timing description.	''
user	str	str Spare/user-defined information field.	''

read_station_from_file_pointer(fp, unicode='latin-1')

Populate station fields by reading binary data from fp.

Parameters:

Name	Type	Description	Default
fp		file-like Open binary file positioned at the start of the Station block.	required
unicode	str	str, optional Encoding used for fixed-width ASCII fields.	'latin-1'

clean()

Trim fixed-size arrays to the configured channel/count sizes.

After reading a binary block many arrays are initialized to a maximum size; this helper trims them to the actual configured channel or band counts for convenience.

TimingType dataclass

Timing configuration for the radar/sounder.

Time values are expressed in microseconds unless stated otherwise. The timing block includes PRI, gate definitions and waveform memory used when decoding PCT payloads.

Parameters:

Name	Type	Description	Default
file_id	str	str Name of the timing settings file.	''
pri	np.float64	np.float64 Pulse Repetition Interval (microseconds).	0.0
pri_count	np.int32	np.int32 Number of PRIs in the measurement.	0
ionogram_count	np.int32	np.int32 Repeat count for ionogram within same data file.	0
holdoff	np.float64	np.float64 Time between GPS 1 pps and start (us).	0.0
range_gate_offset	np.float64	np.float64 True range to gate 0 (us).	0.0
gate_count	np.int32	np.int32 Number of range gates.	0
gate_start	np.float64	np.float64 Start gate placement (us).	0.0
gate_end	np.float64	np.float64 End gate placement (us).	0.0
gate_step	np.float64	np.float64 Range delta between gates (us).	0.0
data_start	np.float64	np.float64 Data range placement start (us).	0.0
data_width	np.float64	np.float64 Data pulse baud width (us).	0.0
data_baud_count	np.int32	np.int32 Number of samples in data baud pattern.	0
data_wave_file	str	str Filename of the data baud pattern.	''
data_baud	List[complex]	List[complex] Complex waveform samples for data baud pattern.	field(default_factory=lambda : [complex(0.0, 0.0)] * 1024)
data_pairs	np.int32	np.int32 Number of IQ pairs in waveform memory.	0
cal_start	np.float64	np.float64 Calibration pulse start (us).	0.0
cal_width	np.float64	np.float64 Calibration pulse width (us).	0.0
cal_baud_count	np.int32	np.int32 Number of samples in cal baud pattern.	0
cal_wave_file	str	str Filename of calibration baud pattern.	''
cal_baud	List[complex]	List[complex] Complex waveform samples for calibration baud pattern.	field(default_factory=lambda : [complex(0.0, 0.0)] * 1024)
cal_pairs	np.int32	np.int32 Number of IQ pairs in calibration waveform memory.	0
user	str	str Spare/user-defined information field.	''

read_timing_from_file_pointer(fp, unicode='latin-1')

Read TimingType fields from a binary file pointer using the timing factory descriptors.

clean()

Trim waveform arrays to their configured lengths.

FrequencyType dataclass

Frequency sweep and tuning table configuration.

Frequencies are expressed in kilohertz unless noted otherwise.

Parameters:

Name	Type	Description	Default
file_id	str	str Frequency settings filename.	''
base_start	np.float64	np.float64 Initial base frequency (kHz).	0.0
base_end	np.float64	np.float64 Final base frequency (kHz).	0.0
base_steps	np.int32	np.int32 Number of base frequency steps.	0
tune_type	np.int32	np.int32 Tuning type flag (1=log, 2=linear, 3=table, 4=Log+Fixed ShuffleMode).	0
base_table	List[float]	List[float] Nominal/base frequency table values.	field(default_factory=lambda : [0.0] * 8192)
linear_step	np.float64	np.float64 Linear frequency step (kHz).	0.0
log_step	np.float64	np.float64 Logarithmic frequency step (percent).	0.0
freq_table_id	str	str Manual tuning table filename.	''
tune_steps	np.int32	np.int32 Pre-ramp repeat count for tuned frequencies.	0
pulse_count	np.int32	np.int32 Length of pulse frequency vector.	0
pulse_pattern	List[int]	List[int] Pulse frequency pattern indices.	field(default_factory=lambda : [0] * 256)
pulse_offset	np.float64	np.float64 Pulse offset (kHz).	0.0
ramp_steps	np.int32	np.int32 Steps per B-mode ramp.	0
ramp_repeats	np.int32	np.int32 Repeat count of B-mode ramps.	0
drive_table	List[float]	List[float] Drive attenuation/silent table for base frequencies.	field(default_factory=lambda : [0.0] * 8192)
user	str	str Spare/user-defined information field.	''

read_frequency_from_file_pointer(fp, unicode='latin-1')

Read FrequencyType fields from a binary file pointer.

clean()

Trim tables to their configured lengths.

RecieverType dataclass

Receiver configuration and processing parameters.

Includes word format, decimation and filter coefficients used by the receiver DSP path.

Parameters:

Name	Type	Description	Default
file_id	str	str Frequency/receiver settings filename.	''
rx_chan	np.int32	np.int32 Number of receiver channels.	0
rx_map	List[int]	List[int] Mapping of receivers to antenna indices.	field(default_factory=lambda : [0] * 16)
word_format	np.int32	np.int32 Word format flag (0=big endian fixed, 1=little endian, 2=floating_point, 3=32-bit little int).	0
cic2_dec	np.int32	np.int32 CIC filter decimation factor (stage 2).	0
cic2_interp	np.int32	np.int32 CIC filter interpolation factor (stage 2).	0
cic2_scale	np.int32	np.int32 CIC filter scale (stage 2).	0
cic5_dec	np.int32	np.int32 CIC filter decimation factor (stage 5).	0
cic5_scale	np.int32	np.int32 CIC filter scale (stage 5).	0
rcf_type	str	str Text descriptor of the receiver FIR filter block.	''
rcf_dec	np.int32	np.int32 Decimation factor for the FIR block.	0
rcf_taps	np.int32	np.int32 Number of taps in the FIR filter.	0
coefficients	List[int]	List[int] Receiver FIR coefficients array.	field(default_factory=lambda : [0] * 160)
analog_delay	np.float64	np.float64 Analog delay of the receiver (us).	0.0
user	str	str Spare/user-defined information field.	''

read_reciever_from_file_pointer(fp, unicode='latin-1')

Read receiver parameters from a binary file pointer.

ExciterType dataclass

Exciter (transmitter) configuration including DAC/DUC filters.

Parameters:

Name	Type	Description	Default
file_id	str	str Exciter/frequency settings filename.	''
cic_scale	np.int32	np.int32 CIC scale factor.	0
cic2_dec	np.int32	np.int32 CIC stage 2 decimation.	0
cic2_interp	np.int32	np.int32 CIC stage 2 interpolation.	0
cic5_interp	np.int32	np.int32 CIC stage 5 interpolation.	0
rcf_type	str	str Text descriptor of the exciter FIR filter block.	''
rcf_taps	np.int32	np.int32 Number of taps in the exciter FIR filter.	0
rcf_taps_phase	np.int32	np.int32 Number of phase taps in exciter FIR.	0
coefficients	List[int]	List[int] Exciter FIR coefficients.	field(default_factory=lambda : [0] * 256)
analog_delay	np.float64	np.float64 Analog delay of exciter/transmitter (us).	0.0
user	str	str Spare/user-defined information field.	''

read_exciter_from_file_pointer(fp, unicode='latin-1')

Read exciter parameters from a binary file pointer.

MonitorType dataclass

Built-in test / monitor values captured at time of sounding.

Parameters:

Name	Type	Description	Default
balun_currents	List[int]	List[int] Balun current readings as read prior to ionogram.	field(default_factory=lambda : [0] * 8)
balun_status	List[int]	List[int] Balun status flags as read prior to ionogram.	field(default_factory=lambda : [0] * 8)
front_end_status	List[int]	List[int] Front-end status words.	field(default_factory=lambda : [0] * 8)
receiver_status	List[int]	List[int] Receiver status indicators.	field(default_factory=lambda : [0] * 8)
exciter_status	List[int]	List[int] Exciter status indicators.	field(default_factory=lambda : [0] * 2)
user	str	str Spare/user-defined information field.	''

read_monitor_from_file_pointer(fp, unicode='latin-1')

Read monitor values from a binary file pointer.

SctType dataclass

Top-level sounder configuration (SCT) structure.

This dataclass aggregates the station, timing, frequency, receiver, exciter and monitor sub-structures that fully describe the configuration necessary to decode and interpret VIPIR binary data.

Parameters:

Name	Type	Description	Default
magic	np.int32	np.int32 Format magic number for SCT records.	1363759616
sounding_table_size	np.int32	np.int32 Bytes in the sounder configuration structure.	0
pulse_table_size	np.int32	np.int32 Bytes in the pulse configuration structure.	0
raw_data_size	np.int32	np.int32 Bytes in the raw data block for one PRI.	0
struct_version	np.float64	np.float64 Format version number.	1.2
start_year	np.int32	np.int32 Start year of the measurement (UTC).	1970
start_daynumber	np.int32	np.int32 Day number within the year.	1
start_month	np.int32	np.int32 Start month.	1
start_day	np.int32	np.int32 Start day of the month.	1
start_hour	np.int32	np.int32 Start hour (UTC).	0
start_minute	np.int32	np.int32 Start minute (UTC).	0
start_second	np.int32	np.int32 Start second (UTC).	0
start_epoch	np.int32	np.int32 Epoch time of the measurement start.	0
readme	str	str Operator comment on this measurement.	''
decimation_method	np.int32	np.int32 Decimation/processing method flag.	0
decimation_threshold	np.float64	np.float64 Threshold value for processing method.	0.0
user	str	str Spare/user-defined information field.	''
station	StationType	StationType Station information sub-structure.	field(default_factory=StationType)
timing	TimingType	TimingType Radar timing sub-structure.	field(default_factory=TimingType)
frequency	FrequencyType	FrequencyType Frequency sweep sub-structure.	field(default_factory=FrequencyType)
receiver	RecieverType	RecieverType Receiver settings sub-structure.	field(default_factory=RecieverType)
exciter	ExciterType	ExciterType Exciter settings sub-structure.	field(default_factory=ExciterType)
monitor	MonitorType	MonitorType Built-in test/monitor sub-structure.	field(default_factory=MonitorType)

read_sct_from_file_pointer(fp, unicode='latin-1')

Populate this SCT by reading binary fields from fp.

The logic mirrors the default factory descriptors and decodes fixed-width ASCII fields as needed.

fix_SCT_strings()

Trim null padding from all fixed-width string fields.

This is a convenience to make textual fields nicer for display and downstream processing after binary reads.

dump_sct(to_file=None)

Return or write a human-readable SCT summary.

Parameters:

Name	Type	Description	Default
to_file	str	str or None, optional If provided, write the summary to the given filename. When None the summary is logged at INFO level.	None

read_dtype(dtype, obj, fp, unicode='latin-1')

Read a typed field from a binary file according to dtype.

The dtype descriptor is a small tuple describing the target attribute name, numpy dtype or special 'S4' string handling and a shape/count specification. This helper centralizes the repetitive logic used by the SCT readers.

Parameters:

Name	Type	Description	Default
dtype		tuple Descriptor tuple (name, type, shape_or_count) coming from the factory descriptions.	required
obj		object Target object whose attribute will receive the parsed value.	required
fp		file-like Open binary file-like object.	required
unicode	str	str, optional Encoding used when decoding fixed-width ASCII fields (default 'latin-1').	'latin-1'

Returns:

Type	Description
	The input obj with the requested attribute set.