Cyclus Library Bindings (cyclus.lib)

Python wrapper for cyclus.

class cyclus.lib.Agent

The abstract base class used by all types of agents that live and interact in a simulation.

ancestor_of(other)

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.

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(other)

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

decommission()

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_time

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

exit_time

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

Decommissioning 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(other)

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

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)

lifetime_force(n_timesteps)

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

An agent’s xml rng schema for initializing from input files. All concrete agents should override this function. This must validate the same xml input that the InfileToDb function receives.

spec

The agent’s spec.

tree_strs(m)

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

version

Agent version string.

class cyclus.lib.AgentSpec

AgentSpec C++ wrapper

Parameters:

spec : str or None, optional

This repesents either the full string form of the spec or just the path.

lib : str or None, optional

agent : str or None, optional

alias : str or None, optional

agent

alias

lib

path

sanatize()

class cyclus.lib.ColumnInfo

Python wrapper for ColumnInfo

col

dbtype

index

shape

table

class cyclus.lib.Context

A simulation context provides access to necessary simulation-global functions and state. All code that writes to the output database, needs to know simulation time, creates/builds facilities, and/or uses loaded composition recipes will need a context pointer. In general, all global state should be accessed through a simulation context.

Parameters:

timer : Timer, optional

An instance of the timer class.

recorder : Recorder, optional

An instance of the recorder class.

init : bool, optional

Whether or not to initialize a new context object.

Warning

• The context takes ownership of and manages the lifetime/destruction of all agents constructed with it (including Cloned agents). Agents should generally NEVER be allocated on the stack.

• The context takes ownership of the solver and will manage its destruction.

add_recipe(name, comp, basis)

Adds a new recipe to a simulation

Parameters:

name: str

name for recipe

comp: dict

dictionary mapping nuclides to their compostion fraction

basis: str

‘atom’ or ‘mass’ to specify the type of composition fraction

del_agent(agent)

Destructs and cleans up an agent (and it’s children recursively).

dt

The length of timer per time step, in seconds.

get_recipe(name, basis='mass')

Retrieve a registered recipe. This is intended for retrieving compositions loaded from an input file(s) at the start of a simulation and NOT for communicating compositions between facilities during the simulation. You must provide the basis as either “mass” or “atom”.

new_datum(title)

Returns a new datum instance.

schedule_build(parent, proto_name, t=-1)

Schedules the named prototype to be built for the specified parent at timestep t. The default t=-1 results in the build being scheduled for the next build phase (i.e. the start of the next timestep).

schedule_decom(agent, t=-1)

Schedules the given Agent to be decommissioned at the specified timestep t. The default t=-1 results in the decommission being scheduled for the next decommission phase (i.e. the end of the current timestep).

sim_id

The simulation ID.

time

The simulation time step number.

class cyclus.lib.Datum

Datum class.

add_val(field, value, shape=None, type=None)

Adds Datum value to current record as the corresponding cyclus data type.

Parameters:

field : str or bytes

The column name.

value : object

Value in table column, optional

shape : list or tuple of ints

Length of value.

type : dbtype or norm type

Data type as defined by cyclus typesystem

Returns:

self : Datum

record()

Records the Datum.

title

The datum name.

class cyclus.lib.DbInit

DbInit provides an interface for agents to record data to the output db that automatically injects the agent’s id and current timestep alongside all recorded data. The prefix ‘AgentState’ + [spec] (e.g. MyReactor) is also added to the datum title.

Parameters:

free : bool, optional

Whether or not to free the C++ instance on deallocation.

new_datum(title)

Returns a new datum to be used exactly as the Context.new_datum() method. Users must not add fields to the datum that are automatically injected: ‘SimId’, ‘AgentId’, and ‘SimTime’.

class cyclus.lib.DynamicModule

Dynamic Module wrapper class.

close_all()

Closes all dynamic modules.

exists(spec)

Tests whether an agent spec exists.

static make(ctx, spec)

Returns a newly constructed agent for the given module spec.

Parameters:

ctx : Context

spec : AgentSpec or str

Returns:

rtn : Agent

path

class cyclus.lib.Env

Environment wrapper class.

An environment utility to help locate files and find environment settings. The environment for a given simulation can be accessed via the simulation’s Context.

allow_milps

whether or not Cyclus should allow Mixed-Integer Linear Programs The default depends on a compile time option DEFAULT_ALLOW_MILPS, but may be specified at run time with the ALLOW_MILPS environment variable.

build_path

The Cyclus build path.

cyclus_path

A tuple of strings representing where cyclus searches for modules.

env_delimiter

the correct environment variable delimiter based on the file system.

static find_module(path)

Returns the full path to a module by searching through default install and CYCLUS_PATH directories.

static get(var)

Obtains an environment variable.

install_path

The Cyclus install path.

nuc_data

The nuc_data path.

static path_base(path)

Effectively basename

path_delimiter

