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

For variables of size 1 and type float, the simplest approach is to apply the JSONGrammar.initialize_from_data_names() method with a list of string variable names (or a single string variable name) passed in argument:

from gemseo.api import MDODiscipline

class NewDiscipline(MDODiscipline):

    def __init__(self):
        super(NewDiscipline, self).__init__()
        self.input_grammar.initialize_from_data_names(['x', 'z'])
        self.output_grammar.initialize_from_data_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.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.initialize_from_base_dict() method with a dict data example:

from gemseo.api import MDODiscipline

class NewDiscipline(MDODiscipline):

    def __init__(self):
        super(NewDiscipline, self).__init__()
        self.input_grammar.initialize_from_base_dict({'x': array([0.]), 'z': array([0.])})
        self.output_grammar.initialize_from_base_dict({'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 defined 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.initialize_from_data_names(['x', 'z'])
        self.output_grammar.initialize_from_data_names(['f', 'g'])
        self.default_inputs = {'x': array([0.]), 'z': array([0.])}

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:

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