Spherical wave expansions

Loading SWE coefficients

waveport.load_swe(path: str | Path) → list[Swe]

Load a grid file given its path

The function takes the name of the file containing the SWE coefficients and returns a list of Swe objects (one per each frequency saved in the file):

import waveport

swe_list = waveport.load_swe("my_antenna_pattern.sph")

The function is able to automatically decompress .gz and .bz2 files.

waveport.loads_swe(contents: str) → list[waveport._core.Swe]

Parse a string containing the contents of a TICRA .sph file

This function accepts a text string that contains the contents of a TICRA .sph file. It should be used whenever a file is not physically present on a storage device but was received by any other means, e.g., through a socket or as the output of a decompression program.

Note that you can use load_swe() if the file you want to load was compressed using GZip or BZip2, as the function handles the decompression automatically.

The Swe class

class waveport.Swe

The contents of a TICRA .sph file

This class contains all the information loaded from a .sph file.

It is typically instantiated by the functions loads_swe() (which reads the contents from a pre-loaded text string) and load_swe() (which takes a filename as parameter and loads its contents).

are_indexes_valid(self, s: int, m: int, n: int) → bool

Determine if \((s, m, n)\) is a valid set of coefficients

The coefficients s (either 0 or 1), m, and n are used to identify the \(Q_{smn}\) coefficient by Swe.coefficient(). Not all combinations of coefficients are valid: if they are not, Swe.coefficient() returns zero. This function can be used to determine if a zero is because the coefficient does not exist or is actually zero.

coefficient(self, s: int, m: int, n: int) → complex

Return one \(Q_{smn}\) coefficient given its index.

property cum_power_w

Return the cumulative power of the SWE coefficients

This variable contains the sum of the power encoded by all the \(Q_{smn}\) coefficients read from the file. Its value is expressed in Watt.

property frequency_hz

The radiation frequency

The frequency (in Hz) of the radiation used to compute the coefficients.

WavePort deduces this field from the header, but as it is not formally documented in the TICRA User’s manual, the extraction of the frequency might fail. In this case, WavePort sets it to None.

property m_max

Maximum value for the azimuthal index \(\left|m\right|\)

The number must be between 1 and Swe.num_of_theta/2

property n_max

Maximum value for the polar index \(n\)

The number must be between 1 and Swe.num_of_theta/2

property num_of_coefficients

Number of coefficients stored in memory

This represents the actual number of complex coefficients \(Q_{smn}\) stored in memory by the Swe object.

property num_of_phi

Number of φ-samples over 360°

This number must be ≥3.

property num_of_theta

Number of ϑ-samples over 360°

This number must be even and ≥4.