setigen.voltage API reference

setigen.voltage.backend module

class setigen.voltage.backend.RawVoltageBackend(antenna_source: Any, digitizer: Any, filterbank: Any, requantizer: Any, start_chan: int = 0, num_chans: int = 64, block_size: int = 134217728, blocks_per_file: int = 128, num_subblocks: int = 32, max_working_set_bytes: int = 536870912)[source]

Bases: object

Central class that wraps around antenna sources and backend elements to facilitate the creation of GUPPI RAW voltage files from synthetic real voltages.

__init__(antenna_source: Any, digitizer: Any, filterbank: Any, requantizer: Any, start_chan: int = 0, num_chans: int = 64, block_size: int = 134217728, blocks_per_file: int = 128, num_subblocks: int = 32, max_working_set_bytes: int = 536870912) → None[source]

Initialize a raw-voltage recording backend.

Parameters:

antenna_source – Antenna or MultiAntennaArray providing voltage samples.
digitizer – Digitizer template or per-antenna/per-polarization digitizer matrix.
filterbank – PFB template or per-antenna/per-polarization filterbank matrix.
requantizer – Requantizer template or per-antenna/per-polarization requantizer matrix.
start_chan – Index of the first coarse channel to record.
num_chans – Number of coarse channels to record.
block_size – Output RAW block size in bytes.
blocks_per_file – Number of RAW blocks to place in each file.
num_subblocks – Requested number of computational subblocks per RAW block.
max_working_set_bytes – Soft cap for transient per-subblock working set. The backend may increase the effective subblock count to stay within this budget.

Raises:

ValueError – If the antenna source is invalid.
TypeError – If a backend element has an unsupported type.

classmethod from_data(input_file_stem: str, antenna_source: Any, digitizer: Any = None, filterbank: Any = None, start_chan: int = 0, num_subblocks: int = 32, max_working_set_bytes: int = 536870912) → RawVoltageBackend[source]

Initialize a backend that injects signals into existing RAW input.

Parameters:

input_file_stem – Path stem to the input RAW data.
antenna_source – Antenna or MultiAntennaArray providing injected voltage samples.
digitizer – Optional digitizer template or per-stream matrix.
filterbank – Optional PFB template or per-stream matrix.
start_chan – Index of the first coarse channel to record.
num_subblocks – Requested number of computational subblocks per RAW block.
max_working_set_bytes – Soft cap for transient per-subblock working set.

Returns:

Initialized backend configured from the input RAW metadata.

collect_data_block(digitize: bool = True, requantize: bool = True, verbose: bool = True) → ndarray[source]

Collect one packed RAW data block from the antenna source.

Parameters:

digitize – Whether to quantize input voltages before the PFB.
requantize – Whether to quantize complex post-PFB voltages.
verbose – Whether to emit progress output.

Returns:

Packed RAW buffer with shape (num_chans * num_antennas, block_size / (num_chans * num_antennas)).

Raises:

ValueError – If input RAW mixing is requested without requantization.

get_num_blocks(obs_length: float) → int[source]

Calculate the number of RAW blocks implied by an observation length.

Parameters:: obs_length – Observation length in seconds.
Returns:: Number of full RAW blocks required.

record(output_file_stem: str, obs_length: float | None = None, num_blocks: int | None = None, length_mode: str = 'obs_length', header_dict: dict[str, Any] | None = None, digitize: bool = True, load_template: bool = True, verbose: bool = True) → None[source]

Record one observation as one or more GUPPI RAW files.

Parameters:

output_file_stem – Path stem for the output RAW files.
obs_length – Observation length in seconds when using length_mode=”obs_length”.
num_blocks – Number of RAW blocks when using length_mode=”num_blocks”.
length_mode – Strategy for interpreting the supplied observation length.
header_dict – Optional RAW header overrides and additions.
digitize – Whether to quantize input voltages before the PFB.
load_template – Whether to merge the built-in RAW header template.
verbose – Whether to emit progress output.

to_spectrogram(spec: Any, obs_length: float | None = None, num_blocks: int | None = None, length_mode: str = 'obs_length', digitize: bool = True, requantize: bool = True, verbose: bool = True) → Any[source]

Generate a reduced spectrogram directly from this backend.

