atomica.model.JunctionCompartment

class atomica.model.JunctionCompartment(pop, name, duration_group=None)

Bases: Compartment

A TimedCompartment has a duration group by virtue of having a .parameter attribute and a flush link. A junction might belong to a duration group by having inflows and outflows exclusively from that group. However, it might not be directly attached to any timed compartments, if the connections are entirely via upstream and downstream junctions. Junctions also do not have flush links. Therefore, we record membership in the duration group by specifying the name of the parameter in the (indirect) upstream and downstream compartments.

Note that having connections to timed compartments does not itself indicate membership in the duration group - the junction is only a member if all of the upstream and downstream compartments belong to the same duration group. The duration group is determined in framework validation and stored in the framework.

Parameters:

• pop

• name (str)

• duration_group (str) – Optionally specify a duration group

Attributes

name	Variable code name
outflow	Return the outflow at all times
duration_group	Store the name of the duration group, if the junction belongs to one
id	Unique identifier for the integration object
units	The units for the quantity, used for plotting and for validation.
pop	Reference back to the Population containing this object

Methods

balance	Balance junction inflows and outflows
connect	Construct link out of this compartment
expected_duration
expected_outflow
initial_flush	Perform an initial junction flush
plot	Produce a time series plot
preallocate	Preallocate junction values
relink
resolve_outflows	Resolve outgoing links and convert to number
set_dynamic	Make the variable a dependency
unlink
update	Update the junction at given time index

balance(ti)

Balance junction inflows and outflows

This is the primary update for a junction - where outflows are adjusted so that they equal the inflows. It’s analogous to resolve_outflows as a primary update method, but it takes place at a separate integration stage (once the outflows for normal compartments have been finalized, as these outputs serve as the junction inputs in that same timestep) After this method is called, all outflows should equal inflows

The parameter workflow is simplified because all links flowing out of junctions must be in ‘proportion’ units, so they can be looked up and used directly.

Parameters:

ti (int) – Time index to update (scalar only, as this function is only called during integration)

Return type:

None

connect(dest, par)

Construct link out of this compartment

For junctions, outgoing links are normal links unless the junction belongs to a duration group. If the junction belongs to a duration group, then the output links should all be TimedLink instances.

Parameters:

• dest – A Compartment instance

• par – The parameter that the Link will be associated with

Return type:

None

duration_group

Store the name of the duration group, if the junction belongs to one

id

Unique identifier for the integration object

initial_flush()

Perform an initial junction flush

If the junction was initialized with a nonzero value, then the initial people need to be flushed. This is distinct from balancing, because the source of the people is the junction itself, rather than the incoming links.

In this step, we need to actually update the value of the downstream compartments, rather than updating the link values - the links get rebalanced again based on the parameters after the initial flush has been completed

Return type:

None

property name: str

Variable code name

This is implemented as a property method because the id of the Variable is a tuple containing the population name and the variable code name, so this property method returns just the variable code name portion. That way, storage does not need to be duplicated.

Returns:

A code name

property outflow: array

Return the outflow at all times

Returns:

The sum of outgoing links at all time indices

plot()

Produce a time series plot

This is a quick function to make a basic line plot of this Variable. Mainly intended for debugging. Production-ready plots should be generated using the plotting library functions instead

Return type:

None

pop

Reference back to the Population containing this object

preallocate(tvec, dt)

Preallocate junction values

Junction preallocation pre-fills the values with zeros, since the junction must be empty at all times.

Parameters:

• tvec (array) – An array of time values

• dt (float) – Time step size

Return type:

None

resolve_outflows(ti)

Resolve outgoing links and convert to number

For junctions, links are updated in a separate step because the logic is different - instead of the value of links coming from parameters, they come from the inflow into the junction. We cannot update the junctions in the same step as compartments because while the junction subgraphs must be acyclic, the entire system may contain cycles. Therefore it is not possible to determine a topological ordering for the entire system. The system is solvable because for normal compartments, only one transition per timestep is allowed. But regardless, this prevents using graph analysis to determine an execution order for the entire system that would allow junction computation in the same step.

Parameters:

ti (int) – Time index to resolve outflows

Return type:

None

set_dynamic(**kwargs)

Make the variable a dependency

For Compartments and Links, this does nothing. For Characteristics and Parameters, it will set the dynamic flag, but in addition, any validation constraints e.g. a Parameter that depends on Links cannot itself be dynamic, will be enforced.

This method generally must be overloaded in derived classes e.g. Parameter.set_dynamic()

Return type:

None

units

The units for the quantity, used for plotting and for validation. Note that the default 'unknown' units are distinct to dimensionless units, which have value ''

update(ti)

Update the junction at given time index

For compartments the update methods steps them forward in time. However, for junctions the value never needs to be stepped forward, because it’s always zero. Thus, this function does nothing.

Parameters:

ti (int) – Time index to update

Return type:

None