genKer

The genKer dNami module is the its source-to-source translation engine.

Function in genKer

This module contains a set of functions and class for generating the Fortran code from symbolic expression provided by the user.

src.generate.genKer.append_Rhs(Flux, Stencil, Order, rhsname, vname, update=False, rhs=None, stored=False)

append_Rhs is a user-level function. It instructs the kernel to generate the Fortran sources codes that loops over the domain to compute all arithmetic expressions needed to build the RHS. Each call to append_Rhs creates a new loop that contains instructions needed to compute equations contained in Flx.

Parameters:

  • Flx (dictionary) – Dictionary containing expressions needed for RHS computations.

  • Stencil (int) – Stencil size for the spatial derivatives (for both first or second derivatives).

  • Order (int) – Order of the spatial derivatives (for both first or second derivatives).

  • rhsname (dictionary) – A dictionary used to name equations in comments of the Fortran codes.

  • vname (dictionary) – A dictionary used to name local variables generated for the produced loop in the Fortran code.

  • update (logical) – whether to update or erase the content of the RHS.

  • rhs (class) – contains all RHS relevant information at runtime.

  • stored (logical) – trigger the generation of stored variables with the current choice of (Stencil,Order).

src.generate.genKer.comment(message)

Generate comments in the produced Fortran source code.

src.generate.genKer.compute_stored(StoredVar, Stencil, Order, output, localvar, update=False, rhs=None)

compute_stored is a kernel-internal function. It produces the Fortran source code that loops over the domain to compute arithmetic expressions provided by the user for stored variables.

Parameters:

  • StoredVar (dictionary) – Dictionary containing stored expressions needed for RHS computations.

  • Stencil (int) – stencil size for the spatial derivatives (for both first or second derivatives).

  • Order (int) – order of the spatial derivatives (for both first or second derivatives).

  • output (class '_io.TextIOWrapper') – file opened in write mode to receive the source code.

  • localvar (string) – string containing declaration statement of intermediate variables.

  • update (logical) – whether to update or erase stored memory content (update=True is NRY).

  • rhs (class) – contains all RHS relevant information at runtime.

src.generate.genKer.compute_storedbc(StoredVar, Stencil, Order, output, localvar, dirBC, update=False, updateqbc=False, rhs=None)

compute_storedbc is a kernel-internal function. It produces the Fortran source code that loops over the domain boundaries to compute arithmetic expressions provided by the user for stored variables.

Parameters:

  • StoredVar (dictionary) – Dictionary containing stored expressions needed for RHS computations.

  • Stencil (int) – stencil size for the spatial derivatives (for both first or second derivatives).

  • Order (int) – order of the spatial derivatives (for both first or second derivatives).

  • output (class '_io.TextIOWrapper') – file opened in write mode to receive the source code.

  • localvar (string) – string containing declaration statement of intermediate variables.

  • update (logical) – whether to update or erase stored memory content (update=True is NRY).

  • rhs (class) – contains all RHS relevant information at runtime.

src.generate.genKer.createNbg(vnamebg, exprnbg, file, der='first', indbc=None, bc=False)

createNbg is a kernel-internal function. Produces Fortran code corresponding to the neighbourhood stencil operations.

Parameters:

  • vnamebg (list) – list of local variable names corresponding to neighbourhood operations.

  • exprnbg (list) – list of Fortran arithmetic expressions corresponding to neighbourhood operations.

  • file (class '_io.TextIOWrapper') – open file in write mode which receive the source code.

  • stencil (int) – stencil size of the second derivative

  • der (string) – {‘first’,’second’}

  • indbc (int) – current distance to the boundary

  • bc (logical) – True/False derivative concerns a boundary condition

Example:
>>> vnamebg = [['q(i-1,j,k,1)*q(i-1,j,k,2)',
...             'q(i+0,j,k,1)*q(i+0,j,k,2)',
...             'q(i+1,j,k,1)*q(i+1,j,k,2)'],
...             ['derhou_im1jk', 'derhou_ip0jk', 'derhou_ip1jk']]
>>> out = open('./src.f90','a+')
>>> createNbg(vnamebg[1],vnamebg[0],out)
>>> out = open('./src.f90','r')
>>> print(out.read())
'derhou_im1jk = q(i-1,j,k,1)*q(i-1,j,k,2)'
'                                        '
'derhou_ip1jk = q(i+1,j,k,1)*q(i+1,j,k,2)'
'                                        '
'                                        '
src.generate.genKer.create_bccalls(fname, fctname, fctcall, rhs=None)

