Package com.amalgamasimulation.discreterate

Class Merge<T>

java.lang.Object

com.amalgamasimulation.discreterate.FlowElement<T>

com.amalgamasimulation.discreterate.Merge<T>

Type Parameters:

T - type (class or interface) whose instances represent types of material

public final class Merge<T>
extends FlowElement<T>

Merge is a flow element that receives material from several inputs and combines them into a single output.

Merge has no storage capacity.

Merge can have many inflow connections and at most one outflow connection. The total current rate of inflow connections is equal to the rate of the outflow connection.

The behavior of a Merge with its downstream element's inflow rate less than sum of actual input flow rates of inflows being merged is defined by its FlowRateDistributionPolicy:

• In a PRIORITY Merge, the material is taken from the top priority inputs first until the downstream element's inflow rate limit is reached. For instance, if the downstream flow element can accept material at the max rate of 12 and the Merge has five inflow connections, with their respective inflow rates and priorities (see setInflowPriority(FlowConnection, double)) being from 1 to 5 (1 is the highest priority), then connections 1-4 will be used at their full rates (for a total rate of 10), and the 5th connection will only be used at its partial rate of 2 (12 - (1+2+3+4) = 2).
• In a PROPORTIONAL Merge, material is taken from all inflow connections. For each connection, a 'rate fraction' parameter is set (see setInflowRateFraction(FlowConnection, double)) indicating the fraction of that connection's rate in the overall inflow rate of the Merge. Rate limits of each incoming connection are respected. For instance, if the downstream flow element can accept material at the max rate of 5 and the Merge has four inflow connections, with their respective max inflow rates being 1 to 4 and 'rate fractions' being 0.25, then the actual inflow rate via each of the inflow connections will be equal to 1, for a total inflow rate of 4. On the other hand, if rate fractions are set to be 0.1, 0.2, 0.3, and 0.4 - then the inflow connections will have respective actual rates of 0.5, 1.0, 1.5, and 2.0, for a total of 5 (this is the rate limit of the downstream element).

Author:

Alexander Morozov

Constructor Summary

Constructors

Constructor	Description
Merge(FlowEnvironment<T> flowEnvironment, FlowRateDistributionPolicy policy)	Creates a new Merge instance.
Merge(FlowEnvironment<T> flowEnvironment, String name, FlowRateDistributionPolicy policy)	Creates a new Merge instance.

Method Summary

Modifier and Type	Method	Description
double	getContentsAmount()	Returns the current sum of quantities of all materials inside this flow element.
double	getContentsAmount(T material)	Returns the current quantity of the specified material inside this flow element.
Accumulator<T>	getContentsDescriptor()	Returns amounts of materials contained inside this flow element as an Accumulator instance.
FlowRateDistributionPolicy	getFlowRateDistributionPolicy()	Returns the FlowRateDistributionPolicy of this merge.
double	getInflowPriority(FlowConnection<T> inflowConnection)	Returns the priority of the specified inflow connection.
double	getInflowRate()	Returns the current flow rate of all materials at the input of this flow element.
Accumulator<T>	getInflowRateDescriptor()	Returns an Accumulator instance that describes the flow rate at the input of this flow element.
Accumulator<T>	getInflowRateDescriptor(FlowConnection<T> inflowConnection)	Returns an Accumulator instance that describes the material flow rate at the specified input connection.
double	getInflowRateFraction(FlowConnection<T> inflowConnection)	Returns the ratio of current inflowConnection flow rate to the overall inflow rate of this Merge.
double	getOutflowRate()	Returns the current flow rate at the output of this flow element.
Accumulator<T>	getOutflowRateDescriptor()	Returns an Accumulator instance that describes the flow rate at the output of this flow element.
Accumulator<T>	getOutflowRateProportions(FlowConnection<T> outflowConnection)	Returns an Accumulator instance that contains flow rate proportions of materials exported through the outflowConnection outflow connection.
double	getPassedAmount()	Returns the total quantity of all materials that have passed through this Merge.
double	getRate()	Returns the current flow rate through this merge.
double	getTotalInflowAmount()	Returns the total amount of all materials that have entered this flow element.
double	getTotalInflowAmount(T material)	Returns the total amount of the specified material that has entered this flow element.
Accumulator<T>	getTotalInflowDescriptor()	Returns an Accumulator instance that contains the total quantity of each material that has entered this flow element.
double	getTotalOutflowAmount()	Returns the total quantity of materials that have left this flow element.
double	getTotalOutflowAmount(T material)	Returns the total quantity of the specified material that has left this flow element.
Accumulator<T>	getTotalOutflowDescriptor()	Returns an Accumulator instance that holds the total amounts of each material that has left this flow element.
void	setInflowPriority(FlowConnection<T> inflowConnection, double priority)	Sets the priority of the input inflowConnection.
void	setInflowRateFraction(FlowConnection<T> inflowConnection, double rateFraction)	Sets the fraction of inflowConnection's actual flow rate in the overall inflow rate of this Merge.

