Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Documentation changes #145

Open
wants to merge 1 commit into
base: main
Choose a base branch
from
Open

Documentation changes #145

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
27 changes: 18 additions & 9 deletions paml/__init__.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -74,6 +74,7 @@ def protocol_primitive_step(self, primitive: Primitive, **input_pin_map):

Note that this will not give a stable order if adding to a Protocol that has been deserialized, since
information about the order in which steps were created is not stored.

:param primitive: Primitive to be invoked (object or string name)
:param input_pin_map: literal value or ActivityNode mapped to names of Behavior parameters
:return: CallBehaviorAction that invokes the Primitive
Expand Down Expand Up @@ -256,15 +257,12 @@ def _type_attrs(object: uml.ActivityNode) -> Dict[str,str]:
Protocol.to_dot = protocol_to_dot

def activity_edge_flow_get_target(self):
'''Find the target node of an edge flow
Parameters
----------
self

Returns ActivityNode
-------
"""
Find the target node of an edge flow

'''
:param self:
:return: FIXME
"""
if self.edge:
target = self.document.find(self.document.find(self.edge).target)
else: # Tokens for pins do not have an edge connecting pin to activity
Expand All @@ -289,6 +287,7 @@ def activity_edge_flow_get_target(self):
def primitive_str(self):
"""
Create a human readable string describing the Primitive

:param self:
:return: str
"""
Expand All @@ -314,8 +313,9 @@ def mark_optional(parameter):
def behavior_execution_parameter_value_map(self):
"""
Return a dictionary mapping parameter names to value or (value, unit)

:param self:
:return:
:return: FIXME
"""
parameter_value_map = {}

Expand Down Expand Up @@ -361,6 +361,11 @@ def import_library(library: str, extension: str = 'ttl', nickname: str = None):
loaded_libraries[nickname] = lib

def show_library(library_name: str):
"""Show information for given library

:param library_name: Name of a library
:return: str
"""
dashes = "-" * 80
print(dashes)
print(f"library: {library_name}")
Expand All @@ -370,6 +375,10 @@ def show_library(library_name: str):
print(dashes)

def show_libraries():
"""Show all available libraries

:return: str
"""
primitives = {}
for lib in paml.loaded_libraries.keys():
show_library(lib)
Expand Down
97 changes: 43 additions & 54 deletions paml/execution_engine.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -17,7 +17,8 @@
l.setLevel(logging.ERROR)

class ExecutionEngine(ABC):
"""Base class for implementing and recording a PAML executions.
"""
Base class for implementing and recording a PAML executions.
This class can handle common UML activities and the propagation of tokens, but does not execute primitives.
It needs to be extended with specific implementations that have that capability.
"""
Expand Down Expand Up @@ -83,18 +84,16 @@ def execute(self,
id: str = uuid.uuid4(),
start_time: datetime.datetime = None
) -> paml.ProtocolExecution:
"""Execute the given protocol against the provided parameters

Parameters
----------
protocol: Protocol to execute
agent: Agent that is executing this protocol
parameter_values: List of all input parameter values (if any)
id: display_id or URI to be used as the name of this execution; defaults to a UUID display_id

Returns
-------
ProtocolExecution containing a record of the execution
"""
Execute the given protocol against the provided parameters

:param protocol: Protocol to execute
:param agent: Agent that is executing this protocol
:param parameter_values: List of all input parameter values (if any)
:param id: display_id or URI to be used as the name of this execution; defaults to a UUID display_id
:param start_time: FIXME

