use_api_internal.md

+## Internal API
+The internal API is meant for users wanting to run a standard computational procedure on a classic lifting configuration. The procedures that are currently implemented can be found under [api/internal](https://gitlab.uliege.be/am-dept/dartflo/blob/master/dart/api/internal):
+- a [polar](https://gitlab.uliege.be/am-dept/dartflo/blob/master/dart/api/internal/polar.py) analysis, to compute the aerodynamic coefficients for various angles of attack,
+- a [trim](https://gitlab.uliege.be/am-dept/dartflo/blob/master/dart/api/internal/trim.py) analysis, to find the angle of attack to produce a desired lift coefficient.
+Sample cases making use of the internal API can be found under [cases](https://gitlab.uliege.be/am-dept/dartflo/blob/master/dart/cases).
+
+**1. Defining the parameters**  
+In practise, all the classes implementing a computational procedure inherit from Config, which setups the solver. The first step thus consists in instantiating the desired class and passing it the parameters as a python dictionary. The different parameters are listed hereunder.  
+Common parameters (used in Config class):
+```python
+p = {}
+# I/O
+p['Dim'] = int # dimension of the problem (2 or 3)
+p['Format'] = str # output format ('gmsh' or 'vtk')
+p['File'] = str # path to the geometry/mesh file
+p['Pars'] = dict # keys/values of parameters or options to be passed to gmsh (can be empty)
+# Groups...
+p['Fluid'] = str # bame of mesh group containing the fluid
+p['Farfield'] = list of str # names of mesh groups containing the farfield boundaries (downstream boundary should be last element)
+# ... only for 2D
+p['Wing'] = str # name of mesh group containing the airfoil boundary
+p['Wake'] = str # name of mesh group containing the wake
+p['Te'] = str # name of mesh group containing the trailing edge
+# ... only for 3D
+p['Wings'] = list of str # names of mesh groups containing the lifting surface boundary
+p['Wakes'] = list of str # names of mesh groups containing the wake
+p['WakeTips'] = list of str # names of mesh groups containing the edge of the wakes
+p['TeTips'] = list of str # names of mesh groups containing the edge of the wakes and the trailing edges
+# Freestream and reference values
+p['M_inf'] = float # freestream Mach number
+p['S_ref'] = float # reference surface length (= c_ref for 2D)
+p['c_ref'] = float # reference chord length
+p['x_ref'] = float # x-coordinate of reference point for moment computation
+p['y_ref'] = float # y-coordinate of reference point for moment computation
+p['z_ref'] = float # z-coordinate of reference point for moment computation
+# Linear solver...
+p['LSolver'] = str # linear solver type (Pardiso, GMRES, MUMPS or SparseLU)
+# ... only for GMRES
+p['G_fill'] = int # fill-in factor for GMRES ILU preconditioner
+p['G_tol'] = float # tolerance for GMRES solver
+p['G_restart'] = int # number of restart for GMRES solver
+# Nonlinear solver...
+p['NSolver'] = str # nonlinear solver type (Picard or Newton)
+p['Rel_tol'] = float # relative tolerance on solver residual
+p['Abs_tol'] = float # absolute tolerance on solver residual
+p['Max_it'] = int # solver maximum number of iterations
+# ... only for Picard
+p['Relaxation'] = float # relaxation parameter (preffered value: 0.7)
+# ... only for Newton
+p['LS_tol'] = float # tolerance on line search residual (preffered value: 1e-6)
+p['Max_it_LS'] = int # line search maximum number of iterations (preffered value: 10)
+p['AV_thrsh'] = float # residual threshold below which the artificial viscosity is decreased (preffered value: 1e-2)
+# Various optional parameters
+p['Slice'] = list of float # y-coordinates of cutting planes to extract slices on the geometry
+p['TagId'] = int # id of physical group to be sliced (id can be obtained through gmsh)
+p['Symmetry'] = str # name of the mesh group containing the symmetry boundary
+p['AoS'] = float # angle of sideslip [degrees]
+```
+Additional parameters specific to Polar class:
+```python
+p['AoA_begin'] = float # first value of the angle of attack [degrees]
+p['AoA_end'] = float # last value of the angle of attack [degrees]
+p['AoA_step'] = float # step in the angle of attack [degrees]
+```
+Additional parameters specific to Trim class:
+```python
+p['CL'] = float # target lift coefficient
+p['AoA'] = float # guess (first) angle of attack
+p['dCL'] = float # guess (first) slope of CL w.r.t AoA [1/rad]
+```
+
+**2. Using the solver**  
+After the parameters have been defined, the solver can be set up automatically by instantiating the object as,
+```python
+import dart.api.internal.polar as pol
+polar = pol.Polar(p)
+# or
+import dart.api.internal.trim as trm
+trim = trm.Trim(p)
+```
+The script can then be run by calling,
+```python
+polar.run()
+# or
+trim.run()
+```
+Finally, the results can be displayed using,
+```python
+polar.disp()
+# or
+trim.disp()
+```