Class JacobianSerialChain<T>

java.lang.Object
org.ddogleg.chainrule.JacobianSerialChain<T>
All Implemented Interfaces:
VerbosePrint
public class JacobianSerialChain<T> extends Object implements VerbosePrint

Sequential chain of operations for forward and backwards calculations used to compute Jacobians using the chain rule. The first input for all operators is where the output of the previous operator is passed in. All other inputs for an operator must be externally handled. When adding a new operator you then specify where the input came from so that it can be passed into the larger system Jacobian

Usage:

  1. Call
invalid reference 
#setPublishJac
to specify how Jacobians are handled
  1. Call add(CROperatorBackwardsJac) for each operator in the chain in order from first to last
  2. Call in(int, int) after a call to add(CROperatorBackwardsJac) and specify where the input came from
  3. Call chain(int...) for each chain of ops you wish to process
  4. Call backwardsF(int, CRArray) performs the backward pass to get the Jacobian, which invokes forward(int, CRArray, CRArray) internally

Constraints:

Explanation:

  • Operators keep their inputs as state, so reusing one would have the second copy overwrite the first, and the backwards pass would then differentiate the wrong inputs. chain(int...) rejects it

  • Constructor Details

    • JacobianSerialChain

      public JacobianSerialChain(MathCRMatrix<T> math)

  • Method Details

    • add

      public JacobianSerialChain<T> add(CROperatorBackwardsJac<T> op)
      Adds a new operation to the chain and internally creates a block

    • lastBlockId

      public int lastBlockId()
      Returns the ID for the most recently added block

    • inputIdx

      public JacobianSerialChain<T> inputIdx(int idx)
      Used to specify which input should the output from the previous block be passed into. By default, input[0] is used. This allows you to specify input[i]. Modifies the most recently added block.

    • in

      public JacobianSerialChain<T> in(int input, int parameter)
      Specifies if an input is being optimized and where the optimized parameter is stored in the system's parameter vector
      Parameters:
      input - Which input in the array corresponds to this parameter
      parameter - Index in the entire system's parameter vector

    • setInputMap

      public void setInputMap(int blockIdx, int input, int parameter)
      Used to set the input mapping for a block after it was first added

    • setCapture

      public void setCapture(int blockIdx, int input, JacobianSerialChain.CaptureJacobian<T> capture)

      Specifies a custom function for handling a block's Jacobian. This is needed when there are multiple chains that form a graph. I.e. the output of a block in chain A is an input to a block in chain B.

      A capture on the block's chain input is called once at the end of backwards(int). Every other input's capture is called as its own block is differentiated

    • setPreForward

      public void setPreForward(int blockIdx, JacobianSerialChain.PreForward<T> preForward)
      Specifies a block's pre-forward hook. See JacobianSerialChain.Block.preForward

    • chain

      public int chain(int... ids)
      Creates a new chain that can be invoked later on. You pass in IDs for all the blocks you wish to add. It will then check the sequence for consistency and precompute anything that's needed. Returns the ID of the new chain that you will need to call it late ron.
      Parameters:
      ids - Sequence of block IDs.

    • insertInputs

      public void insertInputs(int chainID, T params)
      Helper function that will automatically pass in all mapped inputs
      Parameters:
      chainID - Which chain are you inserting inputs for
      params - Parameters from the system array

    • forward

      public void forward(int chainID, CRArray<T> input, @Nullable @Nullable CRArray<T> output)
      Performs the chain in the forward directly while saving all the intermediate inputs in savedInputs array
      Parameters:
      chainID - Which chain it should run
      input - Initial input that's fed into the first block
      output - Storage for output. If null output will not be computed.

    • backwardsF

      public void backwardsF(int chainID, CRArray<T> input)
      Same as backwards(int), except that it runs a forward pass to get the inputs then runs the backwards pass to compute Jacobians. This makes the pair self-contained when several chains are being driven.

    • backwards

      public void backwards(int chainID)
      Performs backwards pass and computes Jacobians for each operator in the chain. You must call forward(int, CRArray, CRArray) first to get the inputs for each operation.
      Parameters:
      chainID - Which chain it should perform the backwards pass on

    • getOutputSize

      public int getOutputSize(int chainID)
      Size of output vector from the chain

    • blockInputSize

      public int blockInputSize(int chainID, int sequenceIdx)
      Size of first input to the specified block in the chain

    • setVerbose

      public void setVerbose(@Nullable @Nullable PrintStream out, @Nullable @Nullable Set<String> configuration)
      Description copied from interface: VerbosePrint
      If set to a non-null output then extra information will be printed to the specified stream.
      Specified by:
      setVerbose in interface VerbosePrint
      Parameters:
      out - Stream that is printed to. Set to null to disable
      configuration - (Future use) Set which specifies flags that can be used to turn on and off different output