use_api.md

+## APIs
+Users wanting to use SDPM for standard computations, or interface it with external software should use one of the available APIs or write their own. The following APIs are available:
+* Core
+* OMFlut
+
+_Note_ the different APIs automate the creation of the mesh, the problem and the solvers, and provide methods for performing specific tasks. These APIs are available under [api](https://gitlab.uliege.be/am-dept/sdpm/blob/master/sdpm/api) and share a common base: [core](https://gitlab.uliege.be/am-dept/sdpm/blob/master/sdpm/api/core.py).
+
+### Core
+The [core](https://gitlab.uliege.be/am-dept/sdpm/blob/master/sdpm/api/core.py) API is the common base of all APIs. It simply consists in a `init_sdpm` method which will return all the C++ objects wrapped in python required to run SDPM. If a new API is created, it should initialize itself by calling this method.
+
+SDPM is initialized by using a dictionary of parameters, and the type of scenario and task. The different parameters are listed hereunder:
+```python
+cfg = {
+  # Model (geometry or mesh)
+  'File': str, # input Gmsh file
+  'Pars': dict, # parameters for Gmsh file (optional)
+  # Markers
+  'Wing': str, # name of the marker defining the lifting body (wing)
+  'Te': str, # name of the marker defining the trailing edge of the lifting body
+  # Freestream
+  'Mach': float, # Mach number (optional)
+  'AoA': float, # angle of attack (optional)
+  'AoS': float, # angle of side slip (optional)
+  # Unsteady motion
+  'Num_wake_div': int, # number of cells per chord length in the wake
+  'Frequencies': array[float], # list of reduced frequencies
+  'Modes': str, # input file containing the modes (optional)
+  'Num_modes': int, # number of modes
+  # Transonic correction
+  'Transonic_pressure_grad': str, # input file containing the pressure derivative (optional)
+  # Geometry
+  'Symmetry': bool, # whether only half (symmetric) model is provided
+  's_ref': float, # reference surface area
+  'c_ref': float, # reference chord length
+  'x_ref': float, # reference point for moment computation (x)
+  'y_ref': float, # reference point for moment computation (y)
+  'z_ref': float # reference point for moment computation (z)
+}
+```
+Once the parameters have been defined, SDPM can simply be initialized by calling,
+
+```python
+from sdpm.api.core import init_sdpm
+_sdpm = init_sdpm(cfg, use_ad=False)
+```
+where `use_ad` indicates whether the adjoint sovler must be instantiated or not. `_sdpm` is a dictionary containing the following objects (named after their key):
+* `n_f` is the number of reference reduced frequencies
+* `n_m` is the number of modes
+* `msh` is the mesh
+* `wrt` is the utility to write mesh/results on disk
+* `pbl` is the formulation of the problem
+* `bdy` is the body of interest
+* `sol` is the direct solver
+* `adj` is the adjoint solver
+
+### OMFlut
+SDPM has been interfaced with [OMFlut](https://gitlab.uliege.be/am-dept/omflut), which is built on top of [OpenMDAO](https://openmdao.org/), in order to calculate flutter. SDPM must be initialized inside an OpenMDAO group using a builder which will latter be reused by OMFlut.
+```python
+from omflut import FlutterGroup
+from sdpm.api.om import SdpmBuilder
+import openmdao.api as om 
+class Flutter(om.Group):
+  # ...
+  sdpm = SdpmBuilder(cfg)
+  self.add_subsystem('flutter', FlutterGroup(struct=..., xfer=..., aero=sdpm, flutter=...))
+```