How to create a discipline from scratch?¶
Creating a discipline from scratch implies to implement a new class inheriting from MDODiscipline
.
For example, let’s consider a discipline called NewDiscipline
,
with two outputs,
f
and g
,
and two inputs,
x
and z
,
where f=x*z
and f=x*(z+1)^2
.
Overloading the MDODiscipline
’s constructor¶
First of all, we overload the MDODiscipline
constructor.
For that,
we call the MDODiscipline
superconstructor:
from gemseo import MDODiscipline
class NewDiscipline(MDODiscipline):
def __init__(self):
super(NewDiscipline, self).__init__()
# TO BE COMPLETED
Setting the input and output grammars¶
Then, we define the MDODiscipline.input_grammar
and MDODiscipline.output_grammar
created by the superconstructor with None
value.
We have different ways to do that.
Setting the grammars from data names¶
When the variables are float arrays without any particular constraint,
the simplest approach is to apply the JSONGrammar.update_from_names()
method to a list of variable names:
from gemseo import MDODiscipline
class NewDiscipline(MDODiscipline):
def __init__(self):
super(NewDiscipline, self).__init__()
self.input_grammar.update_from_names(['x', 'z'])
self.output_grammar.update_from_names(['f', 'g'])
# TO BE COMPLETED
Setting the grammars from JSON files¶
A more complicated approach is to define the grammar into JSON input and output files
with name 'NewDiscipline_inputs.json'
and 'NewDiscipline_outputs.json'
,
put these files in the same directory as the module implementing the NewDiscipline
and
pass an optional argument to the superconstructor:
from gemseo import MDODiscipline
class NewDiscipline(MDODiscipline):
def __init__(self):
super(NewDiscipline, self).__init__(auto_detect_grammar_files=True)
# TO BE COMPLETED
where the 'NewDiscipline_inputs.json'
file is defined as follows:
{
"name": "NewDiscipline_input",
"required": ["x","z"],
"properties": {
"x": {
"items": {
"type": "number"
},
"type": "array"
},
"z": {
"items": {
"type": "number"
},
"type": "array"
}
},
"$schema": "http://json-schema.org/draft-04/schema",
"type": "object",
"id": "#NewDiscipline_input"
}
and where the 'NewDiscipline_outputs.json'
file is defined as follows:
{
"name": "NewDiscipline_output",
"required": ["y1","y2"],
"properties": {
"y1": {
"items": {
"type": "number"
},
"type": "array"
},
"y2": {
"items": {
"type": "number"
},
"type": "array"
}
},
"$schema": "http://json-schema.org/draft-04/schema",
"type": "object",
"id": "#NewDiscipline_output"
}
Setting the grammars from a dictionary data example¶
An intermediate approach is to apply the JSONGrammar.update_from_data()
method
with a dict
data example:
from gemseo import MDODiscipline
class NewDiscipline(MDODiscipline):
def __init__(self):
super(NewDiscipline, self).__init__()
self.input_grammar.update_from_data({'x': array([0.]), 'z': array([0.])})
self.output_grammar.update_from_data({'y1': array([0.]), 'y2': array([0.])})
# TO BE COMPLETED
Note
Variable type is deduced from the values written in the dict
data example, either 'float
’
(e.g. 'x'
and 'y'
in {'x': array([0]), 'z': array([0.])}
) of 'integer'
(e.g. 'x'
in {'x': array([0]), 'z': array([0.])}
).
Checking the grammars¶
Lastly, we can verify a grammar by printing it, e.g.:
discipline = NewDiscipline()
print(discipline.input_grammar)
which results in:
Grammar named :NewDiscipline_input, schema = {"required": ["x", "z"], "type": "object", "properties": {"x": {"items": {"type": "number"}, "type": "array"}, "z": {"items": {"type": "number"}, "type": "array"}}}
NumPy arrays¶
Discipline inputs and outputs shall be numpy arrays of real numbers or integers.
The grammars will check this at each execution and prevent any discipline from running with invalid data, or raise an error if outputs are invalid, which happens sometimes with simulation software…
Setting the default inputs¶
We also define the default inputs by means of the MDODiscipline.default_inputs
attribute:
from gemseo import MDODiscipline
from numpy import array
class NewDiscipline(MDODiscipline):
def __init__(self):
super(NewDiscipline, self).__init__()
self.input_grammar.update_from_names(['x', 'z'])
self.output_grammar.update_from_names(['f', 'g'])
self.default_inputs = {'x': array([0.]), 'z': array([0.])}
Warning
An MDODiscipline
that will be placed inside an MDF
, a BiLevel
formulation or an MDA
with strong couplings must define its default inputs.
Otherwise, the execution will fail.
Overloading the MDODiscipline._run()
method¶
Once the input and output have been declared in the constructor of the discipline,
the abstract MDODiscipline._run()
method of MDODiscipline
shall be overloaded by
the discipline to define how outputs are computed from inputs.
See also
The method is protected (starts with “_”) because it shall not be called from outside the discipline.
External calls that trigger the discipline execution use the MDODiscipline.execute()
public method from the base class,
which provides additional services before and after calling MDODiscipline._run()
. These services, such as data checks by the grammars,
are provided by GEMSEO and the integrator of the discipline does not need to implement them.
Getting the input values from MDODiscipline.local_data
of the discipline¶
First, the data values shall be retrieved.
For each input declared in the input grammar,
GEMSEO will pass the values as arrays to the MDODiscipline
during the execution of the process.
There are different methods to get these values within the MDODiscipline._run()
method of the discipline:
as a dictionary through the
MDODiscipline.get_input_data()
method, which is also already accessible in theMDODiscipline.local_data
attribute of theMDODiscipline
or here as a list of values using
MDODiscipline.get_inputs_by_name()
with the data names passed as a list.
def _run(self):
x, z = self.get_inputs_by_name(['x', 'z'])
# TO BE COMPLETED
Computing the output values from the input ones¶
Then, we compute the output values from these input ones:
def _run(self):
x, z = self.get_inputs_by_name(['x', 'z'])
f = array([x[0]*z[0]])
g = array([x[0]*(z[0]+1.)^2])
# TO BE COMPLETED
Storing the output values into MDODiscipline.local_data
of the discipline¶
Lastly, the computed outputs shall be stored in the MDODiscipline.local_data
,
either directly:
def _run(self):
x, z = self.get_inputs_by_name(['x', 'z'])
f = array([x[0]*z[0]])
g = array([x[0]*(z[0]+1.)^2])
self.local_data['f'] = f
self.local_data['g'] = g
or by means of the MDODiscipline.store_local_data()
method:
def _run(self):
x, z = self.get_inputs_by_name(['x', 'z'])
f = array([x[0]*z[0]])
g = array([x[0]*(z[0]+1.)^2])
self.store_local_data(f=f)
self.store_local_data(g=g)
Overloading the MDODiscipline._compute_jacobian()
method¶
The MDODiscipline
may also provide the derivatives of their outputs with respect to their inputs, i.e. their Jacobians.
This is useful for gradient-based optimization or Multi Disciplinary Analyses based on the Newton method.
For a vector of inputs \(x\) and a vector of outputs \(y\), the Jacobian of the discipline is
\(\frac{\partial y}{\partial x}\).
The discipline shall provide a method to compute the Jacobian for a given set of inputs.
This is made by overloading the abstract MDODiscipline._compute_jacobian()
method of MDODiscipline
.
The discipline may have multiple inputs and multiple outputs.
To store the multiple Jacobian matrices associated to all the inputs and outputs,
GEMSEO uses a dictionary of dictionaries structure.
This data structure is sparse and makes easy the access and the iteration over the elements
of the Jacobian.
The method MDODiscipline._init_jacobian()
fills the dict
of dict
structure
with dense null matrices of the right sizes.
Note that all Jacobians must be 2D matrices, which avoids
ambiguity.
def _compute_jacobian(self, inputs=None, outputs=None):
"""
Computes the jacobian
:param inputs: linearization should be performed with respect
to inputs list. If None, linearization should
be performed wrt all inputs (Default value = None)
:param outputs: linearization should be performed on outputs list.
If None, linearization should be performed
on all outputs (Default value = None)
"""
# Initialize all matrices to zeros
self._init_jacobian(with_zeros=True)
x, z = self.get_inputs_by_name(['x', 'z'])
self.jac['y1'] = {}
self.jac['y1']['x'] = atleast_2d(z)
self.jac['y1']['z'] = atleast_2d(x)
self.jac['y2'] = {}
self.jac['y2']['x'] = atleast_2d(array([(z[0]+1.)^2]))
self.jac['y2']['z'] = atleast_2d(array([2*x[0]*z[0]*(z[0]+1.)]))