This follows the same voltage path as record() through sample generation, digitization, coarse PFB channelization, and requantization, then reduces directly to a spectrogram without packing, writing, reading, or decoding an intermediate RAW file.

Parameters:

spec – setigen.voltage.VoltageSpectrogramSpec instance.
obs_length – Observation length in seconds when using length_mode="obs_length".
num_blocks – Number of backend blocks when using length_mode="num_blocks".
length_mode – Strategy for interpreting the supplied observation length.
digitize – Whether to quantize input voltages before the PFB.
requantize – Whether to quantize complex post-PFB voltages.
verbose – Whether to emit progress output.

Returns:

setigen.voltage.VoltageSpectrogramResult.

setigen.voltage.backend.get_block_size(num_antennas: int = 1, tchans_per_block: int = 128, num_bits: int = 8, num_pols: int = 2, num_branches: int = 1024, num_chans: int = 64, fftlength: int = 1024, int_factor: int = 4) → int[source]

Calculate a RAW block size from the desired reduced-product dimensions.

Parameters:

num_antennas – Number of antennas.
tchans_per_block – Number of output time bins per RAW block after fine channelization.
num_bits – Requantized bit depth, usually 8 or 4.
num_pols – Number of recorded polarizations.
num_branches – Number of PFB branches.
num_chans – Number of recorded coarse channels.
fftlength – Fine-channel FFT length.
int_factor – Fine-channel time integration factor.

Returns:

RAW block size in bytes.

setigen.voltage.backend.get_total_obs_num_samples(obs_length: float | None = None, num_blocks: int | None = None, length_mode: str = 'obs_length', num_antennas: int = 1, sample_rate: float = 3000000000.0, block_size: int = 134217728, num_bits: int = 8, num_pols: int = 2, num_branches: int = 1024, num_chans: int = 64) → int[source]

Estimate the required real-voltage sample count without constructing a backend.

Parameters:

obs_length – Observation length in seconds when using length_mode=”obs_length”.
num_blocks – Number of RAW blocks when using length_mode=”num_blocks”.
length_mode – Strategy for interpreting the supplied observation length.
num_antennas – Number of antennas.
sample_rate – Time-domain sample rate in Hz.
block_size – RAW block size in bytes.
num_bits – Requantized bit depth.
num_pols – Number of recorded polarizations.
num_branches – Number of PFB branches.
num_chans – Number of recorded coarse channels.

Returns:

Estimated count of real voltage samples required.

setigen.voltage.antenna module

Bases: object

Model a radio antenna with one or two polarization streams.

Initialize an antenna and its polarization data streams.

Parameters:

sample_rate – Real-voltage sample rate.
fch1 – Frequency of the first coarse channel.
ascending – Whether the frequency axis is ascending.
num_pols – Number of polarizations, either one or two.
t_start – Start time in seconds.
seed – Random seed or generator.
**kwargs – Reserved keyword arguments.

set_time(t: float) → None[source]

Set the antenna start time for the next sample request.

Parameters:: t – New start time in seconds.

add_time(t: float) → None[source]

Advance the antenna start time.

Parameters:: t – Time increment in seconds.

reset_start() → None[source]: Reset the observation-start state for the antenna.

get_samples(num_samples: int) → ndarray[source]

Retrieve voltage samples from each polarization.

Parameters:: num_samples – Number of samples to retrieve.
Returns:: Voltage samples of shape (1, num_pols, num_samples).

Bases: object

Model an antenna array with per-antenna delays and shared background noise.

Initialize a multi-antenna array.

Parameters:

num_antennas – Number of antennas in the array.
sample_rate – Real-voltage sample rate.
fch1 – Frequency of the first coarse channel.
ascending – Whether the frequency axis is ascending.
num_pols – Number of polarizations, either one or two.
delays – Optional per-antenna integer-sample delays.
t_start – Start time in seconds.
seed – Random seed or generator.
**kwargs – Reserved keyword arguments.

set_time(t: float) → None[source]

Set the array start time for the next sample request.

Parameters:: t – New start time in seconds.

add_time(t: float) → None[source]

Advance the array start time.

Parameters:: t – Time increment in seconds.

reset_start() → None[source]: Reset the observation-start state for the array.

get_samples(num_samples: int) → ndarray[source]

