Getting started#

Installation#

DMDO needs Python 3.10 or newer.

From the Python Package Index:

$ pip install DMDO

To install from source and run the test suite:

$ git clone https://github.com/Ahmed-Bayoumy/DMDO.git
$ cd DMDO
$ pip install -e .
$ pytest tests

DMDO uses OMADS [Bayoumy, 2022] for its derivative-free subproblem solvers and SciPy for the gradient-based ones, together with numpy, pandas and pyyaml. Installing DMDO also installs the dmdo command of the optional HTTP service (The HTTP service and remote workers).

A first problem#

The example below is the basic two-discipline problem (1) used throughout this documentation. Its two analyses are coupled in both directions: \(a\) depends on \(b\), and \(b\) depends on \(a\).

(1)#\[\begin{split}\begin{array}{ll} \min_{u,v,w} & u + v + a + b \\[2pt] \text{s.t.} & a = \log_{10} u + \log_{10} v + \log_{10} b, \\ & b = u^{-1} + w^{-1} + a^{-1}, \\ & w + b - 10 \le 0, \qquad 0 \le u, v, w, a, b \le 10. \end{array}\end{split}\]
_images/basic_partitioned.png

Figure 2 The basic problem partitioned into two subproblems. Each keeps its own copies of the shared variable \(u\) and of the coupling variables \(a\) and \(b\).#

DMDO solves it as two subproblems. Subproblem 1 owns \(v\) and computes \(a\); subproblem 2 owns \(w\), computes \(b\) and holds the constraint. Each one keeps a copy of \(u\), \(a\) and \(b\), and the coordinator drives the copies to agreement (see Background).

A run takes three steps:

  1. write the analyses (one per discipline) and the subproblem objectives as Python callables;

  2. describe the problem in a YAML file (or a dictionary): variables, analyses, subproblems and coordinator;

  3. build a Session and run it.

Listing 1 first_run.py#
import numpy as np
from DMDO import Session

def A1(x):                       # x = [u, v, b]  ->  [a]
    x = np.maximum(x, 1e-12)
    return [np.log10(x[0]) + np.log10(x[1]) + np.log10(x[2])]

def A2(x):                       # x = [u, w, a]  ->  [b]
    x = np.maximum(x, 1e-12)
    return [1 / x[0] + 1 / x[1] + 1 / x[2]]

def opt1(x, y, c=None):          # x = [u, v, b], y = [a]
    return [sum(x) + y[0], [0.0]]

def opt2(x, y, c=None):          # x = [u, w, a], y = [b]
    return [0.0, [x[1] + y[0] - 10.0]]

if __name__ == "__main__":
    session = Session.from_yaml("basic_problem.yaml", working_dir="runs",
                                blackboxes={"A1": A1, "A2": A2, "opt1": opt1, "opt2": opt2})
    result = session.run()
    print(result.status, result.stop_reason)
    print("objective:", result.objective, "max. inconsistency:", result.max_inconsistency)
    print(result.variables)

result is a RunResult: the final status and stopping reason, the objective of the master subproblem, the maximum inconsistency between copies, every variable copy and the per-iteration history. result.to_dict() gives the same content as plain JSON-ready values.

Important

Guard the call with if __name__ == "__main__": in scripts. Parallel runs use multiprocessing, and on Windows and macOS worker processes re-import your script.

The problem definition#

basic_problem.yaml (shipped in the examples folder of the repository) describes the variables, the analyses, how analyses are grouped per subproblem, the coordinator and the subproblems:

Listing 2 examples/basic_problem.yaml#
# The basic MDO problem
variables:
# vs:  [name, SP_index, Link, coupling type, lb, bl, ub, dim]
  v0:  ["u",     1,       2,          s, 0., 1., 10.,  1, 'REAL']
  v1:  ["v",     1,    None,          u, 0., 1., 10.,  1, 'REAL']
  v2:  ["a",     1,       2,         ff, 0., 1., 10.,  1, 'REAL']
  v3:  ["b",     1,       2,         fb, 0., 1., 10.,  1, 'REAL']
  v4:  ["u",     2,       1,          s, 0., 1., 10.,  1, 'REAL']
  v5:  ["w",     2,    None,          u, 0., 1., 10.,  1, 'REAL']
  v6:  ["a",     2,       1,         fb, 0., 1., 10.,  1, 'REAL']
  v7:  ["b",     2,       1,         ff, 0., 1., 10.,  1, 'REAL']

