Interfaces Reference

This page outlines the optimizer interfaces supported by Flume, which currently include SciPy, ParOpt, and pyOptSparse.

class flume.interfaces.scipy_interface.FlumeScipyInterface(flume_sys: System, callback=None)
__init__(flume_sys: System, callback=None)

Creates an interface that is used to link an instance of a Flume System to SciPy’s optimize minimize function to perform numerical optimization.

Parameters:

  • flume_sys (System) – Instance of a Flume System that represents the problem to be solved with ParOpt

  • callback (callable function, default None) – This is a callable function that gets executed during every iteration of the evalObjCon method during optimization. See below for the structure of the function

  • update (callable function, default None) – This is a callable function that gets executed at the start of every iteration of the evalObjCon method during optimization. Nominally, this is used to do parameter updates, such as for a continuation strategy

get_default_options(method, maxit=100)

Get the dictionary of default options that are used when calling SciPy minimize.

Parameters:

  • method (str) – String that specifies the method used for the optimization

  • maxit (int) – Maximum number of iterations for the optimization problem

Returns:

options – Dictionary of default options for the optimization.

Return type:

dict

optimize_system(x0, options=None, method='SLSQP', maxit=100)

Function that the user calls to execute SciPy’s optimize minimize function.

Parameters:

  • x0 (np.ndarray) – Initial point for the optimization procedure

  • options (None or dict) – Default is None, otherwise this is a dictionary of options to provide to the minimize function

  • method (str) – String that specifies the method used for the optimization, defaults to SLSQP

  • maxit (int) – Maximum number of iterations for the optimization problem, defaults to 100

  • callback_func (callable function) – Optional callable function that the user can provide to override the default callback function, which calls Flume’s default log function after each iteration.

Returns:

  • res.x (np.ndarray) – Solution array after the optimization

  • res (SciPy OptimizeResult) – OptimizeResult instance from the numerical optimization (see SciPy documentation for additional details)

set_initial_point(initial_global_vars: dict)

Helper function that maps the design variables provided in the initial_global_vars dictionary to the array that SciPy expects for the initial point.

Parameters:

initial_global_vars (dict) – Dictionary, where each key-value pair corresponds to a global variable name in the Flume system and its corresponding numeric value. E.g. for a variable named ‘x’ with initial value 1 associated with an object named ‘rosenbrock’, the entry in this dictionary is ‘rosenbrock.x’: 1.0.

Returns:

x0 – NumPy array that contains the values provided in the initial_global_vars dictionary, organized according to the start/end indices for each variable.

Return type:

np.ndarray

class flume.interfaces.paropt_interface.FlumeParOptInterface(flume_sys: System, callback=None, update=None)
__init__(flume_sys: System, callback=None, update=None)

Creates an interface that is used to link an instance of a Flume System to a ParOpt optimization problem. Note that at construction of the interface, each Analysis for the constraints is performed to determine the size for each constraint in the System.

Parameters:

  • flume_sys (System) – Instance of a Flume System that represents the problem to be solved with ParOpt

  • callback (callable function, default None) – This is a callable function that gets executed at the end of every iteration of the evalObjConGradient method during optimization. See below for the structure of the function

  • update (callable function, default None) – This is a callable function that gets executed at the start of every iteration of the evalObjCon method during optimization. Nominally, this is used to do parameter updates, such as for a continuation strategy

Note

The callback function is an arbitrary function that the user writes, and it will be called at the end of every evalObjConGradient execution. It is required that the function is setup such that it takes in two arguments:

def user_callback(x, it_number):

…

Here, the parameters are:

x : current design variable info for the problem it_number : current iteration number for the system

The update function is also a function that the user can optionally provide, and it will be called at the start of every evalObjCon execution. This method is primarily used for updating parameters within the Flume System (e.g. for continuation strategies in topology optimization), and it is structured as follows:

def user_update(it_number):

…

where it_number is the current iteration number for the system

construct_paropt_problem()

Function that creates the ParOpt problem that will be used for optimization

Returns:

paroptprob – Returns an instance of the ParOptProb class

Return type:

ParOptProb

evalObjCon(x)

Evaluates the objective and constraints for the problem using the current design variables.

Parameters:

x (ParOptVec) – Design variable vector at the current iteration

Returns:

  • fail (int) – Returns 0 if the method evaluates successfully

  • obj (float) – Value of the objective function

  • con_list (list) – List of the constraint values at the current design point

evalObjConGradient(x, g, A)

Evaluates the objective and constraint gradients for the system.

Parameters:

  • x (ParOptVec) – Design variable vector at the current iteration

  • g (ParOptVec) – Gradient of the objective function at x

  • A (ParOptVec) – Gradients of the constraints evaluated at x. For vector-valued constraints, each element of the constraint array occupies its own row in the constraint Jacobian

Returns:

fail – Returns 0 if the method evaluates successfully

Return type:

int

getVarsAndBounds(x, lb, ub)

Get the variable values and set the bounds for the optimization problem.

