Python

core module

core module that provides function to create/interogate two scale object.

class coarseManager(coarse_manager)

Bases: object

A python coarseManager.

__init__(coarse_manager)

Initialize python coarseManager object from a C++ object.

Parameters:

coarse_manager (A C++ coarse manager object.) – The C++ object to warp.

Note:

coarse_manager objects should usually be constructed using generateCoarseManager() and not using this class initializer.

projectStdCoarse(coarse_enriched_field: Function, fine_field: Function)

Project standard part of coarse enriched field in fine field

resetCoarseToStd()

Reset coarse system with precomputed standard part

setStdCoarse(Aff: Mat, bf: Vec, use_imp_enriched: bool = False)

Create/update coarse system with new fine matrix and vector and compute standard part.

Parameters:

• Aff (PETSc Mat) – System matrix assembled at fine level

• bf (PETSc Vec) – System rhs assembled at fine level

• use_imp_enriched (bool) – If true generate extra information to be able to use updateEImp and solveEImp

solve(fine_field: Function)

solve coarse system and store project result in fine field

solveEImp(fine_field: Function)

solve coarse system and store project result in fine field considering all enriched dof imposed to one

updateEImp()

update imposed enriched contribution to rhs

updateEnrichCoarse(Aff: Mat, bf: Vec)

update only enriched part of coarse system

updateEnrichedOperator(pm: patchManager, func: enrichedFunction)

Compute the enriched part of the scale jump operator based on patches solution and the enrichment function generator

class enrichedFunction(enriched_function)

Bases: object

A python enrichedFunction.

__init__(enriched_function)

Initialize python enrichedFunction object from a C++ object.

Args:

enriched_function: A C++ coarse manager object.

Note:

enriched_function objects should usually be constructed using generateEnrichedXXXFunction() and not using this class initializer.

class patchManager(patch_manager)

Bases: object

A python patchManager.

__init__(patch_manager)

Initialize python patchManager object from a C++ object.

Parameters:

patch_manager – The C++ object to warp.

Note:

patch_manager objects should usually be constructed using generatePatchManager() and not using this class initializer.

generateProblems(Aff: Mat, bf: Vec)

create patches system

grabPatchSolution(seq: int, fine_field: Function)

Grab patch solution for a specific sequence into a fine scale field

Parameters:

• seq (integer) – The sequence id for which the solution(s) is(are) collected

• fine_field (Function) – The field where the patch(es) solution(s) is(are) stored

Danger:

Only for debbuging purpose. May be removed in the future and/or instable.

solveProblems(fine_field: Function)

solve patches system

property numberOfSequence

number of sequence to compute all patches

class scaleJump(scale_jump)

Bases: object

A python scaleJump.

__init__(scale_jump)

Initialize python scalejump object from a C++ object.

Args:

scale_jump: A C++ mesh object.

Note:

scaleJump objects should usually be constructed using topDown() and not using this class initializer.

getChildren(coarse_idx)

Return list of fine mesh cells index embodied in coarse cell of index ‘coarse_idx’ if no fine cell is associated to this coarse cell return an empty list

getFaceChilds(coarse_idx)

Return list of fine mesh faces index embodied in coarse face of index ‘coarse_idx’ if no fine face is associated to this coarse face return an empty list Only coarse face of the support will provides childs

getSurroundingFaceChilds(coarse_idx)

Return list of fine mesh faces index embodied in coarse face of index ‘coarse_idx’ if no fine face is associated to this coarse face return an empty list Only coarse face of the surrounding element will provides childs

isFineMasterNode(idx)

Return fine master node of mpc relation if any.

property getCoarseMaster

Return coarse face connected to node in Extra enriched group if any.

property getCoarseMesh

Return coarse mesh

property getEnriched

Return coarse enriched node index (local and/or ghost))

property getExtraEnriched

Return coarse enriched node index (local and/or ghost))

property getFineMesh

Return fine mesh

property getSupport

Return support of coarse enriched node (i.e. all index of cells connected localy to an enriched node (local or ghost))

property getSurroundingCells

Return cell surronding support if any (i.e. cell connected to node in Extra enriched group but not in support)

property needs_mpc

tells if mpc are required or not

generateCoarseManager(sj: scaleJump, fine_field: Function, coarse_field: Function, mpc: MultiPointConstraint | None = None, bcs: list[DirichletBC] = [])