Methods inherited from class com.amalgamasimulation.discreterate.FlowElement

addInflowElementConnectedHandler, addInflowElementDisconnectedHandler, addOutflowElementConnectedHandler, addOutflowElementDisconnectedHandler, connectToElement, disconnectFrom, getFlowEnvironment, getInflowConnections, getName, getOutflowConnections, inflowConnectionExists, isConnectedWith, outflowConnectionExists, removeInflowElementConnectedHandler, removeInflowElementDisconnectedHandler, removeOutflowElementConnectedHandler, removeOutflowElementDisconnectedHandler, toString

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Details

Merge

public Merge(FlowEnvironment<T> flowEnvironment,
 FlowRateDistributionPolicy policy)

Creates a new Merge instance.

Parameters:

flowEnvironment - FlowEnvironment which the new Merge belongs to

policy - flow rate distribution policy of the new Merge

Merge

public Merge(FlowEnvironment<T> flowEnvironment,
 String name,
 FlowRateDistributionPolicy policy)

Creates a new Merge instance.

Parameters:

flowEnvironment - FlowEnvironment which the new Merge belongs to

name - name of this Merge

policy - flow rate distribution policy of the new Merge

Method Details

getPassedAmount

public double getPassedAmount()

Returns the total quantity of all materials that have passed through this Merge.

Returns:

total quantity of materials passed through this Merge

setInflowPriority

public void setInflowPriority(FlowConnection<T> inflowConnection,
 double priority)

Sets the priority of the input inflowConnection.

Can only be called for a Merge with FlowRateDistributionPolicy.PRIORITY policy. Lower values of priority correspond to HIGHER priority of the inflowConnection.

Parameters:

inflowConnection - input flow connection for which the priority is being set

priority - priority of the input inflowConnection, must be non-negative

Throws:

IllegalStateException - if current policy of the Merge is not FlowRateDistributionPolicy.PRIORITY

IllegalArgumentException - if priority is less than 0

IllegalArgumentException - if inflowConnection is not an inflow connection to this Merge

getInflowPriority

public double getInflowPriority(FlowConnection<T> inflowConnection)

Returns the priority of the specified inflow connection. The lower the returned value, the higher the priority.

Throws an exception is the connection is not related to this flow element.

If the Merge's policy is FlowRateDistributionPolicy.PROPORTIONAL, returns 0.

Parameters:

inflowConnection - inflow connection

Returns:

priority of the incoming inflowConnection

getInflowRateFraction

public double getInflowRateFraction(FlowConnection<T> inflowConnection)

Returns the ratio of current inflowConnection flow rate to the overall inflow rate of this Merge.

The returned value belongs to a closed interval [0..1].

Parameters:

inflowConnection - input flow connection

Returns:

fraction of the inflowConnection flow rate in the overall inflow rate of the Merge

Throws:

IllegalStateException - if called for a Merge with flow distribution policy other than FlowRateDistributionPolicy.PROPORTIONAL

IllegalStateException - if the inflow rate fraction has not been configured for this inflowConnection and this Merge

IllegalArgumentException - if the inflowConnection is not related to this Merge

