4. Spectral Solver

---

Preamble

Read the General Usage section—it is relevant for using the spectral solver as well.

To get started, you might want to run the example included in DAMASK and follow the step-by-step instruction.

Valid command line arguments

Invoke the executable with the --help option for an overview of command line arguments. An overview of all arguments is given in the table below.

> DAMASK_spectral --help

comand line argument	Meaning
--geom / -g / --geometry	Specifies the location of the geometry definition file
--help / -h	Prints help message and exits
--load / -l / --loadcase	Specifies the location of the load case definition file
--restart / -r / --rs XX	Reads in total increment No. XX and continues to calculate total increment No. XX+1 Appends to existing results file
--workingdir / -w / --wd / --workingdirectory	Specifies the working directory

---

Invoking the spectral solver

To start a simulation imposing a load defined in FileNameOfLoad.load on NameOfGeomFile.geom, type

> DAMASK_spectral --geom  PathToGeomFile/NameOfGeomFile.geom --load PathToLoadFile/FileNameOfLoad.load

Working directory

The configuration files must be located (also see general usage) in the working directory, i.e. the location where DAMASK_spectral is invoked. The command line switch --workingdir can be used to specify another working directory:

> DAMASK_spectral --geom  PathToGeomFile/NameOfGeomFile.geom --load PathToLoadFile/NameOfLoadFile.load --workingdir PathToWorkingDir 

Solver job name

The SolverJobName is the base name of the geom file and the base name of the load case file concatenated by an underscore »_«. For the command

> DAMASK_spectral --geom  PathToGeomFile/NameOfGeomFile.geom --load PathToLoadFile/NameOfLoadFile.load

the solver job name will be NameOfGeomFile_NameOfLoadFile.* and placed in PathToGeomFile. All output files, i.e. result files, restart information and DAMASK files.

---

Spectral solver options in numerics.config

The keywords numerics.config relevant for the spectral method boundary value problem solver are explained here. For general information on numerics.config, click here.

Spectral solver variant
keyword	default value	meaning
spectralsolver	basic	type of spectral solver
		basic	basic scheme (direct variational with single field)
		Polarisation	Polarisation (mixed variational with dual fields)
Convergence criteria
keyword	default value	meaning
err_stress_tolrel	0.001	relative tolerance for fulfillment of stress BC
err_stress_tolabs	1000.0	absolute tolerance for fulfillment of stress BC
err_div_tolAbs	1.0e-10	absolute tolerance for equilibrium
err_div_tolRel	5.0e-4	relative tolerance for equilibrium
divergence_correction	2	scaling of divergence calculation
		0	no correction
		1	dimension correction
		2	dimension and resolution correction
tolerances for polarisation
err_curl_tolAbs	1.0e-10	absolute tolerance for compatibility
err_curl_tolRel	5.0e-4	relative tolerance for compatibility
FFTW
keyword	default value	meaning
fftw_timelimit	-1.0	time limit for plan creation for FFTW. -1.0 disables time limit
fftw_plan_mode	FFTW_PATIENT	reads the planning-rigor flag, see manual on www.fftw.org
Iteration controlling
keyword	default value	meaning
itmax	250	maximum iteration number
itmin	2	minimum iteration number
maxCutBack	3	maximum cutback level
continueCalculation	0	if spectral solver doesn't converge
		0	exit
		1	continue
Miscellaneous
keyword	default value	meaning
memory_efficient	1	precalculate Gamma-operator (requires 81 floating point values per FP)
update_gamma	0	update Gamma-operator with current tangent stiffness
rotation_tol	1.0e-12	tolerance of rotation specified in load case
(spectral | my)filter	none	type of filtering method to mitigate Gibbs phenomenon
		none	no filter
		cosine	cosine decay
petsc_options	-snes_type ngmres -snes_ngmres_anderson	PETSc solver options see manual on www.mcs.anl.gov/petsc

---

Parallelization

Thread parallelism

If multiprocessor (openMP) was enabled during compilation (default), the number of threads can be set with "DAMASK_NUM_THREADS":

bash> export DAMASK_NUM_THREADS=4 ; echo $DAMASK_NUM_THREADS
 csh> setenv DAMASK_NUM_THREADS 4 ; echo $DAMASK_NUM_THREADS

for using four cores.

Node parallelism

The solver can use an MPI environment to decompose the geometry into multiple domains that get solved in parallel. For this, the grid dimension along z has to be an integer multiple of the intended number of nodes to be used.

> mpiexec -np 4 DAMASK_spectral --load loadcase --geom geometry
> mpirun   -np 4 DAMASK_spectral --load loadcase --geom geometry

---

Results

SolverJobName.spectralOut
SolverJobName.sta

---

Restart

To enable restart, set a restart write frequency in the load case file. This will trigger the writing of all necessary information for restarting an aborted simulation.