Function to create the coarseManager that operate on fine matrices and patches to construct coarse system and solve it. It mainely create the operators that transform field at fine scale to enriched field at coarse scale.

Parameters:

• sj – scaleJump object holding mesh transition information

• fine_field – field at fine scale

• coarse_field – field at coarse level

• mpc – if any, multi point constrain used to connect finefield dof at support interface

• bcs – List of boundary condition to be impose at coarse scale on coarse_field.

Warning:

The bcs must respect the following rules depending on implementation :

With nested matrix strategy

• No constrain except that all BC space must be included in coarse_field space which is in this case a simple space representing blocked standard dofs.

With the mixed space strategy

• it must be constructed on the same space given by coarse_field argument which is in this case based on a mixed space with standard and enriched dofs

• it must group all Dirichlet boundary condition in one dirichletBC object

• Enriched dofs out of the support are automatically constrained by this function and should not be fixed by the user with bcs

generateEnrichedShiftFunction(fine_field: Function)

Function to create, from fine field, a enrichedFunction object coresponding to a field shifted by value at enriched point

Parameters:

fine_field – field at fine scale

generateMPC(sj: scaleJump, space: FunctionSpace)

Function to create, from scaleJump object and studied space, all mpc (if any) needed to connect dof at support interface

generatePatchManager(sj: scaleJump, fine_field: Function)

Function to create, from scaleJump object , all patches and a manager of them

topDown(mesh: Mesh, enriched: Callable, crit: Callable, level: int = 1, clustering_dual_graph: bool = True, accurate_weight: bool = False, tags: MeshTags | None = None)

Function to create a scaleJump object containing a fine mesh generated from a coarse one, based on enriched nodes and refinement criteria

Parameters:

• mesh – The coarse mesh to start from

• enriched – The function that identify nodes to enrich

• crit – The function that identify element to refine for a given level of refinement

• level – The number of refinement pass to apply to the support of enriched nodes

• clustering_dual_graph – Force usage of clustering strategy for load balancing

• accurate_weight – Ask for use of accurate weight per element for graph node weighting used for load balancing

• tags – one days tags given by this argument will be promoted to generated fine scale mesh

Returns:

The scaleJump object corresponding to the jump from coarse mesh to fine scale mesh

Return type:

scaleJump

useNest()

Function telling if librarie is using or not nested matrix strategy

Returns:

True if nested matrix strategy is activated in the library

linear module

module that provides TwoScale linear solvers tools.

initLinearBasicLoop(sj: scaleJump, A: Mat, B: Vec, fine_space: FunctionSpace, enriched_field: Function, mpc: MultiPointConstraint | None = None, bc: list[DirichletBC] = [])

Function to initialize twoscale object used in runLinearBasicLoop

Parameters:

• sj – The scale jump describing the two scale

• A – The fine scale assembled matrix (it can be either with Dirichlet boundary condition eliminated or not)

• B – The fine scale assembled rhs (it can be either with Dirichlet boundary condition eliminated or not)

• fine_space – The space describing fine scale discretization related to fine scale linear problem

• enriched_field (Function) – The field describing enriched field at coarse scale. The associate linear problem is managed by coarseManager object

• mpc (MultiPointConstraint or None) – The multi point constraint, if any, used to create fine_space and created from a call to core.generateMPC with sj.

Returns:

The field describing fine scale function related to fine scale resolution by the twoScale solver, the coarseManager object to use for the resolution and the patchManager object to use for the resolution

Return type:

tuple Function,coarseManager,patchManager

Warning:

A and B must be both with Dirichlet boundary condition eliminated or not. Mixing eliminated and not eliminated is an error

linearBasicLoop(sj: scaleJump, fine_space: FunctionSpace, Aff: Mat, ADff: Mat, Bf: Vec, BDf: Vec, efunc: enrichedFunction, enriched_field: Function, mpc: MultiPointConstraint | None = None, bc: list[DirichletBC] = [], itmx=10, eps=0.001)

Function to solve a linear problem by looping in between scale with the twoscale approach

Parameters:

• sj – The scale jump describing the two scale

• fine_space – The space describing fine scale discretization related to fine scale linear problem

• Aff – The fine scale assembled matrix

