File Formats

All DAMASK-specific configuration files are text files in YAML style. It is recommended to use damask.Config for generation and modification of configuration files. Hand-written files should be checked for correctness, e.g. with yamllint or on www.yamllint.com.

Note

The YAML parser used in DAMASK does not support advanced features like references and certain line continuation statements.

Material Configuration

DAMASK is configured via a configuration file called material.yaml. This file needs to be located in the current working directory. material.yaml contains three top-level keys:

  • homogenization

  • phase

  • material

Using damask.ConfigMaterial is the recommended way for the generation and modification of material.yaml.

homogenization

… is a dictionary of arbitrarily labeled keys. Each of those entries requires a key N_constituents that specifies the number of homogenized constituents. At least the type of the employed homogenization scheme for each active field (mechanical, thermal, or damage) is required; any further configuration details depend on the selected homogenization scheme. It is recommended to construct homogenization entries based on the examples provided in config.tar.xz rather than from scratch.

Warning

Only a single homogenization entry is supported at the moment.

The basic layout is sketched in the following:

homogenization:

 label_A:
   N_constituents: N_A
   mechanical:
     type: tbd
     ...:
   damage:
     type: tbd
     ...:
   mechanical:
     type: tbd
     ...:

 label_B:
   N_constituents: N_B
   mechanical:
     type: tbd
     ...:
   damage:
     type: tbd
     ...:
   mechanical:
     type: tbd
     ...:

 label_:
   ...

phase

… is a dictionary of arbitrarily labeled keys. Each phase entry requires a key lattice that specifies the lattice structure in Pearson notation. At least the type of the employed constitutive model for each active field (mechanical/elastic, mechanical/plastic, mechanical/eigen, thermal/source(s), or damage) is required; any further configuration details depend on the selected constitutive model. It is recommended to construct phase entries based on the examples provided in config.tar.xz rather than from scratch.

The basic layout is sketched in the following:

phase:

 label_1:
   lattice: lattice_1
   mechanical:
     elastic:
       type: tbd
       ...:
     plastic:
       type: tbd
       ...:
     eigen:
       type: tbd
       ...:
   damage:
     type: tbd
     ...:
   thermal:
     source:
       - type: tbd
         ...:
       - type: tbd
         ...:

 label_2:
   lattice: lattice_2
   mechanical:
     elastic:
       type: tbd
       ...:
     plastic:
       type: tbd
       ...:
     eigen:
       type: tbd
       ...:
   damage:
     type: tbd
     ...:
   thermal:
     source
       - type: tbd
         ...:
       - type: tbd
         ...:

 label_N:
   ...

material

… is a list. The number of entries needs to be at least as long as to accommodate the maximum (zero-based) material ID reference in the employed geometry. Example: a maximum material ID of 4 requires at least a list with five entries. Each entry contains the specification of the employed homogenization referenced by its label and a list of constituents whose length matches N_constituents. Each constituent entry contains the specification of the employed phase referenced by its label, the volume fraction v, and the crystallographic orientation O as a unit quaternion.

It is recommended to use damask.ConfigMaterial.material_add() for the creation of material entries.

The basic layout is sketched in the following:

material:

 - homogenization: label_A
   constituents:
     - phase: label_1
       v: 1.0
       O: [1.0, 0.0, 0.0, 0.0]

 - homogenization: label_B
   constituents:
     - phase: label_1
       v: 0.4
       O: [0.0, 1.0, 0.0, 0.0]
     - phase: label_2
       v: 0.6
       O: [0.0, 0.0, 1.0, 0.0]
 - ...

Grid Solver

Geometry

The grid solver operates on a regular grid specified in the VTK ImageData format. The material ID in material.yaml is referenced via the value of a PointData dataset named material. Uncompressed and zlib compressed datasets are supported. Using damask.Grid is the recommended way for the generation and modification of grid solver geometries.

Load Case

The load case of the grid solver is written in YAML style. It contains three top-level keys:

  • solver

  • initial_conditions

  • loadstep

solver

… is a dictionary that specifies for each considered physical phenomenon what solver to use. The following grid-based solvers are implemented

mechanical: spectral_basic | spectral_polarization | FEM
thermal: spectral
damage: spectral

initial_conditions

… is a dictionary that specifies for each considered physical phenomenon what initial conditions to use. The initial conditions are themselves specified as a dictionary.

Presently, the only supported key is thermal where the initial temperature T for all points is given in Kelvin.

thermal:
  T: T_init/K

loadstep

… is a list of dictionaries that specifies the details of each individual load step in the simulation. Every load step has a number of parameters that need to be declared:

  • discretization

    • N: number of increments

    • t: time of load step in seconds, i.e. \(t = \sum_{i=1}^N \Delta t_i\)

    • r: scaling factor (default 1) in geometric time step series, i.e. \(\Delta t_{i+1} = r\,\Delta t_i\)

  • f_out: output frequency of results; e.g. \(f_\text{out} = 3\) writes results every third increment

  • f_restart: output frequency of restart information; e.g. \(f_\text{restart} = 10\) writes restart information every tenth increment

  • estimate_rate: estimate field of deformation gradient fluctuations based on former load step (default) or assume to be homogeneous, i.e. no fluctuations

  • boundary_conditions

    • mechanical

      • R: rotation axis and angle (in degrees) from grid to load frame coordinate system (defaults to no rotation, i.e. load frame coincides with grid coordinates)

      • F: deformation gradient at end of load step

      • F_dot: rate of deformation gradient during load step

      • L: velocity gradient during load step

      • P: first Piola–Kirchhoff stress at end of load step

      • P_dot: rate of first Piola–Kirchhoff stress during load step

Mixed (deformation–stress) conditions are possible but necessarily mutually exclusive (indicated by ‘x’).

Example:

loadstep:

  - discretization:
      t: 100
      N: 10
    f_out: 10
    boundary_conditions:
      mechanical:
        dot_F: [[1.0e-3, 0, 0],
                [0,      x, 0],
                [0,      0, x]]
        P: [[x, x, x],
            [x, 0, x],
            [x, x, 0]]

  - discretization:
      t: 1000
      N: 50
    boundary_conditions:
      mechanical:
        dot_F: [[1.0e-3, 0, 0],
                [0,      x, 0],
                [0,      0, x]]
        P: [[x, x, x],
            [x, 0, x],
            [x, x, 0]]
    f_out: 10
    f_restart: 25

Mesh Solver

Geometry

The mesh solver operates on an unstructured mesh specified in the MSH format. Neper and Gmsh are the recommended tools to generate mesh solver geometries.

Load Case

Warning

The load case is specified in an undocumented proprietary format.

MSC Marc

DAMASK is interfaced to MSC Marc through a hypela2 user subroutine. MSC Marc requires a so-called input deck that specifies the geometry and boundary conditions (among others) in a *.dat file (see MSC Marc user manual for details). The link between the geometry in the input deck and the material ID in material.yaml is provided via the StateVariable 2 field.

Result (DADF5)

DAMASK results are stored in an HDF5 file according to the DAMASK HDF5 (DADF5) specification. The group–dataset (folder–file) layout of a DADF5 file follows that of material.yaml used for setting up the simulation. Using damask.Result is the recommended way for accessing DADF5 files; HDFView can provide a quick overview. The basics of the file format are explained in the video “DADF5 - DAMASK’s HDF5-Based Output Format”.