spotter.core
============

.. py:module:: spotter.core

.. autoapi-nested-parse::

   Core utilities for spherical maps, geometry, and flux calculations.

   This module provides functions for working with HEALPix maps, including
   coordinate transformations, limb darkening, spot generation, and flux
   integration for stellar surfaces.



Functions
---------

.. autoapisummary::

   spotter.core.distance
   spotter.core.npix
   spotter.core.equator_coords
   spotter.core.mask_projected_limb
   spotter.core.vec
   spotter.core.design_matrix
   spotter.core.flux
   spotter.core.spherical_to_cartesian
   spotter.core.spot
   spotter.core.soft_spot
   spotter.core.render
   spotter.core.amplitude
   spotter.core.transit_chord
   spotter.core.radial_velocity
   spotter.core.doppler_shift
   spotter.core.shifted_spectra
   spotter.core.integrated_spectrum


Module Contents
---------------

.. py:function:: distance(X, x)

   Compute the great-circle distance between vectors X and x.

   :param X: Array of 3D vectors.
   :type X: array_like, shape (..., 3)
   :param x: Single 3D vector.
   :type x: array_like, shape (3,)

   :returns: **d** -- Great-circle distance(s) in radians.
   :rtype: array_like


.. py:function:: npix(N)

   Return the number of HEALPix pixels for a given nside.

   :param N: HEALPix nside parameter.
   :type N: int

   :returns: **n** -- Number of pixels.
   :rtype: int


.. py:function:: equator_coords(phi=None, inc=None, obl=None)

   Compute the coordinates of the stellar equator for given orientation.

   :param phi: Rotation phase in radians.
   :type phi: float or None, optional
   :param inc: Inclination in radians.
   :type inc: float or None, optional
   :param obl: Obliquity in radians.
   :type obl: float or None, optional

   :returns: **coords** -- Cartesian coordinates.
   :rtype: ndarray, shape (3,)


.. py:function:: mask_projected_limb(N_or_y, phase=None, inc=None, u=None, obl=None)

   Compute mask, projected area, and limb darkening for visible pixels.

   :param X: Cartesian coordinates of pixels.
   :type X: array_like, shape (..., 3)
   :param phase: Rotation phase in radians.
   :type phase: float, optional
   :param inc: Inclination in radians.
   :type inc: float, optional
   :param u: Limb darkening coefficients.
   :type u: array_like or None, optional
   :param obl: Obliquity in radians.
   :type obl: float, optional

   :returns: * **mask** (*ndarray*) -- Boolean mask for visible pixels.
             * **projected_area** (*ndarray*) -- Projected area for each pixel.
             * **limb_darkening** (*ndarray*) -- Limb darkening factor for each pixel.


.. py:function:: vec(N_or_y)

   Return xyz coordinates for all pixels of a HEALPix map.

   :param N_or_y: HEALPix nside or map.
   :type N_or_y: int or array_like

   :returns: **xyz** -- Cartesian coordinates of pixels.
   :rtype: ndarray, shape (npix, 3)


.. py:function:: design_matrix(N_or_y, phase=None, inc=None, u=None, obl=None, normalize=True)

   Compute the flux design matrix for a HEALPix map.

   :param N_or_y: HEALPix nside or map.
   :type N_or_y: int or array_like
   :param phase: Rotation phase in radians.
   :type phase: float, optional
   :param inc: Inclination in radians.
   :type inc: float, optional
   :param u: Limb darkening coefficients.
   :type u: array_like or None, optional
   :param obl: Obliquity in radians.
   :type obl: float, optional

   :returns: **matrix** -- Design matrix.
   :rtype: ndarray


.. py:function:: flux(y, inc=None, u=None, phase=None, obl=None)

   Compute the flux for a given map and orientation.

   :param y: HEALPix map.
   :type y: array_like
   :param inc: Inclination in radians.
   :type inc: float, optional
   :param u: Limb darkening coefficients.
   :type u: array_like or None, optional
   :param phase: Rotation phase in radians.
   :type phase: float, optional
   :param obl: Obliquity in radians.
   :type obl: float, optional

   :returns: **flux** -- Integrated flux.
   :rtype: float


.. py:function:: spherical_to_cartesian(theta, phi)

   Convert spherical coordinates to cartesian.

   :param theta: Colatitude in radians.
   :type theta: float or array_like
   :param phi: Longitude in radians.
   :type phi: float or array_like

   :returns: **xyz** -- Cartesian coordinates.
   :rtype: ndarray, shape (3,) or (..., 3)


.. py:function:: spot(N, latitude, longitude, radius, sharpness=1000)

   Generate a HEALPix map with a circular spot.

   :param N: HEALPix nside.
   :type N: int
   :param latitude: Latitude of the spot center in radians.
   :type latitude: float
   :param longitude: Longitude of the spot center in radians.
   :type longitude: float
   :param radius: Spot radius in radians.
   :type radius: float
   :param sharpness: Sharpness of the spot edge.
   :type sharpness: float, optional

   :returns: **spot_map** -- HEALPix map with spot.
   :rtype: ndarray