create_bccalls is a kernel-internal function to manage source code generation for boundary conditions.

src.generate.genKer.create_bcsubroutine(fname, fctname, locvname, loopname, indrange, phy=None, rhs=None)

create_bcsubroutine is a kernel-internal function to manage source code generation for boundary conditions.

src.generate.genKer.dNamiVar(var, rangei, rangej, rangek, rhs)

dNamiVar is a kernel-internal function. It translates a symbolic word into a valid Fortran data access.

Parameters:

  • var (string) – The input symbolic word

  • rangei (int) – The i position in the structured grid

  • rangej (int) – The j position in the structured grid

  • rangek (int) – The k position in the structured grid

  • dim (int) – read from genRhs.py

  • varstored (dictionary) – read from genRhs.py

  • varloc (dictionary) – read from genRhs.py

  • coefficients (dictionary) – read from genRhs.py

  • varbc (dictionary) – read from genRhs.py

  • varsolved (dictionary) – read from genRhs.py

  • varname (dictionary) – read from genRhs.py

Returns:

A valid Fortran data access

Return type:

dvar (string)

Example:
>>> varname = {'u':1}
>>> dNamiVar('u',1,1,1)
'q(1,1,1,1)'
>>> varstored = {'u' : {'symb': 'u','ind':10 ,'static': True}
>>> dNamiVar('u',1,2,5)
'qst(1,2,3,10)'
src.generate.genKer.dder(vnamebg, order, stencil, varname='derv2', dirBC=None, indbc=None, bc=None)

dder is a kernel-internal function. Produces Fortran code corresponding to the second order derivative stencil operations.

Parameters:

  • vnamebg (list) – list of local variable names corresponding to neighbourhood operations.

  • order (int) – order of the second derivative

  • stencil (int) – stencil size of the second derivative

  • varname (string) – local variable used to store the result in the Fortran code

  • dirBc (string) – ‘None’,i1’,’imax’,’j1’,’jmax’,’k1’,’kmax’

  • indbc (int) – current distance to the boundary

  • bc (logical) – True/False derivative concerns a boundary condition

Returns:

Fortran source code corresponding to derivative computation.

Return type:

der (string)

Example:
>>> vnamebg = [['q(i-1,j,k,1)*q(i-1,j,k,2)',
...             'q(i+0,j,k,1)*q(i+0,j,k,2)',
...             'q(i+1,j,k,1)*q(i+1,j,k,2)'],
...             ['derhou_im1jk', 'derhou_ip0jk', 'derhou_ip1jk']]
>>> dder(vnamebg[1],2,3)
'derv2 = 1.0_wp*derhou_im1jk-&\n          2.0_wp*derhou_ip0jk+&\n          1.0_wp*derhou_ip1jk\n\n'
src.generate.genKer.der(vnamebg, order, stencil, varname='derv', dirBC=None, indbc=None, bc=None)

der is a kernel-internal function. Produces Fortran code corresponding to the first order derivative stencil operations.

Parameters:

  • vnamebg (list) – list of local variable names corresponding to neighbourhood operations.

  • order (int) – order of the 1st derivative

  • stencil (int) – stencil size of the 1st derivative

  • varname (string) – local variable used to store the result in the Fortran code

  • dirBc (string) – ‘None’,i1’,’imax’,’j1’,’jmax’,’k1’,’kmax’

  • indbc (int) – current distance to the boundary

  • bc (logical) – True/False derivative concerns a boundary condition

Returns:

Fortran source code corresponding to derivative computation.

Return type:

der (string)

Example:
>>> vnamebg = [['q(i-1,j,k,1)*q(i-1,j,k,2)',
...             'q(i+0,j,k,1)*q(i+0,j,k,2)',
...             'q(i+1,j,k,1)*q(i+1,j,k,2)'],
...             ['derhou_im1jk', 'derhou_ip0jk', 'derhou_ip1jk']]
>>> der(vnamebg[1],2,3)
'derv = -&\n          0.5_wp*derhou_im1jk+&\n          0.5_wp*derhou_ip1jk\n\n'
src.generate.genKer.genBC(Equations, Stencil, Order, rhsname, vname, setbc=[False, {'bcname': {'i1': ['rhs']}}], update=False, rhs=None, stored=False)

genBC is a user-level function. It instructs the kernel to generate the Fortran sources codes that loops over the domain boundaries to compute all arithmetic expressions needed to build the RHS. Each call to genBC creates a new loop that contains instructions needed to compute equations for the RHS at the domain boundaries.

Parameters:

  • Eqns (dictionary) – Dictionary containing expressions needed for the RHS computations at the boundaries.

  • Stencil (int) – Stencil size for the spatial derivatives (for both first or second derivatives).

  • Order (int) – Order of the spatial derivatives (for both first or second derivatives).

  • rhsname (dictionary) – A dictionary used to name equations in comments of the Fortran codes.

  • vname (dictionary) – A dictionary used to name local variables generated for the produced loop in the Fortran code.

  • setbc (dictionary) – if setbc[0]==False, Eqns are used to form the RHS near the domain boundaries, where central schemes are not fitting. If setbc[0]==True, Eqns are used to specify physical boundary conditions to either ‘q’ or ‘RHS’.

  • update (logical) – whether to update or erase the content of the RHS.

  • rhs (class) – contains all RHS relevant information at runtime.

  • stored (logical) – trigger the generation of stored variables with the current choice of (Stencil,Order) at the domain boundaries.

src.generate.genKer.genBC_calls(rhs)

genBC_calls is a kernel-internal function. It generates the Fortran codes that calls for boundary treatments.

src.generate.genKer.genFilter(stencil, order, nvar, dirBC='', indbc='', fltbeg=2, rhs=None)

genFilter is a user-lever function. It generates centred spatial filtering to enforce numerical stability of central finite-differences computations.

Parameters:

  • stencil (int) – stencil size (needs to match an entry in fltDic)

  • order (int) – order of the filter (needs to match an entry in fltDic)

  • nvar (int) – the number of variable to filter (typically the size of varsolved)

  • dirBC (string) – kernel-internal option to manage boundary treatments.

  • indbc (string) – kernel-internal option to manage boundary treatments.

  • fltbeg (int) – kernel-internal option to manage boundary treatments.

  • rhs (class) – contains all RHS informations necessary at runtime.

src.generate.genKer.genNbg(expr, dir, stencil, i='i', j='j', k='k', vname='v', dirBc=None, indbc='', der='first', rhs=None)

dNamiVar is a kernel-internal function. It prepares neighbourhood for spatial derivatives computation.

Parameters:

  • expr (string) – Arithmetical expression to be derived (pseudo-code)

  • dir (string) – ‘x’, ‘y’, ‘z’ (direction used for the derivation)

  • stencil (int) – Stencil size

  • i (string) – The i position in the structured grid

  • j (string) – The j position in the structured grid

  • k (string) – The k position in the structured grid

  • vname (string) – String used to generate the local variables names.

  • dirBc (string) – ‘None’,i1’,’imax’,’j1’,’jmax’,’k1’,’kmax’

  • indbc (int) – current distance to the boundary

  • der (string) – ‘first’,’second’

Returns:

Fortran arithmetic expression in the neighbourhood and local variables names used in the Fortran source.

Example:
>>> genNbg('rho*u','x',3,vname='derhou_')
'[['q(i-1,j,k,1)*q(i-1,j,k,2)',
   'q(i+0,j,k,1)*q(i+0,j,k,2)',
   'q(i+1,j,k,1)*q(i+1,j,k,2)'],
  ['derhou_im1jk', 'derhou_ip0jk', 'derhou_ip1jk']]'
