MatOpt: Nanomaterials Optimization¶
The MatOpt module provides tools for nanomaterials design using Mathematical Optimization. MatOpt can be used to design crystalline nanostructured materials, including but not limited to particles, wires, surfaces, and periodic bulk structures.
The main goals of this package are as follows:
 To automate many of the steps that are necessary for utilizing mathematical optimization to design materials, speeding up the development of new mathematical models and accelerating new materials discovery.
 To simplify the representation of nanostructured materials and their structurefunction relationships as Pyomo objects, streamlining the creation of materials optimization problems in the Pyomo modeling language.
 To provide a simple interface so that users need not handle the details of casting efficient mathematical optimization models, invoking mathematical optimization solvers, or utilizing specialized Pyomo syntax to do this.
Thank you for your interest in MatOpt. We would love to hear your feedback! Please report any thoughts, questions or bugs to: gounaris@cmu.edu
If you are using MatOpt, please consider citing:
 Hanselman, C.L., Yin, X., Miller, D.C. and Gounaris, C.E., 2020. MatOpt: A Python package for nanomaterials design using discrete optimization. In preparation.
Basic Usage¶
There are two main submodules contained in the package serving two distinct purposes:
 The
matopt.materials
module contains objects and methods for efficiently representing and manipulating a nanomaterial and its design space.  The
matopt.opt
module contains objects and methods for speeding up the casting of a Mixedinteger Linear Programming (MILP) model with simplified modeling syntax and automatic model formulation.
Dependencies
User access to the MILP solver CPLEX through Pyomo is assumed. For users who do not have access to CPLEX, the use of NEOSCPLEX is suggested as an alternative.
Define design canvas
Several pieces of information about the material and design space need to be specified in order to formulate a materials optimization problem. To fulfill this need, the matopt.materials
module defines generic and simple objects for describing the type of material to be designed and its design space, also referred to as a “canvas”.
Some key objects are listed as follows:

class
idaes.apps.matopt.materials.lattices.lattice.
Lattice
[source]¶ A class used to represent crystal lattice locations.
The class encodes methods for determining which Cartesian coordinates to consider as sites on an infinite crystal lattice. A
Lattice
can be constructed from a point on the lattice (i.e., a shift from the origin), an alignment (i.e., rotation from a nominal orientation), and appropriate scaling factors. With these attributes, we generally support the translation, rotation, and rescaling of lattices. Additionally,Lattice
objects include a method for determining which sites should be considered neighbors.

class
idaes.apps.matopt.materials.canvas.
Canvas
(Points=None, NeighborhoodIndexes=None, DefaultNN=0)[source]¶ A class for combining geometric points and neighbors.
This class contains a list of Cartesian points coupled with a graph of nodes for sites and arcs for bonds. A
Canvas
object establishes a mapping from the abstract, mathematical modeling of materials as graphs to the geometry of the material lattice. The list of points and neighbor connections necessary to create aCanvas
object can be obtained from the combination ofLattice
,Shape
, andTiling
objects.

class
idaes.apps.matopt.materials.design.
Design
(Canvas_=None, Contents=None)[source]¶ A class used to represent material designs.
This class combines a
Canvas
objects and a list of contents. It assigns an element (possibly None) to each point in theCanvas
. This generally works for any type of content, but it is intended to work withAtom
objects and can be used to generate CFG, PDB, POSCAR, and XYZ files.
Build model via descriptors
The material type and design space specified provide indices, sets, and parameters for the optimization model. Using simple syntax, inspired by materialsrelated terminology, MatOpt users define a MatOptModel
object, which will be translated into a Pyomo ConcreteModel
object automatically.
MatOpt uses MaterialDescriptor
objects to represent variables, constraints, and objectives. A MatOptModel
object holds lists of MaterialDescriptor
objects. By default, several universal site descriptors are predefined in the model.
Descriptor  Explanation 

Yik 
Presence of a building block of type k at site i 
Yi 
Presence of any type of building block at site i 
Xijkl 
Presence of a building block of type k at site i and a building block of type l at site j 
Xij 
Presence of any building block at site i and any building block at site j 
Cikl 
Count of neighbors of type l next to a building block of type k at site i 
Ci 
Count of any type of neighbors next to a building block at site i 
Userspecified descriptors are defined by DescriptorRule
objects in conjunction with Expr
expression objects. Available expressions include:
Expression  Explanation 

