SatelliteClockScale.java

/* Copyright 2002-2025 CS GROUP
 * Licensed to CS GROUP (CS) under one or more
 * contributor license agreements.  See the NOTICE file distributed with
 * this work for additional information regarding copyright ownership.
 * CS licenses this file to You under the Apache License, Version 2.0
 * (the "License"); you may not use this file except in compliance with
 * the License.  You may obtain a copy of the License at
 *
 *   http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */
package org.orekit.time;

import org.hipparchus.CalculusFieldElement;

/** Scale for on-board clock.
 * @author Luc Maisonobe
 * @since 11.0
 */
public class SatelliteClockScale implements TimeScale {

    /** Name of the scale. */
    private final String name;

    /** Reference epoch. */
    private final AbsoluteDate epoch;

    /** Reference epoch. */
    private final DateTimeComponents epochDT;

    /** Offset from TAI at epoch. */
    private final TimeOffset offsetAtEpoch;

    /** Clock count at epoch. */
    private final double countAtEpoch;

    /** Clock drift (i.e. clock count per SI second minus 1.0). */
    private final double drift;

    /** Clock rate. */
    private final double rate;

    /** Create a linear model for satellite clock.
     * <p>
     * Beware that we specify the model using its drift with respect to
     * flow of time. For a perfect clock without any drift, the clock
     * count would be one tick every SI second. A clock that is fast, say
     * for example it generates 1000001 ticks every 1000000 SI second, would
     * have a rate of 1.000001 tick per SI second and hence a drift of
     * 1.0e-6 tick per SI second. In this constructor we use the drift
     * (1.0e-6 in the previous example) rather than the rate (1.000001
     * in the previous example) to specify the clock. The rationale is
     * that for clocks that are intended to be used for representing absolute
     * time, the drift is expected to be small (much smaller that 1.0e-6
     * for a good clock), so using drift is numerically more stable than
     * using rate and risking catastrophic cancellation when subtracting
     * 1.0 in the internal computation.
     * </p>
     * <p>
     * Despite what is explained in the previous paragraph, this class can
     * handle spacecraft clocks that are not intended to be synchronized with
     * SI seconds, for example clocks that ticks at 10 Hz. In such cases the
     * drift would need to be set at 10.0 - 1.0 = 9.0, which is not intuitive.
     * For these clocks, the methods {@link #countAtDate(AbsoluteDate)} and
     * {@link #dateAtCount(double)} and perhaps {@link #offsetFromTAI(AbsoluteDate)}
     * are still useful, whereas {@link #offsetToTAI(DateComponents, TimeComponents)}
     * is probably not really meaningful.
     * </p>
     * @param name of the scale
     * @param epoch reference epoch
     * @param epochScale time scale in which the {@code epoch} was defined
     * @param countAtEpoch clock count at {@code epoch}
     * @param drift clock drift rate (i.e. clock count change per SI second minus 1.0)
     */
    public SatelliteClockScale(final String name,
                               final AbsoluteDate epoch, final TimeScale epochScale,
                               final double countAtEpoch, final double drift) {
        this.name          = name;
        this.epoch         = epoch;
        this.epochDT       = epoch.getComponents(epochScale);
        this.offsetAtEpoch = epochScale.offsetFromTAI(epoch).add(new TimeOffset(countAtEpoch));
        this.countAtEpoch  = countAtEpoch;
        this.drift         = drift;
        this.rate          = 1.0 + drift;
    }

    /** {@inheritDoc} */
    @Override
    public TimeOffset offsetFromTAI(final AbsoluteDate date) {
        return offsetAtEpoch.add(new TimeOffset(drift * date.durationFrom(epoch)));
    }

    /** {@inheritDoc} */
    @Override
    public TimeOffset offsetToTAI(final DateComponents date, final TimeComponents time) {
        final long      deltaDate      = (date.getJ2000Day() - epochDT.getDate().getJ2000Day()) *
                                         TimeOffset.DAY.getSeconds();
        final TimeOffset deltaTime      = time.getSplitSecondsInUTCDay().
                                         subtract(epochDT.getTime().getSplitSecondsInUTCDay());
        final double    delta          = deltaDate + deltaTime.toDouble();
        final double    timeSinceEpoch = (delta - countAtEpoch) / rate;
        return offsetAtEpoch.add(new TimeOffset(drift * timeSinceEpoch)).negate();
    }

    /** Compute date corresponding to some clock count.
     * @param count clock count
     * @return date at {@code count}
     */
    public AbsoluteDate dateAtCount(final double count) {
        return epoch.shiftedBy((count - countAtEpoch) / rate);
    }

    /** Compute clock count corresponding to some date.
     * @param date date
     * @return clock count at {@code date}
     */
    public double countAtDate(final AbsoluteDate date) {
        return countAtEpoch + rate * date.durationFrom(epoch);
    }

    /** {@inheritDoc} */
    @Override
    public <T extends CalculusFieldElement<T>> T offsetFromTAI(final FieldAbsoluteDate<T> date) {
        return date.durationFrom(epoch).multiply(drift).add(offsetAtEpoch.toDouble());
    }

    /** {@inheritDoc} */
    public String getName() {
        return name;
    }

    /** {@inheritDoc} */
    public String toString() {
        return getName();
    }

}