Parameters:

  • x (ParOptVec) – Design variable vector at the current iteration

  • lb (ParOptVec) – Vector containing the lower bounds to apply to the design variables in x

  • ub (ParOptVec) – Vector containing the ubber bounds to apply to the design variables in x

get_paropt_default_options(output_prefix, algorithm='tr', maxit=1000)

Get the default options for paropt.

Parameters:

  • output_prefix (str) – A string that specifies the directory where the output data should be stored

  • algorithm (str) – String that specifies the method to use, defaults to ‘tr’ which is trust-region

  • maxit (int) – Maximum number of iterations

Returns:

options – A dictionary containing the options that can be passed to ParOpt

Return type:

dict

optimize_system(algorithm: str = 'tr', options: dict = None, check_gradients: bool = False) → tuple[ndarray, float, list, paropt.ParOpt.Optimizer]

Performs optimization on the Flume System using ParOpt. Assumes that the user has set the expected initial values for the Flume Analysis instances prior to calling this method (otherwise the defaults for the Flume Analyses will be used).

Parameters:

  • algorithm (str) – String that specifies the algorithm to use for the optimization. Should be ‘tr’ (trust-region) or ‘mma’ (method of moving asymptotes)

  • options (dict) – Dictionary of options to use for ParOpt. If not provided, the default ParOpt options will be used for the specified algorithm (see ParOpt documentation for details)

  • check_gradients (bool) – When provided, executes the ParOpt finite difference gradient check for 3 iterations. Returns nothing when this is True. Defaults to False

Returns:

  • Assuming check_gradients is False, the following are returned

  • x_opt (np.ndarray) – Array of design variables at the final point

  • fstar (float) – Objective function value at the final point

  • con_star (list) – List of constraint function values at the final point

  • opt (ParOpt.Optimizer) – Instance of ParOpt’s Optimizer class (in case the user wants to extract any additional information)

  • If check_gradients is True, nothing is returned

set_system_variables(x)

Sets the variable values for the analysis objects contained within the System.

Parameters:

x (ParOptVec) – Design variable vector at the current iteration

class flume.interfaces.pyoptsparse_interface.FlumePyOptSparseInterface(flume_sys: System, callback=None, update=None)
__init__(flume_sys: System, callback=None, update=None)

Creates an interface that is used to link an instance of a Flume System to an optimization problem constructed and driven through pyOptSparse. To perform the numeric optimization, the user should call the optimize_system method after constructing this object.

Parameters:

  • flume_sys (System) – Instance of a Flume System that represents the problem to be solved with the interface

  • callback (callable function, default None) – This is a callable function that gets executed during every iteration of the _objConFun method during optimization. See below for the structure of the function

  • update (callable function, default None) – This is a callable function that gets executed at the start of every iteration of the evalObjCon method during optimization. Nominally, this is used to do parameter updates, such as for a continuation strategy

Note

The callback function is an arbitrary function that the user writes, and it will be called at the end of every _objconGradFun execution. It is required that the function is setup such that it takes in two arguments:

def user_callback(xdict, it_number):

…

Here, the parameters are:

xdict : dictionary that specifies the current design variable values for the optimization problem it_number : current iteration number for the system

The update function is also a function that the user can optionally provide, and it will be called at the start of every evalObjCon execution. This method is primarily used for updating parameters within the Flume System (e.g. for continuation strategies in topology optimization), and it is structured as follows:

def user_update(it_number):

…

where it_number is the current iteration number for the system

optimize_system(x0dict: dict, opt_prob_name: str, optimizer: str = 'SLSQP', options: dict = None, history_filename: str = None) → pyoptsparse.Solution

Performs optimization on the Flume System, interfaced with pyOptSparse, using the optimizer specified by the user. If using a proprietary optimizer (i.e. SNOPT or NLPQLP), it is assumed that the user already has access to the optimizer. Additionally, it is assumed IPOPT is already installed if the user wants to use this optimizer.

Parameters:

  • x0dict (dict) – Dictionary that provides the initial point from which the optimization will progress. Structured such that the keys are the global variable names, and the values are the numeric values to use

  • opt_prob_name (str) – Name that is provided to the optimization problem constructed with pyOptSparse

  • optimizer (str) – The name of the optimizer to use for optimization, which defaults to SLSQP. Must be one of ‘SLSQP’, ‘IPOPT’, ‘SNOPT’, ‘NLPQLP’, ‘NSGA2’, ‘PSQP’, or ‘CONMIN’.

  • options (dict) – Dictionary of options that is provided to the optimizer. If not provided, defaults to None, and the default options for the specified optimizer are used (see pyOptSparse documentation for details)

  • history_filename (str) – Name to use for the pyOptSparse History file. The full filepath is set as os.path.join(self.flume_sys.log_prefix, history_filename). If not provided, no History file is written.

Returns:

sol – Returns an instance of the pyOptSparse Solution class, which describes the solution for an optimization problem. The final design variables, objective, and Lagrange multipleirs can be accesses with sol.xStar, sol.fStar, and sol.lambdaStar, respectively

Return type:

Solution