Retrieve voltage samples from each antenna and polarization.

Parameters:: num_samples – Number of samples to retrieve.
Returns:: Voltage samples of shape (num_antennas, num_pols, num_samples).
Raises:: ValueError – If num_samples does not exceed the maximum antenna delay.

setigen.voltage.data_stream module

Bases: object

Model a single-polarization real-voltage data stream.

Initialize a real-voltage data stream.

Parameters:

sample_rate – Real-voltage sample rate.
fch1 – Frequency of the first coarse channel.
ascending – Whether the frequency axis is ascending.
t_start – Start time in seconds.
seed – Random seed or generator.

rng: Random number generator

set_time(t: float) → None[source]

Set the start time for the next sample request.

Parameters:: t – New start time in seconds.

add_time(t: float) → None[source]

Advance the start time for the next sample request.

Parameters:: t – Time increment in seconds.

update_noise(stats_calc_num_samples: int = 10000) → None[source]

Estimate and update the stream noise standard deviation.

Parameters:: stats_calc_num_samples – Maximum number of samples to use.

get_total_noise_std() → float[source]

Return the combined intrinsic and background noise standard deviation.

Returns:: Total noise standard deviation including background noise.

add_noise(v_mean: float, v_std: float) → None[source]

Add a Gaussian noise source to the stream.

Parameters:

v_mean – Noise mean.
v_std – Noise standard deviation.

add_constant_signal(f_start: float, drift_rate: float, level: float, phase: float = 0) → None[source]

Add a drifting cosine signal to the stream.

Parameters:

f_start – Starting signal frequency.
drift_rate – Drift rate in Hz/s.
level – Signal amplitude.
phase – Signal phase in radians.

add_signal(signal_func: Callable[[ndarray], ndarray]) → None[source]

Add a custom signal source function to the stream.

Parameters:: signal_func – Callable that maps time samples to voltages.

get_samples(num_samples: int) → ndarray[source]

Generate voltage samples from the configured sources.

Parameters:: num_samples – Number of samples to generate.
Returns:: Array of generated voltage samples.

class setigen.voltage.data_stream.BackgroundDataStream(sample_rate: float | Quantity = <Quantity 3. GHz>, fch1: float | Quantity = <Quantity 0. GHz>, ascending: bool = True, t_start: float = 0, seed: None | int | Generator | BitGenerator | SeedSequence = None, antenna_streams: list[~setigen.voltage.data_stream.DataStream] | tuple[~setigen.voltage.data_stream.DataStream, ...] | None=None)[source]

Bases: DataStream

Data stream used for coherent background noise in antenna arrays.

Initialize a background data stream.

Parameters:

sample_rate – Real-voltage sample rate.
fch1 – Frequency of the first coarse channel.
ascending – Whether the frequency axis is ascending.
t_start – Start time in seconds.
seed – Random seed or generator.
antenna_streams – Antenna streams that share this background noise.

update_noise(stats_calc_num_samples: int = 10000) → None[source]

Estimate background noise and propagate it to antenna streams.

Parameters:: stats_calc_num_samples – Maximum number of samples to use.

add_noise(v_mean: float, v_std: float) → None[source]

Add Gaussian background noise and propagate its variance.

Parameters:

v_mean – Noise mean.
v_std – Noise standard deviation.

setigen.voltage.data_stream.estimate_stats(voltages: ndarray, stats_calc_num_samples: int = 10000) → tuple[float, float][source]

Estimate the mean and standard deviation of a voltage sequence.

Parameters:

voltages – Voltage array.
stats_calc_num_samples – Maximum number of samples to use.

Returns:

Estimated mean and standard deviation.

setigen.voltage.polyphase_filterbank module

class setigen.voltage.polyphase_filterbank.PolyphaseFilterbank(num_taps: int = 8, num_branches: int = 1024, window_fn: str = 'hamming')[source]

Bases: object

Implement a polyphase filterbank for coarse channelization.

__init__(num_taps: int = 8, num_branches: int = 1024, window_fn: str = 'hamming') → None[source]

Initialize a polyphase filterbank.

Parameters:

num_taps – Number of PFB taps.
num_branches – Number of PFB branches.
window_fn – Windowing function used for the PFB.

