Morphhom

This is the manual for morphhom version 18, a program used for computing the physical response of composites using FFT methods.

Problems Morphhom solves
- Numerical schemes
Importing and exporting data
- Importing microstructure images
- Exporting fields into external softwares
Examples
MPI-parallelization
Installation instructions
Benchmarks
- Memory requirements
- Speed

Problems Morphhom solves

Morphhom is an image-based computational tool for solving linear and nonlinear homogenization problems in 2D and 3D, using Fourier (``FFT'') methods. Morphhom solves the following problems:

Linear isotropic or anisotropic elasticity
Thermoelasticity
Nonlinear elasticity (``powerlaw'' or Norton law)
Plasticity (deformation theory)
Electrical or thermal conductivity: linear and powerlaw
Strongly nonlinear electrical conductivity (powerlaw with zero or infinite exponent)
Complex permittivity (linear, quasi-static regime)
Stokes flow in porous media

Some of these problems may be available under an alternative ``discrete'' model (Willot et al, 2007; Willot et al, 2014).

Numerical schemes

Morphhom implements the following algorithms:

``direct scheme'' (Moulinec & Suquet, 1994);
``accelerated scheme'' (Eyre & Milton, 1999);
``augmented Lagrangian'' (Michel, Suquet & Moulinec, 2001);
``Stokes-FFT'' (Wiegman, 2007)

The algorithms above may be combined with several Green functions and convergence criteria.

Importing and exporting data

Importing microstructure images

Raw binary images may be read with the options -rm filename -mfmt [8bit|short|long|longlong]; if -mfmt is not specified the format defaults to the flag PRECISION_INT passed on during compilation, which is itself, by default, 8-bit signed integers.

Exporting fields into external softwares

Full-field solutions computed by morphhom are saved as a series of files, one per tensor component. For instance, for the strain tensor field in two dimensions:

the ε_xx component is saved in the file IDEpsilon_xx;
the ε_xy=ε_yx component is saved in the file IDEpsilon_xy;
the ε_yy component is saved in the file IDEpsilon_yy.

where ID is the identification string passed in the option -id ID (an underscore by default). In turn, each file is to be read as a list of floating-point numbers saved in the ``Fortran'' order

   (1,1)   (2,1)   (3,1)   ... (Lx,1)   (1,2)   ... (Lx,Ly)    (2D)
   (1,1,1) (2,1,1) (3,1,1) ... (Lx,1,1) (1,2,1) ... (Lx,Ly,Lz) (3D)

where the indexes i, j correspond to the coordinates x=i/Lx and y=j/Ly, and k corresponds to z=k/Lz in 3D.

Complex values are saved in two separate files corresponding to a real and imaginary part. Each number is saved in the same machine-dependant format as specified by the flag PRECISION during compilation which is DOUBLE by default. Assuming DOUBLE floating-point precision, the following pieces of code illustrate how fields may be imported into various softwares:

  !fortran (2D)
  INTEGER L
  DOUBLE PRECISION x(L,L)
  OPEN(UNIT=21,FILE='filename',FORM='UNFORMATTED',ACCESS='STREAM')
  READ(21) x
  CLOSE(21)

  %scilab (2D)
  fd=mopen('filename','rb');
  x=matrix(mget(L**2,'d',fd),[L L]);
  mclose(fd);

  %matlab (3D)
  fd=fopen('filename','rb');
  x=reshape(fread(fd,L^3,'double'),[L L L]);
  fclose(fd);

In the examples above, it is assumed that the machine used to run the computation is the same as the one used to import the data and hence have the same endian type, otherwise an endianness conversion may need to be performed.

Alternatively, plain text files may be generated using the -txt option. This is obviously much less efficient and is meant to be used for tesing purposes on small data sets only.

Examples

Linear conductivity

Periodic 2D material with aligned insulating cylinders of surface fraction 10% embedded in a matrix of conductivity 1; a macroscopic temperature gradient is applied in the x direction:

  ./morphhom -2d 128 -hs .1 -l 1 0 -E 1 0

Nonlinear conductivity

A periodic 2D material with spherical perfectly insulating inclusions of surface fraction 10% embedded in a nonlinear (``powerlaw'') matrix of exponent 0.5 and conductivity prefactor 1 and linear part with conductivity 2; a macroscopic temperature gradient is applied in the x direction:

  ./morphhom -2d 128 -hs .1 -pl 1 .5 2 0 -E 1 0