src.generate.genKer.genP2C(output, conserv, rhs=None, bc=[False, []])

genP2C is a kernel-internal function. It creates necessary operation to march in time conservative variables depending on the value of consvar.

src.generate.genKer.genSymbDer1(exp, output, locvar, order=2, stencil=3, indi='i', indj='j', indk='k', vname='symb', history={'x': {'symb': [], 'var': []}, 'y': {'symb': [], 'var': []}, 'z': {'symb': [], 'var': []}}, dhistory={'x': [[], [], [], []], 'y': [[], [], [], []], 'z': [[], [], [], []]}, rhs=None)

genSymbDer1 is a kernel-internal function that scan the given exp pseudo-code for first order derivative computation. It then trigger kernel-internal procedure to generate the associated Fortran codes.

src.generate.genKer.genSymbDer1_bc(bcdic, exp, output, locvar, order=2, stencil=3, indi='i', indj='j', indk='k', vname='symb', history={'x': {'symb': [], 'var': []}, 'y': {'symb': [], 'var': []}, 'z': {'symb': [], 'var': []}}, dhistory={'x': [[], [], [], []], 'y': [[], [], [], []], 'z': [[], [], [], []]}, rhs=None)

genSymbDer1_bc is a kernel-internal function that scan the given exp pseudo-code for first order derivative computation. It then trigger kernel-internal procedure to generate the associated Fortran codes at the domain boundaries.