See Also:

• setInflowRateFraction(FlowConnection, double)

setInflowRateFraction

public void setInflowRateFraction(FlowConnection<T> inflowConnection,
 double rateFraction)

Sets the fraction of inflowConnection's actual flow rate in the overall inflow rate of this Merge.

Can only be called for a Merge with FlowRateDistributionPolicy.PROPORTIONAL policy.

In a Merge with FlowRateDistributionPolicy.PROPORTIONAL policy, each new inflow connection should be assigned a rate fraction. The sum of rate fractions for all such inflow connections must be equal to 1.

Parameters:

inflowConnection - input flow connection for which the rate fraction is being set

rateFraction - a number in the closed interval [0..1] representing the ratio of inflowConnection flow rate to the overall inflow rate of this Merge

Throws:

IllegalStateException - if called for a Merge with flow distribution policy other than FlowRateDistributionPolicy.PROPORTIONAL

IllegalArgumentException - if the inflowConnection is not related to this Merge

IllegalArgumentException - if rateFraction is not in the closed interval [0..1]

getFlowRateDistributionPolicy

public FlowRateDistributionPolicy getFlowRateDistributionPolicy()

Returns the FlowRateDistributionPolicy of this merge. The policy is applied to the inflow rate.

Returns:

FlowRateDistributionPolicy of this merge

getRate

public double getRate()

Returns the current flow rate through this merge.

Returns:

current flow rate through this merge

getContentsAmount

public double getContentsAmount()

Returns the current sum of quantities of all materials inside this flow element. Always returns zero for any Merge because Merges have no storage capacity and do not contain any material.

Specified by:

getContentsAmount in class FlowElement<T>

Returns:

0

See Also:

• getContentsAmount(element)
• getContentsDescriptor()

getContentsAmount

public double getContentsAmount(T material)

Returns the current quantity of the specified material inside this flow element. Always returns zero for any Merge because Merges have no storage capacity and do not contain any material.

Specified by:

getContentsAmount in class FlowElement<T>

Parameters:

material - material

Returns:

0

See Also:

• getContentsAmount()
• getContentsDescriptor()

getContentsDescriptor

public Accumulator<T> getContentsDescriptor()

Returns amounts of materials contained inside this flow element as an Accumulator instance. Always returns an empty Accumulator for any Merge because a merge has no storage capacity and does not contain any material.

Specified by:

getContentsDescriptor in class FlowElement<T>

Returns:

empty Accumulator

See Also:

• getContentsAmount()
• getContentsAmount(element)

getInflowRate

public double getInflowRate()

Description copied from class: FlowElement

Returns the current flow rate of all materials at the input of this flow element.

Specified by:

getInflowRate in class FlowElement<T>

Returns:

current flow rate of all materials at this flow element's input

See Also:

• FlowElement.getInflowRateDescriptor()

getInflowRateDescriptor

public Accumulator<T> getInflowRateDescriptor()

Description copied from class: FlowElement

Returns an Accumulator instance that describes the flow rate at the input of this flow element.

The returned Accumulator instance contains the respective rates of all materials currently entering the flow element. The sum of values in the Accumulator is equal to 1.

Specified by:

getInflowRateDescriptor in class FlowElement<T>

Returns:

descriptor of the current inflow rate

See Also:

• FlowElement.getInflowRate()

getInflowRateDescriptor

public Accumulator<T> getInflowRateDescriptor(FlowConnection<T> inflowConnection)

Returns an Accumulator instance that describes the material flow rate at the specified input connection.

The returned Accumulator instance contains the respective rates of all materials currently entering the Merge through the specified connection.

Parameters:

inflowConnection - input flow connection

Returns:

current flow rate of material at specified input connection

Throws:

IllegalArgumentException - if the inflowConnection is not related to this Merge

getOutflowRate

public double getOutflowRate()

Description copied from class: FlowElement

Returns the current flow rate at the output of this flow element.

Specified by:

getOutflowRate in class FlowElement<T>

Returns:

current flow rate at the output of this flow element