LinearExpr 
Multiplication and addition of coefficients to distinct descriptors 
SiteCombination 
Summation of site contributions from two sites 
SumNeighborSites 
Summation of site contributions from all neighboring sites 
SumNeighborBonds 
Summation of bond contributions to all neighboring sites 
SumSites 
Summation across sites 
SumBonds 
Summation across bonds 
SumSiteTypes 
Summation across site types 
SumBondTypes 
Summation across bond types 
SumSitesAndTypes 
Summation across sites and site types 
SumBondsAndTypes 
Summation across bonds and bond types 
SumConfs 
Summation across conformation types 
SumSitesAndConfs 
Summation across sites and conformation types 
Several types of DescriptorRules
are available.
Rule  Explanation 

LessThan 
Descriptor less than or equal to an expression 
EqualTo 
Descriptor equal to an expression 
GreaterThan 
Descriptor greater than or equal to an expression 
FixedTo 
Descriptor fixed to a scalar value 
PiecewiseLinear 
Descriptor equal to the evaluation of a piecewise linear function 
Implies 
Indicator descriptor that imposes other constraints if equal to 1 
NegImplies 
Indicator descriptor that imposes other constraints if equal to 0 
ImpliesSiteCombination 
Indicator bondindexed descriptor that imposes constraints on the two sites 
ImpliesNeighbors 
Indicator siteindexed descriptor that imposes constraints on neighboring sites 
From the combination of the above predefined descriptors, expressions, and rules, a user can specify a wide variety of other descriptors, as necessary.

class
idaes.apps.matopt.opt.mat_modeling.
MaterialDescriptor
(name, canv=None, atoms=None, confDs=None, bounds=(None, None), integer=False, binary=False, rules=[], **kwargs)[source]¶ A class to represent material geometric and energetic descriptors.
This class holds the information to define mathematical optimization variables for the properties of materials. Additionally, each descriptor has a ‘rules’ list to which the user can append rules defining the descriptor and constraining the design space.

name
¶ A unique (otherwise Pyomo will complain) name
Type: string

canv
¶ The canvas that the descriptor will be indexed over
Type: Canvas

atoms
¶ The building blocks to index the descriptor over.
Type: list< BBlock
>

confDs
¶ The designs for conformations to index over.
Type: list< Design
>

rules
¶ List of rules to define and constrain the material descriptor design space.
Type: list< DescriptorRules
>

bounds
¶ If tuple, the lower and upper bounds on the descriptor values across all indices. If dict, the bounds can be individually set for each index.
Type: tuple/dict/func
See
IndexedElem
for more information on indexing. SeeDescriptorRule
for information on defining descriptors.
Solve optimization model
Once the model is fully specified, the user can optimize it in light of a chosen descriptor to serve as the objective to be maximized or minimized, as appropriate. Several functions are provided for users to choose from.

class
idaes.apps.matopt.opt.mat_modeling.
MatOptModel
(canv, atoms=None, confDs=None)[source]¶ A class for the specification of a materials optimization problem.
Once all the material information is specified, we use this class to specify the material design problem of interest. This class is intended to be interpretable without mathematical optimization background while the conversion to Pyomo optimization models happens automatically.

canv
¶ The canvas of the material design space
Type: Canvas

atoms
¶ The list of building blocks to consider. Note: This list does not need to include a voidatom type. We use ‘None’ to represent the absence of any building block at a given site.
Type: list< BBlock
>

confDs
¶ The list of conformations to consider.
Type: list< Design
>

