Class Exclusive

java.lang.Object
java.util.Observable
ca.spatial.patchworks.Exclusive
All Implemented Interfaces:
Account, Target, Comparable<Account>

public class Exclusive extends Observable
The Exclusive class is an account type that provides an 'xor' type of relationship. Values added to this account will be added to one (and only one) sub account.

A typical use for this account is to divert harvest volume to a single destination, from a choice of multiple destinations.

Add the sub-accounts using the addAccount(Account) method.

  • Field Summary

    Fields inherited from interface ca.spatial.patchworks.Account

    DEFAULT_FACTOR, DEFAULT_SCALE
  • Method Summary

    Modifier and Type
    Method
    Description
    void
    accept​(ca.spatial.patchworks.AccountVisitor visitor, Object[] args)
    Implement the visitor pattern on the account structure
    void
    add​(Complex complex, long[][] values, double[] factors, int index)
    Add a set of values, one per period
    void
    add​(Complex complex, long[] value, double factor, int period, int index)
    Add a value to a specific period.
    void
    addCache​(Complex complex, long[][] values, double[] factors, int index)
    Add a set of values, one per period to the cache accounts.
    void
    addDuplicate​(Account account, double factor)
    Set up a relationship so that the value from this account will be duplicated into the other account.
    void
    addDuplicate​(Account account, double[] factors)
    Set up a relationship so that the value from this account will be duplicated into the other account.
    static String
    Return an HTML string showing the settings for the minimum and maximum settings for this target.
    findAccount​(String label)
    Find if this account matches the specified name, or if it contains a sub-account that matches that name.
    float
    getCurrent​(int period)
    Get the current value of the target for the specified period.
    getDescription​(ca.spatial.patchworks.Forest forest, Vector<Vector<Object>> outputs)
    Get a description of this account that can be used in the AccountExplorer.
    float
    getDiscount​(int period)
    Get the discounting value that applies to a specific period
    float
    Retrieve the discount rate that is being applied to this target.
    boolean
    Check if costs are calculated in period zero for this account
    ca.spatial.patchworks.DuplicateAccount
    getDuplicate​(int i)
    Return a duplicate account.
    int
    Determine the number of duplicate accounts
    int
    Get the index number of the account.
    double
    getInitial​(int period)
    Get the initial target value in the specified period
    float
    getInterval​(int period)
    Get the width of the specified period
    Get the name of the target
    float
    getMarginalCost​(int period)
    Compute the marginal cost of a change in one unit.
    float
    getMaximum​(int period)
    Get the maximum target value in the specified period
    float
    getMaxWeight​(int period)
    Get the weighting factor on targets above the maximum for the specified period.
    float
    getMinimum​(int period)
    Get the minimum target value in the specified period
    float
    getMinWeight​(int period)
    Get the weighting factor on targets below the minimum for the specified period.
    double
    Get the contribution of this target towards the objective function value.
    double
    getObjectiveValue​(int period)
    Get the contribution of this target towards the objective function value in the specified period.
    getOption​(int k)
    Return the specified sub-account.
    getOption​(String label)
     
    int
    Return the number of sub-accounts
    int
    Get the number of periods for this target
    boolean
    Obtain the current setting for non-linear scaling penalty calculation.
    double
    getShortage​(int period)
    Get the shortage between the target and the current value.
    float
    getSummary​(int period)
    Get the normalizing value for the specified period.
    Get the type of the account
    boolean
    Is the target actively contributing to the objective function?
    boolean
    Report if this account is an account that does not depend on any inputs
    boolean
    Determine if this target is using linear or quadratic scaling.
    boolean
    isLock​(int index, int period)
     
    boolean
    Is the maximum value actively contributing to the objective function?
    boolean
    Is the minimum value actively contributing to the objective function?
    boolean
    Has the account been resolved during the initialization process?
    boolean
    Is the target in summary mode.
    void
    listInputs​(Account account, Vector<Vector<Object>> inputs)
    Test to see if the account contributes to the specified account.
    void
    Load the exclusive account assigments from a file.
    void
    Load the exclusive account locks from a file.
    static void
    minimalTargetDef​(Target t, String prefix, int type, Appendable out)
    write commands to an object that can be used to initialize the target to its current settings.
    void
    minimumCost​(float[] costs)
    Return the minimum value of any sub-account
    float
    minimumCost​(int index)
    Estimate the cost of the block at this index.
    void
    Print debugging information
    void
    recordLinks​(ca.spatial.patchworks.AccountsToDot recorder)
    A method to record all of the accounts that are linked from this account.
    void
    reset​(boolean init)
    Set the account back to an inital state
    resolve​(HashMap<String,​Account> accounts, HashMap<String,​Target> targets, float[] intervals, double scale, List<Account> stack)
    Resolve references between accounts.
    void
    Save the exclusive account assigments out to a file.
    void
    Save the exclusive account locks out to a file.
    void
    setActive​(boolean value)
    Set the active status of the target.
    void
    setDiscountRate​(float rate)
    Set a discount rate on this target.
    void
    setDoZeroCosts​(boolean state)
    Indicate if costs should be computed in period zero.
    void
    setIndependent​(boolean state)
    Set the dependent status of this account.
    void
    setInitial​(double value, int period)
     
    void
    setLinear​(boolean value)
    Set the type of weighting to be used to linear (true) or quadratic (false).
    void
    setLock​(int period, boolean value)
     
    void
    setLock​(int index, int period, boolean value)
     
    void
    setMaxActive​(boolean value)
    Set the active status of the maximum value.
    void
    setMaximum​(float value, int period)
    Set the maximum target value in a specific period
    void
    setMaximum​(Curve curve)
    Set all maximum target values using the shape of the curve
    void
    setMaxWeight​(float value, int period)
    Set the weighting factor on targets above the maximum for the specified period to the given value.
    void
    setMaxWeight​(Curve curve)
    Set all the weighting factors on targets above the maximum using curve interpolation.
    void
    setMinActive​(boolean value)
    Set the active status of the minimum value.
    void
    setMinimum​(float value, int period)
    Set the minimum target value in a specific period
    void
    setMinimum​(Curve curve)
    Set all minimum target values using the shape of the curve
    void
    setMinWeight​(float value, int period)
    Set the weighting factor on targets below the minimum for the specified period to the given value.
    void
    setMinWeight​(Curve curve)
    Set all the weighting factors on targets below the minimum using curve interpolation.
    void
    setPreMultiply​(boolean state)
    This variable controls the order of operation for computing the penalty value for non-linear scaling.
    void
    setSumActive​(boolean value)
    Set the display mode to normal (false) or summary (true).
    void
    setSummary​(float value)
     
    void
    setSummary​(float value, int period)
    Set the normalizing value for the specified period.
    void
    setSummary​(Curve curve)
    Set the normalizing value for all periods using curve interpolation.
    void
    sub​(Complex complex, long[][] values, double[] factors, int index)
    Subtract a set of values, one per period
    void
    sub​(Complex complex, long[] value, double factor, int period, int index)
    Subtract a value from a specific period
    void
    subCache​(Complex complex, long[][] values, double[] factors, int index)
    Subtract a set of values, one per period to the cache accounts.
     
    boolean
    validForBlock​(int source)
    This account is valid if the accounts that connect to it are valid and if any of the sub accounts are valid.

    Methods inherited from class java.lang.Object

    equals, getClass, hashCode, notify, notifyAll, wait, wait, wait

    Methods inherited from interface ca.spatial.patchworks.Account

    compareTo

    Methods inherited from interface ca.spatial.patchworks.Target

    addObserver, deleteObserver
  • Method Details

    • getType

      public String getType()
      Description copied from interface: Account
      Get the type of the account
      Specified by:
      getType in interface Account
    • validForBlock

      public boolean validForBlock(int source)
      This account is valid if the accounts that connect to it are valid and if any of the sub accounts are valid.
      Specified by:
      validForBlock in interface Account
    • minimumCost

      public void minimumCost(float[] costs)
      Return the minimum value of any sub-account
      Specified by:
      minimumCost in interface Account
    • minimumCost

      public float minimumCost(int index)
      Description copied from interface: Account
      Estimate the cost of the block at this index. This will return a constant for plain accounts, and a rough estimate of the haul cost value for route accounts. This value is useful to assess the least cost alternative in an exclusive account.
      Specified by:
      minimumCost in interface Account
    • getOptionCount

      public int getOptionCount()
      Return the number of sub-accounts
    • getOption

      public Account getOption(int k)
      Return the specified sub-account.
    • getOption

      public Account getOption(String label)
    • isLock

      public boolean isLock(int index, int period)
    • setLock

      public void setLock(int index, int period, boolean value)
    • setLock

      public void setLock(int period, boolean value)
    • findAccount

      public Account findAccount(String label)
      Description copied from interface: Account
      Find if this account matches the specified name, or if it contains a sub-account that matches that name.
      Specified by:
      findAccount in interface Account
    • add

      public void add(Complex complex, long[] value, double factor, int period, int index)
      Description copied from interface: Account
      Add a value to a specific period.
      Specified by:
      add in interface Account
      Parameters:
      complex - An high-resolution accumulator object that will track the amount that was added in this operation.
      value - The array of values to add, one for each period.
      factor - the scaling factor for this period
      period - the planning period of interest
      index - The internal block id of the feature that is changing
    • add

      public void add(Complex complex, long[][] values, double[] factors, int index)
      Description copied from interface: Account
      Add a set of values, one per period
      Specified by:
      add in interface Account
      Parameters:
      complex - An high-resolution accumulator object that will track the amount that was added in this operation.
      values - The array of values to add, one for each period.
      factors - the scaling factor for this period
      index - The internal block id of the feature that is changing
    • sub

      public void sub(Complex complex, long[] value, double factor, int period, int index)
      Description copied from interface: Account
      Subtract a value from a specific period
      Specified by:
      sub in interface Account
      Parameters:
      complex - An high-resolution accumulator object that will track the amount that was added in this operation.
      value - The array of values to add, one for each period.
      factor - the scaling factor for this period
      period - the planning period of interest
      index - The internal block id of the feature that is changing
    • sub

      public void sub(Complex complex, long[][] values, double[] factors, int index)
      Description copied from interface: Account
      Subtract a set of values, one per period
      Specified by:
      sub in interface Account
      Parameters:
      complex - An high-resolution accumulator object that will track the amount that was added in this operation.
      values - The array of values to add, one for each period.
      factors - the scaling factor for this period
      index - The internal block id of the feature that is changing
    • resolve

      public Account resolve(HashMap<String,​Account> accounts, HashMap<String,​Target> targets, float[] intervals, double scale, List<Account> stack)
      Description copied from interface: Account
      Resolve references between accounts. This method is called when the account structure is being set up in order to link dependent accounts.
      Specified by:
      resolve in interface Account
    • accept

      public void accept(ca.spatial.patchworks.AccountVisitor visitor, Object[] args)
      Description copied from interface: Account
      Implement the visitor pattern on the account structure
      Specified by:
      accept in interface Account
    • recordLinks

      public void recordLinks(ca.spatial.patchworks.AccountsToDot recorder)
      Description copied from interface: Account
      A method to record all of the accounts that are linked from this account.
      Specified by:
      recordLinks in interface Account
    • reset

      public void reset(boolean init)
      Description copied from interface: Account
      Set the account back to an inital state
      Specified by:
      reset in interface Account
    • saveAssignments

      public void saveAssignments(PrintStream out)
      Save the exclusive account assigments out to a file.
    • loadAssignments

      public void loadAssignments(TableReader in) throws Exception
      Load the exclusive account assigments from a file.
      Throws:
      Exception
    • saveLocks

      public void saveLocks(PrintStream out)
      Save the exclusive account locks out to a file.
    • loadLocks

      public void loadLocks(TableReader in) throws Exception
      Load the exclusive account locks from a file.
      Throws:
      Exception
    • print

      public void print(PrintStream pw)
      Description copied from interface: Account
      Print debugging information
      Specified by:
      print in interface Account
    • listInputs

      public void listInputs(Account account, Vector<Vector<Object>> inputs)
      Description copied from interface: Account
      Test to see if the account contributes to the specified account. If yes, then add information about the relationship to the vector.
      Specified by:
      listInputs in interface Account
      Parameters:
      account - The account that we are testing.
      inputs - The vector to add information into if this account contributes to the account we are testing for.
    • getDescription

      public String getDescription(ca.spatial.patchworks.Forest forest, Vector<Vector<Object>> outputs)
      Description copied from interface: Account
      Get a description of this account that can be used in the AccountExplorer.
      Specified by:
      getDescription in interface Account
    • getLabel

      public String getLabel()
      Description copied from interface: Target
      Get the name of the target
      Specified by:
      getLabel in interface Account
      Specified by:
      getLabel in interface Target
    • getIndex

      public int getIndex()
      Description copied from interface: Account
      Get the index number of the account. This is a sequence number that used internally by the accounting mechanism.
      Specified by:
      getIndex in interface Account
    • getPeriods

      public int getPeriods()
      Description copied from interface: Target
      Get the number of periods for this target
      Specified by:
      getPeriods in interface Target
    • addCache

      public void addCache(Complex complex, long[][] values, double[] factors, int index)
      Description copied from interface: Account
      Add a set of values, one per period to the cache accounts.
      Specified by:
      addCache in interface Account
      Parameters:
      complex - An high-resolution accumulator object that will track the amount that was added in this operation.
      values - The array of values to add, one for each period.
      factors - the scaling factor for this period
      index - The internal block id of the feature that is changing
    • subCache

      public void subCache(Complex complex, long[][] values, double[] factors, int index)
      Description copied from interface: Account
      Subtract a set of values, one per period to the cache accounts.
      Specified by:
      subCache in interface Account
      Parameters:
      complex - An high-resolution accumulator object that will track the amount that was added in this operation.
      values - The array of values to add, one for each period.
      factors - the scaling factor for this period
      index - The internal block id of the feature that is changing
    • getObjectiveValue

      public double getObjectiveValue()
      Description copied from interface: Target
      Get the contribution of this target towards the objective function value.
      Specified by:
      getObjectiveValue in interface Target
    • getObjectiveValue

      public double getObjectiveValue(int period)
      Description copied from interface: Target
      Get the contribution of this target towards the objective function value in the specified period.
      Specified by:
      getObjectiveValue in interface Target
    • getShortage

      public double getShortage(int period)
      Description copied from interface: Target
      Get the shortage between the target and the current value. If the target is a upper limit, then the excess will be reported as a negative number.
      Specified by:
      getShortage in interface Target
    • getMarginalCost

      public final float getMarginalCost(int period)
      Compute the marginal cost of a change in one unit.
      Specified by:
      getMarginalCost in interface Target
    • isActive

      public boolean isActive()
      Description copied from interface: Target
      Is the target actively contributing to the objective function?
      Specified by:
      isActive in interface Target
    • setActive

      public void setActive(boolean value)
      Description copied from interface: Target
      Set the active status of the target. If true then the target contributes to the objective function. If false then the value are being tracked, but not used by the solver to control the solution.
      Specified by:
      setActive in interface Target
    • isMinActive

      public boolean isMinActive()
      Description copied from interface: Target
      Is the minimum value actively contributing to the objective function?
      Specified by:
      isMinActive in interface Target
    • setMinActive

      public void setMinActive(boolean value)
      Description copied from interface: Target
      Set the active status of the minimum value. If true then the values below the minimum value will contribute to the objective function.
      Specified by:
      setMinActive in interface Target
    • isMaxActive

      public boolean isMaxActive()
      Description copied from interface: Target
      Is the maximum value actively contributing to the objective function?
      Specified by:
      isMaxActive in interface Target
    • setMaxActive

      public void setMaxActive(boolean value)
      Description copied from interface: Target
      Set the active status of the maximum value. If true then the values above the maximum value will contribute to the objective function.
      Specified by:
      setMaxActive in interface Target
    • isSumActive

      public boolean isSumActive()
      Description copied from interface: Target
      Is the target in summary mode. Summary mode will cause the values to be display in chart format as a percentage of the summary value.
      Specified by:
      isSumActive in interface Target
    • setSumActive

      public void setSumActive(boolean value)
      Description copied from interface: Target
      Set the display mode to normal (false) or summary (true). In summary mode the target values will be normalized by the summary values.
      Specified by:
      setSumActive in interface Target
    • getCurrent

      public float getCurrent(int period)
      Description copied from interface: Target
      Get the current value of the target for the specified period.
      Specified by:
      getCurrent in interface Target
    • getInterval

      public float getInterval(int period)
      Description copied from interface: Target
      Get the width of the specified period
      Specified by:
      getInterval in interface Target
    • getInitial

      public double getInitial(int period)
      Description copied from interface: Target
      Get the initial target value in the specified period
      Specified by:
      getInitial in interface Account
      Specified by:
      getInitial in interface Target
    • setInitial

      public void setInitial(double value, int period)
      Specified by:
      setInitial in interface Account
    • getMinimum

      public float getMinimum(int period)
      Description copied from interface: Target
      Get the minimum target value in the specified period
      Specified by:
      getMinimum in interface Target
    • setMinimum

      public void setMinimum(Curve curve)
      Description copied from interface: Target
      Set all minimum target values using the shape of the curve
      Specified by:
      setMinimum in interface Target
    • setMinimum

      public void setMinimum(float value, int period)
      Description copied from interface: Target
      Set the minimum target value in a specific period
      Specified by:
      setMinimum in interface Target
    • getMaximum

      public float getMaximum(int period)
      Description copied from interface: Target
      Get the maximum target value in the specified period
      Specified by:
      getMaximum in interface Target
    • setMaximum

      public void setMaximum(Curve curve)
      Description copied from interface: Target
      Set all maximum target values using the shape of the curve
      Specified by:
      setMaximum in interface Target
    • setMaximum

      public void setMaximum(float value, int period)
      Description copied from interface: Target
      Set the maximum target value in a specific period
      Specified by:
      setMaximum in interface Target
    • getSummary

      public float getSummary(int period)
      Description copied from interface: Target
      Get the normalizing value for the specified period.
      Specified by:
      getSummary in interface Target
    • setSummary

      public void setSummary(Curve curve)
      Description copied from interface: Target
      Set the normalizing value for all periods using curve interpolation.
      Specified by:
      setSummary in interface Target
    • setSummary

      public void setSummary(float value)
    • setSummary

      public void setSummary(float value, int period)
      Description copied from interface: Target
      Set the normalizing value for the specified period.
      Specified by:
      setSummary in interface Target
    • getDiscount

      public float getDiscount(int period)
      Description copied from interface: Target
      Get the discounting value that applies to a specific period
      Specified by:
      getDiscount in interface Target
    • getDiscountRate

      public float getDiscountRate()
      Retrieve the discount rate that is being applied to this target.
      Specified by:
      getDiscountRate in interface Target
    • setDiscountRate

      public void setDiscountRate(float rate)
      Set a discount rate on this target. The rate is expressed as a value such as 1.04 for a 4% discounting.

      The discount rate is applied to cost calculations along with the weighting factor. Over long time horizons the dicount rate will outweigh the weighting factor.

      The discount value will be calculated at the middle of the period.

      Specified by:
      setDiscountRate in interface Target
    • getMinWeight

      public float getMinWeight(int period)
      Description copied from interface: Target
      Get the weighting factor on targets below the minimum for the specified period.
      Specified by:
      getMinWeight in interface Target
    • setMinWeight

      public void setMinWeight(Curve curve)
      Description copied from interface: Target
      Set all the weighting factors on targets below the minimum using curve interpolation.
      Specified by:
      setMinWeight in interface Target
    • setMinWeight

      public void setMinWeight(float value, int period)
      Description copied from interface: Target
      Set the weighting factor on targets below the minimum for the specified period to the given value.
      Specified by:
      setMinWeight in interface Target
    • getMaxWeight

      public float getMaxWeight(int period)
      Description copied from interface: Target
      Get the weighting factor on targets above the maximum for the specified period.
      Specified by:
      getMaxWeight in interface Target
    • setMaxWeight

      public void setMaxWeight(Curve curve)
      Description copied from interface: Target
      Set all the weighting factors on targets above the maximum using curve interpolation.
      Specified by:
      setMaxWeight in interface Target
    • setMaxWeight

      public void setMaxWeight(float value, int period)
      Description copied from interface: Target
      Set the weighting factor on targets above the maximum for the specified period to the given value.
      Specified by:
      setMaxWeight in interface Target
    • setLinear

      public void setLinear(boolean value)
      Description copied from interface: Target
      Set the type of weighting to be used to linear (true) or quadratic (false).
      Specified by:
      setLinear in interface Target
    • isLinear

      public boolean isLinear()
      Description copied from interface: Target
      Determine if this target is using linear or quadratic scaling.
      Specified by:
      isLinear in interface Target
    • setPreMultiply

      public void setPreMultiply(boolean state)
      Description copied from interface: Target
      This variable controls the order of operation for computing the penalty value for non-linear scaling. If true, then the penalty value is computed by mulitplying the weight times the delta, and then squaring. If false, then square before multiplying. This only effects non-linear scaling. The order does not change the result in linear scaling.

      The default value is false, which is the original Patchworks behaviour.

      Specified by:
      setPreMultiply in interface Target
    • getPreMultiply

      public boolean getPreMultiply()
      Description copied from interface: Target
      Obtain the current setting for non-linear scaling penalty calculation. See the Target.setPreMultiply(boolean) method description for details.
      Specified by:
      getPreMultiply in interface Target
    • setDoZeroCosts

      public void setDoZeroCosts(boolean state)
      Description copied from interface: Account
      Indicate if costs should be computed in period zero. In most cases the answer is no because values are invariant in period zero so they to not influence the objective function. Route costs are always an exception because routes can be changed in this time period. Period zero values can be manipulated when attributes are distributed to period zero.

      This method will toggle the associated TargetChart so that it will show values in period zero.

      Specified by:
      setDoZeroCosts in interface Account
    • getDoZeroCosts

      public boolean getDoZeroCosts()
      Description copied from interface: Account
      Check if costs are calculated in period zero for this account
      Specified by:
      getDoZeroCosts in interface Account
    • isResolved

      public boolean isResolved()
      Description copied from interface: Account
      Has the account been resolved during the initialization process?
      Specified by:
      isResolved in interface Account
    • setIndependent

      public void setIndependent(boolean state)
      Description copied from interface: Account
      Set the dependent status of this account. This can only be done prior to resolving. Accounts that are created without attributes are automatically marked as independent.
      Specified by:
      setIndependent in interface Account
    • isIndependent

      public boolean isIndependent()
      Description copied from interface: Account
      Report if this account is an account that does not depend on any inputs
      Specified by:
      isIndependent in interface Account
    • addDuplicate

      public void addDuplicate(Account account, double factor)
      Description copied from interface: Account
      Set up a relationship so that the value from this account will be duplicated into the other account.
      Specified by:
      addDuplicate in interface Account
      Parameters:
      account - The account to receive the duplicated values.
      factor - A scaling factor to be applied to the duplicated account.
    • addDuplicate

      public void addDuplicate(Account account, double[] factors)
      Description copied from interface: Account
      Set up a relationship so that the value from this account will be duplicated into the other account.
      Specified by:
      addDuplicate in interface Account
      Parameters:
      account - The account to receive the duplicated values.
      factors - An array of scaling factors to be applied to the duplicated account, one for each period.
    • getDuplicateCount

      public int getDuplicateCount()
      Description copied from interface: Account
      Determine the number of duplicate accounts
      Specified by:
      getDuplicateCount in interface Account
    • getDuplicate

      public ca.spatial.patchworks.DuplicateAccount getDuplicate(int i)
      Description copied from interface: Account
      Return a duplicate account.
      Specified by:
      getDuplicate in interface Account
    • toString

      public String toString()
      Overrides:
      toString in class Object
    • minimalTargetDef

      public static void minimalTargetDef(Target t, String prefix, int type, Appendable out) throws IOException
      write commands to an object that can be used to initialize the target to its current settings.
      Parameters:
      t - The target of interest
      prefix - A prefix string to be prepended on to each command line output. This should be the name of the object that that will be used to set these values (e.g. "t.")
      type - The type of setting to restore:
      • 1 = Minimum
      • 2 = Maximum
      • 3 = Minweight
      • 4 = Maxweight
      out - The object to append the commands to.
      Throws:
      IOException
    • describeSettings

      public static String describeSettings(Target t)
      Return an HTML string showing the settings for the minimum and maximum settings for this target. This can be used in reports or meta-data.