HiSPARC clusters¶

Define HiSPARC detectors, stations and clusters.

The BaseCluster defines a HiSPARC cluster consisting of one or more stations. The Station defines a HiSPARC station, consisting of one or more Detector objects.

To easily create a cluster object for a specific set of real HiSPARC stations the HiSPARCStations can be used, for example:

>>> from sapphire import HiSPARCStations
>>> cluster = HiSPARCStations([102, 104, 105], force_stale=True)


The use of force_stale forces the use of local data, which is much faster to load than data from the server.

These cluster objects are mainly used by simulations and reconstructions.

class sapphire.clusters.Detector(station, position, orientation='UD', detector_timestamps=None)

A HiSPARC detector

Initialize detector

Parameters: station – station instance this detector is part of. position – x,y,z position of the center of the detectors relative to the station center. z is optional. Multiple positions can be provided by giving lists for each axis. orientation – orientation of the long side of the detector. Either the angle in radians, or ‘UD’ or ‘LR’ meaning an up-down or left-right orientation of the long side of the detector respectively. detector_timestamps – list of timestamps, the timestamp at which each of the layouts became active.
detector_size
get_area()
get_xy_coordinates()
get_coordinates()
get_polar_coordinates()
get_cylindrical_coordinates()
get_lla_coordinates()

Get detector LLA coordinates (latitude, longitude, altitude)

get detector WGS84 coordinates LLA: Latitude, Longitude, Altitude

Returns: tuple (latitude, longitude, altitude). Latitude, longitude in degrees. Altitude in meters.
get_corners()

Get the x, y coordinates of the detector corners

The z-coordinate is not returned because all detectors are assumed to be laying flat.

Returns: coordinates of detector corners, list of (x, y) tuples.
class sapphire.clusters.Station(cluster, station_id, position, angle=None, detectors=None, station_timestamps=None, detector_timestamps=None, number=None)

A HiSPARC station

Initialize station

Parameters: cluster – cluster this station is a part of station_id – int (unique identifier) position – x,y,z position of the station center relative to the cluster center, z is optional. angle – angle of rotation of the station in radians detectors – list of tuples. Each tuple consists of (dx, dy, orientation) where dx and dy are x and y positions of the center of the detectors relative to the station center. Orientation is either ‘UD’ or ‘LR’ meaning an up-down or left-right orientation of the long side of the detector respectively. station_timestamps – list of timestamps, the timestamp at which each of the positions became active. detector_timestamps – list of timestamps, the timestamp at which each of the layouts became active. number – optional unique identifier for a station this can be used by the cluster to find a specific station and makes it easier to link to a real station. If not given it will be equal to the station_id.
detectors
get_area(detector_ids=None)

Get the total area covered by the detectors

Parameters: detector_ids – list of detectors for which to get the total area. total area of the detectors in m^2.
get_xy_coordinates()

Same as get_coordinates but without the z and alpha

get_xyalpha_coordinates()

Same as get_coordinates but without the z

get_coordinates()

Calculate coordinates of a station

Returns: x, y, z, alpha; coordinates and rotation of station relative to absolute coordinate system
get_polar_alpha_coordinates()
get_cylindrical_alpha_coordinates()
get_lla_coordinates()

Get station LLA coordinates (latitude, longitude, altitude)

LLA: Latitude, Longitude, Altitude

Returns: tuple (latitude, longitude, altitude). Latitude, longitude in degrees. Altitude in meters.
calc_r_and_phi_for_detectors(d0, d1)
calc_rphiz_for_detectors(d0, d1)

Calculate angle and distance between detectors

Parameters: d0,d1 – detector ids to find the vector between. r,phi,z pointing from d0 to d1.
calc_xy_center_of_mass_coordinates()
calc_center_of_mass_coordinates()

Calculate center of mass coordinates of detectors in station

Returns: x, y, z; coordinates of station center relative to absolute coordinate system
class sapphire.clusters.BaseCluster(position=(0, 0, 0), angle=0, lla=(52.35592417, 4.95114402, 56.10234594))

Base class for HiSPARC clusters

Override this function to build your cluster

Parameters: position – x,y,z position for the center of the cluster. angle – rotation of the cluster in the x,y-plane. lla – Reference WGS84 location of the cluster origin. Defaults to (old) GPS location of station 501 (Nikhef).
set_timestamp(timestamp)

Set the timestamp to set the active station and detector locations

Parameters: timestamp – timestamp in seconds.
set_center_off_mass_at_origin()

Set the cluster center of mass to (0, 0, 0)

stations
get_station(number)

Get a station by its number

get_xy_coordinates()

Same as get_coordinates but without the z and alpha

get_xyalpha_coordinates()

Like get_coordinates, but without z

get_coordinates()

Get cluster coordinates (x, y, z, alpha).