:return: ProtocolExecution containing a record of the execution
"""

# Record in the document containing the protocol
Expand Down Expand Up @@ -144,17 +143,15 @@ def execute(self,
def executable_activity_nodes(self, protocol: paml.Protocol, tokens: List[paml.ActivityEdgeFlow],
parameter_values: List[paml.ParameterValue])\
-> List[uml.ActivityNode]:
"""Find all of the activity nodes that are ready to be run given the current set of tokens
"""
Find all of the activity nodes that are ready to be run given the current set of tokens
Note that this will NOT identify activities with no in-flows: those are only set up as initiating nodes

Parameters
----------
protocol: paml.Protocol being executed
tokens: set of ActivityEdgeFlow records that have not yet been consumed
:param protocol: paml.Protocol being executed
:param tokens: set of ActivityEdgeFlow records that have not yet been consumed
:param parameter_values: FIXME

Returns
-------
List of ActivityNodes that are ready to be run
:return: List of ActivityNodes that are ready to be run
"""
candidate_clusters = {}
for t in tokens:
Expand All @@ -165,19 +162,16 @@ def executable_activity_nodes(self, protocol: paml.Protocol, tokens: List[paml.A

def enabled_activity_node(self, protocol: paml.Protocol, node: uml.ActivityNode,
tokens: List[paml.ActivityEdgeFlow], parameter_values: List[paml.ParameterValue]):
"""Check whether all incoming edges have values defined by a token in tokens and that all value pin values are
defined.

Parameters
----------
protocol: paml.Protocol being executed
node: node to be executed
tokens: current list of pending edge flows

Returns
-------
bool if node is enabled
"""
"""
Check whether all incoming edges have values defined by a token in tokens and that all value pin values are defined.

:param protocol: paml.Protocol being executed
:param node: node to be executed
:param tokens: current list of pending edge flows
:param parameter_values: FIXME

:return: bool if node is enabled
"""
tokens_present = {node.document.find(t.edge) for t in tokens if t.edge}==protocol.incoming_edges(node)
if hasattr(node, "inputs"):
required_inputs = [node.input_pin(i.property_value.name)
Expand All @@ -199,17 +193,14 @@ def enabled_activity_node(self, protocol: paml.Protocol, node: uml.ActivityNode

def execute_activity_node(self, ex : paml.ProtocolExecution, node: uml.ActivityNode,
tokens: List[paml.ActivityEdgeFlow]) -> List[paml.ActivityEdgeFlow]:
"""Execute a node in an activity, consuming the incoming flows and recording execution and outgoing flows
"""
Execute a node in an activity, consuming the incoming flows and recording execution and outgoing flows

Parameters
----------
ex: Current execution record
node: node to be executed
tokens: current list of pending edge flows
:param ex: Current execution record
:param node: Node to be executed
:param tokens: Current list of pending edge flows

Returns
-------
updated list of pending edge flows
:return: Updated list of pending edge flows
"""
# Extract the relevant set of incoming flow values
# TODO change to pointer lookup after pySBOL #237
Expand Down Expand Up @@ -396,16 +387,13 @@ def execute_primitive(self, behavior: paml.Primitive, agent: sbol3.Agent, parame
# Helper utility functions

def sum_measures(measure_list):
"""Add a list of measures and return a fresh measure
"""
Add a list of measures and return a fresh measure
Note: requires that all have the same unit and types

Parameters
----------
measure_list of SBOL Measure objects
:param measure_list: list of SBOL Measure objects

Returns
-------
New Measure object with the sum of input measure amounts
:return: New Measure object with the sum of input measure amounts
"""
prototype = measure_list[0]
if not all(m.types == prototype.types and m.unit == prototype.unit for m in measure_list):
Expand All @@ -415,11 +403,11 @@ def sum_measures(measure_list):


def protocol_execution_aggregate_child_materials(self):
"""Merge the consumed material from children, adding a fresh Material for each to this record.
"""
Merge the consumed material from children, adding a fresh Material for each to this record.

Parameters
----------
self: ProtocolExecution object
:param self: ProtocolExecution object
:return:
"""
child_materials = [e.call.consumed_material for e in self.executions
if isinstance(e, paml.CallBehaviorExecution) and
Expand All @@ -433,6 +421,7 @@ def protocol_execution_aggregate_child_materials(self):
def protocol_execution_to_dot(self):
"""
Create a dot graph that illustrates edge values appearing the execution of the protocol.

:param self:
:return: graphviz.Digraph
"""
Expand Down
4 changes: 4 additions & 0 deletions paml/primitive_execution.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -14,6 +14,7 @@
def call_behavior_execution_compute_output(self, parameter):
"""
Get parameter value from call behavior execution

:param self:
:param parameter: output parameter to define value
:return: value
Expand All @@ -28,6 +29,7 @@ def call_behavior_execution_compute_output(self, parameter):
def call_behavior_action_compute_output(self, inputs, parameter):
"""
Get parameter value from call behavior action

:param self:
:param inputs: token values for object pins
:param parameter: output parameter to define value
Expand All @@ -42,6 +44,7 @@ def call_behavior_action_compute_output(self, inputs, parameter):
def call_behavior_action_input_parameter_values(self, inputs=None):
"""
Get parameter values for all inputs

:param self:
:param parameter: output parameter to define value
:return: value
Expand Down Expand Up @@ -77,6 +80,7 @@ def call_behavior_action_input_parameter_values(self, inputs=None):
def primitive_compute_output(self, inputs, parameter):
"""
Compute the value for parameter given the inputs. This default function will be overridden for specific primitives.

:param self:
:param inputs: list of paml.ParameterValue
:param parameter: Parameter needing value
Expand Down
5 changes: 5 additions & 0 deletions paml/ui.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,6 +4,7 @@
def protocol_template():
"""
Create a template instantiation of a protocol. Used for populating UI elements.

:param
:return: str
"""
Expand All @@ -13,6 +14,7 @@ def protocol_template():
def primitive_template(self):
"""
Create a template instantiation of a primitive for writing a protocol. Used for populating UI elements.

:param self:
:return: str
"""
Expand All @@ -25,6 +27,7 @@ def primitive_template(self):
def sample_array_str(self):
"""
Create a human readable string for a SampleArray.

:param self:
:return: str
"""
Expand All @@ -34,6 +37,7 @@ def sample_array_str(self):
def sample_mask_str(self):
"""
Create a human readable string for a SampleMask.

:param self:
:return: str
"""
Expand All @@ -43,6 +47,7 @@ def sample_mask_str(self):
def sample_data_str(self):
"""
Create a human readable string for a SampleData.

:param self:
:return: str
"""
Expand Down