# Agent Interface - Region, Institution, and Facility (cyclus.agents)¶

A Python interface for Agents and their subclasses.

class cyclus.agents.Agent

Python Agent that is subclassable into any kind of agent.

Parameters: ctx : cyclus.lib.Context The simulation execution context. You don’t normally need to call the initilaizer.
adjust_material_prefs()

adjust_product_prefs()

ancestor_of()

Returns true if this agent is an ancestor of an other agent (i.e., resides above an other agent in the family tree).

annotations

Agent annotations.

annotations_json
build()

Called when the agent enters the smiulation as an active participant and is only ever called once. Agents should NOT register for services (such as ticks/tocks and resource exchange) in this function. If agents implement this function, they must call their superclass’ Build function at the BEGINING of their Build function.

build_notify()

Called when a new child of this agent has just been built. It is possible for this function to be called before the simulation has started when initially existing agents are being setup.

children

A frozen set of the children of this agent.

children_str()

Returns recursively generated string of the parent-child tree.

context

Returns this agent’s simulation context.

decendent_of()

Returns true if this agent is an decendent of an other agent (i.e., resides above an other agent in the family tree).

decom_notify()

Called when a new child of this agent is about to be decommissioned.

decomission()

Decommissions the agent, removing it from the simulation. Results in destruction of the agent object. If agents write their own decommission() function, they must call their superclass’ decommission function at the END of their decommission() function.

enter_notify()

Called to give the agent an opportunity to register for services (e.g. ticks/tocks and resource exchange). Note that this may be called more than once, and so agents should track their registrations carefully. If agents implement this function, they must call their superclass’s EnterNotify function at the BEGINNING of their EnterNotify function.

enter_time

The time step at which this agent’s Build function was called (-1 if the agent has never been built).

entity = 'archetype'
exit_time

The default time step at which this agent will exit the simulation (-1 if the agent has an infinite lifetime).

Decomissioning happens at the end of a time step. With a lifetime of 1, we expect an agent to go through only 1 entire time step. In this case, the agent should be decommissioned on the same time step it was created. Therefore, for agents with non-infinite lifetimes, the exit_time will be the enter time plus its lifetime less 1.

id

The agent instance’s unique ID within a simulation.

in_family_tree()

Returns true if this agent is in the parent-child family tree of an other agent.

infile_to_db()

A dynamic version of InfileToDb(InfileTree*, DbInit) that should work for all subclasses. Users should not need to call this ever. However, brave users may choose to override it in exceptional cases.

init_from_agent()

A dynamic version of InitFrom(Agent) that should work for all subclasses. Users should not need to call this ever. However, brave users may choose to override it in exceptional cases.

init_from_dict()

An initializer that reads state varaible values from a dictionary. This is used when InitFrom(QueryableBackend) is called. Users should not need to call this ever. However, brave users may choose to override it in exceptional cases.

init_inv()

An initializer that sets up inventories. This is used when InitInv(Inventories&) is called. Users should not need to call this ever. However, brave users may choose to override it in exceptional cases.

kind

Returns a string that describes the agent subclass (e.g. Region, Facility, etc.)

lifetime

The number of time steps this agent operates between building and decommissioning (-1 if the agent has an infinite lifetime)

niche = None
parent()

Returns parent of this agent. Returns None if the agent has no parent.

parent_id

The id for this agent’s parent or -1 if this agent has no parent.

prototype

The agent’s prototype.

schema

“The class schema based on the state variables.

snapshot()

A dynamic version of Snapshot(DbInit) that should work for all subclasses. Users should not need to call this ever. However, brave users may choose to override it in exceptional cases.

snapshot_inv()

A dynamic version of SnapshotInv() that reports the current state of the inventories. Users should not need to call this ever. However, brave users may choose to override it in exceptional cases.

spec

The agent’s spec.

tooltip = None
tree_strs()

Returns a list of children strings representing the parent-child tree at the node for Agent m.

userlevel = 0
version

Property that represents version of this archetype. Overwrite this to return a custom version string.

class cyclus.agents.Facility

Python Facility that is subclassable into a facility archetype.

Parameters: ctx : cyclus.lib.Context The simulation execution context. You don’t normally need to call the initilaizer.
accept_material_trades()