The coordinates should be interpreted as follows: first, the cluster is rotated over angle alpha, around its original center. Then, the cluster is translated to (x, y, z).

get_polar_alpha_coordinates()

Like get_cylindrical_coordinates but without z.

get_cylindrical_alpha_coordinates()

Get cluster coordinates (r, phi, z, alpha).

The coordinates should be interpreted as follows: first, the cluster is rotated over angle alpha, around its original center. Then, the cluster is translated to (r, phi, z).

get_lla_coordinates()

Get cluster LLA coordinates (latitude, longitude, altitude)

get cluster WGS84 coordinates LLA: Latitude, Longitude, Altitude

Returns: tuple (latitude, longitude, altitude). Latitude, longitude in degrees. Altitude in meters.
set_coordinates(x, y, z, alpha)

Set cluster coordinates (x, y, z, alpha).

The coordinates should be interpreted as follows: first, the cluster is rotated over angle alpha, around its original center. Then, the cluster is translated to (x, y, z).

set_cylindrical_coordinates(r, phi, z, alpha)

Set cluster coordinates (r, phi, z, alpha).

The coordinates should be interpreted as follows: first, the cluster is rotated over angle alpha, around its original center. Than, the cluster is translated to (r, phi).

calc_rphiz_for_stations(s0, s1)

Calculate distance between and direction of two stations

The calculated result is between the center of mass coordinates of the two stations.

Parameters: s0,s1 – The station ids for the two stations. r, phi, z; the distance between and direction of the two given stations.
calc_xy_center_of_mass_coordinates()

Like calc_center_of_mass_coordinates, but without z

calc_center_of_mass_coordinates()

Calculate center of mass coordinates of all detectors in cluster

Returns: x, y, z; coordinates of cluster center relative to absolute coordinate system
calc_distance_between_stations(s1, s2)

Calculate distance between two stations

Parameters: s1,s2 – station numbers. distance between stations.
calc_horizontal_distance_between_stations(s1, s2)

Calculate 2D distance between two HiSPARC stations. Ignores altitude

The 2D plane is the East-North plane defined by the ENU axes at the reference location for this cluster.

Parameters: s1,s2 – station numbers. distance between stations.
class sapphire.clusters.CompassStations(position=(0, 0, 0), angle=0, lla=(52.35592417, 4.95114402, 56.10234594))

Add detectors to stations using compass coordinates

Compass coordinates consist of r, alpha, z, beta. These define the location and orientation of detectors. For more information see Coordinate systems and units in HiSPARC.

This is meant for data from the Publicdb Database API, which uses that coordinate system.

Override this function to build your cluster

Parameters: position – x,y,z position for the center of the cluster. angle – rotation of the cluster in the x,y-plane. lla – Reference WGS84 location of the cluster origin. Defaults to (old) GPS location of station 501 (Nikhef).
class sapphire.clusters.SimpleCluster(size=250)

Define a simple cluster containing four stations

Parameters: size – This value is the distance between the three outer stations.
class sapphire.clusters.SingleStation

Define a cluster containing a single station

class sapphire.clusters.SingleDetectorStation

Define a cluster containing a single 1-detector station

class sapphire.clusters.SingleTwoDetectorStation

Define a cluster containing a single 2 detector station

class sapphire.clusters.SingleDiamondStation

Define a cluster containing a single diamond shaped station

Detectors 1, 3 and 4 are in the usual position for a 4 detector layout, detector 2 is moved out of the center and positioned to create a second equilateral triangle with detectors 1, 2 and 4.

class sapphire.clusters.HiSPARCStations(stations, skip_missing=False, force_fresh=False, force_stale=False)

A cluster containing any real station from the HiSPARC network

The gps position and number of detectors are taken from the API. The detector positions are retrieved if available, otherwise default values are used!

Parameters: stations – A list of station numbers to include. The coordinates are retrieved from the Public Database API. The first station is placed at the origin of the cluster. skip_missing – Set to True to skip stations which have missing location data, otherwise an exception will be raised. Stations with missing location data will be excluded. Does not apply to missing detector positions.

Example:

>>> cluster = HiSPARCStations([7001, 7002, 7003])

class sapphire.clusters.ScienceParkCluster(stations=None, skip_missing=False, force_fresh=False, force_stale=False)

A cluster containing stations from the Science Park subcluster

Parameters: stations – A list of station numbers to include. Only stations from the Science Park subcluster (5xx) are supported. By default 507 is excluded.
class sapphire.clusters.HiSPARCNetwork(force_fresh=False, force_stale=False)

A cluster containing all station from the HiSPARC network

sapphire.clusters.flatten_cluster(cluster)

Set the altitudes for all detectors in a cluster object to z=0

Modify the given cluster by setting the z coordinates of the stations and detectors to 0.

Parameters: cluster – BaseCluster object.