.. py:function:: soft_spot(N, latitude, longitude, radius)

   Generate a HEALPix map with a soft-edged spot.

   :param N: HEALPix nside.
   :type N: int
   :param latitude: Latitude of the spot center in radians.
   :type latitude: float
   :param longitude: Longitude of the spot center in radians.
   :type longitude: float
   :param radius: Spot radius in radians.
   :type radius: float

   :returns: **spot_map** -- HEALPix map with soft-edged spot.
   :rtype: ndarray


.. py:function:: render(y, inc=None, u=None, phase=0.0, obl=0.0, xsize=800, period=None, radius=None)

   Render a HEALPix map as an orthographic projection.

   :param y: HEALPix map.
   :type y: array_like
   :param inc: Inclination in radians.
   :type inc: float, optional
   :param u: Limb darkening coefficients.
   :type u: array_like or None, optional
   :param phase: Rotation phase in radians.
   :type phase: float, optional
   :param obl: Obliquity in radians.
   :type obl: float, optional
   :param xsize: Output image size.
   :type xsize: int, optional

   :returns: **img** -- Rendered image.
   :rtype: ndarray


.. py:function:: amplitude(N_or_y, inc=None, u=None, undersampling: int = 3) -> callable

   Return a function to compute the amplitude of flux variations.

   :param N_or_y: HEALPix nside or map.
   :type N_or_y: int or array_like
   :param inc: Inclination in radians.
   :type inc: float, optional
   :param u: Limb darkening coefficients.
   :type u: array_like or None, optional
   :param undersampling: Undersampling factor for phase grid.
   :type undersampling: int, optional

   :returns: **fun** -- Function that computes amplitude for a given map.
   :rtype: callable


.. py:function:: transit_chord(N, x, r, inc=None)

   Compute mask for a transit chord across the stellar disk.

   :param N: HEALPix nside.
   :type N: int
   :param x: Chord center position.
   :type x: float
   :param r: Chord radius.
   :type r: float
   :param inc: Inclination in radians.
   :type inc: float, optional

   :returns: **mask** -- Boolean mask for pixels inside the chord.
   :rtype: ndarray


.. py:function:: radial_velocity(theta, phi, period, radius, phase, inc=None)

   Compute the radial velocity at each pixel.

   :param theta: Colatitude in radians.
   :type theta: array_like
   :param phi: Longitude in radians.
   :type phi: array_like
   :param period: Rotation period in days.
   :type period: float
   :param radius: Stellar radius in solar radii.
   :type radius: float
   :param phase: Rotation phase in radians.
   :type phase: float
   :param inc: Inclination in radians.
   :type inc: float, optional

   :returns: **rv** -- Radial velocity at each pixel (m/s).
   :rtype: ndarray


.. py:function:: doppler_shift(theta, phi, period, radius, phase, inc=None)

   Compute the Doppler shift at each pixel.

   :param theta: Colatitude in radians.
   :type theta: array_like
   :param phi: Longitude in radians.
   :type phi: array_like
   :param period: Rotation period in days.
   :type period: float
   :param radius: Stellar radius in solar radii.
   :type radius: float
   :param phase: Rotation phase in radians.
   :type phase: float
   :param inc: Inclination in radians.
   :type inc: float, optional

   :returns: **shift** -- Doppler shift at each pixel (fractional).
   :rtype: ndarray


.. py:function:: shifted_spectra(spectra, shift)

   Apply a Doppler shift to spectra.

   :param spectra: Input spectra.
   :type spectra: ndarray, shape (n_pixels, n_wavelength)
   :param shift: Doppler shift for each pixel and wavelength.
   :type shift: ndarray, shape (n_pixels, n_wavelength)

   :returns: **shifted** -- Shifted spectra.
   :rtype: ndarray


.. py:function:: integrated_spectrum(design_matrix, theta, phi, period, radius, wv, spectra, phase, normalize=True)

   Compute the integrated spectrum of a rotating star.

   :param design_matrix: Flux design matrix for a HEALPix map.
   :type design_matrix: array_like
   :param theta: Colatitude in radians.
   :type theta: array_like
   :param phi: Longitude in radians.
   :type phi: array_like
   :param period: Rotation period in days.
   :type period: float
   :param radius: Stellar radius in solar radii.
   :type radius: float
   :param wv: Wavelength grid.
   :type wv: array_like
   :param spectra: Spectra at each pixel.
   :type spectra: ndarray
   :param phase: Rotation phase in radians.
   :type phase: float
   :param inc: Inclination in radians.
   :type inc: float

   :returns: **integrated** -- Integrated spectrum.
   :rtype: ndarray