src.generate.genKer.genSymbDer2(exp, output, locvar, order=2, stencil=3, indi='i', indj='j', indk='k', vname='symb', history={'x': [[], []], 'y': [[], []], 'z': [[], []]}, rhs=None)

genSymbDer2 is a kernel-internal function that scan the given exp pseudo-code for second order derivative computation. It then trigger kernel-internal procedure to generate the associated Fortran codes.

src.generate.genKer.genSymbDer2_bc(bcdic, exp, output, locvar, order=2, stencil=3, indi='i', indj='j', indk='k', vname='symb', history={'x': [[], []], 'y': [[], []], 'z': [[], []]}, rhs=None)

genSymbDer2_bc is a kernel-internal function that scan the given exp pseudo-code for second order derivative computation. It then trigger kernel-internal procedure to generate the associated Fortran codes at the domain boundaries.

src.generate.genKer.genVname(vname, i='i', j='j', k='k')

genVname is a kernel-internal function. It appends local position suffix to a variable name.

Parameters:

  • vname (string) – variable name

  • i (string) – The i position in the structured grid

  • j (string) – The j position in the structured grid

  • k (string) – The k position in the structured grid

Returns:

vname complemented with local position suffix.

Return type:

vname (string)

Example:
>>> genVname('var1_','i','j','k')
var1_ijk'
>>> genVname('var1_','i+2','j-4','k+2-2')
'var1_ip2jm4kp2m2'
src.generate.genKer.gen_eqns_bc(Eqns, output, localvar, eqname, Order=2, Stencil=3, indi='i', indj='j', indk='k', DirDic={'i': {'dir': None, 'indbc': None}, 'j': {'dir': None, 'indbc': None}, 'k': {'dir': None, 'indbc': None}}, vname='symb', update=False, updateq=False, updatest=False, updateqbc=False, rhs=None)

gen_eqns_bc is a kernel-internal function to manage source code generation for boundary conditions.

src.generate.genKer.genbcsrc(nvar, rhs=None)

genbcsrc is a kernel-internal function to manage source code generation for boundary conditions.

src.generate.genKer.gendtype(rhs=None)

gendtype is a kernel-internal function called by append_Rhs to specify floating point number precision in the Fortran sources (through the wp parameter specify in genRhs.py by the user).

src.generate.genKer.geninit(output, nvar, rhs=None)

geninit is a kernel-internal function. It set static Fortran array initial content to zero and ensure first-touch policy for shared-memory parallelisation.

src.generate.genKer.genrk3(nvar, rhs=None, bc=[False, []], rk3=None)

genrk3 is a user-level function. It generates explicit discretisation of the left-hand side using Runge-Kutta schemes.

Parameters:

  • nvar (int) – number of variable to be marched in time (typically the size of varsolved).

  • rhs (class) – contains all RHS information necessary at runtime.

  • bc (list) – kernel-internal option for boundary treatments.

  • rk3 (class '_io.TextIOWrapper') – kernel-internal option to manage produced Fortran source file.

