pycsamt.z.resphase#

Classes

ResPhase([z_array, z_err_array, freq])

Resistivity/phase container backed by complex Z.

class pycsamt.z.resphase.ResPhase(z_array=None, z_err_array=None, freq=None, **kwargs)[source]#

Bases: EMBase

Resistivity/phase container backed by complex Z.

ResPhase computes apparent resistivity \(\rho\) and phase \(\phi\) from a complex impedance tensor Z, and supports the inverse map \((\rho,\ \phi) \rightarrow \mathbf{Z}\) with error propagation. It is a light, independent container; Z inherits from it to add higher-level conveniences.

Parameters:

z_array (ndarray, shape (n_freq, 2, 2), optional) – Complex impedance tensor Z. If omitted, call compute_resistivity_phase() later.
z_err_array (ndarray, shape (n_freq, 2, 2), optional) – Absolute per-component uncertainty on Z. If omitted, uncertainties on \(\rho\) and \(\phi\) remain None.
freq (ndarray, shape (n_freq,), optional) – Frequency vector in Hz. Must be 1-D, finite and strictly positive.
**kwargs – Forwarded to BaseEM (e.g., name, meta).

Variables:

resistivity (ndarray, shape (n_freq, 2, 2)) – Apparent resistivity \(\rho\) (Ω·m). Set by compute_resistivity_phase() or set_res_phase().
phase (ndarray, shape (n_freq, 2, 2)) – Phase \(\phi\) in degrees. Set alongside :pyattr:`resistivity`.
resistivity_err (ndarray or None, shape (n_freq, 2, 2)) – Absolute uncertainty on \(\rho\) (Ω·m) or None if no Z errors were provided.
phase_err (ndarray or None, shape (n_freq, 2, 2)) – Absolute phase uncertainty (deg) or None.
z (ndarray or None, shape (n_freq, 2, 2)) – Complex Z, when known (set by the inverse path).
z_err (ndarray or None, shape (n_freq, 2, 2)) – Absolute uncertainty on Z, when propagated.
freq (ndarray or None, shape (n_freq,)) – Frequency vector in Hz (1-D, finite, > 0).
n_freq (int) – Inferred number of frequencies (from :pyattr:`freq` or the first dimension of known arrays).

Notes

Forward path. \(\rho\) and \(\phi\) are computed from Z using

\[\rho \;=\; 0.2\,\frac{|Z|^{2}}{f}, \qquad \phi \;=\; \angle Z \quad (\text{in degrees}).\]

Error propagation (forward). If Z errors are available, the per-entry relative amplitude error is \(\Delta Z/|Z|\). We use z_error2r_phi_error() to map this to the \(\rho\) relative error (×2) and to an absolute phase uncertainty (deg, capped at \(90^{\circ}\)).

Inverse path. Given \(\rho\) and \(\phi\), we recover \(|Z|\) from

\[|Z| \;=\; \sqrt{\,5\,f\,\rho\,},\]

then build Z in Euler form. When \(\rho\) and \(\phi\) errors are given, the \(|Z|\) error follows

\[\frac{d|Z|}{|Z|} \;=\; \tfrac{1}{2}\,\frac{d\rho}{\rho},\]

and, together with the phase error, is converted to a single absolute Z error per component via propagate_error_polar2rect().

Examples

Compute \(\rho\) and \(\phi\) from a stack of Z:

>>> import numpy as np
>>> from pycsamt.z.resphase import ResPhase
>>> z = np.ones((2, 2, 2), complex)
>>> f = np.array([10.0, 1.0])
>>> rp = ResPhase()
>>> rp.compute_resistivity_phase(z_array=z, freq=f)
>>> rp.resistivity.shape, rp.phase.shape
((2, 2, 2), (2, 2, 2))

Reconstruct Z from \(\rho,\ \phi\) (no uncertainties):

>>> rho = (0.2 / f)[:, None, None] * np.ones((2, 2, 2))
>>> phi = np.zeros_like(rho)
>>> rp.set_res_phase(rho, phi, f)
>>> rp._z.shape
(2, 2, 2)

See also

pycsamt.z.z.Z: High-level impedance container built on ResPhase.
pycsamt.utils.zmath.z_error2r_phi_error: Forward error mapping for \(\rho\) and \(\phi\).
pycsamt.utils.zmath.propagate_error_polar2rect: Polar → rectangular error propagation for Z.

