Base Class Reference

This page outlines the three base classes for Flume: Analysis, State, and System.

class flume.base_classes.analysis.Analysis(obj_name: str, sub_analyses: list = [], **kwargs)

This is a base class for all derived analysis classes that establishes a set of common methods. For the variables and outputs that are stored as attributes of the class, data is stored in dictionaries with key-value pairs structured as “variable/output name” : State object that describes the variable/output.

__init__(obj_name: str, sub_analyses: list = [], **kwargs)

analyze(mode='real', debug_print=False): Performs the analysis procedure for the object after combining the objects into a list that contains the stack. For each analysis in the stack, connections are established between sub-analyses and primary-analyses and then the private _analyze method is called.

analyze_adjoint(debug_print=False): Performs the adjoint analysis for the object and propagates any computations back through other sub-analyses included in the stack. Internally, this is done by reversing through the stack performing the adjoint analysis for each individual object.

declare_design_vars(variables: list)

Declare design variables for the analysis object. This could be all of the variables for the object or a subset based on the user input to the method.

Parameters:: variables (list) – A list of strings which correspond to the variables that are to be included as design variables for the analysis object. This list is stored internally as an attribute and specifies which variables are included in adjoint tests.

get_global_name(local_name: str) → str

Gets the global name for an input local name. This function works for all parameters, variables, and outputs.

Parameters:: local_name (str) – A string that is the local name for a given parameter, variable, or output of the object.
Returns:: global_name – A string that is the global name for a given parameter, variable, or output of the object.
Return type:: str

get_output_metadata(outputs: list = ['all'], display_info=False) → dict

Gets the metadata associated with the outputs specified in the outputs list.

Parameters:

outputs (list) – A list of strings that specifies the local output names that are to be accessed. Default is “all”, which returns the metadata for all outputs for the object.

Returns:

out_meta (dict) – A dictionary of dictionaries for the specified outputs. Each sub-dictionary contains key-value pairs for the following information: variable type, shape (if applicable), and description.
display_info (bool) – Boolean value that dictates whether variable metadata should be displayed when this method is called. Default is False.

get_output_values(outputs: list = ['all'], display_data=False) → dict

Gets the values for the specified outputs.

Parameters:

outputs (list) – A list of strings that specifies the local output names that are to be returned. Default is “all”, which returns all of the outputs for the object.

Returns:

output_values (dict) – A dictionary that contains key-value pairs for the desired outputs based on the input to the function.
display_data (bool) – Boolean value that dictates whether output values should be displayed when this method is called. Default is False.

get_parameter_values(params: list = ['all'], display_data=False) → dict

Gets the values for the parameters specified in the parameters input list.

Parameters:

params (list) – A list of strings that specifies the local parameter names that are to be returned. Default is “all”, which returns all of the parameters for the object.

Returns:

param_values (dict) – A dictionary that contains key-value pairs for the desired parameters based on the input to the function.
display_data (bool) – Boolean value that dictates whether parameter values should be displayed when this method is called. Default is False.

get_var_derivs(variables=['all']) → dict

Gets the derivative values for the variables specified in the variables input list.

Parameters:: variables (list) – A list of strings that specifies the local variable names that are to be returned. Default is “all”, which returns all of the variables for the object.
Returns:: var_derivs – A dictionary that contains key-value pairs for the desired variable derivatives based on the input to the function.
Return type:: dict

get_var_metadata(variables: list = ['all'], display_info=False) → dict

Gets the metadata associated with the variables specified in the variables input list.

Parameters:

variables (list) – A list of strings that specifies the local variable names that are to be accessed. Default is “all”, which returns the metadata for all variables for the object.

Returns:

var_meta (dict) – A dictionary of dictionaries for the specified variables in the input. Each sub-dictionary contains key-value pairs for the following information: variable type, shape (if applicable), and description.
display_info (bool) – Boolean value that dictates whether variable metadata should be displayed when this method is called. Default is False.

get_var_values(variables=['all'], display_data=False) → dict

Gets the values for the variables specified in the variables input list.

Parameters:

variables (list) – A list of strings that specifies the local variable names that are to be returned. Default is “all”, which returns all of the variables for the object.

Returns:

var_values (dict) – A dictionary that contains key-value pairs for the desired variables based on the input to the function.
display_data (bool) – Boolean value that dictates whether variable values should be displayed when this method is called. Default is False.

set_var_values(variables: dict)

Sets the values for the varaibles based on the entries contained in the variables dictionary

Parameters:: variables (dict) – A dictionary that is structued with key-value pairs, where the key is the local name of the variable and the value is the numerical value to set for the variable.
Return type:: None, but internally State objects for the specified variables are updated with the provided values.

test_combined_adjoint(print_res=True, debug_print=False, method='cs', defined_vars={})

Tests the adjoint implementation for an analysis object and accounts for any sub-analyses within the stack.

Parameters:

debug_print (bool) – Boolean value that specifies whether debug print statements should be displayed
method (str) – Either ‘cs’ or ‘fd’, which specifies that the method to check against the adjoint implementation is complex-step or finite-difference, respectively
defined_vars (dictionary) – A dictionary where the keys correspond to the global variable names and the values are the numeric values that the variables should have. For example, if the user wants to set a variable ‘x’ for an analysis object ‘analysis’ to be value 1.0, defined_vars should be given as defined_vars = {‘analysis.x’: 1.0}.

test_isolated_adjoint(print_res=True, debug_print=False, method='cs', defined_vars={})

Tests the adjoint implementation for an analysis object (ignores any sub-analyses for the isolated case). Currently, only the complex-step method is implemented for this test, so calculations must be complex-safe.