• ADff – The fine scale assembled matrix with fine Dirichlet boundary condition eliminated

• Bf – The fine scale assembled rhs

• BDf – The fine scale assembled rhs with fine Dirichlet boundary condition eliminated treated

• efunc – The enriched function functor that transform patch solution into a enriched function (i.g. shifting field to force enriched dof to be null)

• enriched_field – The field describing enriched field at coarse scale. The associate linear problem is managed by coarseManager object

• mpc – The multi point constraint, if any, used to create fine_space and created from a call to core.generateMPC with sj.

• bc (list of DirichletBC) – The list of boundary conditions applied to system at coarse level

• itmx (int) – The maximum number of iteration to compute

• eps (floating point value) – The target precision for relative residual value to be considered as null

Returns:

the field describing fine scale function related to fine scale resolution by the twoScale solver, the last residual computed the number of iteration done in the loop the history of residual evolution

Return type:

tuple Function,float,int,list[float]

linearBasicLoopEimp(sj: scaleJump, fine_space: FunctionSpace, Aff: Mat, ADff: Mat, Bf: Vec, BDf: Vec, efunc: enrichedFunction, enriched_field: Function, mpc: MultiPointConstraint | None = None, bc: list[DirichletBC] = [], itswitch=4, itmx=10, eps=0.001)

Function to solve a linear problem by looping in between scale with the twoscale approach At a specific iteration the enriched dofs are all set to 1 considering that enrichment functions are sufficiently representative of the phenomena so that enriched dof fluctuation can be ignored at coarse level.

Note:

This function can only be used when enrichment function is shifted because its only in this case

that enriched dofs converge to one.

param sj:

The scale jump describing the two scale

param fine_space:

The space describing fine scale discretization related to fine scale linear problem

param Aff:

The fine scale assembled matrix

param ADff:

The fine scale assembled matrix with fine Dirichlet boundary condition eliminated

param Bf:

The fine scale assembled rhs

param BDf:

The fine scale assembled rhs with fine Dirichlet boundary condition eliminated treated

param efunc:

The enriched function functor that transform patch solution into a enriched function (i.g. shifting field to force enriched dof to be null)

param enriched_field:

The field describing enriched field at coarse scale. The associate linear problem is managed by coarseManager object

type enriched_field:

Function

param mpc:

The multi point constraint, if any, used to create fine_space and created from a call to core.generateMPC with sj.

type mpc:

MultiPointConstraint or None

param itswitch:

The maximum number of iteration to compute without imposing enriched dofs to one

type itswitch:

int

param itmx:

The maximum number of iteration to compute

type itmx:

int

param eps:

The target precision for relative residual value to be considered as null

type eps:

floating point value

return:

the field describing fine scale function related to fine scale resolution by the twoScale solver, the last residual computed the number of iteration done in the loop the history of residual evolution

rtype:

tuple Function,float,int,list[float]

linearBasicLoopVideo(filename: str, scale, sj: scaleJump, fine_space: FunctionSpace, Aff: Mat, ADff: Mat, Bf: Vec, BDf: Vec, efunc: enrichedFunction, enriched_field: Function, mpc: MultiPointConstraint | None = None, bc: list[DirichletBC] = [], itmx=10, eps=0.001, camera=None, patch=False)

Function to solve a linear problem by looping in between scale with the twoscale approach It works like linearBasicLoop but generate a gif movie file and thus should only be used for debugging or ilustration but not for real life application.

Parameters:

• filename – The name of the gif file to create

• scale – scaling factor of the deformed mesh by the field

• sj – The scale jump describing the two scale

• fine_space – The space describing fine scale discretization related to fine scale linear problem

• Aff – The fine scale assembled matrix

• ADff – The fine scale assembled matrix with fine Dirichlet boundary condition eliminated

• Bf – The fine scale assembled rhs

• BDf – The fine scale assembled rhs with fine Dirichlet boundary condition eliminated treated

• efunc – The enriched function functor that transform patch solution into a enriched function (i.g. shifting field to force enriched dof to be null)

• enriched_field – The field describing enriched field at coarse scale. The associate linear problem is managed by coarseManager object

• mpc – The multi point constraint, if any, used to create fine_space and created from a call to core.generateMPC with sj.

• itmx (int) – The maximum number of iteration to compute