References

property resistivity: ndarray[source]#

property resistivity_err: ndarray | None[source]#

property phase: ndarray[source]#

property phase_err: ndarray | None[source]#

compute_resistivity_phase(z_array=None, z_err_array=None, freq=None)[source]#

Compute \(rho\) and :math:`phi`(and their errors) from complex Z.

Any provided inputs override the instance state. On success, :pyattr:`resistivity`, :pyattr:`phase`, and, when applicable, :pyattr:`resistivity_err` and :pyattr:`phase_err` are set.

Parameters:

z_array (ndarray, shape (n_freq, 2, 2), optional) – Complex impedance tensor Z. If given, it replaces the internal value used for the computation.
z_err_array (ndarray, shape (n_freq, 2, 2), optional) – Absolute Z error. If omitted, ρ and φ uncertainties are set to None.
freq (ndarray, shape (n_freq,), optional) – Frequency vector in Hz. Must be 1-D, finite and > 0.

Returns:

Results are stored on the instance.

Return type:

None

Raises:

ZError – If Z is missing, shapes are inconsistent, values are not finite, or frequencies are not strictly positive.

Notes

We use \(\rho = 0.2\,|Z|^2 / f\) and \(\phi = \angle Z\) (in degrees).

If z_err_array is given, per-entry uncertainties are computed via z_error2r_phi_error(). The resistivity error is absolute (Ω·m). The phase error is absolute (deg) and is capped at \(90^\circ\).

Examples

>>> import numpy as np
>>> z = np.ones((2, 2, 2), complex)
>>> f = np.array([10.0, 1.0])
>>> rp = ResPhase()
>>> rp.compute_resistivity_phase(z_array=z, freq=f)
>>> rp.resistivity.shape
(2, 2, 2)

set_res_phase(res_array, phase_array, freq, res_err_array=None, phase_err_array=None)[source]#

Attach \(rho\) and \(phi\) (with optional errors) and reconstruct Z.

This inverse path accepts apparent resistivity (ρ) and phase (φ) at each frequency, reconstructs |Z| via |Z| = sqrt(5 f ρ), and builds the complex tensor Z. If both ρ and φ errors are supplied, a per-entry absolute Z uncertainty is propagated in polar coordinates and converted to rectangular form.

Parameters:

res_array (ndarray, shape (n_freq, 2, 2)) – Apparent resistivity (Ω·m). Must be real and finite.
phase_array (ndarray, shape (n_freq, 2, 2)) – Phase in degrees. Must be real and finite.
freq (ndarray, shape (n_freq,)) – Frequency in Hz (1-D, finite, strictly positive).
res_err_array (ndarray, shape (n_freq, 2, 2), optional) – Absolute error on ρ (Ω·m). If omitted, Z error is left None.
phase_err_array (ndarray, shape (n_freq, 2, 2), optional) – Absolute phase error in degrees.

Returns:

Results are stored on the instance (:pyattr:`_z`, :pyattr:`_z_err`, :pyattr:`resistivity`, :pyattr:`phase`).

Return type:

None

Raises:

ResistivityError – If ρ contains complex values.
PhaseError – If φ contains complex values.
ZError – If shapes are inconsistent, values are non-finite, or frequencies are not strictly positive.

Notes

The relationship between \(|Z|\) and \(\rho\) implies

..math:

\frac{d|Z|}{|Z|} = \tfrac{1}{2}\,\frac{d\rho}{\rho}.

When error arrays are supplied, |Z| error follows the above and is combined with phase error by propagate_error_polar2rect() to yield a single absolute Z error per component.

Examples

>>> import numpy as np
>>> f = np.array([10.0, 1.0])
>>> rho = (0.2 / f)[:, None, None] * np.ones((2, 2, 2))
>>> phi = np.zeros_like(rho)
>>> rp = ResPhase()
>>> rp.set_res_phase(rho, phi, f)
>>> rp._z.shape
(2, 2, 2)

property res_xx: ndarray[source]#

property res_xy: ndarray[source]#

property res_yx: ndarray[source]#

property res_yy: ndarray[source]#

property phase_xx: ndarray[source]#

property phase_xy: ndarray[source]#

property phase_yx: ndarray[source]#

property phase_yy: ndarray[source]#

