commons-rng-core/src/main/java/org/apache/commons/rng/core/source64/AbstractL128.java

/*
 * Licensed to the Apache Software Foundation (ASF) under one or more
 * contributor license agreements.  See the NOTICE file distributed with
 * this work for additional information regarding copyright ownership.
 * The ASF 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.apache.commons.rng.core.source64;

import org.apache.commons.rng.JumpableUniformRandomProvider;
import org.apache.commons.rng.LongJumpableUniformRandomProvider;
import org.apache.commons.rng.UniformRandomProvider;
import org.apache.commons.rng.core.util.NumberFactory;

/**
 * This abstract class is a base for algorithms from the LXM family of
 * generators with a 128-bit LCG sub-generator. The class implements
 * the jump functions.
 *
 * @since 1.5
 */
abstract class AbstractL128 extends LongProvider implements LongJumpableUniformRandomProvider {
    /** Size of the seed vector. */
    private static final int SEED_SIZE = 4;
    /** Low half of 128-bit LCG multiplier. */
    private static final long ML = LXMSupport.M128L;

    /** High half of the 128-bit per-instance LCG additive parameter.
     * Cannot be final to support RestorableUniformRandomProvider. */
    protected long lah;
    /** Low half of the 128-bit per-instance LCG additive parameter (must be odd).
     * Cannot be final to support RestorableUniformRandomProvider. */
    protected long lal;
    /** High half of the 128-bit state of the LCG generator. */
    protected long lsh;
    /** Low half of the 128-bit state of the LCG generator. */
    protected long lsl;

    /**
     * Creates a new instance.
     *
     * @param seed Initial seed.
     * If the length is larger than 4, only the first 4 elements will
     * be used; if smaller, the remaining elements will be automatically
     * set.
     *
     * <p>The 1st and 2nd elements are used to set the LCG increment; the least significant bit
     * is set to odd to ensure a full period LCG. The 3rd and 4th elements are used
     * to set the LCG state.</p>
     */
    AbstractL128(long[] seed) {
        setState(extendSeed(seed, SEED_SIZE));
    }

    /**
     * Creates a new instance using a 4 element seed.
     *
     * <p>The 1st and 2nd elements are used to set the LCG increment; the least significant bit
     * is set to odd to ensure a full period LCG. The 3rd and 4th elements are used
     * to set the LCG state.</p>
     *
     * @param seed0 Initial seed element 0.
     * @param seed1 Initial seed element 1.
     * @param seed2 Initial seed element 2.
     * @param seed3 Initial seed element 3.
     */
    AbstractL128(long seed0, long seed1, long seed2, long seed3) {
        lah = seed0;
        // Additive parameter must be odd
        lal = seed1 | 1;
        lsh = seed2;
        lsl = seed3;
    }

    /**
     * Creates a copy instance.
     *
     * @param source Source to copy.
     */
    AbstractL128(AbstractL128 source) {
        super(source);
        lah = source.lah;
        lal = source.lal;
        lsh = source.lsh;
        lsl = source.lsl;
    }

    /**
     * Copies the state into the generator state.
     *
     * @param state the new state
     */
    private void setState(long[] state) {
        lah = state[0];
        // Additive parameter must be odd
        lal = state[1] | 1;
        lsh = state[2];
        lsl = state[3];
    }

    /** {@inheritDoc} */
    @Override
    protected byte[] getStateInternal() {
        return composeStateInternal(NumberFactory.makeByteArray(
                                        new long[] {lah, lal, lsh, lsl}),
                                    super.getStateInternal());
    }

    /** {@inheritDoc} */
    @Override
    protected void setStateInternal(byte[] s) {
        final byte[][] c = splitStateInternal(s, SEED_SIZE * Long.BYTES);
        setState(NumberFactory.makeLongArray(c[0]));
        super.setStateInternal(c[1]);
    }

    /**
     * Creates a copy of the UniformRandomProvider and then <em>retreats</em> the state of the
     * current instance. The copy is returned.
     *
     * <p>The jump is performed by advancing the state of the LCG sub-generator by 1 cycle.
     * The XBG state is unchanged.
     */
    @Override
    public UniformRandomProvider jump() {
        final UniformRandomProvider copy = copy();
        // Advance the LCG 1 step.
        // The LCG is, in effect, "s = m * s + a" where m = ((1LL << 64) + ML)
        final long sh = lsh;
        final long sl = lsl;
        final long u = ML * sl;
        // High half
        lsh = ML * sh + LXMSupport.unsignedMultiplyHigh(ML, sl) + sl + lah +
              // Carry propagation
              LXMSupport.unsignedAddHigh(u, lal);
        // Low half
        lsl = u + lal;
        resetCachedState();
        return copy;
    }

    /**
     * Creates a copy of the UniformRandomProvider and then <em>retreats</em> the state of the
     * current instance. The copy is returned.
     *
     * <p>The jump is performed by advancing the state of the LCG sub-generator by
     * 2<sup>64</sup> cycles. The XBG state is unchanged.
     */
    @Override
    public JumpableUniformRandomProvider longJump() {
        final JumpableUniformRandomProvider copy = copy();
        // Advance the LCG 2^64 steps
        // s = m' * s + c' * c
        // Specialised routine given M128PL=1, C128PL=0 and many terms
        // can be dropped as the low half is unchanged and there is no carry
        // sh = m'l * sh         // sh
        //    + high(m'l * sl)   // dropped as m'l=1 and there is no high part
        //    + m'h * sl
        //    + c'l * ah         // dropped as c'l=0
        //    + high(c'l * ah)   // dropped as c'l=0
        //    + c'h * al
        // sl = m'l * sl + c'l * al
        //    = sl
        lsh = lsh + LXMSupport.M128PH * lsl + LXMSupport.C128PH * lal;
        resetCachedState();
        return copy;
    }

    /**
     * Create a copy.
     *
     * @return the copy
     */
    abstract AbstractL128 copy();
}