• eps (floating point value) – The target precision for relative residual value to be considered as null

Returns:

the field describing fine scale function related to fine scale resolution by the twoScale solver, the last residual computed the number of iteration done in the loop

Return type:

tuple Function,float,int

residual(A: Mat, b: Vec, x: Vec, nb: float | complex)

Function to compute the relative residual of the linear problem A.x=b provided as argument.

Parameters:

• A (Petsc Mat) – The matrix of the system

• b (Petsc Vec) – The right hand side vector of the system

• x (Petsc Vec) – The solution vector of the system (i.e. \(x=A^{-1}.b\))

• nb (PetscScalar) – The value to resize the norm and make it relative. In general it is expected to be the norm of b.

Returns:

The relative norm of the residual: \(\frac{|A.x-b|}{nb}\)

Return type:

PetscScalar

runLinearBasicLoop(solf: Function, cm: coarseManager, pm: patchManager, Aff: Mat, ADff: Mat, Bf: Vec, BDf: Vec, efunc: enrichedFunction, enriched_field: Function, mpc: MultiPointConstraint | None = None, itmx=10, eps=0.001, reset_sol=True)

Function to solve a linear problem by looping in between scale with the twoscale approach

Parameters:

• solf – The field describing fine scale function related to fine scale resolution by the twoScale solver

• cm (twoscale.core.coarseManager object) – coarseManager object initialized by initLinearBasicLoop function

• pm (twoscale.core.patchManager object) – patchManager object initialized by initLinearBasicLoop function

• Aff – The fine scale assembled matrix

• ADff – The fine scale assembled matrix with fine Dirichlet boundary condition eliminated

• Bf – The fine scale assembled rhs

• BDf – The fine scale assembled rhs with fine Dirichlet boundary condition eliminated treated

• efunc – The enriched function functor that transform patch solution into a enriched function (i.g. shifting field to force enriched dof to be null)

• enriched_field – The field describing enriched field at coarse scale. The associate linear problem is managed by coarseManager object

• mpc – The multi point constraint, if any, used to create fine_space and created from a call to core.generateMPC with sj.

• itmx (int) – The maximum number of iteration to compute

• eps (floating point value) – The target precision for relative residual value to be considered as null

• reset_sol – Reset the solution field using enrichied_fied by projection with standard operator

Returns:

the last min residual computed and the number of iteration done in the loop

Return type:

tuple float,int

runLinearBasicLoopEImp(solf: Function, cm: coarseManager, pm: patchManager, Aff: Mat, ADff: Mat, Bf: Vec, BDf: Vec, efunc: enrichedFunction, enriched_field: Function, mpc: MultiPointConstraint | None = None, itswitch=4, itmx=10, eps=0.001, reset_sol=True)

Function to solve a linear problem by looping in between scale with the twoscale approach At a specific iteration the enriched dofs are all set to 1 considering that enrichment functions are sufficiently representative of the phenomena so that enriched dof fluctuation can be ignored at coarse level.

Note:

This function can only be used when enrichment function is shifted because its only in this case

that enriched dofs converge to one.

param solf:

The field describing fine scale function related to fine scale resolution by the twoScale solver

param cm:

coarseManager object initialized by initLinearBasicLoop function

type cm:

twoscale.core.coarseManager object

param pm:

patchManager object initialized by initLinearBasicLoop function

type pm:

twoscale.core.patchManager object

param Aff:

The fine scale assembled matrix

param ADff:

The fine scale assembled matrix with fine Dirichlet boundary condition eliminated

param Bf:

The fine scale assembled rhs

param BDf:

The fine scale assembled rhs with fine Dirichlet boundary condition eliminated treated

param efunc:

The enriched function functor that transform patch solution into a enriched function (i.g. shifting field to force enriched dof to be null)

param enriched_field:

The field describing enriched field at coarse scale. The associate linear problem is managed by coarseManager object

type enriched_field:

Function

param mpc:

The multi point constraint, if any, used to create fine_space and created from a call to core.generateMPC with sj.

type mpc:

MultiPointConstraint or None

param itswitch:

The maximum number of iteration to compute without imposing enriched dofs to one

type itswitch:

int

param itmx:

The maximum number of iteration to compute

type itmx:

int

param eps:

The target precision for relative residual value to be considered as null

type eps:

floating point value