the correct path delimiter based on the file system.

static rng_schema(flat=False)

Returns the current rng schema. Uses CYCLUS_RNG_SCHEMA env var if set; otherwise uses the default install location. If using the default ocation, set flat=True for the default flat schema.

static set_nuc_data_path(path=None)

Initializes the path to the cyclus_nuc_data.h5 file

By default, it is assumed to be located in the path given by GetInstallPath()/share; however, paths in environment variable CYCLUS_NUC_DATA are checked first.

class cyclus.lib.FullBackend

Full backend cyclus database interface.

query(table, conds=None)

Queries a database table.

Parameters:

table : str

The table name.

conds : iterable, optional

A list of conditions.

Returns:

results : pd.DataFrame

Pandas DataFrame the represents the table

schema(table)

tables

Retrieves the set of tables present in the database.

class cyclus.lib.Hdf5Back

HDF5 backend cyclus database interface.

close()

Closes the backend, flushing it in the process.

flush()

Flushes the database to disk.

name

The name of the database.

query(table, conds=None)

Queries a database table.

Parameters:

table : str

The table name.

conds : iterable, optional

A list of conditions.

Returns:

results : pd.DataFrame

Pandas DataFrame the represents the table

schema(table)

tables

Retrieves the set of tables present in the database.

class cyclus.lib.InfileTree

A class for extracting information from a given XML parser

Parameters:

free : bool, optional

Whether or not to free the C++ instance on deallocation.

classmethod from_parser(parser)

Initializes an input file tree from an XML parser.

Parameters:

parser : XMLParser

An XMLParser instance.

nmatches(query)

Investigates the current status and returns the number of elements matching a query.

Parameters:

query : str

The XML path to count.

Returns:

n : int

The number of query matches.

optional_query(query, default)

A query method for optional parameters.

Parameters:

query : str

The XML path to test if it exists.

default : any type

The default value to return if the XML path does not exist in the tree. The type of the return value (str, bool, int, etc) is determined by the type of the default.

query(path, dbtype, index=0)

A query method for required parameters.

Parameters:

path : str

The XML path to test if it exists.

dbtype : str or int

Represents primitive type in type system. Note that only primitive types are queryable, by design, and not all primitive types. Blobs and UUIDs are not included because they cannot be lexically cast.

index : int, optional

The instance to query.

subtree(query, index=0)

Populates a child infile based on a query and index.

Parameters:

query : str

The XML path to test if it exists.

index : int, optional

The index of the queried element, default 0.

Returns:

sub : InfileTree

A sub-tree repreresenting the query and the index.

class cyclus.lib.Logger

A logging tool providing finer grained control over standard output for debugging and other purposes.

no_agent

Set whether or not agent/agent log entries should be printed

no_mem

report_level

Use to get/set the (global) log level report cutoff.

static to_log_level(text)

Converts a string into a corresponding LogLevel value.

For strings that do not correspond to any particular LogLevel enum value the method returns the LogLevel value LEV_ERROR. This method is primarily intended for translating command line verbosity argument(s) in appropriate report levels. LOG(level) statements

static to_string(level)

Converts a LogLevel enum value into a corrsponding string.

For a level argments that have no corresponding string value, the string BAD_LEVEL is returned. This method is primarily intended for translating LOG(level) statement levels into appropriate strings for output to stdout.

class cyclus.lib.Position

a basic class that stores the geographic location in latitude and longitude and follows the ISO 6709 standard. Longitude and Latitude is stored as seconds of degrees. This allows the coordinate elements such as degrees, minutes, and seconds to “remain on the integral portion of values, with the exception of decimal of seconds, avoiding loss of precision.” This is calculated by multiplying decimal degrees by 3600. example: 05.2169 -> 18780.84

distance(other)

Computes the distance between this object and another position.

latitude

longitude

update(latitude=None, longitude=None)

Updates the latitude and/or longitude

class cyclus.lib.Recorder

Cyclus recorder interface.

close()

Closes the recorder.

dump_count

The frequency of recording.

flush()

Flushes the recorder to disk.

inject_sim_id

Whether or not to inject the simulation id into the tables.

new_datum(title)

Returns a new datum instance.

register_backend(backend)

Registers a backend with the recorder.

sim_id

The simulation id of the recorder.

class cyclus.lib.SimInit

Handles initialization of a simulation from the output database. After calling Init, Restart, or Branch, the initialized Context, Timer, and Recorder can be retrieved.

Parameters:

recorder : Recorder

The recorder class for the simulation.

backend : QueryableBackend

A backend to use for this simulation.

context

Returns the initialized context. Note that either Init, Restart, or Branch must be called first.

timer

Returns the initialized timer. Note that either Init, Restart, or Branch must be called first.

class cyclus.lib.SqliteBack

SQLite backend cyclus database interface.

close()

Closes the backend, flushing it in the process.

flush()

Flushes the database to disk.

name

The name of the database.

