femgeom
=======

author: Ondrej Certik <ondrej@certik.cz>
homepage: http://code.google.com/p/femgeom/

Geometry utilities for FEM modeling. The goal of this project is to enable this
procedure:

1. Create a geometry (currently only in gmsh) and specify geometry entities,
i.e. regions (insulator, electrode, air) and boundaries (surface1, surface2).

2. Import the geometry and entities in femgeom. 

    g=geom.read_gmsh("/tmp/x.geo")

3. Mesh the geometry.

    geom.write_tetgen(g,"/tmp/t.smesh")
    os.system("~/fzu/mesh/tetgen -pqQ -a0.01 /tmp/t.smesh")

4. Export the mesh in any format (gmsh, libmesh,...) and list all the entities
together with elements that belong to it and faces of elements if applicable
(surfaces).

    m=mesh()
    geom.read_tetgen(m,"/tmp/t.1")
    m.writemsh("/tmp/t12.msh")
    m.writexda("/tmp/in.xda")


That's all. So the input is a geometry+entities, output is a mesh+elements (and
facets) numbers belonging to each entity. Femgeom should handle the rest. In
you FEM code, you just load the mesh and in the assembly part, you assign a
different parameter to different region (by using the element numbers femgeom
tells you) and assign boundary conditions (by using the element numbers and
sides of each element on boundary).

Current capabilities:
====================

geometry import:
    - gmsh

geometry export:
    - comsol (former femlab), there are bugs in it (and in comsol)
    - tetgen

mesh import:
    - tetgen

mesh export:
    - libmesh
    - gmsh

other:
    - a reusable 2d polygon partitioning submodule

future plans:
    source code of tetgen can be freely downloaded, but it is not open source,
    so I'll try to use netgen as well (it's probably not as good as tetgen, but
    it's opensource) - but the thing is not only to properly handle the mesh
    itself, but also the entities. Also having some other geometry import
    besides gmsh would be fine. Also add export to gmsh.

Testing
-------

py.test

Usage
-----

Prerequisites:

apt-get install python-pyparsing

download and make tetgen:

./make


Create a geometry in gmsh, convert to tetgen, run tetgen, convert mesh to
libmesh, assembly & solve.

Example
-------

cd examples
cd surfacehole
./convert.py

this meshes a gmsh geometry.



Geometry
========

The geometry class (geometry.py) holds the whole geometry. It is constructed
using:

addpoint(), addline(), addsurface(), addvolume(), addphysicalsurface() and
addphysicalvolume()

You can call these methods manually, or use read_gmsh() which imports gmsh
geometry file (*.geo) using these methods.

You can add any number of points, lines, surfaces, volumes. But you must
specify some physical volumes - and those are the ones which are going to be
exported (together with and only with the necessary surfaces, lines and
points). Optionally, you can specify some physical surfaces for applying BC
conditions, for which you will get all the points and elements (with sides)
belonging to them.

The geometry which tetgen can mesh must conform to the following rules:

* the whole body (geometry) is just a part of a space enclosed by plane
  surfaces in a way that it's waterproof, i.e. there is no way how the water
  could get inside the body

* optionally, there can be holes inside the body (enclosed by plane surfaces)

* optionally, there can be plane surfaces inside the body. Tetgen will make
  sure, that the tetrahedrons will respect that surface (so you can have the
  body made of different materials). I know, that if the surfaces form a closed
  object, or stretch from one boundary of the body to the other one, it's ok. I
  haven't tried other possibilities (but I think noone needs it). The
  surfaces inside the body cannot touch each other by the plane. If you want
  that, you need to redesign the geometry by merging the intersection of such
  surfaces into one.


The write_tetgen() exports all the physical volumes together with their numbers
to tetgen (and also all the physical surfaces with numbers). read_tetgen will
read all the elements together with physical volume numbers which they belong
to, plus all the nodes and elements with sides which belong to each physical
surfaces specified in the geometry. This allows you to make the mesh generation
and applying BC fully automatic.