Context#

class phise.Context(
interferometer: Interferometer,
target: Target,
h: Quantity,
Δh: Quantity,
Γ: Quantity,
monochromatic=False,
name: str = 'Unnamed Context',
)[source]#

Bases: object

Observation context holding instrument, target and acquisition settings.

Parameters:

  • interferometer (Interferometer) – Instrument and geometry.

  • target (Target) – Target definition (coordinates, flux, companions).

  • h (u.Quantity) – Local hour angle (central time) of the observation.

  • Δh (u.Quantity) – Time/Hour-angle span of the observation.

  • Γ (u.Quantity) – RMS cophasing error (length quantity).

  • monochromatic (bool) – If True, use monochromatic approximation.

  • name (str) – Human-readable context name.

property interferometer: Interferometer#

Interferometer used in this context.

property target: Target#

Target observed in this context.

property h: Quantity#

Local hour angle (central time) of the observation.

property Δh: Quantity#

Time/Hour-angle span of the observation.

property Γ: Quantity#

Upstream piston RMS (in length units) during the observation.

property p: Quantity#

(Read-only) Projected telescope positions in a plane perpendicular to the line of sight.

property monochromatic: bool#

Whether to use the monochromatic approximation.

property name: str#

Human-readable context name.

property pf: Quantity#

(n_telescopes,)

Type:

(Read-only) Photon flux per telescope. Shape

get_reference_exposure_time(
target_adu_fraction: float = 1,
include_dark_current: bool = True,
) → Quantity[source]#

Compute a reference exposure time for stellar acquisition.

This helper estimates an exposure time that places a detector pixel at a chosen fraction of full-well capacity, assuming perfect coupling of all stellar photons into a single output (ideal fiber coupling scenario). This avoids dependence on chip imperfections or interferometer coherence.

The stellar electron rate on the central pixel is computed as:
electron_rate = (total_photon_flux) × (central_pixel_fraction)

× (quantum_efficiency) [+ dark_current]

where total_photon_flux = sum(pf) is the combined flux from all telescopes, and central_pixel_fraction is the integral of the 2D Gaussian spot over the central pixel area, with sigma = camera.spot_size in pixel units.

Parameters:

  • target_adu_fraction (float) – Target fraction of pixel full-well capacity, in (0, 1].

  • include_dark_current (bool) – If True, include the mean dark current contribution per pixel in the electron budget.

Returns:

Reference exposure time in seconds.

Return type:

u.Quantity

Raises:

  • ValueError – If target_adu_fraction is outside (0, 1] or if the resulting electron rate is not strictly positive.

  • TypeError – If target_adu_fraction is not numeric.

Notes

This calculation assumes 100% coupling efficiency (all stellar photons reach one output). In practice, chip efficiency and interferometric visibility will be lower.

If exposure time exceeds dark saturation threshold (≈ fwc/dc), a warning is issued.

plot_projected_positions(
N: int = 11,
return_image=False,
save_as: str = None,
)[source]#

Plot telescope positions over time.

Parameters:

  • N (int) – Number of positions to plot.

  • return_image (bool) – If True, return an image buffer instead of displaying it.

  • save_as (str) – Path to save the plot.

Returns:

PNG image buffer when return_image=True; otherwise None.

Return type:

Optional[bytes]

get_transmission_maps(N: int)[source]#

See phise.modules.transmission_map.get_transmission_maps().

get_transmission_map_gradient_norm(N: int)[source]#

See phise.modules.transmission_map.get_transmission_map_gradient_norm().

plot_transmission_maps(
N: int = 100,
return_plot: bool = False,
grad=False,
save_as=None,
)[source]#

See phise.modules.transmission_map.plot_transmission_maps().

plot_analytical_transmission_maps(
N: int,
return_plot: bool = False,
save_as=None,
)[source]#

See phise.modules.transmission_map.plot_analytical_transmission_maps().

get_input_fields() → ndarray[complex][source]#

Get complex amplitudes of the signals acquired by the telescopes.

Returns:

Array of shape (n_companions + 1, n_telescopes).

Return type:

np.ndarray[complex]

get_h_range() → ndarray[float][source]#

Get the hour-angle range of the observation.

Returns:

Hour angle values.

Return type:

np.ndarray[float]

observe_monochromatic(
upstream_pistons: Quantity = None,
mode: str = 'flux',
)[source]#

Observe the target with monochromatic approximation.

Parameters:

  • upstream_pistons (Optional[u.Quantity]) – If provided, use this static OPD error instead of random atmospheric piston. Shape: (n_telescopes,)

  • mode (str) – Output mode. Supported values are 'flux' (total photon counts per output), 'image' (camera images per output with shape (nb_outputs, resolution, resolution)), and 'demo' (matplotlib Figure showing output images).

Returns:

Depends on mode.

Return type:

np.ndarray[float] | np.ndarray[int] | matplotlib.figure.Figure

observe(
spectral_samples=5,
upstream_pistons: Quantity = None,
mode: str = 'flux',
)[source]#

Observe the target in this context.

Parameters:

  • spectral_samples (int) – Number of spectral samples to acquire (default: 5).

  • upstream_pistons (Optional[u.Quantity]) – If provided, use this static OPD error instead of random atmospheric piston. Shape: (n_telescopes,)

  • mode (str) – Output mode. Supported values are 'flux' (total photon counts per output), 'image' (camera images per output integrated over bandwidth, shape (nb_outputs, resolution, resolution)), and 'demo' (matplotlib Figure showing output images).

Returns:

Depends on mode.

Return type:

np.ndarray[float] | np.ndarray[int] | matplotlib.figure.Figure

observation_serie(n: int = 1) → ndarray[int][source]#

Generate a series of observations in this context.

Parameters:

n (int) – Number of nights (observations per given hour angle).

Returns:

Array of shape (n, nb_hour_angles, nb_outputs)

Return type:

np.ndarray[int]

calibrate_gen(
β: float,
verbose: bool = False,
plot: bool = False,
figsize: tuple = (10, 10),
save_as=None,
) → dict[source]#

Optimize phase shifter offsets to maximize nulling performance.

Deprecated since version 1.0: Use phise.modules.calibration.calibrate_gen() directly instead.

Parameters:

  • β (float) – Decay factor for the step size (0.5 <= β < 1).

  • verbose (bool) – If True, print optimization progress.

  • plot (bool) – If True, plot the optimization process.

  • figsize (tuple) – Figure size for plots.

  • save_as (str) – Path to save the plot if plot is True.

Returns:

Dictionary with optimization history (depth, shifters).

Return type:

dict

calibrate_obs(
n: int = 1000,
plot: bool = False,
figsize: tuple[int] = (30, 20),
save_as=None,
)[source]#

Optimize calibration via least squares sampling.

Deprecated since version 1.0: Use phise.modules.calibration.calibrate_obs() directly instead.

Parameters:

  • n (int) – Number of sampling points for least squares.

  • plot (bool) – If True, plot the optimization process.

  • figsize (tuple[int]) – Figure size for plots.

  • save_as (str) – Path to save the plot if plot is True.

Returns:

New context with optimized kernel nuller (if implemented to return).

Return type:

None | Context