property res_err_xx: ndarray | None[source]#

property res_err_xy: ndarray | None[source]#

property res_err_yx: ndarray | None[source]#

property res_err_yy: ndarray | None[source]#

property phase_err_xx: ndarray | None[source]#

property phase_err_xy: ndarray | None[source]#

property phase_err_yx: ndarray | None[source]#

property phase_err_yy: ndarray | None[source]#

compute_rho_phi(z_array=None, z_err_array=None, freq=None)#

Compute \(rho\) and :math:`phi`(and their errors) from complex Z.

Any provided inputs override the instance state. On success, :pyattr:`resistivity`, :pyattr:`phase`, and, when applicable, :pyattr:`resistivity_err` and :pyattr:`phase_err` are set.

Parameters:

z_array (ndarray, shape (n_freq, 2, 2), optional) – Complex impedance tensor Z. If given, it replaces the internal value used for the computation.
z_err_array (ndarray, shape (n_freq, 2, 2), optional) – Absolute Z error. If omitted, ρ and φ uncertainties are set to None.
freq (ndarray, shape (n_freq,), optional) – Frequency vector in Hz. Must be 1-D, finite and > 0.

Returns:

Results are stored on the instance.

Return type:

None

Raises:

ZError – If Z is missing, shapes are inconsistent, values are not finite, or frequencies are not strictly positive.

Notes

We use \(\rho = 0.2\,|Z|^2 / f\) and \(\phi = \angle Z\) (in degrees).

If z_err_array is given, per-entry uncertainties are computed via z_error2r_phi_error(). The resistivity error is absolute (Ω·m). The phase error is absolute (deg) and is capped at \(90^\circ\).

Examples

>>> import numpy as np
>>> z = np.ones((2, 2, 2), complex)
>>> f = np.array([10.0, 1.0])
>>> rp = ResPhase()
>>> rp.compute_resistivity_phase(z_array=z, freq=f)
>>> rp.resistivity.shape
(2, 2, 2)

set_rho_phi(res_array, phase_array, freq, res_err_array=None, phase_err_array=None)#

Attach \(rho\) and \(phi\) (with optional errors) and reconstruct Z.

This inverse path accepts apparent resistivity (ρ) and phase (φ) at each frequency, reconstructs |Z| via |Z| = sqrt(5 f ρ), and builds the complex tensor Z. If both ρ and φ errors are supplied, a per-entry absolute Z uncertainty is propagated in polar coordinates and converted to rectangular form.

Parameters:

res_array (ndarray, shape (n_freq, 2, 2)) – Apparent resistivity (Ω·m). Must be real and finite.
phase_array (ndarray, shape (n_freq, 2, 2)) – Phase in degrees. Must be real and finite.
freq (ndarray, shape (n_freq,)) – Frequency in Hz (1-D, finite, strictly positive).
res_err_array (ndarray, shape (n_freq, 2, 2), optional) – Absolute error on ρ (Ω·m). If omitted, Z error is left None.
phase_err_array (ndarray, shape (n_freq, 2, 2), optional) – Absolute phase error in degrees.

Returns:

Results are stored on the instance (:pyattr:`_z`, :pyattr:`_z_err`, :pyattr:`resistivity`, :pyattr:`phase`).

Return type:

None

Raises:

ResistivityError – If ρ contains complex values.
PhaseError – If φ contains complex values.
ZError – If shapes are inconsistent, values are non-finite, or frequencies are not strictly positive.

Notes

The relationship between \(|Z|\) and \(\rho\) implies

..math:

\frac{d|Z|}{|Z|} = \tfrac{1}{2}\,\frac{d\rho}{\rho}.

When error arrays are supplied, |Z| error follows the above and is combined with phase error by propagate_error_polar2rect() to yield a single absolute Z error per component.

Examples

>>> import numpy as np
>>> f = np.array([10.0, 1.0])
>>> rho = (0.2 / f)[:, None, None] * np.ones((2, 2, 2))
>>> phi = np.zeros_like(rho)
>>> rp = ResPhase()
>>> rp.set_res_phase(rho, phi, f)
>>> rp._z.shape
(2, 2, 2)

property phase_det: ndarray[source]#

property phase_det_err: ndarray[source]#

property res_det: ndarray[source]#

property res_det_err: ndarray[source]#