Method for accepting materials from a trade deal.

accept_product_trades()

Method for accepting products from a trade deal.

adjust_material_prefs()

adjust_product_prefs()

ancestor_of()

Returns true if this agent is an ancestor of an other agent (i.e., resides above an other agent in the family tree).

annotations

Agent annotations.

annotations_json
build()

Called when the agent enters the smiulation as an active participant and is only ever called once. Agents should NOT register for services (such as ticks/tocks and resource exchange) in this function. If agents implement this function, they must call their superclass’ Build function at the BEGINING of their Build function.

build_notify()

Called when a new child of this agent has just been built. It is possible for this function to be called before the simulation has started when initially existing agents are being setup.

check_decomission_condition()

facilities over write this method if a condition must be met before their destructors can be called. Return True means that the facility is ready for decomission. False prevents decomission.

children

A frozen set of the children of this agent.

children_str()

Returns recursively generated string of the parent-child tree.

context

Returns this agent’s simulation context.

decendent_of()

Returns true if this agent is an decendent of an other agent (i.e., resides above an other agent in the family tree).

decom_notify()

Called when a new child of this agent is about to be decommissioned.

decomission()

Decommissions the agent, removing it from the simulation. Results in destruction of the agent object. If agents write their own decommission() function, they must call their superclass’ decommission function at the END of their decommission() function.

enter_notify()

Called to give the agent an opportunity to register for services (e.g. ticks/tocks and resource exchange). Note that this may be called more than once, and so agents should track their registrations carefully. If agents implement this function, they must call their superclass’s EnterNotify function at the BEGINNING of their EnterNotify function.

enter_time

The time step at which this agent’s Build function was called (-1 if the agent has never been built).

entity = 'facility'
exit_time

The default time step at which this agent will exit the simulation (-1 if the agent has an infinite lifetime).

Decomissioning happens at the end of a time step. With a lifetime of 1, we expect an agent to go through only 1 entire time step. In this case, the agent should be decommissioned on the same time step it was created. Therefore, for agents with non-infinite lifetimes, the exit_time will be the enter time plus its lifetime less 1.

get_material_bids()

Returns material bids for this agent on this time step. This may be overridden is subclasses.

get_material_requests()

Returns material requests for this agent on this time step. This is meant to be overridden is subclasses.

get_material_trades()

Implementation for responding to material trades.

get_product_bids()

Returns product bids for this agent on this time step. This may be overridden is subclasses.

get_product_requests()

Returns product requests for this agent on this time step. This is meant to be overridden is subclasses.

get_product_trades()

Implementation for responding to product trades.

id

The agent instance’s unique ID within a simulation.

in_family_tree()

Returns true if this agent is in the parent-child family tree of an other agent.

infile_to_db()

A dynamic version of InfileToDb(InfileTree*, DbInit) that should work for all subclasses. Users should not need to call this ever. However, brave users may choose to override it in exceptional cases.

init_from_agent()

A dynamic version of InitFrom(Agent) that should work for all subclasses. Users should not need to call this ever. However, brave users may choose to override it in exceptional cases.

init_from_dict()

An initializer that reads state varaible values from a dictionary. This is used when InitFrom(QueryableBackend) is called. Users should not need to call this ever. However, brave users may choose to override it in exceptional cases.

init_inv()

An initializer that sets up inventories. This is used when InitInv(Inventories&) is called. Users should not need to call this ever. However, brave users may choose to override it in exceptional cases.

kind

Returns a string that describes the agent subclass (e.g. Region, Facility, etc.)

lifetime

The number of time steps this agent operates between building and decommissioning (-1 if the agent has an infinite lifetime)

niche = None
parent()

Returns parent of this agent. Returns None if the agent has no parent.

parent_id

The id for this agent’s parent or -1 if this agent has no parent.

prototype

The agent’s prototype.

schema

“The class schema based on the state variables.

snapshot()

A dynamic version of Snapshot(DbInit) that should work for all subclasses. Users should not need to call this ever. However, brave users may choose to override it in exceptional cases.

snapshot_inv()

A dynamic version of SnapshotInv() that reports the current state of the inventories. Users should not need to call this ever. However, brave users may choose to override it in exceptional cases.