estimate_channelized_stds(factor: int = 10000, seed: None | int | Generator | BitGenerator | SeedSequence = None) → ndarray[source]

Estimate post-channelization real and imaginary standard deviations.

Parameters:

factor – Multiplier for num_branches used in the estimate.
seed – Random seed or generator.

Returns:

Estimated real and imaginary standard deviations.

get_response(fftlength: int = 512) → ndarray[source]

Return the half-coarse-channel PFB frequency response.

Parameters:: fftlength – Fine-channel FFT length used for the response estimate.
Returns:: Half-coarse-channel frequency response.
Raises:: ValueError – If fftlength is not a multiple of num_taps.

tile_response(num_chans: int, fftlength: int = 512) → ndarray[source]

Construct a tiled multi-channel PFB frequency response.

Parameters:

num_chans – Number of coarse channels to tile.
fftlength – Fine-channel FFT length used for the response estimate.

Returns:

Tiled coarse-channel response.

channelize(x: ndarray, cache: bool = True, start_chan: int = 0, num_chans: int | None = None, method: Literal['auto', 'full', 'selected'] = 'auto') → ndarray[source]

Channelize input voltages with the PFB and a normalized FFT.

Parameters:

x – Input voltage array.
cache – Whether to retain overlap samples between calls.
start_chan – First coarse channel to return.
num_chans – Number of coarse channels to return. Defaults to all positive-frequency channels from start_chan onward.
method – Coarse-channel transform method. "full" computes the full FFT then slices, "selected" computes only requested DFT bins, and "auto" selects the exact cheaper path for small channel selections.

Returns:

Post-FFT complex voltages.

Raises:

ValueError – If the selected channel range or method is invalid.

setigen.voltage.polyphase_filterbank.pfb_frontend_reference(x: ndarray, pfb_window: ndarray, num_taps: int, num_branches: int) → ndarray[source]

Apply the polyphase frontend windowing operation.

Parameters:

x – Input voltage array.
pfb_window – PFB window coefficients.
num_taps – Number of PFB taps.
num_branches – Number of PFB branches.

Returns:

Voltage array after PFB weighting.

setigen.voltage.polyphase_filterbank.pfb_frontend(x: ndarray, pfb_window: ndarray, num_taps: int, num_branches: int, method: Literal['auto', 'reference', 'vectorized'] = 'auto', max_working_set_bytes: int | None = 536870912) → ndarray[source]

Apply the vectorized polyphase frontend windowing operation.

Parameters:

x – Input voltage array.
pfb_window – PFB window coefficients.
num_taps – Number of PFB taps.
num_branches – Number of PFB branches.
method – Frontend implementation method. "reference" uses the original row loop, "vectorized" loops over taps, and "auto" uses the conservative reference loop. Users can request "vectorized" explicitly for workloads where it is faster.
max_working_set_bytes – Optional memory budget for the auto selector.

Returns:

Voltage array after PFB weighting.

Raises:

ValueError – If the frontend method is unsupported.

setigen.voltage.polyphase_filterbank.get_pfb_window(num_taps: int, num_branches: int, window_fn: str = 'hamming') → ndarray[source]

Return PFB window coefficients.

Parameters:

num_taps – Number of PFB taps.
num_branches – Number of PFB branches.
window_fn – Windowing function used for the PFB.

Returns:

PFB window coefficients.

setigen.voltage.polyphase_filterbank.get_pfb_voltages(x: ndarray, num_taps: int, num_branches: int, window_fn: str = 'hamming') → ndarray[source]

Produce coarse-channel complex voltages from real-voltage input.

Parameters:

x – Input voltage array.
num_taps – Number of PFB taps.
num_branches – Number of PFB branches.
window_fn – Windowing function used for the PFB.

Returns:

Post-FFT complex voltages.

setigen.voltage.quantization module

class setigen.voltage.quantization.RealQuantizer(target_mean: float = 0, target_fwhm: float = 32, num_bits: int = 8, stats_calc_period: int = 1, stats_calc_num_samples: int = 10000)[source]

Bases: object

Quantize real-valued voltages to integer levels.

__init__(target_mean: float = 0, target_fwhm: float = 32, num_bits: int = 8, stats_calc_period: int = 1, stats_calc_num_samples: int = 10000) → None[source]

