Detailed User Guide
===================

This guide provides a comprehensive breakdown of every component in the ``saltshaker`` package and how they work together to plan SALT observations.

Core Concepts: The Model
------------------------

At the heart of ``saltshaker`` is the **Tracking Model**. Because SALT's fixed-altitude geometry is complex, the package uses empirical data to provide fast, accurate calculations.

SaltTrackingModel (The Singleton)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

The ``SaltTrackingModel`` class contains the raw mathematical logic for SALT's visibility. It is implemented as a **Singleton**, meaning the large visibility data file is only loaded once per session.

*   **When to use it:** You rarely need to interact with this class directly. The ``SaltObserver`` and planning functions handle it for you.
*   **Key Logic:** It differentiates between **East Tracks** (target rising) and **West Tracks** (target setting).

The Observer: SaltObserver
--------------------------

The ``SaltObserver`` class is your primary entry point for Object-Oriented planning. It extends the standard ``astroplan.Observer`` class.

*   **Initialization:** When you create a ``SaltObserver``, it is automatically configured with SALT's precise latitude, longitude, and elevation.
*   **Integration:** Because it inherits from ``astroplan``, you can use it with any standard ``astroplan`` function (like calculating twilight, airmass, or moon position).

Planning Functions: The Functional API
--------------------------------------

For users who prefer a functional style or are building automated scripts, ``saltshaker`` provides high-level functions that don't require managing an observer object.

Visibility Windows
~~~~~~~~~~~~~~~~~~

*   **Function:** ``get_visibility_windows(target, date)``
*   **Returns:** A list of ``VisibilityWindow`` objects.
*   **What it does:** It tells you exactly when (in UTC) a target will enter and exit SALT's visibility annulus on a specific night. It automatically clips these windows to the 24-hour period starting at noon UTC.

Track Lengths
~~~~~~~~~~~~~

*   **Function:** ``get_track_length(target, time)``
*   **Returns:** An Astropy Quantity (seconds).
*   **What it does:** This is the most critical function for feasibility. It tells you how many seconds of tracking are remaining *at a specific moment*. If this is 0, the target is not currently visible.

Rapid Screening
~~~~~~~~~~~~~~~

*   **Function:** ``is_target_observable(target)``
*   **Returns:** Boolean (True/False).
*   **What it does:** A "quick-look" function. It checks if a target's declination is within SALT's reachable range (-75° to +10°). Use this to filter large catalogs before doing detailed time-consuming calculations.

Scheduling: astroplan Constraints
---------------------------------

``saltshaker`` provides two custom constraints that plug directly into the ``astroplan`` scheduling system.

SaltTrackLengthConstraint
~~~~~~~~~~~~~~~~~~~~~~~~~

*   **Purpose:** Ensures your exposure won't be "cut off" by the tracker limit.
*   **Example:** If you set ``min_track_length=1200*u.second``, ``astroplan`` will only mark a time as "observable" if the telescope can track the target for at least 20 continuous minutes from that start time.

SaltMoonConstraint
~~~~~~~~~~~~~~~~~~

*   **Purpose:** Enforces lunar phase requirements.
*   **Unique Logic:** This constraint is satisfied if the Moon's illumination is below your limit **OR** if the Moon is currently below the horizon. This is more accurate for SALT proposals than a simple illumination check.

Semester Management
-------------------

SALT's operations are divided into two semesters. These utilities help with long-term project planning.

*   **``get_semester_start`` / ``get_semester_end``**: Returns the exact ``Time`` objects for the start and end of a given SALT semester.
*   **``get_semester_nights``**: A powerful generator that returns a list of every single night in a semester. Each night is provided as a tuple of ``(evening_astronomical_twilight, morning_astronomical_twilight)``.