Linear elasticity

Periodic 3D material with 10% spherical prefectly-rigid inclusions embedded in a matrix with bulk and shear moduli 1; stress loading is applied:

  ./morphhom -greenstress -3d 128 -hs .1 -l 1 0 -m 1 0 -press

Nonlinear elasticity

Periodic 3D material with 10% spherical voids embedded in a matrix with bulk modulus 1, linear elastic regime with shear modulus 1 and nonlinear powerlaw elastic regime with exponent 0.5; simple shear loading is applied:

  ./morphhom -2d 128 -hs .1 -pl 1 .5 2 0 -m 1 0 -e 0 1 0

Complex permittivity

Periodic 2D material with 10% spherical voids with complex permittivity i embedded in a matrix with complex permittivity 1; an electrical field of mean 1 is applied along the x direction; solved with the accelerated scheme;

  ./morphhom -2d 128 -hs .1 -l 1 0 -p 0 1 -E 1 0 -acc

Stokes flow

Stokes flow around cylinders with volume fraction 10%; a macroscopic pressure gradient of 1 is applied along the x direction; the fluid viscosity is 1 and the voxel size is 1;

  ./morphhom -2d 128 -hs .1 -s 1 -vsi 1 -E 1 0

MPI parallelization

In its MPI-enabled version, morphhom splits the last dimension under parts as equal as possible and distributes the resulting data and computations on the different nodes. The following limitations and considerations must be taken into account:

the MPI enabled version is restricted to 3D problems;
in all numerical experiments so far, the MPI enabled version is found to be slower than its multithreaded counterpart (this is not a problem with Morphhom itself but rather with the FFTs); accordingly the MPI enabled version is useful to handle very large system sizes, not to improve on speed;
if the number of nodes is large, there is a risk that the amount of data will be zero on one of the nodes, which is something Morphhom can not handle; in that case the computation will stop and the job should be restarted on less/more nodes;
microstructure generation has not been optimized: it is done on the first node solely, which must hold the entire microstructure in memory before distributing it to the other nodes;
as per the previous point, it is best to run computations for which the iterations themselvevs are the most time-consuming task; when parallelizing on many nodes, the temporary memory overhead during the microstructure generation on the first node should be taken into account;
with -Os, the microstructure size is reduced only after it has been generated on the first node and distributed to the other nodes;
quadruple precision is not currently supported with MPI.

Note that full-field solutions are split under several files, exactly one per node. For instance

  mpirun -np 2 -h host1,host2 ./morphhom -3d 1024 -l 1 2 -hs .1

runs a distributed computation on two nodes, producing the following output files:

  1_E1, 2_E1, 1_E2, 2_E2, 1_E3, 2_E3, 1_J1, 2_J1, 1_J2, 2_J2, 1_J3, 2_J3.

Files should be concatenated to get the temperature gradient and current fields. For instance, the temperature gradient in the x component might be recovered with:

  cat [12]_E1 > _E1.

Installation instructions

Prerequisites

Morphhom is made of Fortran code (conforming to the 2003 standard) plus some C code. Successful builds of Morphhom have been obtained with the following configurations:

32 & 64 bit x86 machines with GNU-Linux OS;
C and Fortran compilers: GNU's gcc/gfortran≥4.2 or Intel's icc/ifort≥11.0;
FFTW≥3.3.2;

Additionally, if you need any of the parallel versions of the software:

openMP multithreading;
distributed memory parallelization with openMPI or MPICH2.

You may either download precompiled binaries of FFTW, as supplied with your distribution OS, or manually download and install the library with the following typical configure options:

  ./configure --enable-openmp [--enable-sse2] [--enable-mpi] [--enable-float|--enable-long-double|--enable-quad-precision]

The above followed by make; sudo make install installs FFTW in /usr/local/lib and /usr/local/include (as of 2012, this is subject top changes by the FFTW developpers).

You are on your own on non-Unix machines; you probably need to adjust various things, e.g. the files Makefile and Makefile.mk which were only tested with GNU make.

Compilation

Compile the executable morphhom with:

  make [ARG=val [ARG2=val2...]]

The build process supports the following flags:

`CC=...` `FC=...`	C and Fortran compilers (default to `gcc` and `gfortran`).
`THREADS=[yes\|no]`	Enable shared-memory parallelization with openMP multithreading (default: yes).
`MPI=[yes\|no]`	Enable distributed-memory parallelization with MPI (default: no); in that case you may want to adjust the compiler flags `CC` and `FC` to invoke the MPI C and Fortran compilers (typically ``mpicc'' and ``mpif90'').
`PRECISION=prec`	Floating-point precision; valid values for `prec` are, if supported by your compiler: `SINGLE` (6 or more significant digits), `DOUBLE` (default, 15 or more significant digits), `LONGDOUBLE` (18 significant digits) and `QUADPRECISION` (33 digits, requires GCC≥4.6). Note that the corresponding FFTW library should be available; for instance, compile FFTW with `--enable-float` if using `PRECISION=SINGLE`.
`PRECISION_INT=prec`	Range of integers used to index phases; the default value for `prec` is `8BIT` (maximum of 128 phases); to allow for a greater number of phases at the expense of slighty larger memory use, specify `SHORT`, `LONG` or `LONGLONG` (for up to 2¹⁵, 2³¹ and 2⁶³ phases respectively).
`STATIC=[yes\|no]`	Compile statically (default: no); not supported with MPI.
`FFTWINCDIR=dir` `FFTWLIBDIR=dir`	Directories where FFTW header files and libraries might be found by the compiler; default values are `/usr/local/include` and `/usr/local/lib`.

Other flags are used by the developper:

`OUTPUT=exe`	Name of executable ouput (default: morphhom).
`DEBUG=[yes\|no]`	Enable debugging info (default: no).
`PEDANTIC=[yes\|no]`	Use GNU's `-pedantic-errors` option when compiling with `gcc` or `gfortran` (default: no).
`CHECKSTD=[yes\|no]`	Check the code's conformity with the Fortran 2003 standard (default: no).

Instead of supplying them on the command line, you may save your favorite options in a file named ``Makefile.local'' for automatic reading, (see ``Makefile.local.sample'' for an example).

Troubleshooting

If you recompile the code with different flags, it is probably necessary to do a ``make clean'' and start compilation from scratch.
FFTW and morphhom should be compiled with the same software suite (Intel or GNU); unexpected behavior may otherwise happen.
In general, the PP and THREADSLIB flags defined in the file Makefile.mk should be adjusted for building the software with a different compiler. With few minor adjustments, the program compiles with Portland's Fortran and C compilers as well, but the resulting performance on the machine where it was tested was not encouraging.

Installation check

Type make check to verify the correctness of solutions provided for a few basic problems.

This calls the script checkresults which in turn runs morphhom commands; if you compiled morphhom with MPI enabled, this script will attempt to launch commands on two processors, in the form mpirun -np 2 OUTPUT [options...]. This setting might be adjusted by modifying the top of the file checkresults.

Benchmarks

Memory requirements

The maximum system sizes that may be handled by morphhom depend on the dimension, problem type and algorithm. Approximate values are given in the figure below, for some standard problems and machines, assuming single precision and the use of the -Os option; however the figures are only marginaly changed without that option. It is also assumed that Morphhom uses 95% of the RAM, to leave to the OS itself a minimal amount of space.

	4 Gb RAM	16 Gb RAM	128 Gb RAM
2D conductivity, direct or accelerated scheme	22029²	44058²	124615²
2D conductivity (network), direct or accelerated scheme	30916²	61833²	174892²
2D conductivity, Lagrangian	15752²	31505²	89111²
2D mechanics, direct or accelerated scheme	18189²	36379²	102897²
2D mechanics, Lagrangian	12911²	25822²	73036²
3D conductivity, direct or accelerated scheme	688³	1092³	2184³
3D conductivity (network), direct or accelerated scheme	985³	1564³	3129³
3D conductivity, Lagrangian	550³	873³	1747³
3D mechanics, direct or accelerated scheme	550³	873³	1747³
3D mechanics, Lagrangian	437³	695³	1390³

Speed

The developper's own observation, as of 2012, on most common machines he used (mainly Intel 64bit):

when the size increases, FFTs take an increasing part of the total computation time; eventually, for very large sizes, almost all available CPU is spent doing FFTs;
the codes produced by ``gfortran/gcc'' and ``ifort/icc'' take nearly the same time for computing FFTs;
accordingly to the above, the relative speed difference between gfortran and ifort gets smaller when the system size increases;
gfortran's code is significantly slower for computations in the complex domain and when using the -Os option.

Morphhom

Table of contents