Initialize a real-valued quantizer.

Parameters:

target_mean – Target mean of the quantized values.
target_fwhm – Target full width at half maximum.
num_bits – Number of quantization bits.
stats_calc_period – Period for recomputing input statistics.
stats_calc_num_samples – Maximum samples used for statistic estimates.

quantize(voltages: ndarray, custom_std: float | None = None) → ndarray[source]

Quantize real input voltages.

Parameters:

voltages – Array of real voltages.
custom_std – Optional standard deviation to use for scaling.

Returns:

Array of quantized voltages.

digitize(voltages: ndarray, custom_std: float | None = None) → ndarray[source]

Alias for quantize().

Parameters:

voltages – Array of real voltages.
custom_std – Optional standard deviation to use for scaling.

Returns:

Array of quantized voltages.

class setigen.voltage.quantization.ComplexQuantizer(target_mean: float = 0, target_fwhm: float = 32, num_bits: int = 8, stats_calc_period: int = 1, stats_calc_num_samples: int = 10000)[source]

Bases: object

Quantize complex voltages using paired real-valued quantizers.

__init__(target_mean: float = 0, target_fwhm: float = 32, num_bits: int = 8, stats_calc_period: int = 1, stats_calc_num_samples: int = 10000) → None[source]

Initialize a complex-valued quantizer.

Parameters:

target_mean – Target mean of the quantized values.
target_fwhm – Target full width at half maximum.
num_bits – Number of quantization bits.
stats_calc_period – Period for recomputing input statistics.
stats_calc_num_samples – Maximum samples used for statistic estimates.

Quantize complex input voltages.

Parameters:

voltages – Array of complex voltages.
custom_stds – Optional scalar or length-two sequence of standard deviations for the real and imaginary parts.

Returns:

Array of complex quantized voltages.

Raises:

ValueError – If custom_stds is not scalar or length two.

setigen.voltage.quantization.quantize_real(x: ndarray, target_mean: float = 0, target_std: float = np.float64(13.589148804608305), num_bits: int = 8, data_mean: float | None = None, data_std: float | None = None, stats_calc_num_samples: int = 10000) → ndarray[source]

Quantize real voltages to integer levels.

Parameters:

x – Array of voltages.
target_mean – Target mean for quantized voltages.
target_std – Target standard deviation for quantized voltages.
num_bits – Number of quantization bits.
data_mean – Optional precomputed input mean.
data_std – Optional precomputed input standard deviation.
stats_calc_num_samples – Maximum samples used for statistic estimates.

Returns:

Array of quantized voltages.

setigen.voltage.quantization.quantize_complex(x: ndarray, target_mean: float = 0, target_std: float = np.float64(13.589148804608305), num_bits: int = 8, stats_calc_num_samples: int = 10000) → ndarray[source]

Quantize complex voltages to integer levels.

Parameters:

x – Array of complex voltages.
target_mean – Target mean for quantized voltages.
target_std – Target standard deviation for quantized voltages.
num_bits – Number of quantization bits.
stats_calc_num_samples – Maximum samples used for statistic estimates.

Returns:

Array of complex quantized voltages.

setigen.voltage.level_utils module

setigen.voltage.level_utils.get_unit_drift_rate(raw_voltage_backend: RawVoltageBackend, fftlength: int, int_factor: int = 1) → float[source]

Get the drift rate corresponding to a one-pixel shift.

Parameters:

raw_voltage_backend – Backend object used to infer observation parameters.
fftlength – Fine-channel FFT length.
int_factor – Time integration factor used after fine channelization.

Returns:

Drift rate in Hz/s corresponding to a 1x1 pixel shift.

setigen.voltage.level_utils.get_level(snr: float, raw_voltage_backend: RawVoltageBackend, fftlength: int, obs_length: float | None = None, num_blocks: int | None = None, length_mode: str = 'obs_length') → float[source]

Calculate the cosine voltage level needed to reach a target SNR.

This calibration assumes unit input noise variance, a single-polarization signal, no drift, and a tone centered exactly on a fine FFT bin.

Parameters:

