curryer.correction.kernel_ops
=============================

.. py:module:: curryer.correction.kernel_ops

.. autoapi-nested-parse::

   SPICE kernel file management for the correction pipeline.

   This module creates and applies parameter-specific SPICE kernels:

   - :func:`apply_offset` -- modifies telemetry/science data for
     ``OFFSET_KERNEL`` and ``OFFSET_TIME`` parameters.
   - :func:`_create_dynamic_kernels` -- writes SC-SPK/SC-CK kernels from
     telemetry data (once per image pair, not per parameter set).
   - :func:`_create_parameter_kernels` -- writes parameter-specific kernels
     and applies time offsets for each iteration.



Attributes
----------

.. autoapisummary::

   curryer.correction.kernel_ops.logger


Functions
---------

.. autoapisummary::

   curryer.correction.kernel_ops.apply_offset
   curryer.correction.kernel_ops._create_dynamic_kernels
   curryer.correction.kernel_ops._create_parameter_kernels


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

.. py:data:: logger

.. py:function:: apply_offset(config: curryer.correction.config.ParameterConfig, param_data, input_data)

   Apply parameter offsets to input data based on parameter type.

   :param config: ParameterConfig specifying how to apply the offset
   :param param_data: The parameter values to apply (offset amounts)
   :param input_data: The input dataset to modify

   :returns: Modified copy of input_data with parameter offsets applied


.. py:function:: _create_dynamic_kernels(setup: curryer.correction.config.GeolocationSetup, work_dir: pathlib.Path, tlm_dataset: pandas.DataFrame, creator: curryer.kernels.create.KernelCreator) -> list[pathlib.Path]

   Create dynamic SPICE kernels from telemetry data.

   Dynamic kernels (SC-SPK, SC-CK) are generated from spacecraft telemetry
   and do not change with parameter variations. In the current implementation,
   these are created once per image.

   :param setup: Setup with geo settings and dynamic_kernels list
   :type setup: GeolocationSetup
   :param work_dir: Working directory for kernel files
   :type work_dir: Path
   :param tlm_dataset: Spacecraft state data with position, velocity, attitude, and time columns
   :type tlm_dataset: pd.DataFrame
   :param creator: KernelCreator instance for writing kernels
   :type creator: create.KernelCreator

   :returns: List of kernel file paths created (e.g., [sc_ephemeris.bsp, sc_attitude.bc])
   :rtype: list[Path]

   .. rubric:: Examples

   >>> from curryer.kernels import create
   >>> creator = create.KernelCreator(overwrite=True, append=False)
   >>> dynamic_kernels = _create_dynamic_kernels(config, work_dir, tlm_dataset, creator)
   >>> # Use in SPICE context
   >>> with sp.ext.load_kernel(dynamic_kernels):
   ...     # Perform geolocation
   ...     pass


.. py:function:: _create_parameter_kernels(params: list[tuple[curryer.correction.config.ParameterConfig, Any]], work_dir: pathlib.Path, tlm_dataset: pandas.DataFrame, sci_dataset: pandas.DataFrame, ugps_times: Any, setup: curryer.correction.config.GeolocationSetup, creator: curryer.kernels.create.KernelCreator) -> tuple[list[pathlib.Path], Any]

   Create parameter-specific SPICE kernels and apply time offsets.

   This function applies parameter variations by creating modified kernels
   (CONSTANT_KERNEL, OFFSET_KERNEL) or modifying time tags (OFFSET_TIME).
   Each parameter set produces different kernels and/or time modifications.

   :param params: List of (ParameterConfig, parameter_value) tuples for this iteration
   :type params: list[tuple[ParameterConfig, Any]]
   :param work_dir: Working directory for kernel files
   :type work_dir: Path
   :param tlm_dataset: Spacecraft state data (may be modified for OFFSET_KERNEL) with position, velocity, attitude, and time columns
   :type tlm_dataset: pd.DataFrame
   :param sci_dataset: Science frame time data (may be modified for OFFSET_TIME), may include optional measurement columns
   :type sci_dataset: pd.DataFrame
   :param ugps_times: Original time array from science dataset
   :type ugps_times: array-like
   :param setup: Setup with geo settings
   :type setup: GeolocationSetup
   :param creator: KernelCreator instance for writing kernels
   :type creator: create.KernelCreator

   :returns: * **param_kernels** (*list[Path]*) -- List of parameter-specific kernel file paths
             * **ugps_times_modified** (*array-like*) -- Modified time array if OFFSET_TIME applied, otherwise original times

   .. rubric:: Examples

   >>> param_kernels, times = _create_parameter_kernels(
   ...     params, work_dir, tlm_dataset, sci_dataset, ugps_times, setup, creator
   ... )
   >>> # Use in SPICE context with dynamic kernels
   >>> with sp.ext.load_kernel([dynamic_kernels, param_kernels]):
   ...     geo = geolocate(times)