Reference¶
Description language¶
Identifier conventions¶
Identifiers whose names start with the pattern <letters> are special. The following special variable names are supported:
Internal names¶
<p>NAME
This variable contains persistent state. (that survives from one step to the next)
<cond>NAME
This variable is used by a conditional. May not be re-defined.
<dt>
The time increment for the present time step.
Its value at the beginning of a step indicates the step size to be used. If a time step of this size cannot be completed, FailStep must be issued.
This variable contains persistent state. (that survives from one step to the next)
<t>
Base time of current time step.
The integrator code is responsible for incrementing <t> at the end of a successful step.
This variable contains persistent state. (that survives from one step to the next)
User-controlled values¶
<state>NAME
State identifier under user (=scheme writer) control
This variable contains persistent state. (that survives from one step to the next)
<ret_time_id>COMPONENT_ID
<ret_time>COMPONENT_ID
<ret_state>COMPONENT_ID
For targets that are incapable of returning state mid-step, these variables are used to store computed state.
See dagrt.function_registry
for interpretation of function names. The
function namespace and the variable namespace are distinct. No user-defined
identifiers should start with dagrt_.
Statements¶
- class dagrt.language.Statement(**kwargs)¶
Assignment Statements¶
These statements perform updates to the execution state, i.e. the variables.
- class dagrt.language.AssignImplicit(assignees, solve_variables, expressions, other_params, solver_id, **kwargs)¶
- assignees¶
A tuple of strings. The names of the variables to assign with the results of solving for solve_variables
- solve_variables¶
A tuple of strings, the names of the variables being solved for
- expressions¶
A tuple of expressions, which represent the left hand sides of a system of (possibly nonlinear) equations. The solver will attempt to find a simultaneous root of the system.
- other_params¶
A dictionary used to pass extra arguments to the solver, for instance a starting guess
- solver_id¶
An identifier for the solver that is to be used to solve the system. This identifier is intended to match information about solvers which is supplied by the user.
- class dagrt.language.Assign(assignee=None, assignee_subscript=None, expression=None, loops=None, **kwargs)¶
- loops¶
A list of triples (identifier, start, end) that the assignment should be carried out inside of these loops. No ordering of loop iterations is implied. The loops will typically be nested outer-to-inner, but a target may validly use any order it likes.
- class dagrt.language.AssignFunctionCall(assignees, function_id, parameters, kw_parameters=None, **kwargs)¶
This statement encodes function calls. It should be noted that function calls can also be encoded as expressions involving calls, however the existence of this separate statement is justified by two facts:
Some backends (such as Fortran) choose to separate out function calls into individual statements. This statement provides a natural way to encode them.
See
dagrt.codegen.transform.isolate_function_calls
for a transform that accomplishes this.Calling functions with multiple return values is not supported as part of dagrt’s language.
- assignees¶
A tuple of variables to be passed assigned results from calling
function_id
.
- function_id¶
- parameters¶
A list of expressions to be passed as positional arguments.
- kw_parameters¶
A dictionary mapping names to expressions to be passed as keyword arguments.
Control Statements¶
These statements affect the execution of a phase, or cause a phase to interact with user code.
- class dagrt.language.Raise(error_condition, error_message=None, **kwargs)¶
- error_condition¶
A (Python) exception type to be raised.
- error_message¶
The error message to go along with that exception type.
- class dagrt.language.FailStep(**kwargs)¶
Exits the current step with a failure indication to the controlling program. Execution resumes with the next step as normal.
Miscellaneous Statements¶
- class dagrt.language.Nop(**kwargs)¶
Code Container¶
- class dagrt.language.ExecutionPhase(name, next_phase, statements)¶
- name¶
name of this phase
- depends_on¶
a list of statement IDs that need to be executed to complete a successful execution of one round of this phase, excluding their dependencies.
- next_phase¶
name of the next state after this one, if no other state is specified by the user.
- statements¶
is a list of statement instances in no particular order.
- class dagrt.language.DAGCode(phases, initial_phase)¶
- phases¶
is a map from time integrator phase names to
ExecutionPhase
instances
- initial_phase¶
the name of the starting phase
Visualization¶
- dagrt.language.get_dot_dependency_graph(code, use_stmt_ids=False)¶
Return a string in the dot language depicting dependencies among kernel statements.
- dagrt.language.show_dependency_graph(*args, **kwargs)¶
Show the dependency graph generated by
get_dot_dependency_graph()
in a browser. Accepts the same arguments as that function.
Code Creation¶
- class dagrt.language.CodeBuilder(name)¶
- name¶
The name of the phase being generated
- statements¶
The set of statements generated for the phase
Language support:
- assign(assignees, expression, loops=None)¶
Generate code for an assignment.
assignees may be a variable, a subscript (if referring to an array), or a tuple of variables. There must be exactly one assignee unless expression is a function call.
loops is a list of tuples of the form (identifier, start_index, stop_index).
- assign_implicit(assignees, solve_components, expressions, other_params, solver_id)¶
- yield_state(expression, component_id, time, time_id)¶
Yield a value.
- fail_step()¶
- raise_(error_condition, error_message=None)¶
- switch_phase(next_phase)¶
Control flow:
- if_(*condition_arg)¶
Create a new block that is conditionally executed.
- else_()¶
Create the “else” portion of a conditionally executed block.
Context manager:
- __enter__()¶
- __exit__(*ignored)¶
Graph generation:
- as_execution_phase(next_phase)¶
Return the generated graph as an
ExecutionPhase
.- Parameters
next_phase – The name of the default next phase
Convenience functions:
- __call__()¶
Alias for
CodeBuilder.assign()
.
- assign_implicit_1(assignee, solve_component, expression, guess, solver_id=None)¶
Special case of AssignImplicit when there is 1 component to solve for.
- fresh_var_name(prefix='temp')¶
Return a variable name that is not in use also and won’t be returned in the future, regardless of use.
- fresh_var(prefix='temp')¶
- restart_step()¶
Equivalent to switch_phase(self.name).
Code generation¶
Python¶
- class dagrt.codegen.python.CodeGenerator(class_name, class_preamble=None, function_registry=None)¶
- __init__(class_name, class_preamble=None, function_registry=None)¶
- Parameters
class_name – The name of the class to generate
class_preamble – A string to include at the beginning of the the class (in class scope)
function_registry – An instance of
dagrt.function_registry.FunctionRegistry
- __call__(dag)¶
- Returns
a class adhering to
StepperInterface
.
- class dagrt.codegen.python.StepperInterface¶
The interface adhered to by
dagrt
steppers expressed in Python.- next_phase¶
- StateComputed¶
An event yielded by
run_single_step
andrun
. Seedagrt.exec_numpy.StateComputed
.
- StepCompleted¶
An event yielded by
run_single_step
andrun
. Seedagrt.exec_numpy.StepCompleted
.
- StepFailed¶
An event yielded by
run_single_step
andrun
. Seedagrt.exec_numpy.StepFailed
.
- abstract set_up(t_start, dt_start, context)¶
- abstract run(t_end=None, max_steps=None)¶
Execute the stepper until either time reaches t_end or max_steps have been taken. Generates (in the Python
yield
sense) events that occurred during execution along the way.
- abstract run_single_step()¶
Execute a single phase of the stepper. Generates (in the Python
yield
sense) events that occurred during execution along the way.
Fortran¶
Types¶
Code Generator¶
Function registry¶
The function registry is used by targets to resolve external functions and invoke user-specified code, including but not limited to ODE right-hand sides.
- class dagrt.function_registry.Function(language_to_codegen=None, **kwargs)¶
- result_names¶
A list of names of the return values of the function. Note that these names serve as documentation and as identifiers to be used for variables receiving function results inside generated code implementing the call to the function (e.g. in the Fortran backend). They have no relationship to the names to which the results ultimately get assigned.
- identifier¶
The name of the function.
- arg_names¶
The names of the arguments to the function.
- default_dict¶
A dictionary mapping argument names to default values.
- get_result_kinds(arg_kinds, check)¶
Return a tuple of the
dagrt.data.SymbolKind
instances for the values this function returns if arguments of the kinds arg_kinds are supplied.The length of the returned tuple must match the lenght of
result_names
.- Parameters
arg_kinds – a dictionary mapping numbers (for positional arguments) or identifiers (for keyword arguments) to
dagrt.data.SymbolKind
instances indicating the types of the arguments being passed to the function. Some elements of arg_kinds may be None if their kinds have yet not been determined.check – A
bool
. If True, none of arg_kinds will be None, and argument kind checking should be performed.
- register_codegen(language, codegen_function)¶
Return a copy of self with codegen_function registered as a code generator for language.
The interface for codegen_function depends on the code generator being used.
- get_codegen(language)¶
Return the code generator for language.
- resolve_args(arg_dict)¶
Resolve positional and keyword arguments to an argument list.
See also
dagrt.utils.resolve_args()
.- Parameters
arg_dict – a dictionary mapping numbers (for positional arguments) or identifiers (for keyword arguments) to values
- class dagrt.function_registry.FunctionRegistry(id_to_function=None)¶
- register(function)¶
Return a copy of self with function registered.
- __getitem__(function_id)¶
Return the
Function
with identifier function_id.- Raises
FunctionNotFound – when function_id was not found
- __contains__(function_id)¶
- register_codegen(function_id, language, codegen)¶
Register a code generation helper object for target language for the function with identifier function_id.
- Parameters
codegen – an object obeying an interface suitable for code generation for language. This interface depends on the code generator being used.
- get_codegen(function_id, language)¶
- class dagrt.function_registry.FunctionNotFound¶
- dagrt.function_registry.base_function_registry¶
The default function registry, containing all the built-in functions (see Built-ins).
Registering new functions¶
- dagrt.function_registry.register_ode_rhs(function_registry, output_type_id, identifier=None, input_type_ids=None, input_names=None)¶
Register a function as an ODE right-hand side.
Functions registered through this call have the following characteristics. First, there is a single return value of the user type whose type identifier is output_type_id. Second, the function has as its first argument a scalar named t. Last, the remaining argument list to the function consists of user type values.
For example, considering the ODE \(y' = f(t, y)\), the following call registers a right-hand side function with name f and user type y:
freg = register_ode_rhs(freg, "y", identifier="f")
- Parameters
function_registry – the base function registry
output_type_id – a string, the user type ID returned by the call.
identifier – the full name of the function. If not provided, defaults to <func> + output_type_id.
input_type_ids – a tuple of strings, the identifiers of the user types which are the arguments to the right-hand side function. An automatically added t argument occurs before these arguments. If not provided, defaults to (output_type_id,).
input_names – a tuple of strings, the names of the inputs. If not provided, defaults to input_type_ids.
- Returns
a new
FunctionRegistry
- dagrt.function_registry.register_function(function_registry, identifier, arg_names, default_dict=None, result_names=(), result_kinds=())¶
Register a function returning output(s) of fixed kind.
- Parameters
function_registry – the base
FunctionRegistry
identifier – a string, the function identifier
arg_names – a list of strings, the names of the arguments
default_dict – a dictionary mapping argument names to default values
result_names – a list of strings, the names of the output(s)
result_kinds – a list of
dagrt.data.SymbolKind
s, the kinds of the output(s)
- Returns
a new
FunctionRegistry
Built-ins¶
The built-in functions are listed below. This also serves as their language documentation.
- class dagrt.function_registry.Norm1(language_to_codegen=None, **kwargs)¶
norm_1(x)
returns the 1-norm of x. x is a user type or array.
- class dagrt.function_registry.Norm2(language_to_codegen=None, **kwargs)¶
norm_2(x)
returns the 2-norm of x. x is a user type or array.
- class dagrt.function_registry.NormInf(language_to_codegen=None, **kwargs)¶
norm_inf(x)
returns the infinity-norm of x. x is a user type or array.
- class dagrt.function_registry.DotProduct(language_to_codegen=None, **kwargs)¶
dot_product(x, y)
return the dot product of x and y. The complex conjugate of x is taken first, if applicable. x and y are either arrays (that must be of the same length) or the same user type.
- class dagrt.function_registry.Len(language_to_codegen=None, **kwargs)¶
len(x)
returns the number of degrees of freedom in x. x is a user type or array.
- class dagrt.function_registry.IsNaN(language_to_codegen=None, **kwargs)¶
isnan(x)
returns True if and only if there are any NaNs in x. x is a user type, scalar, or array.
- class dagrt.function_registry.Array_(language_to_codegen=None, **kwargs)¶
array(n)
returns an empty array with n entries in it. n must be an integer.
- class dagrt.function_registry.MatMul(language_to_codegen=None, **kwargs)¶
matmul(a, b, a_cols, b_cols)
returns a 1D array containing the matrix resulting from multiplying the arrays a and b (both interpreted as matrices, with a number of columns a_cols and b_cols respectively).
- class dagrt.function_registry.Transpose(language_to_codegen=None, **kwargs)¶
transpose(a, a_cols)
returns a 1D array containing the matrix resulting from transposing the array a (interpreted as a matrix with a_cols columns).
- class dagrt.function_registry.LinearSolve(language_to_codegen=None, **kwargs)¶
linear_solve(a, b, a_cols, b_cols)
returns a 1D array containing the matrix resulting from multiplying the matrix inverse of a by b, both interpreted as matrices, with a number of columns a_cols and b_cols respectively.
- class dagrt.function_registry.SVD(language_to_codegen=None, **kwargs)¶
SVD(a, a_cols)
returns a 2D arrayu
, a 1D arraysigma
, and a 2D arrayvt
, representing the (reduced) SVD ofa
.
- class dagrt.function_registry.Print(language_to_codegen=None, **kwargs)¶
print(arg)
prints the given operand to standard output. Returns an integer that may be ignored.
Data¶
The module dagrt.data
provides symbol kind information and kind
inference.
Symbol kinds¶
- class dagrt.data.SymbolKind(valuedict=None, exclude=None, **kwargs)¶
Base class for kinds encountered in the
dagrt
language.
- class dagrt.data.Boolean(valuedict=None, exclude=None, **kwargs)¶
A boolean.
- class dagrt.data.Integer(valuedict=None, exclude=None, **kwargs)¶
An integer.
- class dagrt.data.Scalar(is_real_valued)¶
A (real or complex) floating-point value.
- is_real_valued¶
Whether the value is definitely real-valued
Symbol kind inference¶
- class dagrt.data.SymbolKindTable¶
A mapping from symbol names to kinds for a program.
- global_table¶
a mapping from symbol names to
SymbolKind
instances, for global symbols
- per_phase_table¶
a nested mapping
[phase_name][symbol_name]
toSymbolKind
instances
- class dagrt.data.UnableToInferKind¶
- class dagrt.data.SymbolKindFinder(function_registry)¶
- __call__(names, phases)¶
Infer the kinds of all the symbols in a program.
- Parameters
names – a list of phase names
phases – a list of iterables, each yielding the statements in a phase
- Returns
- Raises
UnableToInferKind – kind inference could not complete sucessfully
Helper functions¶
- dagrt.data.infer_kinds(dag, function_registry=None)¶
Run kind inference on a
dagrt.language.DAGCode
.- Parameters
dag – a
dagrt.language.DAGCode
function_registry – if not None, the function registry to use
- Returns
- dagrt.data.collect_user_types(skt)¶
Collect all of the of
UserType
identifiers in a table.- Parameters
skt – a
SymbolKindTable
- Returns
a set of strings
Transformations¶
- dagrt.codegen.transform.eliminate_self_dependencies(dag)¶
- dagrt.codegen.transform.isolate_function_arguments(dag)¶
- dagrt.codegen.transform.isolate_function_calls(dag)¶
isolate_function_arguments()
should be called before this.
- dagrt.codegen.transform.expand_IfThenElse(dag)¶
Turn IfThenElse expressions into values that are computed as a result of an If statement. This is useful for targets that do not support ternary operators.
Utilities¶
Random usefulness
- class dagrt.codegen.utils.KeyToUniqueNameMap(start=None, forced_prefix='', key_translate_func=<function make_identifier_from_name>, name_generator=None)¶
Maps keys to unique names that are created on-the-fly.
Before a unique name is created, a base name is first created. The base name consists of a forced prefix followed by a string that results from translating the key with a supplied function. The mapped value is then created from the base name.
- dagrt.codegen.utils.remove_common_indentation(text)¶
- Parameters
text – a multi-line string
- Returns
a list of lines
- dagrt.codegen.utils.wrap_line_base(line, level=0, width=80, indentation=' ', pad_func=<function <lambda>>, lex_func=None)¶
The input is a line of code at the given indentation level. Return the list of lines that results from wrapping the line to the given width. Lines subsequent to the first line in the returned list are padded with extra indentation. The initial indentation level is not included in the input or output lines.
The pad_func argument is a function that adds line continuations. The lex_func argument returns the list of tokens in the line.
Dumping ground of miscellaneous helpfulness.
- exception dagrt.utils.TODO¶
- class dagrt.utils.TemporaryDirectory(suffix='', prefix='tmp', dirname=None)¶
Create and return a temporary directory. This has the same behavior as mkdtemp but can be used as a context manager. For example:
- with TemporaryDirectory() as tmpdir:
…
Upon exiting the context, the directory and everything contained in it are removed.
- dagrt.utils.get_unique_name(prefix, *name_sets)¶
Return a name that begins with prefix and is not found in any of the name sets.
- dagrt.utils.get_variables(expr, include_function_symbols=False)¶
Returns the set of names of variables used in the expression.
- dagrt.utils.is_state_variable(var)¶
Check if the given name corresponds to a state variable.
- dagrt.utils.resolve_args(arg_names, default_dict, arg_dict)¶
Resolve positional and keyword arguments to a single argument list.
- Parameters
arg_dict – a dictionary mapping numbers (for positional arguments) or identifiers (for keyword arguments) to values
default_dict – a dictionary mapping argument names to default values
arg_names – names of the positional arguments
numpy
-based interpretation¶
- class dagrt.exec_numpy.StateComputed(t, time_id, component_id, state_component)¶
- t¶
- time_id¶
- component_id¶
Identifier of the state component being returned.
- state_component¶
- class dagrt.exec_numpy.StepCompleted(dt, t, current_state, next_phase)¶
- dt¶
Size of next time step.
- t¶
Approximate integrator time at end of step.
- current_state¶
- next_phase¶
- exception dagrt.exec_numpy.FailStepException¶
- class dagrt.exec_numpy.TransitionEvent(next_phase)¶
- class dagrt.exec_numpy.NumpyInterpreter(code, function_map)¶
A
numpy
-targeting interpreter for the time integration language defined indagrt.language
.Implements
- next_phase¶
- StateComputed¶
- StepCompleted¶
- StepFailed¶
- set_up(t_start, dt_start, context)¶
- Parameters
context – a dictionary mapping identifiers to their values
- run(t_end=None, max_steps=None)¶
Generates events.
- run_single_step()¶