See Also:

• FlowElement.getOutflowRateDescriptor()

getOutflowRateDescriptor

public Accumulator<T> getOutflowRateDescriptor()

Description copied from class: FlowElement

Returns an Accumulator instance that describes the flow rate at the output of this flow element.

The returned Accumulator instance contains the respective rates of all materials currently leaving the flow element. The sum of values in the Accumulator is equal to 1.

Specified by:

getOutflowRateDescriptor in class FlowElement<T>

Returns:

descriptor of the current outflow rate

See Also:

• FlowElement.getOutflowRate()

getOutflowRateProportions

public Accumulator<T> getOutflowRateProportions(FlowConnection<T> outflowConnection)

Description copied from class: FlowElement

Returns an Accumulator instance that contains flow rate proportions of materials exported through the outflowConnection outflow connection.

Each element of the returned Accumulator corresponds to a material in the current material flow of outflowConnection. The value of each element in the Accumulator is the ratio of the rate of that material's partial flow to the overall flow rate of outflowConnection. The sum of values in the Accumulator is equal to 1.

Specified by:

getOutflowRateProportions in class FlowElement<T>

Parameters:

outflowConnection - an outflow connection

Returns:

material proportions in the outflow connection

getTotalInflowAmount

public double getTotalInflowAmount()

Description copied from class: FlowElement

Returns the total amount of all materials that have entered this flow element.

Specified by:

getTotalInflowAmount in class FlowElement<T>

Returns:

total amount of all arrived materials

getTotalInflowAmount

public double getTotalInflowAmount(T material)

Description copied from class: FlowElement

Returns the total amount of the specified material that has entered this flow element.

Specified by:

getTotalInflowAmount in class FlowElement<T>

Parameters:

material - material

Returns:

total amount of the specified material that has arrived to this flow element

See Also:

• FlowElement.getTotalInflowAmount()
• FlowElement.getTotalInflowDescriptor()

getTotalInflowDescriptor

public Accumulator<T> getTotalInflowDescriptor()

Description copied from class: FlowElement

Returns an Accumulator instance that contains the total quantity of each material that has entered this flow element.

The values of each element in the returned Accumulator match the quantities of the respective materials that have entered the flow element. The sum of values in the Accumulator is equal to the value returned by the FlowElement.getTotalInflowAmount() method.

Specified by:

getTotalInflowDescriptor in class FlowElement<T>

Returns:

Accumulator containing total amounts of materials that have entered this flow element

See Also:

• FlowElement.getTotalInflowAmount()
• FlowElement.getTotalInflowAmount(material)

getTotalOutflowAmount

public double getTotalOutflowAmount()

Description copied from class: FlowElement

Returns the total quantity of materials that have left this flow element.

Specified by:

getTotalOutflowAmount in class FlowElement<T>

Returns:

total quantity of exported materials

See Also:

• FlowElement.getTotalOutflowAmount(material)
• FlowElement.getTotalOutflowDescriptor()

getTotalOutflowAmount

public double getTotalOutflowAmount(T material)

Description copied from class: FlowElement

Returns the total quantity of the specified material that has left this flow element.

Specified by:

getTotalOutflowAmount in class FlowElement<T>

Parameters:

material - material

Returns:

total quantity of the specified material that has left this flow element

See Also:

• FlowElement.getTotalOutflowAmount()
• FlowElement.getTotalOutflowDescriptor()

getTotalOutflowDescriptor

public Accumulator<T> getTotalOutflowDescriptor()

Description copied from class: FlowElement

Returns an Accumulator instance that holds the total amounts of each material that has left this flow element.

The values of each element in the returned Accumulator match the quantities of the respective materials that have left the flow element. The sum of values in the Accumulator is equal to the value returned by the FlowElement.getTotalOutflowAmount() method.

Specified by:

getTotalOutflowDescriptor in class FlowElement<T>

Returns:

Accumulator containing total amounts of materials that have left this flow element

See Also:

• FlowElement.getTotalOutflowAmount()
• FlowElement.getTotalOutflowAmount(material)