spec

The agent’s spec.

tick()

This function is called each time step and is meant to be overlaoded in the subclass.

tock()

This function is called each time step and is meant to be overlaoded in the subclass.

tooltip = None
tree_strs()

Returns a list of children strings representing the parent-child tree at the node for Agent m.

userlevel = 0
version

Property that represents version of this archetype. Overwrite this to return a custom version string.

class cyclus.agents.Institution

Python Institution that is subclassable into a institution archetype.

Parameters: ctx : cyclus.lib.Context The simulation execution context. You don’t normally need to call the initilaizer.
adjust_material_prefs()

adjust_product_prefs()

ancestor_of()

Returns true if this agent is an ancestor of an other agent (i.e., resides above an other agent in the family tree).

annotations

Agent annotations.

annotations_json
build()

Called when the agent enters the smiulation as an active participant and is only ever called once. Agents should NOT register for services (such as ticks/tocks and resource exchange) in this function. If agents implement this function, they must call their superclass’ Build function at the BEGINING of their Build function.

build_notify()

Called when a new child of this agent has just been built. It is possible for this function to be called before the simulation has started when initially existing agents are being setup.

children

A frozen set of the children of this agent.

children_str()

Returns recursively generated string of the parent-child tree.

context

Returns this agent’s simulation context.

decendent_of()

Returns true if this agent is an decendent of an other agent (i.e., resides above an other agent in the family tree).

decom_notify()

Called when a new child of this agent is about to be decommissioned.

decomission()

Decommissions the agent, removing it from the simulation. Results in destruction of the agent object. If agents write their own decommission() function, they must call their superclass’ decommission function at the END of their decommission() function.

enter_notify()

Called to give the agent an opportunity to register for services (e.g. ticks/tocks and resource exchange). Note that this may be called more than once, and so agents should track their registrations carefully. If agents implement this function, they must call their superclass’s EnterNotify function at the BEGINNING of their EnterNotify function.

enter_time

The time step at which this agent’s Build function was called (-1 if the agent has never been built).

entity = 'institution'
exit_time

The default time step at which this agent will exit the simulation (-1 if the agent has an infinite lifetime).

Decomissioning happens at the end of a time step. With a lifetime of 1, we expect an agent to go through only 1 entire time step. In this case, the agent should be decommissioned on the same time step it was created. Therefore, for agents with non-infinite lifetimes, the exit_time will be the enter time plus its lifetime less 1.

id

The agent instance’s unique ID within a simulation.

in_family_tree()

Returns true if this agent is in the parent-child family tree of an other agent.

infile_to_db()

A dynamic version of InfileToDb(InfileTree*, DbInit) that should work for all subclasses. Users should not need to call this ever. However, brave users may choose to override it in exceptional cases.

init_from_agent()

A dynamic version of InitFrom(Agent) that should work for all subclasses. Users should not need to call this ever. However, brave users may choose to override it in exceptional cases.

init_from_dict()

An initializer that reads state varaible values from a dictionary. This is used when InitFrom(QueryableBackend) is called. Users should not need to call this ever. However, brave users may choose to override it in exceptional cases.

init_inv()

An initializer that sets up inventories. This is used when InitInv(Inventories&) is called. Users should not need to call this ever. However, brave users may choose to override it in exceptional cases.

kind

Returns a string that describes the agent subclass (e.g. Region, Facility, etc.)

lifetime

The number of time steps this agent operates between building and decommissioning (-1 if the agent has an infinite lifetime)

niche = None
parent()

Returns parent of this agent. Returns None if the agent has no parent.

parent_id

The id for this agent’s parent or -1 if this agent has no parent.

prototype

The agent’s prototype.

schema

“The class schema based on the state variables.

snapshot()

A dynamic version of Snapshot(DbInit) that should work for all subclasses. Users should not need to call this ever. However, brave users may choose to override it in exceptional cases.

snapshot_inv()

A dynamic version of SnapshotInv() that reports the current state of the inventories. Users should not need to call this ever. However, brave users may choose to override it in exceptional cases.

spec

The agent’s spec.

tick()

This function is called each time step and is meant to be overlaoded in the subclass.

tock()

This function is called each time step and is meant to be overlaoded in the subclass.

