# 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.api 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() method to a list of variable names:

from gemseo.api import MDODiscipline

class NewDiscipline(MDODiscipline):

def __init__(self):
super(NewDiscipline, self).__init__()
self.input_grammar.update(['x', 'z'])
self.output_grammar.update(['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.api 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.api 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.api import MDODiscipline
from numpy import array

class NewDiscipline(MDODiscipline):

def __init__(self):
super(NewDiscipline, self).__init__()
self.input_grammar.update(['x', 'z'])
self.output_grammar.update(['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.

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:

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.)]))