src.generate.genKer.genrk3update(nvar, rhs=None, bc=[False, []], updaterk3=None)

genrk3update is a user-level function. It generates explicit discretisation of the left-hand side using Runge-Kutta schemes.

Parameters:

  • nvar (int) – number of variable to be marched in time (typically the size of varsolved).

  • rhs (class) – contains all RHS information necessary at runtime.

  • bc (list) – kernel-internal option for boundary treatments.

  • updaterk3 (class '_io.TextIOWrapper') – kernel-internal option to manage produced Fortran source file.

src.generate.genKer.globvar(rhs=None)

globvar is a kernel-internal function. It creates Fortran static array declarations in all Fortran codes.

src.generate.genKer.loop(beg, end, rhs=None)

loop is a kernel-internal function. It trigger the creation of loop begin or ending in produced Fortran codes.

src.generate.genKer.loop_create(type, input, bc='all', edge='all', corner='all', rhs=None)

loop_create is a kernel-internal function. It gives developers the opportunity to tailor loop statements in all the Fortran codes.

src.generate.genKer.op_to_dNami(source, i='i', j='j', k='k', rhs=None)

op_to_dNami is a kernel-internal function. It translates pseudo-code containing a mix of symbolic arithmetic expression and Fortran syntax into a valid Fortran syntax.

Parameters:

  • source (string) – The input symbolic sentence (not necessary unary)

  • i (string) – The i position in the structured grid

  • j (string) – The j position in the structured grid

  • k (string) – The k position in the structured grid

Returns:

A valid arithmetic operation in Fortran syntax

Return type:

rhs_line (string)

Example:
>>> varname = {'u':1,'v':2}
>>> op_to_dNami('u*v + 1.0_wp ','1','4','9')
'q(1,4,9,1)*q(1,4,9,2) + 1.0_wp '
src.generate.genKer.opsplit(string, maxsplit=0)

Split string by the occurrences of pattern.

class src.generate.genKer.rhs_info(dim, wp, hlo_glob, incPATH, varsolved, varname, consvar=[], varstored={}, varloc={}, varbc={}, coefficients={}, premult='rho')

rhs_info is a user-level class. It needs to be instantiated by the user before initiating the generation process.

Args:

dim (int): number of spatial dimensions wp (string): working precision for arithmetic operations (e.g. ‘float32’ or ‘float64’) hlo_glob (int): total number of halo cells needed at runtime (including finite-difference and filter constraints). incPATH (string): path to include files (containing automatically generated Fortran source files) varsolved (list): a list of strings corresponding to symbols (names) of variables marched in time. varname (dictionary): the symbols of variables stored in the main memory associated with its order in a corresponding contiguous array. consvar (list): this argument is optional. It specifies which variables to be premultiplied by the density before marching in time. A ‘rho’ symbol is needed in varname by default but can be given a different name using the premult argument. varstored (dictionary): this argument is optional. It contains names of symbolic expressions used to store additional complex expressions in memory. varloc (dictionary): this argument is optional. It contains names of symbolic expressions used to rename complex algebraic expressions to facilitate equation writing (no intermediate store is performed). varbc (dictionary): this argument is optional. It contains names of symbolic expressions that are used at domain boundaries. coefficients (dictionary): this argument is optional. It contains all coefficients needed in the equations.

premult (string): name of the premultiplying variable if a conservative formulation is requested.

export()

export is a method of the rhs_info class that needs to be called at the end of genRhs.py to write necessary rhs information on disk to be used at runtime.

src.generate.genKer.updateRHS(vname, expr, i='i', j='j', k='k', update=False, updateq=False, rhs=None)

updateRHS is a kernel-internal function. Produces Fortran code with arithmetic expression corresponding to the RHS or an update of the RHS.

src.generate.genKer.updateStored(vname, expr, i='i', j='j', k='k', update=False, rhs=None)

updateStored is a kernel-internal function. Produces Fortran code with arithmetic expression corresponding to the stored variable.

src.generate.genKer.updateVarbc(vname, expr, i='i', j='j', k='k', update=False, rhs=None)

updateVarbc is a kernel-internal function. Produces Fortran code with arithmetic expression corresponding to an update of q vector at boundary.