snr – Desired signal-to-noise ratio.
raw_voltage_backend – Backend object used to infer observation parameters.
fftlength – Fine-channel FFT length.
obs_length – Observation length in seconds when using length_mode="obs_length".
num_blocks – Number of RAW blocks when using length_mode="num_blocks".
length_mode – Observation-length interpretation mode.

Returns:

Signal amplitude for a real cosine voltage injection.

Raises:

ValueError – If the requested observation length and FFT length produce no complete fine-channelized spectra.

setigen.voltage.level_utils.get_leakage_factor(f_start: float, raw_voltage_backend: RawVoltageBackend, fftlength: int) → float[source]

Get the fine-channel spectral-leakage correction factor.

Parameters:

f_start – Signal frequency in Hz.
raw_voltage_backend – Backend object used to infer observation parameters.
fftlength – Fine-channel FFT length.

Returns:

Multiplicative correction factor for signal amplitude.

setigen.voltage.waterfall module

setigen.voltage.waterfall.get_pfb_waterfall(pfb_voltages_x: ndarray, pfb_voltages_y: ndarray | None = None, fftlength: int = 256, int_factor: int = 1) → ndarray[source]

Fine-channelize already-channelized complex voltages.

Parameters:

pfb_voltages_x – Complex voltages for the first polarization with shape (time_samples, num_chans).
pfb_voltages_y – Optional complex voltages for the second polarization with the same shape as pfb_voltages_x.
fftlength – Fine-channel FFT length.
int_factor – Time integration factor after fine channelization.

Returns:

Integrated power waterfall with shape (tchans, fchans).

setigen.voltage.waterfall.get_waterfall_from_raw(raw_filename: str, block_size: int, num_chans: int, int_factor: int = 1, fftlength: int = 256) → ndarray[source]

Reduce the first RAW block into a Stokes-I waterfall array.

This helper is intentionally lightweight and primarily intended for tests and quick inspection of a single RAW block.

Parameters:

raw_filename – GUPPI RAW file path or RAW stem.
block_size – Expected number of bytes in a RAW data block.
num_chans – Expected number of coarse channels in the RAW file.
int_factor – Time integration factor after fine channelization.
fftlength – Fine-channel FFT length.

Returns:

Stokes-I waterfall for the first RAW block.

Raises:

ValueError – If the provided block metadata does not match the RAW header values.

setigen.voltage.reduction module

class setigen.voltage.reduction.PolarizationMode(value)[source]

Bases: IntEnum

Supported polarization products for native RAW reduction.

TOTAL_POWER = 1

FULL_POL = 4

FULL_STOKES = -4

class setigen.voltage.reduction.RawReductionSpec(fftlength: int, integration_factor: int, pol_mode: int, output_format: Literal['fil', 'h5'], start_chan: int | None = None, num_chans: int | None = None, frequency_range: tuple[float, float] | None = None, backend: Literal['auto', 'numpy', 'cupy'] = 'auto', accuracy: Literal['exact', 'approx_zoom'] = 'exact', coarse_method: Literal['auto', 'full', 'selected'] = 'auto', fine_method: Literal['auto', 'full', 'selected'] = 'auto')[source]

Bases: object

Configuration for reducing a GUPPI RAW input into a spectrogram product.

fftlength: int

integration_factor: int

pol_mode: int

output_format: Literal['fil', 'h5']

start_chan: int | None = None

num_chans: int | None = None

frequency_range: tuple[float, float] | None = None

backend: Literal['auto', 'numpy', 'cupy'] = 'auto'

accuracy: Literal['exact', 'approx_zoom'] = 'exact'

coarse_method: Literal['auto', 'full', 'selected'] = 'auto'

fine_method: Literal['auto', 'full', 'selected'] = 'auto'

setigen.voltage.reduction.reduce_raw(input_path: str | Path, output_path: str | Path, spec: RawReductionSpec, *, overwrite: bool = False, tmp_dir: str | Path | None = None) → Path[source]

Reduce a RAW stem or .raw file into a .fil or .h5 product.

Parameters:

input_path – RAW stem or specific .raw file path.
output_path – Destination .fil or .h5 path.
spec – Reduction configuration.
overwrite – Whether an existing output file may be replaced.
tmp_dir – Optional directory for staged writes.

Returns:

Final output path.

Raises:

ValueError – If no spectra are produced for the supplied input and reduction settings.