DA:
  DA1:
    index: 1
    inputs: [v0, v1, v3]
    outputs: [v2]
    blackbox: A1
    type: callable
    links: 2
    coupling_type: ff

  DA2:
    index: 2
    inputs: [v4, v5, v6]
    outputs: [v7]
    blackbox: A2
    type: callable
    links: 2
    coupling_type: ff

MDA:
  MDA1:
    index: 1
    nAnalyses: 1
    analyses: [1]
    variables: [v0, v1, v3]
    responses: [v2]

  MDA2:
    index: 2
    nAnalyses: 1
    analyses: [2]
    variables: [v4, v5, v6]
    responses: [v7]

coord:
  c1:
    index: 1
    type: ADMM
    beta: 1.3
    gamma: 0.5
    nsp: 2
    budget: 50
    index_of_master_SP: 1
    display: True
    scaling: 0.1
    mode: serial
    M_update_scheme: normal
    store_q_io: True

subproblem:
  sp1:
    nv: 3
    index: 1
    vars: [v0, v1, v3]
    resps: [v2]
    is_main: True
    MDA: 1
    coordinator: 1
    opt: opt1
    type: callable
    fmin_nop: inf
    solver: poll
    budget: 150
    display: False
    psize: 1.
    pupdate: Last
    freal: 2.625

  sp2:
    nv: 3
    index: 2
    vars: [v4, v5, v6]
    resps: [v7]
    is_main: False
    MDA: 2
    coordinator: 1
    opt: opt2
    type: callable
    fmin_nop: inf
    solver: poll
    budget: 150
    display: False
    psize: 1.
    pupdate: Last

USER:


MDO:
  architecture: IDF
  coordinator: 1
  subproblems: [1, 2]
  responses: [v2, v7]
  fmin: inf
  hmin: inf
  display: True
  inc_stop: 0.0000000001
  stop: "Iteration budget exhausted"
  tab_inc: []
  noprogress_stop: 100
variables

One row per variable copy: [name, subproblem, linked subproblem, coupling, lb, baseline, ub, dim, type]. u appears twice, once in each subproblem, linked to the other one; v and w are local (u, uncoupled). The coupling codes are s (shared variable), ff/fb (feed-forward and feedback coupling variables), u (local) and CP (constant parameter).

DA

The disciplinary analyses: which variables they read, which they compute, and the name of the callable that does it (blackbox).

MDA

The analyses evaluated inside each subproblem and the variables they exchange with it.

coord

The coordinator: penalty growth factor beta, number of subproblems, outer-iteration budget, the master subproblem (the one that holds the system objective) and the penalty-weight update scheme.

subproblem

Each subproblem’s design variables (vars), responses (resps), objective callable (opt), inner solver and inner evaluation budget.

MDO

The overall run: coordinator, subproblems, stopping tolerance inc_stop on the inconsistency and console output.

Problem definition lists every key and its default.

The analysis and objective contract#

Analyses receive their inputs as a list ordered like the inputs of their DA entry and return a list of outputs ordered like its outputs. An analysis may also be any object with a compute(inputs) -> outputs method working on dictionaries keyed by variable name (a Discipline), which is the natural way to wrap a simulation or a model from another framework:

class A1:
    def compute(self, inputs):          # inputs = {"u": ..., "v": ..., "b": ...}
        return {"a": np.log10(inputs["u"]) + np.log10(inputs["v"]) + np.log10(inputs["b"])}

Subproblem objectives receive the subproblem’s design vector x (ordered like vars), the responses y of its analyses (ordered like resps) and, optionally, constant parameters c. They return [f, [g1, g2, ...]]: the local objective and the local constraints in the form \(g_i \le 0\). Subproblems without a local objective return 0; subproblems without constraints return [0].

Callables are referenced by name in the problem definition. Names are resolved from the blackboxes mapping given to the session, then from the global registry (DMDO.register_blackbox()), then as an import path such as "my_package.aero:lift".

Where to go next#