Parameters:: defined_vars (dictionary) – Dictionary that specifies whether any variables that have defined values for the adjoint test. This is nominally empty, but is sometimes necessary for variables that have strict bounds.
Return type:: None, but displays results of adjoint analysis test

class flume.base_classes.state.State(value, desc: str, deriv=None, source=None)

This is a class to use for establishing a structure for variables and outputs of analysis classes.

Storing source information here will establish the flow of data between objects. Then, to access variable/output values one would do var[name].value; could do the same for source, deriv, etc.

__init__(value, desc: str, deriv=None, source=None)

set_deriv_value(deriv_val)

Helper method to set the derivative value for a State object.

Parameters:: deriv_val (float or numpy.ndarray) – The value fo the derivative for the State object.
Return type:: None

class flume.base_classes.system.System(sys_name: str, top_level_analysis_list: List[Analysis], log_name: str = 'flume.log', log_prefix: str = '.')

This class is used to wrap multiple Analysis objects into a system, which can then be utilized to perform optimization using one of Flume’s optimizer interfaces.

__init__(sys_name: str, top_level_analysis_list: List[Analysis], log_name: str = 'flume.log', log_prefix: str = '.')

Defines a class that wraps multiple analysis objects into a single system, which can then be utilized to perform optimization with one of Flume’s optimizer interfaces after declaring design varaibles, an objective function, and (optionally) constraints.

Parameters:

sys_name (str) – Name that is assigned to the System
top_level_analysis_list (list) – A list of instances of Analysis objects that will be utilized within the optimization problem. Here, the objects that should be provided are the analyses that define the objective function and any constraint functions so that these can be declared for the optimization formulation. Other Analysis classes, such as those used as sub-analyses, do not need to be provided here, as they should be provided when creating the objects in the top-level analysis list
log_name (str) – String that defines the name to use for the log file, defaults to ‘flume.log’
log_prefix (str) – String that defines the output directory where the log file and other files are saved, defaults to the current directory ‘.’

assemble_full_analysis_list(): Assembles the full list of analyses that comprise the overall system architecture.

declare_constraints(global_con_name: dict)

Sets the constraints for the optimization problem according to the provided global output names.

Parameters:

global_con_name_dict (dict) –

This is a dictionary of dictionaries. The keys correspond to the global output names for the constraints. The inner dictionary specifies additional information about the structure of the constriant, including the following:

’rhs’ (float) - specifies the right hand side of the constraint equation. Internally, the optimizer interfaces will use this to convert the constraint to an equivalent form that normalizes it, If the ‘rhs’ value is 0.0, no scaling is applied
’direction’ (str) - string that is either ‘geq’ (>=), ‘leq’ (<=), or ‘both’ (=). Defaults to ‘geq’ in the event that a direction is not provided.

Example

Here, the constraints are defined as follows:: x <= 1.0 y >= 1.0 z = 2.0
Thus, the argument here is given as: global_con_name = {: “block1.x”:{“direction”:”leq”, “rhs”:1.0}, “block2.y”:{“rhs”:1.0} “block3.z”:{“direction”: “both”, “rhs”: 2.0} }

declare_design_vars(global_var_name: dict)

Sets the design variables for the system according to the provided global variable names.

Parameters:: global_var_name (dict) – This is a dictionary of dictionaries. Keys for the first dictionary correspond to the global variable names that should be added to the set of design variables, and the values contain information about the variable bounds. If the inner dictionary is empty, then no bounds are provided. Otherwise, the values for the variables lower bound ‘lb’ and upper bound ‘ub’ will be added, if included.

Example

Here, the bounds are defined as follows:: 1.0 <= x <= 2.0 y has no bounds 0.0 <= z

Thus, the argument here is: global_var_name = {“block1.x”:{“lb”:1.0, “lb”:2.0}, “block2.y”:{}, “block3.z”:{“lb”:0.0}}

declare_foi(global_foi_name: list): Sets the functions of interest that are to be tracked by the logger at each iteration. Here, the names must be provided according to their global names. If already declared, the objective and constraints are added by default, but other outputs can be included.

declare_objective(global_obj_name, obj_scale=1.0)

Sets the objective function for the optimization problem according to the provided global output name. This output should be associated with one of the top-level analyses for the system (i.e. included in the top_level_analysis_list).

Parameters:

global_obj_name (str) – A string that specifies the global name for the value that is to be used as the objective function (global name meaning ‘object_name.local_output_name’)
obj_scale (float) – Float value that is multiplied by the value of the objective function, which should scale the objective function value to O(1). This is used by the optimizer interfaces internally to scale the objective.

graph_network(filename: str = None, output_directory: str = None, interactive: bool = False)

Construct the visualization of the network associated with the Flume system using graphviz.

Parameters:

filename (str) – Name to use for the file that is created
output_directory (str) – String that defines the directory where the file should be saved
interactive (bool) – Boolean value that indicates whether the graph should be output in interactive mode. This is an experimental feature at the moment

log_information(iter_number)

Helper function that is used to log the values for the objective function, constraints, and other functions of interest at each iteration. Internally, this will update the log file for the System with this information at every iteration.

Parameters:: iter_number (int) – Current iteration number

profile_iteration(iter_number)

Helper function that is used to display the time taken for each analyze and analyze_adjoint method at the current iteration. Internally, this updates a profile log file that stores the timing information for the System at each iteration.

Parameters:: iter_number (int) – Current iteration number

reset_analysis_flags(it_counter): Resets all of the analysis flags for all analyses within the system to be False. This is done when variable values are updated, as all systems must be analyzed again to propagate chanes in design variable values.