param reset_sol:

Reset the solution field using enrichied_fied by projection with standard operator

return:

the last min residual computed and the number of iteration done in the loop

rtype:

tuple float,int

util module

util module that provides function/class used to simplify implementation.

createFineScaleSytems(a: Form, b: Form, bcs: list[DirichletBC] = [], MPC: MultiPointConstraint | None = None)

Function to create fine scale systems based on given forms and boundary conditions. It return PETSc object \(A\), \(AD\), \(B\), \(BD\)

Parameters:

• a (ufl expression) – bilinear form of the fine scale system

• b (ufl expression) – linear form of the fine scale system

• bcs (list of DirichletBC object) – Dirichlet boundary condition to apply to the fine scale system

Returns:

The matrices \(A\), \(AD\), \(B\), \(BD\)

Note:

This implementation is just for testing it assemble twice but petsc should be used instead

distanceFromEllipse(p: ArrayLike, p0: ArrayLike, p1: ArrayLike, p2: ArrayLike)

Give the distance of a set of point p to the ellipse defined by 3 points (center, end axis 1, end axis 2)

Parameters:

• p – The points to test (shape 3xnb points)

• p0 – The center

• p1 – The end of the axis 1

• p2 – The end of the axis 2

Returns:

Distance of p to the ellipse

distanceFromParallelogram(p: ArrayLike, Orig: ArrayLike, u: ArrayLike, v: ArrayLike)

Give the distance of a point p to the parallelogram defined by a corner and 2 vectors describing each non colinear edges

Parameters:

• p – The points to test (shape 3xnb points)

• Orig – The given corner

• u – The vector describing one pair of edges

• v – The vector describing the second pair of edges

Returns:

Distance of p to the parallelogram

distanceFromSphere(p: ArrayLike, Orig: ArrayLike, r: float)

Give the distance of set of point p to the sphere defined by its center and radius

Parameters:

• p – The points to test (shape 3xnb points)

• Orig – The given center

• r – The radius

Returns:

Distance of p to the sphere

insideCylinder(p: ArrayLike, Orig: ArrayLike, axes: ArrayLike, r: float)

Mark as True the points of a given set that are inside a cylinder defined by an axis (that give also its lenght), a origine on that axis and a radius.

Parameters:

• p – The points to test (shape 3xnb points)

• Orig – The given cylindrical bases

• axes – The vector describing cylinder axes and its length

• r – The radius of the cylinder

Returns:

array indicating if test points are in (True) or out (False) of the cylinder

insideExtrudedEllipse(p: ArrayLike, p0: ArrayLike, p1: ArrayLike, p2: ArrayLike, h: float)

Mark as True the points of a given set that are inside an extruded ellipse volume. The ellipse is defined in space by 3 points (center, end axis 1, end axis 2) and an extrusion height

Parameters:

• p – The points to test (shape 3xnb points)

• p0 – The center

• p1 – The end of the axis 1

• p2 – The end of the axis 2

• h – extrusion height along orthogonal vector to the plan formed by p0,p1 and p2

Returns:

array indicating if test points are in (True) or out (False) of the elliptical volume

insideParallelepiped(p: ArrayLike, Orig: ArrayLike, u: ArrayLike, v: ArrayLike, w: ArrayLike)

Mark as True the points of a given set that are inside a parallelepiped defined by a corner and 3 vectors describing each non colinear edges

Parameters:

• p – The points to test (shape 3xnb points)

• Orig – The given corner

• u – The vector describing one edges direction and size

• v – The vector describing the second edges direction and size

• w – The vector describing the third edges direction and size

Returns:

array indicating if test points are in (True) our out (False) of the parallelepiped

insideSphere(p: ArrayLike, Orig: ArrayLike, r: float)

Mark as True the points of a given set that are inside a sphere defined by its center and radius

Parameters:

• p – The points to test (shape 3xnb points)

• Orig – The given center

• r – The radius

Returns:

array indicating if test points are in (True) our out (False) of the sphere

normalizev(x: ArrayLike)

For a given 2D/3D vector compute and return its normalized version and its 2-norm

Parameters:

x – The vector to normalize

Returns:

Normalized version of x and its norm

par_field(field: Function, scale, extrude=0)

Basic function to genrate from the given field the mesh deformed by that field. In 2D the field can be used as an extrusion value in the z direction. Collective operation

