***************************************************************************************

Jie Yin, jieyin@stanford.edu

Wei Cai, caiwei@stanford.edu


This directory provides matlab codes that implement the expressions for calculating the 
stress fields of dislocation segments in an anisotropic elastic medium. To calculate the 
segment stress field, two steps are needed: (1) computing the intermediate matrices Q, B 
and S using matrix or integral formalism; (2) computing the segment stress using 
either Brown's formula or Willis-Steeds-Lothe formula (WSL). These four combinations 
are discussed in the following paper. Results in isotropic media are used as benchmarks.

Reference: 
Yin J., Barnett, D.M., Cai, W., Efficient Computation of Forces on Dislocation Segments 
in Anisotropic Elasticity, Model. Sim. Mater. Sci. Eng. in press (2010).

This matlab package can be used to perform dislocation dynamics (DD) simulations based 
on the anisotropic elasticity formalism.  It can model an isotropic medium by specifying 
the elastic constants.  The code will automatically perturb C44 if (C11=C12+2*C44) when
the matrix formalism is used.

The tests/ directory contains five test cases that are discussed in the paper above.

The data/ directory will contain the data file to be generated by critical_stress.m
and critical_stress_aniso.m

To perform DD simulations using isotropic elasticity, you need to download the standard
DDLab program.  The cleanupnodes.m, genconnectivity.m and plotnodes.m files are identical 
to those in the DDLab program.

Warning: In the test cases, we construct the elastic stiffness tensor using the 
cubicelasticconst() function.  By default, this function will perturb c44 if the elastic
constants correspond to isotropic medium (c11=c12+2*c44).  If you do not with to perturb
c44, you can call this function as C = cubicelasticconst(c11,c12,c44,'i').  Here 'i'
means we will use the integral formalism, which works even for isotropic elastic constants.
You can also change the amount of perturbation in c44 by passing it as the 5th argument
of this function.


****************************************************************************************
Test cases:

test_iso_inf.m
    compute the stress field of an infinite long dislocation line at a given point in an 
    isotropic medium (W). Since Brown's and WSL formulas are identical for the infinite 
    medium, Brown's formula was chosen to "assemble" Q, B, S matrices. Both matrix and 
    integral formalisms are investigated. A comparison of accuracy and efficiency will 
    be printed out.

    To run it, type
      cd tests
      test_iso_inf

    The program will automatically go to the parent directory (aniso/) after running
    the test case.

test_aniso_inf.m
    almost the same as test_aniso_inf.m except that the test is done in anisotropic Mo.

test_polygonal_iso.m
    compute the stress field of a quadrangle dislocation loop at a point in isotropic W. 
    Brown's formula differ from WSL in the solutions for dislocation segment stresses, 
    which are not unique. However, they agree with each other for a closed loop. Both 
    formulas and both formalisms to compute Q, B, S are compared.

test_polygonal_aniso.m
    almost the same as test_polygonal_aniso.m except that the test is done in anisotropic Mo.

frank_read.m 
    a DD simulation of Frank Read source under a given applied stress. The simulation can be 
    performed for both closed dislocation loop and single dislocation arm. The default medium 
    is W (isotropic). Follow the instruction displayed, you can run the simulation for 
    a certain number of steps and compare with DD simulation based on isotropic elasticity
    (you will need the standard DDLab program for that).

    This test case requires the utility functions in section (3) described below.

    To compute the critical stress to activate a Frank-Read source, you need to call the
    functions critical_stress.m, critical_stress_auto, critical_stress_aniso.m and 
    critical_stress_aniso_auto.m, which are described in section (4) below.


*****************************************************************************************
Important functions

(1) Q, B, S (and other intermediate) matrices calculation

stroh.m
    computes Q,B,S matrices for given line direction, t and elastic constant tensor. It 
    calls stroh_m to use the matrix formalism and calls stroh_i to use the integral formalism 
    (Nint, number of integration points can be specified as an input). 
    Alternatively, functions stroh_m and stroh_i can be called directly.

stroh_p.m
    computes the first angular derivative of Q, B, S matrices. It need an extra vector to 
    define the angular direction in addition to t. Both matrix formalism and integral formalism 
    can be used here. Similar to stroh_m.m and stroh_i.m, functions stroh_p_m.m and stroh_i_m 
    can be called directly.

SIG.m
    computes the so called stress angular factor, Sigma in Brown's formula.

SIG_p.m
    computes the first angular derivative of the stress angular factor, Sigma, 
    in Brown's formula

(2) Stress field calculation

stress_inf_B.m, stress_inf_WS.m, stress_inf_iso.m
    calculates the stress field due to an infinite straight dislocation line using Brown's 
    formula, WSL formula and analytical solution based on isotropic elasticity, respectively

stress_seg_B.m, stress_seg_WS.m, stress_seg_iso.m
    calculates the stress field due to a dislocation segment  using Brown's formula, WSL formula 
    and analytical solution based on isotropic elasticity, respectively. Note that their results 
    may be different until they are summed over complete loops.

stress.co.m
    calculates the stress due to a dislocation segment on a collinear field point based on WSL 
    formula (zero stress for Brown's formula). The computation involves calling fac_co, which 
    compute the stress factor.

(3) Nodal Force calculation

RemoteNodeForce_aniso_quad.m
    computes the nodal forces of two dislocation segments due to elastic interactions using 
    Adaptive Simpson method for numerical integration. It is much more efficient than 
    RemoteNodeForce_aniso.m (not used), which is an old version that uses a uniform 
    integration grid. When the two segments are exactly collinear, RemoteNodeForce_aniso_quad.m
    will call CollinearNodeForce.m.

seg_force_self.m
    evaluate the nodal forces of a dislocation segment due to its own stress field.

(4) Frank-Read source activation stress calculation

critical_stress.m
    computes the critical stress to activate a Frank Read source for a dislocation segment. 
    The external stress increases with a specified increment if the dislocation segment 
    doesn't continue to bow out. For simplicity, the initial dislocation is constructed on the
    (001) slip plane.  This should not make a difference for isotropic medium.  To model 
    initially pure edge or pure screw dislocation, we simply rotate the Burgers vector and 
    the initial dislocation line orientation remains the same.

    For example:  critical_stress(1000, 's', 0.1, 0.01);
    note: this may take hours/days to finish.  stress and elastic constants in units of 10GPa.

critical_stress_aniso.m
    a later version of critical_stress.m that uses realistic slip planes (e.g. (110)) and
    Burgers vector orientations (e.g. [111]).  The default medium is alpha-Fe.

critical_stress_auto.m
    a driver routine for critical_stress,m. It can used to find out the critical F-R source 
    stress at a desired precision. Two important inputs are: initial applied stress increment, 
    dsig_0, and final stress precision, disg_min. They must be integer powers of 10, e.g. 1e-4.

    For example:  critical_stress_auto(1000, 's', 1, 1e-3);
    note: this may take hours/days to finish.  The answer for this test run should be: 0.050.

critical_stress_aniso_auto.m
    a driver routine for critical_stress_aniso.m