tooltip = None
tree_strs()

Returns a list of children strings representing the parent-child tree at the node for Agent m.

userlevel = 0
version

Property that represents version of this archetype. Overwrite this to return a custom version string.

class cyclus.agents.Region

Python Region that is subclassable into a region archetype.

Parameters: ctx : cyclus.lib.Context The simulation execution context. You don’t normally need to call the initilaizer.
adjust_material_prefs()

adjust_product_prefs()

ancestor_of()

Returns true if this agent is an ancestor of an other agent (i.e., resides above an other agent in the family tree).

annotations

Agent annotations.

annotations_json
build()

Called when the agent enters the smiulation as an active participant and is only ever called once. Agents should NOT register for services (such as ticks/tocks and resource exchange) in this function. If agents implement this function, they must call their superclass’ Build function at the BEGINING of their Build function.

build_notify()

Called when a new child of this agent has just been built. It is possible for this function to be called before the simulation has started when initially existing agents are being setup.

children

A frozen set of the children of this agent.

children_str()

Returns recursively generated string of the parent-child tree.

context

Returns this agent’s simulation context.

decendent_of()

Returns true if this agent is an decendent of an other agent (i.e., resides above an other agent in the family tree).

decom_notify()

Called when a new child of this agent is about to be decommissioned.

decomission()

Decommissions the agent, removing it from the simulation. Results in destruction of the agent object. If agents write their own decommission() function, they must call their superclass’ decommission function at the END of their decommission() function.

enter_notify()

Called to give the agent an opportunity to register for services (e.g. ticks/tocks and resource exchange). Note that this may be called more than once, and so agents should track their registrations carefully. If agents implement this function, they must call their superclass’s EnterNotify function at the BEGINNING of their EnterNotify function.

enter_time

The time step at which this agent’s Build function was called (-1 if the agent has never been built).

entity = 'region'
exit_time

The default time step at which this agent will exit the simulation (-1 if the agent has an infinite lifetime).

Decomissioning happens at the end of a time step. With a lifetime of 1, we expect an agent to go through only 1 entire time step. In this case, the agent should be decommissioned on the same time step it was created. Therefore, for agents with non-infinite lifetimes, the exit_time will be the enter time plus its lifetime less 1.

id

The agent instance’s unique ID within a simulation.

in_family_tree()

Returns true if this agent is in the parent-child family tree of an other agent.

infile_to_db()

A dynamic version of InfileToDb(InfileTree*, DbInit) that should work for all subclasses. Users should not need to call this ever. However, brave users may choose to override it in exceptional cases.

init_from_agent()

A dynamic version of InitFrom(Agent) that should work for all subclasses. Users should not need to call this ever. However, brave users may choose to override it in exceptional cases.

init_from_dict()

An initializer that reads state varaible values from a dictionary. This is used when InitFrom(QueryableBackend) is called. Users should not need to call this ever. However, brave users may choose to override it in exceptional cases.

init_inv()

An initializer that sets up inventories. This is used when InitInv(Inventories&) is called. Users should not need to call this ever. However, brave users may choose to override it in exceptional cases.

kind

Returns a string that describes the agent subclass (e.g. Region, Facility, etc.)

lifetime

The number of time steps this agent operates between building and decommissioning (-1 if the agent has an infinite lifetime)

niche = None
parent()

Returns parent of this agent. Returns None if the agent has no parent.

parent_id

The id for this agent’s parent or -1 if this agent has no parent.

prototype

The agent’s prototype.

schema

“The class schema based on the state variables.

snapshot()

A dynamic version of Snapshot(DbInit) that should work for all subclasses. Users should not need to call this ever. However, brave users may choose to override it in exceptional cases.

snapshot_inv()

A dynamic version of SnapshotInv() that reports the current state of the inventories. Users should not need to call this ever. However, brave users may choose to override it in exceptional cases.

spec

The agent’s spec.

tick()

This function is called each time step and is meant to be overlaoded in the subclass.

tock()

This function is called each time step and is meant to be overlaoded in the subclass.

tooltip = None
tree_strs()

Returns a list of children strings representing the parent-child tree at the node for Agent m.

userlevel = 0
version

Property that represents version of this archetype. Overwrite this to return a custom version string.