`virgil.harmonics`

Azimuthal harmonics of a MultipoleDisk: the image harmonics \(I_m\) that every form maps to and from (the linear, positive and von Mises forms of the azimuthal profile and the legacy az_amps/az_pas of ModulatedGaussianRim and TruncatedCone), and the reflection-coefficient machinery of the positive form.

Azimuthal harmonics: the image-harmonic convention and conversions.

Every azimuthal profile of a MultipoleDisk is, at each radius, \(I(\theta)/I_0 = \sum_{m=-M}^{M} I_m e^{im\theta}\) with \(I_0 = 1\) and \(I_{-m} = \bar I_m\), where \(\theta\) is the azimuth in the plane of the disk, from the projected major axis towards pa + 90. The linear, positive, von Mises and legacy amplitude/azimuth forms all map to and from these image harmonics \(I_m\) (complex, \(m = 0 \dots M\)) with to_image_harmonics and from_image_harmonics: report any model in one convention and warm-start a positive-form fit from a linear one. The positive form's reflection coefficients are an internal parametrization: report the image harmonics. The forms, their formulas and references are in azimuthal harmonics.

`to_image_harmonics(harmonics, r=None)`

The image harmonics I_0 .. I_M (I_0 = 1) of a model.

Parameters:

Name	Type	Description	Default
`harmonics`	`Harmonics or VonMises`	A linear or positive `Harmonics`, or a `VonMises` (truncated at its degree; see `VonMises.truncation_power`).	required
`r`	`float or array - like`	Radii (mas) at which to evaluate coefficients that are functions of the radius; not needed for constants.	`None`

Returns:

Type	Description
`array - like`	Complex, shape `(M + 1,)` (or `(M + 1,) + shape(r)`).

`from_image_harmonics(image_harmonics, form='linear')`

A constant-coefficient Harmonics with the given image harmonics.

linear is exact both ways. positive is a spectral factorization (numpy, not differentiated): the roots of \(z^M \sum_m I_m z^m\) outside the unit circle give the minimum-phase \(h\), then the step-down recursion gives the reflection coefficients and the inverse tanh the latents. It needs a non-negative image; roots on the circle (an image that touches zero) clip |k| to 1 - 1e-6 with a warning. The degree is that of image_harmonics (a lower true degree gives zero outer latents).

Parameters:

Name	Type	Description	Default
`image_harmonics`	`array - like`	`I_0 .. I_M`, complex; they are normalized to `I_0 = 1`.	required
`form`	`(linear, positive)`		`"linear"`

Raises:

Type	Description
`ValueError`	For `form="positive"` if the image is negative somewhere.

`from_legacy(az_amps, az_pas, pa, kind='rim')`

The linear Harmonics of a legacy az_amps/az_pas modulation.

Parameters:

Name	Type	Description	Default
`az_amps`	`array - like`	Amplitudes and azimuths (degrees) of the modulations, one per order.	required
`az_pas`	`array - like`	Amplitudes and azimuths (degrees) of the modulations, one per order.	required
`pa`	`float`	The class's `pa` in degrees (the disk's `pa` for a rim; the cone's `pa`, not the disk's `pa - 90`).	required
`kind`	`(rim, cone)`	`ModulatedGaussianRim` or `TruncatedCone` conventions.	`"rim"`

`to_legacy(harmonics, pa, kind='rim')`

(az_amps, az_pas) of constant harmonics: the inverse of :func:from_legacy.

The amplitudes are non-negative and the azimuths in degrees, the first of the 360 / m equivalent ones in a turn about pa.

`rim_coefficients(az_amps, az_pas, pa)`

(c, s) of ModulatedGaussianRim's modulation \(\sum_m A_m \cos[m(\phi - \phi_m)]\).

The rim's azimuth \(\phi\) is the engine's azimuth plus pa (az_pas are in the plane of the rim, in the sense of position angle, with pa on the major axis), so \(c_m = A_m \cos m(\phi_m - \mathrm{pa})\) and \(s_m = A_m \sin m(\phi_m - \mathrm{pa})\). Angles in degrees.

Returns:

Type	Description
`c, s : array-like`	Each of shape `(M,)`.

`cone_coefficients(az_amps, az_pas, pa)`

(c, s) of TruncatedCone's modulation \(\sum_m A_m \cos[m(\phi - \phi_m)]\).

The cone's ring angle is 0 on the wall at pa + 90 and the engine's azimuth runs from the major axis, at pa - 90: half a turn apart, so \(c_m = (-1)^m A_m \cos(m\,\mathrm{ph})\), \(s_m = -(-1)^m A_m \sin(m\,\mathrm{ph})\) with \(\mathrm{ph} = \mathrm{pa} + 90^\circ - \phi_m\). Angles in degrees.

Returns:

Type	Description
`c, s : array-like`	Each of shape `(M,)`.

`reflection_coefficients(re, im)`

Complex reflection coefficients from Cartesian latents.

\(k = w \tanh|w| / |w|\) with \(w = \mathrm{re} + i\,\mathrm{im}\), so \(|k| < 1\). Value and gradient are finite at \(w = 0\) (the series \(\tanh x / x \approx 1 - x^2/3\) is used for small \(|w|\), behind a safe where).

Parameters:

Name	Type	Description	Default
`re`	`array - like`	Real and imaginary parts of the latents, shape `(M, ...)`.	required
`im`	`array - like`	Real and imaginary parts of the latents, shape `(M, ...)`.	required

Returns:

Type	Description
`array - like`	Complex coefficients of the same shape.

`step_up(k)`

Coefficients h_0..h_M of the minimum-phase polynomial of the reflection coefficients k (shape (M, ...)), with h_0 = 1.

Returns a complex array of shape (M + 1, ...).

`step_down(h, clip=_CLIP)`

Reflection coefficients of the polynomial h (h_0 is normalized to 1): the inverse of :func:step_up.

For a minimum-phase h every |k_j| < 1. A coefficient with |k_j| > 1 - clip (a root on or inside the unit circle) is clipped to 1 - clip and clipped is true.

Returns:

Name	Type	Description
`k`	`ndarray`	Complex `k_1 .. k_M`.
`clipped`	`bool`

`latents_from_reflection(k)`

Unconstrained latents w = k artanh|k| / |k| (|k| < 1).

`spectral_factor(image_harmonics, negative_tol=1e-06)`

The minimum-phase h (h_0 = 1) of a positive image.

Takes the 2M roots of \(z^M \sum_m I_m z^m\), keeps the M outside the unit circle (the largest in modulus), and builds \(h(z) = \prod (1 - z / z_k)\).

Parameters:

Name	Type	Description	Default
`image_harmonics`	`array - like`	`I_0 .. I_M` (`I_0 > 0`; the rest relative to it).	required
`negative_tol`	`float`	The image may dip to `-negative_tol * I_0` (rounding) before it is refused.	`1e-06`

Raises:

Type	Description
`ValueError`	If the image is negative somewhere, or `I_0` is not positive.

`image_harmonics_from_h(h)`

Image harmonics I_0..I_M (I_0 = 1) of |h|^2 / sum |h_j|^2.

h has shape (M + 1, ...); the result is complex of the same shape.