FCIO Reference

FCIO Reference#

Entry#

fcio_open(peer, timeout=0, buffersize=0, debug=0, compression='auto', extended=True)[source]#

Opens an fcio data file or tcp stream and returns an FCIO object exposing the data fields as well as interaction (reading) from stream. All parameters are passed as is to the FCIO constructor, offering some default values.

Return type:: FCIO

Classes#

class FCIO#

Bases: object

The main class providing access to the data fields. Interaction mainly by using the get_record() function or FCIO’s properties.

Parameters:

peer (str) – the path to the peer to open, can be zst or gzip compressed files.
timeout (int) – the timeout with which the connection should happend in milliseconds. default: 0 -1 : wait indefinitely >=0 : wait these milliseconds and return
buffersize (int) – the size of the internal buffer used by bufio in bytes. default: 0 uses bufios sane default size
debug (int) – sets the debug level of the fcio.c library using FCIODebug(debug) does not affect the verbosity of fcio-py parts default: 0
compression (str) – allows decompressing the file pointed to by peer while reading. ‘zst’ : use zstd executable to open file. autodetected if file ends with ‘.zst’ ‘gzip’ : use gzip executable to open file. autodetected if file ends with ‘.gz’ default ‘auto’ : determines possible compression by inspecting the peer ending
extended (bool) – enables additional properties of the FCIO record classes by replacing the FCIO properties with their extended classes. e.g. type(FCIO.event) == Event or EventExt some of these additions require additional calculations during reading, which might not be required and can be turned off by setting ‘extended’ to False. default: True

these properties provide access to: - values derived from more basic values in the record - explicit naming of certain field entries - explicit limits to some array accessing, which fall on the responsibility of the programmer in the fcio.c library

examples: - FCIO.event.card_address exposes an unsigned short array for the channels recorded in this event - FCIO.event.utc_unix applies the reference way to calculate the absolute time from the Config and Event records (timestamp and timeoffset depending on gps clock presence) - FCIO.event.trace array only returns the updated waveforms if the record was a SparseEvent - FCIO.event.fpga_baseline/.fpga_energy in correct units for both firmware versions - …

buffersize#: returns the set bufio buffersize in bytes

close()#

If a datafile is opened, close it and deallocate the FCIOData structure.

Return type:: None

config#: returns the current FCIOConfig record

configs#

Iterate through all FCIOConfig records in the datastream.

Returns the current config.

debug#: returns the set debug level

event#: returns the current FCIOEvent record

events#

Iterate through all FCIOEvent or FCIOSparseEvent records in the datastream.

Returns the current event.

fsp#

get_record()#

Calls FCIOGetRecord. Saves the returned tag (accessible via FCIO.tag).

Returns False if the tag <= 0 indicating either a stream error or timeout. Returns True otherwise.

is_open()#

