Micro and Nano Mechanics Group - User contributions [en]

Parallel Cluster Guides

2012-05-01T23:12:18Z

Iryu: /* Run several single-cpu jobs in MC2 */

__TOC__
=su-ahpcrc=
The default settings for MPI will cause the code to use GCC rather than the Intel compilers. To change this:
*EXTREMELY IMPORTANT: Ensure that nothing related to Intel has been added to your path in .bashrc and .bash_profile
*Run:
<blockquote style="background: white; border: 0; padding: 1em; width: 400px;"><pre>
$ mpi-selector --query
default:mvapich2_intel-1.2
level:user
</pre></blockquote>
*If your result is something other than the above (version number may differ), execute:
<blockquote style="background: white; border: 0; padding: 1em; width: 400px;"><pre>
$ mpi-selector --set mvapich2_intel-1.2
</pre></blockquote>
*Log out and reconnect to the cluster
*If everything is correct, asking <tt>which mpicc</tt> should yield:
<blockquote style="background: white; border: 0; padding: 1em; width: 400px;"><pre>
$ which mpicc
/usr/mpi/intel/mvapich2-1.2/bin/mpicc
</pre></blockquote>
*Add the following to makefile.sys, if not present:
<blockquote style="background: white; border: 0; padding: 1em; width: 550px;"><pre>
########################################################
#
# System type: su-ahpcrc
#
# Stanford ME linux system using intel compilers
#
########################################################

#
# Define parallel and serial compilers and compiler flags
# and set the default compiler based on the execution mode
# (defined by user in makefile)
#
CC_PARALLEL.su-ahpcrc = mpicc
CPP_PARALLEL.su-ahpcrc = mpicxx
CCFLAG_PARALLEL.su-ahpcrc = -longdouble -DLONGDOUBLE -DPARALLEL=1
CPPFLAG_PARALLEL.su-ahpcrc =

CC_SERIAL.su-ahpcrc = icc
CPP_SERIAL.su-ahpcrc = icpc
CCFLAG_SERIAL.su-ahpcrc = -DLONGDOUBLE
CPPFLAG_SERIAL.su-ahpcrc =

F90.su-ahpcrc = ifort
F90_OPTS.su-ahpcrc =
F90_LIB.su-ahpcrc = -L/opt/intel/fce/10.1.015/lib -lifcore

CC.su-ahpcrc = $(CC_$(MODE).su-ahpcrc)
CPP.su-ahpcrc = $(CPP_$(MODE).su-ahpcrc)
CCFLAG.su-ahpcrc = $(CCFLAG_$(MODE).su-ahpcrc)
CPPFLAG.su-ahpcrc = $(CPPFLAG_$(MODE).su-ahpcrc)

XLIB_LIBDIR.su-ahpcrc = /usr/X11R6/lib64
XLIB_LIB.su-ahpcrc = -L$(XLIB_LIBDIR.su-ahpcrc) -lX11 -lpthread
XLIB_INCS.su-ahpcrc =

MPI_LIBDIR.su-ahpcrc = -L/export/apps/mvapich/intel/lib
MPI_LIB.su-ahpcrc = -lmpich
MPI_INCS.su-ahpcrc =

OPENMP_FLAG.su-ahpcrc = -openmp

#
# Identify any additional libraries and paths needed for compilation
# on this system type
#
LIB_PARALLEL.su-ahpcrc =
INCS_PARALLEL.su-ahpcrc =

LIB_SERIAL.su-ahpcrc =-L../lib
INCS_SERIAL.su-ahpcrc =
</pre></blockquote>
*When compiling the code, seeing <tt>icc</tt> and comments about vectorizing loops such as "<tt>StressTableGen.c(357): (col. 37) remark: LOOP WAS VECTORIZED.</tt>" are signs that the Intel compilers were used.
*Use a PBS script similar to the following (<tt>/opt/mpiexec/bin/mpiexec --comm=pmi</tt> is the only important difference):
<blockquote style="background: white; border: 0; padding: 1em; width: 600px;"><pre>
#!/bin/bash
#PBS -N ParaDiS
#PBS -j oe
#PBS -l nodes=1:ppn=8,walltime=24:00:00
#PBS -V

### ---------------------------------------
### BEGINNING OF EXECUTION
### ---------------------------------------

echo The master node of this job is `hostname`
echo The working directory is `echo $PBS_O_WORKDIR`
echo This job runs on the following nodes:
echo `cat $PBS_NODEFILE`

ncpu=`cat $PBS_NODEFILE | wc -w`
echo "Number of processors = $ncpu "

### end of information preamble

cd $PBS_O_WORKDIR

echo $PWD

PARADIS_O_DIR="tests/fmm_8cpu_results"
mkdir -p $PARADIS_O_DIR
cmd="/opt/mpiexec/bin/mpiexec --comm=pmi -np $ncpu bin/paradis tests/fmm_8cpu.ctrl"
$cmd >& $PARADIS_O_DIR/paradis.log
</pre></blockquote>
*Submit the job using a command similar to:
<blockquote style="background: white; border: 0; padding: 1em; width: 400px;"><pre>
$ qsub paradis.pbs
</pre></blockquote>

=mc2=
By default, you will not have access to Intel compilers or MPI. They need to be added with the module command.
*EXTREMELY IMPORTANT: Ensure that nothing related to Intel has been added to your path in .bashrc and .bash_profile
*To see the list of available modules use: <tt>module avial</tt>
*To temporarily add the modules for your current session you can use <tt>module add</tt>
*To permanently add modules issue a command similar to this:
<blockquote style="background: white; border: 0; padding: 1em; width: 500px;"><pre>
$ module purge
$ module initrm intel/intel-11 mvapich/1.2rc1-intel-11-dell-gen2
$ module initadd intel/intel-12 mvapich2/1.7rc1-intel-12
$ module load intel/intel-12 mvapich2/1.7rc1-intel-12
</pre></blockquote>

=run ParaDiS in MC2=

To run a ParaDiS input in mc2, we need to edit the following file("paradis.serial.run") and submit it.

=== In paradis.serial.run ===
First of all, we can specify the JOB NAME in "[[#paradis.serial.run|paradis.serial.run]]", as follows

### Job id
#PBS -N CYL_T4_MC2.3

,where JOB NAME is CYL_T4_MC2.3 which is used when you check if the input file is running well.

Next, we need to specify the input file and the location of the log file will be written, as follows.

bin/paradiscyl tests/CYL_test/CYL_T5_MC2/CYL_T4_MC2_3.ctrl >& tests/CYL_test/CYL_T4_MC2/CYL_T4_MC2_3.log

We can see that the first part ("bin/paradiscyl tests/CYL_test/CYL_T5_MC2/CYL_T4_MC2_3.ctrl") is exactly same as the command you use when you run a input file in your computer.After this simbol(" >&"), the name of log file is specified("tests/CYL_test/CYL_T4_MC2/CYL_T4_MC2_3.log")

Then, we need to turn off the x-window in "winDefaultsFile" which is specified in the ctrl file.
For example, if it is "inputs/paradis.xdefaults", modify this file as follows.If you don't have X-server in your computer, you need to do the same thing to run the simulation.
enable_window = 0 # Toggle enabling/disabling simulation X-window.

=== submit paradis.serial.run ===
Finally, submit this file("paradis.serial.run") in MC2, as follows.

$ qsub paradis.serial.run
6006.mc2.stanford.edu

Job id("6006.mc2") will be shown in the screen.

After that, we can check if the input file in running using "qstat" or "showq"

$ qstat
Job id Name User Time Use S Queue
------------------------- ---------------- --------------- -------- - -----
5976.mc2 YSZ_CC5 inmyway 597:13:0 R default
5977.mc2 YSZ_CC6 inmyway 597:11:2 R default
5978.mc2 YSZ_CC7 inmyway 597:05:2 R default
5979.mc2 YSZ_CC8 inmyway 597:08:0 R default
5980.mc2 YSZ_CC9 inmyway 597:08:5 R default
5981.mc2 YSZ_CC10 inmyway 597:07:1 R default
5982.mc2 YSZ_CC11 inmyway 398:06:0 R default
5999.mc2 ...mmps_Test-hcp yanmingw 147:57:1 R default
6000.mc2 AuSi_Lammps_Test yanmingw 147:48:1 R default
6005.mc2 YSZ_S2_NEB inmyway 15:46:24 R default
<u>6006.mc2 CYL_T4_MC2.3 iryu 00:00:00 R default</u>

Moreover, you can see the progress in the log file, as follows.
$ cd tests/CYL_test/
$ vi CYL_T4_MC2_3.log

=== check compilers ===
We can check which compilers are used, as follows.

$ ldd bin/paradiscyl
libm.so.6 => /lib64/libm.so.6 (0x00000038dba00000)
libX11.so.6 => /usr/lib64/libX11.so.6 (0x00000038de200000)
libpthread.so.0 => /lib64/libpthread.so.0 (0x00000038dc200000)
libfftw3.so.3 => /usr/lib64/libfftw3.so.3 (0x0000003440200000)
libgsl.so.0 => /home/iryu/usr/lib/libgsl.so.0 (0x00002b38ee018000)
libgslcblas.so.0 => /home/iryu/usr/lib/libgslcblas.so.0 (0x00002b38ee545000)
libstdc++.so.6 => /usr/lib64/libstdc++.so.6 (0x00000038ee000000)
libgcc_s.so.1 => /lib64/libgcc_s.so.1 (0x00000038ebc00000)
libc.so.6 => /lib64/libc.so.6 (0x00000038db600000)
libdl.so.2 => /lib64/libdl.so.2 (0x00000038dbe00000)
libXau.so.6 => /usr/lib64/libXau.so.6 (0x00000038dd600000)
libXdmcp.so.6 => /usr/lib64/libXdmcp.so.6 (0x00000038dde00000)
/lib64/ld-linux-x86-64.so.2 (0x00000038db200000)
libimf.so => /share/apps/intel/lib/intel64/libimf.so (0x00002b38ee7af000)
libsvml.so => /share/apps/intel/lib/intel64/libsvml.so (0x00002b38eeb92000)
libintlc.so.5 => /share/apps/intel/lib/intel64/libintlc.so.5 (0x00002b38ef23a000)

If you have some problem to find proper compiler, we need to add it in your user bash_profile.
To do that, check your bash_profile, as follows.

$ cd ~
$ vi ~/.bash_profile

In "bash_profile", we need to specify path for "LD_LIBRARY_PATH", as follows.
export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:/home/iryu/Codes/fftw3_lib
export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:/usr/lib64:/home/iryu/usr/lib
export TARGET=mc2

After that, copy proper files to the path which is specified in bash_profile.
For example, if "libfftw3.so.3" is missing,
$ cp libfftw3.so.3 usr/lib/

=== kill the job ===
If you want to stop the calculation, we can do it using "qdel"
$ qdel 6005
, where 6005 is JOB ID which you can see through "qstat"

=== paradis.serial.run ===
<blockquote style="background: white; border: 0; padding: 1em; width: 750px;"><pre>
#!/bin/bash

### Job id
#PBS -N CYL_T4_MC2.3
### #PBS -N fmm.8cpu

#PBS -j oe

### ppn : # of cpus / walltime = running time
#PBS -l nodes=1:ppn=1,walltime=48:00:00
#PBS -V

### ---------------------------------------
### BEGINNING OF EXECUTION
### ---------------------------------------

echo The master node of this job is `hostname`
echo The working directory is `echo $PBS_O_WORKDIR`
echo This job runs on the following nodes:
echo `cat $PBS_NODEFILE`

ncpu=`cat $PBS_NODEFILE | wc -w`
echo "Number of processors = $ncpu "

### end of information preamble

cd $PBS_O_WORKDIR

echo $PWD

cd $PBS_O_WORKDIR

export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:/home/iryu/Codes/fftw3_lib
export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:/usr/lib64:/home/iryu/usr/lib

### To see which compiler is being used.(You can see it from Job_id.oJOBNAME)
###ldd bin/paradiscyl

bin/paradiscyl tests/CYL_test/CYL_T5_MC2/CYL_T4_MC2_3.ctrl >& tests/CYL_test/CYL_T4_MC2/CYL_T4_MC2_3.log

</pre></blockquote>

=== Run several single-cpu jobs in MC2 ===

If you want to run many jobs which all use just one cpu, we can use the following stop the calculation, we can do it by submitting the following file.
For example, if you want to run two jobs whose command are

bin/paradiscyl tests/CYL_TEST1.ctrl >& tests/CYL_TEST1.log
bin/paradiscyl tests/CYL_TEST2.ctrl >& tests/CYL_TEST2.log

, you can use the following file.
<blockquote style="background: white; border: 0; padding: 1em; width: 750px;"><pre>
#!/bin/bash

### Job id
#PBS -N CYL_TEST
### #PBS -N fmm.8cpu

#PBS -j oe

### ppn : # of cpus / walltime = running time
#PBS -l nodes=1:ppn=1,walltime=48:00:00
#PBS -V

### ---------------------------------------
### BEGINNING OF EXECUTION
### ---------------------------------------

echo The master node of this job is `hostname`
echo The working directory is `echo $PBS_O_WORKDIR`
echo This job runs on the following nodes:
echo `cat $PBS_NODEFILE`

ncpu=`cat $PBS_NODEFILE | wc -w`
echo "Number of processors = $ncpu "

### end of information preamble

cd $PBS_O_WORKDIR

echo $PWD

cd $PBS_O_WORKDIR

export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:/home/iryu/Codes/fftw3_lib
export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:/usr/lib64:/home/iryu/usr/lib

### To see which compiler is being used.(You can see it from Job_id.oJOBNAME)
###ldd bin/paradiscyl

bin/paradiscyl tests/CYL_TEST1.ctrl >& tests/CYL_TEST1.log &
bin/paradiscyl tests/CYL_TEST2.ctrl >& tests/CYL_TEST2.log &

wait
</pre></blockquote>

The only difference is to put ampersand sign(&) in the end of the command line.

Parallel Cluster Guides

2012-05-01T23:11:41Z

Iryu: /* run ParaDiS in MC2 */

__TOC__
=su-ahpcrc=
The default settings for MPI will cause the code to use GCC rather than the Intel compilers. To change this:
*EXTREMELY IMPORTANT: Ensure that nothing related to Intel has been added to your path in .bashrc and .bash_profile
*Run:
<blockquote style="background: white; border: 0; padding: 1em; width: 400px;"><pre>
$ mpi-selector --query
default:mvapich2_intel-1.2
level:user
</pre></blockquote>
*If your result is something other than the above (version number may differ), execute:
<blockquote style="background: white; border: 0; padding: 1em; width: 400px;"><pre>
$ mpi-selector --set mvapich2_intel-1.2
</pre></blockquote>
*Log out and reconnect to the cluster
*If everything is correct, asking <tt>which mpicc</tt> should yield:
<blockquote style="background: white; border: 0; padding: 1em; width: 400px;"><pre>
$ which mpicc
/usr/mpi/intel/mvapich2-1.2/bin/mpicc
</pre></blockquote>
*Add the following to makefile.sys, if not present:
<blockquote style="background: white; border: 0; padding: 1em; width: 550px;"><pre>
########################################################
#
# System type: su-ahpcrc
#
# Stanford ME linux system using intel compilers
#
########################################################

#
# Define parallel and serial compilers and compiler flags
# and set the default compiler based on the execution mode
# (defined by user in makefile)
#
CC_PARALLEL.su-ahpcrc = mpicc
CPP_PARALLEL.su-ahpcrc = mpicxx
CCFLAG_PARALLEL.su-ahpcrc = -longdouble -DLONGDOUBLE -DPARALLEL=1
CPPFLAG_PARALLEL.su-ahpcrc =

CC_SERIAL.su-ahpcrc = icc
CPP_SERIAL.su-ahpcrc = icpc
CCFLAG_SERIAL.su-ahpcrc = -DLONGDOUBLE
CPPFLAG_SERIAL.su-ahpcrc =

F90.su-ahpcrc = ifort
F90_OPTS.su-ahpcrc =
F90_LIB.su-ahpcrc = -L/opt/intel/fce/10.1.015/lib -lifcore

CC.su-ahpcrc = $(CC_$(MODE).su-ahpcrc)
CPP.su-ahpcrc = $(CPP_$(MODE).su-ahpcrc)
CCFLAG.su-ahpcrc = $(CCFLAG_$(MODE).su-ahpcrc)
CPPFLAG.su-ahpcrc = $(CPPFLAG_$(MODE).su-ahpcrc)

XLIB_LIBDIR.su-ahpcrc = /usr/X11R6/lib64
XLIB_LIB.su-ahpcrc = -L$(XLIB_LIBDIR.su-ahpcrc) -lX11 -lpthread
XLIB_INCS.su-ahpcrc =

MPI_LIBDIR.su-ahpcrc = -L/export/apps/mvapich/intel/lib
MPI_LIB.su-ahpcrc = -lmpich
MPI_INCS.su-ahpcrc =

OPENMP_FLAG.su-ahpcrc = -openmp

#
# Identify any additional libraries and paths needed for compilation
# on this system type
#
LIB_PARALLEL.su-ahpcrc =
INCS_PARALLEL.su-ahpcrc =

LIB_SERIAL.su-ahpcrc =-L../lib
INCS_SERIAL.su-ahpcrc =
</pre></blockquote>
*When compiling the code, seeing <tt>icc</tt> and comments about vectorizing loops such as "<tt>StressTableGen.c(357): (col. 37) remark: LOOP WAS VECTORIZED.</tt>" are signs that the Intel compilers were used.
*Use a PBS script similar to the following (<tt>/opt/mpiexec/bin/mpiexec --comm=pmi</tt> is the only important difference):
<blockquote style="background: white; border: 0; padding: 1em; width: 600px;"><pre>
#!/bin/bash
#PBS -N ParaDiS
#PBS -j oe
#PBS -l nodes=1:ppn=8,walltime=24:00:00
#PBS -V

### ---------------------------------------
### BEGINNING OF EXECUTION
### ---------------------------------------

echo The master node of this job is `hostname`
echo The working directory is `echo $PBS_O_WORKDIR`
echo This job runs on the following nodes:
echo `cat $PBS_NODEFILE`

ncpu=`cat $PBS_NODEFILE | wc -w`
echo "Number of processors = $ncpu "

### end of information preamble

cd $PBS_O_WORKDIR

echo $PWD

PARADIS_O_DIR="tests/fmm_8cpu_results"
mkdir -p $PARADIS_O_DIR
cmd="/opt/mpiexec/bin/mpiexec --comm=pmi -np $ncpu bin/paradis tests/fmm_8cpu.ctrl"
$cmd >& $PARADIS_O_DIR/paradis.log
</pre></blockquote>
*Submit the job using a command similar to:
<blockquote style="background: white; border: 0; padding: 1em; width: 400px;"><pre>
$ qsub paradis.pbs
</pre></blockquote>

=mc2=
By default, you will not have access to Intel compilers or MPI. They need to be added with the module command.
*EXTREMELY IMPORTANT: Ensure that nothing related to Intel has been added to your path in .bashrc and .bash_profile
*To see the list of available modules use: <tt>module avial</tt>
*To temporarily add the modules for your current session you can use <tt>module add</tt>
*To permanently add modules issue a command similar to this:
<blockquote style="background: white; border: 0; padding: 1em; width: 500px;"><pre>
$ module purge
$ module initrm intel/intel-11 mvapich/1.2rc1-intel-11-dell-gen2
$ module initadd intel/intel-12 mvapich2/1.7rc1-intel-12
$ module load intel/intel-12 mvapich2/1.7rc1-intel-12
</pre></blockquote>

=run ParaDiS in MC2=

To run a ParaDiS input in mc2, we need to edit the following file("paradis.serial.run") and submit it.

=== In paradis.serial.run ===
First of all, we can specify the JOB NAME in "[[#paradis.serial.run|paradis.serial.run]]", as follows

### Job id
#PBS -N CYL_T4_MC2.3

,where JOB NAME is CYL_T4_MC2.3 which is used when you check if the input file is running well.

Next, we need to specify the input file and the location of the log file will be written, as follows.

bin/paradiscyl tests/CYL_test/CYL_T5_MC2/CYL_T4_MC2_3.ctrl >& tests/CYL_test/CYL_T4_MC2/CYL_T4_MC2_3.log

We can see that the first part ("bin/paradiscyl tests/CYL_test/CYL_T5_MC2/CYL_T4_MC2_3.ctrl") is exactly same as the command you use when you run a input file in your computer.After this simbol(" >&"), the name of log file is specified("tests/CYL_test/CYL_T4_MC2/CYL_T4_MC2_3.log")

Then, we need to turn off the x-window in "winDefaultsFile" which is specified in the ctrl file.
For example, if it is "inputs/paradis.xdefaults", modify this file as follows.If you don't have X-server in your computer, you need to do the same thing to run the simulation.
enable_window = 0 # Toggle enabling/disabling simulation X-window.

=== submit paradis.serial.run ===
Finally, submit this file("paradis.serial.run") in MC2, as follows.

$ qsub paradis.serial.run
6006.mc2.stanford.edu

Job id("6006.mc2") will be shown in the screen.

After that, we can check if the input file in running using "qstat" or "showq"

$ qstat
Job id Name User Time Use S Queue
------------------------- ---------------- --------------- -------- - -----
5976.mc2 YSZ_CC5 inmyway 597:13:0 R default
5977.mc2 YSZ_CC6 inmyway 597:11:2 R default
5978.mc2 YSZ_CC7 inmyway 597:05:2 R default
5979.mc2 YSZ_CC8 inmyway 597:08:0 R default
5980.mc2 YSZ_CC9 inmyway 597:08:5 R default
5981.mc2 YSZ_CC10 inmyway 597:07:1 R default
5982.mc2 YSZ_CC11 inmyway 398:06:0 R default
5999.mc2 ...mmps_Test-hcp yanmingw 147:57:1 R default
6000.mc2 AuSi_Lammps_Test yanmingw 147:48:1 R default
6005.mc2 YSZ_S2_NEB inmyway 15:46:24 R default
<u>6006.mc2 CYL_T4_MC2.3 iryu 00:00:00 R default</u>

Moreover, you can see the progress in the log file, as follows.
$ cd tests/CYL_test/
$ vi CYL_T4_MC2_3.log

=== check compilers ===
We can check which compilers are used, as follows.

$ ldd bin/paradiscyl
libm.so.6 => /lib64/libm.so.6 (0x00000038dba00000)
libX11.so.6 => /usr/lib64/libX11.so.6 (0x00000038de200000)
libpthread.so.0 => /lib64/libpthread.so.0 (0x00000038dc200000)
libfftw3.so.3 => /usr/lib64/libfftw3.so.3 (0x0000003440200000)
libgsl.so.0 => /home/iryu/usr/lib/libgsl.so.0 (0x00002b38ee018000)
libgslcblas.so.0 => /home/iryu/usr/lib/libgslcblas.so.0 (0x00002b38ee545000)
libstdc++.so.6 => /usr/lib64/libstdc++.so.6 (0x00000038ee000000)
libgcc_s.so.1 => /lib64/libgcc_s.so.1 (0x00000038ebc00000)
libc.so.6 => /lib64/libc.so.6 (0x00000038db600000)
libdl.so.2 => /lib64/libdl.so.2 (0x00000038dbe00000)
libXau.so.6 => /usr/lib64/libXau.so.6 (0x00000038dd600000)
libXdmcp.so.6 => /usr/lib64/libXdmcp.so.6 (0x00000038dde00000)
/lib64/ld-linux-x86-64.so.2 (0x00000038db200000)
libimf.so => /share/apps/intel/lib/intel64/libimf.so (0x00002b38ee7af000)
libsvml.so => /share/apps/intel/lib/intel64/libsvml.so (0x00002b38eeb92000)
libintlc.so.5 => /share/apps/intel/lib/intel64/libintlc.so.5 (0x00002b38ef23a000)

If you have some problem to find proper compiler, we need to add it in your user bash_profile.
To do that, check your bash_profile, as follows.

$ cd ~
$ vi ~/.bash_profile

In "bash_profile", we need to specify path for "LD_LIBRARY_PATH", as follows.
export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:/home/iryu/Codes/fftw3_lib
export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:/usr/lib64:/home/iryu/usr/lib
export TARGET=mc2

After that, copy proper files to the path which is specified in bash_profile.
For example, if "libfftw3.so.3" is missing,
$ cp libfftw3.so.3 usr/lib/

=== kill the job ===
If you want to stop the calculation, we can do it using "qdel"
$ qdel 6005
, where 6005 is JOB ID which you can see through "qstat"

=== paradis.serial.run ===
<blockquote style="background: white; border: 0; padding: 1em; width: 750px;"><pre>
#!/bin/bash

### Job id
#PBS -N CYL_T4_MC2.3
### #PBS -N fmm.8cpu

#PBS -j oe

### ppn : # of cpus / walltime = running time
#PBS -l nodes=1:ppn=1,walltime=48:00:00
#PBS -V

### ---------------------------------------
### BEGINNING OF EXECUTION
### ---------------------------------------

echo The master node of this job is `hostname`
echo The working directory is `echo $PBS_O_WORKDIR`
echo This job runs on the following nodes:
echo `cat $PBS_NODEFILE`

ncpu=`cat $PBS_NODEFILE | wc -w`
echo "Number of processors = $ncpu "

### end of information preamble

cd $PBS_O_WORKDIR

echo $PWD

cd $PBS_O_WORKDIR

export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:/home/iryu/Codes/fftw3_lib
export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:/usr/lib64:/home/iryu/usr/lib

### To see which compiler is being used.(You can see it from Job_id.oJOBNAME)
###ldd bin/paradiscyl

bin/paradiscyl tests/CYL_test/CYL_T5_MC2/CYL_T4_MC2_3.ctrl >& tests/CYL_test/CYL_T4_MC2/CYL_T4_MC2_3.log

</pre></blockquote>

=== Run several single-cpu jobs in MC2 ===

If you want to run many jobs which all use just one cpu, we can use the following stop the calculation, we can do it by submitting the following file.
For example, if you want to run two jobs whose command are

bin/paradiscyl tests/CYL_TEST1.ctrl >& tests/CYL_TEST1.log
bin/paradiscyl tests/CYL_TEST2.ctrl >& tests/CYL_TEST2.log

, you can use the following file.

<blockquote style="background: white; border: 0; padding: 1em; width: 750px;"><pre>
#!/bin/bash

### Job id
#PBS -N CYL_TEST
### #PBS -N fmm.8cpu

#PBS -j oe

### ppn : # of cpus / walltime = running time
#PBS -l nodes=1:ppn=1,walltime=48:00:00
#PBS -V

### ---------------------------------------
### BEGINNING OF EXECUTION
### ---------------------------------------

echo The master node of this job is `hostname`
echo The working directory is `echo $PBS_O_WORKDIR`
echo This job runs on the following nodes:
echo `cat $PBS_NODEFILE`

ncpu=`cat $PBS_NODEFILE | wc -w`
echo "Number of processors = $ncpu "

### end of information preamble

cd $PBS_O_WORKDIR

echo $PWD

cd $PBS_O_WORKDIR

export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:/home/iryu/Codes/fftw3_lib
export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:/usr/lib64:/home/iryu/usr/lib

### To see which compiler is being used.(You can see it from Job_id.oJOBNAME)
###ldd bin/paradiscyl

bin/paradiscyl tests/CYL_TEST1.ctrl >& tests/CYL_TEST1.log &
bin/paradiscyl tests/CYL_TEST2.ctrl >& tests/CYL_TEST2.log &

wait

</pre></blockquote>

The only difference is to put ampersand sign(&) in the end of the command line.

PARADISCYL:Cylinder-Project surface node

2011-12-08T09:43:58Z

Iryu:

<P ALIGN="CENTER">
<FONT SIZE="+3" color="darkred"><STRONG>
Project surface nodes </STRONG></font></P>
<DIV>
<P ALIGN="CENTER"><STRONG>ill Ryu and Wei Cai</STRONG></P>
</DIV>

In the cylinder code, surface nodes need to stay on the surface of the cylinder. If they move outside the cylinder, it can be handled by Cylinder_Remesh(). However, if they move inside cylinder surface, it make a bug. In this Wiki page describe how to project the surface nodes when they moves inside the cylinder surface.

When the surface nodes move outside of the cylinder, Cylinder_Remesh() makes new surface node with flag''6'' (See figure 1.(c)). In the cylinder code, when two surface nodes are linked to each other, this segment is removed.(See figure 1.(d)).
{|border="0" align="center"
|[[Image:Project_out.jpg‎ |frameless|800px|caption]]
|-
|colspan="2" | Fig.1 (a)Schematic diagram when the surface node moves outwards

However, if the surface nodes move inside of the cylinder, this node is projected on the surface.To do that, the center point of the same slip plane is computed. From the center point, this node is projected along this line.
{|border="0" align="center"
|[[Image:Project_in.jpg‎ |frameless|800px|caption]]
|-
|colspan="2" | Fig.2 (a)Schematic diagram when the surface node moves inwards .

<HR>

PARADISCYL:Cylinder-Project surface node

2011-12-08T09:30:44Z

Iryu:

<P ALIGN="CENTER">
<FONT SIZE="+3" color="darkred"><STRONG>
Project surface nodes </STRONG></font></P>
<DIV>
<P ALIGN="CENTER"><STRONG>ill Ryu and Wei Cai</STRONG></P>
</DIV>

In the cylinder code, surface nodes need to stay on the surface of the cylinder. If they move outside the cylinder, it can be handled by Cylinder_Remesh(). However, if they move inside cylinder surface, it make a bug. In this Wiki page describe how to project the surface nodes when they moves inside the cylinder surface.

When the surface nodes move outside of the cylinder, cylinder code makes a new surface node with flag of '6' (See figure 1.(c)).In cylinder code, if two surface nodes are linked to each other, it is removed in Cylinder_Remesh(), as shown in figure 1.
{|border="0" align="center"
|[[Image:Project_out.jpg‎ |frameless|800px|caption]]
|-
|colspan="2" | Fig.1 (a)Schematic diagram when the surface node moves outwards

In the cylinder code, surface nodes need to stay on the surface of the cylinder. If they move outside the cylinder, it can be handled by Cylinder_Remesh(). However, if they move inside cylinder surface, it make a bug. In this Wiki page describe how to project the surface nodes when they moves inside the cylinder surface.

{|border="0" align="center"
|[[Image:Project_in.jpg‎ |frameless|800px|caption]]
|-
|colspan="2" | Fig.2 (a)Schematic diagram when the surface node moves inwards .

<HR>

PARADISCYL:Cylinder-Project surface node

2011-12-08T09:16:58Z

Iryu:

<P ALIGN="CENTER">
<FONT SIZE="+3" color="darkred"><STRONG>
Project surface nodes </STRONG></font></P>
<DIV>
<P ALIGN="CENTER"><STRONG>ill Ryu and Wei Cai</STRONG></P>
</DIV>

In the cylinder code, surface nodes need to stay on the surface of the cylinder. If they move outside the cylinder, it can be handled by Cylinder_Remesh(). However, if they move inside cylinder surface, it make a bug. In this Wiki page describe how to project the surface nodes when they moves inside the cylinder surface.

{|border="0" align="center"
|[[Image:Project_out.jpg‎ |frameless|800px|caption]]
|-
|colspan="2" | Fig.1 (a)Schematic diagram.

Searching for the surface node(node in Figure 1.(a))
<HR>

==Algorithm==

1. Searching for the surface node(node in Figure 1.(a))

2. Find the neighbor node(nbr1 in Figure 1.(a))

3. Check if ''seglength'' is less than ''minSeg''

4. Count the number of independent slip planes of inside arms.

''Case I'':if nbr1 has a independent slip plane and nbr1 has 3, 2 of which are linked to surface
-> Project nbr1 to the surface along the line(See figure 1.(b))

''Case II'':if nbr1 has 2 independent slip planes
Project nbr1 to surface along the intersection of two slip planes(See figure 1.(c))

<HR>

File:Project in.jpg

2011-12-08T09:16:32Z

Iryu: uploaded a new version of "File:Project in.jpg"

File:Project in.jpg

2011-12-08T09:16:11Z

Iryu: uploaded a new version of "File:Project in.jpg"

File:Project in.jpg

2011-12-08T09:15:57Z

Iryu: uploaded a new version of "File:Project in.jpg"

File:Project out.jpg

2011-12-08T09:15:08Z

Iryu: uploaded a new version of "File:Project out.jpg"

File:Project out.jpg

2011-12-08T09:14:00Z

Iryu: uploaded a new version of "File:Project out.jpg"

File:Project in.jpg

2011-12-08T09:01:18Z

Iryu:

File:Project out.jpg

2011-12-08T09:01:06Z

Iryu:

PARADISCYL:Cylinder-Remove surface debris

2011-12-08T08:14:00Z

Iryu:

<P ALIGN="CENTER">
<FONT SIZE="+3" color="darkred"><STRONG>
Remove surface debris </STRONG></font></P>
<DIV>
<P ALIGN="CENTER"><STRONG>ill Ryu and Wei Cai</STRONG></P>
</DIV>

There is remaining issue realted to the time step due to the small dislocation segments.This tutorial describes how to remove tiny dislocation segment in cylinder code.

When two dislocations meet near the surface and form a junction, it would generate very tiny segments, which occur rapid drop in time step. To overcome this issue,we remove these small dislocation segment according to the following algorithm.

<HR>

==Algorithm==

1. Searching for the surface node(node in Figure 1.(a))

2. Find the neighbor node(nbr1 in Figure 1.(a))

3. Check if ''seglength'' is less than ''minSeg''

4. Count the number of independent slip planes of inside arms.

''Case I'':if nbr1 has a independent slip plane and nbr1 has 3, 2 of which are linked to surface
-> Project nbr1 to the surface along the line(See figure 1.(b))

''Case II'':if nbr1 has 2 independent slip planes
Project nbr1 to surface along the intersection of two slip planes(See figure 1.(c))

{|border="0" align="center"
|[[Image:Remove_surface_debris1.jpg‎ |frameless|200px|caption]]
|[[Image:Remove_surface_debris2.jpg‎ |frameless|200px|caption]]
|[[Image:Remove_surface_debris3.jpg‎ |frameless|200px|caption]]
|-
|align="center"|(a)
|align="center"|(b)
|align="center"|(c)
|-
|colspan="2" | Fig.1 (a)Schematic diagram (b) Case ''I'' (c) Case ''II''.

<HR>

PARADISCYL:Cylinder-Remove surface debris

2011-12-08T08:09:33Z

Iryu: /* Algorithm */

<P ALIGN="CENTER">
<FONT SIZE="+3" color="darkred"><STRONG>
Remove surface debris </STRONG></font></P>
<DIV>
<P ALIGN="CENTER"><STRONG>ill Ryu and Wei Cai</STRONG></P>
</DIV>

There is remaining issue realted to the time step due to the small dislocation segments.This tutorial describes how to remove tiny dislocation segment in cylinder code.

When two dislocations meet near the surface and form a junction, it would generate very tiny segments, which occur rapid drop in time step. To overcome this issue,

<HR>

==Algorithm==

1. Searching for the surface node(node in Figure 1.(a))

2. Find the neighbor node(nbr1 in Figure 1.(a))

3. Check if ''seglength'' is less than ''minSeg''

4. Count the number of independent slip planes of inside arms.

''Case I'':if nbr1 has a independent slip plane and nbr1 has 3, 2 of which are linked to surface
-> Project nbr1 to the surface along the line(See figure 1.(b))

''Case II'':if nbr1 has 2 independent slip planes
Project nbr1 to surface along the intersection of two slip planes(See figure 1.(c))

{|border="0" align="center"
|[[Image:Remove_surface_debris1.jpg‎ |frameless|200px|caption]]
|[[Image:Remove_surface_debris2.jpg‎ |frameless|200px|caption]]
|[[Image:Remove_surface_debris3.jpg‎ |frameless|200px|caption]]
|-
|align="center"|(a)
|align="center"|(b)
|align="center"|(c)
|-
|colspan="2" | Fig.1 (a)Schematic diagram (b) Case ''I'' (c) Case ''II''.

<HR>

PARADISCYL:Cylinder-Remove surface debris

2011-12-08T07:54:05Z

Iryu:

<P ALIGN="CENTER">
<FONT SIZE="+3" color="darkred"><STRONG>
Remove surface debris </STRONG></font></P>
<DIV>
<P ALIGN="CENTER"><STRONG>ill Ryu and Wei Cai</STRONG></P>
</DIV>

There is remaining issue realted to the time step due to the small dislocation segments.This tutorial describes how to remove tiny dislocation segment in cylinder code.

When two dislocations meet near the surface and form a junction, it would generate very tiny segments, which occur rapid drop in time step. To overcome this issue,

<HR>

==Algorithm==

1. Searching for the surface node(node in Figure 1.(a))

2. Find the neighbor node(nbr1 in Figure 1.(a))

3. Check if ''seglength'' is less than ''minSeg''

4. Count number of independent slip plane of inside arms.

{|border="0" align="center"
|[[Image:Remove_surface_debris1.jpg‎ |frameless|200px|caption]]
|[[Image:Remove_surface_debris2.jpg‎ |frameless|200px|caption]]
|[[Image:Remove_surface_debris3.jpg‎ |frameless|200px|caption]]
|-
|align="center"|(a)
|align="center"|(b)
|align="center"|(c)
|-
|colspan="2" | Fig.1 (a)Schematic diagram (b) Case ''I'' (c) Case ''II''.

<HR>

File:Remove surface debris1.jpg

2011-12-08T07:47:45Z

Iryu: uploaded a new version of "File:Remove surface debris1.jpg"

File:Remove surface debris2.jpg

2011-12-08T07:47:28Z

Iryu: uploaded a new version of "File:Remove surface debris2.jpg"

File:Remove surface debris3.jpg

2011-12-08T07:47:10Z

Iryu: uploaded a new version of "File:Remove surface debris3.jpg"

File:Remove surface debris3.jpg

2011-12-08T07:40:21Z

Iryu:

File:Remove surface debris2.jpg

2011-12-08T07:40:11Z

Iryu:

File:Remove surface debris1.jpg

2011-12-08T07:39:58Z

Iryu:

PARADISCYL:Cylinder-Remove surface debris

2011-12-08T07:27:52Z

Iryu:

<P ALIGN="CENTER">
<FONT SIZE="+3" color="darkred"><STRONG>
Remove surface debris </STRONG></font></P>
<DIV>
<P ALIGN="CENTER"><STRONG>ill Ryu and Wei Cai</STRONG></P>
</DIV>

There is remaining issue realted to the time step due to the small dislocation segments.This tutorial describes how to remove tiny dislocation segment in cylinder code.

<HR>

==Algorithm==

1. Searching for the surface node(node in Figure 2.(a))

2. Find the neighbor node(nbr1 in Figure 2.(a))

3. Check if the character of surface segment is similar to screw
<math> 1.0-\mathbf{b} \cdot \mathbf{ \xi}<= \epsilon</math>
, where <math>\epsilon</math> is a tolerance.

4. Given burgers vector, there are three possible slip planes. For example, if <math>\mathbf{b} = a[111]</math>, then possible slip planes are <math>\mathbf{n}_1 = [1\bar{1}1],\mathbf{n}_2 = [0\bar{1}1],\mathbf{n}_3 = [\bar{1}01]</math>(See figure 2(b))

5. Compute projected forces on each plane.
<math>\mathbf{F}_{i} = \mathbf{F}_{total}-(\mathbf{F}_{total} \cdot \mathbf{n}_i)\mathbf{n}_i</math>

6. Based on the magnitudes of <math>\mathbf{F}_{i}</math>, choose slip plane of the surface dislocation segment.
{|border="0" align="center"
|[[Image:cylinder_fig.jpg‎ |frameless|300px|caption]]
|[[Image:slip_system.jpg‎ |frameless|300px|caption]]
|-
|align="center"|(a)
|align="center"|(b)
|-
|colspan="2" | Fig.2 (a)Schematic (b) Slip system <math>\mathbf{b} = a[111],\mathbf{n}_1 = [1\bar{1}1],\mathbf{n}_2 = [0\bar{1}1],\mathbf{n}_3 = [\bar{1}01]</math>.
<HR>

PARADISCYL:Cylinder-Surface cross slip

2011-12-08T01:01:34Z

Iryu: /* Algorithm */

<P ALIGN="CENTER">
<FONT SIZE="+3" color="darkred"><STRONG>
Surface cross slip </STRONG></font></P>
<DIV>
<P ALIGN="CENTER"><STRONG>ill Ryu and Wei Cai</STRONG></P>
</DIV>

This tutorial describes how to implement cross slip mechanism from the cylinder surface. The theoretical background is published in Computing Image Stress in an Elastic Cylinder(''Proceedings of the National Academy of Sciences'', '''105''', 14304 (2008)http://micro.stanford.edu/~caiwei/papers/Weinberger08PNAS-bccpillar.pdf (PDF)])

== How to select slip plane of the surface segments==

To implement surface cross slip in cylinder code, we change the slip plane of the surface nodes with respect to the magnitude of the force on the surface nodes.To do that,dislocation character of the surface nodes should be screw-like.
[[Image:Schematic_view.jpg|frameless|300px|right|Fig.2. ]]

If there is a screw dislocation in the BCC crystal in left figure, we can see that there are three possible slip planes(red, blue green planes in the figure). From the MD calculation, we knew the image stress generate the force to move dislocations in the direction along which the length of dislocation would be shortened.Therefore, image force points downward for the front node, while it points upward for the back node(Figure 1). However, P-K force points in same direction both front node and back node. Taking the summation of these forces into account, the slip plane is selected as the one on which projected total force has maximum value.

{|border="0" align="center"
|[[Image:Force_sum1.jpg|frameless|350px|caption]]
|[[Image:Force_sum2.jpg|frameless|350px|caption]]
|-
|align="center"|(a)
|align="center"|(b)
|-
|colspan="2" | Fig.1 (a) When the P-K force is dominant(blue plane is taken as a slip plane for the front node, while red plane is selected for the back node)(b) When the image force is dominant(green plane is taken as a slip plane)

In this mechanism, straight edge dislocation has two different slip planes(See Figure 1-(a)).
<HR>

==Algorithm==

1. Searching for the surface node(node in Figure 2.(a))

2. Find the neighbor node(nbr1 in Figure 2.(a))

3. Check if the character of surface segment is similar to screw
<math> 1.0-\mathbf{b} \cdot \mathbf{ \xi}<= \epsilon</math>
, where <math>\epsilon</math> is a tolerance.

4. Given burgers vector, there are three possible slip planes. For example, if <math>\mathbf{b} = a[111]</math>, then possible slip planes are <math>\mathbf{n}_1 = [1\bar{1}1],\mathbf{n}_2 = [0\bar{1}1],\mathbf{n}_3 = [\bar{1}01]</math>(See figure 2(b))

5. Compute projected forces on each plane.
<math>\mathbf{F}_{i} = \mathbf{F}_{total}-(\mathbf{F}_{total} \cdot \mathbf{n}_i)\mathbf{n}_i</math>

6. Based on the magnitudes of <math>\mathbf{F}_{i}</math>, choose slip plane of the surface dislocation segment.
{|border="0" align="center"
|[[Image:cylinder_fig.jpg‎ |frameless|300px|caption]]
|[[Image:slip_system.jpg‎ |frameless|300px|caption]]
|-
|align="center"|(a)
|align="center"|(b)
|-
|colspan="2" | Fig.2 (a)Schematic (b) Slip system <math>\mathbf{b} = a[111],\mathbf{n}_1 = [1\bar{1}1],\mathbf{n}_2 = [0\bar{1}1],\mathbf{n}_3 = [\bar{1}01]</math>.
<HR>

PARADISCYL:Cylinder-Surface cross slip

2011-12-08T01:00:50Z

Iryu: /* How to select slip plane of the surface segments */

<P ALIGN="CENTER">
<FONT SIZE="+3" color="darkred"><STRONG>
Surface cross slip </STRONG></font></P>
<DIV>
<P ALIGN="CENTER"><STRONG>ill Ryu and Wei Cai</STRONG></P>
</DIV>

This tutorial describes how to implement cross slip mechanism from the cylinder surface. The theoretical background is published in Computing Image Stress in an Elastic Cylinder(''Proceedings of the National Academy of Sciences'', '''105''', 14304 (2008)http://micro.stanford.edu/~caiwei/papers/Weinberger08PNAS-bccpillar.pdf (PDF)])

== How to select slip plane of the surface segments==

To implement surface cross slip in cylinder code, we change the slip plane of the surface nodes with respect to the magnitude of the force on the surface nodes.To do that,dislocation character of the surface nodes should be screw-like.
[[Image:Schematic_view.jpg|frameless|300px|right|Fig.2. ]]

If there is a screw dislocation in the BCC crystal in left figure, we can see that there are three possible slip planes(red, blue green planes in the figure). From the MD calculation, we knew the image stress generate the force to move dislocations in the direction along which the length of dislocation would be shortened.Therefore, image force points downward for the front node, while it points upward for the back node(Figure 1). However, P-K force points in same direction both front node and back node. Taking the summation of these forces into account, the slip plane is selected as the one on which projected total force has maximum value.

{|border="0" align="center"
|[[Image:Force_sum1.jpg|frameless|350px|caption]]
|[[Image:Force_sum2.jpg|frameless|350px|caption]]
|-
|align="center"|(a)
|align="center"|(b)
|-
|colspan="2" | Fig.1 (a) When the P-K force is dominant(blue plane is taken as a slip plane for the front node, while red plane is selected for the back node)(b) When the image force is dominant(green plane is taken as a slip plane)

In this mechanism, straight edge dislocation has two different slip planes(See Figure 1-(a)).
<HR>

==Algorithm==

1. Searching for the surface node(node in Figure 2.(a))

2. Find the neighbor node(nbr1 in Figure 2.(a))

3. Check if the character of surface segment is similar to screw
<math> 1.0-\mathbf{b} \cdot \mathbf{ \xi}<= \epsilon</math>
, where <math>\epsilon</math> is a tolerance.

4. Given burgers vector, there are three possible slip planes. For example, if <math>\mathbf{b} = a[111]</math>, then possible slip planes are <math>\mathbf{n}_1 = [1\bar{1}1],\mathbf{n}_2 = [0\bar{1}1],\mathbf{n}_3 = [\bar{1}01]</math>(See figure 2(b))

5. Compute projected forces on each plane.
<math>\mathbf{F}_{i} = \mathbf{F}_{total}-(\mathbf{F}_{total} \cdot \mathbf{n}_i)\mathbf{n}_i</math>

6. Based on the magnitudes of <math>\mathbf{F}_{i}</math>, choose slip plane of the surface dislocation segment.
{|border="0" align="center"
|[[Image:cylinder_fig.jpg‎ |frameless|300px|caption]]
|[[Image:slip_system.jpg‎ |frameless|300px|caption]]
|-
|align="center"|(a)
|align="center"|(b)
|-
|colspan="2" | Fig.3 (a)Schematic (b) Slip system <math>\mathbf{b} = a[111],\mathbf{n}_1 = [1\bar{1}1],\mathbf{n}_2 = [0\bar{1}1],\mathbf{n}_3 = [\bar{1}01]</math>.
<HR>

PARADISCYL:Cylinder-Surface cross slip

2011-12-08T00:57:50Z

Iryu: /* How to select slip plane of the surface segments */

<P ALIGN="CENTER">
<FONT SIZE="+3" color="darkred"><STRONG>
Surface cross slip </STRONG></font></P>
<DIV>
<P ALIGN="CENTER"><STRONG>ill Ryu and Wei Cai</STRONG></P>
</DIV>

This tutorial describes how to implement cross slip mechanism from the cylinder surface. The theoretical background is published in Computing Image Stress in an Elastic Cylinder(''Proceedings of the National Academy of Sciences'', '''105''', 14304 (2008)http://micro.stanford.edu/~caiwei/papers/Weinberger08PNAS-bccpillar.pdf (PDF)])

== How to select slip plane of the surface segments==

To implement surface cross slip in cylinder code, we change the slip plane of the surface nodes with respect to the magnitude of the force on the surface nodes.To do that,dislocation character of the surface nodes should be screw-like.
[[Image:Schematic_view.jpg|frameless|300px|right|Fig.2. ]]

If there is a screw dislocation in the BCC crystal in left figure, we can see that there are three possible slip planes(red, blue green planes in the figure). From the MD calculation, we knew the image stress generate the force to move dislocations in the direction along which the length of dislocation shortens their length.Therefore, image force points downward for the front node, while it points upward for the back node(Figure 1). However, P-K force points in same direction both front node and back node. Taking the summation of these forces into account, the slip plane is selected as the one on which the summation of forces has maximum value.

{|border="0" align="center"
|[[Image:Force_sum1.jpg|frameless|350px|caption]]
|[[Image:Force_sum2.jpg|frameless|350px|caption]]
|-
|align="center"|(a)
|align="center"|(b)
|-
|colspan="2" | Fig.1 (a) When the P-K force is dominant(blue plane is taken as a slip plane for the front node, while red plane is selected for the back node)(b) When the image force is dominant(green plane is taken as a slip plane)

In this mechanism, straight edge dislocation has two different slip planes(See Figure 1-(a)).
<HR>

==Algorithm==

1. Searching for the surface node(node in Figure 2.(a))

2. Find the neighbor node(nbr1 in Figure 2.(a))

3. Check if the character of surface segment is similar to screw
<math> 1.0-\mathbf{b} \cdot \mathbf{ \xi}<= \epsilon</math>
, where <math>\epsilon</math> is a tolerance.

4. Given burgers vector, there are three possible slip planes. For example, if <math>\mathbf{b} = a[111]</math>, then possible slip planes are <math>\mathbf{n}_1 = [1\bar{1}1],\mathbf{n}_2 = [0\bar{1}1],\mathbf{n}_3 = [\bar{1}01]</math>(See figure 2(b))

5. Compute projected forces on each plane.
<math>\mathbf{F}_{i} = \mathbf{F}_{total}-(\mathbf{F}_{total} \cdot \mathbf{n}_i)\mathbf{n}_i</math>

6. Based on the magnitudes of <math>\mathbf{F}_{i}</math>, choose slip plane of the surface dislocation segment.
{|border="0" align="center"
|[[Image:cylinder_fig.jpg‎ |frameless|300px|caption]]
|[[Image:slip_system.jpg‎ |frameless|300px|caption]]
|-
|align="center"|(a)
|align="center"|(b)
|-
|colspan="2" | Fig.3 (a)Schematic (b) Slip system <math>\mathbf{b} = a[111],\mathbf{n}_1 = [1\bar{1}1],\mathbf{n}_2 = [0\bar{1}1],\mathbf{n}_3 = [\bar{1}01]</math>.
<HR>

PARADISCYL:Cylinder-Surface cross slip

2011-12-08T00:56:21Z

Iryu: /* Algorithm */

<P ALIGN="CENTER">
<FONT SIZE="+3" color="darkred"><STRONG>
Surface cross slip </STRONG></font></P>
<DIV>
<P ALIGN="CENTER"><STRONG>ill Ryu and Wei Cai</STRONG></P>
</DIV>

This tutorial describes how to implement cross slip mechanism from the cylinder surface. The theoretical background is published in Computing Image Stress in an Elastic Cylinder(''Proceedings of the National Academy of Sciences'', '''105''', 14304 (2008)http://micro.stanford.edu/~caiwei/papers/Weinberger08PNAS-bccpillar.pdf (PDF)])

== How to select slip plane of the surface segments==

To implement surface cross slip in cylinder code, we change the slip plane of the surface nodes with respect to the magnitude of the force on the surface nodes.To do that,dislocation character of the surface nodes should be screw-like.
[[Image:Schematic_view.jpg|frameless|300px|right|Fig.2. ]]

If there is a screw dislocation in the BCC crystal in left figure, we can see that there are three possible slip planes(red, blue green planes in the figure). From the MD calculation, we knew the image stress generate the force to move dislocation in the direction along which the length of dislocation shortens.Therefore, image force points downward for the front node, while it points upward for the back node(Figure 1). However, P-K force points in same direction both front node and back node. Taking the summation of these forces into account, the slip plane is selected as the one on which the summation of forces has maximum value.

{|border="0" align="center"
|[[Image:Force_sum1.jpg|frameless|350px|caption]]
|[[Image:Force_sum2.jpg|frameless|350px|caption]]
|-
|align="center"|(a)
|align="center"|(b)
|-
|colspan="2" | Fig.1 (a) When the P-K force is dominant(blue plane is taken as a slip plane for the front node, while red plane is selected for the back node)(b) When the image force is dominant(green plane is taken as a slip plane)

In this mechanism, straight edge dislocation has two different slip planes(See Figure 1-(a)).
<HR>
==Algorithm==

1. Searching for the surface node(node in Figure 2.(a))

2. Find the neighbor node(nbr1 in Figure 2.(a))

3. Check if the character of surface segment is similar to screw
<math> 1.0-\mathbf{b} \cdot \mathbf{ \xi}<= \epsilon</math>
, where <math>\epsilon</math> is a tolerance.

4. Given burgers vector, there are three possible slip planes. For example, if <math>\mathbf{b} = a[111]</math>, then possible slip planes are <math>\mathbf{n}_1 = [1\bar{1}1],\mathbf{n}_2 = [0\bar{1}1],\mathbf{n}_3 = [\bar{1}01]</math>(See figure 2(b))

5. Compute projected forces on each plane.
<math>\mathbf{F}_{i} = \mathbf{F}_{total}-(\mathbf{F}_{total} \cdot \mathbf{n}_i)\mathbf{n}_i</math>

6. Based on the magnitudes of <math>\mathbf{F}_{i}</math>, choose slip plane of the surface dislocation segment.
{|border="0" align="center"
|[[Image:cylinder_fig.jpg‎ |frameless|300px|caption]]
|[[Image:slip_system.jpg‎ |frameless|300px|caption]]
|-
|align="center"|(a)
|align="center"|(b)
|-
|colspan="2" | Fig.3 (a)Schematic (b) Slip system <math>\mathbf{b} = a[111],\mathbf{n}_1 = [1\bar{1}1],\mathbf{n}_2 = [0\bar{1}1],\mathbf{n}_3 = [\bar{1}01]</math>.
<HR>

PARADISCYL:Cylinder-Surface cross slip

2011-12-08T00:54:58Z

Iryu: /* Algorithm */

<P ALIGN="CENTER">
<FONT SIZE="+3" color="darkred"><STRONG>
Surface cross slip </STRONG></font></P>
<DIV>
<P ALIGN="CENTER"><STRONG>ill Ryu and Wei Cai</STRONG></P>
</DIV>

This tutorial describes how to implement cross slip mechanism from the cylinder surface. The theoretical background is published in Computing Image Stress in an Elastic Cylinder(''Proceedings of the National Academy of Sciences'', '''105''', 14304 (2008)http://micro.stanford.edu/~caiwei/papers/Weinberger08PNAS-bccpillar.pdf (PDF)])

== How to select slip plane of the surface segments==

To implement surface cross slip in cylinder code, we change the slip plane of the surface nodes with respect to the magnitude of the force on the surface nodes.To do that,dislocation character of the surface nodes should be screw-like.
[[Image:Schematic_view.jpg|frameless|300px|right|Fig.2. ]]

If there is a screw dislocation in the BCC crystal in left figure, we can see that there are three possible slip planes(red, blue green planes in the figure). From the MD calculation, we knew the image stress generate the force to move dislocation in the direction along which the length of dislocation shortens.Therefore, image force points downward for the front node, while it points upward for the back node(Figure 1). However, P-K force points in same direction both front node and back node. Taking the summation of these forces into account, the slip plane is selected as the one on which the summation of forces has maximum value.

{|border="0" align="center"
|[[Image:Force_sum1.jpg|frameless|350px|caption]]
|[[Image:Force_sum2.jpg|frameless|350px|caption]]
|-
|align="center"|(a)
|align="center"|(b)
|-
|colspan="2" | Fig.1 (a) When the P-K force is dominant(blue plane is taken as a slip plane for the front node, while red plane is selected for the back node)(b) When the image force is dominant(green plane is taken as a slip plane)

In this mechanism, straight edge dislocation has two different slip planes(See Figure 1-(a)).
<HR>
==Algorithm==

1. Searching for the surface node(node in Figure 2.(a))

2. Find the neighbor node(nbr1 in Figure 2.(a))

3. Check if the character of surface segment is similar to screw
<math> 1.0-\mathbf{b} \cdot \mathbf{ \xi}<= \epsilon</math>
, where <math>\epsilon</math> is a tolerance.

4. Given burgers vector, there are three possible slip planes. For example, if <math>\mathbf{b} = a[111]</math>, then possible slip planes are <math>\mathbf{n}_1 = [1\bar{1}1],\mathbf{n}_2 = [0\bar{1}1],\mathbf{n}_3 = [\bar{1}01]</math>(See figure 2(b))

5. Compute projected forces on each plane.
<math>\mathbf{F}_{i} = \mathbf{F}_{total}-(\mathbf{F}_{total} \cdot \mathbf{n}_i)\mathbf{n}_i</math>

In the second test case, we consider a circular prismatic dislocation loop concentric with the cylindrical axis, discretized with 12 equally spaced nodes connected by straight segments, as shown in Fig. 3, where the dislocation loop radius is 0.8 times to the cylinder radius.
{|border="0" align="center"
|[[Image:cylinder_fig.jpg‎ |frameless|300px|caption]]
|[[Image:slip_system.jpg‎ |frameless|300px|caption]]
|-
|align="center"|(a)
|align="center"|(b)
|-
|colspan="2" | Fig.3 (a)Schematic (b) Slip system <math>\mathbf{b} = a[111],\mathbf{n}_1 = [1\bar{1}1],\mathbf{n}_2 = [0\bar{1}1],\mathbf{n}_3 = [\bar{1}01]</math>.
<HR>

PARADISCYL:Cylinder-Surface cross slip

2011-12-08T00:47:56Z

Iryu:

<P ALIGN="CENTER">
<FONT SIZE="+3" color="darkred"><STRONG>
Surface cross slip </STRONG></font></P>
<DIV>
<P ALIGN="CENTER"><STRONG>ill Ryu and Wei Cai</STRONG></P>
</DIV>

This tutorial describes how to implement cross slip mechanism from the cylinder surface. The theoretical background is published in Computing Image Stress in an Elastic Cylinder(''Proceedings of the National Academy of Sciences'', '''105''', 14304 (2008)http://micro.stanford.edu/~caiwei/papers/Weinberger08PNAS-bccpillar.pdf (PDF)])

== How to select slip plane of the surface segments==

To implement surface cross slip in cylinder code, we change the slip plane of the surface nodes with respect to the magnitude of the force on the surface nodes.To do that,dislocation character of the surface nodes should be screw-like.
[[Image:Schematic_view.jpg|frameless|300px|right|Fig.2. ]]

If there is a screw dislocation in the BCC crystal in left figure, we can see that there are three possible slip planes(red, blue green planes in the figure). From the MD calculation, we knew the image stress generate the force to move dislocation in the direction along which the length of dislocation shortens.Therefore, image force points downward for the front node, while it points upward for the back node(Figure 1). However, P-K force points in same direction both front node and back node. Taking the summation of these forces into account, the slip plane is selected as the one on which the summation of forces has maximum value.

{|border="0" align="center"
|[[Image:Force_sum1.jpg|frameless|350px|caption]]
|[[Image:Force_sum2.jpg|frameless|350px|caption]]
|-
|align="center"|(a)
|align="center"|(b)
|-
|colspan="2" | Fig.1 (a) When the P-K force is dominant(blue plane is taken as a slip plane for the front node, while red plane is selected for the back node)(b) When the image force is dominant(green plane is taken as a slip plane)

In this mechanism, straight edge dislocation has two different slip planes(See Figure 1-(a)).
<HR>
==Algorithm==

1. Searching for the surface node(node in Figure 2.(a))

2. Find the neighbor node(nbr1 in Figure 2.(a))

3. Check if the character of surface segment is similar to screw
<math> 1.0-\mathbf{b} \cdot \mathbf{ \xi}<= \epsilon</math>
, where <math>\epsilon</math> is a tolerance.

In the second test case, we consider a circular prismatic dislocation loop concentric with the cylindrical axis, discretized with 12 equally spaced nodes connected by straight segments, as shown in Fig. 3, where the dislocation loop radius is 0.8 times to the cylinder radius.
{|border="0" align="center"
|[[Image:cylinder_fig.jpg‎ |frameless|300px|caption]]
|[[Image:slip_system.jpg‎ |frameless|300px|caption]]
|-
|align="center"|(a)
|align="center"|(b)
|-
|colspan="2" | Fig.3 (a)Schematic (b) Slip system <math>\mathbf{b} = a[111],\mathbf{n}_1 = [1\bar{1}1],\mathbf{n}_2 = [0\bar{1}1],\mathbf{n}_3 = [\bar{1}01]</math>.
<HR>

PARADISCYL:Cylinder-Surface cross slip

2011-12-08T00:43:11Z

Iryu: /* Algorithm */

<P ALIGN="CENTER">
<FONT SIZE="+3" color="darkred"><STRONG>
Surface cross slip </STRONG></font></P>
<DIV>
<P ALIGN="CENTER"><STRONG>ill Ryu and Wei Cai</STRONG></P>
</DIV>

This tutorial describes how to implement cross slip mechanism from the cylinder surface. The theoretical background is published in Computing Image Stress in an Elastic Cylinder(''Proceedings of the National Academy of Sciences'', '''105''', 14304 (2008)http://micro.stanford.edu/~caiwei/papers/Weinberger08PNAS-bccpillar.pdf (PDF)])

== How to select slip plane of the surface segments==

To implement surface cross slip in cylinder code, we change the slip plane of the surface nodes with respect to the magnitude of the force on the surface nodes.To do that,dislocation character of the surface nodes should be screw-like.
[[Image:Schematic_view.jpg|frameless|300px|right|Fig.2. ]]

If there is a screw dislocation in the BCC crystal in left figure, we can see that there are three possible slip planes(red, blue green planes in the figure). From the MD calculation, we knew the image stress generate the force to move dislocation in the direction along which the length of dislocation shortens.Therefore, image force points downward for the front node, while it points upward for the back node(Figure 1). However, P-K force points in same direction both front node and back node. Taking the summation of these forces into account, the slip plane is selected as the one on which the summation of forces has maximum value.

{|border="0" align="center"
|[[Image:Force_sum1.jpg|frameless|350px|caption]]
|[[Image:Force_sum2.jpg|frameless|350px|caption]]
|-
|align="center"|(a)
|align="center"|(b)
|-
|colspan="2" | Fig.1 (a) When the P-K force is dominant(blue plane is taken as a slip plane for the front node, while red plane is selected for the back node)(b) When the image force is dominant(green plane is taken as a slip plane)

In this mechanism, straight edge dislocation has two different slip planes(See Figure 1-(a)).
<HR>
==Algorithm==

1. Searching for the surface node(node in Figure 2.(a))

2. Find the neighbor node(nbr1 in Figure 2.(a))

3. Check if the character of surface segment is similar to screw
1.0-<math>T_{ij}<= \epsilon</math> }

In the second test case, we consider a circular prismatic dislocation loop concentric with the cylindrical axis, discretized with 12 equally spaced nodes connected by straight segments, as shown in Fig. 3, where the dislocation loop radius is 0.8 times to the cylinder radius.
{|border="0" align="center"
|[[Image:cylinder_fig.jpg‎ |frameless|300px|caption]]
|[[Image:slip_system.jpg‎ |frameless|300px|caption]]
|-
|align="center"|(a)
|align="center"|(b)
|-
|colspan="2" | Fig.3 (a)Schematic (b) Slip system <math>\mathbf{b} = a[111],\mathbf{n}_1 = [1\bar{1}1],\mathbf{n}_2 = [0\bar{1}1],\mathbf{n}_3 = [\bar{1}01]</math>.
For simplicity, cell is not used for the force calculatoin. To do this, modify '''makefile''' in ParaDiS/cylinder directory so that the following line is active.
DEFS += -D_CYL_TEST23

[[Image:T2_relative_error.jpg|frameless|400px|right|Fig.4. ]]
Due to the symmetry of this problem, the image forces on all nodes point to the radial direction and
have the same magnitude. An estimate of their relative error is plotted as a function of number of grid in the circumferential direction(<math>\mathbf{n}_\theta</math>) in the following figure. Because this problem does not have an analytic solution, the reference value is taken to be the value obtained using Method I (Bessel) with <math>\mathbf{n}_\theta=181</math>. As expected, the relative error in radial image force decreases with increasing number of grids.

<HR>

PARADISCYL:Cylinder-Surface cross slip

2011-12-08T00:37:14Z

Iryu: /* Algorithm */

<P ALIGN="CENTER">
<FONT SIZE="+3" color="darkred"><STRONG>
Surface cross slip </STRONG></font></P>
<DIV>
<P ALIGN="CENTER"><STRONG>ill Ryu and Wei Cai</STRONG></P>
</DIV>

This tutorial describes how to implement cross slip mechanism from the cylinder surface. The theoretical background is published in Computing Image Stress in an Elastic Cylinder(''Proceedings of the National Academy of Sciences'', '''105''', 14304 (2008)http://micro.stanford.edu/~caiwei/papers/Weinberger08PNAS-bccpillar.pdf (PDF)])

== How to select slip plane of the surface segments==

To implement surface cross slip in cylinder code, we change the slip plane of the surface nodes with respect to the magnitude of the force on the surface nodes.To do that,dislocation character of the surface nodes should be screw-like.
[[Image:Schematic_view.jpg|frameless|300px|right|Fig.2. ]]

If there is a screw dislocation in the BCC crystal in left figure, we can see that there are three possible slip planes(red, blue green planes in the figure). From the MD calculation, we knew the image stress generate the force to move dislocation in the direction along which the length of dislocation shortens.Therefore, image force points downward for the front node, while it points upward for the back node(Figure 1). However, P-K force points in same direction both front node and back node. Taking the summation of these forces into account, the slip plane is selected as the one on which the summation of forces has maximum value.

{|border="0" align="center"
|[[Image:Force_sum1.jpg|frameless|350px|caption]]
|[[Image:Force_sum2.jpg|frameless|350px|caption]]
|-
|align="center"|(a)
|align="center"|(b)
|-
|colspan="2" | Fig.1 (a) When the P-K force is dominant(blue plane is taken as a slip plane for the front node, while red plane is selected for the back node)(b) When the image force is dominant(green plane is taken as a slip plane)

In this mechanism, straight edge dislocation has two different slip planes(See Figure 1-(a)).
<HR>
==Algorithm==

1. Searching for the surface node(node in Figure 2.(a))
2. Find the neighbor node(nbr1 in Figure 2.(a))
In the second test case, we consider a circular prismatic dislocation loop concentric with the cylindrical axis, discretized with 12 equally spaced nodes connected by straight segments, as shown in Fig. 3, where the dislocation loop radius is 0.8 times to the cylinder radius.
{|border="0" align="center"
|[[Image:cylinder_fig.jpg‎ |frameless|300px|caption]]
|[[Image:slip_system.jpg‎ |frameless|300px|caption]]
|-
|align="center"|(a)
|align="center"|(b)
|-
|colspan="2" | Fig.3 (a)Schematic (b) Slip system <math>\mathbf{b} = a[111],\mathbf{n}_1 = [1\bar{1}1],\mathbf{n}_2 = [0\bar{1}1],\mathbf{n}_3 = [\bar{1}01]</math>.
For simplicity, cell is not used for the force calculatoin. To do this, modify '''makefile''' in ParaDiS/cylinder directory so that the following line is active.
DEFS += -D_CYL_TEST23

[[Image:T2_relative_error.jpg|frameless|400px|right|Fig.4. ]]
Due to the symmetry of this problem, the image forces on all nodes point to the radial direction and
have the same magnitude. An estimate of their relative error is plotted as a function of number of grid in the circumferential direction(<math>\mathbf{n}_\theta</math>) in the following figure. Because this problem does not have an analytic solution, the reference value is taken to be the value obtained using Method I (Bessel) with <math>\mathbf{n}_\theta=181</math>. As expected, the relative error in radial image force decreases with increasing number of grids.

<HR>

File:Slip system.jpg

2011-12-08T00:29:09Z

Iryu:

File:Cylinder fig.jpg

2011-12-08T00:28:58Z

Iryu:

PARADISCYL:Cylinder-Surface cross slip

2011-12-07T23:11:46Z

Iryu:

<P ALIGN="CENTER">
<FONT SIZE="+3" color="darkred"><STRONG>
Surface cross slip </STRONG></font></P>
<DIV>
<P ALIGN="CENTER"><STRONG>ill Ryu and Wei Cai</STRONG></P>
</DIV>

This tutorial describes how to implement cross slip mechanism from the cylinder surface. The theoretical background is published in Computing Image Stress in an Elastic Cylinder(''Proceedings of the National Academy of Sciences'', '''105''', 14304 (2008)http://micro.stanford.edu/~caiwei/papers/Weinberger08PNAS-bccpillar.pdf (PDF)])

== How to select slip plane of the surface segments==

To implement surface cross slip in cylinder code, we change the slip plane of the surface nodes with respect to the magnitude of the force on the surface nodes.To do that,dislocation character of the surface nodes should be screw-like.
[[Image:Schematic_view.jpg|frameless|300px|right|Fig.2. ]]

If there is a screw dislocation in the BCC crystal in left figure, we can see that there are three possible slip planes(red, blue green planes in the figure). From the MD calculation, we knew the image stress generate the force to move dislocation in the direction along which the length of dislocation shortens.Therefore, image force points downward for the front node, while it points upward for the back node(Figure 1). However, P-K force points in same direction both front node and back node. Taking the summation of these forces into account, the slip plane is selected as the one on which the summation of forces has maximum value.

{|border="0" align="center"
|[[Image:Force_sum1.jpg|frameless|350px|caption]]
|[[Image:Force_sum2.jpg|frameless|350px|caption]]
|-
|align="center"|(a)
|align="center"|(b)
|-
|colspan="2" | Fig.1 (a) When the P-K force is dominant(blue plane is taken as a slip plane for the front node, while red plane is selected for the back node)(b) When the image force is dominant(green plane is taken as a slip plane)

In this mechanism, straight edge dislocation has two different slip planes(See Figure 1-(a)).
<HR>
==Algorithm==

In the second test case, we consider a circular prismatic dislocation loop concentric with the cylindrical axis, discretized with 12 equally spaced nodes connected by straight segments, as shown in Fig. 3, where the dislocation loop radius is 0.8 times to the cylinder radius.
{|border="0" align="center"
|[[Image:T2_flat_loop_Isoview.jpg‎ |frameless|400px|caption]]
|[[Image:T2_flat_loop_topview.jpg‎ |frameless|400px|caption]]
|-
|align="center"|(a)
|align="center"|(b)
|-
|colspan="2" | Fig.3 (a) Isoview (b) Topview.The Bergurs vector is <math>\mathbf{b} = a[001]</math>.
For simplicity, cell is not used for the force calculatoin. To do this, modify '''makefile''' in ParaDiS/cylinder directory so that the following line is active.
DEFS += -D_CYL_TEST23

[[Image:T2_relative_error.jpg|frameless|400px|right|Fig.4. ]]
Due to the symmetry of this problem, the image forces on all nodes point to the radial direction and
have the same magnitude. An estimate of their relative error is plotted as a function of number of grid in the circumferential direction(<math>\mathbf{n}_\theta</math>) in the following figure. Because this problem does not have an analytic solution, the reference value is taken to be the value obtained using Method I (Bessel) with <math>\mathbf{n}_\theta=181</math>. As expected, the relative error in radial image force decreases with increasing number of grids.

<HR>

PARADISCYL:Cylinder-Surface cross slip

2011-12-07T23:03:39Z

Iryu:

<P ALIGN="CENTER">
<FONT SIZE="+3" color="darkred"><STRONG>
Surface cross slip </STRONG></font></P>
<DIV>
<P ALIGN="CENTER"><STRONG>ill Ryu and Wei Cai</STRONG></P>
</DIV>

This tutorial describes how to implement cross slip mechanism from the cylinder surface. The theoretical background is published in Computing Image Stress in an Elastic Cylinder(''Proceedings of the National Academy of Sciences'', '''105''', 14304 (2008)http://micro.stanford.edu/~caiwei/papers/Weinberger08PNAS-bccpillar.pdf (PDF)])

== How to select slip plane of the surface segments==

To implement surface cross slip in cylinder code, we change the slip plane of the surface nodes with respect to the magnitude of the force on the surface nodes.To do that,dislocation character of the surface nodes should be screw-like.
[[Image:Schematic_view.jpg|frameless|300px|right|Fig.2. ]]

If there is a screw dislocation in the BCC crystal in left figure, we can see that there are three possible slip planes(red, blue green planes in the figure). From the MD calculation, we knew the image stress generate the force to move dislocation in the direction along which the length of dislocation shortens.Therefore, image force points downward for the front node, while it points upward for the back node(Figure 1). However, P-K force points in same direction both front node and back node. Taking the summation of these forces into account, the slip plane is selected as the one

For simplicity, we In the first test case, image stress of a straight edge dislocation is considered, as shown in the ''Figure 1'', where dislocation is offset(<math>x0</math>) from the center of the cylinder. We have two cases of <math>x0</math>=0.5<math>R</math> and 0.9<math>R</math>.Here, <math>R</math> is the radius of the cylinder.
{|border="0" align="center"
|[[Image:Force_sum1.jpg|frameless|350px|caption]]
|[[Image:Force_sum2.jpg|frameless|350px|caption]]
|-
|align="center"|(a)
|align="center"|(b)
|-
|colspan="2" | Fig.1 (a) When the P-K force is dominant(blue plane is taken as a slip plane)(b) When the image force is dominant(green plane is taken as a slip plane)

Since the image stress field of this configuration had been solved analytically[Eshelby, J.D., 1979],we compare the image force between the simulation result and analytic solution.The number of grids in circumferential direction is same as the one along the cylinder axis.To consider periodic images along the cylinder axis under PBC, analytical stress field of edge dislocation is implemented in the function of "AllSegmentStress_no_cell_test1".To use this function, modify '''makefile''' in ParaDiS/cylinder directory so that the following line is active.
DEFS += -D_CYL_TEST1

[[Image:Relative error plot.jpg|frameless|400px|right|Fig.2. ]]

Using Method I,the relative error in the image force is computed from the image stress calcualtion. Right plot clearly show exponential decay of the relative error with increasing number of grids. The convergence is slower when the location of the edge dislocation is close to the surface.

<HR>

File:Force sum2.jpg

2011-12-07T22:55:37Z

Iryu: uploaded a new version of "File:Force sum2.jpg"

File:Force sum1.jpg

2011-12-07T22:55:25Z

Iryu: uploaded a new version of "File:Force sum1.jpg"

File:Force sum2.jpg

2011-12-07T22:47:34Z

Iryu: uploaded a new version of "File:Force sum2.jpg"

File:Force sum1.jpg

2011-12-07T22:47:04Z

Iryu: uploaded a new version of "File:Force sum1.jpg"

PARADISCYL:Cylinder-Surface cross slip

2011-12-07T22:40:44Z

Iryu:

<P ALIGN="CENTER">
<FONT SIZE="+3" color="darkred"><STRONG>
Surface cross slip </STRONG></font></P>
<DIV>
<P ALIGN="CENTER"><STRONG>ill Ryu and Wei Cai</STRONG></P>
</DIV>

This tutorial describes how to implement cross slip mechanism from the cylinder surface. The theoretical background is published in Computing Image Stress in an Elastic Cylinder(''Proceedings of the National Academy of Sciences'', '''105''', 14304 (2008)http://micro.stanford.edu/~caiwei/papers/Weinberger08PNAS-bccpillar.pdf (PDF)])

== How to select slip plane of the surface segments==

To implement surface cross slip in cylinder code, we change the slip plane of the surface nodes with respect to the magnitude of the force on the surface nodes.To do that,dislocation character of the surface nodes should be screw-like.
[[Image:Schematic_view.jpg|frameless|300px|right|Fig.2. ]]

If there is a screw dislocation in the BCC crystal in left figure, we can see that there are three possible slip planes(red, blue green planes in the figure). From the MD calculation we know the image stress Using Method I,the relative error in the image force is computed from the image stress calcualtion. Right plot clearly show exponential decay of the relative error with increasing number of grids. The convergence is slower when the location of the edge dislocation is close to the surface.

For simplicity, we In the first test case, image stress of a straight edge dislocation is considered, as shown in the ''Figure 1'', where dislocation is offset(<math>x0</math>) from the center of the cylinder. We have two cases of <math>x0</math>=0.5<math>R</math> and 0.9<math>R</math>.Here, <math>R</math> is the radius of the cylinder.
{|border="0" align="center"
|[[Image:Force_sum1.jpg|frameless|350px|caption]]
|[[Image:Force_sum2.jpg|frameless|350px|caption]]
|-
|align="center"|(a)
|align="center"|(b)
|-
|colspan="2" | Fig.1 (a) When the P-K force is dominant(blue plane is taken as a slip plane)(b) When the image force is dominant(green plane is taken as a slip plane)

Since the image stress field of this configuration had been solved analytically[Eshelby, J.D., 1979],we compare the image force between the simulation result and analytic solution.The number of grids in circumferential direction is same as the one along the cylinder axis.To consider periodic images along the cylinder axis under PBC, analytical stress field of edge dislocation is implemented in the function of "AllSegmentStress_no_cell_test1".To use this function, modify '''makefile''' in ParaDiS/cylinder directory so that the following line is active.
DEFS += -D_CYL_TEST1

[[Image:Relative error plot.jpg|frameless|400px|right|Fig.2. ]]

Using Method I,the relative error in the image force is computed from the image stress calcualtion. Right plot clearly show exponential decay of the relative error with increasing number of grids. The convergence is slower when the location of the edge dislocation is close to the surface.

<HR>

File:Force sum2.jpg

2011-12-07T22:37:25Z

Iryu:

File:Force sum1.jpg

2011-12-07T22:37:12Z

Iryu:

File:Schematic view.jpg

2011-12-07T22:31:54Z

Iryu:

Overview of ParaDiS 2.2

2011-12-05T04:52:13Z

Iryu: /* Simulation time and timestepping controls */

This document is taken from ParaDiSInfo.txt in ParaDiS.v2.2 distribution. Written by Gregg Hommes, LLNL.

== Introduction ==

The Parallel Dislocation Simulator (ParaDiS) was written
and developed at LLNL by a team of physicists and computer
scientists. ParaDiS is a code for doing Dislocation Dynamics
simulations and was specifically written to perform well on
massively parallel computers. The computational approach to
Dislocation Dynamics used in ParaDiS is fairly simple. In
it, one introduces dislocation lines into the computational
volume and lets them interact and move in response to the
forces imposed by external stress and inter-dislocation
interactions.

---------------------------------------------------------------------

== Building ParaDiS ==

=== Directory Structure ===

The ParaDiS release consists of a file which, when unzipped
and untarred creates a primary directory and a structure
of subdirectories. For convenience, this primary directory
will hereafter be referred to as <ParadisDir>. The directory
structure of the release will look like:

<TABLE CELLPADDING=3 >
<TR valign="top">
<TD ALIGN="LEFT">     </TD>
<TD ALIGN="LEFT"><ParadisDir>/</TD>
<TD ALIGN="LEFT">     </TD>
<TD ALIGN="LEFT">Contains primary 'make' files for controlling build of all executables</TD>
</TR>
<TR valign="top">
<TD ALIGN="LEFT">     </TD>
<TD ALIGN="LEFT"><ParadisDir>/bin/</TD>
<TD ALIGN="LEFT">     </TD>
<TD ALIGN="LEFT">This directory will be created during the 'make' process. All executables will be placed in this directory during compilation</TD>
</TR>
<TR valign="top">
<TD ALIGN="LEFT">     </TD>
<TD ALIGN="LEFT"><ParadisDir>/docs/</TD>
<TD ALIGN="LEFT">     </TD>
<TD ALIGN="LEFT">Contains any additional documentation</TD>
</TR>
<TR valign="top">
<TD ALIGN="LEFT">     </TD>
<TD ALIGN="LEFT"><ParadisDir>/include/</TD>
<TD ALIGN="LEFT">     </TD>
<TD ALIGN="LEFT">Contains all C and C++ header files</TD>
</TR>
<TR valign="top">
<TD ALIGN="LEFT">     </TD>
<TD ALIGN="LEFT"><ParadisDir>/inputs/</TD>
<TD ALIGN="LEFT">     </TD>
<TD ALIGN="LEFT">FMM and non-FMM correction tables, X-display defaults file, gnuplot command file, etc.</TD>
</TR>
<TR valign="top">
<TD ALIGN="LEFT">     </TD>
<TD ALIGN="LEFT"><ParadisDir>/materials/</TD>
<TD ALIGN="LEFT">     </TD>
<TD ALIGN="LEFT">Sample files containing material specific tables and constants</TD>
</TR>
<TR valign="top">
<TD ALIGN="LEFT">     </TD>
<TD ALIGN="LEFT"><ParadisDir>/src/</TD>
<TD ALIGN="LEFT">     </TD>
<TD ALIGN="LEFT">All C and C++ source code modules related to the paradis executable</TD>
</TR>
<TR valign="top">
<TD ALIGN="LEFT">     </TD>
<TD ALIGN="LEFT"><ParadisDir>/tools/</TD>
<TD ALIGN="LEFT">     </TD>
<TD ALIGN="LEFT">Miscellaneous support scripts</TD>
</TR>
<TR valign="top">
<TD ALIGN="LEFT">     </TD>
<TD ALIGN="LEFT"><ParadisDir>/utilities/</TD>
<TD ALIGN="LEFT">     </TD>
<TD ALIGN="LEFT">Source code modules pertaining to the various support tools</TD>
</TR>
</TABLE>

=== Compiling ===

The current ParaDiS 'make' files support compilation for
a number of pre-defined system types that are defined in
the file 'makefile.sys'. In order to compile the code on
one of these pre-defined system types, simply edit
'makefile.setup' and set the "SYS=..." value to the
desired system type. For other system types, add a new
system type into 'makefile.sys' following the format used
for the existing systems and, as above, set the "SYS=..."
value in 'makefile.setup'.

Executing 'gmake' with no options in <ParadisDir> will
build the following executables:

<TABLE CELLPADDING=3 >
<TR valign="top">
<TD ALIGN="LEFT">     </TD>
<TD ALIGN="LEFT"><ParadisDir>/bin/paradis</TD>
<TD ALIGN="LEFT">     </TD>
<TD ALIGN="LEFT">-- Main parallel application</TD>
</TR>
<TR valign="top">
<TD ALIGN="LEFT">     </TD>
<TD ALIGN="LEFT"><ParadisDir>/bin/paradisgen</TD>
<TD ALIGN="LEFT">     </TD>
<TD ALIGN="LEFT">-- Utility for creating initial dislocation configurations (See [[#Utilities|Utilities]] section for details)</TD>
</TR>
<TR valign="top">
<TD ALIGN="LEFT">     </TD>
<TD ALIGN="LEFT"><ParadisDir>/bin/paradisrepart</TD>
<TD ALIGN="LEFT">     </TD>
<TD ALIGN="LEFT">-- Utility for generating a new domain decomposition for an existing dislocation configuration (See [[#Utilities|Utilities]] section for details)</TD>
</TR>
<TR valign="top">
<TD ALIGN="LEFT">     </TD>
<TD ALIGN="LEFT"><ParadisDir>/bin/paradisconvert</TD>
<TD ALIGN="LEFT">     </TD>
<TD ALIGN="LEFT">-- Utility for converting older format ParaDiS control parameter files to the current format (See [[#Utilities|Utilities]] section for details)</TD>
</TR>
<TR valign="top">
<TD ALIGN="LEFT">     </TD>
<TD ALIGN="LEFT"><ParadisDir>/bin/ctablegen</TD>
<TD ALIGN="LEFT">     </TD>
<TD ALIGN="LEFT">-- Utility for creating image correction tables needed when FMM code is enabled. (See [[#Utilities|Utilities]] section for details)</TD>
</TR>
<TR valign="top">
<TD ALIGN="LEFT">     </TD>
<TD ALIGN="LEFT"><ParadisDir>/bin/ctablegenp</TD>
<TD ALIGN="LEFT">     </TD>
<TD ALIGN="LEFT">-- Parallel version of the ctablegen utility. See above.</TD>
</TR>
<TR valign="top">
<TD ALIGN="LEFT">     </TD>
<TD ALIGN="LEFT"><ParadisDir>/bin/stresstablegen</TD>
<TD ALIGN="LEFT">     </TD>
<TD ALIGN="LEFT">-- Utility for creating tables used in calculating far-field stress if the FMM code is not enabled. (See [[#Utilities|Utilities]] section for details)
</TD>
</TR>
</TABLE>

=== Make files ===

Compilation of the code is done via 'gmake' and depends
on the following 'make' files located in the <ParadisDir>
directory. (See the individual make files for details)

<TABLE CELLPADDING=3 >
<TR valign="top">
<TD ALIGN="LEFT">     </TD>
<TD ALIGN="LEFT">makefile</TD>
<TD ALIGN="LEFT">     </TD>
<TD ALIGN="LEFT">-- This is the primary make file controlling the build of the parallel executable and associated utilities.
</TD>
</TR>
<TR valign="top">
<TD ALIGN="LEFT">     </TD>
<TD ALIGN="LEFT">makefile.sys</TD>
<TD ALIGN="LEFT">     </TD>
<TD ALIGN="LEFT">-- This file contains, for each supported system type, a set of 'make' macros, definitions, compiler selection, library and include file paths, etc.
</TD>
</TR>
<TR valign="top">
<TD ALIGN="LEFT">     </TD>
<TD ALIGN="LEFT">makefile.setup</TD>
<TD ALIGN="LEFT">     </TD>
<TD ALIGN="LEFT">-- Contains numerous 'make' settings and flags that are not system specific, including settings for system type, optimization level, debugging flags, etc.
</TD>
</TR>
</TABLE>

---------------------------------------------------------------------

== Executing ParaDiS ==

=== Command line ===

The ParaDiS command line format is:

paradis [-r <numCycles>] [-d dataFile] <controlFile>

where:

<TABLE CELLPADDING=3 >
<TR valign="top">
<TD ALIGN="LEFT">     </TD>
<TD ALIGN="LEFT"><ctrlFile></TD>
<TD ALIGN="LEFT">     </TD>
<TD ALIGN="LEFT">Specifies the name of the ParaDiS control parameter file
</TD>
</TR>
<TR valign="top">
<TD ALIGN="LEFT">     </TD>
<TD ALIGN="LEFT">-d <dataFile></TD>
<TD ALIGN="LEFT">     </TD>
<TD ALIGN="LEFT">Specifies the base name of the file(s) containing the nodal data for the run. If this file name is not supplied, the code looks for a data file named the same as the control file with the file name suffix (if any) replaced with ".data"
</TD>
</TR>
<TR valign="top">
<TD ALIGN="LEFT">     </TD>
<TD ALIGN="LEFT">-r   <numCycles></TD>
<TD ALIGN="LEFT">     </TD>
<TD ALIGN="LEFT">Causes the code to execute a series of <numCycles> cycles during which no force calculations or dislocation movement will occur. These cycles will be used strictly for load-balancing purposes and will be done before the normal cycles. This can be useful when a simulation is started with a uniform domain decomposition and needs time to converge on an optimal decomposition as would occur when restarting a simulation on a different number of cpus
</TD>
</TR>
</TABLE>

=== Examples ===

For example, the following are all valid execution lines with the
first two being equivalent, the third version using the same control
file as the first two, but explicitly selecting a different nodal
data file.

For example, assuming you had a the control parameter file
'testrun.ctrl' and the two different nodal data files 'testrun.data'
and 'testrun2.data', all of the following command lines formats
are valid. The first two commands are equivalent, the third
uses the same control parameter file as the first two, but
explicitly selects a different nodal data file.

mpirun -np 8 bin/paradis testrun.ctrl
mpirun -np 8 bin/paradis -d testrun.data testrun.ctrl
mpirun -np 8 bin/paradis -d testrun2.data testrun.ctrl

NOTE: The number of processors specified to mpirun (or other
parallel job initiator applicable to the execting system)
must match the number of domains specified in the control
file (i.e. np = numXdoms * numYdoms * numZdoms).

Several small example problems are included with the
ParaDiS release. The control and data files for these
examples are:

<ParadisDir>/tests/frank_read_src.ctrl
<ParadisDir>/tests/frank_read_src.data

<ParadisDir>/tests/form_binaryjunc.ctrl
<ParadisDir>/tests/form_binaryjunc.data

<ParadisDir>/tests/fmm_8cpu.ctrl
<ParadisDir>/tests/fmm_8cpu.data

NOTE: These tests require the following tables used
for calculating the far-field stresses from distant
cells and periodic images of the problem.

<ParadisDir>/inputs/Rijm.cube.out
<ParadisDir>/inputs/RijmPBC.cube.out
<ParadisDir>/inputs/fm-ctab.Ta.600K.0GPa.m2.t5.dat

These file *may* have been provided with the source
code release. If not, see the README file in the
<ParadisDir>/tests directory for instructions on
generating these files.

The 'form_binaryjunc*' files contain a small configuration that
will demonstrate the formation of a binary junction from two
dislocation lines, while the 'frank_read_src*' files contain a
configuration that demonstrates the behaviour of a frank-read
source. Both these examples are single cpu examples. To run
these tests, from the main <ParadisDir> directory execute:

mpirun -np 1 ./bin/paradis ./tests/form_binaryjunc.ctrl
or
mpirun -np 1 ./bin/paradis ./tests/frank_read_src.ctrl

The 'fmm_8cpu*' files are just a general demonstration of the
behavior of a small number of screw dislocations. This is
an 8 processor simulation using the Fast Multipole Method
(FMM) for calculating stress from far-field interactions.

mpirun -np 8 ./bin/paradis ./tests/fmm_8cpu.ctrl

Any output from these runs will be placed into corresponding
subdirectories under the "tests" directory.
---------------------------------------------------------------------

== Inputs ==

=== Input Files ===

A ParaDiS simulation may be started from scratch, or
terminated and then later restarted if the user requested
periodic dumps of restart files. In either case, the initial
or restart data data consists of two files, a control
parameter file and a nodal data file. (See section on
[[#Output|Output]] for details on restart files)

=== Control Parameter File ===

The control parameter file consists of data of the form:

<TABLE>
<TR>
<TD ALIGN="LEFT">     </TD>
<TD ALIGN="LEFT"> </TD>
<TD ALIGN="LEFT">     </TD>
<TD ALIGN="LEFT">
identifier = value
</TD></TR>
<TR>
<TD ALIGN="LEFT">     </TD>
<TD ALIGN="LEFT"> </TD>
<TD ALIGN="LEFT">     </TD>
<TD ALIGN="LEFT">
identifier = [value_list]
</TD></TR>
<TR>
<TD ALIGN="LEFT">     </TD>
<TD ALIGN="LEFT">or</TD>
<TD ALIGN="LEFT">     </TD>
<TD ALIGN="LEFT">
identifier = string
</TD></TR>
</TABLE>

where

<TABLE CELLPADDING=3 >
<TR valign="top">
<TD ALIGN="LEFT">     </TD>
<TD ALIGN="LEFT">identifier</TD>
<TD ALIGN="LEFT">     </TD>
<TD ALIGN="LEFT">is the name of a control parameter
</TD></TR>
<TR valign="top">
<TD ALIGN="LEFT">     </TD>
<TD ALIGN="LEFT">value</TD>
<TD ALIGN="LEFT">     </TD>
<TD ALIGN="LEFT">is a numeric value associated with the parameter specified by <identifier>
</TD></TR>
<TR valign="top">
<TD ALIGN="LEFT">     </TD>
<TD ALIGN="LEFT">value_list</TD>
<TD ALIGN="LEFT">     </TD>
<TD ALIGN="LEFT">is a list of numeric values to be associated with the array specified by <identifier>. This values in this list must be delimited by white-space or line-feeds.
</TD></TR>
<TR valign="top">
<TD ALIGN="LEFT">     </TD>
<TD ALIGN="LEFT">string</TD>
<TD ALIGN="LEFT">     </TD>
<TD ALIGN="LEFT">a character string enclosed within either single or double quotes. The string may not contain a line-feed character.
</TD></TR>
</TABLE>

The identifier names are case-insensitive and may be specified
as any mixture of upper and lower case. If the code encounters
an identifier it does not recognize, the identifier and associated
value(s) will be ignore and a warning message displayed.

Any blank lines in the control parameter file will will be
ignored and additionally, any '#' not contained within quotes
is treated as the beginning of a comment and causes the remainder
of the current line to be ignored.

See the [[#Appendix 1. Control Parameters|Appendix]] for a complete list of the recognized control
parameters as well as a brief description of each.

=== Nodal Data File ===

==== Data File Format ====

The nodal data will be contained in 1 or more file
segments, with the information being broken into
three sections (described below). The first section
is the data file parameters, the second section the
domain decomposition, and the third section the nodal
data. The first two sections will be included only
in the first file segment.

==== Data File Segments ====

Given a control parameter file 'restart.cn', the
associated nodal data file(s) would be named:

restart.data[.SEQ]

where
<TABLE CELLPADDING=3 >
<TR valign="top">
<TD ALIGN="LEFT">     </TD>
<TD ALIGN="LEFT">SEQ</TD>
<TD ALIGN="LEFT">     </TD>
<TD ALIGN="LEFT">is a sequence number included only when the nodal data was written in parallel (i.e. the <numIOGroups> control parameter was greater than 1). <SEQ> will range from zero to <numIOGroups>-1.
</TD></TR>
</TABLE>

For example, suppose the <numIOGroups> control parameter
was set to 4 during a simulation executed on 16 processors.
If the simulation created a restart file set at termination,
the following files would be generated and could be used
as input to continue the simulation at a later time:

<outputDir>/restart/restart.cn
<outputDir>/restart/restart.data.0
<outputDir>/restart/restart.data.1
<outputDir>/restart/restart.data.2
<outputDir>/restart/restart.data.3

==== Data File Parameters ====

The data file parameters make up the first section of
the nodal data file and are parsed in the same manner
as specified above for the control file parameters.
These parameters must preceed the other two types of
information in the nodal data file. NOTE: The values
of these parameters are updated within the ParaDiS
code as necessary and should not be changed by the user.

The recognized data file parameters are:

: dataFileVersion
: numFileSegments
: minCoordinates
: maxCoordinates
: nodeCount
: dataDecompType
: dataDecompGeometry

==== Domain Decomposition ====

TBD

==== Nodal Data ====
The raw nodal data comprises the third section
of the nodal data file. For each node, there will
be a single line of node specific data followed by
several lines of segment specific data for each
segment associated with the node. The nodal data
consists of:

: node_tag x_coord y_coord z_coord num_arms constraint

The segment specific data consists of:

: nbr_tag burg_x burg_y, burg_z
: norm_x norm_y norm_z

where
<TABLE CELLPADDING=3 >
<TR valign="top">
<TD ALIGN="LEFT">     </TD>
<TD ALIGN="LEFT">*_tag</TD>
<TD ALIGN="LEFT">     </TD>
<TD ALIGN="LEFT">is a comma delimited pair of numbers uniquely identifying a node. The first number is the ID of the domain owning the node, the second is the index number of the node within the owning domain.
</TD></TR>
<TR valign="bottom">
<TD ALIGN="LEFT">     </TD>
<TD ALIGN="LEFT">x_coord, y_coord, z_coord</TD>
<TD ALIGN="LEFT">     </TD>
<TD ALIGN="LEFT">coordinates of the node
</TD></TR>
<TR valign="top">
<TD ALIGN="LEFT">     </TD>
<TD ALIGN="LEFT">num_arms</TD>
<TD ALIGN="LEFT">     </TD>
<TD ALIGN="LEFT">Number of segments associated with the node
</TD></TR>
<TR valign="top">
<TD ALIGN="LEFT">     </TD>
<TD ALIGN="LEFT">constraint</TD>
<TD ALIGN="LEFT">     </TD>
<TD ALIGN="LEFT">Integer value indicating any constraints placed on the node (i.e. a constraint of 7 implies a node fixed in place and unmovable)
</TD></TR>
</TABLE>

---------------------------------------------------------------------

== Cell and Domain Structure ==

The ParaDiS code is used to simulate cubic systems which
are simultaneously partitioned into a uniform mesh of
cubic 'cells' and spatially decomposed into 'domains'.

The cellular structure is defined by the <nXcells>, <nYcells>
and <nZcells> control parameters, and is used to determine
the cut-off distance between direct segment to segment
dislocation interactions and remote (or far-field) interactions.
In particular, for a given dislocation segment, the interaction
between the segment and any other segments in the same cell
or any of the immediately neighboring 26 cells are calculated
directly. Interactions with all segments outside that range
are calculated via a hierarchical Fast Multipole Method or
by lumping all segments in the remote cell into a
'super-dislocation' where the group of remote dislocations
are represented as an expansion of dislocation multipoles.
(See [[#Far-Field Dislocation Interactions|section on Far-Field Forces]] for details)

The type of spatial decomposition used for the simulation is
selected by the <decompType> control parameter, along with
the <nXdoms>, <nYdoms> and <nZdoms> parameters defining
the number of spatial domains in each dimension. Each 'domain'
is assigned to a single task (processor) within the simulation.
(See [[#Domain Decomposition 2|section on Domain Decomposition]] for details on the
supported types of spatial decomposition)

---------------------------------------------------------------------

== Domain Decomposition ==

=== Selecting a Domain Decomposition Method ===

ParaDiS simulations are spatially decomposed into a number of
domains equal to the number of processors on which the simulation
is being executed. The code curently supports two types of
domain decomposition and is selected via the <decompType>
control parameter. The type 1 decomposition is a Recursive
Sectioning decomposition which is the default if no decomposition
type is explicitly requested. The type 2 is a Recursive
Bisection decomposition. (See descriptions of decomposition
algorithms below.)

Since the ParaDiS simulations tend to grow in size and are
spatially heterogeneous, it is preferable to dynamically
recalculate the domain decomposition at intervals during the
simulation in order to rebalance the workload more efficiently.
The frequency with which the domain decomposition will be
recomputed is specified by the <DLBfreq> control parameter.

The domain decomposition will be included in the restart files.
If the simulation is restarted and the <decompType> control
parameter selects a decomposition type *other* than the
decomposition that was used to generate the restart file, the
old domain decomposition from the restart file will be ignored
and a new domain decomposition of the selected type will be used.

Additionally, if a simulation is restarted with a different number
of domains or a different domain geometry that that which was used
to create the restart file, the domain decomposition from the
restart file will be ignored and a new decomposition will be
generated.

Note: When restarting a large simulation (i.e. thousands
of processors) in such a way that the old domain decomposition must
be discarded, it may take some time for the simulation to converge
on an optimal domain decomposition. (The type 1 decomposition is
particularly susceptible to this.) There are two ways to mitigate
this effect. The first is to use the 'paradisrepart' utility, the
second through the use of the "-r" command line option to ParaDiS.
See comments in other sections pertaining to these capabilities.

=== Recursive Sectioning ===

The Recursive Sectioning algorithm performs a domain
decomposition over a 3-timestep period. During the
first timestep, the entire problem space will be
sectioned along the X dimension into <nXdoms> slabs
such that the computational cost of each slab is roughly
equivalent. The next timestep, each slab will be
sectioned alng the Y axis into <nYdoms> columns
such that the computational cost of each column in a
slab is roughly equivalent. On the thrid timestep,
every column will be sectioned along the Z axis
into <nZdoms> chunks such that the computational
cost of each chunk in a column is roughy equivalent.

As stated above, the frequency with which the domain boundaries
will be recalulated is controlled by the <DLBfreq> parameter.
If this parameter is not explicity set, the default frequency
for recalculating this type of domain decomposition is every
third timestep.

NOTE: Due to the fact that this algorithm requires 3
timesteps to complete a new decomposition, the
<DLBfreq> value must be no less than 3.

=== Recursive Bisection ===

WARNING: The implementation of this algorithm requires the
number of domains in each dimension (as specified
by the <nXdoms>, <nYdoms>, and <nZdoms> control
parameters) must be a power of 2.

The Recursive Bisectioning algorithm begins with the entire
cubic problem space and bisects the space in the X, Y and/or
Z dimensions into octants quarters or halves (depending on
the number of domains specified per dimension) such that
computational cost of each subpartition is roughly the same.
The decomposition is then recursively applied to each of the
subpartitions until no further decomposition is necesssary.

As stated above, the frequency with which the domain boundaries
will be recalulated is controlled by the <DLBfreq> parameter.
If this parameter is not explicity set, the default frequency
for recalculating this type of domain decomposition is every
timestep.

---------------------------------------------------------------------

== Dislocation Mobility ==

=== Selecting a Mobility Module ===

One of the crucial aspects of a ParaDiS simulation is the
selection of the set of rules governing the material specific
physics such as glide climb, and cross-slip with respect to
crystallographic constraints. ParaDiS provides multiple sets
of rules or "mobility laws", each implemented in a separate
module, that may be selected via the <mobilityLaw> control
file parameter. The currently support modules are:

: "BCC_0"
: "BCC_0b"

There are additional modules for dealing with FCC type materials
however these are neither fully developed nor supported at this
point. These FCC mobility functions are:

: "FCC_0"
: "FCC_2"

For a list of the control parameters related to the mobility
of dislocations, see the [[#Material and mobility parameters:|"Material and Mobility Parameters" section]] of the Appendix detailing the control file parameters.
Currently the default values of all mobility related parameters
correspond to tantalum at a temperature of 600 K and a
pressure of 0GPa.

=== BCC_0 Mobility: ===

In BCC metals, screw dislocations do not dissociate into partial
dislocations the same way they do in FCC metals, therefore, for
BCC crystals we do not assign glide plane normals to screw
dislocations. Instead, screw dislocations are given the same
mobility in all directions perpendicular to the line. This
isotropic mobility for screws mimics the "pencil-glide" behavior
of dislocations observed in BCC metals at elevated temperatures.
At the same time, the drag coefficient for non-screw segments
will remain anisotropic with respect to glide and climb.

For details on this mobility module, refer to the paper:

:<ParadisDir>/Docs/ParaDiSAlgorithm.pdf

=== BCC_0b Mobility: ===

The BCC_0b mobility module is nearly a duplicate of BCC_0 with
the exception that the movement of discretization nodes along
the dislocation lines has been dampened.

=== TBD ===

=== FCC_0 Mobility: ===

This module attempts to simulate easy glide in FCC systems. The
glide plane is limited to one of the [111] planes, and cross-slip
is not permitted. Also, no crystallographic information is
used in the dislocation core reactions and hence junction formation
can take place even slightly off the zone axis.

Reminder: This mobility module is not fully developed or supported.

=== FCC_2 Mobility: ===

TBD

---------------------------------------------------------------------

== Material Properties ==

=== Specifying Material Properties ===

All material specific properties are set via the control
file parameters. If not specified, defaults will correspond
to tantalum at a temperatue of 300 K and pressure of 0GPa.

See the [[#Material and mobility parameters:|"Material and mobility parameters" section]] of
Appendix 1 for a list of the material related parameters.

---------------------------------------------------------------------

== Far-Field Dislocation Interactions ==

=== Fast Multipole for Far-Field Interactions ===

The FMM algorithm is enabled within the code via the <fmEnabled>
toggle in the control file. The order of the multipole and
Taylor expansions used by the FMM algorithm are set via the
<fmMPOrder> and <fmTaylorOrder> control parameters respectively.
As a general rule, the taylor expansion order should be around
twice that of the multipole expansion order. One additional
control parameter [[#FMM controls|<fmCorrectionTbl>]] specifies the name of the
file containing the table used by the FMM code to adjust the
stress calculated by the FMM for multiple periodic images.

It is important to note that the file indicated by <fmCorrectionTbl>
must be built with the same multipole order, Taylor expansion order,
and Poisson value (<pois> control parameter) specified for a
simulation. An appropriate correction table may be generated
via the 'ctablegen' utility (See the section on Utilities for
details on the use of 'ctablegen'), although a correction table
matching the code's default control parameter settings *may* have
been provided in the code release as:

: <ParadisDir>/inputs/fm-ctab.Ta.600k.0GPa.m2.t5.dat

The use of a Fast Multipole Method (FMM) for calculating the
far-field forces is based on formulae for generating and evaluating
multipole expansions and a few translation theorems. A very
general description can be found below, but for details refer
to the following paper included with the source release.

:<ParadisDir>/docs/ParaDiSAlgorithm.pdf

The general FMM algorithm consists of the following steps:

# Construct multipole moments:
#: Each domain (CPU) calculates the contributions of its dislocation segments to the multipole moments of the FMM subcells to which those segments belong, and communicates those contributions to the domain that owns the FMM subcell. Each domain that owns an FMM subcell sums all the contributions for that subcell together. <bf>
# Upward pass:
#: Starting at the lowest layer of the FMM hierarchy, each domain collects and sums the contributions to the multipole moments for each of the FMM subcells it owns from the eight child cells and the calculates the upward pass translation of its multipole moments and communicates the result to the domain owing the subcell's parent, until the top of the hierarchy is reached.
# Transverse translations:
#: The multipole moments from 189 cells that are outside the nearest neighbor distance of the target cell but inside the nearest neaighbor distance of its parent are collected by the domain owning the target cell and their contributions to the Taylor series expansion of the stress filed in target is calculated.
# PBC correction:
#: The domain that owns the FMM cell at the highest level of the FMM hierarchy calculates the Taylor series expansion of the stress state due to periodic images of the system (using [[#FMM controls|table]] specified in the <fmCorrectionTbl> parameter).
# Downward pass:
#: Starting with the highest level of the FMM hierarchy, each domain that owns an FMM subcell sums the contributions from its parent to its Taylor series expansion of the stress from step 3 and then calculates the downward pass translation of the stress for each one of its child cells and sends the results to the domain owning the child subcells until the bottom of the hierarchy is reached.
# Each domain that owns a subcell at the lowest level of the FMM hierarchy communicates the Taylor series expansions of the stress field to the domains intersecting the subcell.

=== Non-FMM Far-Field Interactions ===

The use of the FMM in ParaDiS can be disable by setting the control
parameter <fmEnabled> to 0. When FMM is disabled, ParaDiS requires
additional tables used to factor in the far-field stresses from
distant cells and periodic images of the system. The names of the
files containing the tables are specified via the <Rijmfile> and
<RijmPBCfile> control parameters. These tables can be generated
using the 'stresstablegen' utility (see [[#Creating Far-Field Stress Tables with 'stresstablegen'|Utilities section]] for
details), although copies *may* have been provided in the code
release as:

: <ParadisDir>/inputs/Rijm.cube.out
: <ParadisDir>/inputs/RijmPBC.cube.out

This method essentially lumps all dislocations in a cell into a
'super-dislocation' where the cell's dislocations are represented
as an expansion of the dislocation multipoles. The remote stress
for a segment in a given cell is then calculated from two
components. The first is the sum of the stresses resulting from
expansions from all remote cells (i.e. neither the current cell
nor any of its 26 immediate neighbors) and the stress from all
periodic images of those remote cells. The second component
consists of the stress from only the periodic images of the local
cells (i.e. the current cell and its immediate neighbors).

This method is can be faster for smaller simulations but unlike
the FMM, its performance does not scale well as the size of
a simulation increases in both dislocation density and number
of cells.

---------------------------------------------------------------------

== Discretization (Remesh) ==

=== Selecting a Discretization Method ===

The nature of DD simulations is such that the total length
of dislocation lines can increase several orders of magnitude.
Hence, rediscretization of the dislocations is an absolutely necessary
components of ParaDiS simulations. The goal of the rediscretization
is to optimize the numerical description of the continuous dsilocation
line geometry so that a given level of accuracy is achieved with the
fewest degrees of freedom. For regions of high curvature, an optimal
distribution of nodes will place nodes more closely together than
in regions of lower curvature.

The level of accuracy is tied to the control parameters <maxSeg>
and <minSeg> which define the maximum and minimum segment lengths (in
units of b) respectively. The smaller the maximum segment length, the
higher the accuracy.

A number of rediscretization version have been developed and
tested, although only versions 2 and 3 are currently supported.
The rediscretization version to use can be selected through
the control parameter <remeshRule>.

=== Remesh Version 2 ===

This method achieves rediscrtization through two types of
operations; mesh coarsening and mesh refinement (removing and
adding discretization nodes respectively).

This involved defining both minimum and maximum discretization areas
(A_min and A_max) based on the simulation minimum and maximum
segment lengths <minSeg> and <maxSeg>. Then for each discretization
node (i.e. a node with no more than two associated segments) a
discretization area (A_node) is calculated. This area is defined
as the triangle with vertices at the node and its two neighbors.
When the discretization area associated with a node A_node < A_min
the node is removed (coarsened out). Conversely, if the area
A_node > A_max, the local discretization is refined by bisecting
both segments attached to the node.

For additional information, refer to the following paper included
with the ParaDiS source release:

: <ParadisDir>/docs/ParaDiSAlgorithm.pdf

=== Remesh Version 3 ===

This rediscretization method is identical to type 2 with
the exception that during mesh refinement the inserted
nodes are not placed at the exact center of the segment
being bisected. Instead, the algorithm treats the three
initial nodes as if they were on an arc and places the
new nodes at the center of the segments of the arc.

The rationale behind this is that in simulations using
long segments and/or high stress, a new node added at the
center of a segment in a region of high curvature will
not be optimally placed. This new node may immediately
accelerate quickly toward its optimal position then
decelerate as it nears that position. This behavior
can severly impact the simulatuion timesteps. By placing
the new nodes on an arc, the initial stress on the new
nodes will not be as high, keeping the motion of the node
similar to that of the surrounding nodes. Hence, no
detrimental effects on the timestep.

---------------------------------------------------------------------

== Simulation Timestepping ==

=== Timestep Controls ===

Two timestepping algorithms are provided in the ParaDiS code.
The <timestepIntegrator> control parameter is used to select
the desired algorithm. The currently supported algorithms
are:

: "trapezoid"
: "forward-euler"

The default timestep integrator is the "trapezoid" integrator.
There are several general control parameters used in conjunction
with any selected timestep intergrator, and several that are unique
to specific integrators. The general control parameters are
<deltaTT> which specifies the duration of the previous timestep,
<nextDT> which indicates the desired timestep to attempt the next
timestep, and <maxDT> which specifies the maximum timestep duration
permitted.

=== Timestep Integrators ===

==== Trapezoid ====

This implicit integrator is a mix of the Euler-Forward and
Euler-Backward methods. This method is unconditionally
stable, but requires an iterative process that may involve
multiple nodal force and velocity calculations. The
additional expense of the multiple calculations, however,
is usually offset by the gains from the larger timesteps
compared to explicit methods such as the forward euler
integrator.

The algorithm uses the current nodal velocities to reposition
each node, then recalculates forces and velocities for the
nodes at their new positions. A positioning 'error' is
calculated for each node based on the current and previous
nodal position and velocity. If the positioning error of
any node is greater than the maximum permitted positioning
error as defined by the <rTol> control parameter, the
timestep will be decremented by a factor specified in the
<dtDecrementFact> control parameter and the process starts
again. On the otehr hand, if the positioning error of all
nodes is within the tolerance, the timestep is accepted
and the current timestep is multipled by the factor in the
<dtIncrementFactor> to be used as the initial timestep to
attempt the next cycle.

==== Forward Euler ====

The forward euler timestep integrator is relatively simple
and inexpensive in that it requires only a single calculation
of nodal force and velocities per timestep. Unfortunately,
the algorithm is subject to the Courant condition for
numerical stability and is limited to relatively small
timesteps. The size of the timestep is controlled by the
ratio between the length of the shortest segment and the
velocity of the fastest moving node. Additionally, the
<rmax> control parameter defines the maximum distance
any node is permitted to move in a single timestep, which
further limits the timestep duration. This 'rmax' distance
should be set such that no dislocation segment crosses
multiple simulation cells in a single timestep.

Note: This timestep integrator is NOT recommended.

---------------------------------------------------------------------

== Visualization ==

=== X-window display ===

ParaDiS provides a simple X-window display capability for
visualization and debugging of small scale simulations as well
as obtaining certain types of nodal data via the display window.

Unlike some of the other visualization capabilities, this one
must be enabled/disabled via the compile time flag "XLIB_MODE"
in the file <ParadisDir>/makefile.setup. The X-window support
is enabled by setting:

: XLIB_MODE = ON

and disabled by:

: XLIB_MODE = OFF

The default behavior is to have the X-window support enabled.

The <winDefaultsFile> control parameter can be used to specify default
visualization options and attributes such as view perspective, colors
and so on. Unless otherwise specified, this control parameter will
point to the following defaults file provided with the source release:

: <ParadisDir>/inputs/paradis.xdefaults

Once the X-window display is initiated, the view can be controlled
through the following single-key commands:

Key Command Description
--- -------------------
<Home> Restores image to default view
<Esc> Terminates X-window display without terminating
the simulation
a Enable/disable aspect ratio changes. When enabled,
the Arrow keys alter the aspect ratio
c Enable/disable slice view of image. When enabled,
Up/Down Arrows control slice position, Left/Right
Arrows control slice thickness.
f Turn display frame on/off
p Pause/restart simulation
r Enable image rotation. When enabled, rotation can
be controlled via the mouse or Arrow keys.
s Enable display scaling. When enabled, the Arrow
keys control scaling size.
t Enable image translation. When enable,
the Arrow keys control translation direction.
<F10> Generate a postscript image of the display window.
File will be called <outputDir>/YshotNNNN where
'NNNN' is a sequence number incremented each time
a dump of the display window is generated and
<outputDir> is the directory specified by the
<dirname> control file parameter.

Additionally, clicking the mouse on a nodal point in the X-window
image will cause the following information to be written to the
terminal device (not the X-window display):

* relative position (x,y) on the X-window display
* node ID (domainID,nodeindex)
* number of segments (arms) associated with the node
* simulation coordinates (x,y,z) of the node

=== Gnuplot ===

ParaDiS is capable of producing output files formatted for use
with the gnuplot visualization package. This capability is
enabled via the <gnuplot> toggle in the control parameter file.
The frequency with which gnuplot files will be generated is
controlled by the settings of the <gnuplotfreq> and <gnuplotdt>
parameters.

When this capability is enabled, the code will periodically
create a set of gnuplot output files in the directory
<outputDir>/gnuplot where <outputDir> is the directory
specified by the <dirname> control file parameter. The
naming convention used for these files is:

: <outputDir>/gnuplot/box.in
: <outputDir>/gnuplot/0tNNNN[.SEQ]

where
<TABLE CELLPADDING=3 >
<TR valign="top">
<TD ALIGN="LEFT">     </TD>
<TD ALIGN="LEFT">NNNN</TD>
<TD ALIGN="LEFT">     </TD>
<TD ALIGN="LEFT">is a sequence number begining at '0001' and incremented each time a gnuplot file set is written.
</TD></TR>
<TR valign="top">
<TD ALIGN="LEFT">     </TD>
<TD ALIGN="LEFT">SEQ</TD>
<TD ALIGN="LEFT">     </TD>
<TD ALIGN="LEFT">is a sequence number included only when gnuplot files are being written in parallel (i.e. the <numIOGroups> control parameter is greater than 1) <SEQ> will range from zero to <numIOGroups>-1.
</TD></TR>
</TABLE>

In addition, at program termination, an extra set of gnuplot
files will be created. This set will be generated regardless
of the specified dump frequency in order to provide an image
of the final configuration. This set will be named with the
slightly different naming convention:

: <outputDir>/gnuplot/gnuplot.final[.SEQ]

The 'box.in' data file will contain data for plotting the boundaries
of the simulation space, while the '0t*' files contain the coordinate
pairs defining each unique dislocation segment.

NOTE: When gnuplot data is being written in parallel
(i.e. <numIOGroups> is larger than 1), the dislocation segment
data is spread over the file segments. These file segments
can be combined into a single file for display in gnuplot
via the <ParadisDir>/tools/stitch tool. (See description of
[[#stitch|'stitch']] tool for details.)

To aid in visualizing the dislocation configuration, a file
containing commands to set some useful gnuplot options has
been provided; This file is located at:

: <ParadisDir>/inputs/gnuplot.cmds

For example, to view the dislocation structure contained in the
gnuplot data file 0t0001 you could start gnuplot interactively
and execute the commands:

gnuplot> load '<ParadisDir>/inputs/gnuplot.defaults'
gnuplot> splot 'box.in' with lines, '0t0001' w lines

A second gnuplot command file has been provided as an example
of displaying a sequence of gnuplot files. This file is
located at:

: <ParadisDir>/inputs/gnuplot.movie

This file has the neccesary commands to plot the sequence
of files beginning with 0t0001 and ending with 0t1000. After
starting gnuplot, simply load this file with:

gnuplot> load '<ParadisDir>/inputs/gnuplot.movie'

This will initiate the plot of the first file, and thereafter,
simply hitting return will cause gnuplot to move to the next
file in the sequence.

For details on using gnuplot, refer to the gnuplot manual or
enter 'help' from the gnuplot interactive prompt.

=== Tecplot ===

ParaDiS is capable of producing output files formatted for use
with the commercial visualization package Tecplot. This
capability is enabled via the <tecplot> toggle in the control
parameter file. The frequency with which tecplot files will
be generated is controlled by the settings of the <tecplotfreq>
and <tecplotdt> parameters.

When this capability is enabled, the code will periodically
create a set of tecplot output files in the directory
<outputDir>/tecplot where <outputDir> is the directory
specified by the <dirname> control file parameter. The
naming convention used for these files is:

: <outputDir>/tecplot/tecdataNNNN[.SEQ]

where
<TABLE CELLPADDING=3 >
<TR valign="top">
<TD ALIGN="LEFT">     </TD>
<TD ALIGN="LEFT">NNNN</TD>
<TD ALIGN="LEFT">     </TD>
<TD ALIGN="LEFT">is a sequence number begining at '0001' and incremented each time a tecplot file set is written.
</TD></TR>
<TR valign="top">
<TD ALIGN="LEFT">     </TD>
<TD ALIGN="LEFT">SEQ</TD>
<TD ALIGN="LEFT">     </TD>
<TD ALIGN="LEFT">is a sequence number included only when tecplot files are being written in parallel (i.e. the <numIOGroups> control parameter is greater than 1) <SEQ> will range from zero to <numIOGroups>-1.
</TD></TR>
</TABLE>

In addition, at program termination, an extra set of tecplot
files will be created. This set will be generated regardless
of the specified dump frequency in order to provide an image
of the final configuration. This set will be named with the
slightly different naming convention:

: <outputDir>/tecplot/tecdata.final[.SEQ]

The generated tecplot output has specific headers to assign the
variables and time frames (zones) and should look something like
this:

...
variables = X,Y,Z,V1,V2,V3,V4,V5,V6,V7,V8
zone i = 54 F=POINT
-4000.0 500.0 6000.0 133.1 612.4 -612.3 0.0000 0.0000 0.0000 1 3
-3866.9 1112.4 5387.7 -133.1 -612.4 612.3 0.0000 0.0000 0.0000 1 3
471.0 -5132.6 11632.3 -1712.7 -48.8 48.9 0.0090 -0.0918 0.0918 2 3
...

The first line defines the variables to reconstruct the dislocation
configuration. X Y and Z specify the nodal coordinates, V1 V2 and
V3 define arm vectors to the neighboring nodes. These 6 variable
are used to represent dislocation segments as combinations of points
and vectors in tecplot. The V4 V5 and V6 represent the nodal velocity
vector, V7 indicates the number of segments associated with the node
and V8 indicates a burgers vector type.

NOTE: When tecplot data is being written in parallel
(i.e. <numIOGroups> is larger than 1), the headers will only be
included in the first file segment with the remainder of the data
spread over the file segments. These file segments can be combined
into a single file for display in tecplot via the
<ParadisDir>/tools/stitch tool. (See description of [[#stitch|'stitch']]
tool for details.)

For details on using tecplot, refer to the tecplot manual or select
the 'Help' menu in tecplot.

=== Povray ===

If the <povray> toggle is set in the control file,
ParaDiS will periodically generate files containing
dislocation segment data formatted for use with the POVRAY
(Persistence of Vision(tm) Ray Tracer) tool. The frequency
with which these files will be generated is controlled by
the settings of the <povrayfreq> and <povraydt> parameters.

Note: These files contain the main data to be processed by
povray, but must be post-processed via the
'genPovrayFrames' tool (See [[#genPovrayFrames|section]] on Tools)
which will create the final povray input file
containing the segment data embedded within a
proper framework of povray settings and commands.

When this capability is enabled, the code will periodically
create a set of files in the directory <outputDir>/povray
where <outputDir> is the directory specified by the <dirname>
control file parameter. The naming convention used for
these files is:

: <outputDir>/povray/povframeNNNN[.SEQ]

where
<TABLE CELLPADDING=3 >
<TR valign="top">
<TD ALIGN="LEFT">     </TD>
<TD ALIGN="LEFT">NNNN</TD>
<TD ALIGN="LEFT">     </TD>
<TD ALIGN="LEFT">is a sequence number begining at '0001' and incremented each time a povray frame file set is written.
</TD></TR>
<TR valign="top">
<TD ALIGN="LEFT">     </TD>
<TD ALIGN="LEFT">SEQ </TD>
<TD ALIGN="LEFT">     </TD>
<TD ALIGN="LEFT">is a sequence number included only when povray files are being written in parallel (i.e. the <numIOGroups> control parameter is greater than 1) <SEQ> will range from zero to <numIOGroups>-1.
</TD></TR>
</TABLE>

In addition, at program termination, an extra set of povray
frame files will be created. This set will be generated
regardless of the specified dump frequency in order to provide
an image of the final configuration. This set will be named
with the slightly different naming convention:

: <outputDir>/povray/povray.final[.SEQ]

NOTE: When povray data is being written in parallel
(i.e. <numIOGroups> is larger than 1), the dislocation segment
data is spread over the file segments. If desired, these file
segments may be combined into a single file for post-processing
via the <ParadisDir>/tools/stitch tool. (See description
of [[#stitch|'stitch']] tool for details.)

As stated above, these files must be post-processed via the
'genPovrayFrames' tool (See [[#genPovrayFrames|section]] on Tools) which will
create the final povray input file containing the segment
data embedded within a proper framework of povray settings
and commands. This tool is capable of dealing with single
or segmented 'povframe*' files.

For details on using povray, refer to the povray manual.

=== Terascale Browser ===

TBD

=== Postscript ===

If the <psfile> toggle is set in the control file,
ParaDiS will periodically generate a postscript file
containing an image of the current state of the system.
The frequency with which the postscript files are
written is determined by the settings of the
<psfilefreq> and <psfiledt> control file parameters.
All files will be located in the directory <outputDir>
where <outputDir> is the directory specified by the
<dirname> control file parameter.

All files will be named with the following convention:

: <outputDir>/YshotNNNN.ps

where NNNN is a sequence number beginning with zero and incremented
each time another postscript file is written.

---------------------------------------------------------------------

== Output ==

=== Restart files ===

Periodic creation of ParaDiS restart files is enabled via
the <savecn> toggle in the control file. The frequency with
which restart files are written is determined by the settings
of the <savecnfreq> and <savecndt> control file parameters.

When enabled, the code will periodically generate restart
file which will be located in the directory <outputDir>/restart
where <outputDir> is the directory specified by the <dirname>
control file parameter.

The naming convention used for these restart files is:

<TABLE CELLPADDING=3 >
<TR valign="top">
<TD ALIGN="LEFT">     </TD>
<TD ALIGN="LEFT"><outputDir>/restart/rsNNNN</TD>
<TD ALIGN="LEFT">     </TD>
<TD ALIGN="LEFT"># control parameter file
</TD></TR>
<TR valign="top">
<TD ALIGN="LEFT">     </TD>
<TD ALIGN="LEFT"><outputDir>/restart/rsNNNN.data[.SEQ]</TD>
<TD ALIGN="LEFT">     </TD>
<TD ALIGN="LEFT"># nodal data file
</TD></TR>
</TABLE>
where
<TABLE CELLPADDING=3 >
<TR valign="top">
<TD ALIGN="LEFT">     </TD>
<TD ALIGN="LEFT">NNNN</TD>
<TD ALIGN="LEFT">     </TD>
<TD ALIGN="LEFT">is a sequence number begining at '0001' and incremented each time a restart file set is written.
</TD></TR>
<TR valign="top">
<TD ALIGN="LEFT">     </TD>
<TD ALIGN="LEFT">SEQ</TD>
<TD ALIGN="LEFT">     </TD>
<TD ALIGN="LEFT">is a sequence number included only when restart files are being written in parallel (i.e. the <numIOGroups> control parameter is greater than 1) <SEQ> will range from zero to <numIOGroups>-1.
</TD></TR>
</TABLE>

Each time a restart file set is written, the name of the
control parameter file will also be written into the file:

: <outputDir>/latest_restart

Additionally, when creation of restart files is enabled, an
additional restart file pair named 'restart.cn' and restart.data'
will be written at program termination even if the cycle is not
a multiple of the <savecnfreq> control parameter.

=== Property Outputs ===

==== Enabling Properties Output ====

The code has the capability to produce files containing
various dislocation properties. This capability is enabled
via the <saveprop> toggle in the control file. The
frequency with which the property data is written is
determined by the settings of the <savepropfreq> and
<savepropdt> control file parameters.

When this capability is enabled, the code will generate
and periodically append the properties data to one or more of
the following files which will be located in the directory
<outputDir>/properties, where <outputDir> is the directory
specified by the <dirname> control file parameter.

==== Property Files ====

===== density =====

Note: burgVolFactor converts from length in units of B, to density
in units of meters

This file contains the following columns of data:

# plastic strain
# strain
# dislocation density
# deleted dislocation density
#: (lost through annihilation, junction formation, etc)
#: (density lost since last dump of data)
# average dislocation velocity‡
# std. deviation of dislocation velocities‡
# density file version number
# dislocation density for segments of specific groupings of burgers vectors (see below)*

‡ These items will be calculated only if
the "VEL_STATISTICS" pre-processor macro was
defined during compilation. Otherwise these
values will be zeroes.

For BCC simulations:
Column Burgers vector types
8 [ 1 1 1] [-1-1-1]
9 [-1 1 1] [ 1-1-1]
10 [ 1-1 1] [-1 1-1]
11 [ 1 1-1] [-1-1 1]
12 [ 1 0 0] [-1 0 0] [ 0 1 0]
[ 0-1 0] [ 0 0 1] [ 0 0-1]

For FCC simulations:
Column Burgers vector types
8 [ 1 1 0] [-1-1 0]
9 [-1 1 0] [ 1-1 0]
10 [ 1 0 1] [-1 0-1]
11 [-1 0 1] [ 1 0-1]
12 [ 0 1 1] [ 0-1-1]
13 [ 0-1 1] [ 0 1-1]
14 all others

===== time_Plastic_strain =====

This file contains the following two columns of data:

# elapsed simulation time
# plastic strain

===== stress_Plastic_strain =====

This file will only be generated if the user specified
a loadType of 1 (constant strain rate) or 4 (cyclic
loading). The file contains the following two columns
of data:

# plastic strain
# stress

===== stress_Total_strain =====

This file will only be generated if the user specified
a loadType of 1 (constant strain rate) or 4 (cyclic
loading). If the user specified a constant strain
rate, this file contains:

# strain
# stress

If the user specified cyclic loading, this file contains:

# net accumulated strain
# stress
# elapsed simulation time
# number of loading cycles

===== alleps =====

This file contains the following 9 columns of data:

{|
|-
| align=right | 1.||simulation timestep number
|-
| align=right | 2.||elapsed simulation time
|-
| align=right | 3-8.||plastic strain components‡
|-
| align=right | 9.||dislocation density
|}

‡ from plastic strain tensor matrix, elements [0][0], [1][1], [2][2], [1][2], [0][1], and [0][2]

===== epsdot =====

This file contains the 2 columns of data:

# elapsed simulation time
# plastic strain rate

=== Flux Decomposition ===

ParaDiS has the capability to produce files containing
flux decomposition information for the simulation.
This capability is enabled via the <fluxfile> control
file toggle. The frequency with which the flux
data is written is determined by the settings of
the <fluxfreq> and <fluxdt> control file parameters.

When this capability is enabled the code will generate
and periodically append the flux data to two sets of
files that will be located in the directory
<outputDir>/fluxdata where <outputDir> is the directory
specified by the <dirname> control file parameter.

Each set contains four files, one file per burgers vector.
Files *b1, *b2, *b3, and *b4 contain statistics for burgers
vector types [111], [-111], [1-11], and [11-1] respectively.

The first set of files (Ltot_b1, Ltot_b2, Ltot_b3 and
Ltot_b4) consist of the following 9 columns of data:

# Plastic strain
# Strain,
# Screw density
# Edgedensity1
# Edgedensity2
# Edgedensity3
# Sum of edge Densities (4+5+6)
# Total system EdgeDensity from all Ltot files
# Total system screw density from all Ltot files

The second set of files (fluxtot_b1, fluxtot_b2, fluxtot_b3 and
fluxtot_b4) consist of the following 9 columns of data:

{|
|-
| align=right | 1.||Plastic Strain
|-
| align=right | 2.||Strain
|-
| align=right | 3.||Flux due to climb motion
|-
| align=right | 4-6.||Flux created by edge components on three planes (See below.)
|-
| align=right | 7-9.||Flux created by screw dislocation on three planes (See below.)
|}

For b1 = 1/2[1 1 1]
<ol start="4">
<li> ( 0 1 -1), [-2 1 1]</li>
<li> (-1 0 1), [ 1 -2 1]</li>
<li> ( 1 -1 0), [ 1 1 -2]</li>
<li> ( 0 1 -1), [-2 1 1]</li>
<li> (-1 0 1), [ 1 -2 1]</li>
<li> ( 1 -1 0), [ 1 1 -2]</li>
</ol>
For b2 = 1/2[-1 1 1]
<ol start="4">
<li> ( 0 1 -1), [ 2 1 1] </li>
<li> ( 1 0 1), [ 1 2 -1] </li>
<li> ( 1 1 0), [ 1 -1 2] </li>
<li> ( 0 1 -1), [ 2 1 1] </li>
<li> ( 1 0 1), [ 1 2 -1] </li>
<li> ( 1 1 0), [ 1 -1 2] </li>
</ol>
For b3 = 1/2[1 -1 1]
<ol start="4">
<li> ( 0 1 1), [ 2 1 -1] </li>
<li> ( 1 0 -1), [ 1 2 1] </li>
<li> ( 1 1 0), [-1 1 2] </li>
<li> ( 0 1 1), [ 2 1 -1] </li>
<li> ( 1 0 -1), [ 1 2 1] </li>
<li> ( 1 1 0), [-1 1 2] </li>
</ol>
For b4 = 1/2[1 1 -1]
<ol start="4">
<li> ( 0 1 1), [ 2 -1 1] </li>
<li> ( 1 0 1), [-1 2 1] </li>
<li> ( 1 -1 0), [ 1 1 2] </li>
<li> ( 0 1 1), [ 2 -1 1] </li>
<li> ( 1 0 1), [-1 2 1] </li>
<li> ( 1 -1 0), [ 1 1 2] </li>
</ol>

=== Pole figures ===

TBD

=== Velocity files ===

If the <velfile> toggle is set in the control file,
ParaDiS will periodically generate a set of files containing
velocity information about each unique dislocation node
in the system. The frequency with which the velocity
data is written is determined by the settings of the
<velfilefreq> and <velfiledt> control file parameters.
All files will be located in the directory <outputDir>/velocity
where <outputDir> is the directory specified by the
<dirname> control file parameter.

All files will be named with the following convention:

: <outputDir>/velocity/velNNNN[.SEQ]

where
<TABLE CELLPADDING=3 >
<TR valign="top">
<TD ALIGN="LEFT">     </TD>
<TD ALIGN="LEFT">NNNN</TD>
<TD ALIGN="LEFT">     </TD>
<TD ALIGN="LEFT">is a sequence number based on the <velfilecounter> control parameter and is incremented each time another velocity file is written.
</TD></TR>
<TR valign="top">
<TD ALIGN="LEFT">     </TD>
<TD ALIGN="LEFT">SEQ </TD>
<TD ALIGN="LEFT">     </TD>
<TD ALIGN="LEFT">is a sequence number included only when velocity data is being written in parallel (i.e. <numIOGroups> control parameter is greater than 1. SEQ will range from zero to <numIOGroups>-1.
</TD></TR>
</TABLE>

In addition, at program termination, an extra set of velocity
files will be created. This set will be generated regardless
of the specified dump frequency in order to provide an image
of the final configuration. This set will be named with the
slightly different naming convention:

: <outputDir>/velocity/vel.final[.SEQ]

NOTE: When velocity data is being written in parallel
the dislocation segment data is spread over the file segments.
These file segments can be combined into a single file via
the <ParadisDir>/tools/stitch tool. (See [[#stitch|section]] on Tools
for details)

The contents of the velocity files consist of 4 columns
of data for each unique dislocation segment. Those
columns are:

{|
|-
| align=right | 1-3.||Velocity components (x,y,z)
|-valign="top"
| align=right | 4.|| +1 if contributing to strain rate <br> -1 if moving in opposite direction
|}

=== Segment files ===

If the <armfile> toggle is set in the control file,
ParaDiS will periodically generate a set of files containing
information about each unique dislocation segment
in the system. The frequency with which the segment
(or arm) files are written is determined by the settings
of the <armfilefreq> and <armfiledt> control file parameters.
All files will be located in the directory <outputDir>/armdata
where <outputDir> is the directory specified by the
<dirname> control file parameter.

All files will be named with the following convention:

: <outputDir>/armdata/armNNNN[.SEQ]

where
<TABLE CELLPADDING=3 >
<TR valign="top">
<TD ALIGN="LEFT">     </TD>
<TD ALIGN="LEFT">NNNN</TD>
<TD ALIGN="LEFT">     </TD>
<TD ALIGN="LEFT">is a sequence number based on the <armfilecounter> control parameter and is incremented each time another arm file is written.
</TD></TR>
<TR valign="top">
<TD ALIGN="LEFT">     </TD>
<TD ALIGN="LEFT">SEQ</TD>
<TD ALIGN="LEFT">     </TD>
<TD ALIGN="LEFT">is a sequence number included only when arm data is being written in parallel (i.e. <numIOGroups> control parameter is greater than 1. SEQ will range from zero to <numIOGroups>-1.
</TD></TR>
</TABLE>

In addition, at program termination, an extra set of arm
files will be created. This set will be generated regardless
of the specified dump frequency in order to provide an image
of the final configuration. This set will be named with the
slightly different naming convention:

: <outputDir>/armdata/arm.final[.SEQ]

NOTE: When arm data is being written in parallel
the dislocation segment data is spread over the file segments.
These file segments can be combined into a single file via
the <ParadisDir>/tools/stitch tool. (See [[#stitch|section]] on Tools
for details)

The contents of the arm files consist of 10 columns
of data for each unique dislocation segment. Those
columns are:

{|
|-
| align=right | 1-3.||Burgers vector components
|-
| align=right | 4-6.||Line direction vector
|-
| align=right | 7.||Segment length
|-
| align=right | 8-10.||Coordinates of node 'owning' the segment
|}

=== Density Field file ===

If all components of the <savedensityspec> control parameter
are set to positive values in the control file, ParaDiS
will (at program termination) create a file containing a
3D dislocation density field formatted for use with the
VASP Data Viewer (vaspview). The three components of
the <savedensityspec> parameter specify the granularity
of the density field in the X, Y and Z dimensions
respectively. The density field will be written to the
file:

: <outputDir>/densityfield.out

Warning: This will overwrite any existing density field
file of the same name!

The VASP Data Viewer is publicly available on the web
for non-commercial use. For details on the product,
download the VASP Data Viewer from the web and refer
to the accompanying documentation.

---------------------------------------------------------------------

== Utilities ==

=== Creating Initial Dislocations with 'paradisgen' ===

The paradisgen utility is capable of generating initial
dislocations suitable for a paradis simulation. The command
line options for paradisgen control the type of dislocations,
number of dislocations, size of the simulation box, and so
on. See "Examples" below for sample executions of this utility.

The command line format for paradisgen is:

paradisgen [-cubel <cubelength>] [-help] [-hexsize <size>] \
[-maxseg <maxseglen] [-nchains <numchains>] \
[-nloops <numloops>] [-outfile <filename> \
[-radius <radius>] [-seed <seedval>] \
[-type <configtype>]

All command line options may be abbreviated to the shortest
non-ambiguous abbreviation of the option. Descriptions of
the command lines options are as follows:

<pre>
-cubel <cubelength> Defines the size of the simulation cube
in units of b. Minimum and maximum problem
space coordinates will be 0.5*cubel and
-0.5*cubel respectively. If not specified
this will default to 35000b (approx.
10 micron).

-help Causes the utility to display the command line
format and option descriptions then terminate.

-hexsize <size> Defines the radius (in units of b) for the
hexagonal interstitial loops. This option is
used only when the selected dislocation type
is 'fcc-irrad'.

-looptype <ltype> Specifies the types of prismatic loops to
generate. If not specified, this value
will default to zero. Valid values are:

0 == mixture of [1 1 1] and [1 0 0] types
1 == all [1 1 1] type loops
2 == all [1 0 0] type loops

This option is only used when the selected
dislocation type is 'prismatic-loop'.

-maxseg <length> Defines the maximum desired segment length
in units of b. Initial dislocations will
be discretized so no segment is longer than
this value. If not specified this value
defaults to 500.

-nchains <numchain> Indicates the number of dislocation lines
to create. This value is ignored when the
selected dislocation type is 'prismatic-loop',
and when the type is 'fcc-perfect-loop',
this value must be a multiple of 12. If
not specified, this value defaults to 2.

-nloops <numloops> Specifies the number of loops to create when
the selected dislocation type is
'prismatic-loop' or 'fcc-irrad'. If not
specified, this value defaults to 1000.

-nsegs <numsegs> Specifies the number of segments into which
a prismatic loop will be discretized. This
option is only used when the selected
dislocation type is 'prismatic-loop'. If
not specified, this value defaults to
(2*PI*radius)/(maxseg/2).

-outfile <filename> Name of the ParaDiS data file to be created.
If not specified, data will be written
into a file called 'paradis.data'.

-radius <radius> Radius (in units of b) of prismatic loops.
This option is only used when the selected
dislocation type is 'prismatic-loop'. If
not specified, this value defaults to maxseg/2.

-seed <seed> Specifies a value to seed the random number
generator. Using the same seed value for
multiple executions of paradis (for which
all other options are identical) insures
creation of an identical configuration.

-type <type> Specifies the type of dislocations to create.
This type can be a name or the integer value
corresponding to the name. Valid types are:

0 or 'screw' BCC screw dislocations.
Assumes periodic boundary
conditions are enabled.
1 or 'finite-mixed' A mixture of BCC screw and
edge dislocations
terminating at the edges
of the cubic problem
space. This should not
be used with periodic
boundary conditions.
2 or 'prismatic-loop' BCC prismatic loops.
Assumes periodic boundary
conditions are enabled.
3 or 'fcc' FCC dislocations. Assumes
periodic boundary
conditions are enabled.
4 or 'fcc-irrad' Mixture of FCC
dislocations and hexagonal
interstitial loops.
Assumes periodic boundary
conditions are enabled.
5 or 'fcc-perfect-loop' Not fully implemented.

Examples:
---------

TBD
</pre>

=== Recomputing Domain Boundaries with 'paradisrepart' ===

The paradisrepart utility provides a mechanism by which to
replace the domain decomposition/partitioning in an
existing nodal data file with a new domain decomposition.
The utility will read the current nodal data, and use the
specified domain/cell geometries to attempt to partition
the domains such that the computational cost for each domain
will be roughly equivalent.

This utility is primarily used when it is necessary alter
the domain geometry or domain count for a simulation in
order to continue. In such a situation, the existing
domain decomposition would be thrown away and the ParaDiS
code would generate an initial uniform decomposition
and then over time converge on a more optimal decomposition.
Using this utility instead to generate a new decomposition
provides a much more reasonable starting point from allowing
the ParaDiS simulation to converge on an optimal decomposition
much more quickly.

The command line format for the paradisrepart utility is:

paradisrepart -infile <inputFile> \
-cells <xcells[,ycells,zcells]> \
-domains <xdoms[,ydoms,zdoms]> \
[-outfile <outputFile>] [-decompType <type>] \
[-help]

All command line arguments and options may be abbreviated to the
shortest non-ambiguous abbreviation of the option. Descriptions
of the command lines options are as follows:

<pre>
-infile <inputFile> Specifies the name of the nodal data file.
On success, the first nodal data file
segment will be copied to <inputFile>.bkup.
This command line argument is not optional.

-cells <xcells[,ycells,zcells]> Specifies the number of
cells in each dimension. If the
number of cells in the Y and Z dimensions
are not provided, they will default to the
same value as <xcells>. This command line
argument is not optional.

-domains <xdoms[,ydoms,zdoms]> Specifies the number of domains
in each dimension. If the number of
domains in the Y and Z dimensions are
not provided, they will default to the
same value as <xdoms>. This command line
argument is not optional.

-decompType <type> Specifies type of domain decomposition:
If not specified, defaults to 1. Valid
types are:

1 == Recursive Sectioning
2 == Recursive Bisectioning

-help Causes the utility to display the command
line format and option descriptions then
terminate.

-outfile <outputFile> Specifies the name of the file into which
to write the new domain decomposition. If
not specified, new domain decomposition
will be written into the file specified
by <inputFile>.

Examples:
---------
</pre>

=== Converting Control and Data File with 'paradisconvert' ===

The paradisconvert utility provides a mechanism by which
older format ParaDiS control and data files (and restart
files) may be converted to the current file formats.
This utility does recognize and handle segmented data files.

In most cases this utility will not be required since
ParaDiS is still able to recognize and handle *most* of
the older file formats. The only format the ParaDiS code
no longer recognizes is the truly ancient format associated
with the earliest incarnations of the code in which the
control file parameters and nodal data were included in
a single file. For these control files, the paradisconvert
utility will be needed.

The command line format for the paradisconvert utility is:

paradisconvert <controlFile> [dataFile]

where:
<TABLE CELLPADDING=3 >
<TR valign="top">
<TD ALIGN="LEFT">     </TD>
<TD ALIGN="LEFT">controlFile</TD>
<TD ALIGN="LEFT">     </TD>
<TD ALIGN="LEFT">Specifies the name of the control parameter file to be updated to the current format.
</TD></TR>
<TR valign="top">
<TD ALIGN="LEFT">     </TD>
<TD ALIGN="LEFT">dataFile</TD>
<TD ALIGN="LEFT">     </TD>
<TD ALIGN="LEFT">If the specified control file is the original ancient format including control parameters and nodal data in the single file, this argument is ignored. Otherwise, this specifies the base name of the nodal data file(s) to be converted. If not this argument is not provided, it will default to the same name as <controlFile> with any file name suffix removed and the '.data' suffix added.
</TD></TR>
</TABLE>

On success, the utility will rename the original files by appending
a '.bkup' suffix to the names, and create new control and data files
with the specified names. Note: for control parameter files which
include nodal data, a new data file will be generated under the
the name as <controlFile> with any file name suffix removed and
a '.data' suffix added.

<u>Examples:</u>

To convert the original format file 'restart.cn' containing
both control parameters and nodal data, execute:

paradisconvert restart.cn

The utility will generate the following files:

: restart.cn.bkup
: restart.cn
: restart.data

To convert a newer control parameter and data file pair with
the names 'rs0100' and 'rs0100.data' respective, execute either
of the following equivalent command lines:

paradisconvert rs0100
paradisconvert rs0100 rs0100.data

In both cases, the utility would generate the files:

: rs0100.bkup
: rs0100.data.bkup

: rs0100
: rs0100.data

To convert a newer control file <rs0100> and a set of segmented
data files with the names <rs0100.data.0>, <rs0100.data.1>, ...
<rs0100.data.7>, execute any of the following equivalent commands:

paradisconvert rs0100
paradisconvert rs0100 rs0100.data
paradisconvert rs0100 rs0100.data.0

In all of the above cases, the utility would generate the files

: rs0100.bkup
: rs0100.data.0.bkup
: rs0100.data.1.bkup
: ...
: rs0100.data.7.bkup

: rs0100
: rs0100.data.0
: rs0100.data.1
: ...
: rs0100.data.7

=== Creating the FMM Image Correction Table with 'ctablegen' ===

The 'ctablegen' utility is used to create an image correction
table needed when the FMM (Fast Multipole Method) has been enabled
by setting the <fmEnabled> toggle on in the control file. Since
the data in this file is dependent on the poisson ratio, shear
modulus, and orders of the multipole and taylor expansions, the
file must be created for the particular values of these items
used in the simulation.

Given the current defaults used by ParaDiS (as set in Param.c):

{|
|      ||align="left"| poisson ratio: ||align="center"| 3.327533e-01
|-
| ||align="left"| shear modulus: ||align="center"| 6.488424e+10
|-
| ||align="left"| multipole order: ||align="center"| 2
|-
| ||align="left"| taylor expansion order: ||align="center"| 5
|}

To create the FMM image correction table, you could execute
ctablegen from the main <ParadisDir> directory using the
following command line:

bin/ctablegen -nu 3.327533e-01 -mu 6.488424e+10 -mporder 2 -torder 5 -outfile \
inputs/fm-ctab.Ta.600K.0GPa.m2.t5.dat

NOTE: The generation of this table can take a significant
amount of time, therefore, a parallel version of the utility
(called ctablegenp) has also been provided. To execute the
table generation in parallel on 8 processors using mpirun as
a parallel program initiator, one could execute:

mpirun -np 8 bin/ctablegen -nu 3.327533e-01 -mu 6.488424e+10 -mporder 2 -torder 5 -outfile \
inputs/fm-ctab.Ta.600K.0GPa.m2.t5.dat

The locations of this file is specified in the control
parameter file via the <fmCorrectionTbl> parameter.

=== Creating Far-Field Stress Tables with 'stresstablegen' ===

The 'stresstablegen' utility is used to create tables needed
for calculating stress from distant cells and periodic images
of the system when FMM is disabled (i.e. <fmEnabled> is set
to zero). There are two required tables, one which factors
in stress from periodic images only and the other which factors
in stress from both the primary and period images.

To create the needed stress tables, execute the stesstablegen
utility twice from the main <ParadisDir> directory using the
following command lines:

bin/stresstablegen -nopbc -outfile inputs/Rijm.cube.out
and
bin/stresstablegen -pbc -outfile inputs/RijmPBC.cube.out

The locations of these files are specified in the control
parameter file via the <Rijmfile> and <RijmPBCfile> parameters
respectively.

---------------------------------------------------------------------

== Tools ==

=== genPovrayFrames ===

The genPovrayFrames tool is provided to post-process the
povray data files generated by ParaDiS when the <povray>
control parameter toggle has been set. This tool will
create an '*.pov' file containing the ParaDiS generated
data embedded in a proper framework of povray settings
and commands. The tool is located in the <ParadisDir>/tools
directory. For details on the use of this tool, see
the comments at the beginning of the script or execute:

<ParadisDir/tools/genPovrayFrames -help

=== gnuplot2povray ===

The gnuplot2povray tool is provided to post-process the
gnuplot data files generated by ParaDiS when the <gnuplot>
control parameter toggle has been set. This tool will
convert the data in the gnuplot files into a format
suitable for povray, and create an '*.pov' file containing
the converted data embedded in a proper framework of povray
settings and commands. The tool is located in the
<ParadisDir>/tools directory. For details on the use of
this tool, see the comments at the beginning of the script
or execute:

<ParadisDir/tools/gnuplot2povray -help

=== stitch ===

When ParaDiS is configured to enable parallel I/O
(i.e. the <numIOGroups> control parameter is greater
than 1), each of the following types of output
will be generated as a set of files rather than a
single output file.

: gnuplot files
: tecplot files
: segment/arm data
: povray files
: velocity data
: terascale browser files
: pole figures

Each file 'segment' will contain a portion of the full
data and will have a sequence number appended to the file
name.

Most utilities for processing these types of output, however,
expect the data in a single file, so the 'stitch' tool
has been provided in order to recombine these data file
segments into a single usable file as a post-processing
step. The tool can be found in the source release as:

: <ParadisDir>/tools/stitch

The command line for 'stitch is as follows:

stitch [-h] [-d dir | -f file]

where
<pre>
-h prints the usage information to stdout

-d <dir> specifies a directory the utility will
scan for any segmented output files that
need to be stitched together.

-f <file> specifies a base file name and the utility will
scan for the corresponding file segments (files
named <file>.N where N ranges from zero on up)
and stitch the segments into the single specified
base file name.
</pre>

NOTE: If neither a directory nor file name was provided
on the command line, the tool will behave as though
the caller specified the current directory on the command
line and perform as stated above.

== Appendix 1. Control Parameters ==

The following is a brief description of the valid control
file parameters. Also see the example control files contained
within the <ParadisDir>/tests directory.

The parameters have been grouped into the following categories, and
unless otherwise specified, units are in SI, and lengths are
normalized by burgers vector magnitude:

* Simulation cell and processor setup
* Simulation time and timestepping controls
* Discretization controls
* FMM controls
* Tables for non-FMM far-field forces
* Loading condition parameters
* Material and mobility parameters
* Velocity statistics and controls
* I/O controls and parameters
* Miscellaneous parameters

=== Simulation cell and processor setup: ===

{|class="wikitable" border="1" align="center"
|+ Table A1. Control parameters for simulation setup
! Parameter
! Type
! Description
|-
|align="center"| numXdoms, numYdoms, numZdoms ||align="center"| integer ||align="left"|
Defines the number of computational domains into which the problem space is partitioned in the corresponding dimensions.
|-
|align="center"| numXcells, numYcells, numZcells ||align="center"| integer ||align="left"|
Defines the number of cells in the corresponding dimension of the problem space. Cells are independent of the domain geometry and are used to determine boundaries at which far-field forces are computed rather than direct segment to segment forces.
|-
|align="center"| xBoundType, yBoundType, zBoundType ||align="center"| integer ||align="left"|
Defines the type of problem space boundaries in the corresponding dimension. Currently supported types are 0, and 1 for periodic and free surfaces respectively.
|-
|align="center"| xBoundMax, yBoundMax, zBoundMax ||align="center"| double ||align="left"|
If periodic boundaries are not enabled, defines the upper limit on coordinates of any dislocation nodes in the corresponding dimension. Value must be <= the respective maximum problem space coordinate specified in the nodal data file.
|-
|align="center"| xBoundMin, yBoundMin, zBoundMin ||align="center"| double ||align="left"|
If periodic boundaries are not enabled, defines the lower limit on coordinates of any dislocation nodes in the corresponding dimension. Value must be >= the respective minimum problem space coordinate specified in the nodal data file.
|-
|align="center"| decompType ||align="center"| Integer ||align="left"|
Specifies the type of domain decomposition to be used for a run. A value of one selects the old Recursive Sectioning (RS) algorithm, a value of 2 selects the Recursive Bisectioning (RB) decomposition algorithm. The default is currently the RS decomposition.
|-
|align="center"| DLBfreq ||align="center"| Integer ||align="left"|
Indicates the frequency (in cycles) at which Dynamic Load-Balancing is to be attempted. A value of zero indicates no load-balancing is to be done. Default is 3.
|}

=== Simulation time and timestepping controls ===

{|class="wikitable" border="1" align="center"
|+ Table A2. Time Control parameters
! Parameter
! Type
! Description
|-
|align="center"| cycleStart ||align="center"| integer ||align="left"|
Starting cycle number for the simulation.
|-
|align="center"| maxstep ||align="center"| integer ||align="left"|
Indicates the number of timesteps to execute before terminating.
|-
|align="center"| timeNow ||align="center"| double ||align="left"|
Current simulation time (in seconds).
|-
|align="center"| timeStart ||align="center"| double ||align="left"|
Initial simulation time (in seconds).
|-
|align="center"| timestepIntegrator ||align="center"| string ||align="left"|
Selects a timestep integration method. Valid methods are "trapezoid" and "forward-euler". The default value is "trapezoid".
|-
|align="center"| deltaTT ||align="center"| double ||align="left"|
Specifies the duration of the previous timestep in units of seconds.
|-
|align="center"| maxDT ||align="center"| double ||align="left"|
Specifies the maximum timestep permitted. Default is 1.0e-07.
|-
|align="center"| nextDT ||align="center"| double ||align="left"|
Specifies the timestep duration to attempt on the next cycle. The timestep integrator will adjust this value dynamically. Default is <maxDT>.
|-
|align="center"| dtDecrementFact ||align="center"| double ||align="left"|
Factor by which <delatTT> is mutiplied when cutting the timestep duration down. Must be between 0.0 and 1.0. Currently only used with the "trapezoid" integrator. Default is 0.5.
|-
|align="center"| dtExponent ||align="center"| double ||align="left"|
Exponent used in calculation of timestep increment when <dtVariableAdjustment> toggle is enabled. Currently used only with "trapezoid" timestep integrator.
|-
|align="center"| dtIncrementFact ||align="center"| double ||align="left"|
Maximum factor by which <deltaTT> is multiplied when incrementing the timestep. Must be at least 1.0. Default is 1.2.
|-
|align="center"| dtVariableAdjustment ||align="center"| integer ||align="left"|
Toggles ability to vary the increment by which the timestep is adjusted when the current timestep is determined to be too small. This will permit the timestep to be adjusted to a value between 1.0 and <dtIncrementFact> * <deltaTT>. Toggle is zero (off) by default. Used only with "trapezoid" integrator.
|-
|align="center"| rTol ||align="center"| double ||align="left"|
Maximum position error (in units of b) tolerated in the timestep integration. Only applies to the "trapezoid" integrator. Default is 0.25 * <rc>. The annihilation
distance is related to rTol(By default, it is set to 2* <rTol> = 0.5 * <rc>.)
|-
|align="center"| rmax ||align="center"| double ||align="left"|
Maximum distance (in units of b) a node is permitted to move in a single timestep. Not used if "trapezoid" timestep integrator used. Default is 0.5 * <minSeg>.
|}

=== Discretization controls: ===

{|class="wikitable" border="1" align="center"
|+ Table A3. Discretization control parameters
! Parameter
! Type
! Description
|-
|align="center"| maxSeg ||align="center"| double ||align="left"|
Sets the maximum permitted length (in units of b) of a dislocation segment. Primarily used for determining when segments are to be rediscretized during remesh operations. This value must be less than 9/10 the size of a cell. There is no default value, and must be specified in the control file.
|-
|align="center"| minSeg ||align="center"| double ||align="left"|
Sets the minimum desired length (in units of b) of a dislocation segment. Primarily used for determining when nodes are to be removed during remesh operations. Default is: sqrt(remeshAreaMin*(4/sqrt(3))) where remeshAreaMin = 2*rTol*maxSeg
|-
|align="center"| remeshRule ||align="center"| integer ||align="left"|
Specifies by number the set of rules governing rediscretization of dislocations. Currently the only supported remesh modules are versions 2 and 3. Default is 2. (See section on Rediscretization for details on remesh versions.)
|}

=== FMM controls ===

{|class="wikitable" border="0" align="center"
|+ Table A4. FMM control parameters
! Parameter
! Type
! Description
|-
|align="center"| fmEnabled ||align="center"| integer ||align="left"|
Toggle controlling use of a Fast Multipole Method (FMM) for computing force contributions from remote dislocation segments. A value of zero disables the use of FMM, any other value enables FMM. Default value is zero.
|-
|align="center"| fmCorrectionTbl ||align="center"| string ||align="left"|
Name of the image correction table used by the FMM. This correction table must correspond to the specified <fmMPOrder>, <fmTaylorOrder> and <shearModulus>(?) control parameters. See the [[#Creating the FMM Image Correction Table with 'ctablegen'|'ctablegen' utility]] for information on creating these tables. This value is ignored if <fmEnabled> is zero.
|-
|align="center"| fmMPOrder ||align="center"| integer ||align="left"|
Defines the multipole expansion order used by the FMM. This value is ignored if <fmEnabled> is zero. Default is 2.
|-
|align="center"| fmTaylorOrder ||align="center"| integer ||align="left"|
Defines the order of taylor expansions used by the FMM. This values is ignored if <fmEnabled> is zero. Default is 4.
|}

{|class="wikitable" border="0" align="center"
|+ Table A5. Table for non-FMM far-field forces
! Parameter
! Type
! Description
|-
|align="center"| Rijmfile ||align="center"| string ||align="left"|
Name of file containing the RIJM table to be used for far-field stress calculations. This parameter is ignored if the <fmEnabled> parameter is non-zero. Default is "inputs/Rijm.cube.out".
|-
|align="center"| RijmPBCfile ||align="center"| string ||align="left"|
Name of file containing the RIJM table to be used for far-field stress calculations with periodic boundary conditions. This parameter is ignored if the <fmEnabled> parameter is non-zero. Default is "inputs/RijmPBC.cube.out".
|}

=== Loading condition parameters: ===

{|class="wikitable" border="1" align="center"
|+ Table A6. Loading condition parameters
! Parameter
! Type
! Description
|-
|align="center"| loadType ||align="center"| integer ||align="left"|
Defines the type of load on the system. Valid types are:
<ol start="0">
<li> Creep test </li>
<li> Constant strain rate test </li>
<li> Displacement-controlled test </li>
<li> Load-controlled, load vs. time curve </li>
<li> Cyclic loading condition </li>
</ol>
|-
|align="center"| appliedStress ||align="center"| double[6] ||align="left"|
Defines the type of load on the system. Valid types are:
External stress specified in units of Pa as [sigma11, sigma22, sigma33, sigma23, sigma31, sigma12] when <loadType> == 0. Default is [0.0, 0.0, 0.0, 0.0, 0.0, 0.0].
|-
|align="center"| eRate ||align="center"| double ||align="left"|
Strain rate. Applicable only when <loadType> == 1. Default is 1.0/sec.
|-
|align="center"| indxErate ||align="center"| integer ||align="left"|
Index to indicate normal or shear deformation. Used only when <loadType> == 1. Valid values are:
# normal
# shear
If not specified, defaults to 1.
|-
|align="center"| edotdir ||align="center"| double[3] ||align="left"|
Uniaxial loading direction accompanying <eRate>. Default is [1.0 0.0 0.0].
|-
|align="center"| cTimeOld ||align="center"| integer ||align="left"|
Timestep related to cyclic loading. Only used when <loadType> == 4.
|-
|align="center"| dCyclicStrain ||align="center"| double ||align="left"|
Incremental strain under cyclic load. Only used when <loadType> == 4.
|-
|align="center"| netCyclicStrain ||align="center"| double ||align="left"|
Net accumulated strain under cyclic load. Only used when <loadType> == 4.
|-
|align="center"| numLoadCycle ||align="center"| integer ||align="left"|
Number of cyclic cycles. Only used when <loadType> == 4.
|-
|align="center"| eAmp ||align="center"| double ||align="left"|
Strain amplitude. Only used when <loadType> == 4.
|}

=== Material and mobility parameters: ===

Note: Default values for all material and mobility related
parameters correspond to Tantalum at a temperature of
600 degress K and pressure of 0 GPa.

{|class="wikitable" border="1" align="center"
|+ Table A7. Table for material and mobility parameters
! Parameter
! Type
! Description
|-
|align="center"| mobilityLaw ||align="center"| string ||align="left"|
Specifies by name the set of rules governing dislocation motion for the simulation conditions. Default is "BCC_0".
|-
|align="center"| shearModulus ||align="center"| double ||align="left"|
Shear modulus in units of Pa. Default is 6.488424e+10
|-
|align="center"| pois ||align="center"| double ||align="left"|
Poisson ratio. Default is 3.327533e-01
|-
|align="center"| burgMag ||align="center"| double ||align="left"|
Magnitude of the burgers vector (b) in units of meters. Default is 2.875401e-10
|-
|align="center"| YoungModulus ||align="center"| double ||align="left"|
Young's modulus (in units of Pa). calculated from E = 2G(1+pois). Default is 200.0e+09.
|-
|align="center"| rc ||align="center"| double ||align="left"|
Core radius (in units of b) for self-force calculations. No default value; must be specified in control file.
|-
|align="center"| Ecore ||align="center"| double ||align="left"|
Core energy used for self-force calculation. Default is (<shearModulus>/(4*PI)) * log(<rc>/0.1)
|-
|align="center"| MobScrew ||align="center"| double ||align="left"|
Mobility of screw dislocations in units of 1/(Pa*sec). Default is 10.0.
|-
|align="center"| MobEdge ||align="center"| double ||align="left"|
Mobility of edge dislocations in units of 1/(Pa*sec). Default is 10.0.
|-
|align="center"| MobClimb ||align="center"| double ||align="left"|
Climb mobility of dislocations in units of 1/(Pa*sec). Default is 1.0e-02.
|-
|align="center"| sessileburgspec ||align="center"| double[30] ||align="left"|
Array of burgers vectors to be considered sessile. First element of the array contains the number of burgers vectors specified, the remaining elements specify the X, Y, then Z components of each sessile burgers vector. Maximum sessile burgers vectors allowed is 9. No burgers vectors are sessile by default.
|-
|align="center"| sessilelinespec ||align="center"| double[30] ||align="left"|
Array of line directions related to sessileburgspec. First element is ignored, remaining elements specify the X, Y, then Z components of each sessile line. The number of lines is assumed to be the same as the number of sessile burgers vectors.
|}

=== Flux Decomposition: ===

{|class="wikitable" border="1" align="center"
|+ Table A8.
! Parameter
! Type
! Description
|-
|align="center"| totpSpn ||align="center"| double[6] ||align="left"|
Plastic strain tensor
|-
|align="center"| totpStn ||align="center"| double[6] ||align="left"|
Plastic spin tensor
|-
|align="center"| totstraintensor ||align="center"| double[6] ||align="left"|
Strain rate tensor with respect to global coordinate system.
|-
|align="center"| Ltot ||align="center"| double[4][4] ||align="left"|
Decomposed density per burgers vector for screw and three edges (for BCC slip systems only).
|-
|align="center"| fluxtot ||align="center"| double[4][7] ||align="left"|
For each burgers vector (for BCC slip systems only), contains:
<table border = "0" cellpadding = "0" cellspacing = "0">
<tr>
<td align="right"> 1. </td>
<td> flux due to climb </td>
</tr>
<tr>
<td align="right"> 2-4. </td>
<td> flux due to edge components </td>
</tr>
<tr>
<td align="right"> 5-7. </td>
<td> flux due to screw components </td>
</tr>
</table>
|}

=== Velocity statistics: ===

‡ Note: these statistics will only be used if the VEL_STATISTICS pre-processor macro has been defined during compilation.

{|class="wikitable" border="1" align="center"
|+ Table A9.
! Parameter
! Type
! Description
|-
|align="center"| vAverage ||align="center"| double ||align="left"|
Average dislocation velocity.
|-
|align="center"| vStDev ||align="center"| double ||align="left"|
Standard deviation of dislocation velocities.
|}

=== I/O controls and parameters ===

‡ Note: A number of the supported output forms are controlled by
very similar control parameters. The general descriptions below
apply to all I/O control parameters of like names:

<pre>
*freq Sets the frequency (in cycles) at which the associated data
will be written to disk. If the corresponding <*dt> parameter
is greater than 0, this parameter will be ignored.
Default for all such values is 100.

*dt The *dt variables specify the simulation delta time that will
control the frequency at which the associated output will be
written to disk. A positive value is interpreted as a delta
time and will take precedence over any frequency specified by
the corresponding <*freq> value. A value <= zero indicates
write frequency will not be determined by delta times.
Default value is -1.0.

*time Specifies the simulation time at which the associated data
was last written to disk. This value will be automatically
updated during the simulation. If the corresponding <*dt>
parameter is <= 0.0 this parameter will be ignored.

*counter Sequence number of the previously written file of the
corresponding type. Default is 0.
</pre>

{|class="wikitable" border="1" align="center"
|+ Table A10.
! Parameter
! Type
! Description
|-
|align="center"| dirname ||align="center"| string ||align="left"|
Base output directory name.
|-
|align="center"| skipIO ||align="center"| integer ||align="left"|
Toggle for disabling generation of all output types other than timing files. Overrides output-specific toggles if set. Default is 0.
|-
|align="center"| numIOGroups ||align="center"| integer ||align="left"|
Sets the number of groups into which the domains will be separated for doing parallel IO. All files generated in parallel will be created with this number of segments. This value must be at least one and no more than the total number of domains used. default is 1.
|-
|align="center"| armfile ||align="center"| integer ||align="left"|
Toggle enabling/disabling generation of files identifying each unique dislocation segment. Toggle is zero (off) by default.
|-
|align="center"| armfilecounter ||align="center"| integer ||align="left"|
See description of <*counter> above.
|-
|align="center"| armfiledt ||align="center"| double ||align="left"|
See description of <*dt> above.
|-
|align="center"| armfilefreq ||align="center"| integer ||align="left"|
See description of <*freq> above.
|-
|align="center"| armfiletime ||align="center"| double ||align="left"|
See description of <*time> above.
|-
|align="center"| fluxfile ||align="center"| integer ||align="left"|
Toggle enabling/disabling generation of flux decomposition files. Toggle is zero (off) by default.
|-
|align="center"| fluxcounter ||align="center"| integer ||align="left"|
See description of <*counter> above.
|-
|align="center"| fluxdt ||align="center"| double ||align="left"|
See description of <*dt> above.
|-
|align="center"| fluxfreq ||align="center"| integer ||align="left"|
See description of <*freq> above.
|-
|align="center"|fluxtime ||align="center"| double ||align="left"|
See description of <*time> above.
|-
|align="center"| gnuplot ||align="center"| integer ||align="left"|
Toggle enabling/disabling generation of files formatted for use with gnuplot. Toggle is zero (off) by default.
|-
|align="center"| gnuplotcounter ||align="center"| integer ||align="left"|
See description of <*counter> above.
|-
|align="center"| gnuplotdt ||align="center"| double ||align="left"|
See description of <*dt> above.
|-
|align="center"| gnuplotfreq ||align="center"| integer ||align="left"|
See description of <*freq> above.
|-
|align="center"| gnuplottime ||align="center"| double ||align="left"|
See description of <*time> above.
|-
|align="center"| polefigfile ||align="center"| integer ||align="left"|
Toggle enabling/disabling generation of <111> type burgers vector pole figures. Toggle is zero (off) by default.
|-
|align="center"| polefilecounter ||align="center"| integer ||align="left"|
See description of <*counter> above.
|-
|align="center"| polefigdt ||align="center"| double ||align="left"|
See description of <*dt> above.
|-
|align="center"| polefigfreq ||align="center"| integer ||align="left"|
See description of <*freq> above.
|-
|align="center"| polefigtime ||align="center"| double ||align="left"|
See description of <*time> above.
|-
|align="center"| povray ||align="center"| integer ||align="left"|
Toggle enabling/disabling generation of files with nodal data and domain boundaries for use with povray. Toggle is zero (off) by default.
|-
|align="center"| povraycounter ||align="center"| integer ||align="left"|
See description of <*counter> above.
|-
|align="center"| povraydt ||align="center"| double ||align="left"|
See description of <*dt> above.
|-
|align="center"| povrayfreq ||align="center"| integer ||align="left"|
See description of <*freq> above.
|-
|align="center"| povraytime ||align="center"| double ||align="left"|
See description of <*time> above.
|-
|align="center"| psfile ||align="center"| integer ||align="left"|
Toggle enabling/disabling generation of postscript files containing nodal data and domain boundaries. Toggle is zero (off) by default.
|-
|align="center"| psfiledt ||align="center"| double ||align="left"|
See description of <*dt> above.
|-
|align="center"| psfilefreq ||align="center"| integer ||align="left"|
See description of <*freq> above.
|-
|align="center"| psfiletime ||align="center"| double ||align="left"|
See description of <*time> above.
|-
|align="center"| savecn ||align="center"| integer ||align="left"|
Toggle enabling/disabling writing of restart files. Toggle is zero (off) by default.
|-
|align="center"| savecncounter ||align="center"| integer ||align="left"|
See description of <*counter> above.
|-
|align="center"| savecndt ||align="center"| double ||align="left"|
See description of <*dt> above.
|-
|align="center"| savecnfreq ||align="center"| integer ||align="left"|
See description of <*freq> above.
|-
|align="center"| savecntime ||align="center"| double ||align="left"|
See description of <*time> above.
|-
|align="center"| saveprop ||align="center"| integer ||align="left"|
Toggle enabling/disabling writing of various properties files. Toggle is zero (off) by default.
|-
|align="center"| savepropdt ||align="center"| double ||align="left"|
See description of <*dt> above.
|-
|align="center"| savepropfreq ||align="center"| integer ||align="left"|
See description of <*freq> above.
|-
|align="center"| saveproptime ||align="center"| double ||align="left"|
See description of <*time> above.
|-
|align="center"| savetimers ||align="center"| integer ||align="left"|
Toggle enabling/disabling generation of timing data files. Toggle is zero (off) by default.
|-
|align="center"| savetimerscounter ||align="center"| integer ||align="left"|
See description of <*counter> above.
|-
|align="center"| savetimersdt ||align="center"| double ||align="left"|
See description of <*dt> above.
|-
|align="center"| savetimersfreq ||align="center"| integer ||align="left"|
See description of <*freq> above.
|-
|align="center"| savetimerstime ||align="center"| double ||align="left"|
See description of <*time> above.
|-
|align="center"| savedensityspec ||align="center"| integer[3] ||align="left"|
Specifies the granularity of the 3D density field written to the density field file in X, Y and Z dimensions. If any element of this array is zero, this capability is disabled.
|-
|align="center"| tecplot ||align="center"| integer ||align="left"|
Toggle enabling/disabling generation of output files formatted for use with tecplot. Toggle is zero (off) by default.
|-
|align="center"| tecplotcounter ||align="center"| integer ||align="left"|
See description of <*counter> above.
|-
|align="center"| tecplotdt ||align="center"| double ||align="left"|
See description of <*dt> above.
|-
|align="center"| tecplotfreq ||align="center"| integer ||align="left"|
See description of <*freq> above.
|-
|align="center"| tecplottime ||align="center"| double ||align="left"|
See description of <*time> above.
|-
|align="center"| tsbfile ||align="center"| integer ||align="left"|
Toggle enabling/disabling generation of output files formatted for use with the TeraScale Browser. Toggle is zero (off) by default.
|-
|align="center"| writetsbspec ||align="center"| integer[3] ||align="left"|
TBD
|-
|align="center"| tsbfilecounter ||align="center"| integer ||align="left"|
See description of <*counter> above.
|-
|align="center"| tsbfiledt ||align="center"| double ||align="left"|
See description of <*dt> above.
|-
|align="center"| tsbfilefreq ||align="center"| integer ||align="left"|
See description of <*freq> above.
|-
|align="center"| tsbfiletime ||align="center"| double ||align="left"|
See description of <*time> above.
|-
|align="center"| velfile ||align="center"| integer ||align="left"|
Toggle enabling/disabling generation of output files containing velocity data for all nodes in the simulation. Toggle is zero (off) by default.
|-
|align="center"| velfilecounter ||align="center"| integer ||align="left"|
See description of <*counter> above.
|-
|align="center"| velfiledt ||align="center"| double ||align="left"|
See description of <*dt> above.
|-
|align="center"| velfilefreq ||align="center"| integer ||align="left"|
See description of <*freq> above.
|-
|align="center"| velfiletime ||align="center"| double ||align="left"|
See description of <*time> above.
|-
|align="center"| winDefaultsFile ||align="center"| string ||align="left"|
Name of file containing default options and attributes for the X-window display. This is ignore if the X display support was not enabled at compile time. Defaults to "./inputs/paradis.xdefaults".
|}

=== Miscellaneous parameters ===

{|class="wikitable" border="1" align="center"
|+ Table A11.
! Parameter
! Type
! Description
|-
|align="center"| elasticinteraction ||align="center"| integer ||align="left"|
Toggles between explicit calculation of elastic interaction and simple line tension calculations. Toggle is one (on) by default.
|-
|align="center"| TensionFactor ||align="center"| double ||align="left"|
Factor used for simple line tension force calculations when the <elasticinteraction> parameter is zero. Default is 1.0.
|}

=== Under development ===

{|class="wikitable" border="1" align="center"
|+ Table A12.
! Parameter
! Type
! Description
|-
|align="center"| TempK ||align="center"| double ||align="left"|
Simulation temperature (in Kelvin). For use in FCC cross-slip.
|-
|align="center"| enforceGlidePlanes ||align="center"| integer ||align="left"|
If non-zero, forces remesh, collision handling, etc. to use glide-plane constraints. Default is zero.
|-
|align="center"| springConst ||align="center"| double ||align="left"|
For use with FCC_0 mobility
|-
|align="center"| mob_compute_escaig ||align="center"| integer ||align="left"|
TBD
|-
|align="center"| mob_cross_slip ||align="center"| integer ||align="left"|
TBD
|}

Overview of ParaDiS 2.2

2011-12-05T04:51:42Z

Iryu: /* Simulation time and timestepping controls */

This document is taken from ParaDiSInfo.txt in ParaDiS.v2.2 distribution. Written by Gregg Hommes, LLNL.

== Introduction ==

The Parallel Dislocation Simulator (ParaDiS) was written
and developed at LLNL by a team of physicists and computer
scientists. ParaDiS is a code for doing Dislocation Dynamics
simulations and was specifically written to perform well on
massively parallel computers. The computational approach to
Dislocation Dynamics used in ParaDiS is fairly simple. In
it, one introduces dislocation lines into the computational
volume and lets them interact and move in response to the
forces imposed by external stress and inter-dislocation
interactions.

---------------------------------------------------------------------

== Building ParaDiS ==

=== Directory Structure ===

The ParaDiS release consists of a file which, when unzipped
and untarred creates a primary directory and a structure
of subdirectories. For convenience, this primary directory
will hereafter be referred to as <ParadisDir>. The directory
structure of the release will look like:

<TABLE CELLPADDING=3 >
<TR valign="top">
<TD ALIGN="LEFT">     </TD>
<TD ALIGN="LEFT"><ParadisDir>/</TD>
<TD ALIGN="LEFT">     </TD>
<TD ALIGN="LEFT">Contains primary 'make' files for controlling build of all executables</TD>
</TR>
<TR valign="top">
<TD ALIGN="LEFT">     </TD>
<TD ALIGN="LEFT"><ParadisDir>/bin/</TD>
<TD ALIGN="LEFT">     </TD>
<TD ALIGN="LEFT">This directory will be created during the 'make' process. All executables will be placed in this directory during compilation</TD>
</TR>
<TR valign="top">
<TD ALIGN="LEFT">     </TD>
<TD ALIGN="LEFT"><ParadisDir>/docs/</TD>
<TD ALIGN="LEFT">     </TD>
<TD ALIGN="LEFT">Contains any additional documentation</TD>
</TR>
<TR valign="top">
<TD ALIGN="LEFT">     </TD>
<TD ALIGN="LEFT"><ParadisDir>/include/</TD>
<TD ALIGN="LEFT">     </TD>
<TD ALIGN="LEFT">Contains all C and C++ header files</TD>
</TR>
<TR valign="top">
<TD ALIGN="LEFT">     </TD>
<TD ALIGN="LEFT"><ParadisDir>/inputs/</TD>
<TD ALIGN="LEFT">     </TD>
<TD ALIGN="LEFT">FMM and non-FMM correction tables, X-display defaults file, gnuplot command file, etc.</TD>
</TR>
<TR valign="top">
<TD ALIGN="LEFT">     </TD>
<TD ALIGN="LEFT"><ParadisDir>/materials/</TD>
<TD ALIGN="LEFT">     </TD>
<TD ALIGN="LEFT">Sample files containing material specific tables and constants</TD>
</TR>
<TR valign="top">
<TD ALIGN="LEFT">     </TD>
<TD ALIGN="LEFT"><ParadisDir>/src/</TD>
<TD ALIGN="LEFT">     </TD>
<TD ALIGN="LEFT">All C and C++ source code modules related to the paradis executable</TD>
</TR>
<TR valign="top">
<TD ALIGN="LEFT">     </TD>
<TD ALIGN="LEFT"><ParadisDir>/tools/</TD>
<TD ALIGN="LEFT">     </TD>
<TD ALIGN="LEFT">Miscellaneous support scripts</TD>
</TR>
<TR valign="top">
<TD ALIGN="LEFT">     </TD>
<TD ALIGN="LEFT"><ParadisDir>/utilities/</TD>
<TD ALIGN="LEFT">     </TD>
<TD ALIGN="LEFT">Source code modules pertaining to the various support tools</TD>
</TR>
</TABLE>

=== Compiling ===

The current ParaDiS 'make' files support compilation for
a number of pre-defined system types that are defined in
the file 'makefile.sys'. In order to compile the code on
one of these pre-defined system types, simply edit
'makefile.setup' and set the "SYS=..." value to the
desired system type. For other system types, add a new
system type into 'makefile.sys' following the format used
for the existing systems and, as above, set the "SYS=..."
value in 'makefile.setup'.

Executing 'gmake' with no options in <ParadisDir> will
build the following executables:

<TABLE CELLPADDING=3 >
<TR valign="top">
<TD ALIGN="LEFT">     </TD>
<TD ALIGN="LEFT"><ParadisDir>/bin/paradis</TD>
<TD ALIGN="LEFT">     </TD>
<TD ALIGN="LEFT">-- Main parallel application</TD>
</TR>
<TR valign="top">
<TD ALIGN="LEFT">     </TD>
<TD ALIGN="LEFT"><ParadisDir>/bin/paradisgen</TD>
<TD ALIGN="LEFT">     </TD>
<TD ALIGN="LEFT">-- Utility for creating initial dislocation configurations (See [[#Utilities|Utilities]] section for details)</TD>
</TR>
<TR valign="top">
<TD ALIGN="LEFT">     </TD>
<TD ALIGN="LEFT"><ParadisDir>/bin/paradisrepart</TD>
<TD ALIGN="LEFT">     </TD>
<TD ALIGN="LEFT">-- Utility for generating a new domain decomposition for an existing dislocation configuration (See [[#Utilities|Utilities]] section for details)</TD>
</TR>
<TR valign="top">
<TD ALIGN="LEFT">     </TD>
<TD ALIGN="LEFT"><ParadisDir>/bin/paradisconvert</TD>
<TD ALIGN="LEFT">     </TD>
<TD ALIGN="LEFT">-- Utility for converting older format ParaDiS control parameter files to the current format (See [[#Utilities|Utilities]] section for details)</TD>
</TR>
<TR valign="top">
<TD ALIGN="LEFT">     </TD>
<TD ALIGN="LEFT"><ParadisDir>/bin/ctablegen</TD>
<TD ALIGN="LEFT">     </TD>
<TD ALIGN="LEFT">-- Utility for creating image correction tables needed when FMM code is enabled. (See [[#Utilities|Utilities]] section for details)</TD>
</TR>
<TR valign="top">
<TD ALIGN="LEFT">     </TD>
<TD ALIGN="LEFT"><ParadisDir>/bin/ctablegenp</TD>
<TD ALIGN="LEFT">     </TD>
<TD ALIGN="LEFT">-- Parallel version of the ctablegen utility. See above.</TD>
</TR>
<TR valign="top">
<TD ALIGN="LEFT">     </TD>
<TD ALIGN="LEFT"><ParadisDir>/bin/stresstablegen</TD>
<TD ALIGN="LEFT">     </TD>
<TD ALIGN="LEFT">-- Utility for creating tables used in calculating far-field stress if the FMM code is not enabled. (See [[#Utilities|Utilities]] section for details)
</TD>
</TR>
</TABLE>

=== Make files ===

Compilation of the code is done via 'gmake' and depends
on the following 'make' files located in the <ParadisDir>
directory. (See the individual make files for details)

<TABLE CELLPADDING=3 >
<TR valign="top">
<TD ALIGN="LEFT">     </TD>
<TD ALIGN="LEFT">makefile</TD>
<TD ALIGN="LEFT">     </TD>
<TD ALIGN="LEFT">-- This is the primary make file controlling the build of the parallel executable and associated utilities.
</TD>
</TR>
<TR valign="top">
<TD ALIGN="LEFT">     </TD>
<TD ALIGN="LEFT">makefile.sys</TD>
<TD ALIGN="LEFT">     </TD>
<TD ALIGN="LEFT">-- This file contains, for each supported system type, a set of 'make' macros, definitions, compiler selection, library and include file paths, etc.
</TD>
</TR>
<TR valign="top">
<TD ALIGN="LEFT">     </TD>
<TD ALIGN="LEFT">makefile.setup</TD>
<TD ALIGN="LEFT">     </TD>
<TD ALIGN="LEFT">-- Contains numerous 'make' settings and flags that are not system specific, including settings for system type, optimization level, debugging flags, etc.
</TD>
</TR>
</TABLE>

---------------------------------------------------------------------

== Executing ParaDiS ==

=== Command line ===

The ParaDiS command line format is:

paradis [-r <numCycles>] [-d dataFile] <controlFile>

where:

<TABLE CELLPADDING=3 >
<TR valign="top">
<TD ALIGN="LEFT">     </TD>
<TD ALIGN="LEFT"><ctrlFile></TD>
<TD ALIGN="LEFT">     </TD>
<TD ALIGN="LEFT">Specifies the name of the ParaDiS control parameter file
</TD>
</TR>
<TR valign="top">
<TD ALIGN="LEFT">     </TD>
<TD ALIGN="LEFT">-d <dataFile></TD>
<TD ALIGN="LEFT">     </TD>
<TD ALIGN="LEFT">Specifies the base name of the file(s) containing the nodal data for the run. If this file name is not supplied, the code looks for a data file named the same as the control file with the file name suffix (if any) replaced with ".data"
</TD>
</TR>
<TR valign="top">
<TD ALIGN="LEFT">     </TD>
<TD ALIGN="LEFT">-r   <numCycles></TD>
<TD ALIGN="LEFT">     </TD>
<TD ALIGN="LEFT">Causes the code to execute a series of <numCycles> cycles during which no force calculations or dislocation movement will occur. These cycles will be used strictly for load-balancing purposes and will be done before the normal cycles. This can be useful when a simulation is started with a uniform domain decomposition and needs time to converge on an optimal decomposition as would occur when restarting a simulation on a different number of cpus
</TD>
</TR>
</TABLE>

=== Examples ===

For example, the following are all valid execution lines with the
first two being equivalent, the third version using the same control
file as the first two, but explicitly selecting a different nodal
data file.

For example, assuming you had a the control parameter file
'testrun.ctrl' and the two different nodal data files 'testrun.data'
and 'testrun2.data', all of the following command lines formats
are valid. The first two commands are equivalent, the third
uses the same control parameter file as the first two, but
explicitly selects a different nodal data file.

mpirun -np 8 bin/paradis testrun.ctrl
mpirun -np 8 bin/paradis -d testrun.data testrun.ctrl
mpirun -np 8 bin/paradis -d testrun2.data testrun.ctrl

NOTE: The number of processors specified to mpirun (or other
parallel job initiator applicable to the execting system)
must match the number of domains specified in the control
file (i.e. np = numXdoms * numYdoms * numZdoms).

Several small example problems are included with the
ParaDiS release. The control and data files for these
examples are:

<ParadisDir>/tests/frank_read_src.ctrl
<ParadisDir>/tests/frank_read_src.data

<ParadisDir>/tests/form_binaryjunc.ctrl
<ParadisDir>/tests/form_binaryjunc.data

<ParadisDir>/tests/fmm_8cpu.ctrl
<ParadisDir>/tests/fmm_8cpu.data

NOTE: These tests require the following tables used
for calculating the far-field stresses from distant
cells and periodic images of the problem.

<ParadisDir>/inputs/Rijm.cube.out
<ParadisDir>/inputs/RijmPBC.cube.out
<ParadisDir>/inputs/fm-ctab.Ta.600K.0GPa.m2.t5.dat

These file *may* have been provided with the source
code release. If not, see the README file in the
<ParadisDir>/tests directory for instructions on
generating these files.

The 'form_binaryjunc*' files contain a small configuration that
will demonstrate the formation of a binary junction from two
dislocation lines, while the 'frank_read_src*' files contain a
configuration that demonstrates the behaviour of a frank-read
source. Both these examples are single cpu examples. To run
these tests, from the main <ParadisDir> directory execute:

mpirun -np 1 ./bin/paradis ./tests/form_binaryjunc.ctrl
or
mpirun -np 1 ./bin/paradis ./tests/frank_read_src.ctrl

The 'fmm_8cpu*' files are just a general demonstration of the
behavior of a small number of screw dislocations. This is
an 8 processor simulation using the Fast Multipole Method
(FMM) for calculating stress from far-field interactions.

mpirun -np 8 ./bin/paradis ./tests/fmm_8cpu.ctrl

Any output from these runs will be placed into corresponding
subdirectories under the "tests" directory.
---------------------------------------------------------------------

== Inputs ==

=== Input Files ===

A ParaDiS simulation may be started from scratch, or
terminated and then later restarted if the user requested
periodic dumps of restart files. In either case, the initial
or restart data data consists of two files, a control
parameter file and a nodal data file. (See section on
[[#Output|Output]] for details on restart files)

=== Control Parameter File ===

The control parameter file consists of data of the form:

<TABLE>
<TR>
<TD ALIGN="LEFT">     </TD>
<TD ALIGN="LEFT"> </TD>
<TD ALIGN="LEFT">     </TD>
<TD ALIGN="LEFT">
identifier = value
</TD></TR>
<TR>
<TD ALIGN="LEFT">     </TD>
<TD ALIGN="LEFT"> </TD>
<TD ALIGN="LEFT">     </TD>
<TD ALIGN="LEFT">
identifier = [value_list]
</TD></TR>
<TR>
<TD ALIGN="LEFT">     </TD>
<TD ALIGN="LEFT">or</TD>
<TD ALIGN="LEFT">     </TD>
<TD ALIGN="LEFT">
identifier = string
</TD></TR>
</TABLE>

where

<TABLE CELLPADDING=3 >
<TR valign="top">
<TD ALIGN="LEFT">     </TD>
<TD ALIGN="LEFT">identifier</TD>
<TD ALIGN="LEFT">     </TD>
<TD ALIGN="LEFT">is the name of a control parameter
</TD></TR>
<TR valign="top">
<TD ALIGN="LEFT">     </TD>
<TD ALIGN="LEFT">value</TD>
<TD ALIGN="LEFT">     </TD>
<TD ALIGN="LEFT">is a numeric value associated with the parameter specified by <identifier>
</TD></TR>
<TR valign="top">
<TD ALIGN="LEFT">     </TD>
<TD ALIGN="LEFT">value_list</TD>
<TD ALIGN="LEFT">     </TD>
<TD ALIGN="LEFT">is a list of numeric values to be associated with the array specified by <identifier>. This values in this list must be delimited by white-space or line-feeds.
</TD></TR>
<TR valign="top">
<TD ALIGN="LEFT">     </TD>
<TD ALIGN="LEFT">string</TD>
<TD ALIGN="LEFT">     </TD>
<TD ALIGN="LEFT">a character string enclosed within either single or double quotes. The string may not contain a line-feed character.
</TD></TR>
</TABLE>

The identifier names are case-insensitive and may be specified
as any mixture of upper and lower case. If the code encounters
an identifier it does not recognize, the identifier and associated
value(s) will be ignore and a warning message displayed.

Any blank lines in the control parameter file will will be
ignored and additionally, any '#' not contained within quotes
is treated as the beginning of a comment and causes the remainder
of the current line to be ignored.

See the [[#Appendix 1. Control Parameters|Appendix]] for a complete list of the recognized control
parameters as well as a brief description of each.

=== Nodal Data File ===

==== Data File Format ====

The nodal data will be contained in 1 or more file
segments, with the information being broken into
three sections (described below). The first section
is the data file parameters, the second section the
domain decomposition, and the third section the nodal
data. The first two sections will be included only
in the first file segment.

==== Data File Segments ====

Given a control parameter file 'restart.cn', the
associated nodal data file(s) would be named:

restart.data[.SEQ]

where
<TABLE CELLPADDING=3 >
<TR valign="top">
<TD ALIGN="LEFT">     </TD>
<TD ALIGN="LEFT">SEQ</TD>
<TD ALIGN="LEFT">     </TD>
<TD ALIGN="LEFT">is a sequence number included only when the nodal data was written in parallel (i.e. the <numIOGroups> control parameter was greater than 1). <SEQ> will range from zero to <numIOGroups>-1.
</TD></TR>
</TABLE>

For example, suppose the <numIOGroups> control parameter
was set to 4 during a simulation executed on 16 processors.
If the simulation created a restart file set at termination,
the following files would be generated and could be used
as input to continue the simulation at a later time:

<outputDir>/restart/restart.cn
<outputDir>/restart/restart.data.0
<outputDir>/restart/restart.data.1
<outputDir>/restart/restart.data.2
<outputDir>/restart/restart.data.3

==== Data File Parameters ====

The data file parameters make up the first section of
the nodal data file and are parsed in the same manner
as specified above for the control file parameters.
These parameters must preceed the other two types of
information in the nodal data file. NOTE: The values
of these parameters are updated within the ParaDiS
code as necessary and should not be changed by the user.

The recognized data file parameters are:

: dataFileVersion
: numFileSegments
: minCoordinates
: maxCoordinates
: nodeCount
: dataDecompType
: dataDecompGeometry

==== Domain Decomposition ====

TBD

==== Nodal Data ====
The raw nodal data comprises the third section
of the nodal data file. For each node, there will
be a single line of node specific data followed by
several lines of segment specific data for each
segment associated with the node. The nodal data
consists of:

: node_tag x_coord y_coord z_coord num_arms constraint

The segment specific data consists of:

: nbr_tag burg_x burg_y, burg_z
: norm_x norm_y norm_z

where
<TABLE CELLPADDING=3 >
<TR valign="top">
<TD ALIGN="LEFT">     </TD>
<TD ALIGN="LEFT">*_tag</TD>
<TD ALIGN="LEFT">     </TD>
<TD ALIGN="LEFT">is a comma delimited pair of numbers uniquely identifying a node. The first number is the ID of the domain owning the node, the second is the index number of the node within the owning domain.
</TD></TR>
<TR valign="bottom">
<TD ALIGN="LEFT">     </TD>
<TD ALIGN="LEFT">x_coord, y_coord, z_coord</TD>
<TD ALIGN="LEFT">     </TD>
<TD ALIGN="LEFT">coordinates of the node
</TD></TR>
<TR valign="top">
<TD ALIGN="LEFT">     </TD>
<TD ALIGN="LEFT">num_arms</TD>
<TD ALIGN="LEFT">     </TD>
<TD ALIGN="LEFT">Number of segments associated with the node
</TD></TR>
<TR valign="top">
<TD ALIGN="LEFT">     </TD>
<TD ALIGN="LEFT">constraint</TD>
<TD ALIGN="LEFT">     </TD>
<TD ALIGN="LEFT">Integer value indicating any constraints placed on the node (i.e. a constraint of 7 implies a node fixed in place and unmovable)
</TD></TR>
</TABLE>

---------------------------------------------------------------------

== Cell and Domain Structure ==

The ParaDiS code is used to simulate cubic systems which
are simultaneously partitioned into a uniform mesh of
cubic 'cells' and spatially decomposed into 'domains'.

The cellular structure is defined by the <nXcells>, <nYcells>
and <nZcells> control parameters, and is used to determine
the cut-off distance between direct segment to segment
dislocation interactions and remote (or far-field) interactions.
In particular, for a given dislocation segment, the interaction
between the segment and any other segments in the same cell
or any of the immediately neighboring 26 cells are calculated
directly. Interactions with all segments outside that range
are calculated via a hierarchical Fast Multipole Method or
by lumping all segments in the remote cell into a
'super-dislocation' where the group of remote dislocations
are represented as an expansion of dislocation multipoles.
(See [[#Far-Field Dislocation Interactions|section on Far-Field Forces]] for details)

The type of spatial decomposition used for the simulation is
selected by the <decompType> control parameter, along with
the <nXdoms>, <nYdoms> and <nZdoms> parameters defining
the number of spatial domains in each dimension. Each 'domain'
is assigned to a single task (processor) within the simulation.
(See [[#Domain Decomposition 2|section on Domain Decomposition]] for details on the
supported types of spatial decomposition)

---------------------------------------------------------------------

== Domain Decomposition ==

=== Selecting a Domain Decomposition Method ===

ParaDiS simulations are spatially decomposed into a number of
domains equal to the number of processors on which the simulation
is being executed. The code curently supports two types of
domain decomposition and is selected via the <decompType>
control parameter. The type 1 decomposition is a Recursive
Sectioning decomposition which is the default if no decomposition
type is explicitly requested. The type 2 is a Recursive
Bisection decomposition. (See descriptions of decomposition
algorithms below.)

Since the ParaDiS simulations tend to grow in size and are
spatially heterogeneous, it is preferable to dynamically
recalculate the domain decomposition at intervals during the
simulation in order to rebalance the workload more efficiently.
The frequency with which the domain decomposition will be
recomputed is specified by the <DLBfreq> control parameter.

The domain decomposition will be included in the restart files.
If the simulation is restarted and the <decompType> control
parameter selects a decomposition type *other* than the
decomposition that was used to generate the restart file, the
old domain decomposition from the restart file will be ignored
and a new domain decomposition of the selected type will be used.

Additionally, if a simulation is restarted with a different number
of domains or a different domain geometry that that which was used
to create the restart file, the domain decomposition from the
restart file will be ignored and a new decomposition will be
generated.

Note: When restarting a large simulation (i.e. thousands
of processors) in such a way that the old domain decomposition must
be discarded, it may take some time for the simulation to converge
on an optimal domain decomposition. (The type 1 decomposition is
particularly susceptible to this.) There are two ways to mitigate
this effect. The first is to use the 'paradisrepart' utility, the
second through the use of the "-r" command line option to ParaDiS.
See comments in other sections pertaining to these capabilities.

=== Recursive Sectioning ===

The Recursive Sectioning algorithm performs a domain
decomposition over a 3-timestep period. During the
first timestep, the entire problem space will be
sectioned along the X dimension into <nXdoms> slabs
such that the computational cost of each slab is roughly
equivalent. The next timestep, each slab will be
sectioned alng the Y axis into <nYdoms> columns
such that the computational cost of each column in a
slab is roughly equivalent. On the thrid timestep,
every column will be sectioned along the Z axis
into <nZdoms> chunks such that the computational
cost of each chunk in a column is roughy equivalent.

As stated above, the frequency with which the domain boundaries
will be recalulated is controlled by the <DLBfreq> parameter.
If this parameter is not explicity set, the default frequency
for recalculating this type of domain decomposition is every
third timestep.

NOTE: Due to the fact that this algorithm requires 3
timesteps to complete a new decomposition, the
<DLBfreq> value must be no less than 3.

=== Recursive Bisection ===

WARNING: The implementation of this algorithm requires the
number of domains in each dimension (as specified
by the <nXdoms>, <nYdoms>, and <nZdoms> control
parameters) must be a power of 2.

The Recursive Bisectioning algorithm begins with the entire
cubic problem space and bisects the space in the X, Y and/or
Z dimensions into octants quarters or halves (depending on
the number of domains specified per dimension) such that
computational cost of each subpartition is roughly the same.
The decomposition is then recursively applied to each of the
subpartitions until no further decomposition is necesssary.

As stated above, the frequency with which the domain boundaries
will be recalulated is controlled by the <DLBfreq> parameter.
If this parameter is not explicity set, the default frequency
for recalculating this type of domain decomposition is every
timestep.

---------------------------------------------------------------------

== Dislocation Mobility ==

=== Selecting a Mobility Module ===

One of the crucial aspects of a ParaDiS simulation is the
selection of the set of rules governing the material specific
physics such as glide climb, and cross-slip with respect to
crystallographic constraints. ParaDiS provides multiple sets
of rules or "mobility laws", each implemented in a separate
module, that may be selected via the <mobilityLaw> control
file parameter. The currently support modules are:

: "BCC_0"
: "BCC_0b"

There are additional modules for dealing with FCC type materials
however these are neither fully developed nor supported at this
point. These FCC mobility functions are:

: "FCC_0"
: "FCC_2"

For a list of the control parameters related to the mobility
of dislocations, see the [[#Material and mobility parameters:|"Material and Mobility Parameters" section]] of the Appendix detailing the control file parameters.
Currently the default values of all mobility related parameters
correspond to tantalum at a temperature of 600 K and a
pressure of 0GPa.

=== BCC_0 Mobility: ===

In BCC metals, screw dislocations do not dissociate into partial
dislocations the same way they do in FCC metals, therefore, for
BCC crystals we do not assign glide plane normals to screw
dislocations. Instead, screw dislocations are given the same
mobility in all directions perpendicular to the line. This
isotropic mobility for screws mimics the "pencil-glide" behavior
of dislocations observed in BCC metals at elevated temperatures.
At the same time, the drag coefficient for non-screw segments
will remain anisotropic with respect to glide and climb.

For details on this mobility module, refer to the paper:

:<ParadisDir>/Docs/ParaDiSAlgorithm.pdf

=== BCC_0b Mobility: ===

The BCC_0b mobility module is nearly a duplicate of BCC_0 with
the exception that the movement of discretization nodes along
the dislocation lines has been dampened.

=== TBD ===

=== FCC_0 Mobility: ===

This module attempts to simulate easy glide in FCC systems. The
glide plane is limited to one of the [111] planes, and cross-slip
is not permitted. Also, no crystallographic information is
used in the dislocation core reactions and hence junction formation
can take place even slightly off the zone axis.

Reminder: This mobility module is not fully developed or supported.

=== FCC_2 Mobility: ===

TBD

---------------------------------------------------------------------

== Material Properties ==

=== Specifying Material Properties ===

All material specific properties are set via the control
file parameters. If not specified, defaults will correspond
to tantalum at a temperatue of 300 K and pressure of 0GPa.

See the [[#Material and mobility parameters:|"Material and mobility parameters" section]] of
Appendix 1 for a list of the material related parameters.

---------------------------------------------------------------------

== Far-Field Dislocation Interactions ==

=== Fast Multipole for Far-Field Interactions ===

The FMM algorithm is enabled within the code via the <fmEnabled>
toggle in the control file. The order of the multipole and
Taylor expansions used by the FMM algorithm are set via the
<fmMPOrder> and <fmTaylorOrder> control parameters respectively.
As a general rule, the taylor expansion order should be around
twice that of the multipole expansion order. One additional
control parameter [[#FMM controls|<fmCorrectionTbl>]] specifies the name of the
file containing the table used by the FMM code to adjust the
stress calculated by the FMM for multiple periodic images.

It is important to note that the file indicated by <fmCorrectionTbl>
must be built with the same multipole order, Taylor expansion order,
and Poisson value (<pois> control parameter) specified for a
simulation. An appropriate correction table may be generated
via the 'ctablegen' utility (See the section on Utilities for
details on the use of 'ctablegen'), although a correction table
matching the code's default control parameter settings *may* have
been provided in the code release as:

: <ParadisDir>/inputs/fm-ctab.Ta.600k.0GPa.m2.t5.dat

The use of a Fast Multipole Method (FMM) for calculating the
far-field forces is based on formulae for generating and evaluating
multipole expansions and a few translation theorems. A very
general description can be found below, but for details refer
to the following paper included with the source release.

:<ParadisDir>/docs/ParaDiSAlgorithm.pdf

The general FMM algorithm consists of the following steps:

# Construct multipole moments:
#: Each domain (CPU) calculates the contributions of its dislocation segments to the multipole moments of the FMM subcells to which those segments belong, and communicates those contributions to the domain that owns the FMM subcell. Each domain that owns an FMM subcell sums all the contributions for that subcell together. <bf>
# Upward pass:
#: Starting at the lowest layer of the FMM hierarchy, each domain collects and sums the contributions to the multipole moments for each of the FMM subcells it owns from the eight child cells and the calculates the upward pass translation of its multipole moments and communicates the result to the domain owing the subcell's parent, until the top of the hierarchy is reached.
# Transverse translations:
#: The multipole moments from 189 cells that are outside the nearest neighbor distance of the target cell but inside the nearest neaighbor distance of its parent are collected by the domain owning the target cell and their contributions to the Taylor series expansion of the stress filed in target is calculated.
# PBC correction:
#: The domain that owns the FMM cell at the highest level of the FMM hierarchy calculates the Taylor series expansion of the stress state due to periodic images of the system (using [[#FMM controls|table]] specified in the <fmCorrectionTbl> parameter).
# Downward pass:
#: Starting with the highest level of the FMM hierarchy, each domain that owns an FMM subcell sums the contributions from its parent to its Taylor series expansion of the stress from step 3 and then calculates the downward pass translation of the stress for each one of its child cells and sends the results to the domain owning the child subcells until the bottom of the hierarchy is reached.
# Each domain that owns a subcell at the lowest level of the FMM hierarchy communicates the Taylor series expansions of the stress field to the domains intersecting the subcell.

=== Non-FMM Far-Field Interactions ===

The use of the FMM in ParaDiS can be disable by setting the control
parameter <fmEnabled> to 0. When FMM is disabled, ParaDiS requires
additional tables used to factor in the far-field stresses from
distant cells and periodic images of the system. The names of the
files containing the tables are specified via the <Rijmfile> and
<RijmPBCfile> control parameters. These tables can be generated
using the 'stresstablegen' utility (see [[#Creating Far-Field Stress Tables with 'stresstablegen'|Utilities section]] for
details), although copies *may* have been provided in the code
release as:

: <ParadisDir>/inputs/Rijm.cube.out
: <ParadisDir>/inputs/RijmPBC.cube.out

This method essentially lumps all dislocations in a cell into a
'super-dislocation' where the cell's dislocations are represented
as an expansion of the dislocation multipoles. The remote stress
for a segment in a given cell is then calculated from two
components. The first is the sum of the stresses resulting from
expansions from all remote cells (i.e. neither the current cell
nor any of its 26 immediate neighbors) and the stress from all
periodic images of those remote cells. The second component
consists of the stress from only the periodic images of the local
cells (i.e. the current cell and its immediate neighbors).

This method is can be faster for smaller simulations but unlike
the FMM, its performance does not scale well as the size of
a simulation increases in both dislocation density and number
of cells.

---------------------------------------------------------------------

== Discretization (Remesh) ==

=== Selecting a Discretization Method ===

The nature of DD simulations is such that the total length
of dislocation lines can increase several orders of magnitude.
Hence, rediscretization of the dislocations is an absolutely necessary
components of ParaDiS simulations. The goal of the rediscretization
is to optimize the numerical description of the continuous dsilocation
line geometry so that a given level of accuracy is achieved with the
fewest degrees of freedom. For regions of high curvature, an optimal
distribution of nodes will place nodes more closely together than
in regions of lower curvature.

The level of accuracy is tied to the control parameters <maxSeg>
and <minSeg> which define the maximum and minimum segment lengths (in
units of b) respectively. The smaller the maximum segment length, the
higher the accuracy.

A number of rediscretization version have been developed and
tested, although only versions 2 and 3 are currently supported.
The rediscretization version to use can be selected through
the control parameter <remeshRule>.

=== Remesh Version 2 ===

This method achieves rediscrtization through two types of
operations; mesh coarsening and mesh refinement (removing and
adding discretization nodes respectively).

This involved defining both minimum and maximum discretization areas
(A_min and A_max) based on the simulation minimum and maximum
segment lengths <minSeg> and <maxSeg>. Then for each discretization
node (i.e. a node with no more than two associated segments) a
discretization area (A_node) is calculated. This area is defined
as the triangle with vertices at the node and its two neighbors.
When the discretization area associated with a node A_node < A_min
the node is removed (coarsened out). Conversely, if the area
A_node > A_max, the local discretization is refined by bisecting
both segments attached to the node.

For additional information, refer to the following paper included
with the ParaDiS source release:

: <ParadisDir>/docs/ParaDiSAlgorithm.pdf

=== Remesh Version 3 ===

This rediscretization method is identical to type 2 with
the exception that during mesh refinement the inserted
nodes are not placed at the exact center of the segment
being bisected. Instead, the algorithm treats the three
initial nodes as if they were on an arc and places the
new nodes at the center of the segments of the arc.

The rationale behind this is that in simulations using
long segments and/or high stress, a new node added at the
center of a segment in a region of high curvature will
not be optimally placed. This new node may immediately
accelerate quickly toward its optimal position then
decelerate as it nears that position. This behavior
can severly impact the simulatuion timesteps. By placing
the new nodes on an arc, the initial stress on the new
nodes will not be as high, keeping the motion of the node
similar to that of the surrounding nodes. Hence, no
detrimental effects on the timestep.

---------------------------------------------------------------------

== Simulation Timestepping ==

=== Timestep Controls ===

Two timestepping algorithms are provided in the ParaDiS code.
The <timestepIntegrator> control parameter is used to select
the desired algorithm. The currently supported algorithms
are:

: "trapezoid"
: "forward-euler"

The default timestep integrator is the "trapezoid" integrator.
There are several general control parameters used in conjunction
with any selected timestep intergrator, and several that are unique
to specific integrators. The general control parameters are
<deltaTT> which specifies the duration of the previous timestep,
<nextDT> which indicates the desired timestep to attempt the next
timestep, and <maxDT> which specifies the maximum timestep duration
permitted.

=== Timestep Integrators ===

==== Trapezoid ====

This implicit integrator is a mix of the Euler-Forward and
Euler-Backward methods. This method is unconditionally
stable, but requires an iterative process that may involve
multiple nodal force and velocity calculations. The
additional expense of the multiple calculations, however,
is usually offset by the gains from the larger timesteps
compared to explicit methods such as the forward euler
integrator.

The algorithm uses the current nodal velocities to reposition
each node, then recalculates forces and velocities for the
nodes at their new positions. A positioning 'error' is
calculated for each node based on the current and previous
nodal position and velocity. If the positioning error of
any node is greater than the maximum permitted positioning
error as defined by the <rTol> control parameter, the
timestep will be decremented by a factor specified in the
<dtDecrementFact> control parameter and the process starts
again. On the otehr hand, if the positioning error of all
nodes is within the tolerance, the timestep is accepted
and the current timestep is multipled by the factor in the
<dtIncrementFactor> to be used as the initial timestep to
attempt the next cycle.

==== Forward Euler ====

The forward euler timestep integrator is relatively simple
and inexpensive in that it requires only a single calculation
of nodal force and velocities per timestep. Unfortunately,
the algorithm is subject to the Courant condition for
numerical stability and is limited to relatively small
timesteps. The size of the timestep is controlled by the
ratio between the length of the shortest segment and the
velocity of the fastest moving node. Additionally, the
<rmax> control parameter defines the maximum distance
any node is permitted to move in a single timestep, which
further limits the timestep duration. This 'rmax' distance
should be set such that no dislocation segment crosses
multiple simulation cells in a single timestep.

Note: This timestep integrator is NOT recommended.

---------------------------------------------------------------------

== Visualization ==

=== X-window display ===

ParaDiS provides a simple X-window display capability for
visualization and debugging of small scale simulations as well
as obtaining certain types of nodal data via the display window.

Unlike some of the other visualization capabilities, this one
must be enabled/disabled via the compile time flag "XLIB_MODE"
in the file <ParadisDir>/makefile.setup. The X-window support
is enabled by setting:

: XLIB_MODE = ON

and disabled by:

: XLIB_MODE = OFF

The default behavior is to have the X-window support enabled.

The <winDefaultsFile> control parameter can be used to specify default
visualization options and attributes such as view perspective, colors
and so on. Unless otherwise specified, this control parameter will
point to the following defaults file provided with the source release:

: <ParadisDir>/inputs/paradis.xdefaults

Once the X-window display is initiated, the view can be controlled
through the following single-key commands:

Key Command Description
--- -------------------
<Home> Restores image to default view
<Esc> Terminates X-window display without terminating
the simulation
a Enable/disable aspect ratio changes. When enabled,
the Arrow keys alter the aspect ratio
c Enable/disable slice view of image. When enabled,
Up/Down Arrows control slice position, Left/Right
Arrows control slice thickness.
f Turn display frame on/off
p Pause/restart simulation
r Enable image rotation. When enabled, rotation can
be controlled via the mouse or Arrow keys.
s Enable display scaling. When enabled, the Arrow
keys control scaling size.
t Enable image translation. When enable,
the Arrow keys control translation direction.
<F10> Generate a postscript image of the display window.
File will be called <outputDir>/YshotNNNN where
'NNNN' is a sequence number incremented each time
a dump of the display window is generated and
<outputDir> is the directory specified by the
<dirname> control file parameter.

Additionally, clicking the mouse on a nodal point in the X-window
image will cause the following information to be written to the
terminal device (not the X-window display):

* relative position (x,y) on the X-window display
* node ID (domainID,nodeindex)
* number of segments (arms) associated with the node
* simulation coordinates (x,y,z) of the node

=== Gnuplot ===

ParaDiS is capable of producing output files formatted for use
with the gnuplot visualization package. This capability is
enabled via the <gnuplot> toggle in the control parameter file.
The frequency with which gnuplot files will be generated is
controlled by the settings of the <gnuplotfreq> and <gnuplotdt>
parameters.

When this capability is enabled, the code will periodically
create a set of gnuplot output files in the directory
<outputDir>/gnuplot where <outputDir> is the directory
specified by the <dirname> control file parameter. The
naming convention used for these files is:

: <outputDir>/gnuplot/box.in
: <outputDir>/gnuplot/0tNNNN[.SEQ]

where
<TABLE CELLPADDING=3 >
<TR valign="top">
<TD ALIGN="LEFT">     </TD>
<TD ALIGN="LEFT">NNNN</TD>
<TD ALIGN="LEFT">     </TD>
<TD ALIGN="LEFT">is a sequence number begining at '0001' and incremented each time a gnuplot file set is written.
</TD></TR>
<TR valign="top">
<TD ALIGN="LEFT">     </TD>
<TD ALIGN="LEFT">SEQ</TD>
<TD ALIGN="LEFT">     </TD>
<TD ALIGN="LEFT">is a sequence number included only when gnuplot files are being written in parallel (i.e. the <numIOGroups> control parameter is greater than 1) <SEQ> will range from zero to <numIOGroups>-1.
</TD></TR>
</TABLE>

In addition, at program termination, an extra set of gnuplot
files will be created. This set will be generated regardless
of the specified dump frequency in order to provide an image
of the final configuration. This set will be named with the
slightly different naming convention:

: <outputDir>/gnuplot/gnuplot.final[.SEQ]

The 'box.in' data file will contain data for plotting the boundaries
of the simulation space, while the '0t*' files contain the coordinate
pairs defining each unique dislocation segment.

NOTE: When gnuplot data is being written in parallel
(i.e. <numIOGroups> is larger than 1), the dislocation segment
data is spread over the file segments. These file segments
can be combined into a single file for display in gnuplot
via the <ParadisDir>/tools/stitch tool. (See description of
[[#stitch|'stitch']] tool for details.)

To aid in visualizing the dislocation configuration, a file
containing commands to set some useful gnuplot options has
been provided; This file is located at:

: <ParadisDir>/inputs/gnuplot.cmds

For example, to view the dislocation structure contained in the
gnuplot data file 0t0001 you could start gnuplot interactively
and execute the commands:

gnuplot> load '<ParadisDir>/inputs/gnuplot.defaults'
gnuplot> splot 'box.in' with lines, '0t0001' w lines

A second gnuplot command file has been provided as an example
of displaying a sequence of gnuplot files. This file is
located at:

: <ParadisDir>/inputs/gnuplot.movie

This file has the neccesary commands to plot the sequence
of files beginning with 0t0001 and ending with 0t1000. After
starting gnuplot, simply load this file with:

gnuplot> load '<ParadisDir>/inputs/gnuplot.movie'

This will initiate the plot of the first file, and thereafter,
simply hitting return will cause gnuplot to move to the next
file in the sequence.

For details on using gnuplot, refer to the gnuplot manual or
enter 'help' from the gnuplot interactive prompt.

=== Tecplot ===

ParaDiS is capable of producing output files formatted for use
with the commercial visualization package Tecplot. This
capability is enabled via the <tecplot> toggle in the control
parameter file. The frequency with which tecplot files will
be generated is controlled by the settings of the <tecplotfreq>
and <tecplotdt> parameters.

When this capability is enabled, the code will periodically
create a set of tecplot output files in the directory
<outputDir>/tecplot where <outputDir> is the directory
specified by the <dirname> control file parameter. The
naming convention used for these files is:

: <outputDir>/tecplot/tecdataNNNN[.SEQ]

where
<TABLE CELLPADDING=3 >
<TR valign="top">
<TD ALIGN="LEFT">     </TD>
<TD ALIGN="LEFT">NNNN</TD>
<TD ALIGN="LEFT">     </TD>
<TD ALIGN="LEFT">is a sequence number begining at '0001' and incremented each time a tecplot file set is written.
</TD></TR>
<TR valign="top">
<TD ALIGN="LEFT">     </TD>
<TD ALIGN="LEFT">SEQ</TD>
<TD ALIGN="LEFT">     </TD>
<TD ALIGN="LEFT">is a sequence number included only when tecplot files are being written in parallel (i.e. the <numIOGroups> control parameter is greater than 1) <SEQ> will range from zero to <numIOGroups>-1.
</TD></TR>
</TABLE>

In addition, at program termination, an extra set of tecplot
files will be created. This set will be generated regardless
of the specified dump frequency in order to provide an image
of the final configuration. This set will be named with the
slightly different naming convention:

: <outputDir>/tecplot/tecdata.final[.SEQ]

The generated tecplot output has specific headers to assign the
variables and time frames (zones) and should look something like
this:

...
variables = X,Y,Z,V1,V2,V3,V4,V5,V6,V7,V8
zone i = 54 F=POINT
-4000.0 500.0 6000.0 133.1 612.4 -612.3 0.0000 0.0000 0.0000 1 3
-3866.9 1112.4 5387.7 -133.1 -612.4 612.3 0.0000 0.0000 0.0000 1 3
471.0 -5132.6 11632.3 -1712.7 -48.8 48.9 0.0090 -0.0918 0.0918 2 3
...

The first line defines the variables to reconstruct the dislocation
configuration. X Y and Z specify the nodal coordinates, V1 V2 and
V3 define arm vectors to the neighboring nodes. These 6 variable
are used to represent dislocation segments as combinations of points
and vectors in tecplot. The V4 V5 and V6 represent the nodal velocity
vector, V7 indicates the number of segments associated with the node
and V8 indicates a burgers vector type.

NOTE: When tecplot data is being written in parallel
(i.e. <numIOGroups> is larger than 1), the headers will only be
included in the first file segment with the remainder of the data
spread over the file segments. These file segments can be combined
into a single file for display in tecplot via the
<ParadisDir>/tools/stitch tool. (See description of [[#stitch|'stitch']]
tool for details.)

For details on using tecplot, refer to the tecplot manual or select
the 'Help' menu in tecplot.

=== Povray ===

If the <povray> toggle is set in the control file,
ParaDiS will periodically generate files containing
dislocation segment data formatted for use with the POVRAY
(Persistence of Vision(tm) Ray Tracer) tool. The frequency
with which these files will be generated is controlled by
the settings of the <povrayfreq> and <povraydt> parameters.

Note: These files contain the main data to be processed by
povray, but must be post-processed via the
'genPovrayFrames' tool (See [[#genPovrayFrames|section]] on Tools)
which will create the final povray input file
containing the segment data embedded within a
proper framework of povray settings and commands.

When this capability is enabled, the code will periodically
create a set of files in the directory <outputDir>/povray
where <outputDir> is the directory specified by the <dirname>
control file parameter. The naming convention used for
these files is:

: <outputDir>/povray/povframeNNNN[.SEQ]

where
<TABLE CELLPADDING=3 >
<TR valign="top">
<TD ALIGN="LEFT">     </TD>
<TD ALIGN="LEFT">NNNN</TD>
<TD ALIGN="LEFT">     </TD>
<TD ALIGN="LEFT">is a sequence number begining at '0001' and incremented each time a povray frame file set is written.
</TD></TR>
<TR valign="top">
<TD ALIGN="LEFT">     </TD>
<TD ALIGN="LEFT">SEQ </TD>
<TD ALIGN="LEFT">     </TD>
<TD ALIGN="LEFT">is a sequence number included only when povray files are being written in parallel (i.e. the <numIOGroups> control parameter is greater than 1) <SEQ> will range from zero to <numIOGroups>-1.
</TD></TR>
</TABLE>

In addition, at program termination, an extra set of povray
frame files will be created. This set will be generated
regardless of the specified dump frequency in order to provide
an image of the final configuration. This set will be named
with the slightly different naming convention:

: <outputDir>/povray/povray.final[.SEQ]

NOTE: When povray data is being written in parallel
(i.e. <numIOGroups> is larger than 1), the dislocation segment
data is spread over the file segments. If desired, these file
segments may be combined into a single file for post-processing
via the <ParadisDir>/tools/stitch tool. (See description
of [[#stitch|'stitch']] tool for details.)

As stated above, these files must be post-processed via the
'genPovrayFrames' tool (See [[#genPovrayFrames|section]] on Tools) which will
create the final povray input file containing the segment
data embedded within a proper framework of povray settings
and commands. This tool is capable of dealing with single
or segmented 'povframe*' files.

For details on using povray, refer to the povray manual.

=== Terascale Browser ===

TBD

=== Postscript ===

If the <psfile> toggle is set in the control file,
ParaDiS will periodically generate a postscript file
containing an image of the current state of the system.
The frequency with which the postscript files are
written is determined by the settings of the
<psfilefreq> and <psfiledt> control file parameters.
All files will be located in the directory <outputDir>
where <outputDir> is the directory specified by the
<dirname> control file parameter.

All files will be named with the following convention:

: <outputDir>/YshotNNNN.ps

where NNNN is a sequence number beginning with zero and incremented
each time another postscript file is written.

---------------------------------------------------------------------

== Output ==

=== Restart files ===

Periodic creation of ParaDiS restart files is enabled via
the <savecn> toggle in the control file. The frequency with
which restart files are written is determined by the settings
of the <savecnfreq> and <savecndt> control file parameters.

When enabled, the code will periodically generate restart
file which will be located in the directory <outputDir>/restart
where <outputDir> is the directory specified by the <dirname>
control file parameter.

The naming convention used for these restart files is:

<TABLE CELLPADDING=3 >
<TR valign="top">
<TD ALIGN="LEFT">     </TD>
<TD ALIGN="LEFT"><outputDir>/restart/rsNNNN</TD>
<TD ALIGN="LEFT">     </TD>
<TD ALIGN="LEFT"># control parameter file
</TD></TR>
<TR valign="top">
<TD ALIGN="LEFT">     </TD>
<TD ALIGN="LEFT"><outputDir>/restart/rsNNNN.data[.SEQ]</TD>
<TD ALIGN="LEFT">     </TD>
<TD ALIGN="LEFT"># nodal data file
</TD></TR>
</TABLE>
where
<TABLE CELLPADDING=3 >
<TR valign="top">
<TD ALIGN="LEFT">     </TD>
<TD ALIGN="LEFT">NNNN</TD>
<TD ALIGN="LEFT">     </TD>
<TD ALIGN="LEFT">is a sequence number begining at '0001' and incremented each time a restart file set is written.
</TD></TR>
<TR valign="top">
<TD ALIGN="LEFT">     </TD>
<TD ALIGN="LEFT">SEQ</TD>
<TD ALIGN="LEFT">     </TD>
<TD ALIGN="LEFT">is a sequence number included only when restart files are being written in parallel (i.e. the <numIOGroups> control parameter is greater than 1) <SEQ> will range from zero to <numIOGroups>-1.
</TD></TR>
</TABLE>

Each time a restart file set is written, the name of the
control parameter file will also be written into the file:

: <outputDir>/latest_restart

Additionally, when creation of restart files is enabled, an
additional restart file pair named 'restart.cn' and restart.data'
will be written at program termination even if the cycle is not
a multiple of the <savecnfreq> control parameter.

=== Property Outputs ===

==== Enabling Properties Output ====

The code has the capability to produce files containing
various dislocation properties. This capability is enabled
via the <saveprop> toggle in the control file. The
frequency with which the property data is written is
determined by the settings of the <savepropfreq> and
<savepropdt> control file parameters.

When this capability is enabled, the code will generate
and periodically append the properties data to one or more of
the following files which will be located in the directory
<outputDir>/properties, where <outputDir> is the directory
specified by the <dirname> control file parameter.

==== Property Files ====

===== density =====

Note: burgVolFactor converts from length in units of B, to density
in units of meters

This file contains the following columns of data:

# plastic strain
# strain
# dislocation density
# deleted dislocation density
#: (lost through annihilation, junction formation, etc)
#: (density lost since last dump of data)
# average dislocation velocity‡
# std. deviation of dislocation velocities‡
# density file version number
# dislocation density for segments of specific groupings of burgers vectors (see below)*

‡ These items will be calculated only if
the "VEL_STATISTICS" pre-processor macro was
defined during compilation. Otherwise these
values will be zeroes.

For BCC simulations:
Column Burgers vector types
8 [ 1 1 1] [-1-1-1]
9 [-1 1 1] [ 1-1-1]
10 [ 1-1 1] [-1 1-1]
11 [ 1 1-1] [-1-1 1]
12 [ 1 0 0] [-1 0 0] [ 0 1 0]
[ 0-1 0] [ 0 0 1] [ 0 0-1]

For FCC simulations:
Column Burgers vector types
8 [ 1 1 0] [-1-1 0]
9 [-1 1 0] [ 1-1 0]
10 [ 1 0 1] [-1 0-1]
11 [-1 0 1] [ 1 0-1]
12 [ 0 1 1] [ 0-1-1]
13 [ 0-1 1] [ 0 1-1]
14 all others

===== time_Plastic_strain =====

This file contains the following two columns of data:

# elapsed simulation time
# plastic strain

===== stress_Plastic_strain =====

This file will only be generated if the user specified
a loadType of 1 (constant strain rate) or 4 (cyclic
loading). The file contains the following two columns
of data:

# plastic strain
# stress

===== stress_Total_strain =====

This file will only be generated if the user specified
a loadType of 1 (constant strain rate) or 4 (cyclic
loading). If the user specified a constant strain
rate, this file contains:

# strain
# stress

If the user specified cyclic loading, this file contains:

# net accumulated strain
# stress
# elapsed simulation time
# number of loading cycles

===== alleps =====

This file contains the following 9 columns of data:

{|
|-
| align=right | 1.||simulation timestep number
|-
| align=right | 2.||elapsed simulation time
|-
| align=right | 3-8.||plastic strain components‡
|-
| align=right | 9.||dislocation density
|}

‡ from plastic strain tensor matrix, elements [0][0], [1][1], [2][2], [1][2], [0][1], and [0][2]

===== epsdot =====

This file contains the 2 columns of data:

# elapsed simulation time
# plastic strain rate

=== Flux Decomposition ===

ParaDiS has the capability to produce files containing
flux decomposition information for the simulation.
This capability is enabled via the <fluxfile> control
file toggle. The frequency with which the flux
data is written is determined by the settings of
the <fluxfreq> and <fluxdt> control file parameters.

When this capability is enabled the code will generate
and periodically append the flux data to two sets of
files that will be located in the directory
<outputDir>/fluxdata where <outputDir> is the directory
specified by the <dirname> control file parameter.

Each set contains four files, one file per burgers vector.
Files *b1, *b2, *b3, and *b4 contain statistics for burgers
vector types [111], [-111], [1-11], and [11-1] respectively.

The first set of files (Ltot_b1, Ltot_b2, Ltot_b3 and
Ltot_b4) consist of the following 9 columns of data:

# Plastic strain
# Strain,
# Screw density
# Edgedensity1
# Edgedensity2
# Edgedensity3
# Sum of edge Densities (4+5+6)
# Total system EdgeDensity from all Ltot files
# Total system screw density from all Ltot files

The second set of files (fluxtot_b1, fluxtot_b2, fluxtot_b3 and
fluxtot_b4) consist of the following 9 columns of data:

{|
|-
| align=right | 1.||Plastic Strain
|-
| align=right | 2.||Strain
|-
| align=right | 3.||Flux due to climb motion
|-
| align=right | 4-6.||Flux created by edge components on three planes (See below.)
|-
| align=right | 7-9.||Flux created by screw dislocation on three planes (See below.)
|}

For b1 = 1/2[1 1 1]
<ol start="4">
<li> ( 0 1 -1), [-2 1 1]</li>
<li> (-1 0 1), [ 1 -2 1]</li>
<li> ( 1 -1 0), [ 1 1 -2]</li>
<li> ( 0 1 -1), [-2 1 1]</li>
<li> (-1 0 1), [ 1 -2 1]</li>
<li> ( 1 -1 0), [ 1 1 -2]</li>
</ol>
For b2 = 1/2[-1 1 1]
<ol start="4">
<li> ( 0 1 -1), [ 2 1 1] </li>
<li> ( 1 0 1), [ 1 2 -1] </li>
<li> ( 1 1 0), [ 1 -1 2] </li>
<li> ( 0 1 -1), [ 2 1 1] </li>
<li> ( 1 0 1), [ 1 2 -1] </li>
<li> ( 1 1 0), [ 1 -1 2] </li>
</ol>
For b3 = 1/2[1 -1 1]
<ol start="4">
<li> ( 0 1 1), [ 2 1 -1] </li>
<li> ( 1 0 -1), [ 1 2 1] </li>
<li> ( 1 1 0), [-1 1 2] </li>
<li> ( 0 1 1), [ 2 1 -1] </li>
<li> ( 1 0 -1), [ 1 2 1] </li>
<li> ( 1 1 0), [-1 1 2] </li>
</ol>
For b4 = 1/2[1 1 -1]
<ol start="4">
<li> ( 0 1 1), [ 2 -1 1] </li>
<li> ( 1 0 1), [-1 2 1] </li>
<li> ( 1 -1 0), [ 1 1 2] </li>
<li> ( 0 1 1), [ 2 -1 1] </li>
<li> ( 1 0 1), [-1 2 1] </li>
<li> ( 1 -1 0), [ 1 1 2] </li>
</ol>

=== Pole figures ===

TBD

=== Velocity files ===

If the <velfile> toggle is set in the control file,
ParaDiS will periodically generate a set of files containing
velocity information about each unique dislocation node
in the system. The frequency with which the velocity
data is written is determined by the settings of the
<velfilefreq> and <velfiledt> control file parameters.
All files will be located in the directory <outputDir>/velocity
where <outputDir> is the directory specified by the
<dirname> control file parameter.

All files will be named with the following convention:

: <outputDir>/velocity/velNNNN[.SEQ]

where
<TABLE CELLPADDING=3 >
<TR valign="top">
<TD ALIGN="LEFT">     </TD>
<TD ALIGN="LEFT">NNNN</TD>
<TD ALIGN="LEFT">     </TD>
<TD ALIGN="LEFT">is a sequence number based on the <velfilecounter> control parameter and is incremented each time another velocity file is written.
</TD></TR>
<TR valign="top">
<TD ALIGN="LEFT">     </TD>
<TD ALIGN="LEFT">SEQ </TD>
<TD ALIGN="LEFT">     </TD>
<TD ALIGN="LEFT">is a sequence number included only when velocity data is being written in parallel (i.e. <numIOGroups> control parameter is greater than 1. SEQ will range from zero to <numIOGroups>-1.
</TD></TR>
</TABLE>

In addition, at program termination, an extra set of velocity
files will be created. This set will be generated regardless
of the specified dump frequency in order to provide an image
of the final configuration. This set will be named with the
slightly different naming convention:

: <outputDir>/velocity/vel.final[.SEQ]

NOTE: When velocity data is being written in parallel
the dislocation segment data is spread over the file segments.
These file segments can be combined into a single file via
the <ParadisDir>/tools/stitch tool. (See [[#stitch|section]] on Tools
for details)

The contents of the velocity files consist of 4 columns
of data for each unique dislocation segment. Those
columns are:

{|
|-
| align=right | 1-3.||Velocity components (x,y,z)
|-valign="top"
| align=right | 4.|| +1 if contributing to strain rate <br> -1 if moving in opposite direction
|}

=== Segment files ===

If the <armfile> toggle is set in the control file,
ParaDiS will periodically generate a set of files containing
information about each unique dislocation segment
in the system. The frequency with which the segment
(or arm) files are written is determined by the settings
of the <armfilefreq> and <armfiledt> control file parameters.
All files will be located in the directory <outputDir>/armdata
where <outputDir> is the directory specified by the
<dirname> control file parameter.

All files will be named with the following convention:

: <outputDir>/armdata/armNNNN[.SEQ]

where
<TABLE CELLPADDING=3 >
<TR valign="top">
<TD ALIGN="LEFT">     </TD>
<TD ALIGN="LEFT">NNNN</TD>
<TD ALIGN="LEFT">     </TD>
<TD ALIGN="LEFT">is a sequence number based on the <armfilecounter> control parameter and is incremented each time another arm file is written.
</TD></TR>
<TR valign="top">
<TD ALIGN="LEFT">     </TD>
<TD ALIGN="LEFT">SEQ</TD>
<TD ALIGN="LEFT">     </TD>
<TD ALIGN="LEFT">is a sequence number included only when arm data is being written in parallel (i.e. <numIOGroups> control parameter is greater than 1. SEQ will range from zero to <numIOGroups>-1.
</TD></TR>
</TABLE>

In addition, at program termination, an extra set of arm
files will be created. This set will be generated regardless
of the specified dump frequency in order to provide an image
of the final configuration. This set will be named with the
slightly different naming convention:

: <outputDir>/armdata/arm.final[.SEQ]

NOTE: When arm data is being written in parallel
the dislocation segment data is spread over the file segments.
These file segments can be combined into a single file via
the <ParadisDir>/tools/stitch tool. (See [[#stitch|section]] on Tools
for details)

The contents of the arm files consist of 10 columns
of data for each unique dislocation segment. Those
columns are:

{|
|-
| align=right | 1-3.||Burgers vector components
|-
| align=right | 4-6.||Line direction vector
|-
| align=right | 7.||Segment length
|-
| align=right | 8-10.||Coordinates of node 'owning' the segment
|}

=== Density Field file ===

If all components of the <savedensityspec> control parameter
are set to positive values in the control file, ParaDiS
will (at program termination) create a file containing a
3D dislocation density field formatted for use with the
VASP Data Viewer (vaspview). The three components of
the <savedensityspec> parameter specify the granularity
of the density field in the X, Y and Z dimensions
respectively. The density field will be written to the
file:

: <outputDir>/densityfield.out

Warning: This will overwrite any existing density field
file of the same name!

The VASP Data Viewer is publicly available on the web
for non-commercial use. For details on the product,
download the VASP Data Viewer from the web and refer
to the accompanying documentation.

---------------------------------------------------------------------

== Utilities ==

=== Creating Initial Dislocations with 'paradisgen' ===

The paradisgen utility is capable of generating initial
dislocations suitable for a paradis simulation. The command
line options for paradisgen control the type of dislocations,
number of dislocations, size of the simulation box, and so
on. See "Examples" below for sample executions of this utility.

The command line format for paradisgen is:

paradisgen [-cubel <cubelength>] [-help] [-hexsize <size>] \
[-maxseg <maxseglen] [-nchains <numchains>] \
[-nloops <numloops>] [-outfile <filename> \
[-radius <radius>] [-seed <seedval>] \
[-type <configtype>]

All command line options may be abbreviated to the shortest
non-ambiguous abbreviation of the option. Descriptions of
the command lines options are as follows:

<pre>
-cubel <cubelength> Defines the size of the simulation cube
in units of b. Minimum and maximum problem
space coordinates will be 0.5*cubel and
-0.5*cubel respectively. If not specified
this will default to 35000b (approx.
10 micron).

-help Causes the utility to display the command line
format and option descriptions then terminate.

-hexsize <size> Defines the radius (in units of b) for the
hexagonal interstitial loops. This option is
used only when the selected dislocation type
is 'fcc-irrad'.

-looptype <ltype> Specifies the types of prismatic loops to
generate. If not specified, this value
will default to zero. Valid values are:

0 == mixture of [1 1 1] and [1 0 0] types
1 == all [1 1 1] type loops
2 == all [1 0 0] type loops

This option is only used when the selected
dislocation type is 'prismatic-loop'.

-maxseg <length> Defines the maximum desired segment length
in units of b. Initial dislocations will
be discretized so no segment is longer than
this value. If not specified this value
defaults to 500.

-nchains <numchain> Indicates the number of dislocation lines
to create. This value is ignored when the
selected dislocation type is 'prismatic-loop',
and when the type is 'fcc-perfect-loop',
this value must be a multiple of 12. If
not specified, this value defaults to 2.

-nloops <numloops> Specifies the number of loops to create when
the selected dislocation type is
'prismatic-loop' or 'fcc-irrad'. If not
specified, this value defaults to 1000.

-nsegs <numsegs> Specifies the number of segments into which
a prismatic loop will be discretized. This
option is only used when the selected
dislocation type is 'prismatic-loop'. If
not specified, this value defaults to
(2*PI*radius)/(maxseg/2).

-outfile <filename> Name of the ParaDiS data file to be created.
If not specified, data will be written
into a file called 'paradis.data'.

-radius <radius> Radius (in units of b) of prismatic loops.
This option is only used when the selected
dislocation type is 'prismatic-loop'. If
not specified, this value defaults to maxseg/2.

-seed <seed> Specifies a value to seed the random number
generator. Using the same seed value for
multiple executions of paradis (for which
all other options are identical) insures
creation of an identical configuration.

-type <type> Specifies the type of dislocations to create.
This type can be a name or the integer value
corresponding to the name. Valid types are:

0 or 'screw' BCC screw dislocations.
Assumes periodic boundary
conditions are enabled.
1 or 'finite-mixed' A mixture of BCC screw and
edge dislocations
terminating at the edges
of the cubic problem
space. This should not
be used with periodic
boundary conditions.
2 or 'prismatic-loop' BCC prismatic loops.
Assumes periodic boundary
conditions are enabled.
3 or 'fcc' FCC dislocations. Assumes
periodic boundary
conditions are enabled.
4 or 'fcc-irrad' Mixture of FCC
dislocations and hexagonal
interstitial loops.
Assumes periodic boundary
conditions are enabled.
5 or 'fcc-perfect-loop' Not fully implemented.

Examples:
---------

TBD
</pre>

=== Recomputing Domain Boundaries with 'paradisrepart' ===

The paradisrepart utility provides a mechanism by which to
replace the domain decomposition/partitioning in an
existing nodal data file with a new domain decomposition.
The utility will read the current nodal data, and use the
specified domain/cell geometries to attempt to partition
the domains such that the computational cost for each domain
will be roughly equivalent.

This utility is primarily used when it is necessary alter
the domain geometry or domain count for a simulation in
order to continue. In such a situation, the existing
domain decomposition would be thrown away and the ParaDiS
code would generate an initial uniform decomposition
and then over time converge on a more optimal decomposition.
Using this utility instead to generate a new decomposition
provides a much more reasonable starting point from allowing
the ParaDiS simulation to converge on an optimal decomposition
much more quickly.

The command line format for the paradisrepart utility is:

paradisrepart -infile <inputFile> \
-cells <xcells[,ycells,zcells]> \
-domains <xdoms[,ydoms,zdoms]> \
[-outfile <outputFile>] [-decompType <type>] \
[-help]

All command line arguments and options may be abbreviated to the
shortest non-ambiguous abbreviation of the option. Descriptions
of the command lines options are as follows:

<pre>
-infile <inputFile> Specifies the name of the nodal data file.
On success, the first nodal data file
segment will be copied to <inputFile>.bkup.
This command line argument is not optional.

-cells <xcells[,ycells,zcells]> Specifies the number of
cells in each dimension. If the
number of cells in the Y and Z dimensions
are not provided, they will default to the
same value as <xcells>. This command line
argument is not optional.

-domains <xdoms[,ydoms,zdoms]> Specifies the number of domains
in each dimension. If the number of
domains in the Y and Z dimensions are
not provided, they will default to the
same value as <xdoms>. This command line
argument is not optional.

-decompType <type> Specifies type of domain decomposition:
If not specified, defaults to 1. Valid
types are:

1 == Recursive Sectioning
2 == Recursive Bisectioning

-help Causes the utility to display the command
line format and option descriptions then
terminate.

-outfile <outputFile> Specifies the name of the file into which
to write the new domain decomposition. If
not specified, new domain decomposition
will be written into the file specified
by <inputFile>.

Examples:
---------
</pre>

=== Converting Control and Data File with 'paradisconvert' ===

The paradisconvert utility provides a mechanism by which
older format ParaDiS control and data files (and restart
files) may be converted to the current file formats.
This utility does recognize and handle segmented data files.

In most cases this utility will not be required since
ParaDiS is still able to recognize and handle *most* of
the older file formats. The only format the ParaDiS code
no longer recognizes is the truly ancient format associated
with the earliest incarnations of the code in which the
control file parameters and nodal data were included in
a single file. For these control files, the paradisconvert
utility will be needed.

The command line format for the paradisconvert utility is:

paradisconvert <controlFile> [dataFile]

where:
<TABLE CELLPADDING=3 >
<TR valign="top">
<TD ALIGN="LEFT">     </TD>
<TD ALIGN="LEFT">controlFile</TD>
<TD ALIGN="LEFT">     </TD>
<TD ALIGN="LEFT">Specifies the name of the control parameter file to be updated to the current format.
</TD></TR>
<TR valign="top">
<TD ALIGN="LEFT">     </TD>
<TD ALIGN="LEFT">dataFile</TD>
<TD ALIGN="LEFT">     </TD>
<TD ALIGN="LEFT">If the specified control file is the original ancient format including control parameters and nodal data in the single file, this argument is ignored. Otherwise, this specifies the base name of the nodal data file(s) to be converted. If not this argument is not provided, it will default to the same name as <controlFile> with any file name suffix removed and the '.data' suffix added.
</TD></TR>
</TABLE>

On success, the utility will rename the original files by appending
a '.bkup' suffix to the names, and create new control and data files
with the specified names. Note: for control parameter files which
include nodal data, a new data file will be generated under the
the name as <controlFile> with any file name suffix removed and
a '.data' suffix added.

<u>Examples:</u>

To convert the original format file 'restart.cn' containing
both control parameters and nodal data, execute:

paradisconvert restart.cn

The utility will generate the following files:

: restart.cn.bkup
: restart.cn
: restart.data

To convert a newer control parameter and data file pair with
the names 'rs0100' and 'rs0100.data' respective, execute either
of the following equivalent command lines:

paradisconvert rs0100
paradisconvert rs0100 rs0100.data

In both cases, the utility would generate the files:

: rs0100.bkup
: rs0100.data.bkup

: rs0100
: rs0100.data

To convert a newer control file <rs0100> and a set of segmented
data files with the names <rs0100.data.0>, <rs0100.data.1>, ...
<rs0100.data.7>, execute any of the following equivalent commands:

paradisconvert rs0100
paradisconvert rs0100 rs0100.data
paradisconvert rs0100 rs0100.data.0

In all of the above cases, the utility would generate the files

: rs0100.bkup
: rs0100.data.0.bkup
: rs0100.data.1.bkup
: ...
: rs0100.data.7.bkup

: rs0100
: rs0100.data.0
: rs0100.data.1
: ...
: rs0100.data.7

=== Creating the FMM Image Correction Table with 'ctablegen' ===

The 'ctablegen' utility is used to create an image correction
table needed when the FMM (Fast Multipole Method) has been enabled
by setting the <fmEnabled> toggle on in the control file. Since
the data in this file is dependent on the poisson ratio, shear
modulus, and orders of the multipole and taylor expansions, the
file must be created for the particular values of these items
used in the simulation.

Given the current defaults used by ParaDiS (as set in Param.c):

{|
|      ||align="left"| poisson ratio: ||align="center"| 3.327533e-01
|-
| ||align="left"| shear modulus: ||align="center"| 6.488424e+10
|-
| ||align="left"| multipole order: ||align="center"| 2
|-
| ||align="left"| taylor expansion order: ||align="center"| 5
|}

To create the FMM image correction table, you could execute
ctablegen from the main <ParadisDir> directory using the
following command line:

bin/ctablegen -nu 3.327533e-01 -mu 6.488424e+10 -mporder 2 -torder 5 -outfile \
inputs/fm-ctab.Ta.600K.0GPa.m2.t5.dat

NOTE: The generation of this table can take a significant
amount of time, therefore, a parallel version of the utility
(called ctablegenp) has also been provided. To execute the
table generation in parallel on 8 processors using mpirun as
a parallel program initiator, one could execute:

mpirun -np 8 bin/ctablegen -nu 3.327533e-01 -mu 6.488424e+10 -mporder 2 -torder 5 -outfile \
inputs/fm-ctab.Ta.600K.0GPa.m2.t5.dat

The locations of this file is specified in the control
parameter file via the <fmCorrectionTbl> parameter.

=== Creating Far-Field Stress Tables with 'stresstablegen' ===

The 'stresstablegen' utility is used to create tables needed
for calculating stress from distant cells and periodic images
of the system when FMM is disabled (i.e. <fmEnabled> is set
to zero). There are two required tables, one which factors
in stress from periodic images only and the other which factors
in stress from both the primary and period images.

To create the needed stress tables, execute the stesstablegen
utility twice from the main <ParadisDir> directory using the
following command lines:

bin/stresstablegen -nopbc -outfile inputs/Rijm.cube.out
and
bin/stresstablegen -pbc -outfile inputs/RijmPBC.cube.out

The locations of these files are specified in the control
parameter file via the <Rijmfile> and <RijmPBCfile> parameters
respectively.

---------------------------------------------------------------------

== Tools ==

=== genPovrayFrames ===

The genPovrayFrames tool is provided to post-process the
povray data files generated by ParaDiS when the <povray>
control parameter toggle has been set. This tool will
create an '*.pov' file containing the ParaDiS generated
data embedded in a proper framework of povray settings
and commands. The tool is located in the <ParadisDir>/tools
directory. For details on the use of this tool, see
the comments at the beginning of the script or execute:

<ParadisDir/tools/genPovrayFrames -help

=== gnuplot2povray ===

The gnuplot2povray tool is provided to post-process the
gnuplot data files generated by ParaDiS when the <gnuplot>
control parameter toggle has been set. This tool will
convert the data in the gnuplot files into a format
suitable for povray, and create an '*.pov' file containing
the converted data embedded in a proper framework of povray
settings and commands. The tool is located in the
<ParadisDir>/tools directory. For details on the use of
this tool, see the comments at the beginning of the script
or execute:

<ParadisDir/tools/gnuplot2povray -help

=== stitch ===

When ParaDiS is configured to enable parallel I/O
(i.e. the <numIOGroups> control parameter is greater
than 1), each of the following types of output
will be generated as a set of files rather than a
single output file.

: gnuplot files
: tecplot files
: segment/arm data
: povray files
: velocity data
: terascale browser files
: pole figures

Each file 'segment' will contain a portion of the full
data and will have a sequence number appended to the file
name.

Most utilities for processing these types of output, however,
expect the data in a single file, so the 'stitch' tool
has been provided in order to recombine these data file
segments into a single usable file as a post-processing
step. The tool can be found in the source release as:

: <ParadisDir>/tools/stitch

The command line for 'stitch is as follows:

stitch [-h] [-d dir | -f file]

where
<pre>
-h prints the usage information to stdout

-d <dir> specifies a directory the utility will
scan for any segmented output files that
need to be stitched together.

-f <file> specifies a base file name and the utility will
scan for the corresponding file segments (files
named <file>.N where N ranges from zero on up)
and stitch the segments into the single specified
base file name.
</pre>

NOTE: If neither a directory nor file name was provided
on the command line, the tool will behave as though
the caller specified the current directory on the command
line and perform as stated above.

== Appendix 1. Control Parameters ==

The following is a brief description of the valid control
file parameters. Also see the example control files contained
within the <ParadisDir>/tests directory.

The parameters have been grouped into the following categories, and
unless otherwise specified, units are in SI, and lengths are
normalized by burgers vector magnitude:

* Simulation cell and processor setup
* Simulation time and timestepping controls
* Discretization controls
* FMM controls
* Tables for non-FMM far-field forces
* Loading condition parameters
* Material and mobility parameters
* Velocity statistics and controls
* I/O controls and parameters
* Miscellaneous parameters

=== Simulation cell and processor setup: ===

{|class="wikitable" border="1" align="center"
|+ Table A1. Control parameters for simulation setup
! Parameter
! Type
! Description
|-
|align="center"| numXdoms, numYdoms, numZdoms ||align="center"| integer ||align="left"|
Defines the number of computational domains into which the problem space is partitioned in the corresponding dimensions.
|-
|align="center"| numXcells, numYcells, numZcells ||align="center"| integer ||align="left"|
Defines the number of cells in the corresponding dimension of the problem space. Cells are independent of the domain geometry and are used to determine boundaries at which far-field forces are computed rather than direct segment to segment forces.
|-
|align="center"| xBoundType, yBoundType, zBoundType ||align="center"| integer ||align="left"|
Defines the type of problem space boundaries in the corresponding dimension. Currently supported types are 0, and 1 for periodic and free surfaces respectively.
|-
|align="center"| xBoundMax, yBoundMax, zBoundMax ||align="center"| double ||align="left"|
If periodic boundaries are not enabled, defines the upper limit on coordinates of any dislocation nodes in the corresponding dimension. Value must be <= the respective maximum problem space coordinate specified in the nodal data file.
|-
|align="center"| xBoundMin, yBoundMin, zBoundMin ||align="center"| double ||align="left"|
If periodic boundaries are not enabled, defines the lower limit on coordinates of any dislocation nodes in the corresponding dimension. Value must be >= the respective minimum problem space coordinate specified in the nodal data file.
|-
|align="center"| decompType ||align="center"| Integer ||align="left"|
Specifies the type of domain decomposition to be used for a run. A value of one selects the old Recursive Sectioning (RS) algorithm, a value of 2 selects the Recursive Bisectioning (RB) decomposition algorithm. The default is currently the RS decomposition.
|-
|align="center"| DLBfreq ||align="center"| Integer ||align="left"|
Indicates the frequency (in cycles) at which Dynamic Load-Balancing is to be attempted. A value of zero indicates no load-balancing is to be done. Default is 3.
|}

=== Simulation time and timestepping controls ===

{|class="wikitable" border="1" align="center"
|+ Table A2. Time Control parameters
! Parameter
! Type
! Description
|-
|align="center"| cycleStart ||align="center"| integer ||align="left"|
Starting cycle number for the simulation.
|-
|align="center"| maxstep ||align="center"| integer ||align="left"|
Indicates the number of timesteps to execute before terminating.
|-
|align="center"| timeNow ||align="center"| double ||align="left"|
Current simulation time (in seconds).
|-
|align="center"| timeStart ||align="center"| double ||align="left"|
Initial simulation time (in seconds).
|-
|align="center"| timestepIntegrator ||align="center"| string ||align="left"|
Selects a timestep integration method. Valid methods are "trapezoid" and "forward-euler". The default value is "trapezoid".
|-
|align="center"| deltaTT ||align="center"| double ||align="left"|
Specifies the duration of the previous timestep in units of seconds.
|-
|align="center"| maxDT ||align="center"| double ||align="left"|
Specifies the maximum timestep permitted. Default is 1.0e-07.
|-
|align="center"| nextDT ||align="center"| double ||align="left"|
Specifies the timestep duration to attempt on the next cycle. The timestep integrator will adjust this value dynamically. Default is <maxDT>.
|-
|align="center"| dtDecrementFact ||align="center"| double ||align="left"|
Factor by which <delatTT> is mutiplied when cutting the timestep duration down. Must be between 0.0 and 1.0. Currently only used with the "trapezoid" integrator. Default is 0.5.
|-
|align="center"| dtExponent ||align="center"| double ||align="left"|
Exponent used in calculation of timestep increment when <dtVariableAdjustment> toggle is enabled. Currently used only with "trapezoid" timestep integrator.
|-
|align="center"| dtIncrementFact ||align="center"| double ||align="left"|
Maximum factor by which <deltaTT> is multiplied when incrementing the timestep. Must be at least 1.0. Default is 1.2.
|-
|align="center"| dtVariableAdjustment ||align="center"| integer ||align="left"|
Toggles ability to vary the increment by which the timestep is adjusted when the current timestep is determined to be too small. This will permit the timestep to be adjusted to a value between 1.0 and <dtIncrementFact> * <deltaTT>. Toggle is zero (off) by default. Used only with "trapezoid" integrator.
|-
|align="center"| rTol ||align="center"| double ||align="left"|
Maximum position error (in units of b) tolerated in the timestep integration. Only applies to the "trapezoid" integrator. Default is 0.25 * <rc>. The annihilation
distance is related to rTol(By default, it is set to 2*<rTol>= 0.5 * <rc>.)
|-
|align="center"| rmax ||align="center"| double ||align="left"|
Maximum distance (in units of b) a node is permitted to move in a single timestep. Not used if "trapezoid" timestep integrator used. Default is 0.5 * <minSeg>.
|}

=== Discretization controls: ===

{|class="wikitable" border="1" align="center"
|+ Table A3. Discretization control parameters
! Parameter
! Type
! Description
|-
|align="center"| maxSeg ||align="center"| double ||align="left"|
Sets the maximum permitted length (in units of b) of a dislocation segment. Primarily used for determining when segments are to be rediscretized during remesh operations. This value must be less than 9/10 the size of a cell. There is no default value, and must be specified in the control file.
|-
|align="center"| minSeg ||align="center"| double ||align="left"|
Sets the minimum desired length (in units of b) of a dislocation segment. Primarily used for determining when nodes are to be removed during remesh operations. Default is: sqrt(remeshAreaMin*(4/sqrt(3))) where remeshAreaMin = 2*rTol*maxSeg
|-
|align="center"| remeshRule ||align="center"| integer ||align="left"|
Specifies by number the set of rules governing rediscretization of dislocations. Currently the only supported remesh modules are versions 2 and 3. Default is 2. (See section on Rediscretization for details on remesh versions.)
|}

=== FMM controls ===

{|class="wikitable" border="0" align="center"
|+ Table A4. FMM control parameters
! Parameter
! Type
! Description
|-
|align="center"| fmEnabled ||align="center"| integer ||align="left"|
Toggle controlling use of a Fast Multipole Method (FMM) for computing force contributions from remote dislocation segments. A value of zero disables the use of FMM, any other value enables FMM. Default value is zero.
|-
|align="center"| fmCorrectionTbl ||align="center"| string ||align="left"|
Name of the image correction table used by the FMM. This correction table must correspond to the specified <fmMPOrder>, <fmTaylorOrder> and <shearModulus>(?) control parameters. See the [[#Creating the FMM Image Correction Table with 'ctablegen'|'ctablegen' utility]] for information on creating these tables. This value is ignored if <fmEnabled> is zero.
|-
|align="center"| fmMPOrder ||align="center"| integer ||align="left"|
Defines the multipole expansion order used by the FMM. This value is ignored if <fmEnabled> is zero. Default is 2.
|-
|align="center"| fmTaylorOrder ||align="center"| integer ||align="left"|
Defines the order of taylor expansions used by the FMM. This values is ignored if <fmEnabled> is zero. Default is 4.
|}

{|class="wikitable" border="0" align="center"
|+ Table A5. Table for non-FMM far-field forces
! Parameter
! Type
! Description
|-
|align="center"| Rijmfile ||align="center"| string ||align="left"|
Name of file containing the RIJM table to be used for far-field stress calculations. This parameter is ignored if the <fmEnabled> parameter is non-zero. Default is "inputs/Rijm.cube.out".
|-
|align="center"| RijmPBCfile ||align="center"| string ||align="left"|
Name of file containing the RIJM table to be used for far-field stress calculations with periodic boundary conditions. This parameter is ignored if the <fmEnabled> parameter is non-zero. Default is "inputs/RijmPBC.cube.out".
|}

=== Loading condition parameters: ===

{|class="wikitable" border="1" align="center"
|+ Table A6. Loading condition parameters
! Parameter
! Type
! Description
|-
|align="center"| loadType ||align="center"| integer ||align="left"|
Defines the type of load on the system. Valid types are:
<ol start="0">
<li> Creep test </li>
<li> Constant strain rate test </li>
<li> Displacement-controlled test </li>
<li> Load-controlled, load vs. time curve </li>
<li> Cyclic loading condition </li>
</ol>
|-
|align="center"| appliedStress ||align="center"| double[6] ||align="left"|
Defines the type of load on the system. Valid types are:
External stress specified in units of Pa as [sigma11, sigma22, sigma33, sigma23, sigma31, sigma12] when <loadType> == 0. Default is [0.0, 0.0, 0.0, 0.0, 0.0, 0.0].
|-
|align="center"| eRate ||align="center"| double ||align="left"|
Strain rate. Applicable only when <loadType> == 1. Default is 1.0/sec.
|-
|align="center"| indxErate ||align="center"| integer ||align="left"|
Index to indicate normal or shear deformation. Used only when <loadType> == 1. Valid values are:
# normal
# shear
If not specified, defaults to 1.
|-
|align="center"| edotdir ||align="center"| double[3] ||align="left"|
Uniaxial loading direction accompanying <eRate>. Default is [1.0 0.0 0.0].
|-
|align="center"| cTimeOld ||align="center"| integer ||align="left"|
Timestep related to cyclic loading. Only used when <loadType> == 4.
|-
|align="center"| dCyclicStrain ||align="center"| double ||align="left"|
Incremental strain under cyclic load. Only used when <loadType> == 4.
|-
|align="center"| netCyclicStrain ||align="center"| double ||align="left"|
Net accumulated strain under cyclic load. Only used when <loadType> == 4.
|-
|align="center"| numLoadCycle ||align="center"| integer ||align="left"|
Number of cyclic cycles. Only used when <loadType> == 4.
|-
|align="center"| eAmp ||align="center"| double ||align="left"|
Strain amplitude. Only used when <loadType> == 4.
|}

=== Material and mobility parameters: ===

Note: Default values for all material and mobility related
parameters correspond to Tantalum at a temperature of
600 degress K and pressure of 0 GPa.

{|class="wikitable" border="1" align="center"
|+ Table A7. Table for material and mobility parameters
! Parameter
! Type
! Description
|-
|align="center"| mobilityLaw ||align="center"| string ||align="left"|
Specifies by name the set of rules governing dislocation motion for the simulation conditions. Default is "BCC_0".
|-
|align="center"| shearModulus ||align="center"| double ||align="left"|
Shear modulus in units of Pa. Default is 6.488424e+10
|-
|align="center"| pois ||align="center"| double ||align="left"|
Poisson ratio. Default is 3.327533e-01
|-
|align="center"| burgMag ||align="center"| double ||align="left"|
Magnitude of the burgers vector (b) in units of meters. Default is 2.875401e-10
|-
|align="center"| YoungModulus ||align="center"| double ||align="left"|
Young's modulus (in units of Pa). calculated from E = 2G(1+pois). Default is 200.0e+09.
|-
|align="center"| rc ||align="center"| double ||align="left"|
Core radius (in units of b) for self-force calculations. No default value; must be specified in control file.
|-
|align="center"| Ecore ||align="center"| double ||align="left"|
Core energy used for self-force calculation. Default is (<shearModulus>/(4*PI)) * log(<rc>/0.1)
|-
|align="center"| MobScrew ||align="center"| double ||align="left"|
Mobility of screw dislocations in units of 1/(Pa*sec). Default is 10.0.
|-
|align="center"| MobEdge ||align="center"| double ||align="left"|
Mobility of edge dislocations in units of 1/(Pa*sec). Default is 10.0.
|-
|align="center"| MobClimb ||align="center"| double ||align="left"|
Climb mobility of dislocations in units of 1/(Pa*sec). Default is 1.0e-02.
|-
|align="center"| sessileburgspec ||align="center"| double[30] ||align="left"|
Array of burgers vectors to be considered sessile. First element of the array contains the number of burgers vectors specified, the remaining elements specify the X, Y, then Z components of each sessile burgers vector. Maximum sessile burgers vectors allowed is 9. No burgers vectors are sessile by default.
|-
|align="center"| sessilelinespec ||align="center"| double[30] ||align="left"|
Array of line directions related to sessileburgspec. First element is ignored, remaining elements specify the X, Y, then Z components of each sessile line. The number of lines is assumed to be the same as the number of sessile burgers vectors.
|}

=== Flux Decomposition: ===

{|class="wikitable" border="1" align="center"
|+ Table A8.
! Parameter
! Type
! Description
|-
|align="center"| totpSpn ||align="center"| double[6] ||align="left"|
Plastic strain tensor
|-
|align="center"| totpStn ||align="center"| double[6] ||align="left"|
Plastic spin tensor
|-
|align="center"| totstraintensor ||align="center"| double[6] ||align="left"|
Strain rate tensor with respect to global coordinate system.
|-
|align="center"| Ltot ||align="center"| double[4][4] ||align="left"|
Decomposed density per burgers vector for screw and three edges (for BCC slip systems only).
|-
|align="center"| fluxtot ||align="center"| double[4][7] ||align="left"|
For each burgers vector (for BCC slip systems only), contains:
<table border = "0" cellpadding = "0" cellspacing = "0">
<tr>
<td align="right"> 1. </td>
<td> flux due to climb </td>
</tr>
<tr>
<td align="right"> 2-4. </td>
<td> flux due to edge components </td>
</tr>
<tr>
<td align="right"> 5-7. </td>
<td> flux due to screw components </td>
</tr>
</table>
|}

=== Velocity statistics: ===

‡ Note: these statistics will only be used if the VEL_STATISTICS pre-processor macro has been defined during compilation.

{|class="wikitable" border="1" align="center"
|+ Table A9.
! Parameter
! Type
! Description
|-
|align="center"| vAverage ||align="center"| double ||align="left"|
Average dislocation velocity.
|-
|align="center"| vStDev ||align="center"| double ||align="left"|
Standard deviation of dislocation velocities.
|}

=== I/O controls and parameters ===

‡ Note: A number of the supported output forms are controlled by
very similar control parameters. The general descriptions below
apply to all I/O control parameters of like names:

<pre>
*freq Sets the frequency (in cycles) at which the associated data
will be written to disk. If the corresponding <*dt> parameter
is greater than 0, this parameter will be ignored.
Default for all such values is 100.

*dt The *dt variables specify the simulation delta time that will
control the frequency at which the associated output will be
written to disk. A positive value is interpreted as a delta
time and will take precedence over any frequency specified by
the corresponding <*freq> value. A value <= zero indicates
write frequency will not be determined by delta times.
Default value is -1.0.

*time Specifies the simulation time at which the associated data
was last written to disk. This value will be automatically
updated during the simulation. If the corresponding <*dt>
parameter is <= 0.0 this parameter will be ignored.

*counter Sequence number of the previously written file of the
corresponding type. Default is 0.
</pre>

{|class="wikitable" border="1" align="center"
|+ Table A10.
! Parameter
! Type
! Description
|-
|align="center"| dirname ||align="center"| string ||align="left"|
Base output directory name.
|-
|align="center"| skipIO ||align="center"| integer ||align="left"|
Toggle for disabling generation of all output types other than timing files. Overrides output-specific toggles if set. Default is 0.
|-
|align="center"| numIOGroups ||align="center"| integer ||align="left"|
Sets the number of groups into which the domains will be separated for doing parallel IO. All files generated in parallel will be created with this number of segments. This value must be at least one and no more than the total number of domains used. default is 1.
|-
|align="center"| armfile ||align="center"| integer ||align="left"|
Toggle enabling/disabling generation of files identifying each unique dislocation segment. Toggle is zero (off) by default.
|-
|align="center"| armfilecounter ||align="center"| integer ||align="left"|
See description of <*counter> above.
|-
|align="center"| armfiledt ||align="center"| double ||align="left"|
See description of <*dt> above.
|-
|align="center"| armfilefreq ||align="center"| integer ||align="left"|
See description of <*freq> above.
|-
|align="center"| armfiletime ||align="center"| double ||align="left"|
See description of <*time> above.
|-
|align="center"| fluxfile ||align="center"| integer ||align="left"|
Toggle enabling/disabling generation of flux decomposition files. Toggle is zero (off) by default.
|-
|align="center"| fluxcounter ||align="center"| integer ||align="left"|
See description of <*counter> above.
|-
|align="center"| fluxdt ||align="center"| double ||align="left"|
See description of <*dt> above.
|-
|align="center"| fluxfreq ||align="center"| integer ||align="left"|
See description of <*freq> above.
|-
|align="center"|fluxtime ||align="center"| double ||align="left"|
See description of <*time> above.
|-
|align="center"| gnuplot ||align="center"| integer ||align="left"|
Toggle enabling/disabling generation of files formatted for use with gnuplot. Toggle is zero (off) by default.
|-
|align="center"| gnuplotcounter ||align="center"| integer ||align="left"|
See description of <*counter> above.
|-
|align="center"| gnuplotdt ||align="center"| double ||align="left"|
See description of <*dt> above.
|-
|align="center"| gnuplotfreq ||align="center"| integer ||align="left"|
See description of <*freq> above.
|-
|align="center"| gnuplottime ||align="center"| double ||align="left"|
See description of <*time> above.
|-
|align="center"| polefigfile ||align="center"| integer ||align="left"|
Toggle enabling/disabling generation of <111> type burgers vector pole figures. Toggle is zero (off) by default.
|-
|align="center"| polefilecounter ||align="center"| integer ||align="left"|
See description of <*counter> above.
|-
|align="center"| polefigdt ||align="center"| double ||align="left"|
See description of <*dt> above.
|-
|align="center"| polefigfreq ||align="center"| integer ||align="left"|
See description of <*freq> above.
|-
|align="center"| polefigtime ||align="center"| double ||align="left"|
See description of <*time> above.
|-
|align="center"| povray ||align="center"| integer ||align="left"|
Toggle enabling/disabling generation of files with nodal data and domain boundaries for use with povray. Toggle is zero (off) by default.
|-
|align="center"| povraycounter ||align="center"| integer ||align="left"|
See description of <*counter> above.
|-
|align="center"| povraydt ||align="center"| double ||align="left"|
See description of <*dt> above.
|-
|align="center"| povrayfreq ||align="center"| integer ||align="left"|
See description of <*freq> above.
|-
|align="center"| povraytime ||align="center"| double ||align="left"|
See description of <*time> above.
|-
|align="center"| psfile ||align="center"| integer ||align="left"|
Toggle enabling/disabling generation of postscript files containing nodal data and domain boundaries. Toggle is zero (off) by default.
|-
|align="center"| psfiledt ||align="center"| double ||align="left"|
See description of <*dt> above.
|-
|align="center"| psfilefreq ||align="center"| integer ||align="left"|
See description of <*freq> above.
|-
|align="center"| psfiletime ||align="center"| double ||align="left"|
See description of <*time> above.
|-
|align="center"| savecn ||align="center"| integer ||align="left"|
Toggle enabling/disabling writing of restart files. Toggle is zero (off) by default.
|-
|align="center"| savecncounter ||align="center"| integer ||align="left"|
See description of <*counter> above.
|-
|align="center"| savecndt ||align="center"| double ||align="left"|
See description of <*dt> above.
|-
|align="center"| savecnfreq ||align="center"| integer ||align="left"|
See description of <*freq> above.
|-
|align="center"| savecntime ||align="center"| double ||align="left"|
See description of <*time> above.
|-
|align="center"| saveprop ||align="center"| integer ||align="left"|
Toggle enabling/disabling writing of various properties files. Toggle is zero (off) by default.
|-
|align="center"| savepropdt ||align="center"| double ||align="left"|
See description of <*dt> above.
|-
|align="center"| savepropfreq ||align="center"| integer ||align="left"|
See description of <*freq> above.
|-
|align="center"| saveproptime ||align="center"| double ||align="left"|
See description of <*time> above.
|-
|align="center"| savetimers ||align="center"| integer ||align="left"|
Toggle enabling/disabling generation of timing data files. Toggle is zero (off) by default.
|-
|align="center"| savetimerscounter ||align="center"| integer ||align="left"|
See description of <*counter> above.
|-
|align="center"| savetimersdt ||align="center"| double ||align="left"|
See description of <*dt> above.
|-
|align="center"| savetimersfreq ||align="center"| integer ||align="left"|
See description of <*freq> above.
|-
|align="center"| savetimerstime ||align="center"| double ||align="left"|
See description of <*time> above.
|-
|align="center"| savedensityspec ||align="center"| integer[3] ||align="left"|
Specifies the granularity of the 3D density field written to the density field file in X, Y and Z dimensions. If any element of this array is zero, this capability is disabled.
|-
|align="center"| tecplot ||align="center"| integer ||align="left"|
Toggle enabling/disabling generation of output files formatted for use with tecplot. Toggle is zero (off) by default.
|-
|align="center"| tecplotcounter ||align="center"| integer ||align="left"|
See description of <*counter> above.
|-
|align="center"| tecplotdt ||align="center"| double ||align="left"|
See description of <*dt> above.
|-
|align="center"| tecplotfreq ||align="center"| integer ||align="left"|
See description of <*freq> above.
|-
|align="center"| tecplottime ||align="center"| double ||align="left"|
See description of <*time> above.
|-
|align="center"| tsbfile ||align="center"| integer ||align="left"|
Toggle enabling/disabling generation of output files formatted for use with the TeraScale Browser. Toggle is zero (off) by default.
|-
|align="center"| writetsbspec ||align="center"| integer[3] ||align="left"|
TBD
|-
|align="center"| tsbfilecounter ||align="center"| integer ||align="left"|
See description of <*counter> above.
|-
|align="center"| tsbfiledt ||align="center"| double ||align="left"|
See description of <*dt> above.
|-
|align="center"| tsbfilefreq ||align="center"| integer ||align="left"|
See description of <*freq> above.
|-
|align="center"| tsbfiletime ||align="center"| double ||align="left"|
See description of <*time> above.
|-
|align="center"| velfile ||align="center"| integer ||align="left"|
Toggle enabling/disabling generation of output files containing velocity data for all nodes in the simulation. Toggle is zero (off) by default.
|-
|align="center"| velfilecounter ||align="center"| integer ||align="left"|
See description of <*counter> above.
|-
|align="center"| velfiledt ||align="center"| double ||align="left"|
See description of <*dt> above.
|-
|align="center"| velfilefreq ||align="center"| integer ||align="left"|
See description of <*freq> above.
|-
|align="center"| velfiletime ||align="center"| double ||align="left"|
See description of <*time> above.
|-
|align="center"| winDefaultsFile ||align="center"| string ||align="left"|
Name of file containing default options and attributes for the X-window display. This is ignore if the X display support was not enabled at compile time. Defaults to "./inputs/paradis.xdefaults".
|}

=== Miscellaneous parameters ===

{|class="wikitable" border="1" align="center"
|+ Table A11.
! Parameter
! Type
! Description
|-
|align="center"| elasticinteraction ||align="center"| integer ||align="left"|
Toggles between explicit calculation of elastic interaction and simple line tension calculations. Toggle is one (on) by default.
|-
|align="center"| TensionFactor ||align="center"| double ||align="left"|
Factor used for simple line tension force calculations when the <elasticinteraction> parameter is zero. Default is 1.0.
|}

=== Under development ===

{|class="wikitable" border="1" align="center"
|+ Table A12.
! Parameter
! Type
! Description
|-
|align="center"| TempK ||align="center"| double ||align="left"|
Simulation temperature (in Kelvin). For use in FCC cross-slip.
|-
|align="center"| enforceGlidePlanes ||align="center"| integer ||align="left"|
If non-zero, forces remesh, collision handling, etc. to use glide-plane constraints. Default is zero.
|-
|align="center"| springConst ||align="center"| double ||align="left"|
For use with FCC_0 mobility
|-
|align="center"| mob_compute_escaig ||align="center"| integer ||align="left"|
TBD
|-
|align="center"| mob_cross_slip ||align="center"| integer ||align="left"|
TBD
|}

Overview of ParaDiS 2.2

2011-12-05T04:51:29Z

Iryu: /* Simulation time and timestepping controls */

This document is taken from ParaDiSInfo.txt in ParaDiS.v2.2 distribution. Written by Gregg Hommes, LLNL.

== Introduction ==

The Parallel Dislocation Simulator (ParaDiS) was written
and developed at LLNL by a team of physicists and computer
scientists. ParaDiS is a code for doing Dislocation Dynamics
simulations and was specifically written to perform well on
massively parallel computers. The computational approach to
Dislocation Dynamics used in ParaDiS is fairly simple. In
it, one introduces dislocation lines into the computational
volume and lets them interact and move in response to the
forces imposed by external stress and inter-dislocation
interactions.

---------------------------------------------------------------------

== Building ParaDiS ==

=== Directory Structure ===

The ParaDiS release consists of a file which, when unzipped
and untarred creates a primary directory and a structure
of subdirectories. For convenience, this primary directory
will hereafter be referred to as <ParadisDir>. The directory
structure of the release will look like:

<TABLE CELLPADDING=3 >
<TR valign="top">
<TD ALIGN="LEFT">     </TD>
<TD ALIGN="LEFT"><ParadisDir>/</TD>
<TD ALIGN="LEFT">     </TD>
<TD ALIGN="LEFT">Contains primary 'make' files for controlling build of all executables</TD>
</TR>
<TR valign="top">
<TD ALIGN="LEFT">     </TD>
<TD ALIGN="LEFT"><ParadisDir>/bin/</TD>
<TD ALIGN="LEFT">     </TD>
<TD ALIGN="LEFT">This directory will be created during the 'make' process. All executables will be placed in this directory during compilation</TD>
</TR>
<TR valign="top">
<TD ALIGN="LEFT">     </TD>
<TD ALIGN="LEFT"><ParadisDir>/docs/</TD>
<TD ALIGN="LEFT">     </TD>
<TD ALIGN="LEFT">Contains any additional documentation</TD>
</TR>
<TR valign="top">
<TD ALIGN="LEFT">     </TD>
<TD ALIGN="LEFT"><ParadisDir>/include/</TD>
<TD ALIGN="LEFT">     </TD>
<TD ALIGN="LEFT">Contains all C and C++ header files</TD>
</TR>
<TR valign="top">
<TD ALIGN="LEFT">     </TD>
<TD ALIGN="LEFT"><ParadisDir>/inputs/</TD>
<TD ALIGN="LEFT">     </TD>
<TD ALIGN="LEFT">FMM and non-FMM correction tables, X-display defaults file, gnuplot command file, etc.</TD>
</TR>
<TR valign="top">
<TD ALIGN="LEFT">     </TD>
<TD ALIGN="LEFT"><ParadisDir>/materials/</TD>
<TD ALIGN="LEFT">     </TD>
<TD ALIGN="LEFT">Sample files containing material specific tables and constants</TD>
</TR>
<TR valign="top">
<TD ALIGN="LEFT">     </TD>
<TD ALIGN="LEFT"><ParadisDir>/src/</TD>
<TD ALIGN="LEFT">     </TD>
<TD ALIGN="LEFT">All C and C++ source code modules related to the paradis executable</TD>
</TR>
<TR valign="top">
<TD ALIGN="LEFT">     </TD>
<TD ALIGN="LEFT"><ParadisDir>/tools/</TD>
<TD ALIGN="LEFT">     </TD>
<TD ALIGN="LEFT">Miscellaneous support scripts</TD>
</TR>
<TR valign="top">
<TD ALIGN="LEFT">     </TD>
<TD ALIGN="LEFT"><ParadisDir>/utilities/</TD>
<TD ALIGN="LEFT">     </TD>
<TD ALIGN="LEFT">Source code modules pertaining to the various support tools</TD>
</TR>
</TABLE>

=== Compiling ===

The current ParaDiS 'make' files support compilation for
a number of pre-defined system types that are defined in
the file 'makefile.sys'. In order to compile the code on
one of these pre-defined system types, simply edit
'makefile.setup' and set the "SYS=..." value to the
desired system type. For other system types, add a new
system type into 'makefile.sys' following the format used
for the existing systems and, as above, set the "SYS=..."
value in 'makefile.setup'.

Executing 'gmake' with no options in <ParadisDir> will
build the following executables:

<TABLE CELLPADDING=3 >
<TR valign="top">
<TD ALIGN="LEFT">     </TD>
<TD ALIGN="LEFT"><ParadisDir>/bin/paradis</TD>
<TD ALIGN="LEFT">     </TD>
<TD ALIGN="LEFT">-- Main parallel application</TD>
</TR>
<TR valign="top">
<TD ALIGN="LEFT">     </TD>
<TD ALIGN="LEFT"><ParadisDir>/bin/paradisgen</TD>
<TD ALIGN="LEFT">     </TD>
<TD ALIGN="LEFT">-- Utility for creating initial dislocation configurations (See [[#Utilities|Utilities]] section for details)</TD>
</TR>
<TR valign="top">
<TD ALIGN="LEFT">     </TD>
<TD ALIGN="LEFT"><ParadisDir>/bin/paradisrepart</TD>
<TD ALIGN="LEFT">     </TD>
<TD ALIGN="LEFT">-- Utility for generating a new domain decomposition for an existing dislocation configuration (See [[#Utilities|Utilities]] section for details)</TD>
</TR>
<TR valign="top">
<TD ALIGN="LEFT">     </TD>
<TD ALIGN="LEFT"><ParadisDir>/bin/paradisconvert</TD>
<TD ALIGN="LEFT">     </TD>
<TD ALIGN="LEFT">-- Utility for converting older format ParaDiS control parameter files to the current format (See [[#Utilities|Utilities]] section for details)</TD>
</TR>
<TR valign="top">
<TD ALIGN="LEFT">     </TD>
<TD ALIGN="LEFT"><ParadisDir>/bin/ctablegen</TD>
<TD ALIGN="LEFT">     </TD>
<TD ALIGN="LEFT">-- Utility for creating image correction tables needed when FMM code is enabled. (See [[#Utilities|Utilities]] section for details)</TD>
</TR>
<TR valign="top">
<TD ALIGN="LEFT">     </TD>
<TD ALIGN="LEFT"><ParadisDir>/bin/ctablegenp</TD>
<TD ALIGN="LEFT">     </TD>
<TD ALIGN="LEFT">-- Parallel version of the ctablegen utility. See above.</TD>
</TR>
<TR valign="top">
<TD ALIGN="LEFT">     </TD>
<TD ALIGN="LEFT"><ParadisDir>/bin/stresstablegen</TD>
<TD ALIGN="LEFT">     </TD>
<TD ALIGN="LEFT">-- Utility for creating tables used in calculating far-field stress if the FMM code is not enabled. (See [[#Utilities|Utilities]] section for details)
</TD>
</TR>
</TABLE>

=== Make files ===

Compilation of the code is done via 'gmake' and depends
on the following 'make' files located in the <ParadisDir>
directory. (See the individual make files for details)

<TABLE CELLPADDING=3 >
<TR valign="top">
<TD ALIGN="LEFT">     </TD>
<TD ALIGN="LEFT">makefile</TD>
<TD ALIGN="LEFT">     </TD>
<TD ALIGN="LEFT">-- This is the primary make file controlling the build of the parallel executable and associated utilities.
</TD>
</TR>
<TR valign="top">
<TD ALIGN="LEFT">     </TD>
<TD ALIGN="LEFT">makefile.sys</TD>
<TD ALIGN="LEFT">     </TD>
<TD ALIGN="LEFT">-- This file contains, for each supported system type, a set of 'make' macros, definitions, compiler selection, library and include file paths, etc.
</TD>
</TR>
<TR valign="top">
<TD ALIGN="LEFT">     </TD>
<TD ALIGN="LEFT">makefile.setup</TD>
<TD ALIGN="LEFT">     </TD>
<TD ALIGN="LEFT">-- Contains numerous 'make' settings and flags that are not system specific, including settings for system type, optimization level, debugging flags, etc.
</TD>
</TR>
</TABLE>

---------------------------------------------------------------------

== Executing ParaDiS ==

=== Command line ===

The ParaDiS command line format is:

paradis [-r <numCycles>] [-d dataFile] <controlFile>

where:

<TABLE CELLPADDING=3 >
<TR valign="top">
<TD ALIGN="LEFT">     </TD>
<TD ALIGN="LEFT"><ctrlFile></TD>
<TD ALIGN="LEFT">     </TD>
<TD ALIGN="LEFT">Specifies the name of the ParaDiS control parameter file
</TD>
</TR>
<TR valign="top">
<TD ALIGN="LEFT">     </TD>
<TD ALIGN="LEFT">-d <dataFile></TD>
<TD ALIGN="LEFT">     </TD>
<TD ALIGN="LEFT">Specifies the base name of the file(s) containing the nodal data for the run. If this file name is not supplied, the code looks for a data file named the same as the control file with the file name suffix (if any) replaced with ".data"
</TD>
</TR>
<TR valign="top">
<TD ALIGN="LEFT">     </TD>
<TD ALIGN="LEFT">-r   <numCycles></TD>
<TD ALIGN="LEFT">     </TD>
<TD ALIGN="LEFT">Causes the code to execute a series of <numCycles> cycles during which no force calculations or dislocation movement will occur. These cycles will be used strictly for load-balancing purposes and will be done before the normal cycles. This can be useful when a simulation is started with a uniform domain decomposition and needs time to converge on an optimal decomposition as would occur when restarting a simulation on a different number of cpus
</TD>
</TR>
</TABLE>

=== Examples ===

For example, the following are all valid execution lines with the
first two being equivalent, the third version using the same control
file as the first two, but explicitly selecting a different nodal
data file.

For example, assuming you had a the control parameter file
'testrun.ctrl' and the two different nodal data files 'testrun.data'
and 'testrun2.data', all of the following command lines formats
are valid. The first two commands are equivalent, the third
uses the same control parameter file as the first two, but
explicitly selects a different nodal data file.

mpirun -np 8 bin/paradis testrun.ctrl
mpirun -np 8 bin/paradis -d testrun.data testrun.ctrl
mpirun -np 8 bin/paradis -d testrun2.data testrun.ctrl

NOTE: The number of processors specified to mpirun (or other
parallel job initiator applicable to the execting system)
must match the number of domains specified in the control
file (i.e. np = numXdoms * numYdoms * numZdoms).

Several small example problems are included with the
ParaDiS release. The control and data files for these
examples are:

<ParadisDir>/tests/frank_read_src.ctrl
<ParadisDir>/tests/frank_read_src.data

<ParadisDir>/tests/form_binaryjunc.ctrl
<ParadisDir>/tests/form_binaryjunc.data

<ParadisDir>/tests/fmm_8cpu.ctrl
<ParadisDir>/tests/fmm_8cpu.data

NOTE: These tests require the following tables used
for calculating the far-field stresses from distant
cells and periodic images of the problem.

<ParadisDir>/inputs/Rijm.cube.out
<ParadisDir>/inputs/RijmPBC.cube.out
<ParadisDir>/inputs/fm-ctab.Ta.600K.0GPa.m2.t5.dat

These file *may* have been provided with the source
code release. If not, see the README file in the
<ParadisDir>/tests directory for instructions on
generating these files.

The 'form_binaryjunc*' files contain a small configuration that
will demonstrate the formation of a binary junction from two
dislocation lines, while the 'frank_read_src*' files contain a
configuration that demonstrates the behaviour of a frank-read
source. Both these examples are single cpu examples. To run
these tests, from the main <ParadisDir> directory execute:

mpirun -np 1 ./bin/paradis ./tests/form_binaryjunc.ctrl
or
mpirun -np 1 ./bin/paradis ./tests/frank_read_src.ctrl

The 'fmm_8cpu*' files are just a general demonstration of the
behavior of a small number of screw dislocations. This is
an 8 processor simulation using the Fast Multipole Method
(FMM) for calculating stress from far-field interactions.

mpirun -np 8 ./bin/paradis ./tests/fmm_8cpu.ctrl

Any output from these runs will be placed into corresponding
subdirectories under the "tests" directory.
---------------------------------------------------------------------

== Inputs ==

=== Input Files ===

A ParaDiS simulation may be started from scratch, or
terminated and then later restarted if the user requested
periodic dumps of restart files. In either case, the initial
or restart data data consists of two files, a control
parameter file and a nodal data file. (See section on
[[#Output|Output]] for details on restart files)

=== Control Parameter File ===

The control parameter file consists of data of the form:

<TABLE>
<TR>
<TD ALIGN="LEFT">     </TD>
<TD ALIGN="LEFT"> </TD>
<TD ALIGN="LEFT">     </TD>
<TD ALIGN="LEFT">
identifier = value
</TD></TR>
<TR>
<TD ALIGN="LEFT">     </TD>
<TD ALIGN="LEFT"> </TD>
<TD ALIGN="LEFT">     </TD>
<TD ALIGN="LEFT">
identifier = [value_list]
</TD></TR>
<TR>
<TD ALIGN="LEFT">     </TD>
<TD ALIGN="LEFT">or</TD>
<TD ALIGN="LEFT">     </TD>
<TD ALIGN="LEFT">
identifier = string
</TD></TR>
</TABLE>

where

<TABLE CELLPADDING=3 >
<TR valign="top">
<TD ALIGN="LEFT">     </TD>
<TD ALIGN="LEFT">identifier</TD>
<TD ALIGN="LEFT">     </TD>
<TD ALIGN="LEFT">is the name of a control parameter
</TD></TR>
<TR valign="top">
<TD ALIGN="LEFT">     </TD>
<TD ALIGN="LEFT">value</TD>
<TD ALIGN="LEFT">     </TD>
<TD ALIGN="LEFT">is a numeric value associated with the parameter specified by <identifier>
</TD></TR>
<TR valign="top">
<TD ALIGN="LEFT">     </TD>
<TD ALIGN="LEFT">value_list</TD>
<TD ALIGN="LEFT">     </TD>
<TD ALIGN="LEFT">is a list of numeric values to be associated with the array specified by <identifier>. This values in this list must be delimited by white-space or line-feeds.
</TD></TR>
<TR valign="top">
<TD ALIGN="LEFT">     </TD>
<TD ALIGN="LEFT">string</TD>
<TD ALIGN="LEFT">     </TD>
<TD ALIGN="LEFT">a character string enclosed within either single or double quotes. The string may not contain a line-feed character.
</TD></TR>
</TABLE>

The identifier names are case-insensitive and may be specified
as any mixture of upper and lower case. If the code encounters
an identifier it does not recognize, the identifier and associated
value(s) will be ignore and a warning message displayed.

Any blank lines in the control parameter file will will be
ignored and additionally, any '#' not contained within quotes
is treated as the beginning of a comment and causes the remainder
of the current line to be ignored.

See the [[#Appendix 1. Control Parameters|Appendix]] for a complete list of the recognized control
parameters as well as a brief description of each.

=== Nodal Data File ===

==== Data File Format ====

The nodal data will be contained in 1 or more file
segments, with the information being broken into
three sections (described below). The first section
is the data file parameters, the second section the
domain decomposition, and the third section the nodal
data. The first two sections will be included only
in the first file segment.

==== Data File Segments ====

Given a control parameter file 'restart.cn', the
associated nodal data file(s) would be named:

restart.data[.SEQ]

where
<TABLE CELLPADDING=3 >
<TR valign="top">
<TD ALIGN="LEFT">     </TD>
<TD ALIGN="LEFT">SEQ</TD>
<TD ALIGN="LEFT">     </TD>
<TD ALIGN="LEFT">is a sequence number included only when the nodal data was written in parallel (i.e. the <numIOGroups> control parameter was greater than 1). <SEQ> will range from zero to <numIOGroups>-1.
</TD></TR>
</TABLE>

For example, suppose the <numIOGroups> control parameter
was set to 4 during a simulation executed on 16 processors.
If the simulation created a restart file set at termination,
the following files would be generated and could be used
as input to continue the simulation at a later time:

<outputDir>/restart/restart.cn
<outputDir>/restart/restart.data.0
<outputDir>/restart/restart.data.1
<outputDir>/restart/restart.data.2
<outputDir>/restart/restart.data.3

==== Data File Parameters ====

The data file parameters make up the first section of
the nodal data file and are parsed in the same manner
as specified above for the control file parameters.
These parameters must preceed the other two types of
information in the nodal data file. NOTE: The values
of these parameters are updated within the ParaDiS
code as necessary and should not be changed by the user.

The recognized data file parameters are:

: dataFileVersion
: numFileSegments
: minCoordinates
: maxCoordinates
: nodeCount
: dataDecompType
: dataDecompGeometry

==== Domain Decomposition ====

TBD

==== Nodal Data ====
The raw nodal data comprises the third section
of the nodal data file. For each node, there will
be a single line of node specific data followed by
several lines of segment specific data for each
segment associated with the node. The nodal data
consists of:

: node_tag x_coord y_coord z_coord num_arms constraint

The segment specific data consists of:

: nbr_tag burg_x burg_y, burg_z
: norm_x norm_y norm_z

where
<TABLE CELLPADDING=3 >
<TR valign="top">
<TD ALIGN="LEFT">     </TD>
<TD ALIGN="LEFT">*_tag</TD>
<TD ALIGN="LEFT">     </TD>
<TD ALIGN="LEFT">is a comma delimited pair of numbers uniquely identifying a node. The first number is the ID of the domain owning the node, the second is the index number of the node within the owning domain.
</TD></TR>
<TR valign="bottom">
<TD ALIGN="LEFT">     </TD>
<TD ALIGN="LEFT">x_coord, y_coord, z_coord</TD>
<TD ALIGN="LEFT">     </TD>
<TD ALIGN="LEFT">coordinates of the node
</TD></TR>
<TR valign="top">
<TD ALIGN="LEFT">     </TD>
<TD ALIGN="LEFT">num_arms</TD>
<TD ALIGN="LEFT">     </TD>
<TD ALIGN="LEFT">Number of segments associated with the node
</TD></TR>
<TR valign="top">
<TD ALIGN="LEFT">     </TD>
<TD ALIGN="LEFT">constraint</TD>
<TD ALIGN="LEFT">     </TD>
<TD ALIGN="LEFT">Integer value indicating any constraints placed on the node (i.e. a constraint of 7 implies a node fixed in place and unmovable)
</TD></TR>
</TABLE>

---------------------------------------------------------------------

== Cell and Domain Structure ==

The ParaDiS code is used to simulate cubic systems which
are simultaneously partitioned into a uniform mesh of
cubic 'cells' and spatially decomposed into 'domains'.

The cellular structure is defined by the <nXcells>, <nYcells>
and <nZcells> control parameters, and is used to determine
the cut-off distance between direct segment to segment
dislocation interactions and remote (or far-field) interactions.
In particular, for a given dislocation segment, the interaction
between the segment and any other segments in the same cell
or any of the immediately neighboring 26 cells are calculated
directly. Interactions with all segments outside that range
are calculated via a hierarchical Fast Multipole Method or
by lumping all segments in the remote cell into a
'super-dislocation' where the group of remote dislocations
are represented as an expansion of dislocation multipoles.
(See [[#Far-Field Dislocation Interactions|section on Far-Field Forces]] for details)

The type of spatial decomposition used for the simulation is
selected by the <decompType> control parameter, along with
the <nXdoms>, <nYdoms> and <nZdoms> parameters defining
the number of spatial domains in each dimension. Each 'domain'
is assigned to a single task (processor) within the simulation.
(See [[#Domain Decomposition 2|section on Domain Decomposition]] for details on the
supported types of spatial decomposition)

---------------------------------------------------------------------

== Domain Decomposition ==

=== Selecting a Domain Decomposition Method ===

ParaDiS simulations are spatially decomposed into a number of
domains equal to the number of processors on which the simulation
is being executed. The code curently supports two types of
domain decomposition and is selected via the <decompType>
control parameter. The type 1 decomposition is a Recursive
Sectioning decomposition which is the default if no decomposition
type is explicitly requested. The type 2 is a Recursive
Bisection decomposition. (See descriptions of decomposition
algorithms below.)

Since the ParaDiS simulations tend to grow in size and are
spatially heterogeneous, it is preferable to dynamically
recalculate the domain decomposition at intervals during the
simulation in order to rebalance the workload more efficiently.
The frequency with which the domain decomposition will be
recomputed is specified by the <DLBfreq> control parameter.

The domain decomposition will be included in the restart files.
If the simulation is restarted and the <decompType> control
parameter selects a decomposition type *other* than the
decomposition that was used to generate the restart file, the
old domain decomposition from the restart file will be ignored
and a new domain decomposition of the selected type will be used.

Additionally, if a simulation is restarted with a different number
of domains or a different domain geometry that that which was used
to create the restart file, the domain decomposition from the
restart file will be ignored and a new decomposition will be
generated.

Note: When restarting a large simulation (i.e. thousands
of processors) in such a way that the old domain decomposition must
be discarded, it may take some time for the simulation to converge
on an optimal domain decomposition. (The type 1 decomposition is
particularly susceptible to this.) There are two ways to mitigate
this effect. The first is to use the 'paradisrepart' utility, the
second through the use of the "-r" command line option to ParaDiS.
See comments in other sections pertaining to these capabilities.

=== Recursive Sectioning ===

The Recursive Sectioning algorithm performs a domain
decomposition over a 3-timestep period. During the
first timestep, the entire problem space will be
sectioned along the X dimension into <nXdoms> slabs
such that the computational cost of each slab is roughly
equivalent. The next timestep, each slab will be
sectioned alng the Y axis into <nYdoms> columns
such that the computational cost of each column in a
slab is roughly equivalent. On the thrid timestep,
every column will be sectioned along the Z axis
into <nZdoms> chunks such that the computational
cost of each chunk in a column is roughy equivalent.

As stated above, the frequency with which the domain boundaries
will be recalulated is controlled by the <DLBfreq> parameter.
If this parameter is not explicity set, the default frequency
for recalculating this type of domain decomposition is every
third timestep.

NOTE: Due to the fact that this algorithm requires 3
timesteps to complete a new decomposition, the
<DLBfreq> value must be no less than 3.

=== Recursive Bisection ===

WARNING: The implementation of this algorithm requires the
number of domains in each dimension (as specified
by the <nXdoms>, <nYdoms>, and <nZdoms> control
parameters) must be a power of 2.

The Recursive Bisectioning algorithm begins with the entire
cubic problem space and bisects the space in the X, Y and/or
Z dimensions into octants quarters or halves (depending on
the number of domains specified per dimension) such that
computational cost of each subpartition is roughly the same.
The decomposition is then recursively applied to each of the
subpartitions until no further decomposition is necesssary.

As stated above, the frequency with which the domain boundaries
will be recalulated is controlled by the <DLBfreq> parameter.
If this parameter is not explicity set, the default frequency
for recalculating this type of domain decomposition is every
timestep.

---------------------------------------------------------------------

== Dislocation Mobility ==

=== Selecting a Mobility Module ===

One of the crucial aspects of a ParaDiS simulation is the
selection of the set of rules governing the material specific
physics such as glide climb, and cross-slip with respect to
crystallographic constraints. ParaDiS provides multiple sets
of rules or "mobility laws", each implemented in a separate
module, that may be selected via the <mobilityLaw> control
file parameter. The currently support modules are:

: "BCC_0"
: "BCC_0b"

There are additional modules for dealing with FCC type materials
however these are neither fully developed nor supported at this
point. These FCC mobility functions are:

: "FCC_0"
: "FCC_2"

For a list of the control parameters related to the mobility
of dislocations, see the [[#Material and mobility parameters:|"Material and Mobility Parameters" section]] of the Appendix detailing the control file parameters.
Currently the default values of all mobility related parameters
correspond to tantalum at a temperature of 600 K and a
pressure of 0GPa.

=== BCC_0 Mobility: ===

In BCC metals, screw dislocations do not dissociate into partial
dislocations the same way they do in FCC metals, therefore, for
BCC crystals we do not assign glide plane normals to screw
dislocations. Instead, screw dislocations are given the same
mobility in all directions perpendicular to the line. This
isotropic mobility for screws mimics the "pencil-glide" behavior
of dislocations observed in BCC metals at elevated temperatures.
At the same time, the drag coefficient for non-screw segments
will remain anisotropic with respect to glide and climb.

For details on this mobility module, refer to the paper:

:<ParadisDir>/Docs/ParaDiSAlgorithm.pdf

=== BCC_0b Mobility: ===

The BCC_0b mobility module is nearly a duplicate of BCC_0 with
the exception that the movement of discretization nodes along
the dislocation lines has been dampened.

=== TBD ===

=== FCC_0 Mobility: ===

This module attempts to simulate easy glide in FCC systems. The
glide plane is limited to one of the [111] planes, and cross-slip
is not permitted. Also, no crystallographic information is
used in the dislocation core reactions and hence junction formation
can take place even slightly off the zone axis.

Reminder: This mobility module is not fully developed or supported.

=== FCC_2 Mobility: ===

TBD

---------------------------------------------------------------------

== Material Properties ==

=== Specifying Material Properties ===

All material specific properties are set via the control
file parameters. If not specified, defaults will correspond
to tantalum at a temperatue of 300 K and pressure of 0GPa.

See the [[#Material and mobility parameters:|"Material and mobility parameters" section]] of
Appendix 1 for a list of the material related parameters.

---------------------------------------------------------------------

== Far-Field Dislocation Interactions ==

=== Fast Multipole for Far-Field Interactions ===

The FMM algorithm is enabled within the code via the <fmEnabled>
toggle in the control file. The order of the multipole and
Taylor expansions used by the FMM algorithm are set via the
<fmMPOrder> and <fmTaylorOrder> control parameters respectively.
As a general rule, the taylor expansion order should be around
twice that of the multipole expansion order. One additional
control parameter [[#FMM controls|<fmCorrectionTbl>]] specifies the name of the
file containing the table used by the FMM code to adjust the
stress calculated by the FMM for multiple periodic images.

It is important to note that the file indicated by <fmCorrectionTbl>
must be built with the same multipole order, Taylor expansion order,
and Poisson value (<pois> control parameter) specified for a
simulation. An appropriate correction table may be generated
via the 'ctablegen' utility (See the section on Utilities for
details on the use of 'ctablegen'), although a correction table
matching the code's default control parameter settings *may* have
been provided in the code release as:

: <ParadisDir>/inputs/fm-ctab.Ta.600k.0GPa.m2.t5.dat

The use of a Fast Multipole Method (FMM) for calculating the
far-field forces is based on formulae for generating and evaluating
multipole expansions and a few translation theorems. A very
general description can be found below, but for details refer
to the following paper included with the source release.

:<ParadisDir>/docs/ParaDiSAlgorithm.pdf

The general FMM algorithm consists of the following steps:

# Construct multipole moments:
#: Each domain (CPU) calculates the contributions of its dislocation segments to the multipole moments of the FMM subcells to which those segments belong, and communicates those contributions to the domain that owns the FMM subcell. Each domain that owns an FMM subcell sums all the contributions for that subcell together. <bf>
# Upward pass:
#: Starting at the lowest layer of the FMM hierarchy, each domain collects and sums the contributions to the multipole moments for each of the FMM subcells it owns from the eight child cells and the calculates the upward pass translation of its multipole moments and communicates the result to the domain owing the subcell's parent, until the top of the hierarchy is reached.
# Transverse translations:
#: The multipole moments from 189 cells that are outside the nearest neighbor distance of the target cell but inside the nearest neaighbor distance of its parent are collected by the domain owning the target cell and their contributions to the Taylor series expansion of the stress filed in target is calculated.
# PBC correction:
#: The domain that owns the FMM cell at the highest level of the FMM hierarchy calculates the Taylor series expansion of the stress state due to periodic images of the system (using [[#FMM controls|table]] specified in the <fmCorrectionTbl> parameter).
# Downward pass:
#: Starting with the highest level of the FMM hierarchy, each domain that owns an FMM subcell sums the contributions from its parent to its Taylor series expansion of the stress from step 3 and then calculates the downward pass translation of the stress for each one of its child cells and sends the results to the domain owning the child subcells until the bottom of the hierarchy is reached.
# Each domain that owns a subcell at the lowest level of the FMM hierarchy communicates the Taylor series expansions of the stress field to the domains intersecting the subcell.

=== Non-FMM Far-Field Interactions ===

The use of the FMM in ParaDiS can be disable by setting the control
parameter <fmEnabled> to 0. When FMM is disabled, ParaDiS requires
additional tables used to factor in the far-field stresses from
distant cells and periodic images of the system. The names of the
files containing the tables are specified via the <Rijmfile> and
<RijmPBCfile> control parameters. These tables can be generated
using the 'stresstablegen' utility (see [[#Creating Far-Field Stress Tables with 'stresstablegen'|Utilities section]] for
details), although copies *may* have been provided in the code
release as:

: <ParadisDir>/inputs/Rijm.cube.out
: <ParadisDir>/inputs/RijmPBC.cube.out

This method essentially lumps all dislocations in a cell into a
'super-dislocation' where the cell's dislocations are represented
as an expansion of the dislocation multipoles. The remote stress
for a segment in a given cell is then calculated from two
components. The first is the sum of the stresses resulting from
expansions from all remote cells (i.e. neither the current cell
nor any of its 26 immediate neighbors) and the stress from all
periodic images of those remote cells. The second component
consists of the stress from only the periodic images of the local
cells (i.e. the current cell and its immediate neighbors).

This method is can be faster for smaller simulations but unlike
the FMM, its performance does not scale well as the size of
a simulation increases in both dislocation density and number
of cells.

---------------------------------------------------------------------

== Discretization (Remesh) ==

=== Selecting a Discretization Method ===

The nature of DD simulations is such that the total length
of dislocation lines can increase several orders of magnitude.
Hence, rediscretization of the dislocations is an absolutely necessary
components of ParaDiS simulations. The goal of the rediscretization
is to optimize the numerical description of the continuous dsilocation
line geometry so that a given level of accuracy is achieved with the
fewest degrees of freedom. For regions of high curvature, an optimal
distribution of nodes will place nodes more closely together than
in regions of lower curvature.

The level of accuracy is tied to the control parameters <maxSeg>
and <minSeg> which define the maximum and minimum segment lengths (in
units of b) respectively. The smaller the maximum segment length, the
higher the accuracy.

A number of rediscretization version have been developed and
tested, although only versions 2 and 3 are currently supported.
The rediscretization version to use can be selected through
the control parameter <remeshRule>.

=== Remesh Version 2 ===

This method achieves rediscrtization through two types of
operations; mesh coarsening and mesh refinement (removing and
adding discretization nodes respectively).

This involved defining both minimum and maximum discretization areas
(A_min and A_max) based on the simulation minimum and maximum
segment lengths <minSeg> and <maxSeg>. Then for each discretization
node (i.e. a node with no more than two associated segments) a
discretization area (A_node) is calculated. This area is defined
as the triangle with vertices at the node and its two neighbors.
When the discretization area associated with a node A_node < A_min
the node is removed (coarsened out). Conversely, if the area
A_node > A_max, the local discretization is refined by bisecting
both segments attached to the node.

For additional information, refer to the following paper included
with the ParaDiS source release:

: <ParadisDir>/docs/ParaDiSAlgorithm.pdf

=== Remesh Version 3 ===

This rediscretization method is identical to type 2 with
the exception that during mesh refinement the inserted
nodes are not placed at the exact center of the segment
being bisected. Instead, the algorithm treats the three
initial nodes as if they were on an arc and places the
new nodes at the center of the segments of the arc.

The rationale behind this is that in simulations using
long segments and/or high stress, a new node added at the
center of a segment in a region of high curvature will
not be optimally placed. This new node may immediately
accelerate quickly toward its optimal position then
decelerate as it nears that position. This behavior
can severly impact the simulatuion timesteps. By placing
the new nodes on an arc, the initial stress on the new
nodes will not be as high, keeping the motion of the node
similar to that of the surrounding nodes. Hence, no
detrimental effects on the timestep.

---------------------------------------------------------------------

== Simulation Timestepping ==

=== Timestep Controls ===

Two timestepping algorithms are provided in the ParaDiS code.
The <timestepIntegrator> control parameter is used to select
the desired algorithm. The currently supported algorithms
are:

: "trapezoid"
: "forward-euler"

The default timestep integrator is the "trapezoid" integrator.
There are several general control parameters used in conjunction
with any selected timestep intergrator, and several that are unique
to specific integrators. The general control parameters are
<deltaTT> which specifies the duration of the previous timestep,
<nextDT> which indicates the desired timestep to attempt the next
timestep, and <maxDT> which specifies the maximum timestep duration
permitted.

=== Timestep Integrators ===

==== Trapezoid ====

This implicit integrator is a mix of the Euler-Forward and
Euler-Backward methods. This method is unconditionally
stable, but requires an iterative process that may involve
multiple nodal force and velocity calculations. The
additional expense of the multiple calculations, however,
is usually offset by the gains from the larger timesteps
compared to explicit methods such as the forward euler
integrator.

The algorithm uses the current nodal velocities to reposition
each node, then recalculates forces and velocities for the
nodes at their new positions. A positioning 'error' is
calculated for each node based on the current and previous
nodal position and velocity. If the positioning error of
any node is greater than the maximum permitted positioning
error as defined by the <rTol> control parameter, the
timestep will be decremented by a factor specified in the
<dtDecrementFact> control parameter and the process starts
again. On the otehr hand, if the positioning error of all
nodes is within the tolerance, the timestep is accepted
and the current timestep is multipled by the factor in the
<dtIncrementFactor> to be used as the initial timestep to
attempt the next cycle.

==== Forward Euler ====

The forward euler timestep integrator is relatively simple
and inexpensive in that it requires only a single calculation
of nodal force and velocities per timestep. Unfortunately,
the algorithm is subject to the Courant condition for
numerical stability and is limited to relatively small
timesteps. The size of the timestep is controlled by the
ratio between the length of the shortest segment and the
velocity of the fastest moving node. Additionally, the
<rmax> control parameter defines the maximum distance
any node is permitted to move in a single timestep, which
further limits the timestep duration. This 'rmax' distance
should be set such that no dislocation segment crosses
multiple simulation cells in a single timestep.

Note: This timestep integrator is NOT recommended.

---------------------------------------------------------------------

== Visualization ==

=== X-window display ===

ParaDiS provides a simple X-window display capability for
visualization and debugging of small scale simulations as well
as obtaining certain types of nodal data via the display window.

Unlike some of the other visualization capabilities, this one
must be enabled/disabled via the compile time flag "XLIB_MODE"
in the file <ParadisDir>/makefile.setup. The X-window support
is enabled by setting:

: XLIB_MODE = ON

and disabled by:

: XLIB_MODE = OFF

The default behavior is to have the X-window support enabled.

The <winDefaultsFile> control parameter can be used to specify default
visualization options and attributes such as view perspective, colors
and so on. Unless otherwise specified, this control parameter will
point to the following defaults file provided with the source release:

: <ParadisDir>/inputs/paradis.xdefaults

Once the X-window display is initiated, the view can be controlled
through the following single-key commands:

Key Command Description
--- -------------------
<Home> Restores image to default view
<Esc> Terminates X-window display without terminating
the simulation
a Enable/disable aspect ratio changes. When enabled,
the Arrow keys alter the aspect ratio
c Enable/disable slice view of image. When enabled,
Up/Down Arrows control slice position, Left/Right
Arrows control slice thickness.
f Turn display frame on/off
p Pause/restart simulation
r Enable image rotation. When enabled, rotation can
be controlled via the mouse or Arrow keys.
s Enable display scaling. When enabled, the Arrow
keys control scaling size.
t Enable image translation. When enable,
the Arrow keys control translation direction.
<F10> Generate a postscript image of the display window.
File will be called <outputDir>/YshotNNNN where
'NNNN' is a sequence number incremented each time
a dump of the display window is generated and
<outputDir> is the directory specified by the
<dirname> control file parameter.

Additionally, clicking the mouse on a nodal point in the X-window
image will cause the following information to be written to the
terminal device (not the X-window display):

* relative position (x,y) on the X-window display
* node ID (domainID,nodeindex)
* number of segments (arms) associated with the node
* simulation coordinates (x,y,z) of the node

=== Gnuplot ===

ParaDiS is capable of producing output files formatted for use
with the gnuplot visualization package. This capability is
enabled via the <gnuplot> toggle in the control parameter file.
The frequency with which gnuplot files will be generated is
controlled by the settings of the <gnuplotfreq> and <gnuplotdt>
parameters.

When this capability is enabled, the code will periodically
create a set of gnuplot output files in the directory
<outputDir>/gnuplot where <outputDir> is the directory
specified by the <dirname> control file parameter. The
naming convention used for these files is:

: <outputDir>/gnuplot/box.in
: <outputDir>/gnuplot/0tNNNN[.SEQ]

where
<TABLE CELLPADDING=3 >
<TR valign="top">
<TD ALIGN="LEFT">     </TD>
<TD ALIGN="LEFT">NNNN</TD>
<TD ALIGN="LEFT">     </TD>
<TD ALIGN="LEFT">is a sequence number begining at '0001' and incremented each time a gnuplot file set is written.
</TD></TR>
<TR valign="top">
<TD ALIGN="LEFT">     </TD>
<TD ALIGN="LEFT">SEQ</TD>
<TD ALIGN="LEFT">     </TD>
<TD ALIGN="LEFT">is a sequence number included only when gnuplot files are being written in parallel (i.e. the <numIOGroups> control parameter is greater than 1) <SEQ> will range from zero to <numIOGroups>-1.
</TD></TR>
</TABLE>

In addition, at program termination, an extra set of gnuplot
files will be created. This set will be generated regardless
of the specified dump frequency in order to provide an image
of the final configuration. This set will be named with the
slightly different naming convention:

: <outputDir>/gnuplot/gnuplot.final[.SEQ]

The 'box.in' data file will contain data for plotting the boundaries
of the simulation space, while the '0t*' files contain the coordinate
pairs defining each unique dislocation segment.

NOTE: When gnuplot data is being written in parallel
(i.e. <numIOGroups> is larger than 1), the dislocation segment
data is spread over the file segments. These file segments
can be combined into a single file for display in gnuplot
via the <ParadisDir>/tools/stitch tool. (See description of
[[#stitch|'stitch']] tool for details.)

To aid in visualizing the dislocation configuration, a file
containing commands to set some useful gnuplot options has
been provided; This file is located at:

: <ParadisDir>/inputs/gnuplot.cmds

For example, to view the dislocation structure contained in the
gnuplot data file 0t0001 you could start gnuplot interactively
and execute the commands:

gnuplot> load '<ParadisDir>/inputs/gnuplot.defaults'
gnuplot> splot 'box.in' with lines, '0t0001' w lines

A second gnuplot command file has been provided as an example
of displaying a sequence of gnuplot files. This file is
located at:

: <ParadisDir>/inputs/gnuplot.movie

This file has the neccesary commands to plot the sequence
of files beginning with 0t0001 and ending with 0t1000. After
starting gnuplot, simply load this file with:

gnuplot> load '<ParadisDir>/inputs/gnuplot.movie'

This will initiate the plot of the first file, and thereafter,
simply hitting return will cause gnuplot to move to the next
file in the sequence.

For details on using gnuplot, refer to the gnuplot manual or
enter 'help' from the gnuplot interactive prompt.

=== Tecplot ===

ParaDiS is capable of producing output files formatted for use
with the commercial visualization package Tecplot. This
capability is enabled via the <tecplot> toggle in the control
parameter file. The frequency with which tecplot files will
be generated is controlled by the settings of the <tecplotfreq>
and <tecplotdt> parameters.

When this capability is enabled, the code will periodically
create a set of tecplot output files in the directory
<outputDir>/tecplot where <outputDir> is the directory
specified by the <dirname> control file parameter. The
naming convention used for these files is:

: <outputDir>/tecplot/tecdataNNNN[.SEQ]

where
<TABLE CELLPADDING=3 >
<TR valign="top">
<TD ALIGN="LEFT">     </TD>
<TD ALIGN="LEFT">NNNN</TD>
<TD ALIGN="LEFT">     </TD>
<TD ALIGN="LEFT">is a sequence number begining at '0001' and incremented each time a tecplot file set is written.
</TD></TR>
<TR valign="top">
<TD ALIGN="LEFT">     </TD>
<TD ALIGN="LEFT">SEQ</TD>
<TD ALIGN="LEFT">     </TD>
<TD ALIGN="LEFT">is a sequence number included only when tecplot files are being written in parallel (i.e. the <numIOGroups> control parameter is greater than 1) <SEQ> will range from zero to <numIOGroups>-1.
</TD></TR>
</TABLE>

In addition, at program termination, an extra set of tecplot
files will be created. This set will be generated regardless
of the specified dump frequency in order to provide an image
of the final configuration. This set will be named with the
slightly different naming convention:

: <outputDir>/tecplot/tecdata.final[.SEQ]

The generated tecplot output has specific headers to assign the
variables and time frames (zones) and should look something like
this:

...
variables = X,Y,Z,V1,V2,V3,V4,V5,V6,V7,V8
zone i = 54 F=POINT
-4000.0 500.0 6000.0 133.1 612.4 -612.3 0.0000 0.0000 0.0000 1 3
-3866.9 1112.4 5387.7 -133.1 -612.4 612.3 0.0000 0.0000 0.0000 1 3
471.0 -5132.6 11632.3 -1712.7 -48.8 48.9 0.0090 -0.0918 0.0918 2 3
...

The first line defines the variables to reconstruct the dislocation
configuration. X Y and Z specify the nodal coordinates, V1 V2 and
V3 define arm vectors to the neighboring nodes. These 6 variable
are used to represent dislocation segments as combinations of points
and vectors in tecplot. The V4 V5 and V6 represent the nodal velocity
vector, V7 indicates the number of segments associated with the node
and V8 indicates a burgers vector type.

NOTE: When tecplot data is being written in parallel
(i.e. <numIOGroups> is larger than 1), the headers will only be
included in the first file segment with the remainder of the data
spread over the file segments. These file segments can be combined
into a single file for display in tecplot via the
<ParadisDir>/tools/stitch tool. (See description of [[#stitch|'stitch']]
tool for details.)

For details on using tecplot, refer to the tecplot manual or select
the 'Help' menu in tecplot.

=== Povray ===

If the <povray> toggle is set in the control file,
ParaDiS will periodically generate files containing
dislocation segment data formatted for use with the POVRAY
(Persistence of Vision(tm) Ray Tracer) tool. The frequency
with which these files will be generated is controlled by
the settings of the <povrayfreq> and <povraydt> parameters.

Note: These files contain the main data to be processed by
povray, but must be post-processed via the
'genPovrayFrames' tool (See [[#genPovrayFrames|section]] on Tools)
which will create the final povray input file
containing the segment data embedded within a
proper framework of povray settings and commands.

When this capability is enabled, the code will periodically
create a set of files in the directory <outputDir>/povray
where <outputDir> is the directory specified by the <dirname>
control file parameter. The naming convention used for
these files is:

: <outputDir>/povray/povframeNNNN[.SEQ]

where
<TABLE CELLPADDING=3 >
<TR valign="top">
<TD ALIGN="LEFT">     </TD>
<TD ALIGN="LEFT">NNNN</TD>
<TD ALIGN="LEFT">     </TD>
<TD ALIGN="LEFT">is a sequence number begining at '0001' and incremented each time a povray frame file set is written.
</TD></TR>
<TR valign="top">
<TD ALIGN="LEFT">     </TD>
<TD ALIGN="LEFT">SEQ </TD>
<TD ALIGN="LEFT">     </TD>
<TD ALIGN="LEFT">is a sequence number included only when povray files are being written in parallel (i.e. the <numIOGroups> control parameter is greater than 1) <SEQ> will range from zero to <numIOGroups>-1.
</TD></TR>
</TABLE>

In addition, at program termination, an extra set of povray
frame files will be created. This set will be generated
regardless of the specified dump frequency in order to provide
an image of the final configuration. This set will be named
with the slightly different naming convention:

: <outputDir>/povray/povray.final[.SEQ]

NOTE: When povray data is being written in parallel
(i.e. <numIOGroups> is larger than 1), the dislocation segment
data is spread over the file segments. If desired, these file
segments may be combined into a single file for post-processing
via the <ParadisDir>/tools/stitch tool. (See description
of [[#stitch|'stitch']] tool for details.)

As stated above, these files must be post-processed via the
'genPovrayFrames' tool (See [[#genPovrayFrames|section]] on Tools) which will
create the final povray input file containing the segment
data embedded within a proper framework of povray settings
and commands. This tool is capable of dealing with single
or segmented 'povframe*' files.

For details on using povray, refer to the povray manual.

=== Terascale Browser ===

TBD

=== Postscript ===

If the <psfile> toggle is set in the control file,
ParaDiS will periodically generate a postscript file
containing an image of the current state of the system.
The frequency with which the postscript files are
written is determined by the settings of the
<psfilefreq> and <psfiledt> control file parameters.
All files will be located in the directory <outputDir>
where <outputDir> is the directory specified by the
<dirname> control file parameter.

All files will be named with the following convention:

: <outputDir>/YshotNNNN.ps

where NNNN is a sequence number beginning with zero and incremented
each time another postscript file is written.

---------------------------------------------------------------------

== Output ==

=== Restart files ===

Periodic creation of ParaDiS restart files is enabled via
the <savecn> toggle in the control file. The frequency with
which restart files are written is determined by the settings
of the <savecnfreq> and <savecndt> control file parameters.

When enabled, the code will periodically generate restart
file which will be located in the directory <outputDir>/restart
where <outputDir> is the directory specified by the <dirname>
control file parameter.

The naming convention used for these restart files is:

<TABLE CELLPADDING=3 >
<TR valign="top">
<TD ALIGN="LEFT">     </TD>
<TD ALIGN="LEFT"><outputDir>/restart/rsNNNN</TD>
<TD ALIGN="LEFT">     </TD>
<TD ALIGN="LEFT"># control parameter file
</TD></TR>
<TR valign="top">
<TD ALIGN="LEFT">     </TD>
<TD ALIGN="LEFT"><outputDir>/restart/rsNNNN.data[.SEQ]</TD>
<TD ALIGN="LEFT">     </TD>
<TD ALIGN="LEFT"># nodal data file
</TD></TR>
</TABLE>
where
<TABLE CELLPADDING=3 >
<TR valign="top">
<TD ALIGN="LEFT">     </TD>
<TD ALIGN="LEFT">NNNN</TD>
<TD ALIGN="LEFT">     </TD>
<TD ALIGN="LEFT">is a sequence number begining at '0001' and incremented each time a restart file set is written.
</TD></TR>
<TR valign="top">
<TD ALIGN="LEFT">     </TD>
<TD ALIGN="LEFT">SEQ</TD>
<TD ALIGN="LEFT">     </TD>
<TD ALIGN="LEFT">is a sequence number included only when restart files are being written in parallel (i.e. the <numIOGroups> control parameter is greater than 1) <SEQ> will range from zero to <numIOGroups>-1.
</TD></TR>
</TABLE>

Each time a restart file set is written, the name of the
control parameter file will also be written into the file:

: <outputDir>/latest_restart

Additionally, when creation of restart files is enabled, an
additional restart file pair named 'restart.cn' and restart.data'
will be written at program termination even if the cycle is not
a multiple of the <savecnfreq> control parameter.

=== Property Outputs ===

==== Enabling Properties Output ====

The code has the capability to produce files containing
various dislocation properties. This capability is enabled
via the <saveprop> toggle in the control file. The
frequency with which the property data is written is
determined by the settings of the <savepropfreq> and
<savepropdt> control file parameters.

When this capability is enabled, the code will generate
and periodically append the properties data to one or more of
the following files which will be located in the directory
<outputDir>/properties, where <outputDir> is the directory
specified by the <dirname> control file parameter.

==== Property Files ====

===== density =====

Note: burgVolFactor converts from length in units of B, to density
in units of meters

This file contains the following columns of data:

# plastic strain
# strain
# dislocation density
# deleted dislocation density
#: (lost through annihilation, junction formation, etc)
#: (density lost since last dump of data)
# average dislocation velocity‡
# std. deviation of dislocation velocities‡
# density file version number
# dislocation density for segments of specific groupings of burgers vectors (see below)*

‡ These items will be calculated only if
the "VEL_STATISTICS" pre-processor macro was
defined during compilation. Otherwise these
values will be zeroes.

For BCC simulations:
Column Burgers vector types
8 [ 1 1 1] [-1-1-1]
9 [-1 1 1] [ 1-1-1]
10 [ 1-1 1] [-1 1-1]
11 [ 1 1-1] [-1-1 1]
12 [ 1 0 0] [-1 0 0] [ 0 1 0]
[ 0-1 0] [ 0 0 1] [ 0 0-1]

For FCC simulations:
Column Burgers vector types
8 [ 1 1 0] [-1-1 0]
9 [-1 1 0] [ 1-1 0]
10 [ 1 0 1] [-1 0-1]
11 [-1 0 1] [ 1 0-1]
12 [ 0 1 1] [ 0-1-1]
13 [ 0-1 1] [ 0 1-1]
14 all others

===== time_Plastic_strain =====

This file contains the following two columns of data:

# elapsed simulation time
# plastic strain

===== stress_Plastic_strain =====

This file will only be generated if the user specified
a loadType of 1 (constant strain rate) or 4 (cyclic
loading). The file contains the following two columns
of data:

# plastic strain
# stress

===== stress_Total_strain =====

This file will only be generated if the user specified
a loadType of 1 (constant strain rate) or 4 (cyclic
loading). If the user specified a constant strain
rate, this file contains:

# strain
# stress

If the user specified cyclic loading, this file contains:

# net accumulated strain
# stress
# elapsed simulation time
# number of loading cycles

===== alleps =====

This file contains the following 9 columns of data:

{|
|-
| align=right | 1.||simulation timestep number
|-
| align=right | 2.||elapsed simulation time
|-
| align=right | 3-8.||plastic strain components‡
|-
| align=right | 9.||dislocation density
|}

‡ from plastic strain tensor matrix, elements [0][0], [1][1], [2][2], [1][2], [0][1], and [0][2]

===== epsdot =====

This file contains the 2 columns of data:

# elapsed simulation time
# plastic strain rate

=== Flux Decomposition ===

ParaDiS has the capability to produce files containing
flux decomposition information for the simulation.
This capability is enabled via the <fluxfile> control
file toggle. The frequency with which the flux
data is written is determined by the settings of
the <fluxfreq> and <fluxdt> control file parameters.

When this capability is enabled the code will generate
and periodically append the flux data to two sets of
files that will be located in the directory
<outputDir>/fluxdata where <outputDir> is the directory
specified by the <dirname> control file parameter.

Each set contains four files, one file per burgers vector.
Files *b1, *b2, *b3, and *b4 contain statistics for burgers
vector types [111], [-111], [1-11], and [11-1] respectively.

The first set of files (Ltot_b1, Ltot_b2, Ltot_b3 and
Ltot_b4) consist of the following 9 columns of data:

# Plastic strain
# Strain,
# Screw density
# Edgedensity1
# Edgedensity2
# Edgedensity3
# Sum of edge Densities (4+5+6)
# Total system EdgeDensity from all Ltot files
# Total system screw density from all Ltot files

The second set of files (fluxtot_b1, fluxtot_b2, fluxtot_b3 and
fluxtot_b4) consist of the following 9 columns of data:

{|
|-
| align=right | 1.||Plastic Strain
|-
| align=right | 2.||Strain
|-
| align=right | 3.||Flux due to climb motion
|-
| align=right | 4-6.||Flux created by edge components on three planes (See below.)
|-
| align=right | 7-9.||Flux created by screw dislocation on three planes (See below.)
|}

For b1 = 1/2[1 1 1]
<ol start="4">
<li> ( 0 1 -1), [-2 1 1]</li>
<li> (-1 0 1), [ 1 -2 1]</li>
<li> ( 1 -1 0), [ 1 1 -2]</li>
<li> ( 0 1 -1), [-2 1 1]</li>
<li> (-1 0 1), [ 1 -2 1]</li>
<li> ( 1 -1 0), [ 1 1 -2]</li>
</ol>
For b2 = 1/2[-1 1 1]
<ol start="4">
<li> ( 0 1 -1), [ 2 1 1] </li>
<li> ( 1 0 1), [ 1 2 -1] </li>
<li> ( 1 1 0), [ 1 -1 2] </li>
<li> ( 0 1 -1), [ 2 1 1] </li>
<li> ( 1 0 1), [ 1 2 -1] </li>
<li> ( 1 1 0), [ 1 -1 2] </li>
</ol>
For b3 = 1/2[1 -1 1]
<ol start="4">
<li> ( 0 1 1), [ 2 1 -1] </li>
<li> ( 1 0 -1), [ 1 2 1] </li>
<li> ( 1 1 0), [-1 1 2] </li>
<li> ( 0 1 1), [ 2 1 -1] </li>
<li> ( 1 0 -1), [ 1 2 1] </li>
<li> ( 1 1 0), [-1 1 2] </li>
</ol>
For b4 = 1/2[1 1 -1]
<ol start="4">
<li> ( 0 1 1), [ 2 -1 1] </li>
<li> ( 1 0 1), [-1 2 1] </li>
<li> ( 1 -1 0), [ 1 1 2] </li>
<li> ( 0 1 1), [ 2 -1 1] </li>
<li> ( 1 0 1), [-1 2 1] </li>
<li> ( 1 -1 0), [ 1 1 2] </li>
</ol>

=== Pole figures ===

TBD

=== Velocity files ===

If the <velfile> toggle is set in the control file,
ParaDiS will periodically generate a set of files containing
velocity information about each unique dislocation node
in the system. The frequency with which the velocity
data is written is determined by the settings of the
<velfilefreq> and <velfiledt> control file parameters.
All files will be located in the directory <outputDir>/velocity
where <outputDir> is the directory specified by the
<dirname> control file parameter.

All files will be named with the following convention:

: <outputDir>/velocity/velNNNN[.SEQ]

where
<TABLE CELLPADDING=3 >
<TR valign="top">
<TD ALIGN="LEFT">     </TD>
<TD ALIGN="LEFT">NNNN</TD>
<TD ALIGN="LEFT">     </TD>
<TD ALIGN="LEFT">is a sequence number based on the <velfilecounter> control parameter and is incremented each time another velocity file is written.
</TD></TR>
<TR valign="top">
<TD ALIGN="LEFT">     </TD>
<TD ALIGN="LEFT">SEQ </TD>
<TD ALIGN="LEFT">     </TD>
<TD ALIGN="LEFT">is a sequence number included only when velocity data is being written in parallel (i.e. <numIOGroups> control parameter is greater than 1. SEQ will range from zero to <numIOGroups>-1.
</TD></TR>
</TABLE>

In addition, at program termination, an extra set of velocity
files will be created. This set will be generated regardless
of the specified dump frequency in order to provide an image
of the final configuration. This set will be named with the
slightly different naming convention:

: <outputDir>/velocity/vel.final[.SEQ]

NOTE: When velocity data is being written in parallel
the dislocation segment data is spread over the file segments.
These file segments can be combined into a single file via
the <ParadisDir>/tools/stitch tool. (See [[#stitch|section]] on Tools
for details)

The contents of the velocity files consist of 4 columns
of data for each unique dislocation segment. Those
columns are:

{|
|-
| align=right | 1-3.||Velocity components (x,y,z)
|-valign="top"
| align=right | 4.|| +1 if contributing to strain rate <br> -1 if moving in opposite direction
|}

=== Segment files ===

If the <armfile> toggle is set in the control file,
ParaDiS will periodically generate a set of files containing
information about each unique dislocation segment
in the system. The frequency with which the segment
(or arm) files are written is determined by the settings
of the <armfilefreq> and <armfiledt> control file parameters.
All files will be located in the directory <outputDir>/armdata
where <outputDir> is the directory specified by the
<dirname> control file parameter.

All files will be named with the following convention:

: <outputDir>/armdata/armNNNN[.SEQ]

where
<TABLE CELLPADDING=3 >
<TR valign="top">
<TD ALIGN="LEFT">     </TD>
<TD ALIGN="LEFT">NNNN</TD>
<TD ALIGN="LEFT">     </TD>
<TD ALIGN="LEFT">is a sequence number based on the <armfilecounter> control parameter and is incremented each time another arm file is written.
</TD></TR>
<TR valign="top">
<TD ALIGN="LEFT">     </TD>
<TD ALIGN="LEFT">SEQ</TD>
<TD ALIGN="LEFT">     </TD>
<TD ALIGN="LEFT">is a sequence number included only when arm data is being written in parallel (i.e. <numIOGroups> control parameter is greater than 1. SEQ will range from zero to <numIOGroups>-1.
</TD></TR>
</TABLE>

In addition, at program termination, an extra set of arm
files will be created. This set will be generated regardless
of the specified dump frequency in order to provide an image
of the final configuration. This set will be named with the
slightly different naming convention:

: <outputDir>/armdata/arm.final[.SEQ]

NOTE: When arm data is being written in parallel
the dislocation segment data is spread over the file segments.
These file segments can be combined into a single file via
the <ParadisDir>/tools/stitch tool. (See [[#stitch|section]] on Tools
for details)

The contents of the arm files consist of 10 columns
of data for each unique dislocation segment. Those
columns are:

{|
|-
| align=right | 1-3.||Burgers vector components
|-
| align=right | 4-6.||Line direction vector
|-
| align=right | 7.||Segment length
|-
| align=right | 8-10.||Coordinates of node 'owning' the segment
|}

=== Density Field file ===

If all components of the <savedensityspec> control parameter
are set to positive values in the control file, ParaDiS
will (at program termination) create a file containing a
3D dislocation density field formatted for use with the
VASP Data Viewer (vaspview). The three components of
the <savedensityspec> parameter specify the granularity
of the density field in the X, Y and Z dimensions
respectively. The density field will be written to the
file:

: <outputDir>/densityfield.out

Warning: This will overwrite any existing density field
file of the same name!

The VASP Data Viewer is publicly available on the web
for non-commercial use. For details on the product,
download the VASP Data Viewer from the web and refer
to the accompanying documentation.

---------------------------------------------------------------------

== Utilities ==

=== Creating Initial Dislocations with 'paradisgen' ===

The paradisgen utility is capable of generating initial
dislocations suitable for a paradis simulation. The command
line options for paradisgen control the type of dislocations,
number of dislocations, size of the simulation box, and so
on. See "Examples" below for sample executions of this utility.

The command line format for paradisgen is:

paradisgen [-cubel <cubelength>] [-help] [-hexsize <size>] \
[-maxseg <maxseglen] [-nchains <numchains>] \
[-nloops <numloops>] [-outfile <filename> \
[-radius <radius>] [-seed <seedval>] \
[-type <configtype>]

All command line options may be abbreviated to the shortest
non-ambiguous abbreviation of the option. Descriptions of
the command lines options are as follows:

<pre>
-cubel <cubelength> Defines the size of the simulation cube
in units of b. Minimum and maximum problem
space coordinates will be 0.5*cubel and
-0.5*cubel respectively. If not specified
this will default to 35000b (approx.
10 micron).

-help Causes the utility to display the command line
format and option descriptions then terminate.

-hexsize <size> Defines the radius (in units of b) for the
hexagonal interstitial loops. This option is
used only when the selected dislocation type
is 'fcc-irrad'.

-looptype <ltype> Specifies the types of prismatic loops to
generate. If not specified, this value
will default to zero. Valid values are:

0 == mixture of [1 1 1] and [1 0 0] types
1 == all [1 1 1] type loops
2 == all [1 0 0] type loops

This option is only used when the selected
dislocation type is 'prismatic-loop'.

-maxseg <length> Defines the maximum desired segment length
in units of b. Initial dislocations will
be discretized so no segment is longer than
this value. If not specified this value
defaults to 500.

-nchains <numchain> Indicates the number of dislocation lines
to create. This value is ignored when the
selected dislocation type is 'prismatic-loop',
and when the type is 'fcc-perfect-loop',
this value must be a multiple of 12. If
not specified, this value defaults to 2.

-nloops <numloops> Specifies the number of loops to create when
the selected dislocation type is
'prismatic-loop' or 'fcc-irrad'. If not
specified, this value defaults to 1000.

-nsegs <numsegs> Specifies the number of segments into which
a prismatic loop will be discretized. This
option is only used when the selected
dislocation type is 'prismatic-loop'. If
not specified, this value defaults to
(2*PI*radius)/(maxseg/2).

-outfile <filename> Name of the ParaDiS data file to be created.
If not specified, data will be written
into a file called 'paradis.data'.

-radius <radius> Radius (in units of b) of prismatic loops.
This option is only used when the selected
dislocation type is 'prismatic-loop'. If
not specified, this value defaults to maxseg/2.

-seed <seed> Specifies a value to seed the random number
generator. Using the same seed value for
multiple executions of paradis (for which
all other options are identical) insures
creation of an identical configuration.

-type <type> Specifies the type of dislocations to create.
This type can be a name or the integer value
corresponding to the name. Valid types are:

0 or 'screw' BCC screw dislocations.
Assumes periodic boundary
conditions are enabled.
1 or 'finite-mixed' A mixture of BCC screw and
edge dislocations
terminating at the edges
of the cubic problem
space. This should not
be used with periodic
boundary conditions.
2 or 'prismatic-loop' BCC prismatic loops.
Assumes periodic boundary
conditions are enabled.
3 or 'fcc' FCC dislocations. Assumes
periodic boundary
conditions are enabled.
4 or 'fcc-irrad' Mixture of FCC
dislocations and hexagonal
interstitial loops.
Assumes periodic boundary
conditions are enabled.
5 or 'fcc-perfect-loop' Not fully implemented.

Examples:
---------

TBD
</pre>

=== Recomputing Domain Boundaries with 'paradisrepart' ===

The paradisrepart utility provides a mechanism by which to
replace the domain decomposition/partitioning in an
existing nodal data file with a new domain decomposition.
The utility will read the current nodal data, and use the
specified domain/cell geometries to attempt to partition
the domains such that the computational cost for each domain
will be roughly equivalent.

This utility is primarily used when it is necessary alter
the domain geometry or domain count for a simulation in
order to continue. In such a situation, the existing
domain decomposition would be thrown away and the ParaDiS
code would generate an initial uniform decomposition
and then over time converge on a more optimal decomposition.
Using this utility instead to generate a new decomposition
provides a much more reasonable starting point from allowing
the ParaDiS simulation to converge on an optimal decomposition
much more quickly.

The command line format for the paradisrepart utility is:

paradisrepart -infile <inputFile> \
-cells <xcells[,ycells,zcells]> \
-domains <xdoms[,ydoms,zdoms]> \
[-outfile <outputFile>] [-decompType <type>] \
[-help]

All command line arguments and options may be abbreviated to the
shortest non-ambiguous abbreviation of the option. Descriptions
of the command lines options are as follows:

<pre>
-infile <inputFile> Specifies the name of the nodal data file.
On success, the first nodal data file
segment will be copied to <inputFile>.bkup.
This command line argument is not optional.

-cells <xcells[,ycells,zcells]> Specifies the number of
cells in each dimension. If the
number of cells in the Y and Z dimensions
are not provided, they will default to the
same value as <xcells>. This command line
argument is not optional.

-domains <xdoms[,ydoms,zdoms]> Specifies the number of domains
in each dimension. If the number of
domains in the Y and Z dimensions are
not provided, they will default to the
same value as <xdoms>. This command line
argument is not optional.

-decompType <type> Specifies type of domain decomposition:
If not specified, defaults to 1. Valid
types are:

1 == Recursive Sectioning
2 == Recursive Bisectioning

-help Causes the utility to display the command
line format and option descriptions then
terminate.

-outfile <outputFile> Specifies the name of the file into which
to write the new domain decomposition. If
not specified, new domain decomposition
will be written into the file specified
by <inputFile>.

Examples:
---------
</pre>

=== Converting Control and Data File with 'paradisconvert' ===

The paradisconvert utility provides a mechanism by which
older format ParaDiS control and data files (and restart
files) may be converted to the current file formats.
This utility does recognize and handle segmented data files.

In most cases this utility will not be required since
ParaDiS is still able to recognize and handle *most* of
the older file formats. The only format the ParaDiS code
no longer recognizes is the truly ancient format associated
with the earliest incarnations of the code in which the
control file parameters and nodal data were included in
a single file. For these control files, the paradisconvert
utility will be needed.

The command line format for the paradisconvert utility is:

paradisconvert <controlFile> [dataFile]

where:
<TABLE CELLPADDING=3 >
<TR valign="top">
<TD ALIGN="LEFT">     </TD>
<TD ALIGN="LEFT">controlFile</TD>
<TD ALIGN="LEFT">     </TD>
<TD ALIGN="LEFT">Specifies the name of the control parameter file to be updated to the current format.
</TD></TR>
<TR valign="top">
<TD ALIGN="LEFT">     </TD>
<TD ALIGN="LEFT">dataFile</TD>
<TD ALIGN="LEFT">     </TD>
<TD ALIGN="LEFT">If the specified control file is the original ancient format including control parameters and nodal data in the single file, this argument is ignored. Otherwise, this specifies the base name of the nodal data file(s) to be converted. If not this argument is not provided, it will default to the same name as <controlFile> with any file name suffix removed and the '.data' suffix added.
</TD></TR>
</TABLE>

On success, the utility will rename the original files by appending
a '.bkup' suffix to the names, and create new control and data files
with the specified names. Note: for control parameter files which
include nodal data, a new data file will be generated under the
the name as <controlFile> with any file name suffix removed and
a '.data' suffix added.

<u>Examples:</u>

To convert the original format file 'restart.cn' containing
both control parameters and nodal data, execute:

paradisconvert restart.cn

The utility will generate the following files:

: restart.cn.bkup
: restart.cn
: restart.data

To convert a newer control parameter and data file pair with
the names 'rs0100' and 'rs0100.data' respective, execute either
of the following equivalent command lines:

paradisconvert rs0100
paradisconvert rs0100 rs0100.data

In both cases, the utility would generate the files:

: rs0100.bkup
: rs0100.data.bkup

: rs0100
: rs0100.data

To convert a newer control file <rs0100> and a set of segmented
data files with the names <rs0100.data.0>, <rs0100.data.1>, ...
<rs0100.data.7>, execute any of the following equivalent commands:

paradisconvert rs0100
paradisconvert rs0100 rs0100.data
paradisconvert rs0100 rs0100.data.0

In all of the above cases, the utility would generate the files

: rs0100.bkup
: rs0100.data.0.bkup
: rs0100.data.1.bkup
: ...
: rs0100.data.7.bkup

: rs0100
: rs0100.data.0
: rs0100.data.1
: ...
: rs0100.data.7

=== Creating the FMM Image Correction Table with 'ctablegen' ===

The 'ctablegen' utility is used to create an image correction
table needed when the FMM (Fast Multipole Method) has been enabled
by setting the <fmEnabled> toggle on in the control file. Since
the data in this file is dependent on the poisson ratio, shear
modulus, and orders of the multipole and taylor expansions, the
file must be created for the particular values of these items
used in the simulation.

Given the current defaults used by ParaDiS (as set in Param.c):

{|
|      ||align="left"| poisson ratio: ||align="center"| 3.327533e-01
|-
| ||align="left"| shear modulus: ||align="center"| 6.488424e+10
|-
| ||align="left"| multipole order: ||align="center"| 2
|-
| ||align="left"| taylor expansion order: ||align="center"| 5
|}

To create the FMM image correction table, you could execute
ctablegen from the main <ParadisDir> directory using the
following command line:

bin/ctablegen -nu 3.327533e-01 -mu 6.488424e+10 -mporder 2 -torder 5 -outfile \
inputs/fm-ctab.Ta.600K.0GPa.m2.t5.dat

NOTE: The generation of this table can take a significant
amount of time, therefore, a parallel version of the utility
(called ctablegenp) has also been provided. To execute the
table generation in parallel on 8 processors using mpirun as
a parallel program initiator, one could execute:

mpirun -np 8 bin/ctablegen -nu 3.327533e-01 -mu 6.488424e+10 -mporder 2 -torder 5 -outfile \
inputs/fm-ctab.Ta.600K.0GPa.m2.t5.dat

The locations of this file is specified in the control
parameter file via the <fmCorrectionTbl> parameter.

=== Creating Far-Field Stress Tables with 'stresstablegen' ===

The 'stresstablegen' utility is used to create tables needed
for calculating stress from distant cells and periodic images
of the system when FMM is disabled (i.e. <fmEnabled> is set
to zero). There are two required tables, one which factors
in stress from periodic images only and the other which factors
in stress from both the primary and period images.

To create the needed stress tables, execute the stesstablegen
utility twice from the main <ParadisDir> directory using the
following command lines:

bin/stresstablegen -nopbc -outfile inputs/Rijm.cube.out
and
bin/stresstablegen -pbc -outfile inputs/RijmPBC.cube.out

The locations of these files are specified in the control
parameter file via the <Rijmfile> and <RijmPBCfile> parameters
respectively.

---------------------------------------------------------------------

== Tools ==

=== genPovrayFrames ===

The genPovrayFrames tool is provided to post-process the
povray data files generated by ParaDiS when the <povray>
control parameter toggle has been set. This tool will
create an '*.pov' file containing the ParaDiS generated
data embedded in a proper framework of povray settings
and commands. The tool is located in the <ParadisDir>/tools
directory. For details on the use of this tool, see
the comments at the beginning of the script or execute:

<ParadisDir/tools/genPovrayFrames -help

=== gnuplot2povray ===

The gnuplot2povray tool is provided to post-process the
gnuplot data files generated by ParaDiS when the <gnuplot>
control parameter toggle has been set. This tool will
convert the data in the gnuplot files into a format
suitable for povray, and create an '*.pov' file containing
the converted data embedded in a proper framework of povray
settings and commands. The tool is located in the
<ParadisDir>/tools directory. For details on the use of
this tool, see the comments at the beginning of the script
or execute:

<ParadisDir/tools/gnuplot2povray -help

=== stitch ===

When ParaDiS is configured to enable parallel I/O
(i.e. the <numIOGroups> control parameter is greater
than 1), each of the following types of output
will be generated as a set of files rather than a
single output file.

: gnuplot files
: tecplot files
: segment/arm data
: povray files
: velocity data
: terascale browser files
: pole figures

Each file 'segment' will contain a portion of the full
data and will have a sequence number appended to the file
name.

Most utilities for processing these types of output, however,
expect the data in a single file, so the 'stitch' tool
has been provided in order to recombine these data file
segments into a single usable file as a post-processing
step. The tool can be found in the source release as:

: <ParadisDir>/tools/stitch

The command line for 'stitch is as follows:

stitch [-h] [-d dir | -f file]

where
<pre>
-h prints the usage information to stdout

-d <dir> specifies a directory the utility will
scan for any segmented output files that
need to be stitched together.

-f <file> specifies a base file name and the utility will
scan for the corresponding file segments (files
named <file>.N where N ranges from zero on up)
and stitch the segments into the single specified
base file name.
</pre>

NOTE: If neither a directory nor file name was provided
on the command line, the tool will behave as though
the caller specified the current directory on the command
line and perform as stated above.

== Appendix 1. Control Parameters ==

The following is a brief description of the valid control
file parameters. Also see the example control files contained
within the <ParadisDir>/tests directory.

The parameters have been grouped into the following categories, and
unless otherwise specified, units are in SI, and lengths are
normalized by burgers vector magnitude:

* Simulation cell and processor setup
* Simulation time and timestepping controls
* Discretization controls
* FMM controls
* Tables for non-FMM far-field forces
* Loading condition parameters
* Material and mobility parameters
* Velocity statistics and controls
* I/O controls and parameters
* Miscellaneous parameters

=== Simulation cell and processor setup: ===

{|class="wikitable" border="1" align="center"
|+ Table A1. Control parameters for simulation setup
! Parameter
! Type
! Description
|-
|align="center"| numXdoms, numYdoms, numZdoms ||align="center"| integer ||align="left"|
Defines the number of computational domains into which the problem space is partitioned in the corresponding dimensions.
|-
|align="center"| numXcells, numYcells, numZcells ||align="center"| integer ||align="left"|
Defines the number of cells in the corresponding dimension of the problem space. Cells are independent of the domain geometry and are used to determine boundaries at which far-field forces are computed rather than direct segment to segment forces.
|-
|align="center"| xBoundType, yBoundType, zBoundType ||align="center"| integer ||align="left"|
Defines the type of problem space boundaries in the corresponding dimension. Currently supported types are 0, and 1 for periodic and free surfaces respectively.
|-
|align="center"| xBoundMax, yBoundMax, zBoundMax ||align="center"| double ||align="left"|
If periodic boundaries are not enabled, defines the upper limit on coordinates of any dislocation nodes in the corresponding dimension. Value must be <= the respective maximum problem space coordinate specified in the nodal data file.
|-
|align="center"| xBoundMin, yBoundMin, zBoundMin ||align="center"| double ||align="left"|
If periodic boundaries are not enabled, defines the lower limit on coordinates of any dislocation nodes in the corresponding dimension. Value must be >= the respective minimum problem space coordinate specified in the nodal data file.
|-
|align="center"| decompType ||align="center"| Integer ||align="left"|
Specifies the type of domain decomposition to be used for a run. A value of one selects the old Recursive Sectioning (RS) algorithm, a value of 2 selects the Recursive Bisectioning (RB) decomposition algorithm. The default is currently the RS decomposition.
|-
|align="center"| DLBfreq ||align="center"| Integer ||align="left"|
Indicates the frequency (in cycles) at which Dynamic Load-Balancing is to be attempted. A value of zero indicates no load-balancing is to be done. Default is 3.
|}

=== Simulation time and timestepping controls ===

{|class="wikitable" border="1" align="center"
|+ Table A2. Time Control parameters
! Parameter
! Type
! Description
|-
|align="center"| cycleStart ||align="center"| integer ||align="left"|
Starting cycle number for the simulation.
|-
|align="center"| maxstep ||align="center"| integer ||align="left"|
Indicates the number of timesteps to execute before terminating.
|-
|align="center"| timeNow ||align="center"| double ||align="left"|
Current simulation time (in seconds).
|-
|align="center"| timeStart ||align="center"| double ||align="left"|
Initial simulation time (in seconds).
|-
|align="center"| timestepIntegrator ||align="center"| string ||align="left"|
Selects a timestep integration method. Valid methods are "trapezoid" and "forward-euler". The default value is "trapezoid".
|-
|align="center"| deltaTT ||align="center"| double ||align="left"|
Specifies the duration of the previous timestep in units of seconds.
|-
|align="center"| maxDT ||align="center"| double ||align="left"|
Specifies the maximum timestep permitted. Default is 1.0e-07.
|-
|align="center"| nextDT ||align="center"| double ||align="left"|
Specifies the timestep duration to attempt on the next cycle. The timestep integrator will adjust this value dynamically. Default is <maxDT>.
|-
|align="center"| dtDecrementFact ||align="center"| double ||align="left"|
Factor by which <delatTT> is mutiplied when cutting the timestep duration down. Must be between 0.0 and 1.0. Currently only used with the "trapezoid" integrator. Default is 0.5.
|-
|align="center"| dtExponent ||align="center"| double ||align="left"|
Exponent used in calculation of timestep increment when <dtVariableAdjustment> toggle is enabled. Currently used only with "trapezoid" timestep integrator.
|-
|align="center"| dtIncrementFact ||align="center"| double ||align="left"|
Maximum factor by which <deltaTT> is multiplied when incrementing the timestep. Must be at least 1.0. Default is 1.2.
|-
|align="center"| dtVariableAdjustment ||align="center"| integer ||align="left"|
Toggles ability to vary the increment by which the timestep is adjusted when the current timestep is determined to be too small. This will permit the timestep to be adjusted to a value between 1.0 and <dtIncrementFact> * <deltaTT>. Toggle is zero (off) by default. Used only with "trapezoid" integrator.
|-
|align="center"| rTol ||align="center"| double ||align="left"|
Maximum position error (in units of b) tolerated in the timestep integration. Only applies to the "trapezoid" integrator. Default is 0.25 * <rc>. The annihilation
distance is related to rTol(By default, it is set to 2*<rTol>=0.5 * <rc>.)
|-
|align="center"| rmax ||align="center"| double ||align="left"|
Maximum distance (in units of b) a node is permitted to move in a single timestep. Not used if "trapezoid" timestep integrator used. Default is 0.5 * <minSeg>.
|}

=== Discretization controls: ===

{|class="wikitable" border="1" align="center"
|+ Table A3. Discretization control parameters
! Parameter
! Type
! Description
|-
|align="center"| maxSeg ||align="center"| double ||align="left"|
Sets the maximum permitted length (in units of b) of a dislocation segment. Primarily used for determining when segments are to be rediscretized during remesh operations. This value must be less than 9/10 the size of a cell. There is no default value, and must be specified in the control file.
|-
|align="center"| minSeg ||align="center"| double ||align="left"|
Sets the minimum desired length (in units of b) of a dislocation segment. Primarily used for determining when nodes are to be removed during remesh operations. Default is: sqrt(remeshAreaMin*(4/sqrt(3))) where remeshAreaMin = 2*rTol*maxSeg
|-
|align="center"| remeshRule ||align="center"| integer ||align="left"|
Specifies by number the set of rules governing rediscretization of dislocations. Currently the only supported remesh modules are versions 2 and 3. Default is 2. (See section on Rediscretization for details on remesh versions.)
|}

=== FMM controls ===

{|class="wikitable" border="0" align="center"
|+ Table A4. FMM control parameters
! Parameter
! Type
! Description
|-
|align="center"| fmEnabled ||align="center"| integer ||align="left"|
Toggle controlling use of a Fast Multipole Method (FMM) for computing force contributions from remote dislocation segments. A value of zero disables the use of FMM, any other value enables FMM. Default value is zero.
|-
|align="center"| fmCorrectionTbl ||align="center"| string ||align="left"|
Name of the image correction table used by the FMM. This correction table must correspond to the specified <fmMPOrder>, <fmTaylorOrder> and <shearModulus>(?) control parameters. See the [[#Creating the FMM Image Correction Table with 'ctablegen'|'ctablegen' utility]] for information on creating these tables. This value is ignored if <fmEnabled> is zero.
|-
|align="center"| fmMPOrder ||align="center"| integer ||align="left"|
Defines the multipole expansion order used by the FMM. This value is ignored if <fmEnabled> is zero. Default is 2.
|-
|align="center"| fmTaylorOrder ||align="center"| integer ||align="left"|
Defines the order of taylor expansions used by the FMM. This values is ignored if <fmEnabled> is zero. Default is 4.
|}

{|class="wikitable" border="0" align="center"
|+ Table A5. Table for non-FMM far-field forces
! Parameter
! Type
! Description
|-
|align="center"| Rijmfile ||align="center"| string ||align="left"|
Name of file containing the RIJM table to be used for far-field stress calculations. This parameter is ignored if the <fmEnabled> parameter is non-zero. Default is "inputs/Rijm.cube.out".
|-
|align="center"| RijmPBCfile ||align="center"| string ||align="left"|
Name of file containing the RIJM table to be used for far-field stress calculations with periodic boundary conditions. This parameter is ignored if the <fmEnabled> parameter is non-zero. Default is "inputs/RijmPBC.cube.out".
|}

=== Loading condition parameters: ===

{|class="wikitable" border="1" align="center"
|+ Table A6. Loading condition parameters
! Parameter
! Type
! Description
|-
|align="center"| loadType ||align="center"| integer ||align="left"|
Defines the type of load on the system. Valid types are:
<ol start="0">
<li> Creep test </li>
<li> Constant strain rate test </li>
<li> Displacement-controlled test </li>
<li> Load-controlled, load vs. time curve </li>
<li> Cyclic loading condition </li>
</ol>
|-
|align="center"| appliedStress ||align="center"| double[6] ||align="left"|
Defines the type of load on the system. Valid types are:
External stress specified in units of Pa as [sigma11, sigma22, sigma33, sigma23, sigma31, sigma12] when <loadType> == 0. Default is [0.0, 0.0, 0.0, 0.0, 0.0, 0.0].
|-
|align="center"| eRate ||align="center"| double ||align="left"|
Strain rate. Applicable only when <loadType> == 1. Default is 1.0/sec.
|-
|align="center"| indxErate ||align="center"| integer ||align="left"|
Index to indicate normal or shear deformation. Used only when <loadType> == 1. Valid values are:
# normal
# shear
If not specified, defaults to 1.
|-
|align="center"| edotdir ||align="center"| double[3] ||align="left"|
Uniaxial loading direction accompanying <eRate>. Default is [1.0 0.0 0.0].
|-
|align="center"| cTimeOld ||align="center"| integer ||align="left"|
Timestep related to cyclic loading. Only used when <loadType> == 4.
|-
|align="center"| dCyclicStrain ||align="center"| double ||align="left"|
Incremental strain under cyclic load. Only used when <loadType> == 4.
|-
|align="center"| netCyclicStrain ||align="center"| double ||align="left"|
Net accumulated strain under cyclic load. Only used when <loadType> == 4.
|-
|align="center"| numLoadCycle ||align="center"| integer ||align="left"|
Number of cyclic cycles. Only used when <loadType> == 4.
|-
|align="center"| eAmp ||align="center"| double ||align="left"|
Strain amplitude. Only used when <loadType> == 4.
|}

=== Material and mobility parameters: ===

Note: Default values for all material and mobility related
parameters correspond to Tantalum at a temperature of
600 degress K and pressure of 0 GPa.

{|class="wikitable" border="1" align="center"
|+ Table A7. Table for material and mobility parameters
! Parameter
! Type
! Description
|-
|align="center"| mobilityLaw ||align="center"| string ||align="left"|
Specifies by name the set of rules governing dislocation motion for the simulation conditions. Default is "BCC_0".
|-
|align="center"| shearModulus ||align="center"| double ||align="left"|
Shear modulus in units of Pa. Default is 6.488424e+10
|-
|align="center"| pois ||align="center"| double ||align="left"|
Poisson ratio. Default is 3.327533e-01
|-
|align="center"| burgMag ||align="center"| double ||align="left"|
Magnitude of the burgers vector (b) in units of meters. Default is 2.875401e-10
|-
|align="center"| YoungModulus ||align="center"| double ||align="left"|
Young's modulus (in units of Pa). calculated from E = 2G(1+pois). Default is 200.0e+09.
|-
|align="center"| rc ||align="center"| double ||align="left"|
Core radius (in units of b) for self-force calculations. No default value; must be specified in control file.
|-
|align="center"| Ecore ||align="center"| double ||align="left"|
Core energy used for self-force calculation. Default is (<shearModulus>/(4*PI)) * log(<rc>/0.1)
|-
|align="center"| MobScrew ||align="center"| double ||align="left"|
Mobility of screw dislocations in units of 1/(Pa*sec). Default is 10.0.
|-
|align="center"| MobEdge ||align="center"| double ||align="left"|
Mobility of edge dislocations in units of 1/(Pa*sec). Default is 10.0.
|-
|align="center"| MobClimb ||align="center"| double ||align="left"|
Climb mobility of dislocations in units of 1/(Pa*sec). Default is 1.0e-02.
|-
|align="center"| sessileburgspec ||align="center"| double[30] ||align="left"|
Array of burgers vectors to be considered sessile. First element of the array contains the number of burgers vectors specified, the remaining elements specify the X, Y, then Z components of each sessile burgers vector. Maximum sessile burgers vectors allowed is 9. No burgers vectors are sessile by default.
|-
|align="center"| sessilelinespec ||align="center"| double[30] ||align="left"|
Array of line directions related to sessileburgspec. First element is ignored, remaining elements specify the X, Y, then Z components of each sessile line. The number of lines is assumed to be the same as the number of sessile burgers vectors.
|}

=== Flux Decomposition: ===

{|class="wikitable" border="1" align="center"
|+ Table A8.
! Parameter
! Type
! Description
|-
|align="center"| totpSpn ||align="center"| double[6] ||align="left"|
Plastic strain tensor
|-
|align="center"| totpStn ||align="center"| double[6] ||align="left"|
Plastic spin tensor
|-
|align="center"| totstraintensor ||align="center"| double[6] ||align="left"|
Strain rate tensor with respect to global coordinate system.
|-
|align="center"| Ltot ||align="center"| double[4][4] ||align="left"|
Decomposed density per burgers vector for screw and three edges (for BCC slip systems only).
|-
|align="center"| fluxtot ||align="center"| double[4][7] ||align="left"|
For each burgers vector (for BCC slip systems only), contains:
<table border = "0" cellpadding = "0" cellspacing = "0">
<tr>
<td align="right"> 1. </td>
<td> flux due to climb </td>
</tr>
<tr>
<td align="right"> 2-4. </td>
<td> flux due to edge components </td>
</tr>
<tr>
<td align="right"> 5-7. </td>
<td> flux due to screw components </td>
</tr>
</table>
|}

=== Velocity statistics: ===

‡ Note: these statistics will only be used if the VEL_STATISTICS pre-processor macro has been defined during compilation.

{|class="wikitable" border="1" align="center"
|+ Table A9.
! Parameter
! Type
! Description
|-
|align="center"| vAverage ||align="center"| double ||align="left"|
Average dislocation velocity.
|-
|align="center"| vStDev ||align="center"| double ||align="left"|
Standard deviation of dislocation velocities.
|}

=== I/O controls and parameters ===

‡ Note: A number of the supported output forms are controlled by
very similar control parameters. The general descriptions below
apply to all I/O control parameters of like names:

<pre>
*freq Sets the frequency (in cycles) at which the associated data
will be written to disk. If the corresponding <*dt> parameter
is greater than 0, this parameter will be ignored.
Default for all such values is 100.

*dt The *dt variables specify the simulation delta time that will
control the frequency at which the associated output will be
written to disk. A positive value is interpreted as a delta
time and will take precedence over any frequency specified by
the corresponding <*freq> value. A value <= zero indicates
write frequency will not be determined by delta times.
Default value is -1.0.

*time Specifies the simulation time at which the associated data
was last written to disk. This value will be automatically
updated during the simulation. If the corresponding <*dt>
parameter is <= 0.0 this parameter will be ignored.

*counter Sequence number of the previously written file of the
corresponding type. Default is 0.
</pre>

{|class="wikitable" border="1" align="center"
|+ Table A10.
! Parameter
! Type
! Description
|-
|align="center"| dirname ||align="center"| string ||align="left"|
Base output directory name.
|-
|align="center"| skipIO ||align="center"| integer ||align="left"|
Toggle for disabling generation of all output types other than timing files. Overrides output-specific toggles if set. Default is 0.
|-
|align="center"| numIOGroups ||align="center"| integer ||align="left"|
Sets the number of groups into which the domains will be separated for doing parallel IO. All files generated in parallel will be created with this number of segments. This value must be at least one and no more than the total number of domains used. default is 1.
|-
|align="center"| armfile ||align="center"| integer ||align="left"|
Toggle enabling/disabling generation of files identifying each unique dislocation segment. Toggle is zero (off) by default.
|-
|align="center"| armfilecounter ||align="center"| integer ||align="left"|
See description of <*counter> above.
|-
|align="center"| armfiledt ||align="center"| double ||align="left"|
See description of <*dt> above.
|-
|align="center"| armfilefreq ||align="center"| integer ||align="left"|
See description of <*freq> above.
|-
|align="center"| armfiletime ||align="center"| double ||align="left"|
See description of <*time> above.
|-
|align="center"| fluxfile ||align="center"| integer ||align="left"|
Toggle enabling/disabling generation of flux decomposition files. Toggle is zero (off) by default.
|-
|align="center"| fluxcounter ||align="center"| integer ||align="left"|
See description of <*counter> above.
|-
|align="center"| fluxdt ||align="center"| double ||align="left"|
See description of <*dt> above.
|-
|align="center"| fluxfreq ||align="center"| integer ||align="left"|
See description of <*freq> above.
|-
|align="center"|fluxtime ||align="center"| double ||align="left"|
See description of <*time> above.
|-
|align="center"| gnuplot ||align="center"| integer ||align="left"|
Toggle enabling/disabling generation of files formatted for use with gnuplot. Toggle is zero (off) by default.
|-
|align="center"| gnuplotcounter ||align="center"| integer ||align="left"|
See description of <*counter> above.
|-
|align="center"| gnuplotdt ||align="center"| double ||align="left"|
See description of <*dt> above.
|-
|align="center"| gnuplotfreq ||align="center"| integer ||align="left"|
See description of <*freq> above.
|-
|align="center"| gnuplottime ||align="center"| double ||align="left"|
See description of <*time> above.
|-
|align="center"| polefigfile ||align="center"| integer ||align="left"|
Toggle enabling/disabling generation of <111> type burgers vector pole figures. Toggle is zero (off) by default.
|-
|align="center"| polefilecounter ||align="center"| integer ||align="left"|
See description of <*counter> above.
|-
|align="center"| polefigdt ||align="center"| double ||align="left"|
See description of <*dt> above.
|-
|align="center"| polefigfreq ||align="center"| integer ||align="left"|
See description of <*freq> above.
|-
|align="center"| polefigtime ||align="center"| double ||align="left"|
See description of <*time> above.
|-
|align="center"| povray ||align="center"| integer ||align="left"|
Toggle enabling/disabling generation of files with nodal data and domain boundaries for use with povray. Toggle is zero (off) by default.
|-
|align="center"| povraycounter ||align="center"| integer ||align="left"|
See description of <*counter> above.
|-
|align="center"| povraydt ||align="center"| double ||align="left"|
See description of <*dt> above.
|-
|align="center"| povrayfreq ||align="center"| integer ||align="left"|
See description of <*freq> above.
|-
|align="center"| povraytime ||align="center"| double ||align="left"|
See description of <*time> above.
|-
|align="center"| psfile ||align="center"| integer ||align="left"|
Toggle enabling/disabling generation of postscript files containing nodal data and domain boundaries. Toggle is zero (off) by default.
|-
|align="center"| psfiledt ||align="center"| double ||align="left"|
See description of <*dt> above.
|-
|align="center"| psfilefreq ||align="center"| integer ||align="left"|
See description of <*freq> above.
|-
|align="center"| psfiletime ||align="center"| double ||align="left"|
See description of <*time> above.
|-
|align="center"| savecn ||align="center"| integer ||align="left"|
Toggle enabling/disabling writing of restart files. Toggle is zero (off) by default.
|-
|align="center"| savecncounter ||align="center"| integer ||align="left"|
See description of <*counter> above.
|-
|align="center"| savecndt ||align="center"| double ||align="left"|
See description of <*dt> above.
|-
|align="center"| savecnfreq ||align="center"| integer ||align="left"|
See description of <*freq> above.
|-
|align="center"| savecntime ||align="center"| double ||align="left"|
See description of <*time> above.
|-
|align="center"| saveprop ||align="center"| integer ||align="left"|
Toggle enabling/disabling writing of various properties files. Toggle is zero (off) by default.
|-
|align="center"| savepropdt ||align="center"| double ||align="left"|
See description of <*dt> above.
|-
|align="center"| savepropfreq ||align="center"| integer ||align="left"|
See description of <*freq> above.
|-
|align="center"| saveproptime ||align="center"| double ||align="left"|
See description of <*time> above.
|-
|align="center"| savetimers ||align="center"| integer ||align="left"|
Toggle enabling/disabling generation of timing data files. Toggle is zero (off) by default.
|-
|align="center"| savetimerscounter ||align="center"| integer ||align="left"|
See description of <*counter> above.
|-
|align="center"| savetimersdt ||align="center"| double ||align="left"|
See description of <*dt> above.
|-
|align="center"| savetimersfreq ||align="center"| integer ||align="left"|
See description of <*freq> above.
|-
|align="center"| savetimerstime ||align="center"| double ||align="left"|
See description of <*time> above.
|-
|align="center"| savedensityspec ||align="center"| integer[3] ||align="left"|
Specifies the granularity of the 3D density field written to the density field file in X, Y and Z dimensions. If any element of this array is zero, this capability is disabled.
|-
|align="center"| tecplot ||align="center"| integer ||align="left"|
Toggle enabling/disabling generation of output files formatted for use with tecplot. Toggle is zero (off) by default.
|-
|align="center"| tecplotcounter ||align="center"| integer ||align="left"|
See description of <*counter> above.
|-
|align="center"| tecplotdt ||align="center"| double ||align="left"|
See description of <*dt> above.
|-
|align="center"| tecplotfreq ||align="center"| integer ||align="left"|
See description of <*freq> above.
|-
|align="center"| tecplottime ||align="center"| double ||align="left"|
See description of <*time> above.
|-
|align="center"| tsbfile ||align="center"| integer ||align="left"|
Toggle enabling/disabling generation of output files formatted for use with the TeraScale Browser. Toggle is zero (off) by default.
|-
|align="center"| writetsbspec ||align="center"| integer[3] ||align="left"|
TBD
|-
|align="center"| tsbfilecounter ||align="center"| integer ||align="left"|
See description of <*counter> above.
|-
|align="center"| tsbfiledt ||align="center"| double ||align="left"|
See description of <*dt> above.
|-
|align="center"| tsbfilefreq ||align="center"| integer ||align="left"|
See description of <*freq> above.
|-
|align="center"| tsbfiletime ||align="center"| double ||align="left"|
See description of <*time> above.
|-
|align="center"| velfile ||align="center"| integer ||align="left"|
Toggle enabling/disabling generation of output files containing velocity data for all nodes in the simulation. Toggle is zero (off) by default.
|-
|align="center"| velfilecounter ||align="center"| integer ||align="left"|
See description of <*counter> above.
|-
|align="center"| velfiledt ||align="center"| double ||align="left"|
See description of <*dt> above.
|-
|align="center"| velfilefreq ||align="center"| integer ||align="left"|
See description of <*freq> above.
|-
|align="center"| velfiletime ||align="center"| double ||align="left"|
See description of <*time> above.
|-
|align="center"| winDefaultsFile ||align="center"| string ||align="left"|
Name of file containing default options and attributes for the X-window display. This is ignore if the X display support was not enabled at compile time. Defaults to "./inputs/paradis.xdefaults".
|}

=== Miscellaneous parameters ===

{|class="wikitable" border="1" align="center"
|+ Table A11.
! Parameter
! Type
! Description
|-
|align="center"| elasticinteraction ||align="center"| integer ||align="left"|
Toggles between explicit calculation of elastic interaction and simple line tension calculations. Toggle is one (on) by default.
|-
|align="center"| TensionFactor ||align="center"| double ||align="left"|
Factor used for simple line tension force calculations when the <elasticinteraction> parameter is zero. Default is 1.0.
|}

=== Under development ===

{|class="wikitable" border="1" align="center"
|+ Table A12.
! Parameter
! Type
! Description
|-
|align="center"| TempK ||align="center"| double ||align="left"|
Simulation temperature (in Kelvin). For use in FCC cross-slip.
|-
|align="center"| enforceGlidePlanes ||align="center"| integer ||align="left"|
If non-zero, forces remesh, collision handling, etc. to use glide-plane constraints. Default is zero.
|-
|align="center"| springConst ||align="center"| double ||align="left"|
For use with FCC_0 mobility
|-
|align="center"| mob_compute_escaig ||align="center"| integer ||align="left"|
TBD
|-
|align="center"| mob_cross_slip ||align="center"| integer ||align="left"|
TBD
|}

Overview of ParaDiS 2.2

2011-12-05T04:50:39Z

Iryu: /* Simulation time and timestepping controls */

This document is taken from ParaDiSInfo.txt in ParaDiS.v2.2 distribution. Written by Gregg Hommes, LLNL.

== Introduction ==

The Parallel Dislocation Simulator (ParaDiS) was written
and developed at LLNL by a team of physicists and computer
scientists. ParaDiS is a code for doing Dislocation Dynamics
simulations and was specifically written to perform well on
massively parallel computers. The computational approach to
Dislocation Dynamics used in ParaDiS is fairly simple. In
it, one introduces dislocation lines into the computational
volume and lets them interact and move in response to the
forces imposed by external stress and inter-dislocation
interactions.

---------------------------------------------------------------------

== Building ParaDiS ==

=== Directory Structure ===

The ParaDiS release consists of a file which, when unzipped
and untarred creates a primary directory and a structure
of subdirectories. For convenience, this primary directory
will hereafter be referred to as <ParadisDir>. The directory
structure of the release will look like:

<TABLE CELLPADDING=3 >
<TR valign="top">
<TD ALIGN="LEFT">     </TD>
<TD ALIGN="LEFT"><ParadisDir>/</TD>
<TD ALIGN="LEFT">     </TD>
<TD ALIGN="LEFT">Contains primary 'make' files for controlling build of all executables</TD>
</TR>
<TR valign="top">
<TD ALIGN="LEFT">     </TD>
<TD ALIGN="LEFT"><ParadisDir>/bin/</TD>
<TD ALIGN="LEFT">     </TD>
<TD ALIGN="LEFT">This directory will be created during the 'make' process. All executables will be placed in this directory during compilation</TD>
</TR>
<TR valign="top">
<TD ALIGN="LEFT">     </TD>
<TD ALIGN="LEFT"><ParadisDir>/docs/</TD>
<TD ALIGN="LEFT">     </TD>
<TD ALIGN="LEFT">Contains any additional documentation</TD>
</TR>
<TR valign="top">
<TD ALIGN="LEFT">     </TD>
<TD ALIGN="LEFT"><ParadisDir>/include/</TD>
<TD ALIGN="LEFT">     </TD>
<TD ALIGN="LEFT">Contains all C and C++ header files</TD>
</TR>
<TR valign="top">
<TD ALIGN="LEFT">     </TD>
<TD ALIGN="LEFT"><ParadisDir>/inputs/</TD>
<TD ALIGN="LEFT">     </TD>
<TD ALIGN="LEFT">FMM and non-FMM correction tables, X-display defaults file, gnuplot command file, etc.</TD>
</TR>
<TR valign="top">
<TD ALIGN="LEFT">     </TD>
<TD ALIGN="LEFT"><ParadisDir>/materials/</TD>
<TD ALIGN="LEFT">     </TD>
<TD ALIGN="LEFT">Sample files containing material specific tables and constants</TD>
</TR>
<TR valign="top">
<TD ALIGN="LEFT">     </TD>
<TD ALIGN="LEFT"><ParadisDir>/src/</TD>
<TD ALIGN="LEFT">     </TD>
<TD ALIGN="LEFT">All C and C++ source code modules related to the paradis executable</TD>
</TR>
<TR valign="top">
<TD ALIGN="LEFT">     </TD>
<TD ALIGN="LEFT"><ParadisDir>/tools/</TD>
<TD ALIGN="LEFT">     </TD>
<TD ALIGN="LEFT">Miscellaneous support scripts</TD>
</TR>
<TR valign="top">
<TD ALIGN="LEFT">     </TD>
<TD ALIGN="LEFT"><ParadisDir>/utilities/</TD>
<TD ALIGN="LEFT">     </TD>
<TD ALIGN="LEFT">Source code modules pertaining to the various support tools</TD>
</TR>
</TABLE>

=== Compiling ===

The current ParaDiS 'make' files support compilation for
a number of pre-defined system types that are defined in
the file 'makefile.sys'. In order to compile the code on
one of these pre-defined system types, simply edit
'makefile.setup' and set the "SYS=..." value to the
desired system type. For other system types, add a new
system type into 'makefile.sys' following the format used
for the existing systems and, as above, set the "SYS=..."
value in 'makefile.setup'.

Executing 'gmake' with no options in <ParadisDir> will
build the following executables:

<TABLE CELLPADDING=3 >
<TR valign="top">
<TD ALIGN="LEFT">     </TD>
<TD ALIGN="LEFT"><ParadisDir>/bin/paradis</TD>
<TD ALIGN="LEFT">     </TD>
<TD ALIGN="LEFT">-- Main parallel application</TD>
</TR>
<TR valign="top">
<TD ALIGN="LEFT">     </TD>
<TD ALIGN="LEFT"><ParadisDir>/bin/paradisgen</TD>
<TD ALIGN="LEFT">     </TD>
<TD ALIGN="LEFT">-- Utility for creating initial dislocation configurations (See [[#Utilities|Utilities]] section for details)</TD>
</TR>
<TR valign="top">
<TD ALIGN="LEFT">     </TD>
<TD ALIGN="LEFT"><ParadisDir>/bin/paradisrepart</TD>
<TD ALIGN="LEFT">     </TD>
<TD ALIGN="LEFT">-- Utility for generating a new domain decomposition for an existing dislocation configuration (See [[#Utilities|Utilities]] section for details)</TD>
</TR>
<TR valign="top">
<TD ALIGN="LEFT">     </TD>
<TD ALIGN="LEFT"><ParadisDir>/bin/paradisconvert</TD>
<TD ALIGN="LEFT">     </TD>
<TD ALIGN="LEFT">-- Utility for converting older format ParaDiS control parameter files to the current format (See [[#Utilities|Utilities]] section for details)</TD>
</TR>
<TR valign="top">
<TD ALIGN="LEFT">     </TD>
<TD ALIGN="LEFT"><ParadisDir>/bin/ctablegen</TD>
<TD ALIGN="LEFT">     </TD>
<TD ALIGN="LEFT">-- Utility for creating image correction tables needed when FMM code is enabled. (See [[#Utilities|Utilities]] section for details)</TD>
</TR>
<TR valign="top">
<TD ALIGN="LEFT">     </TD>
<TD ALIGN="LEFT"><ParadisDir>/bin/ctablegenp</TD>
<TD ALIGN="LEFT">     </TD>
<TD ALIGN="LEFT">-- Parallel version of the ctablegen utility. See above.</TD>
</TR>
<TR valign="top">
<TD ALIGN="LEFT">     </TD>
<TD ALIGN="LEFT"><ParadisDir>/bin/stresstablegen</TD>
<TD ALIGN="LEFT">     </TD>
<TD ALIGN="LEFT">-- Utility for creating tables used in calculating far-field stress if the FMM code is not enabled. (See [[#Utilities|Utilities]] section for details)
</TD>
</TR>
</TABLE>

=== Make files ===

Compilation of the code is done via 'gmake' and depends
on the following 'make' files located in the <ParadisDir>
directory. (See the individual make files for details)

<TABLE CELLPADDING=3 >
<TR valign="top">
<TD ALIGN="LEFT">     </TD>
<TD ALIGN="LEFT">makefile</TD>
<TD ALIGN="LEFT">     </TD>
<TD ALIGN="LEFT">-- This is the primary make file controlling the build of the parallel executable and associated utilities.
</TD>
</TR>
<TR valign="top">
<TD ALIGN="LEFT">     </TD>
<TD ALIGN="LEFT">makefile.sys</TD>
<TD ALIGN="LEFT">     </TD>
<TD ALIGN="LEFT">-- This file contains, for each supported system type, a set of 'make' macros, definitions, compiler selection, library and include file paths, etc.
</TD>
</TR>
<TR valign="top">
<TD ALIGN="LEFT">     </TD>
<TD ALIGN="LEFT">makefile.setup</TD>
<TD ALIGN="LEFT">     </TD>
<TD ALIGN="LEFT">-- Contains numerous 'make' settings and flags that are not system specific, including settings for system type, optimization level, debugging flags, etc.
</TD>
</TR>
</TABLE>

---------------------------------------------------------------------

== Executing ParaDiS ==

=== Command line ===

The ParaDiS command line format is:

paradis [-r <numCycles>] [-d dataFile] <controlFile>

where:

<TABLE CELLPADDING=3 >
<TR valign="top">
<TD ALIGN="LEFT">     </TD>
<TD ALIGN="LEFT"><ctrlFile></TD>
<TD ALIGN="LEFT">     </TD>
<TD ALIGN="LEFT">Specifies the name of the ParaDiS control parameter file
</TD>
</TR>
<TR valign="top">
<TD ALIGN="LEFT">     </TD>
<TD ALIGN="LEFT">-d <dataFile></TD>
<TD ALIGN="LEFT">     </TD>
<TD ALIGN="LEFT">Specifies the base name of the file(s) containing the nodal data for the run. If this file name is not supplied, the code looks for a data file named the same as the control file with the file name suffix (if any) replaced with ".data"
</TD>
</TR>
<TR valign="top">
<TD ALIGN="LEFT">     </TD>
<TD ALIGN="LEFT">-r   <numCycles></TD>
<TD ALIGN="LEFT">     </TD>
<TD ALIGN="LEFT">Causes the code to execute a series of <numCycles> cycles during which no force calculations or dislocation movement will occur. These cycles will be used strictly for load-balancing purposes and will be done before the normal cycles. This can be useful when a simulation is started with a uniform domain decomposition and needs time to converge on an optimal decomposition as would occur when restarting a simulation on a different number of cpus
</TD>
</TR>
</TABLE>

=== Examples ===

For example, the following are all valid execution lines with the
first two being equivalent, the third version using the same control
file as the first two, but explicitly selecting a different nodal
data file.

For example, assuming you had a the control parameter file
'testrun.ctrl' and the two different nodal data files 'testrun.data'
and 'testrun2.data', all of the following command lines formats
are valid. The first two commands are equivalent, the third
uses the same control parameter file as the first two, but
explicitly selects a different nodal data file.

mpirun -np 8 bin/paradis testrun.ctrl
mpirun -np 8 bin/paradis -d testrun.data testrun.ctrl
mpirun -np 8 bin/paradis -d testrun2.data testrun.ctrl

NOTE: The number of processors specified to mpirun (or other
parallel job initiator applicable to the execting system)
must match the number of domains specified in the control
file (i.e. np = numXdoms * numYdoms * numZdoms).

Several small example problems are included with the
ParaDiS release. The control and data files for these
examples are:

<ParadisDir>/tests/frank_read_src.ctrl
<ParadisDir>/tests/frank_read_src.data

<ParadisDir>/tests/form_binaryjunc.ctrl
<ParadisDir>/tests/form_binaryjunc.data

<ParadisDir>/tests/fmm_8cpu.ctrl
<ParadisDir>/tests/fmm_8cpu.data

NOTE: These tests require the following tables used
for calculating the far-field stresses from distant
cells and periodic images of the problem.

<ParadisDir>/inputs/Rijm.cube.out
<ParadisDir>/inputs/RijmPBC.cube.out
<ParadisDir>/inputs/fm-ctab.Ta.600K.0GPa.m2.t5.dat

These file *may* have been provided with the source
code release. If not, see the README file in the
<ParadisDir>/tests directory for instructions on
generating these files.

The 'form_binaryjunc*' files contain a small configuration that
will demonstrate the formation of a binary junction from two
dislocation lines, while the 'frank_read_src*' files contain a
configuration that demonstrates the behaviour of a frank-read
source. Both these examples are single cpu examples. To run
these tests, from the main <ParadisDir> directory execute:

mpirun -np 1 ./bin/paradis ./tests/form_binaryjunc.ctrl
or
mpirun -np 1 ./bin/paradis ./tests/frank_read_src.ctrl

The 'fmm_8cpu*' files are just a general demonstration of the
behavior of a small number of screw dislocations. This is
an 8 processor simulation using the Fast Multipole Method
(FMM) for calculating stress from far-field interactions.

mpirun -np 8 ./bin/paradis ./tests/fmm_8cpu.ctrl

Any output from these runs will be placed into corresponding
subdirectories under the "tests" directory.
---------------------------------------------------------------------

== Inputs ==

=== Input Files ===

A ParaDiS simulation may be started from scratch, or
terminated and then later restarted if the user requested
periodic dumps of restart files. In either case, the initial
or restart data data consists of two files, a control
parameter file and a nodal data file. (See section on
[[#Output|Output]] for details on restart files)

=== Control Parameter File ===

The control parameter file consists of data of the form:

<TABLE>
<TR>
<TD ALIGN="LEFT">     </TD>
<TD ALIGN="LEFT"> </TD>
<TD ALIGN="LEFT">     </TD>
<TD ALIGN="LEFT">
identifier = value
</TD></TR>
<TR>
<TD ALIGN="LEFT">     </TD>
<TD ALIGN="LEFT"> </TD>
<TD ALIGN="LEFT">     </TD>
<TD ALIGN="LEFT">
identifier = [value_list]
</TD></TR>
<TR>
<TD ALIGN="LEFT">     </TD>
<TD ALIGN="LEFT">or</TD>
<TD ALIGN="LEFT">     </TD>
<TD ALIGN="LEFT">
identifier = string
</TD></TR>
</TABLE>

where

<TABLE CELLPADDING=3 >
<TR valign="top">
<TD ALIGN="LEFT">     </TD>
<TD ALIGN="LEFT">identifier</TD>
<TD ALIGN="LEFT">     </TD>
<TD ALIGN="LEFT">is the name of a control parameter
</TD></TR>
<TR valign="top">
<TD ALIGN="LEFT">     </TD>
<TD ALIGN="LEFT">value</TD>
<TD ALIGN="LEFT">     </TD>
<TD ALIGN="LEFT">is a numeric value associated with the parameter specified by <identifier>
</TD></TR>
<TR valign="top">
<TD ALIGN="LEFT">     </TD>
<TD ALIGN="LEFT">value_list</TD>
<TD ALIGN="LEFT">     </TD>
<TD ALIGN="LEFT">is a list of numeric values to be associated with the array specified by <identifier>. This values in this list must be delimited by white-space or line-feeds.
</TD></TR>
<TR valign="top">
<TD ALIGN="LEFT">     </TD>
<TD ALIGN="LEFT">string</TD>
<TD ALIGN="LEFT">     </TD>
<TD ALIGN="LEFT">a character string enclosed within either single or double quotes. The string may not contain a line-feed character.
</TD></TR>
</TABLE>

The identifier names are case-insensitive and may be specified
as any mixture of upper and lower case. If the code encounters
an identifier it does not recognize, the identifier and associated
value(s) will be ignore and a warning message displayed.

Any blank lines in the control parameter file will will be
ignored and additionally, any '#' not contained within quotes
is treated as the beginning of a comment and causes the remainder
of the current line to be ignored.

See the [[#Appendix 1. Control Parameters|Appendix]] for a complete list of the recognized control
parameters as well as a brief description of each.

=== Nodal Data File ===

==== Data File Format ====

The nodal data will be contained in 1 or more file
segments, with the information being broken into
three sections (described below). The first section
is the data file parameters, the second section the
domain decomposition, and the third section the nodal
data. The first two sections will be included only
in the first file segment.

==== Data File Segments ====

Given a control parameter file 'restart.cn', the
associated nodal data file(s) would be named:

restart.data[.SEQ]

where
<TABLE CELLPADDING=3 >
<TR valign="top">
<TD ALIGN="LEFT">     </TD>
<TD ALIGN="LEFT">SEQ</TD>
<TD ALIGN="LEFT">     </TD>
<TD ALIGN="LEFT">is a sequence number included only when the nodal data was written in parallel (i.e. the <numIOGroups> control parameter was greater than 1). <SEQ> will range from zero to <numIOGroups>-1.
</TD></TR>
</TABLE>

For example, suppose the <numIOGroups> control parameter
was set to 4 during a simulation executed on 16 processors.
If the simulation created a restart file set at termination,
the following files would be generated and could be used
as input to continue the simulation at a later time:

<outputDir>/restart/restart.cn
<outputDir>/restart/restart.data.0
<outputDir>/restart/restart.data.1
<outputDir>/restart/restart.data.2
<outputDir>/restart/restart.data.3

==== Data File Parameters ====

The data file parameters make up the first section of
the nodal data file and are parsed in the same manner
as specified above for the control file parameters.
These parameters must preceed the other two types of
information in the nodal data file. NOTE: The values
of these parameters are updated within the ParaDiS
code as necessary and should not be changed by the user.

The recognized data file parameters are:

: dataFileVersion
: numFileSegments
: minCoordinates
: maxCoordinates
: nodeCount
: dataDecompType
: dataDecompGeometry

==== Domain Decomposition ====

TBD

==== Nodal Data ====
The raw nodal data comprises the third section
of the nodal data file. For each node, there will
be a single line of node specific data followed by
several lines of segment specific data for each
segment associated with the node. The nodal data
consists of:

: node_tag x_coord y_coord z_coord num_arms constraint

The segment specific data consists of:

: nbr_tag burg_x burg_y, burg_z
: norm_x norm_y norm_z

where
<TABLE CELLPADDING=3 >
<TR valign="top">
<TD ALIGN="LEFT">     </TD>
<TD ALIGN="LEFT">*_tag</TD>
<TD ALIGN="LEFT">     </TD>
<TD ALIGN="LEFT">is a comma delimited pair of numbers uniquely identifying a node. The first number is the ID of the domain owning the node, the second is the index number of the node within the owning domain.
</TD></TR>
<TR valign="bottom">
<TD ALIGN="LEFT">     </TD>
<TD ALIGN="LEFT">x_coord, y_coord, z_coord</TD>
<TD ALIGN="LEFT">     </TD>
<TD ALIGN="LEFT">coordinates of the node
</TD></TR>
<TR valign="top">
<TD ALIGN="LEFT">     </TD>
<TD ALIGN="LEFT">num_arms</TD>
<TD ALIGN="LEFT">     </TD>
<TD ALIGN="LEFT">Number of segments associated with the node
</TD></TR>
<TR valign="top">
<TD ALIGN="LEFT">     </TD>
<TD ALIGN="LEFT">constraint</TD>
<TD ALIGN="LEFT">     </TD>
<TD ALIGN="LEFT">Integer value indicating any constraints placed on the node (i.e. a constraint of 7 implies a node fixed in place and unmovable)
</TD></TR>
</TABLE>

---------------------------------------------------------------------

== Cell and Domain Structure ==

The ParaDiS code is used to simulate cubic systems which
are simultaneously partitioned into a uniform mesh of
cubic 'cells' and spatially decomposed into 'domains'.

The cellular structure is defined by the <nXcells>, <nYcells>
and <nZcells> control parameters, and is used to determine
the cut-off distance between direct segment to segment
dislocation interactions and remote (or far-field) interactions.
In particular, for a given dislocation segment, the interaction
between the segment and any other segments in the same cell
or any of the immediately neighboring 26 cells are calculated
directly. Interactions with all segments outside that range
are calculated via a hierarchical Fast Multipole Method or
by lumping all segments in the remote cell into a
'super-dislocation' where the group of remote dislocations
are represented as an expansion of dislocation multipoles.
(See [[#Far-Field Dislocation Interactions|section on Far-Field Forces]] for details)

The type of spatial decomposition used for the simulation is
selected by the <decompType> control parameter, along with
the <nXdoms>, <nYdoms> and <nZdoms> parameters defining
the number of spatial domains in each dimension. Each 'domain'
is assigned to a single task (processor) within the simulation.
(See [[#Domain Decomposition 2|section on Domain Decomposition]] for details on the
supported types of spatial decomposition)

---------------------------------------------------------------------

== Domain Decomposition ==

=== Selecting a Domain Decomposition Method ===

ParaDiS simulations are spatially decomposed into a number of
domains equal to the number of processors on which the simulation
is being executed. The code curently supports two types of
domain decomposition and is selected via the <decompType>
control parameter. The type 1 decomposition is a Recursive
Sectioning decomposition which is the default if no decomposition
type is explicitly requested. The type 2 is a Recursive
Bisection decomposition. (See descriptions of decomposition
algorithms below.)

Since the ParaDiS simulations tend to grow in size and are
spatially heterogeneous, it is preferable to dynamically
recalculate the domain decomposition at intervals during the
simulation in order to rebalance the workload more efficiently.
The frequency with which the domain decomposition will be
recomputed is specified by the <DLBfreq> control parameter.

The domain decomposition will be included in the restart files.
If the simulation is restarted and the <decompType> control
parameter selects a decomposition type *other* than the
decomposition that was used to generate the restart file, the
old domain decomposition from the restart file will be ignored
and a new domain decomposition of the selected type will be used.

Additionally, if a simulation is restarted with a different number
of domains or a different domain geometry that that which was used
to create the restart file, the domain decomposition from the
restart file will be ignored and a new decomposition will be
generated.

Note: When restarting a large simulation (i.e. thousands
of processors) in such a way that the old domain decomposition must
be discarded, it may take some time for the simulation to converge
on an optimal domain decomposition. (The type 1 decomposition is
particularly susceptible to this.) There are two ways to mitigate
this effect. The first is to use the 'paradisrepart' utility, the
second through the use of the "-r" command line option to ParaDiS.
See comments in other sections pertaining to these capabilities.

=== Recursive Sectioning ===

The Recursive Sectioning algorithm performs a domain
decomposition over a 3-timestep period. During the
first timestep, the entire problem space will be
sectioned along the X dimension into <nXdoms> slabs
such that the computational cost of each slab is roughly
equivalent. The next timestep, each slab will be
sectioned alng the Y axis into <nYdoms> columns
such that the computational cost of each column in a
slab is roughly equivalent. On the thrid timestep,
every column will be sectioned along the Z axis
into <nZdoms> chunks such that the computational
cost of each chunk in a column is roughy equivalent.

As stated above, the frequency with which the domain boundaries
will be recalulated is controlled by the <DLBfreq> parameter.
If this parameter is not explicity set, the default frequency
for recalculating this type of domain decomposition is every
third timestep.

NOTE: Due to the fact that this algorithm requires 3
timesteps to complete a new decomposition, the
<DLBfreq> value must be no less than 3.

=== Recursive Bisection ===

WARNING: The implementation of this algorithm requires the
number of domains in each dimension (as specified
by the <nXdoms>, <nYdoms>, and <nZdoms> control
parameters) must be a power of 2.

The Recursive Bisectioning algorithm begins with the entire
cubic problem space and bisects the space in the X, Y and/or
Z dimensions into octants quarters or halves (depending on
the number of domains specified per dimension) such that
computational cost of each subpartition is roughly the same.
The decomposition is then recursively applied to each of the
subpartitions until no further decomposition is necesssary.

As stated above, the frequency with which the domain boundaries
will be recalulated is controlled by the <DLBfreq> parameter.
If this parameter is not explicity set, the default frequency
for recalculating this type of domain decomposition is every
timestep.

---------------------------------------------------------------------

== Dislocation Mobility ==

=== Selecting a Mobility Module ===

One of the crucial aspects of a ParaDiS simulation is the
selection of the set of rules governing the material specific
physics such as glide climb, and cross-slip with respect to
crystallographic constraints. ParaDiS provides multiple sets
of rules or "mobility laws", each implemented in a separate
module, that may be selected via the <mobilityLaw> control
file parameter. The currently support modules are:

: "BCC_0"
: "BCC_0b"

There are additional modules for dealing with FCC type materials
however these are neither fully developed nor supported at this
point. These FCC mobility functions are:

: "FCC_0"
: "FCC_2"

For a list of the control parameters related to the mobility
of dislocations, see the [[#Material and mobility parameters:|"Material and Mobility Parameters" section]] of the Appendix detailing the control file parameters.
Currently the default values of all mobility related parameters
correspond to tantalum at a temperature of 600 K and a
pressure of 0GPa.

=== BCC_0 Mobility: ===

In BCC metals, screw dislocations do not dissociate into partial
dislocations the same way they do in FCC metals, therefore, for
BCC crystals we do not assign glide plane normals to screw
dislocations. Instead, screw dislocations are given the same
mobility in all directions perpendicular to the line. This
isotropic mobility for screws mimics the "pencil-glide" behavior
of dislocations observed in BCC metals at elevated temperatures.
At the same time, the drag coefficient for non-screw segments
will remain anisotropic with respect to glide and climb.

For details on this mobility module, refer to the paper:

:<ParadisDir>/Docs/ParaDiSAlgorithm.pdf

=== BCC_0b Mobility: ===

The BCC_0b mobility module is nearly a duplicate of BCC_0 with
the exception that the movement of discretization nodes along
the dislocation lines has been dampened.

=== TBD ===

=== FCC_0 Mobility: ===

This module attempts to simulate easy glide in FCC systems. The
glide plane is limited to one of the [111] planes, and cross-slip
is not permitted. Also, no crystallographic information is
used in the dislocation core reactions and hence junction formation
can take place even slightly off the zone axis.

Reminder: This mobility module is not fully developed or supported.

=== FCC_2 Mobility: ===

TBD

---------------------------------------------------------------------

== Material Properties ==

=== Specifying Material Properties ===

All material specific properties are set via the control
file parameters. If not specified, defaults will correspond
to tantalum at a temperatue of 300 K and pressure of 0GPa.

See the [[#Material and mobility parameters:|"Material and mobility parameters" section]] of
Appendix 1 for a list of the material related parameters.

---------------------------------------------------------------------

== Far-Field Dislocation Interactions ==

=== Fast Multipole for Far-Field Interactions ===

The FMM algorithm is enabled within the code via the <fmEnabled>
toggle in the control file. The order of the multipole and
Taylor expansions used by the FMM algorithm are set via the
<fmMPOrder> and <fmTaylorOrder> control parameters respectively.
As a general rule, the taylor expansion order should be around
twice that of the multipole expansion order. One additional
control parameter [[#FMM controls|<fmCorrectionTbl>]] specifies the name of the
file containing the table used by the FMM code to adjust the
stress calculated by the FMM for multiple periodic images.

It is important to note that the file indicated by <fmCorrectionTbl>
must be built with the same multipole order, Taylor expansion order,
and Poisson value (<pois> control parameter) specified for a
simulation. An appropriate correction table may be generated
via the 'ctablegen' utility (See the section on Utilities for
details on the use of 'ctablegen'), although a correction table
matching the code's default control parameter settings *may* have
been provided in the code release as:

: <ParadisDir>/inputs/fm-ctab.Ta.600k.0GPa.m2.t5.dat

The use of a Fast Multipole Method (FMM) for calculating the
far-field forces is based on formulae for generating and evaluating
multipole expansions and a few translation theorems. A very
general description can be found below, but for details refer
to the following paper included with the source release.

:<ParadisDir>/docs/ParaDiSAlgorithm.pdf

The general FMM algorithm consists of the following steps:

# Construct multipole moments:
#: Each domain (CPU) calculates the contributions of its dislocation segments to the multipole moments of the FMM subcells to which those segments belong, and communicates those contributions to the domain that owns the FMM subcell. Each domain that owns an FMM subcell sums all the contributions for that subcell together. <bf>
# Upward pass:
#: Starting at the lowest layer of the FMM hierarchy, each domain collects and sums the contributions to the multipole moments for each of the FMM subcells it owns from the eight child cells and the calculates the upward pass translation of its multipole moments and communicates the result to the domain owing the subcell's parent, until the top of the hierarchy is reached.
# Transverse translations:
#: The multipole moments from 189 cells that are outside the nearest neighbor distance of the target cell but inside the nearest neaighbor distance of its parent are collected by the domain owning the target cell and their contributions to the Taylor series expansion of the stress filed in target is calculated.
# PBC correction:
#: The domain that owns the FMM cell at the highest level of the FMM hierarchy calculates the Taylor series expansion of the stress state due to periodic images of the system (using [[#FMM controls|table]] specified in the <fmCorrectionTbl> parameter).
# Downward pass:
#: Starting with the highest level of the FMM hierarchy, each domain that owns an FMM subcell sums the contributions from its parent to its Taylor series expansion of the stress from step 3 and then calculates the downward pass translation of the stress for each one of its child cells and sends the results to the domain owning the child subcells until the bottom of the hierarchy is reached.
# Each domain that owns a subcell at the lowest level of the FMM hierarchy communicates the Taylor series expansions of the stress field to the domains intersecting the subcell.

=== Non-FMM Far-Field Interactions ===

The use of the FMM in ParaDiS can be disable by setting the control
parameter <fmEnabled> to 0. When FMM is disabled, ParaDiS requires
additional tables used to factor in the far-field stresses from
distant cells and periodic images of the system. The names of the
files containing the tables are specified via the <Rijmfile> and
<RijmPBCfile> control parameters. These tables can be generated
using the 'stresstablegen' utility (see [[#Creating Far-Field Stress Tables with 'stresstablegen'|Utilities section]] for
details), although copies *may* have been provided in the code
release as:

: <ParadisDir>/inputs/Rijm.cube.out
: <ParadisDir>/inputs/RijmPBC.cube.out

This method essentially lumps all dislocations in a cell into a
'super-dislocation' where the cell's dislocations are represented
as an expansion of the dislocation multipoles. The remote stress
for a segment in a given cell is then calculated from two
components. The first is the sum of the stresses resulting from
expansions from all remote cells (i.e. neither the current cell
nor any of its 26 immediate neighbors) and the stress from all
periodic images of those remote cells. The second component
consists of the stress from only the periodic images of the local
cells (i.e. the current cell and its immediate neighbors).

This method is can be faster for smaller simulations but unlike
the FMM, its performance does not scale well as the size of
a simulation increases in both dislocation density and number
of cells.

---------------------------------------------------------------------

== Discretization (Remesh) ==

=== Selecting a Discretization Method ===

The nature of DD simulations is such that the total length
of dislocation lines can increase several orders of magnitude.
Hence, rediscretization of the dislocations is an absolutely necessary
components of ParaDiS simulations. The goal of the rediscretization
is to optimize the numerical description of the continuous dsilocation
line geometry so that a given level of accuracy is achieved with the
fewest degrees of freedom. For regions of high curvature, an optimal
distribution of nodes will place nodes more closely together than
in regions of lower curvature.

The level of accuracy is tied to the control parameters <maxSeg>
and <minSeg> which define the maximum and minimum segment lengths (in
units of b) respectively. The smaller the maximum segment length, the
higher the accuracy.

A number of rediscretization version have been developed and
tested, although only versions 2 and 3 are currently supported.
The rediscretization version to use can be selected through
the control parameter <remeshRule>.

=== Remesh Version 2 ===

This method achieves rediscrtization through two types of
operations; mesh coarsening and mesh refinement (removing and
adding discretization nodes respectively).

This involved defining both minimum and maximum discretization areas
(A_min and A_max) based on the simulation minimum and maximum
segment lengths <minSeg> and <maxSeg>. Then for each discretization
node (i.e. a node with no more than two associated segments) a
discretization area (A_node) is calculated. This area is defined
as the triangle with vertices at the node and its two neighbors.
When the discretization area associated with a node A_node < A_min
the node is removed (coarsened out). Conversely, if the area
A_node > A_max, the local discretization is refined by bisecting
both segments attached to the node.

For additional information, refer to the following paper included
with the ParaDiS source release:

: <ParadisDir>/docs/ParaDiSAlgorithm.pdf

=== Remesh Version 3 ===

This rediscretization method is identical to type 2 with
the exception that during mesh refinement the inserted
nodes are not placed at the exact center of the segment
being bisected. Instead, the algorithm treats the three
initial nodes as if they were on an arc and places the
new nodes at the center of the segments of the arc.

The rationale behind this is that in simulations using
long segments and/or high stress, a new node added at the
center of a segment in a region of high curvature will
not be optimally placed. This new node may immediately
accelerate quickly toward its optimal position then
decelerate as it nears that position. This behavior
can severly impact the simulatuion timesteps. By placing
the new nodes on an arc, the initial stress on the new
nodes will not be as high, keeping the motion of the node
similar to that of the surrounding nodes. Hence, no
detrimental effects on the timestep.

---------------------------------------------------------------------

== Simulation Timestepping ==

=== Timestep Controls ===

Two timestepping algorithms are provided in the ParaDiS code.
The <timestepIntegrator> control parameter is used to select
the desired algorithm. The currently supported algorithms
are:

: "trapezoid"
: "forward-euler"

The default timestep integrator is the "trapezoid" integrator.
There are several general control parameters used in conjunction
with any selected timestep intergrator, and several that are unique
to specific integrators. The general control parameters are
<deltaTT> which specifies the duration of the previous timestep,
<nextDT> which indicates the desired timestep to attempt the next
timestep, and <maxDT> which specifies the maximum timestep duration
permitted.

=== Timestep Integrators ===

==== Trapezoid ====

This implicit integrator is a mix of the Euler-Forward and
Euler-Backward methods. This method is unconditionally
stable, but requires an iterative process that may involve
multiple nodal force and velocity calculations. The
additional expense of the multiple calculations, however,
is usually offset by the gains from the larger timesteps
compared to explicit methods such as the forward euler
integrator.

The algorithm uses the current nodal velocities to reposition
each node, then recalculates forces and velocities for the
nodes at their new positions. A positioning 'error' is
calculated for each node based on the current and previous
nodal position and velocity. If the positioning error of
any node is greater than the maximum permitted positioning
error as defined by the <rTol> control parameter, the
timestep will be decremented by a factor specified in the
<dtDecrementFact> control parameter and the process starts
again. On the otehr hand, if the positioning error of all
nodes is within the tolerance, the timestep is accepted
and the current timestep is multipled by the factor in the
<dtIncrementFactor> to be used as the initial timestep to
attempt the next cycle.

==== Forward Euler ====

The forward euler timestep integrator is relatively simple
and inexpensive in that it requires only a single calculation
of nodal force and velocities per timestep. Unfortunately,
the algorithm is subject to the Courant condition for
numerical stability and is limited to relatively small
timesteps. The size of the timestep is controlled by the
ratio between the length of the shortest segment and the
velocity of the fastest moving node. Additionally, the
<rmax> control parameter defines the maximum distance
any node is permitted to move in a single timestep, which
further limits the timestep duration. This 'rmax' distance
should be set such that no dislocation segment crosses
multiple simulation cells in a single timestep.

Note: This timestep integrator is NOT recommended.

---------------------------------------------------------------------

== Visualization ==

=== X-window display ===

ParaDiS provides a simple X-window display capability for
visualization and debugging of small scale simulations as well
as obtaining certain types of nodal data via the display window.

Unlike some of the other visualization capabilities, this one
must be enabled/disabled via the compile time flag "XLIB_MODE"
in the file <ParadisDir>/makefile.setup. The X-window support
is enabled by setting:

: XLIB_MODE = ON

and disabled by:

: XLIB_MODE = OFF

The default behavior is to have the X-window support enabled.

The <winDefaultsFile> control parameter can be used to specify default
visualization options and attributes such as view perspective, colors
and so on. Unless otherwise specified, this control parameter will
point to the following defaults file provided with the source release:

: <ParadisDir>/inputs/paradis.xdefaults

Once the X-window display is initiated, the view can be controlled
through the following single-key commands:

Key Command Description
--- -------------------
<Home> Restores image to default view
<Esc> Terminates X-window display without terminating
the simulation
a Enable/disable aspect ratio changes. When enabled,
the Arrow keys alter the aspect ratio
c Enable/disable slice view of image. When enabled,
Up/Down Arrows control slice position, Left/Right
Arrows control slice thickness.
f Turn display frame on/off
p Pause/restart simulation
r Enable image rotation. When enabled, rotation can
be controlled via the mouse or Arrow keys.
s Enable display scaling. When enabled, the Arrow
keys control scaling size.
t Enable image translation. When enable,
the Arrow keys control translation direction.
<F10> Generate a postscript image of the display window.
File will be called <outputDir>/YshotNNNN where
'NNNN' is a sequence number incremented each time
a dump of the display window is generated and
<outputDir> is the directory specified by the
<dirname> control file parameter.

Additionally, clicking the mouse on a nodal point in the X-window
image will cause the following information to be written to the
terminal device (not the X-window display):

* relative position (x,y) on the X-window display
* node ID (domainID,nodeindex)
* number of segments (arms) associated with the node
* simulation coordinates (x,y,z) of the node

=== Gnuplot ===

ParaDiS is capable of producing output files formatted for use
with the gnuplot visualization package. This capability is
enabled via the <gnuplot> toggle in the control parameter file.
The frequency with which gnuplot files will be generated is
controlled by the settings of the <gnuplotfreq> and <gnuplotdt>
parameters.

When this capability is enabled, the code will periodically
create a set of gnuplot output files in the directory
<outputDir>/gnuplot where <outputDir> is the directory
specified by the <dirname> control file parameter. The
naming convention used for these files is:

: <outputDir>/gnuplot/box.in
: <outputDir>/gnuplot/0tNNNN[.SEQ]

where
<TABLE CELLPADDING=3 >
<TR valign="top">
<TD ALIGN="LEFT">     </TD>
<TD ALIGN="LEFT">NNNN</TD>
<TD ALIGN="LEFT">     </TD>
<TD ALIGN="LEFT">is a sequence number begining at '0001' and incremented each time a gnuplot file set is written.
</TD></TR>
<TR valign="top">
<TD ALIGN="LEFT">     </TD>
<TD ALIGN="LEFT">SEQ</TD>
<TD ALIGN="LEFT">     </TD>
<TD ALIGN="LEFT">is a sequence number included only when gnuplot files are being written in parallel (i.e. the <numIOGroups> control parameter is greater than 1) <SEQ> will range from zero to <numIOGroups>-1.
</TD></TR>
</TABLE>

In addition, at program termination, an extra set of gnuplot
files will be created. This set will be generated regardless
of the specified dump frequency in order to provide an image
of the final configuration. This set will be named with the
slightly different naming convention:

: <outputDir>/gnuplot/gnuplot.final[.SEQ]

The 'box.in' data file will contain data for plotting the boundaries
of the simulation space, while the '0t*' files contain the coordinate
pairs defining each unique dislocation segment.

NOTE: When gnuplot data is being written in parallel
(i.e. <numIOGroups> is larger than 1), the dislocation segment
data is spread over the file segments. These file segments
can be combined into a single file for display in gnuplot
via the <ParadisDir>/tools/stitch tool. (See description of
[[#stitch|'stitch']] tool for details.)

To aid in visualizing the dislocation configuration, a file
containing commands to set some useful gnuplot options has
been provided; This file is located at:

: <ParadisDir>/inputs/gnuplot.cmds

For example, to view the dislocation structure contained in the
gnuplot data file 0t0001 you could start gnuplot interactively
and execute the commands:

gnuplot> load '<ParadisDir>/inputs/gnuplot.defaults'
gnuplot> splot 'box.in' with lines, '0t0001' w lines

A second gnuplot command file has been provided as an example
of displaying a sequence of gnuplot files. This file is
located at:

: <ParadisDir>/inputs/gnuplot.movie

This file has the neccesary commands to plot the sequence
of files beginning with 0t0001 and ending with 0t1000. After
starting gnuplot, simply load this file with:

gnuplot> load '<ParadisDir>/inputs/gnuplot.movie'

This will initiate the plot of the first file, and thereafter,
simply hitting return will cause gnuplot to move to the next
file in the sequence.

For details on using gnuplot, refer to the gnuplot manual or
enter 'help' from the gnuplot interactive prompt.

=== Tecplot ===

ParaDiS is capable of producing output files formatted for use
with the commercial visualization package Tecplot. This
capability is enabled via the <tecplot> toggle in the control
parameter file. The frequency with which tecplot files will
be generated is controlled by the settings of the <tecplotfreq>
and <tecplotdt> parameters.

When this capability is enabled, the code will periodically
create a set of tecplot output files in the directory
<outputDir>/tecplot where <outputDir> is the directory
specified by the <dirname> control file parameter. The
naming convention used for these files is:

: <outputDir>/tecplot/tecdataNNNN[.SEQ]

where
<TABLE CELLPADDING=3 >
<TR valign="top">
<TD ALIGN="LEFT">     </TD>
<TD ALIGN="LEFT">NNNN</TD>
<TD ALIGN="LEFT">     </TD>
<TD ALIGN="LEFT">is a sequence number begining at '0001' and incremented each time a tecplot file set is written.
</TD></TR>
<TR valign="top">
<TD ALIGN="LEFT">     </TD>
<TD ALIGN="LEFT">SEQ</TD>
<TD ALIGN="LEFT">     </TD>
<TD ALIGN="LEFT">is a sequence number included only when tecplot files are being written in parallel (i.e. the <numIOGroups> control parameter is greater than 1) <SEQ> will range from zero to <numIOGroups>-1.
</TD></TR>
</TABLE>

In addition, at program termination, an extra set of tecplot
files will be created. This set will be generated regardless
of the specified dump frequency in order to provide an image
of the final configuration. This set will be named with the
slightly different naming convention:

: <outputDir>/tecplot/tecdata.final[.SEQ]

The generated tecplot output has specific headers to assign the
variables and time frames (zones) and should look something like
this:

...
variables = X,Y,Z,V1,V2,V3,V4,V5,V6,V7,V8
zone i = 54 F=POINT
-4000.0 500.0 6000.0 133.1 612.4 -612.3 0.0000 0.0000 0.0000 1 3
-3866.9 1112.4 5387.7 -133.1 -612.4 612.3 0.0000 0.0000 0.0000 1 3
471.0 -5132.6 11632.3 -1712.7 -48.8 48.9 0.0090 -0.0918 0.0918 2 3
...

The first line defines the variables to reconstruct the dislocation
configuration. X Y and Z specify the nodal coordinates, V1 V2 and
V3 define arm vectors to the neighboring nodes. These 6 variable
are used to represent dislocation segments as combinations of points
and vectors in tecplot. The V4 V5 and V6 represent the nodal velocity
vector, V7 indicates the number of segments associated with the node
and V8 indicates a burgers vector type.

NOTE: When tecplot data is being written in parallel
(i.e. <numIOGroups> is larger than 1), the headers will only be
included in the first file segment with the remainder of the data
spread over the file segments. These file segments can be combined
into a single file for display in tecplot via the
<ParadisDir>/tools/stitch tool. (See description of [[#stitch|'stitch']]
tool for details.)

For details on using tecplot, refer to the tecplot manual or select
the 'Help' menu in tecplot.

=== Povray ===

If the <povray> toggle is set in the control file,
ParaDiS will periodically generate files containing
dislocation segment data formatted for use with the POVRAY
(Persistence of Vision(tm) Ray Tracer) tool. The frequency
with which these files will be generated is controlled by
the settings of the <povrayfreq> and <povraydt> parameters.

Note: These files contain the main data to be processed by
povray, but must be post-processed via the
'genPovrayFrames' tool (See [[#genPovrayFrames|section]] on Tools)
which will create the final povray input file
containing the segment data embedded within a
proper framework of povray settings and commands.

When this capability is enabled, the code will periodically
create a set of files in the directory <outputDir>/povray
where <outputDir> is the directory specified by the <dirname>
control file parameter. The naming convention used for
these files is:

: <outputDir>/povray/povframeNNNN[.SEQ]

where
<TABLE CELLPADDING=3 >
<TR valign="top">
<TD ALIGN="LEFT">     </TD>
<TD ALIGN="LEFT">NNNN</TD>
<TD ALIGN="LEFT">     </TD>
<TD ALIGN="LEFT">is a sequence number begining at '0001' and incremented each time a povray frame file set is written.
</TD></TR>
<TR valign="top">
<TD ALIGN="LEFT">     </TD>
<TD ALIGN="LEFT">SEQ </TD>
<TD ALIGN="LEFT">     </TD>
<TD ALIGN="LEFT">is a sequence number included only when povray files are being written in parallel (i.e. the <numIOGroups> control parameter is greater than 1) <SEQ> will range from zero to <numIOGroups>-1.
</TD></TR>
</TABLE>

In addition, at program termination, an extra set of povray
frame files will be created. This set will be generated
regardless of the specified dump frequency in order to provide
an image of the final configuration. This set will be named
with the slightly different naming convention:

: <outputDir>/povray/povray.final[.SEQ]

NOTE: When povray data is being written in parallel
(i.e. <numIOGroups> is larger than 1), the dislocation segment
data is spread over the file segments. If desired, these file
segments may be combined into a single file for post-processing
via the <ParadisDir>/tools/stitch tool. (See description
of [[#stitch|'stitch']] tool for details.)

As stated above, these files must be post-processed via the
'genPovrayFrames' tool (See [[#genPovrayFrames|section]] on Tools) which will
create the final povray input file containing the segment
data embedded within a proper framework of povray settings
and commands. This tool is capable of dealing with single
or segmented 'povframe*' files.

For details on using povray, refer to the povray manual.

=== Terascale Browser ===

TBD

=== Postscript ===

If the <psfile> toggle is set in the control file,
ParaDiS will periodically generate a postscript file
containing an image of the current state of the system.
The frequency with which the postscript files are
written is determined by the settings of the
<psfilefreq> and <psfiledt> control file parameters.
All files will be located in the directory <outputDir>
where <outputDir> is the directory specified by the
<dirname> control file parameter.

All files will be named with the following convention:

: <outputDir>/YshotNNNN.ps

where NNNN is a sequence number beginning with zero and incremented
each time another postscript file is written.

---------------------------------------------------------------------

== Output ==

=== Restart files ===

Periodic creation of ParaDiS restart files is enabled via
the <savecn> toggle in the control file. The frequency with
which restart files are written is determined by the settings
of the <savecnfreq> and <savecndt> control file parameters.

When enabled, the code will periodically generate restart
file which will be located in the directory <outputDir>/restart
where <outputDir> is the directory specified by the <dirname>
control file parameter.

The naming convention used for these restart files is:

<TABLE CELLPADDING=3 >
<TR valign="top">
<TD ALIGN="LEFT">     </TD>
<TD ALIGN="LEFT"><outputDir>/restart/rsNNNN</TD>
<TD ALIGN="LEFT">     </TD>
<TD ALIGN="LEFT"># control parameter file
</TD></TR>
<TR valign="top">
<TD ALIGN="LEFT">     </TD>
<TD ALIGN="LEFT"><outputDir>/restart/rsNNNN.data[.SEQ]</TD>
<TD ALIGN="LEFT">     </TD>
<TD ALIGN="LEFT"># nodal data file
</TD></TR>
</TABLE>
where
<TABLE CELLPADDING=3 >
<TR valign="top">
<TD ALIGN="LEFT">     </TD>
<TD ALIGN="LEFT">NNNN</TD>
<TD ALIGN="LEFT">     </TD>
<TD ALIGN="LEFT">is a sequence number begining at '0001' and incremented each time a restart file set is written.
</TD></TR>
<TR valign="top">
<TD ALIGN="LEFT">     </TD>
<TD ALIGN="LEFT">SEQ</TD>
<TD ALIGN="LEFT">     </TD>
<TD ALIGN="LEFT">is a sequence number included only when restart files are being written in parallel (i.e. the <numIOGroups> control parameter is greater than 1) <SEQ> will range from zero to <numIOGroups>-1.
</TD></TR>
</TABLE>

Each time a restart file set is written, the name of the
control parameter file will also be written into the file:

: <outputDir>/latest_restart

Additionally, when creation of restart files is enabled, an
additional restart file pair named 'restart.cn' and restart.data'
will be written at program termination even if the cycle is not
a multiple of the <savecnfreq> control parameter.

=== Property Outputs ===

==== Enabling Properties Output ====

The code has the capability to produce files containing
various dislocation properties. This capability is enabled
via the <saveprop> toggle in the control file. The
frequency with which the property data is written is
determined by the settings of the <savepropfreq> and
<savepropdt> control file parameters.

When this capability is enabled, the code will generate
and periodically append the properties data to one or more of
the following files which will be located in the directory
<outputDir>/properties, where <outputDir> is the directory
specified by the <dirname> control file parameter.

==== Property Files ====

===== density =====

Note: burgVolFactor converts from length in units of B, to density
in units of meters

This file contains the following columns of data:

# plastic strain
# strain
# dislocation density
# deleted dislocation density
#: (lost through annihilation, junction formation, etc)
#: (density lost since last dump of data)
# average dislocation velocity‡
# std. deviation of dislocation velocities‡
# density file version number
# dislocation density for segments of specific groupings of burgers vectors (see below)*

‡ These items will be calculated only if
the "VEL_STATISTICS" pre-processor macro was
defined during compilation. Otherwise these
values will be zeroes.

For BCC simulations:
Column Burgers vector types
8 [ 1 1 1] [-1-1-1]
9 [-1 1 1] [ 1-1-1]
10 [ 1-1 1] [-1 1-1]
11 [ 1 1-1] [-1-1 1]
12 [ 1 0 0] [-1 0 0] [ 0 1 0]
[ 0-1 0] [ 0 0 1] [ 0 0-1]

For FCC simulations:
Column Burgers vector types
8 [ 1 1 0] [-1-1 0]
9 [-1 1 0] [ 1-1 0]
10 [ 1 0 1] [-1 0-1]
11 [-1 0 1] [ 1 0-1]
12 [ 0 1 1] [ 0-1-1]
13 [ 0-1 1] [ 0 1-1]
14 all others

===== time_Plastic_strain =====

This file contains the following two columns of data:

# elapsed simulation time
# plastic strain

===== stress_Plastic_strain =====

This file will only be generated if the user specified
a loadType of 1 (constant strain rate) or 4 (cyclic
loading). The file contains the following two columns
of data:

# plastic strain
# stress

===== stress_Total_strain =====

This file will only be generated if the user specified
a loadType of 1 (constant strain rate) or 4 (cyclic
loading). If the user specified a constant strain
rate, this file contains:

# strain
# stress

If the user specified cyclic loading, this file contains:

# net accumulated strain
# stress
# elapsed simulation time
# number of loading cycles

===== alleps =====

This file contains the following 9 columns of data:

{|
|-
| align=right | 1.||simulation timestep number
|-
| align=right | 2.||elapsed simulation time
|-
| align=right | 3-8.||plastic strain components‡
|-
| align=right | 9.||dislocation density
|}

‡ from plastic strain tensor matrix, elements [0][0], [1][1], [2][2], [1][2], [0][1], and [0][2]

===== epsdot =====

This file contains the 2 columns of data:

# elapsed simulation time
# plastic strain rate

=== Flux Decomposition ===

ParaDiS has the capability to produce files containing
flux decomposition information for the simulation.
This capability is enabled via the <fluxfile> control
file toggle. The frequency with which the flux
data is written is determined by the settings of
the <fluxfreq> and <fluxdt> control file parameters.

When this capability is enabled the code will generate
and periodically append the flux data to two sets of
files that will be located in the directory
<outputDir>/fluxdata where <outputDir> is the directory
specified by the <dirname> control file parameter.

Each set contains four files, one file per burgers vector.
Files *b1, *b2, *b3, and *b4 contain statistics for burgers
vector types [111], [-111], [1-11], and [11-1] respectively.

The first set of files (Ltot_b1, Ltot_b2, Ltot_b3 and
Ltot_b4) consist of the following 9 columns of data:

# Plastic strain
# Strain,
# Screw density
# Edgedensity1
# Edgedensity2
# Edgedensity3
# Sum of edge Densities (4+5+6)
# Total system EdgeDensity from all Ltot files
# Total system screw density from all Ltot files

The second set of files (fluxtot_b1, fluxtot_b2, fluxtot_b3 and
fluxtot_b4) consist of the following 9 columns of data:

{|
|-
| align=right | 1.||Plastic Strain
|-
| align=right | 2.||Strain
|-
| align=right | 3.||Flux due to climb motion
|-
| align=right | 4-6.||Flux created by edge components on three planes (See below.)
|-
| align=right | 7-9.||Flux created by screw dislocation on three planes (See below.)
|}

For b1 = 1/2[1 1 1]
<ol start="4">
<li> ( 0 1 -1), [-2 1 1]</li>
<li> (-1 0 1), [ 1 -2 1]</li>
<li> ( 1 -1 0), [ 1 1 -2]</li>
<li> ( 0 1 -1), [-2 1 1]</li>
<li> (-1 0 1), [ 1 -2 1]</li>
<li> ( 1 -1 0), [ 1 1 -2]</li>
</ol>
For b2 = 1/2[-1 1 1]
<ol start="4">
<li> ( 0 1 -1), [ 2 1 1] </li>
<li> ( 1 0 1), [ 1 2 -1] </li>
<li> ( 1 1 0), [ 1 -1 2] </li>
<li> ( 0 1 -1), [ 2 1 1] </li>
<li> ( 1 0 1), [ 1 2 -1] </li>
<li> ( 1 1 0), [ 1 -1 2] </li>
</ol>
For b3 = 1/2[1 -1 1]
<ol start="4">
<li> ( 0 1 1), [ 2 1 -1] </li>
<li> ( 1 0 -1), [ 1 2 1] </li>
<li> ( 1 1 0), [-1 1 2] </li>
<li> ( 0 1 1), [ 2 1 -1] </li>
<li> ( 1 0 -1), [ 1 2 1] </li>
<li> ( 1 1 0), [-1 1 2] </li>
</ol>
For b4 = 1/2[1 1 -1]
<ol start="4">
<li> ( 0 1 1), [ 2 -1 1] </li>
<li> ( 1 0 1), [-1 2 1] </li>
<li> ( 1 -1 0), [ 1 1 2] </li>
<li> ( 0 1 1), [ 2 -1 1] </li>
<li> ( 1 0 1), [-1 2 1] </li>
<li> ( 1 -1 0), [ 1 1 2] </li>
</ol>

=== Pole figures ===

TBD

=== Velocity files ===

If the <velfile> toggle is set in the control file,
ParaDiS will periodically generate a set of files containing
velocity information about each unique dislocation node
in the system. The frequency with which the velocity
data is written is determined by the settings of the
<velfilefreq> and <velfiledt> control file parameters.
All files will be located in the directory <outputDir>/velocity
where <outputDir> is the directory specified by the
<dirname> control file parameter.

All files will be named with the following convention:

: <outputDir>/velocity/velNNNN[.SEQ]

where
<TABLE CELLPADDING=3 >
<TR valign="top">
<TD ALIGN="LEFT">     </TD>
<TD ALIGN="LEFT">NNNN</TD>
<TD ALIGN="LEFT">     </TD>
<TD ALIGN="LEFT">is a sequence number based on the <velfilecounter> control parameter and is incremented each time another velocity file is written.
</TD></TR>
<TR valign="top">
<TD ALIGN="LEFT">     </TD>
<TD ALIGN="LEFT">SEQ </TD>
<TD ALIGN="LEFT">     </TD>
<TD ALIGN="LEFT">is a sequence number included only when velocity data is being written in parallel (i.e. <numIOGroups> control parameter is greater than 1. SEQ will range from zero to <numIOGroups>-1.
</TD></TR>
</TABLE>

In addition, at program termination, an extra set of velocity
files will be created. This set will be generated regardless
of the specified dump frequency in order to provide an image
of the final configuration. This set will be named with the
slightly different naming convention:

: <outputDir>/velocity/vel.final[.SEQ]

NOTE: When velocity data is being written in parallel
the dislocation segment data is spread over the file segments.
These file segments can be combined into a single file via
the <ParadisDir>/tools/stitch tool. (See [[#stitch|section]] on Tools
for details)

The contents of the velocity files consist of 4 columns
of data for each unique dislocation segment. Those
columns are:

{|
|-
| align=right | 1-3.||Velocity components (x,y,z)
|-valign="top"
| align=right | 4.|| +1 if contributing to strain rate <br> -1 if moving in opposite direction
|}

=== Segment files ===

If the <armfile> toggle is set in the control file,
ParaDiS will periodically generate a set of files containing
information about each unique dislocation segment
in the system. The frequency with which the segment
(or arm) files are written is determined by the settings
of the <armfilefreq> and <armfiledt> control file parameters.
All files will be located in the directory <outputDir>/armdata
where <outputDir> is the directory specified by the
<dirname> control file parameter.

All files will be named with the following convention:

: <outputDir>/armdata/armNNNN[.SEQ]

where
<TABLE CELLPADDING=3 >
<TR valign="top">
<TD ALIGN="LEFT">     </TD>
<TD ALIGN="LEFT">NNNN</TD>
<TD ALIGN="LEFT">     </TD>
<TD ALIGN="LEFT">is a sequence number based on the <armfilecounter> control parameter and is incremented each time another arm file is written.
</TD></TR>
<TR valign="top">
<TD ALIGN="LEFT">     </TD>
<TD ALIGN="LEFT">SEQ</TD>
<TD ALIGN="LEFT">     </TD>
<TD ALIGN="LEFT">is a sequence number included only when arm data is being written in parallel (i.e. <numIOGroups> control parameter is greater than 1. SEQ will range from zero to <numIOGroups>-1.
</TD></TR>
</TABLE>

In addition, at program termination, an extra set of arm
files will be created. This set will be generated regardless
of the specified dump frequency in order to provide an image
of the final configuration. This set will be named with the
slightly different naming convention:

: <outputDir>/armdata/arm.final[.SEQ]

NOTE: When arm data is being written in parallel
the dislocation segment data is spread over the file segments.
These file segments can be combined into a single file via
the <ParadisDir>/tools/stitch tool. (See [[#stitch|section]] on Tools
for details)

The contents of the arm files consist of 10 columns
of data for each unique dislocation segment. Those
columns are:

{|
|-
| align=right | 1-3.||Burgers vector components
|-
| align=right | 4-6.||Line direction vector
|-
| align=right | 7.||Segment length
|-
| align=right | 8-10.||Coordinates of node 'owning' the segment
|}

=== Density Field file ===

If all components of the <savedensityspec> control parameter
are set to positive values in the control file, ParaDiS
will (at program termination) create a file containing a
3D dislocation density field formatted for use with the
VASP Data Viewer (vaspview). The three components of
the <savedensityspec> parameter specify the granularity
of the density field in the X, Y and Z dimensions
respectively. The density field will be written to the
file:

: <outputDir>/densityfield.out

Warning: This will overwrite any existing density field
file of the same name!

The VASP Data Viewer is publicly available on the web
for non-commercial use. For details on the product,
download the VASP Data Viewer from the web and refer
to the accompanying documentation.

---------------------------------------------------------------------

== Utilities ==

=== Creating Initial Dislocations with 'paradisgen' ===

The paradisgen utility is capable of generating initial
dislocations suitable for a paradis simulation. The command
line options for paradisgen control the type of dislocations,
number of dislocations, size of the simulation box, and so
on. See "Examples" below for sample executions of this utility.

The command line format for paradisgen is:

paradisgen [-cubel <cubelength>] [-help] [-hexsize <size>] \
[-maxseg <maxseglen] [-nchains <numchains>] \
[-nloops <numloops>] [-outfile <filename> \
[-radius <radius>] [-seed <seedval>] \
[-type <configtype>]

All command line options may be abbreviated to the shortest
non-ambiguous abbreviation of the option. Descriptions of
the command lines options are as follows:

<pre>
-cubel <cubelength> Defines the size of the simulation cube
in units of b. Minimum and maximum problem
space coordinates will be 0.5*cubel and
-0.5*cubel respectively. If not specified
this will default to 35000b (approx.
10 micron).

-help Causes the utility to display the command line
format and option descriptions then terminate.

-hexsize <size> Defines the radius (in units of b) for the
hexagonal interstitial loops. This option is
used only when the selected dislocation type
is 'fcc-irrad'.

-looptype <ltype> Specifies the types of prismatic loops to
generate. If not specified, this value
will default to zero. Valid values are:

0 == mixture of [1 1 1] and [1 0 0] types
1 == all [1 1 1] type loops
2 == all [1 0 0] type loops

This option is only used when the selected
dislocation type is 'prismatic-loop'.

-maxseg <length> Defines the maximum desired segment length
in units of b. Initial dislocations will
be discretized so no segment is longer than
this value. If not specified this value
defaults to 500.

-nchains <numchain> Indicates the number of dislocation lines
to create. This value is ignored when the
selected dislocation type is 'prismatic-loop',
and when the type is 'fcc-perfect-loop',
this value must be a multiple of 12. If
not specified, this value defaults to 2.

-nloops <numloops> Specifies the number of loops to create when
the selected dislocation type is
'prismatic-loop' or 'fcc-irrad'. If not
specified, this value defaults to 1000.

-nsegs <numsegs> Specifies the number of segments into which
a prismatic loop will be discretized. This
option is only used when the selected
dislocation type is 'prismatic-loop'. If
not specified, this value defaults to
(2*PI*radius)/(maxseg/2).

-outfile <filename> Name of the ParaDiS data file to be created.
If not specified, data will be written
into a file called 'paradis.data'.

-radius <radius> Radius (in units of b) of prismatic loops.
This option is only used when the selected
dislocation type is 'prismatic-loop'. If
not specified, this value defaults to maxseg/2.

-seed <seed> Specifies a value to seed the random number
generator. Using the same seed value for
multiple executions of paradis (for which
all other options are identical) insures
creation of an identical configuration.

-type <type> Specifies the type of dislocations to create.
This type can be a name or the integer value
corresponding to the name. Valid types are:

0 or 'screw' BCC screw dislocations.
Assumes periodic boundary
conditions are enabled.
1 or 'finite-mixed' A mixture of BCC screw and
edge dislocations
terminating at the edges
of the cubic problem
space. This should not
be used with periodic
boundary conditions.
2 or 'prismatic-loop' BCC prismatic loops.
Assumes periodic boundary
conditions are enabled.
3 or 'fcc' FCC dislocations. Assumes
periodic boundary
conditions are enabled.
4 or 'fcc-irrad' Mixture of FCC
dislocations and hexagonal
interstitial loops.
Assumes periodic boundary
conditions are enabled.
5 or 'fcc-perfect-loop' Not fully implemented.

Examples:
---------

TBD
</pre>

=== Recomputing Domain Boundaries with 'paradisrepart' ===

The paradisrepart utility provides a mechanism by which to
replace the domain decomposition/partitioning in an
existing nodal data file with a new domain decomposition.
The utility will read the current nodal data, and use the
specified domain/cell geometries to attempt to partition
the domains such that the computational cost for each domain
will be roughly equivalent.

This utility is primarily used when it is necessary alter
the domain geometry or domain count for a simulation in
order to continue. In such a situation, the existing
domain decomposition would be thrown away and the ParaDiS
code would generate an initial uniform decomposition
and then over time converge on a more optimal decomposition.
Using this utility instead to generate a new decomposition
provides a much more reasonable starting point from allowing
the ParaDiS simulation to converge on an optimal decomposition
much more quickly.

The command line format for the paradisrepart utility is:

paradisrepart -infile <inputFile> \
-cells <xcells[,ycells,zcells]> \
-domains <xdoms[,ydoms,zdoms]> \
[-outfile <outputFile>] [-decompType <type>] \
[-help]

All command line arguments and options may be abbreviated to the
shortest non-ambiguous abbreviation of the option. Descriptions
of the command lines options are as follows:

<pre>
-infile <inputFile> Specifies the name of the nodal data file.
On success, the first nodal data file
segment will be copied to <inputFile>.bkup.
This command line argument is not optional.

-cells <xcells[,ycells,zcells]> Specifies the number of
cells in each dimension. If the
number of cells in the Y and Z dimensions
are not provided, they will default to the
same value as <xcells>. This command line
argument is not optional.

-domains <xdoms[,ydoms,zdoms]> Specifies the number of domains
in each dimension. If the number of
domains in the Y and Z dimensions are
not provided, they will default to the
same value as <xdoms>. This command line
argument is not optional.

-decompType <type> Specifies type of domain decomposition:
If not specified, defaults to 1. Valid
types are:

1 == Recursive Sectioning
2 == Recursive Bisectioning

-help Causes the utility to display the command
line format and option descriptions then
terminate.

-outfile <outputFile> Specifies the name of the file into which
to write the new domain decomposition. If
not specified, new domain decomposition
will be written into the file specified
by <inputFile>.

Examples:
---------
</pre>

=== Converting Control and Data File with 'paradisconvert' ===

The paradisconvert utility provides a mechanism by which
older format ParaDiS control and data files (and restart
files) may be converted to the current file formats.
This utility does recognize and handle segmented data files.

In most cases this utility will not be required since
ParaDiS is still able to recognize and handle *most* of
the older file formats. The only format the ParaDiS code
no longer recognizes is the truly ancient format associated
with the earliest incarnations of the code in which the
control file parameters and nodal data were included in
a single file. For these control files, the paradisconvert
utility will be needed.

The command line format for the paradisconvert utility is:

paradisconvert <controlFile> [dataFile]

where:
<TABLE CELLPADDING=3 >
<TR valign="top">
<TD ALIGN="LEFT">     </TD>
<TD ALIGN="LEFT">controlFile</TD>
<TD ALIGN="LEFT">     </TD>
<TD ALIGN="LEFT">Specifies the name of the control parameter file to be updated to the current format.
</TD></TR>
<TR valign="top">
<TD ALIGN="LEFT">     </TD>
<TD ALIGN="LEFT">dataFile</TD>
<TD ALIGN="LEFT">     </TD>
<TD ALIGN="LEFT">If the specified control file is the original ancient format including control parameters and nodal data in the single file, this argument is ignored. Otherwise, this specifies the base name of the nodal data file(s) to be converted. If not this argument is not provided, it will default to the same name as <controlFile> with any file name suffix removed and the '.data' suffix added.
</TD></TR>
</TABLE>

On success, the utility will rename the original files by appending
a '.bkup' suffix to the names, and create new control and data files
with the specified names. Note: for control parameter files which
include nodal data, a new data file will be generated under the
the name as <controlFile> with any file name suffix removed and
a '.data' suffix added.

<u>Examples:</u>

To convert the original format file 'restart.cn' containing
both control parameters and nodal data, execute:

paradisconvert restart.cn

The utility will generate the following files:

: restart.cn.bkup
: restart.cn
: restart.data

To convert a newer control parameter and data file pair with
the names 'rs0100' and 'rs0100.data' respective, execute either
of the following equivalent command lines:

paradisconvert rs0100
paradisconvert rs0100 rs0100.data

In both cases, the utility would generate the files:

: rs0100.bkup
: rs0100.data.bkup

: rs0100
: rs0100.data

To convert a newer control file <rs0100> and a set of segmented
data files with the names <rs0100.data.0>, <rs0100.data.1>, ...
<rs0100.data.7>, execute any of the following equivalent commands:

paradisconvert rs0100
paradisconvert rs0100 rs0100.data
paradisconvert rs0100 rs0100.data.0

In all of the above cases, the utility would generate the files

: rs0100.bkup
: rs0100.data.0.bkup
: rs0100.data.1.bkup
: ...
: rs0100.data.7.bkup

: rs0100
: rs0100.data.0
: rs0100.data.1
: ...
: rs0100.data.7

=== Creating the FMM Image Correction Table with 'ctablegen' ===

The 'ctablegen' utility is used to create an image correction
table needed when the FMM (Fast Multipole Method) has been enabled
by setting the <fmEnabled> toggle on in the control file. Since
the data in this file is dependent on the poisson ratio, shear
modulus, and orders of the multipole and taylor expansions, the
file must be created for the particular values of these items
used in the simulation.

Given the current defaults used by ParaDiS (as set in Param.c):

{|
|      ||align="left"| poisson ratio: ||align="center"| 3.327533e-01
|-
| ||align="left"| shear modulus: ||align="center"| 6.488424e+10
|-
| ||align="left"| multipole order: ||align="center"| 2
|-
| ||align="left"| taylor expansion order: ||align="center"| 5
|}

To create the FMM image correction table, you could execute
ctablegen from the main <ParadisDir> directory using the
following command line:

bin/ctablegen -nu 3.327533e-01 -mu 6.488424e+10 -mporder 2 -torder 5 -outfile \
inputs/fm-ctab.Ta.600K.0GPa.m2.t5.dat

NOTE: The generation of this table can take a significant
amount of time, therefore, a parallel version of the utility
(called ctablegenp) has also been provided. To execute the
table generation in parallel on 8 processors using mpirun as
a parallel program initiator, one could execute:

mpirun -np 8 bin/ctablegen -nu 3.327533e-01 -mu 6.488424e+10 -mporder 2 -torder 5 -outfile \
inputs/fm-ctab.Ta.600K.0GPa.m2.t5.dat

The locations of this file is specified in the control
parameter file via the <fmCorrectionTbl> parameter.

=== Creating Far-Field Stress Tables with 'stresstablegen' ===

The 'stresstablegen' utility is used to create tables needed
for calculating stress from distant cells and periodic images
of the system when FMM is disabled (i.e. <fmEnabled> is set
to zero). There are two required tables, one which factors
in stress from periodic images only and the other which factors
in stress from both the primary and period images.

To create the needed stress tables, execute the stesstablegen
utility twice from the main <ParadisDir> directory using the
following command lines:

bin/stresstablegen -nopbc -outfile inputs/Rijm.cube.out
and
bin/stresstablegen -pbc -outfile inputs/RijmPBC.cube.out

The locations of these files are specified in the control
parameter file via the <Rijmfile> and <RijmPBCfile> parameters
respectively.

---------------------------------------------------------------------

== Tools ==

=== genPovrayFrames ===

The genPovrayFrames tool is provided to post-process the
povray data files generated by ParaDiS when the <povray>
control parameter toggle has been set. This tool will
create an '*.pov' file containing the ParaDiS generated
data embedded in a proper framework of povray settings
and commands. The tool is located in the <ParadisDir>/tools
directory. For details on the use of this tool, see
the comments at the beginning of the script or execute:

<ParadisDir/tools/genPovrayFrames -help

=== gnuplot2povray ===

The gnuplot2povray tool is provided to post-process the
gnuplot data files generated by ParaDiS when the <gnuplot>
control parameter toggle has been set. This tool will
convert the data in the gnuplot files into a format
suitable for povray, and create an '*.pov' file containing
the converted data embedded in a proper framework of povray
settings and commands. The tool is located in the
<ParadisDir>/tools directory. For details on the use of
this tool, see the comments at the beginning of the script
or execute:

<ParadisDir/tools/gnuplot2povray -help

=== stitch ===

When ParaDiS is configured to enable parallel I/O
(i.e. the <numIOGroups> control parameter is greater
than 1), each of the following types of output
will be generated as a set of files rather than a
single output file.

: gnuplot files
: tecplot files
: segment/arm data
: povray files
: velocity data
: terascale browser files
: pole figures

Each file 'segment' will contain a portion of the full
data and will have a sequence number appended to the file
name.

Most utilities for processing these types of output, however,
expect the data in a single file, so the 'stitch' tool
has been provided in order to recombine these data file
segments into a single usable file as a post-processing
step. The tool can be found in the source release as:

: <ParadisDir>/tools/stitch

The command line for 'stitch is as follows:

stitch [-h] [-d dir | -f file]

where
<pre>
-h prints the usage information to stdout

-d <dir> specifies a directory the utility will
scan for any segmented output files that
need to be stitched together.

-f <file> specifies a base file name and the utility will
scan for the corresponding file segments (files
named <file>.N where N ranges from zero on up)
and stitch the segments into the single specified
base file name.
</pre>

NOTE: If neither a directory nor file name was provided
on the command line, the tool will behave as though
the caller specified the current directory on the command
line and perform as stated above.

== Appendix 1. Control Parameters ==

The following is a brief description of the valid control
file parameters. Also see the example control files contained
within the <ParadisDir>/tests directory.

The parameters have been grouped into the following categories, and
unless otherwise specified, units are in SI, and lengths are
normalized by burgers vector magnitude:

* Simulation cell and processor setup
* Simulation time and timestepping controls
* Discretization controls
* FMM controls
* Tables for non-FMM far-field forces
* Loading condition parameters
* Material and mobility parameters
* Velocity statistics and controls
* I/O controls and parameters
* Miscellaneous parameters

=== Simulation cell and processor setup: ===

{|class="wikitable" border="1" align="center"
|+ Table A1. Control parameters for simulation setup
! Parameter
! Type
! Description
|-
|align="center"| numXdoms, numYdoms, numZdoms ||align="center"| integer ||align="left"|
Defines the number of computational domains into which the problem space is partitioned in the corresponding dimensions.
|-
|align="center"| numXcells, numYcells, numZcells ||align="center"| integer ||align="left"|
Defines the number of cells in the corresponding dimension of the problem space. Cells are independent of the domain geometry and are used to determine boundaries at which far-field forces are computed rather than direct segment to segment forces.
|-
|align="center"| xBoundType, yBoundType, zBoundType ||align="center"| integer ||align="left"|
Defines the type of problem space boundaries in the corresponding dimension. Currently supported types are 0, and 1 for periodic and free surfaces respectively.
|-
|align="center"| xBoundMax, yBoundMax, zBoundMax ||align="center"| double ||align="left"|
If periodic boundaries are not enabled, defines the upper limit on coordinates of any dislocation nodes in the corresponding dimension. Value must be <= the respective maximum problem space coordinate specified in the nodal data file.
|-
|align="center"| xBoundMin, yBoundMin, zBoundMin ||align="center"| double ||align="left"|
If periodic boundaries are not enabled, defines the lower limit on coordinates of any dislocation nodes in the corresponding dimension. Value must be >= the respective minimum problem space coordinate specified in the nodal data file.
|-
|align="center"| decompType ||align="center"| Integer ||align="left"|
Specifies the type of domain decomposition to be used for a run. A value of one selects the old Recursive Sectioning (RS) algorithm, a value of 2 selects the Recursive Bisectioning (RB) decomposition algorithm. The default is currently the RS decomposition.
|-
|align="center"| DLBfreq ||align="center"| Integer ||align="left"|
Indicates the frequency (in cycles) at which Dynamic Load-Balancing is to be attempted. A value of zero indicates no load-balancing is to be done. Default is 3.
|}

=== Simulation time and timestepping controls ===

{|class="wikitable" border="1" align="center"
|+ Table A2. Time Control parameters
! Parameter
! Type
! Description
|-
|align="center"| cycleStart ||align="center"| integer ||align="left"|
Starting cycle number for the simulation.
|-
|align="center"| maxstep ||align="center"| integer ||align="left"|
Indicates the number of timesteps to execute before terminating.
|-
|align="center"| timeNow ||align="center"| double ||align="left"|
Current simulation time (in seconds).
|-
|align="center"| timeStart ||align="center"| double ||align="left"|
Initial simulation time (in seconds).
|-
|align="center"| timestepIntegrator ||align="center"| string ||align="left"|
Selects a timestep integration method. Valid methods are "trapezoid" and "forward-euler". The default value is "trapezoid".
|-
|align="center"| deltaTT ||align="center"| double ||align="left"|
Specifies the duration of the previous timestep in units of seconds.
|-
|align="center"| maxDT ||align="center"| double ||align="left"|
Specifies the maximum timestep permitted. Default is 1.0e-07.
|-
|align="center"| nextDT ||align="center"| double ||align="left"|
Specifies the timestep duration to attempt on the next cycle. The timestep integrator will adjust this value dynamically. Default is <maxDT>.
|-
|align="center"| dtDecrementFact ||align="center"| double ||align="left"|
Factor by which <delatTT> is mutiplied when cutting the timestep duration down. Must be between 0.0 and 1.0. Currently only used with the "trapezoid" integrator. Default is 0.5.
|-
|align="center"| dtExponent ||align="center"| double ||align="left"|
Exponent used in calculation of timestep increment when <dtVariableAdjustment> toggle is enabled. Currently used only with "trapezoid" timestep integrator.
|-
|align="center"| dtIncrementFact ||align="center"| double ||align="left"|
Maximum factor by which <deltaTT> is multiplied when incrementing the timestep. Must be at least 1.0. Default is 1.2.
|-
|align="center"| dtVariableAdjustment ||align="center"| integer ||align="left"|
Toggles ability to vary the increment by which the timestep is adjusted when the current timestep is determined to be too small. This will permit the timestep to be adjusted to a value between 1.0 and <dtIncrementFact> * <deltaTT>. Toggle is zero (off) by default. Used only with "trapezoid" integrator.
|-
|align="center"| rTol ||align="center"| double ||align="left"|
Maximum position error (in units of b) tolerated in the timestep integration. Only applies to the "trapezoid" integrator. Default is 0.25 * <rc>. The annihilation
distance is related to rTol(By default, it is set to 2*<rTol>)
|-
|align="center"| rmax ||align="center"| double ||align="left"|
Maximum distance (in units of b) a node is permitted to move in a single timestep. Not used if "trapezoid" timestep integrator used. Default is 0.5 * <minSeg>.
|}

=== Discretization controls: ===

{|class="wikitable" border="1" align="center"
|+ Table A3. Discretization control parameters
! Parameter
! Type
! Description
|-
|align="center"| maxSeg ||align="center"| double ||align="left"|
Sets the maximum permitted length (in units of b) of a dislocation segment. Primarily used for determining when segments are to be rediscretized during remesh operations. This value must be less than 9/10 the size of a cell. There is no default value, and must be specified in the control file.
|-
|align="center"| minSeg ||align="center"| double ||align="left"|
Sets the minimum desired length (in units of b) of a dislocation segment. Primarily used for determining when nodes are to be removed during remesh operations. Default is: sqrt(remeshAreaMin*(4/sqrt(3))) where remeshAreaMin = 2*rTol*maxSeg
|-
|align="center"| remeshRule ||align="center"| integer ||align="left"|
Specifies by number the set of rules governing rediscretization of dislocations. Currently the only supported remesh modules are versions 2 and 3. Default is 2. (See section on Rediscretization for details on remesh versions.)
|}

=== FMM controls ===

{|class="wikitable" border="0" align="center"
|+ Table A4. FMM control parameters
! Parameter
! Type
! Description
|-
|align="center"| fmEnabled ||align="center"| integer ||align="left"|
Toggle controlling use of a Fast Multipole Method (FMM) for computing force contributions from remote dislocation segments. A value of zero disables the use of FMM, any other value enables FMM. Default value is zero.
|-
|align="center"| fmCorrectionTbl ||align="center"| string ||align="left"|
Name of the image correction table used by the FMM. This correction table must correspond to the specified <fmMPOrder>, <fmTaylorOrder> and <shearModulus>(?) control parameters. See the [[#Creating the FMM Image Correction Table with 'ctablegen'|'ctablegen' utility]] for information on creating these tables. This value is ignored if <fmEnabled> is zero.
|-
|align="center"| fmMPOrder ||align="center"| integer ||align="left"|
Defines the multipole expansion order used by the FMM. This value is ignored if <fmEnabled> is zero. Default is 2.
|-
|align="center"| fmTaylorOrder ||align="center"| integer ||align="left"|
Defines the order of taylor expansions used by the FMM. This values is ignored if <fmEnabled> is zero. Default is 4.
|}

{|class="wikitable" border="0" align="center"
|+ Table A5. Table for non-FMM far-field forces
! Parameter
! Type
! Description
|-
|align="center"| Rijmfile ||align="center"| string ||align="left"|
Name of file containing the RIJM table to be used for far-field stress calculations. This parameter is ignored if the <fmEnabled> parameter is non-zero. Default is "inputs/Rijm.cube.out".
|-
|align="center"| RijmPBCfile ||align="center"| string ||align="left"|
Name of file containing the RIJM table to be used for far-field stress calculations with periodic boundary conditions. This parameter is ignored if the <fmEnabled> parameter is non-zero. Default is "inputs/RijmPBC.cube.out".
|}

=== Loading condition parameters: ===

{|class="wikitable" border="1" align="center"
|+ Table A6. Loading condition parameters
! Parameter
! Type
! Description
|-
|align="center"| loadType ||align="center"| integer ||align="left"|
Defines the type of load on the system. Valid types are:
<ol start="0">
<li> Creep test </li>
<li> Constant strain rate test </li>
<li> Displacement-controlled test </li>
<li> Load-controlled, load vs. time curve </li>
<li> Cyclic loading condition </li>
</ol>
|-
|align="center"| appliedStress ||align="center"| double[6] ||align="left"|
Defines the type of load on the system. Valid types are:
External stress specified in units of Pa as [sigma11, sigma22, sigma33, sigma23, sigma31, sigma12] when <loadType> == 0. Default is [0.0, 0.0, 0.0, 0.0, 0.0, 0.0].
|-
|align="center"| eRate ||align="center"| double ||align="left"|
Strain rate. Applicable only when <loadType> == 1. Default is 1.0/sec.
|-
|align="center"| indxErate ||align="center"| integer ||align="left"|
Index to indicate normal or shear deformation. Used only when <loadType> == 1. Valid values are:
# normal
# shear
If not specified, defaults to 1.
|-
|align="center"| edotdir ||align="center"| double[3] ||align="left"|
Uniaxial loading direction accompanying <eRate>. Default is [1.0 0.0 0.0].
|-
|align="center"| cTimeOld ||align="center"| integer ||align="left"|
Timestep related to cyclic loading. Only used when <loadType> == 4.
|-
|align="center"| dCyclicStrain ||align="center"| double ||align="left"|
Incremental strain under cyclic load. Only used when <loadType> == 4.
|-
|align="center"| netCyclicStrain ||align="center"| double ||align="left"|
Net accumulated strain under cyclic load. Only used when <loadType> == 4.
|-
|align="center"| numLoadCycle ||align="center"| integer ||align="left"|
Number of cyclic cycles. Only used when <loadType> == 4.
|-
|align="center"| eAmp ||align="center"| double ||align="left"|
Strain amplitude. Only used when <loadType> == 4.
|}

=== Material and mobility parameters: ===

Note: Default values for all material and mobility related
parameters correspond to Tantalum at a temperature of
600 degress K and pressure of 0 GPa.

{|class="wikitable" border="1" align="center"
|+ Table A7. Table for material and mobility parameters
! Parameter
! Type
! Description
|-
|align="center"| mobilityLaw ||align="center"| string ||align="left"|
Specifies by name the set of rules governing dislocation motion for the simulation conditions. Default is "BCC_0".
|-
|align="center"| shearModulus ||align="center"| double ||align="left"|
Shear modulus in units of Pa. Default is 6.488424e+10
|-
|align="center"| pois ||align="center"| double ||align="left"|
Poisson ratio. Default is 3.327533e-01
|-
|align="center"| burgMag ||align="center"| double ||align="left"|
Magnitude of the burgers vector (b) in units of meters. Default is 2.875401e-10
|-
|align="center"| YoungModulus ||align="center"| double ||align="left"|
Young's modulus (in units of Pa). calculated from E = 2G(1+pois). Default is 200.0e+09.
|-
|align="center"| rc ||align="center"| double ||align="left"|
Core radius (in units of b) for self-force calculations. No default value; must be specified in control file.
|-
|align="center"| Ecore ||align="center"| double ||align="left"|
Core energy used for self-force calculation. Default is (<shearModulus>/(4*PI)) * log(<rc>/0.1)
|-
|align="center"| MobScrew ||align="center"| double ||align="left"|
Mobility of screw dislocations in units of 1/(Pa*sec). Default is 10.0.
|-
|align="center"| MobEdge ||align="center"| double ||align="left"|
Mobility of edge dislocations in units of 1/(Pa*sec). Default is 10.0.
|-
|align="center"| MobClimb ||align="center"| double ||align="left"|
Climb mobility of dislocations in units of 1/(Pa*sec). Default is 1.0e-02.
|-
|align="center"| sessileburgspec ||align="center"| double[30] ||align="left"|
Array of burgers vectors to be considered sessile. First element of the array contains the number of burgers vectors specified, the remaining elements specify the X, Y, then Z components of each sessile burgers vector. Maximum sessile burgers vectors allowed is 9. No burgers vectors are sessile by default.
|-
|align="center"| sessilelinespec ||align="center"| double[30] ||align="left"|
Array of line directions related to sessileburgspec. First element is ignored, remaining elements specify the X, Y, then Z components of each sessile line. The number of lines is assumed to be the same as the number of sessile burgers vectors.
|}

=== Flux Decomposition: ===

{|class="wikitable" border="1" align="center"
|+ Table A8.
! Parameter
! Type
! Description
|-
|align="center"| totpSpn ||align="center"| double[6] ||align="left"|
Plastic strain tensor
|-
|align="center"| totpStn ||align="center"| double[6] ||align="left"|
Plastic spin tensor
|-
|align="center"| totstraintensor ||align="center"| double[6] ||align="left"|
Strain rate tensor with respect to global coordinate system.
|-
|align="center"| Ltot ||align="center"| double[4][4] ||align="left"|
Decomposed density per burgers vector for screw and three edges (for BCC slip systems only).
|-
|align="center"| fluxtot ||align="center"| double[4][7] ||align="left"|
For each burgers vector (for BCC slip systems only), contains:
<table border = "0" cellpadding = "0" cellspacing = "0">
<tr>
<td align="right"> 1. </td>
<td> flux due to climb </td>
</tr>
<tr>
<td align="right"> 2-4. </td>
<td> flux due to edge components </td>
</tr>
<tr>
<td align="right"> 5-7. </td>
<td> flux due to screw components </td>
</tr>
</table>
|}

=== Velocity statistics: ===

‡ Note: these statistics will only be used if the VEL_STATISTICS pre-processor macro has been defined during compilation.

{|class="wikitable" border="1" align="center"
|+ Table A9.
! Parameter
! Type
! Description
|-
|align="center"| vAverage ||align="center"| double ||align="left"|
Average dislocation velocity.
|-
|align="center"| vStDev ||align="center"| double ||align="left"|
Standard deviation of dislocation velocities.
|}

=== I/O controls and parameters ===

‡ Note: A number of the supported output forms are controlled by
very similar control parameters. The general descriptions below
apply to all I/O control parameters of like names:

<pre>
*freq Sets the frequency (in cycles) at which the associated data
will be written to disk. If the corresponding <*dt> parameter
is greater than 0, this parameter will be ignored.
Default for all such values is 100.

*dt The *dt variables specify the simulation delta time that will
control the frequency at which the associated output will be
written to disk. A positive value is interpreted as a delta
time and will take precedence over any frequency specified by
the corresponding <*freq> value. A value <= zero indicates
write frequency will not be determined by delta times.
Default value is -1.0.

*time Specifies the simulation time at which the associated data
was last written to disk. This value will be automatically
updated during the simulation. If the corresponding <*dt>
parameter is <= 0.0 this parameter will be ignored.

*counter Sequence number of the previously written file of the
corresponding type. Default is 0.
</pre>

{|class="wikitable" border="1" align="center"
|+ Table A10.
! Parameter
! Type
! Description
|-
|align="center"| dirname ||align="center"| string ||align="left"|
Base output directory name.
|-
|align="center"| skipIO ||align="center"| integer ||align="left"|
Toggle for disabling generation of all output types other than timing files. Overrides output-specific toggles if set. Default is 0.
|-
|align="center"| numIOGroups ||align="center"| integer ||align="left"|
Sets the number of groups into which the domains will be separated for doing parallel IO. All files generated in parallel will be created with this number of segments. This value must be at least one and no more than the total number of domains used. default is 1.
|-
|align="center"| armfile ||align="center"| integer ||align="left"|
Toggle enabling/disabling generation of files identifying each unique dislocation segment. Toggle is zero (off) by default.
|-
|align="center"| armfilecounter ||align="center"| integer ||align="left"|
See description of <*counter> above.
|-
|align="center"| armfiledt ||align="center"| double ||align="left"|
See description of <*dt> above.
|-
|align="center"| armfilefreq ||align="center"| integer ||align="left"|
See description of <*freq> above.
|-
|align="center"| armfiletime ||align="center"| double ||align="left"|
See description of <*time> above.
|-
|align="center"| fluxfile ||align="center"| integer ||align="left"|
Toggle enabling/disabling generation of flux decomposition files. Toggle is zero (off) by default.
|-
|align="center"| fluxcounter ||align="center"| integer ||align="left"|
See description of <*counter> above.
|-
|align="center"| fluxdt ||align="center"| double ||align="left"|
See description of <*dt> above.
|-
|align="center"| fluxfreq ||align="center"| integer ||align="left"|
See description of <*freq> above.
|-
|align="center"|fluxtime ||align="center"| double ||align="left"|
See description of <*time> above.
|-
|align="center"| gnuplot ||align="center"| integer ||align="left"|
Toggle enabling/disabling generation of files formatted for use with gnuplot. Toggle is zero (off) by default.
|-
|align="center"| gnuplotcounter ||align="center"| integer ||align="left"|
See description of <*counter> above.
|-
|align="center"| gnuplotdt ||align="center"| double ||align="left"|
See description of <*dt> above.
|-
|align="center"| gnuplotfreq ||align="center"| integer ||align="left"|
See description of <*freq> above.
|-
|align="center"| gnuplottime ||align="center"| double ||align="left"|
See description of <*time> above.
|-
|align="center"| polefigfile ||align="center"| integer ||align="left"|
Toggle enabling/disabling generation of <111> type burgers vector pole figures. Toggle is zero (off) by default.
|-
|align="center"| polefilecounter ||align="center"| integer ||align="left"|
See description of <*counter> above.
|-
|align="center"| polefigdt ||align="center"| double ||align="left"|
See description of <*dt> above.
|-
|align="center"| polefigfreq ||align="center"| integer ||align="left"|
See description of <*freq> above.
|-
|align="center"| polefigtime ||align="center"| double ||align="left"|
See description of <*time> above.
|-
|align="center"| povray ||align="center"| integer ||align="left"|
Toggle enabling/disabling generation of files with nodal data and domain boundaries for use with povray. Toggle is zero (off) by default.
|-
|align="center"| povraycounter ||align="center"| integer ||align="left"|
See description of <*counter> above.
|-
|align="center"| povraydt ||align="center"| double ||align="left"|
See description of <*dt> above.
|-
|align="center"| povrayfreq ||align="center"| integer ||align="left"|
See description of <*freq> above.
|-
|align="center"| povraytime ||align="center"| double ||align="left"|
See description of <*time> above.
|-
|align="center"| psfile ||align="center"| integer ||align="left"|
Toggle enabling/disabling generation of postscript files containing nodal data and domain boundaries. Toggle is zero (off) by default.
|-
|align="center"| psfiledt ||align="center"| double ||align="left"|
See description of <*dt> above.
|-
|align="center"| psfilefreq ||align="center"| integer ||align="left"|
See description of <*freq> above.
|-
|align="center"| psfiletime ||align="center"| double ||align="left"|
See description of <*time> above.
|-
|align="center"| savecn ||align="center"| integer ||align="left"|
Toggle enabling/disabling writing of restart files. Toggle is zero (off) by default.
|-
|align="center"| savecncounter ||align="center"| integer ||align="left"|
See description of <*counter> above.
|-
|align="center"| savecndt ||align="center"| double ||align="left"|
See description of <*dt> above.
|-
|align="center"| savecnfreq ||align="center"| integer ||align="left"|
See description of <*freq> above.
|-
|align="center"| savecntime ||align="center"| double ||align="left"|
See description of <*time> above.
|-
|align="center"| saveprop ||align="center"| integer ||align="left"|
Toggle enabling/disabling writing of various properties files. Toggle is zero (off) by default.
|-
|align="center"| savepropdt ||align="center"| double ||align="left"|
See description of <*dt> above.
|-
|align="center"| savepropfreq ||align="center"| integer ||align="left"|
See description of <*freq> above.
|-
|align="center"| saveproptime ||align="center"| double ||align="left"|
See description of <*time> above.
|-
|align="center"| savetimers ||align="center"| integer ||align="left"|
Toggle enabling/disabling generation of timing data files. Toggle is zero (off) by default.
|-
|align="center"| savetimerscounter ||align="center"| integer ||align="left"|
See description of <*counter> above.
|-
|align="center"| savetimersdt ||align="center"| double ||align="left"|
See description of <*dt> above.
|-
|align="center"| savetimersfreq ||align="center"| integer ||align="left"|
See description of <*freq> above.
|-
|align="center"| savetimerstime ||align="center"| double ||align="left"|
See description of <*time> above.
|-
|align="center"| savedensityspec ||align="center"| integer[3] ||align="left"|
Specifies the granularity of the 3D density field written to the density field file in X, Y and Z dimensions. If any element of this array is zero, this capability is disabled.
|-
|align="center"| tecplot ||align="center"| integer ||align="left"|
Toggle enabling/disabling generation of output files formatted for use with tecplot. Toggle is zero (off) by default.
|-
|align="center"| tecplotcounter ||align="center"| integer ||align="left"|
See description of <*counter> above.
|-
|align="center"| tecplotdt ||align="center"| double ||align="left"|
See description of <*dt> above.
|-
|align="center"| tecplotfreq ||align="center"| integer ||align="left"|
See description of <*freq> above.
|-
|align="center"| tecplottime ||align="center"| double ||align="left"|
See description of <*time> above.
|-
|align="center"| tsbfile ||align="center"| integer ||align="left"|
Toggle enabling/disabling generation of output files formatted for use with the TeraScale Browser. Toggle is zero (off) by default.
|-
|align="center"| writetsbspec ||align="center"| integer[3] ||align="left"|
TBD
|-
|align="center"| tsbfilecounter ||align="center"| integer ||align="left"|
See description of <*counter> above.
|-
|align="center"| tsbfiledt ||align="center"| double ||align="left"|
See description of <*dt> above.
|-
|align="center"| tsbfilefreq ||align="center"| integer ||align="left"|
See description of <*freq> above.
|-
|align="center"| tsbfiletime ||align="center"| double ||align="left"|
See description of <*time> above.
|-
|align="center"| velfile ||align="center"| integer ||align="left"|
Toggle enabling/disabling generation of output files containing velocity data for all nodes in the simulation. Toggle is zero (off) by default.
|-
|align="center"| velfilecounter ||align="center"| integer ||align="left"|
See description of <*counter> above.
|-
|align="center"| velfiledt ||align="center"| double ||align="left"|
See description of <*dt> above.
|-
|align="center"| velfilefreq ||align="center"| integer ||align="left"|
See description of <*freq> above.
|-
|align="center"| velfiletime ||align="center"| double ||align="left"|
See description of <*time> above.
|-
|align="center"| winDefaultsFile ||align="center"| string ||align="left"|
Name of file containing default options and attributes for the X-window display. This is ignore if the X display support was not enabled at compile time. Defaults to "./inputs/paradis.xdefaults".
|}

=== Miscellaneous parameters ===

{|class="wikitable" border="1" align="center"
|+ Table A11.
! Parameter
! Type
! Description
|-
|align="center"| elasticinteraction ||align="center"| integer ||align="left"|
Toggles between explicit calculation of elastic interaction and simple line tension calculations. Toggle is one (on) by default.
|-
|align="center"| TensionFactor ||align="center"| double ||align="left"|
Factor used for simple line tension force calculations when the <elasticinteraction> parameter is zero. Default is 1.0.
|}

=== Under development ===

{|class="wikitable" border="1" align="center"
|+ Table A12.
! Parameter
! Type
! Description
|-
|align="center"| TempK ||align="center"| double ||align="left"|
Simulation temperature (in Kelvin). For use in FCC cross-slip.
|-
|align="center"| enforceGlidePlanes ||align="center"| integer ||align="left"|
If non-zero, forces remesh, collision handling, etc. to use glide-plane constraints. Default is zero.
|-
|align="center"| springConst ||align="center"| double ||align="left"|
For use with FCC_0 mobility
|-
|align="center"| mob_compute_escaig ||align="center"| integer ||align="left"|
TBD
|-
|align="center"| mob_cross_slip ||align="center"| integer ||align="left"|
TBD
|}

PARADISCYL:Cylinder-Algorithm

2011-12-03T06:57:24Z

Iryu: /* List of Files */

<P ALIGN="CENTER">
<FONT SIZE="+3" color="darkred"><STRONG>
Cylinder Code Algorithm </STRONG></font></P>
<DIV>
<P ALIGN="CENTER"><STRONG>ill Ryu and Wei Cai</STRONG></P>
</DIV>

This wiki page describes the ParaDiS Cylinder code v.2.5.1. This version of the Cylinder code is created by a ''translation'' from the ParaDiS ThinFilm code v.2.5.1, with subsequent modifications. In this wiki page, we only describe the difference between the Cylinder code and the ''translated'' ThinFilm code.

<HR>

==List of Files==

The following is a list of all files modified manually after the ''translation''.

1. AllSegmentStress.c
Changes are made in this file to construct the test cases.

A new function AllSegmentStress_no_cell_test1() is added, which computes the stress field of a
infinite straight dislocation (analytic expression) for Test Case 1 only. This function is activated
when CYL_TEST1 is defined (in the makefile).

Function AllSegmentStress_no_cell() is modified to account for periodic images in Z direction.
NimgPBC is specified in the input file(By default, it is '1'). For each dislocation segment, NimgPBC number
of its images are included in the stress calculation.

Macros (#ifdef 's) are added to make the Cylinder code use FULL_N2_FORCES when _CYL_TEST23 is defined.
The same changes also affect these files: Initialize.c, LocalSegForce.c, NodeForce.c.

2. Cylinder_Remesh.c
In function Cylinder_Remesh(), added new rules to remove surface debris (to increase time step).
Surface debris are defined as dislocation line consisting of two or three segments with two
(end) surface nodes.

See [[PARADISCYL:Cylinder-Remove_surface_debris | M11 Remove surface debris ]].
A new function ProjectSurfaceNodes() is defined to project nodes flagged by CYLINDER_SURFACE_NODE
back to the cylinder surface when it drifts inside the cylinder. Note that surface nodes moving
out of the cylinder are already handled by Cylinder_Remesh.

See [[PARADISCYL:Cylinder-Project_surface_node | M12 Project surface nodes ]].

3. MobilityLaw_BCC_glide.c

Modify the mobility of surface node /* version 3 */ so that they are kept simultaneously on the
surface and its slip plane. This algorithm works in two steps. First, the velocity is made to
satisfy all the slip plane glide constraints (copied from FCC_0 mobility law of bulk). Then the
surface normal is computed. The surface node velocity is adjusted by adding a component parallel to
the surface dislocation segment, so that the velocity becomes orthogonal to the surface normal.

The mobility (magnitude) of the surface node is made to be 2 (or 1, or 3, hard coded) times faster
than the bulk. (Search for keyword: scale). This mobility enhancement is applied to a region near
the cylinder surface (r > 0.8 R_cylinder) with a linear interpolation.

Added codes to choose glide planes for surface nodes based on the force on the force. This force
contains contributions from PK force (due to applied stress and other dislocations) and line tension
force (if any). Image stress does not contribute to this force and the image stress is supposed to
be turned off when running with these codes.
See [[PARADISCYL:Cylinder-Surface_cross_slip | M10 Surface multiplication ]].

A threshold stress is applied to all nodes to mimic the Peierls stress behavior in BCC metals.
(Maybe the surface node has lower Peierls stress.)

'''We need to clean up this file.'''

4. Collision.c
Added lines to turn off collision if param->collisionoMethod is specified as a negative number
(in the input file).

5. cylinder.c
In function CYL_stress_boundary(), a minus sign is added in computing the surface traction from
the infinite stress:
tr[j+i*nq] = -cylstress[0][0];
tq[j+i*nq] = -cylstress[0][1];
tz[j+i*nq] = -cylstress[2][0];

6. gridstress.c
Added lines to scale the image stress calculation when the cylinder radius is not 1. This removes
the (old) constraint that the cylinder radius has to be one.

See [[PARADISCYL:Scale-Rule | M04 How units are scaled]].

6. Remesh.c, Cylinder_Remesh.c
Make substitutions: SURFACE_NODE -> CYLINDER_SURFACE_NODE.
'''This is supposed to be handled by translation'''.

7. SplitSurfaceNodes.c PredictiveCollision.c ProximityCollision.c
- For the surface node split (not implemented yet)

==Cylinder Code Algorithm==

PARADISCYL:Cylinder-Algorithm

2011-12-03T06:25:19Z

Iryu: /* List of Files */

<P ALIGN="CENTER">
<FONT SIZE="+3" color="darkred"><STRONG>
Cylinder Code Algorithm </STRONG></font></P>
<DIV>
<P ALIGN="CENTER"><STRONG>ill Ryu and Wei Cai</STRONG></P>
</DIV>

This wiki page describes the ParaDiS Cylinder code v.2.5.1. This version of the Cylinder code is created by a ''translation'' from the ParaDiS ThinFilm code v.2.5.1, with subsequent modifications. In this wiki page, we only describe the difference between the Cylinder code and the ''translated'' ThinFilm code.

<HR>

==List of Files==

The following is a list of all files modified manually after the ''translation''.

1. AllSegmentStress.c
Changes are made in this file to construct the test cases.

A new function AllSegmentStress_no_cell_test1() is added, which computes the stress field of a
infinite straight dislocation (analytic expression) for Test Case 1 only. This function is activated
when CYL_TEST1 is defined (in the makefile).

Function AllSegmentStress_no_cell() is modified to account for periodic images in Z direction.
A local variable NimgPBC is hard coded. For each dislocation segment, NimgPBC number of its images
are included in the stress calculation. '''We should move this to Param.h.'''

Macros (#ifdef 's) are added to make the Cylinder code use FULL_N2_FORCES when _CYL_TEST23 is defined.
The same changes also affect these files: Initialize.c, LocalSegForce.c, NodeForce.c.

2. Cylinder_Remesh.c
In function Cylinder_Remesh(), added new rules to remove surface debris (to increase time step).
Surface debris are defined as dislocation line consisting of two or three segments with two
(end) surface nodes.

See [[PARADISCYL:Cylinder-Remove_surface_debris | M11 Remove surface debris ]].
A new function ProjectSurfaceNodes() is defined to project nodes flagged by CYLINDER_SURFACE_NODE
back to the cylinder surface when it drifts inside the cylinder. Note that surface nodes moving
out of the cylinder are already handled by Cylinder_Remesh.

See [[PARADISCYL:Cylinder-Project_surface_node | M12 Project surface nodes ]].

3. MobilityLaw_BCC_glide.c

Modify the mobility of surface node /* version 3 */ so that they are kept simultaneously on the
surface and its slip plane. This algorithm works in two steps. First, the velocity is made to
satisfy all the slip plane glide constraints (copied from FCC_0 mobility law of bulk). Then the
surface normal is computed. The surface node velocity is adjusted by adding a component parallel to
the surface dislocation segment, so that the velocity becomes orthogonal to the surface normal.

The mobility (magnitude) of the surface node is made to be 2 (or 1, or 3, hard coded) times faster
than the bulk. (Search for keyword: scale). This mobility enhancement is applied to a region near
the cylinder surface (r > 0.8 R_cylinder) with a linear interpolation.

Added codes to choose glide planes for surface nodes based on the force on the force. This force
contains contributions from PK force (due to applied stress and other dislocations) and line tension
force (if any). Image stress does not contribute to this force and the image stress is supposed to
be turned off when running with these codes.
See [[PARADISCYL:Cylinder-Surface_cross_slip | M10 Surface multiplication ]].

A threshold stress is applied to all nodes to mimic the Peierls stress behavior in BCC metals.
(Maybe the surface node has lower Peierls stress.)

'''We need to clean up this file.'''

4. Collision.c
Added lines to turn off collision if param->collisionoMethod is specified as a negative number
(in the input file).

5. cylinder.c
In function CYL_stress_boundary(), a minus sign is added in computing the surface traction from
the infinite stress:
tr[j+i*nq] = -cylstress[0][0];
tq[j+i*nq] = -cylstress[0][1];
tz[j+i*nq] = -cylstress[2][0];

6. gridstress.c
Added lines to scale the image stress calculation when the cylinder radius is not 1. This removes
the (old) constraint that the cylinder radius has to be one.

See [[PARADISCYL:Scale-Rule | M04 How units are scaled]].

6. Remesh.c, Cylinder_Remesh.c
Make substitutions: SURFACE_NODE -> CYLINDER_SURFACE_NODE.
'''This is supposed to be handled by translation'''.

7. SplitSurfaceNodes.c PredictiveCollision.c ProximityCollision.c
- For the surface node split (not implemented yet)

==Cylinder Code Algorithm==

ParaDiS Cylinder Code Manuals

2011-12-03T06:22:06Z

Iryu:

<UL>
<LI>[[PARADISCYL:How-To-Install | M01 How to install]]
<LI>[[PARADISCYL:Test-Run | M02 Test Run]]
<LI>[[PARADISCYL:Cylinder-Algorithm | M03 Cylinder code algorithm ]]
<LI>[[PARADISCYL:Scale-Rule | M04 How units are scaled]]
<LI>[[PARADISCYL:How-To-Get-Nodal-Force | M05 How to get nodal force data]]
<LI>[[PARADISCYL:Cylinder-Benchmark | M06 Benchmarks to check PBC ]]
<LI>[[PARADISCYL:Cylinder-Benchmark2 | M07 Benchmarks to check traction boundary condition ]]
<LI>[[PARADISCYL:Cylinder-bug | M08 Discontinuites in stress at the cell boundary ]]
<LI>[[PARADISCYL:Cylinder-test | M09 Test Cases ]]
<LI>[[PARADISCYL:Cylinder-Surface_cross_slip | M10 Surface multiplication ]]
<LI>[[PARADISCYL:Cylinder-Remove_surface_debris | M11 Remove surface debris ]]
<LI>[[PARADISCYL:Cylinder-Project_surface_node | M12 Project surface nodes ]]
</UL>

PARADISCYL:Cylinder-Project surface node

2011-12-03T06:17:04Z

Iryu: