fragments
Fragment
Bases: LcEntity
What can I say? THey're complicated. Conceptually, a fragment is a modeler's tool for keeping track of measurements of a specific material flow.
A fragment's main purpose is to express a linkage between a parent node and a target or 'anchor' node by means of an observed flow.
Fragments have the following broad functionalities:
- they can be named. external_ref can be set. not clear why this is only for fragments, but it is meant to provide h-r semantic consistency / clarity during data use
- they can be observed. a fragment has a cached and an observed exchange value. the cached value is meant to indicate its value upon creation, and observed is the default value returned upon quantitative queries. observations take the form of a scenario specification and an exchange value (along with metadata such as dqi, uncertainty, etc)
- they can be anchored, to data sets or to other models. anchor points are also specified by scenario. anchors can be toggled to "descend" (i.e. expand sub-fragments) or non-descend / roll-up sub-fragments
- they have child flows. "reference flows" have no parent and supply/consume a good or service through exchange with a second party. Child flows are then dependent on the reference flow. By traversing these links to their ends, the entire "span" of the study can be enumerated. It is the job of the traversal engine to ensure that traversal terminates upon reaching a background node (i.e. one with membership in a cycle) to a flat LCI.
- they can balance. Each fragment node (the thing that is 'anchored') can compute a balance during traversal, assigning a designated child flow the magnitude of the balance at traversal time. The quantity that is conserved is precisely the designated balance flow's reference quantity. all flows are queried for characterization in computing the balance.
- STILL TBD: how to handle "balancing" into and out of anchored subfragments
unit
property
used for formatting the fragment in display
Returns:
| Type | Description |
|---|---|
|
|
__hash__()
Fragments must use UUID as hash because the link is mutable
Returns:
| Type | Description |
|---|---|
|
|
add_child(child)
This should only be called from the child's set_parent function
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
child |
|
required |
Returns:
| Type | Description |
|---|---|
|
|
de_name()
Remove a fragment's name
Returns:
| Type | Description |
|---|---|
|
|
ev(scenarios=None)
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
scenarios |
either None, or an iterable of scenarios |
None
|
Returns:
| Type | Description |
|---|---|
|
matching scenario, matching ev |
exchanges(scenario=None)
Generator for query compatibility with processes
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
scenario |
|
None
|
Returns:
| Type | Description |
|---|---|
|
|
make_ref(query)
We do NOT want to make local fragments into refs-- but we DO want to make remote fragments into refs. so we simply neuter the workhorse function here.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
query |
|
required |
Returns:
| Type | Description |
|---|---|
|
|
new(flow, direction, **kwargs)
classmethod
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
flow |
entity or ref |
required | |
direction |
"Input" or "Output" w/r/t parent (future: "balance" to be also accepted) |
required | |
kwargs |
parent; exchange_value/observe; anchor/anchor_flow/descend; balance_flow (alt.), external_ref |
{}
|
Returns:
| Type | Description |
|---|---|
|
|
nodes(scenario=None, descend=True)
Report proximal terminal nodes for the fragment (recurse until a nondescend is reached)
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
scenario |
[None] |
None
|
|
descend |
[True] if False, yield subfragments as nodes |
True
|
Returns:
| Type | Description |
|---|---|
|
generator of terminal nodes |
reference(flow=None)
For process interoperability
Returns:
| Type | Description |
|---|---|
|
|
remove_child(child)
This should only be called from the child's unset_parent function
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
child |
|
required |
Returns:
| Type | Description |
|---|---|
|
|
scale_evs(factor)
needed when foregrounding terminations
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
factor |
|
required |
Returns:
| Type | Description |
|---|---|
|
|
set_balance_flow()
A balance flow balances its own reference quantity.
Returns:
| Type | Description |
|---|---|
|
|
tree()
This is real simple- just a recursive enumeration of child flows, depth first
Returns:
| Type | Description |
|---|---|
|
|