pyfreefem 1.0

Package PyFreeFEM for interfacing Python and FreeFEM.

PyFreeFEM

PyFreeFEM is a package which allows to interface FreeFEM scripts with python. PyFreeFEM parses special instructions added to a FreeFEM script and converts it into a proper .edp file executable by FreeFEM, which itself can be run from python. It also include functions to read and write FreeFEM arrays or sparse matrices in the numpy format.

Please cite the following references when using this source:

FEPPON, Florian. Shape and topology optimization of multiphysics systems. 2019. Université Paris-Saclay. Thèse préparée à l'École polytechnique.

Installation

With pip

pip install pyfreefem

Installation from local folder

pip install -e /path/to/pyfreefem

where /path/to/pyfreefem is the directory where pyfreefem has been cloned.

Running examples

Examples are available in the folder examples and can be run from the command line with

python -m pyfreefem.examples.hello_world
python -m pyfreefem.examples.ex0

You can run all the examples at once with

python -m pyfreefem.examples.test_all

Requirements

Runs with python 3.6 and the following libraries:

• numpy (>=1.12.1)
• scipy (>=0.19.1)
• cvxopt (>=1.2.1)

Optional dependencies:

• colored (>=1.3.93) (for colored output)

Furthermore, a recent version of FreeFEM (>=4.0) should be available from the command line.

Quick documentation

PyFreeFEM operates through a meta-language which preprocesses special instructions added to a FreeFEM code or .edp source files. The instructions currently supported are listed in the table below.

Instruction	Example	Action
$	real Re=$Re;	Dollar prefixed "magic" variables will be replaced textually in the executable .edp file.
DEFAULT	DEFAULT (Re,"100")	Specify a default value for a dollar prefixed magic variable.
SET	SET (Re,"100")	Assign a value to a magic variable.
SET_TEXTVAR	SET_TEXTVAR text Multiple line variable END_TEXTVAR`	Assign a multiple line text as the value of a magic variable.
IF/ELSE/ENDIF	IF DISPLAY_MESSAGE cout << "Hello world" << endl; ELSE //Do nothing ENDIF	Include a portion of FreeFEM code if a magic variable is not zero.
OR	IFEQ (Re,["30","50"]) cout << "Re==30 or Re==50" << endl; ENDIF IFEQ (Re,"30") OR (Re,"50") cout << "Re==30 or Re==50" << endl; ENDIF	Usage of conditional or statements
IFEQ/ELSE/ENDIF	IFEQ (Re,"100") cout << "Re=100!!" << endl; ELSE cout << "Re!=100" << endl; ENDIF	Include a portion of FreeFEM code if a magic variable has a specified value.
FOR/ENDFOR	FOR (I,0,3) cout << "Message $I !" << endl; ENDFOR	Include several times the same portion of code using a "magic" increment.
INCLUDE	INCLUDE "lib.edp"	Include and parse a portion of code from an external file.
\\	real result = int2d(Th)(x IF ADD_Y +y ENDIF \\);	Remove the last line break from the executable .edp file.
//**	//** This comment will not appear in the final .edp file	"Magic" comment: the comment will be removed from the executable .edp file.

PyFreeFEM generates a .edp file (by default, the file run/run.edp) executable by FreeFEM according to these instructions and the values of dollar prefixed "magic" variables. The magic variables can be set either in FreeFEM scripts through the above meta-language or while executing it from the python interface. See DOC.md and the docstrings of pyfreefem/preprocessor.py and pyfreefem/freefemrunner.py for a more exhaustive documentation.

The package includes a syntax file edp.vim (based on this source) which provides the coloration of PyFreeFEM instructions in the vim text editor.

Quick example

File pyfreefem/examples/hello_world.py:

from pyfreefem import FreeFemRunner

code = """
mesh Th=square(30,30);
fespace Fh(Th,P1);
Fh u,v;

DEFAULT (SOLVE_LAPLACE,0)
cout << "The value of SOLVE_LAPLACE is $SOLVE_LAPLACE." << endl;
IF SOLVE_LAPLACE
solve laplace(u,v)=
    int2d(Th)(dx(u)*dx(v)+dy(u)*dy(v))
        -int2d(Th)(v)
        +on(1,2,3,4,u=0);
plot(u,cmm="$message");
ENDIF
"""

FreeFemRunner(code).execute({'message':'Hello world','SOLVE_LAPLACE':1},verbosity=1,plot=True)

The dollar prefixed variable $message allows to interact with a python source code. Running this code with python (version >=3.6) should display something like:

$ python -m pyfreefem.examples.hello_world
-- FreeFem++ v  4.100000 (date samedi 27 avril 2019, 20:25:42 (UTC+0200) git v4-beta-352-gc62e139d)
 Load: lg_fem lg_mesh lg_mesh3 eigenvalue 
    1 : 
    2 : mesh Th=square(30,30);
    3 : fespace Fh(Th,P1);
    4 : Fh u,v;
    5 : 
    6 : cout << "The value of SOLVE_LAPLACE is 1." << endl;
    7 : solve laplace(u,v)=
    8 :     int2d(Th)(dx(u)*dx(v)+dy(u)*dy(v))
    9 :         -int2d(Th)(v)
   10 :         +on(1,2,3,4,u=0);
   11 : plot(u,cmm="Hello world");
   12 :  sizestack + 1024 =1576  ( 552 )

  -- Square mesh : nb vertices  =961 ,  nb triangles = 1800 ,  nb boundary edges 120
The value of SOLVE_LAPLACE is 1.
  -- Solve : 
          min 2.20333e-63  max 0.0736069
times: compile 0.050628s, execution 0.379778s,  mpirank:0