maximize
(func, **kwargs)[source]¶ Method to maximize a target functionality of the material model.
Parameters:  func (
MaterialDescriptor
/Expr
) – Material functionality to optimize.  **kwargs – Arguments to
MatOptModel.optimize
Returns: (
Design
/list<Design
>) Optimal designs.Raises: pyutilib.ApplicationError
if MatOpt can not find usable solver (CPLEX or NEOSCPLEX)See
MatOptModel.optimize
method for details. func (

minimize
(func, **kwargs)[source]¶ Method to minimize a target functionality of the material model.
Parameters:  func (
MaterialDescriptor
/Expr
) – Material functionality to optimize.  **kwargs – Arguments to
MatOptModel.optimize
Returns: (
Design
/list<Design
>) Optimal designs.Raises: pyutilib.ApplicationError
if MatOpt can not find usable solver (CPLEX or NEOSCPLEX)See
MatOptModel.optimize
method for details. func (

optimize
(func, sense, nSolns=1, tee=True, disp=1, keepfiles=False, tilim=3600, trelim=None, solver='cplex')[source]¶ Method to create and optimize the materials design problem.
This method automatically creates a new optimization model every time it is called. Then, it solves the model via Pyomo with the CPLEX solver.
If multiple solutions (called a ‘solution pool’) are desired, then the nSolns argument can be provided and the populate method will be called instead.
Parameters:  func (
MaterialDescriptor
/Expr
) – Material functionality to optimize.  sense (int) – flag to indicate the choice to minimize or maximize the functionality of interest. Choices: minimize/maximize (Pyomo constants 1,1 respectively)
 nSolns (int) – Optional, number of Design objects to return.
Default: 1 (See
MatOptModel.populate
for more information)  tee (bool) – Optional, flag to turn on solver output. Default: True
 disp (int) – Optional, flag to control level of MatOpt output. Choices: 0: No MatOpt output (other than solver tee) 1: MatOpt output for outer level method 2: MatOpt output for solution pool & individual solns. Default: 1
 keepfiles (bool) – Optional, flag to save temporary pyomo files. Default: True
 tilim (float) – Optional, solver time limit (in seconds). Default: 3600
 trelim (float) – Optional, solver tree memeory limit (in MB). Default: None (i.e., Pyomo/CPLEX default)
 solver (str) – Solver choice. Currently only cplex or neoscplex are supported Default: cplex
Returns: (
Design
/list<Design
>) Optimal design or designs, depending on the number of solutions requested by argumentnSolns
.Raises: pyutilib.ApplicationError
if MatOpt can not find usable solver (CPLEX or NEOSCPLEX) func (

populate
(func, sense, nSolns, tee=True, disp=1, keepfiles=False, tilim=3600, trelim=None, solver='cplex')[source]¶ Method to a pool of solutions that optimize the material model.
This method automatically creates a new optimization model every time it is called. Then, it solves the model via Pyomo with the CPLEX solver.
The populate method iteratively solves the model, interprets the solution as a Design object, creates a constraint to disallow that design, and resolves to find the next best design. We build a pool of Designs that are gauranteed to be the nSolnsbest solutions in the material design space.
Parameters:  func (
MaterialDescriptor
/Expr
) – Material functionality to optimize.  sense (int) – flag to indicate the choice to minimize or maximize the functionality of interest. Choices: minimize/maximize (Pyomo constants 1,1 respectively)
 nSolns (int) – Optional, number of Design objects to return.
Default: 1 (See
MatOptModel.populate
for more information)  tee (bool) – Optional, flag to turn on solver output. Default: True
 disp (int) – Optional, flag to control level of MatOpt output. Choices: 0: No MatOpt output (other than solver tee) 1: MatOpt output for outer level method 2: MatOpt output for solution pool & individual solns. Default: 1
 keepfiles (bool) – Optional, flag to save temporary pyomo files. Default: True
 tilim (float) – Optional, solver time limit (in seconds). Default: 3600
 trelim (float) – Optional, solver tree memeory limit (in MB). Default: None (i.e., Pyomo/CPLEX default)
 solver (str) – Solver choice. Currently only cplex or neoscplex are supported Default: cplex
Returns: (list<
Design
>) A list of optimal Designs in order of decreasing optimality.Raises: pyutilib.ApplicationError
if MatOpt can not find usable solver (CPLEX or NEOSCPLEX) func (

MatOpt Output¶
The results of the optimization process will be loaded into Design
objects automatically. Users can then save material design(s) into files for further analysis and visualization using suitable functions provided. MatOpt provides interfaces to several standard crystal structure file formats, including CFG, PDB, POSCAR, and XYZ.
MatOpt Examples¶
Five case studies are provided to illustrate the detailed usage of MatOpt. In each case, a Jupyter notebook with explanations as well as an equivalent Python script is provided.
References¶
 Hanselman, C.L. and Gounaris, C.E., 2016. A mathematical optimization framework for the design of nanopatterned surfaces. AIChE Journal, 62(9), pp.32503263.
 Hanselman, C.L., Alfonso, D.R., Lekse, J.W., Matranga, C., Miller, D.C. and Gounaris, C.E., 2019. A framework for optimizing oxygen vacancy formation in doped perovskites. Computers & Chemical Engineering, 126, pp.168177.
 Hanselman, C.L., Zhong, W., Tran, K., Ulissi, Z.W. and Gounaris, C.E., 2019. Optimizationbased design of active and stable nanostructured surfaces. The Journal of Physical Chemistry C, 123(48), pp.2920929218.
 Isenberg, N.M., Taylor, M.G., Yan, Z., Hanselman, C.L., Mpourmpakis, G. and Gounaris, C.E., 2020. Identification of optimally stable nanocluster geometries via mathematical optimization and densityfunctional theory. Molecular Systems Design & Engineering.
 Yin, X., Isenberg, N.M., Hanselman, C.L., Mpourmpakis, G. and Gounaris, C.E., 2020. A mathematical optimizationbased design framework for identifying stable bimetallic nanoclusters. In preparation.
 Hanselman, C.L., Yin, X., Miller, D.C. and Gounaris, C.E., 2020. MatOpt: A Python package for nanomaterials design using discrete optimization. In preparation.