query(table, conds=None)

Queries a database table.

Parameters:

table : str

The table name.

conds : iterable, optional

A list of conditions.

Returns:

results : pd.DataFrame

Pandas DataFrame the represents the table

schema(table)

tables

Retrieves the set of tables present in the database.

class cyclus.lib.Timer

Controls simulation timestepping and inter-timestep phases.

Parameters:

init : bool, optional

Whether or not we should initialize a new C++ Timer instance.

run_sim()

Runs the simulation.

class cyclus.lib.XMLFileLoader

Handles initialization of a database with information from a cyclus xml input file.

Create a new loader reading from the xml simulation input file and writing to and initializing the backends in the recorder. The recorder must already have the backend registered. schema_file identifies the main xml rng schema used to validate the input file. The format specifies the input file format from one of: “none”, “xml”, “json”, or “py”.

load_sim()

Load an entire simulation from the inputfile.

class cyclus.lib.XMLFlatLoader

Handles initialization of a database with information from a cyclus xml input file.

Create a new loader reading from the xml simulation input file and writing to and initializing the backends in the recorder. The recorder must already have the backend registered. schema_file identifies the main xml rng schema used to validate the input file. The format specifies the input file format from one of: “none”, “xml”, “json”, or “py”.

Notes

This is not a subclass of the XMLFileLoader Python bindings, even though the C++ class is a subclass in C++. Rather, they are duck typed by exposing the same interface. This makes handling the instance pointers in Cython a little easier.

load_sim()

Load an entire simulation from the inputfile.

class cyclus.lib.XMLParser

A helper class to hold xml file data and provide automatic validation.

Parameters:

filename : str, optional

Path to file to load.

format : str, optional

The format to read in as: “none”, “xml”, “json”, or “py”. Applies to either filename or raw, if given.

raw : str, optional

XML string to load.

cyclus.lib.boost_version()

Boost version.

cyclus.lib.call_listeners(tsname, agent, time, value)

Calls the time series listener functions of cyclus agents.

cyclus.lib.capsule_agent_to_py(agent, ctx)

Returns an agent from its id

cyclus.lib.coincbc_version()

Coin CBC version.

cyclus.lib.coinclp_version()

Coin CLP version.

cyclus.lib.core_version()

Cyclus core version.

cyclus.lib.dbopen(fname)

Opens a Cyclus database.

cyclus.lib.describe_version()

Describes the Cyclus version.

cyclus.lib.discover_metadata_in_cyclus_path()

Discover archetype metadata in cyclus path. Returns a Jason.Value object.

cyclus.lib.discover_specs(path, library)

Discover archetype specifications for a path and library. Returns a set of strings.

cyclus.lib.discover_specs_in_cyclus_path()

Discover archetype specifications that live recursively in CYCLUS_PATH directories. Returns a set of strings.

cyclus.lib.get_warn_as_error()

Returns the current value for wether warnings should be treated as errors.

cyclus.lib.get_warn_limit()

Returns the current warning limit.

cyclus.lib.hdf5_version()

HDF5 version.

cyclus.lib.json_to_py(s)

Converts a JSON string into an equivalent Python string

cyclus.lib.json_to_xml(s)

Converts a JSON string into an equivalent XML string

cyclus.lib.load_string_from_file(filename, format=None)

Loads an XML file from a path or from a string and a format (‘xml’, ‘json’, or ‘py’).

cyclus.lib.make_py_agent(libname, agentname, ctx_capsule)

Makes a new Python agent instance.

cyclus.lib.normalize_bid_portfolio(inp)

Normalizes a bid portfolio into a standard Python form, ready to be traded. Note that this does not include the bidder object.

cyclus.lib.normalize_request_portfolio(inp)

Normalizes a request portfolio into a standard Python form, ready to be traded. Note that this does not include the requester object.

cyclus.lib.py_to_json(s)

Converts a Python string into an equivalent JSON string

cyclus.lib.py_to_xml(s)

Converts a Python string into an equivalent XML string

cyclus.lib.record_time_series(tstype, agent, value)

Python hook into RecordTimeSeries for Python archetypes

Parameters:

tstype : int or string

Time series type flag; POWER, ENRICH_SWU, etc or the string flag.

agent : object

Python agent, usually self when called by an archetype.

value : float

The value being recorded in the time series.

cyclus.lib.set_warn_as_error(wae)

Sets whether warnings should be treated as errors.

cyclus.lib.set_warn_limit(wl)

Sets the warning limit.

cyclus.lib.sqlite3_version()

SQLite3 version.

cyclus.lib.version()

Returns string of the cyclus version and its dependencies.

cyclus.lib.xml2_version()

libxml 2 version.

cyclus.lib.xml_to_json(s)

Converts an XML string into an equivalent JSON string

cyclus.lib.xml_to_py(s)

Converts an XML string into an equivalent Python string

cyclus.lib.xmlpp_version()

libxml++ version.