Welcome to S2M’s documentation!

S2M is a python program for modelling polycristalline aggregate for numerical simulation with crystallography information. It offers the capability to:

  • Create 3D realistic aggregate from 2D EBSD experimental data ; In this case, we can get a voxelized volume, driven by sphere or ellipsoid filling.

  • Create 3D voxel mesh based on the reconstruction process, or on several 2D tif images.

  • Create 3D tetrahedron mesh from voxel structure based on multiple materials marching cubes algorithm with following smoothing and remeshing algorithms.

S2M can write image file format or unstructured grid from VTK library. It can create “ready made” abaqus input file for FEM input solver (mesh, element sets, boundary conditions), and GMSH mesh format.


Show me! I need examples!

Modelling 3D aggregate from ebsd data :
  • import modules

    >>> import pickle # to save data
    >>> import S2M
    >>> from S2M.core import data_generator
    >>> from S2M.core import filler_sphere
    >>> from S2M.core import voxelizer
    >>> from S2M.io import reader,writer
    >>> from S2M.visualization import display
  • read input data (see for example the gfi OIM files in ebsd_data directory):

    >>> S2M.get_ebsd_data_names()
    >>> S2M.get_ebsd_data_info()
    >>> S2M.copy_ebsd_data('B3crop27.gfi') # copy 'B3crop27.gfi' file in work dir
    >>> gfi_reader = data_generator.ExpReader('B3crop27.gfi')
    >>> gfi_reader.read_data()
  • process data to obtain 3D voxelised polycristalline aggregate:

    >>> sph_filler = filler_sphere.FillerSpheres(cL=(0,0,0),cU=(50,50,50),random_1st_layer=False,intersect_value = 0.3,crystal_struct=['cubic'])
    >>> sph_filler.process(surface_reader=gfi_reader,volume_reader=None,fill_method=0,iter_MAX=200,safety = 1)
    >>> voxel_size = (1,1,1)
    >>> vx = voxelizer.Voxelizer(voxel_size)
    >>> vx.process(sph_filler,voxelizer.voxel_method_type['wo_intersection'])
    >>> indx = np.arange(vx.voxels.min(),vx.voxels.max()+1)
    >>> orientation_index = np.column_stack((indx,sph_filler.orientation_all))
    >>> writer.save_vti(vx.voxels, 'B3crop27_angles.vti',discretisation=voxel_size,orientation=orientation_index)
    digraph g
    "2d" [image="titane_2400_gr_vox_zp_diry.png", width=0.65,shape=none, taillabel="from 2D EBSD map",
                            fontname = Monaco, fontsize = 14, imagescale=true];
    #"2D" [label=];
    "3d" [image="titane_2400_vol_ea_y_3.png",shape=none, taillabel="to 3D volume" , width=0.8,
                            fontname = Monaco, fontsize = 14, imagescale=true];
    "2d" -> "3d" [arrowhead=vee,arrowsize=3, penwidth=2];

    from 2D EBSD Map to 3D Volume

Create voxelized mesh from volumetric data, converted in abaqus inp and suitable periodic boundary conditions

>>> import S2M
>>> from S2M.io import reader,writer,inpwriter
>>> voxels = reader.read_tif("input_data.tif")
# or
>>> img_path = './data/NA7_200/NA7*.tif'
>>> voxels = reader.read_stack_tiff(path_directory=img_path)
# then
>>> inpwriter.generate_voxels(voxels, out_folder='B3crop27_ell',
                        lx=1.0, ly=1.0, lz=1.0,
                        doPBC=True, doIterative=True, doMaterial=True,

Create conformal mesh from volumetric data (see previous features), and convert into abaqus inp and paraview vtk format

from S2M.io import inpwriter,reader,writer
import S2M.vox2tet as v2t
filename = "JMA_30"
directory_path = "./data/JMA/"
jma_mesher = v2t.get_settings()
jma_mesher.input_img_file = directory_path + filename + '.tif'
jma_mesher.out_path_base = "./" + filename + '_v2t/' + filename
jma_mesher.do_save_remesh_grains_inp = False
jma_mesher.do_save_remesh_grains_stl = False
jma_mesher.do_save_vtk = True
_images/Voron.png _images/JMA30PolyMat.png

The primary goal of this vox2tet module is to generate finite element mesh from multi-label 3D images of polycrystal materials without limitation on the count of phases and complexity of microstructure geometry. It has been developped for polycrystalline aggregates, but can also be used for another kind of material (woven composite, fiber glass reinforced thermoplastic).

_images/fiber_glass_100.png _images/fiber_glass_100_zoom.png

Citing S2M

For vox2tet module :

Sinchuk and al ; X-ray CT based Multi-layer Unit Cell Modeling of Carbon Fiber-Reinforced Textile Composites: Segmentation, Meshing and Elastic Property Homogenization Composite Structures, 2022. [sinchuk2022]



S2M is referred to the Agence pour la Protection des Programmes, APP with IDDN.FR.001.07003.000.S.C.2018.000.31235, and IDDN.FR.001.420032.000.S.A.2021.000.31235 for last version with vox2tet module. S2M is distributed under a 3-clause BSD license (see LICENSE.rst) :


This development of vox2tet module was supported financially by the CEA (Commissariat à l’Energie Atomique et aux Energies Alternatives).

Indices and tables

S2M version 0.6.350, documentation generated the Jan 05, 2023 by mik.