Parameters:

• field – The field to plot

• scale – The scaling value used to deform the mesh from field values

• extrude – In 2D if set to 1 the norm of the components at nodes is used as the z value. If set to 2 the square norm of the components is filtered by a Heaviside function to obtain a binary vision of the zone where the field is non null (1 extrusion) or null (0 extrusion)

par_rank(dom: Mesh)

Basic function to genarate the ready to plot vtk grid from mesh given as argument and set a color per rank on each elements. Collective operation

Parameters:

dom (Mesh object) – the mesh distributed on a specific communicator. Somme process may hold no element of the mesh and thus will not participate to the visualization.

rootMasterFace(sj: scaleJump, dom: Mesh)

Basic function to gather on root process (i.e. 0) the ready to plot vtk grid of coarse mesh master faces. Collective operation

Parameters:

• sj – The scale jump describing the two scale

• dom – the mesh distributed on a specific communicator. Somme process may hold no element of the mesh and thus will not participate to the visualization.

Returns:

a vtk grid object

root_field(field: Function, scale, extrude=0)

Basic function to gather on root process (i.e. 0) the given field on the gathered mesh given as argument and deformed by that field. In 2D the field can be used as an extrusion value in the z direction. Collective operation

Parameters:

• field – The field to plot

• scale – The scaling value used to deform the mesh from field values

• extrude – In 2D if set to 1 the norm of the components at nodes is used as the z value. If set to 2 the square norm of the components is filtered by a Heaviside function to obtain a binary vision of the zone where the field is non null (1 extrusion) or null (0 extrusion)

root_mesh(dom: Mesh)

Basic function to gather on root process (i.e. 0) the ready to plot vtk grid from mesh given as argument. Collective operation

Parameters:

dom – the mesh distributed on a specific communicator. Somme process may hold no element of the mesh and thus will not participate to the visualization.

Returns:

a vtk grid object

root_rank(dom: Mesh)

Basic function to gather on root process (i.e. 0) the ready to plot vtk grid given as argument and set a color per rank on each elements. Collective operation

Parameters:

dom – the mesh distributed on a specific communicator. Somme process may hold no element of the mesh and thus will not participate to the visualization.

show_dofs_ids(space: FunctionSpace, dom: Mesh, pv_plt: Plotter, pvopt: dict, pvoptl: dict)

Function to plot global(local) indexes of the dofs related to a space on a domain. It is relatively specific to TS library as space can only be:

• related to fine scale

• related to coarse scale without enrichment

• related to coarse scale with enrichment

Parameters:

• space – space from which dofs are showed

• dom (FunctionSpace object) – mesh where dofs of space are located

• pv_plt (An instance of Plotter class) – The Plotter (pyVista sens) to which this function add the dofs index

• pvopt (Python dictionary of options) – Option to set when adding mesh view with the add_mesh method

• pvoptl (Python dictionary of options) – Option to set when adding label view with the add_point_labels method

show_patch_sol(sj: scaleJump, pm: patchManager, field: Function, cdomain: Mesh, pvopt: dict, do_mpc: bool, mpc, scale, seqb=-1, nbseq=1, merge=False, all_data=False, raw=False, extrude=0, to_file: str = '')

Function to plot patche(s) solution(s)

Parameters:

• sj – scale jump

• pm – Patch manager

• field – field to store patche(s) solution(s)

• cdomain – mesh at coarse scale

• pvopt (Python dictionary of options) –

  Option to set when adding mesh view with the add_mesh method

• do_mpc (Boolean) – If true next argument must be used for mpc treatment

• mpc – Multipoint constraint definition

• scale – scaling for deformed mesh representation

• seqb – first sequence to collect or -1 for all

• nbseq – number of sequence from seqb to collect

• merge (string) – if true all selected sequence are plotted on the same plot. Othewise 1 sequence per subplot

• all_data (Boolean) – if true one view per selected sequence with associated mesh (force merge to False)

• raw (Boolean) – if true show patches solution in a distributed way from fine field (force merge and all_data to False)

• extrude – In 2D, if 1 transform solution into z component. If 0 solution unchanged (2 meaning less in this context)

• to_file – Save patch(es) of a sequence in a file named to_file_xx with xx the sequence id. Only raw=False possible in this case