Morphhom

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

Table of contents

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: 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: 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: 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: 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: Additionally, if you need any of the parallel versions of the software: 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 215, 231 and 263 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

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 220292 440582 1246152
2D conductivity (network), direct or accelerated scheme 309162 618332 1748922
2D conductivity, Lagrangian 157522 315052 891112
2D mechanics, direct or accelerated scheme 181892 363792 1028972
2D mechanics, Lagrangian 129112 258222 730362
3D conductivity, direct or accelerated scheme 6883 10923 21843
3D conductivity (network), direct or accelerated scheme 9853 15643 31293
3D conductivity, Lagrangian 5503 8733 17473
3D mechanics, direct or accelerated scheme 5503 8733 17473
3D mechanics, Lagrangian 4373 6953 13903

Speed

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