Returns True/False if the internal data structur is allocated (i.e. if open() has been called without closing. No connection checks to remote peers are performed.

Return type:: bool

open(peer, timeout=0, buffersize=0, debug=0, compression='auto', extended=False)#

read_bytes(offset=0)#

Returns the number of bytes read from stream since opening. If offset is != 0, offset will be subtracted from the total, allowing quick calculation of deltas as in:

n_delta_bytes = fcio.read_bytes(0)

while fcio.get_record(): n_delta_bytes = fcio.read_bytes(n_delta_bytes)

recevent#: returns the current FCIORecEvent record

recevents#

Iterate through all FCIORecEvent records in the datastream.

Returns the current event.

set_mem_field(mview)#

skipped_bytes(offset=0)#

Returns the number of bytes skipped from stream since opening. If offset is != 0, offset will be subtracted from the total, allowing quick calculation of deltas as in:

n_delta_bytes = fcio.skipped_bytes(0)

while fcio.get_record(): n_delta_bytes = fcio.skipped_bytes(n_delta_bytes)

status#: returns the current FCIOStatus record

statuses#

Iterate through all FCIOStatus records in the datastream.

Returns the current event.

tag#: returns the current tag

tags#

Iterate through all FCIO records in the datastream.

Returns the current tag. Comparable behaviour to FCIOGetRecord of fcio.c

timeout#: returns the set timeout in milliseconds

class Tags#

Bases: object

A wrapper class for the fcio tag enum. Provides supported tags as attributes.

Config = 1#

Event = 3#

EventHeader = 7#

FSPConfig = 8#

FSPEvent = 9#

FSPStatus = 10#

RecEvent = 5#

SparseEvent = 6#

Status = 4#

str()#

class Limits#

Bases: object

A wrapper class to expose the compile time defines used in fcio.c

MaxChannels = 2400#

MaxPulses = 26400000#

MaxSamples = 32768#

TraceBufferLength = 22021440#

Records#

class Config#

Bases: object

Class internal to the fcio library. Do not allocate directly, must be created by using fcio_open or FCIO.open(). Represents the immutable readout configuration after starting a daq run. Guaranteed to be the first record in the stream. When concatenating streams or runs, might be sent again (with different values). Therefor it is advisable, to access these values as attributes from this class and not copy them somewhere else in the code.

adcbits#: The dynamic range of each sample, can be either 12 or 16. Determine by the firmware loaded.

adccards#: Number of adccards mapped during readout.

adcs#: The number of mapped adc channels.

blprecision#: For the 12-bit firmware, the baseline is calculated in higher precision (16-bit) and written as unsigned short in the trace header fields of the Event struct. To recover the correct units, the theader[0] field has to be divided by the blprecision parameter. For the 16-bit firmware this field is 1, allowing indifferent code.

eventsamples#: The number of samples configured. This determines the length of the waveforms.

gps#: GPS mode. 0: no connected external pps/clock (gps) >0: external pps/clock is used, and the value signifies the maximum acceptable delta between pps counters and unix seconds in microseconds.

mastercards#: Number of mastercards mapped during readout.

sampling_frequency_hz#: The sampling frequency in Hz of the digitizer used in this datastream.

sampling_period_ns#: The sampling period in nanoseconds of the digitizer used in this datastream.

streamid#: The id of this data stream.

sumlength#

For 12-bit firmware:: The number of samples used for the integrator value. If sumlength >= blprecision use integrator = sumlength/blprecision * (theader[1] - theader[0]) if sumlength < blprecision use integrator = theader[1] - theader[0] * sumlength / blprecision
For 16-bit firmware:: No meaning.

tracemap#: 1D Array of unsigned integers containing the fadc/trigger card address and input channel (front connected). Format is (address <<16) + channel. The index of the array is the same as the trace array indices, allowing to lookup the corresponding information.

triggercards#: Number of triggercards mapped during readout.

triggers#: The number of mapped trigger channels. This is one channel per trigger card. Only used in the 12-bit firmware.

class Event#

Bases: FCIOHeaderExt

Class internal to the fcio library. Do not allocate directly, must be created by using fcio_open or FCIO.open(). Exposes the fcio_event struct fields from the fcio.c library. All fields are exposes as numpy scalars or arrays with their corresponsing datatype and size.

card_address#: List of corresponding MAC addresses of the FADC Card per channel. Display in human readable form as hex(car_address[index])

card_channel#: List of input RJ45 Jacks of the FADC Card per channel. Must be within [0,5] for 16-bit firmware and [0,23] for 12-bit firmware.

dead_interval_nsec#: The dead time since the last triggered event in nanoseconds.

dead_interval_sec#: The dead time since the last triggered event in nanoseconds.

dead_time_nsec#

dead_time_sec#

deadregion#: the pps/clock counters while the readout system buffers are full. only updates when the system is

deadregion_size#: Size of the deadregion array. Must be equal to the shape[0] of the array.

eventnumber#: The event counter from the Top Master Card of this event for FCIOEvent records, and the event counter from the corresponding FADC Card for FCIOSparseEvent records.

eventsamples#: The number of samples of each waveform. This parameter is taken from the Config Record and exposed here for convenience.

fpga_baseline#: 1-d array of fpga baseline values with length <total number of read out traces>.

fpga_energy#: 1-d array of fpga energy values with length <total number of read out traces>.

fpga_time_nsec#: The number of nanoseconds since daq reset.

fpga_time_sec#: The number of nanoseconds since daq reset.

gps#: The maximum time difference between fpga pps and readout server second. If no external clock is used, this parameter is 0.

life_time_nsec#

life_time_sec#

num_traces#: the numbers of traces contain in the event. Incase of FCIOTag.Event tag, num_traces must be equal to the total number of mapped channels.

pulser#: the pulser amplitude setting

run_time_nsec#

run_time_sec#

theader#: 2D array of the waveforms headers containing the [0]fpga baseline and [1] fpga energy. shape is (<total number of traces in this event>,<2>)

timeoffset#: the offset between master card pps/clock counters and the readout server unix time.

timeoffset_size#: Size of the timeoffset array. Must be equal to the shape[0] of the array.

timestamp#: contains event counters and pps/clock counters

timestamp_size#: Size of the timestamp array. Must be equal to the shape[0] of the array.

trace#: 2D array containing the waveforms. shape is (<total number of traces in this event>,<number of samples>). See trace_list to get the correct trace_index or card_address / card_channel attributes.

trace_buffer#: The internal 2D FCIO traces buffer. Exposed for faster read operations, e.g. using memcpy or remapping of the buffer. For waveform access, use the trace property. shape is (<total number of mapped trace>,<number of samples + 2>)

trace_list#: Lookup array for the mapped channels, use with trace_buffer or trace attributes to get the correct waveforms.

type#: the event type

unix_time_utc_nsec#: The number of nanoseconds since 1970 (UTC unix timestamps).

unix_time_utc_sec#: utc_unix_ns in seconds as float64. Be aware that float64 on your machine probably doesn’t allow for a precision better than microseconds.

class RecEvent#

Bases: FCIOHeaderExt

amplitudes#: An float32 field containing the reconstructed amplitudes of the pulses.

card_address#: List of corresponding MAC addresses of the FADC Card per channel. Display in human readable form as hex(car_address[index])

card_channel#: List of input RJ45 Jacks of the FADC Card per channel. Must be within [0,5] for 16-bit firmware and [0,23] for 12-bit firmware.

channel_pulses#: A list of pulses per channel. Size is number of adcs (in config record). Use to look up the pulses per channel in the flags,`times` and amplitudes fields.

dead_interval_nsec#: The dead time since the last triggered event in nanoseconds.

dead_interval_sec#: The dead time since the last triggered event in nanoseconds.

dead_time_nsec#

dead_time_sec#

deadregion#: the pps/clock counters while the readout system buffers are full. only updates when the system is

deadregion_size#: Size of the deadregion array. Must be equal to the shape[0] of the array.

eventnumber#: The event counter from the Top Master Card of this event for FCIOEvent records, and the event counter from the corresponding FADC Card for FCIOSparseEvent records.

eventsamples#: The number of samples of each waveform. This parameter is taken from the Config Record and exposed here for convenience.

flags#: An int32 array containing some flags.

fpga_time_nsec#: The number of nanoseconds since daq reset.

fpga_time_sec#: The number of nanoseconds since daq reset.

gps#: The maximum time difference between fpga pps and readout server second. If no external clock is used, this parameter is 0.

life_time_nsec#

life_time_sec#

pulser#: the pulser amplitude setting

pulses#: Accessor for the stored pulse properties, will yield a tuple (trace_idx, flag, time, amplitude).

run_time_nsec#

run_time_sec#

timeoffset#: the offset between master card pps/clock counters and the readout server unix time.

timeoffset_size#: Size of the timeoffset array. Must be equal to the shape[0] of the array.

times#: An float32 field containing the reconstructed times of the pulses.

timestamp#: contains event counters and pps/clock counters

timestamp_size#: Size of the timestamp array. Must be equal to the shape[0] of the array.

totalpulses#: The total number of pulses in this RecEvent. Determines the size of the flags,`times` and amplitudes fields.

type#: the event type

unix_time_utc_nsec#: The number of nanoseconds since 1970 (UTC unix timestamps).

unix_time_utc_sec#: utc_unix_ns in seconds as float64. Be aware that float64 on your machine probably doesn’t allow for a precision better than microseconds.

class Status#

Bases: object

Class internal to the fcio library. Do not allocate directly, must be created by using fcio_open or FCIO.open(). Exposes the fcio_status struct fields from the fcio.c library. All fields are exposes as numpy scalars or arrays with their corresponsing datatype and size. The card status fields are accessible via the data attribute array

cards#: The total number of cards present in the data attribute

data#: An array of CardStatus objects. The type of card is ordered as master -> trigger -> adc card and their counts should be taken from the Config attributes.

fpga_start_time_sec#: Floating point calculation of statustime[5] * 1e-6 * statustime[6]

fpga_time_sec#: Floating point calculation of statustime[0] * 1e-6 * statustime[1]

size#: The size in bytes of each original card_status struct in fcio.c

status#: Overall status flag of the system. 1 : no errors 0 : errors did occur on some card

statustime#

1D array containing time information of this status record. Offsets: 0 : fc250 (mastercard) seconds since run start 1 : fc250 (mastercard) microseconds since last second 2 : unix utc (server) seconds 3 : unix utc (server) microseconds since last unix second 5 : pps counter when the trigger was enabled after start of the daq 6 : microseconds since [5]

5/6 signifies a start of the run offset one needs to for deadtime calculation

unix_time_utc_sec#: Floating point calculation of statustime[1] * 1e-6 * statustime[3]

class CardStatus#

Bases: object

ctierrors#: Number of errors on the CTI connection.

ctilinks#: Contain expert values, see fc250bcommands.h.

daughterboard_temperatures_mC#

dummy#: Ignored value..

enverrors#: Number of errors from environment sensors.

environment#: Contains information from the on-board environment sensors in the following order: 5 temperatures in mDegree 6 voltages in mV 1 main current im mA 1 humidity in o/oo 2 temperatures in mDegree, only present if adc piggy cards are used (adc card).

eventno#: The current event number (counter) when the Status was requested.

fpga_time_nsec#: The current time in nanoseconds in units of fpga clock.

fpga_time_sec#: The current time in nanoseconds in units of fpga clock.

linkerrors#: Number of errors on the trigger links (only relevant if trigger cards are attached).

linkstates#: Contain expert values, see fc250bcommands.h.

mainboard_current_mA#

mainboard_humiditiy_permille#

mainboard_temperatures_mC#

mainboard_voltages_mV#

maxticks#: The current maxticks. (Ticks counter when the last pps arrived.)

numctilinks#: Size of the ctilinks array.

numenv#: Size of the environment array.

numlinks#: Size of linkstates array.

othererrors#: 5 possible other erros. Check fc250b source code for more information.

pps#: The current pps counter.

reqid#: Current request id.

status#: Status of this card: 1 : ok, 0 : error

ticks#: The current ticks counter.

totalerrors#: Sum of enverrors, ctierrors and linkerrors.

class FSPConfig#

Bases: object

buffer#

ct#

hwm#

triggerconfig#

wps#

class FSPEvent#

Bases: object

is_consecutive#

is_ct_multiplicity#

is_extended#

is_hwm_multiplicity#

is_hwm_prescaled#

is_wps_coincident_sum#

is_wps_prescaled#

is_wps_sum#

is_written#

obs#

obs_ct_max#

obs_ct_multiplicity#

obs_ct_trace_idx#

obs_evt_nconsecutive#

obs_hwm_hw_multiplicity#

obs_hwm_max_value#

obs_hwm_min_value#

obs_hwm_sw_multiplicity#

obs_ps_hwm_prescaled_trace_idx#

obs_wps_max_single_peak_offset#

obs_wps_max_single_peak_value#

obs_wps_sum_multiplicity#

obs_wps_sum_offset#

obs_wps_sum_value#

proc_flags#

write_flags#

class FSPStatus#

Bases: object

avg_rate_discard_events#

avg_rate_read_events#

avg_rate_write_events#

dt#

dt_logtime#

dt_n_discarded_events#

dt_n_read_events#

dt_n_written_events#

dt_rate_discard_events#

dt_rate_read_events#

dt_rate_write_events#

log_time#

n_discarded_events#

n_read_events#

n_written_events#

runtime#

start_time#

stats#: The internal c-struct exposed as python dictionary.

FCIO Reference

Contents

FCIO Reference#

Entry#

Classes#

Records#