setigen.voltage.reduction.reduce_raw_to_frame(input_path: str | Path, spec: RawReductionSpec, *, max_blocks: int | None = None) → Frame[source]

Reduce a total-power RAW input directly into a Frame for inspection.

Parameters:

input_path – RAW stem or specific .raw file path.
spec – Reduction configuration. Must request total power.
max_blocks – Optional maximum number of RAW blocks to process.

Returns:

Reduced Frame object.

Raises:

ValueError – If the reduction is not total power or no frame rows are produced.

setigen.voltage.spectrogram module

class setigen.voltage.spectrogram.VoltageSpectrogramSpec(fftlength: int, integration_factor: int, pol_mode: int = PolarizationMode.TOTAL_POWER, start_chan: int | None = None, num_chans: int | None = None, frequency_range: tuple[float, float] | None = None, backend: Literal['auto', 'numpy', 'cupy'] = 'auto', accuracy: Literal['exact', 'approx_zoom'] = 'exact', coarse_method: Literal['auto', 'full', 'selected'] = 'auto', fine_method: Literal['auto', 'full', 'selected'] = 'auto')[source]

Bases: object

Configuration for direct voltage-backend spectrogram generation.

Parameters:

fftlength – Fine-channel FFT length.
integration_factor – Number of fine spectra to integrate in time.
pol_mode – Polarization output mode.
start_chan – First coarse channel relative to the backend recorded span.
num_chans – Number of coarse channels to reduce.
frequency_range – Optional inclusive final-frequency bounds in Hz.
backend – Array backend for fine channelization.
accuracy – Accuracy policy. Only "exact" is implemented.
coarse_method – Coarse PFB transform method.
fine_method – Fine FFT transform method.

fftlength: int

integration_factor: int

pol_mode: int = 1

start_chan: int | None = None

num_chans: int | None = None

frequency_range: tuple[float, float] | None = None

backend: Literal['auto', 'numpy', 'cupy'] = 'auto'

accuracy: Literal['exact', 'approx_zoom'] = 'exact'

coarse_method: Literal['auto', 'full', 'selected'] = 'auto'

fine_method: Literal['auto', 'full', 'selected'] = 'auto'

class setigen.voltage.spectrogram.VoltageSpectrogramResult(data: ndarray, metadata: _ReductionMetadata, spec: VoltageSpectrogramSpec, input_spec: Any)[source]

Bases: object

Spectrogram data and metadata produced by a voltage backend.

Parameters:

data – Spectrogram array with shape (time, nifs, frequency).
metadata – Derived frequency/time metadata.
spec – Generation specification.
input_spec – Minimal input descriptor used for file headers.

data: ndarray

metadata: _ReductionMetadata

spec: VoltageSpectrogramSpec

input_spec: Any

to_frame() → Frame[source]

Return this total-power product as a setigen.Frame.

Returns:: Total-power spectrogram as a setigen.Frame.
Raises:: ValueError – If the result is not a total-power/Stokes-I product.

write(output_path: str | Path, *, output_format: Literal['fil', 'h5'] | None = None, overwrite: bool = False, tmp_dir: str | Path | None = None) → Path[source]

Write the spectrogram as a filterbank product.

Parameters:

output_path – Destination path.
output_format – Output format. If omitted, inferred from suffix.
overwrite – Whether an existing output file may be replaced.
tmp_dir – Optional staging directory.

Returns:

Final output path.

setigen.voltage.spectrogram.generate_voltage_spectrogram(backend: Any, spec: VoltageSpectrogramSpec, *, obs_length: float | None = None, num_blocks: int | None = None, length_mode: str = 'obs_length', digitize: bool = True, requantize: bool = True, verbose: bool = True, xp: Any) → VoltageSpectrogramResult[source]

Generate a spectrogram directly from a voltage backend.

Parameters:

backend – Configured RawVoltageBackend.
spec – Spectrogram generation specification.
obs_length – Observation length in seconds.
num_blocks – Number of backend blocks to generate.
length_mode – Strategy for interpreting observation length inputs.
digitize – Whether to quantize input voltages before the PFB.
requantize – Whether to quantize complex post-PFB voltages.
verbose – Whether to emit progress output.
xp – Numerical array module used by the backend.

Returns:

Direct spectrogram result.