SolverJobName.F	field of current deformation gradients
SolverJobName.F_lastInc	field of previous deformation gradients
SolverJobName.F_aimDot	average deformation rate
SolverJobName.C	current stiffness matrix
SolverJobName.C_lastInc	previous stiffness matrix
SolverJobName.C_ref	reference stiffness matrix

SolverJobName.F_lambda	field of current Lagrange multipliers
SolverJobName.F_lambda_lastInc	field of previous Lagrange multipliers

Additionally, the files needed by DAMASK for restart are required

To restart an simulation aborted after increment XX-1, tell the spectral solver to start with calculation at step XX

> DAMASK_spectral --geom  PathToGeomFile/NameOfGeomFile.geom --load PathToLoadFile/NameOfLoadFile.load --workingdir PathToWorkingDir --restart XX

The output results will be appended to SolverJobName.spectralOut, if results where written to that file after writing the restart information, they will appear double. It works only if the restart information for total increment No. XX-1 and the usual configuration files are available in the working directory.

Please Note: The solver cannot determine to which increment the restart information belongs. It is highly recommended to backup the output file (*.spectralOut) before restarting the calculation.

---

Step-by-step instruction (example included in DAMASK)

Running the simulation

Change to the directory containing the example files for the spectral solver.

> cd $DAMASK_ROOT/examples/SpectralMethod/Polycrystal

Invoke the spectral solver to run a tensile test in x-direction on the low-resolution example

> DAMASK_spectral --load tensionX.load --geom 20grains16x16x16.geom

Get ASCII data out of the binary result file

Convert selected output (deformation gradient F and 1st Piola--Kirchhoff stress P) from the result file to an separate ASCIItable for each time step with data on each grid point

> postResults --cr f,p --split --separation x,y,z 20grains16x16x16_tensionX.spectralOut

switch to the output directory postProc and check the header information of the last increment (100). It should contain 9 values for F and P plus geometric information.

> cd postProc
> viewTable -a 20grains16x16x16_tensionX_inc100.txt

Add additional information

Add the Cauchy stress (a function of F and P) and its von Mises equivalent to the ASCIItable containing the final increment. Check whether additional information has been added to the ASCIItable.

> addCauchy 20grains16x16x16_tensionX_inc100.txt
> addMises -s Cauchy 20grains16x16x16_tensionX_inc100.txt
> viewTable -a 20grains16x16x16_tensionX_inc100.txt

Add a logarithmic strain and its scalar equivalent:

> addStrainTensors --left --logarithmic 20grains16x16x16_tensionX_inc100.txt
> addMises -e 'ln(V)' 20grains16x16x16_tensionX_inc100.txt
> viewTable -a 20grains16x16x16_tensionX_inc100.txt

Generate a file for visualization

To visualize the equivalent Cauchy stress, the first component (in loading direction) of P, and the equivalent logarithmic strain, generate a rectilinear grid VTK file from the geometry contained in the ASCIItable. Then, add the data to be visualized to this skeleton VTK file.

> vtk_rectilinearGrid 20grains16x16x16_tensionX_inc100.txt
> vtk_addRectilinearGridData \
 --data 'Mises(Cauchy)',1_p,'1_ln(V)',1_Cauchy \
 --vtk '20grains16x16x16_tensionX_inc100_pos(cell).vtr' \
 20grains16x16x16_tensionX_inc100.txt

Open the file 20grains16x16x16_tensionX_inc100_pos(cell).vtr in ParaView. To view a time series showing the evolution of the quantities, repeat the last two steps for all files in postProc using the scripting facilities of your shell.

Visualize the displacement

To visualize the displacement, first calculate the average and fluctuating displacement from the results file. For the voxel-based visualization (i.e. using vtk_rectilinearGrid), use the following command.

> addDisplacement --nodal 20grains16x16x16_tensionX_inc100.txt

This will create a new file as the displacements will be interpolated to the nodes of the voxels (due to the --nodal option) resulting in a grid of 17x17x17. Now, add the data to the VTK file.

vtk_addRectilinearGridData \
 --data 'fluct(f).pos','avg(f).pos' \
 --vtk '20grains16x16x16_tensionX_inc100_pos(cell).vtr' \
 20grains16x16x16_tensionX_inc100_nodal.txt

Reopen the file 20grains16x16x16_tensionX_inc100_pos(cell).vtr in ParaView. Choose Filters > Common > Warp By Vector from the menu and select first "avg(f).pos". Select the new entry in the pipeline to visualize the uniformly deformed geometry. Similarly, choose Filters > Common > Warp By Vector from the menu and select first "fluct(f).pos" to also see the fluctuations resulting from the solution of static mechanical equilibrium.

Further Exercices

1. A shear test using the corresponding loadcase file in the example folder
2. A tensile test in z-direction using a modified tensionX.load loadcase from the example folder
3. Generate a vtk file with all 9 components of the Cauchy stress
4. Use the higher resolved examples (20grains32x32x32.geom and 20grains64x64x64.geom)
5. Generate a geometry file with 48 grid points in each direction using the file 20grains.seeds in the example directory
6. Modify numerics.config to use the polarisation solver