CACmb/README.md

# CAC_Model_Builder
This is a tool for building models in CAC. Commands and usage options are below. This code is intended to follow the atomsk code fairly closely.

## Modes

The modes follow similarly to the modes you find when using atomsk. The modes will be listed below alongside their syntax and other usage instructions. As a note, if a mode is being used then it has to come first.

### Mode Create

``` 
cacmb --create name element_type lattice_parameter esize
```

Mode create has the following parameters:

`name` - User defined name that either defines the atom type or the lattice type if using the basis option

`element_type` - Specifies which element type to use, this dictates the crystal being build. Current   acceptable options for element_type are:

* FCC - Uses the Rhombohedral primitive fcc unit cell as the finite element.

`lattice_parameter` - The lattice parameter for the crystal structure.

`esize` - Number of atoms per edge of the finite element. A value of 2 signifies full atomistic resolution and is the lowest number acceptable.

**Example**

```
cacmb --create Cu fcc 3.615 11
```

Creates a copper element with a lattice parameter of 3.615 with 11 atoms per side

#### Optional keywords

**Orient**

``` orient [hkl] [hkl] [hkl] 
orient [hkl] [hkl] [hkl]
```

Default orientation is `[100] [010] [001]`. If this keyword is present then the user must provide the orientation matrix in form `[hkl] [hkl] [hkl]`.

*Example:* `orient [-112] [110] [-11-1]` 

**Basis**

``` 
basis num atom_name x y z
```

Default basis has `atom_name = name` with position (0,0,0). If used then the `atom_name x y z` must be include `num` times. 

*Example:* `basis 2 Mg 0 0 0 Mg 0.5 0.288675 0.81647`

**Duplicate**

```
duplicate numx numy numz
```

Default duplicate is `1 1 1`. This is used to replicate the element along each dimensions. This cannot be used if the keyword dimensions is included. By default jagged edges along boundaries are filled if duplicate is greater than `1 1 1`.

*Example:* `duplicate 10 10 10`

**Dimensions**

```
dimensions dimx dimy dimz
```

There is no default dimensions as duplicate is the default option. This command assigns a box with user-assigned dimensions and fills it with the desired element. By default atoms fill in the jagged edges at the boundaries if the dimensions command is included.

Example: `dimensions 100 100 100` 

**ZigZag**

```
zigzag boolx booly boolz
```

Default zigzag is `f f f`. This command specifies whether a boundary should be left jagged (i.e. in essence not filled in). If `boolx` is `t` than the x dimension is left jagged and if it is `f` then the x dimension is filled.

*Example:* `zigzag t f t` gives a box with jagged edges in the x and z and filled edges in the y.

**Origin**

```
origin x y z
```

Default origin is `0 0 0`. This command just sets the origin for where the simulation cell starts building.

*Example:* `origin 10 0 1`

### Mode Convert

```
cacmb --convert infile outfile
```

This mode converts a file `infile` to a file of  `outfile`. The extensions determine the conversion process.

### Mode Merge

```
cacmb --merge dim N infiles outfile
```

This mode merges multiple data files and creates one big simulation cell. The parameters are:

`N` - The number of files which are being read

`dim` - the dimension they are to be stacked along, can be either `x`, `y`, or `z`. If the argument `none` is passed then the cells are just overlaid. Future options will include a delete overlap command.

**Additional options:**

**Shift**

```
shift x y z
```

If the shift command is passed to mode merge then each file after the first file in the merge command is displaced by the vector `[x, y, z]`. This is additive so if you are merging three files and this command is passed then the second file is shifted by `[x,y,z]` and the third file is shifted by `2*[x,y,z]`. 

Example: `cacmb --merge z 2 Cu.mb Cu2.mb Cu3.mb Cumerged.mb shift 2 0 0` will shift the atomic and element positions in the `Cu2.mb` file by `[2,0,0]` and the positions in `Cu3.mb` by `[4,0,0]`.

**Wrap**

```
wrap
```

This will wrap atomic positions back inside the box. Effectively as if periodic boundary conditions are applied so that atoms which exit from one side of the simulation cell enter back in through the other.

## Options

Options are additional portions of code which have additional functionality. Options are performed in the order that they appear in the argument list and can be added to any mode. If wanting to use strictly options use `--convert` to specify input and output files.

### Option dislgen

```
-dislgen [ijk] [hkl] x y z burgers char_angle poisson 
```



This options adds an arbitrarily oriented dislocation into your model based on user inputs using the volterra displacement fields. The options are below

`[ijk]` - The vector for the line direction

`[hkl]` - The vector for the slip plane 

`burgers` - The magnitude of the burgers vector for the dislocation to be inserted

`x y z` - The position of the dislocation centroid

`char_angle` - Character angle of the dislocation (0 is screw and 90 is edge)

`poisson` - Poisson's ratio used for the displacement field.

### Option disloop

````
-disloop loop_normal radius x y z bx by bz poisson
````

This option deletes vacancies on a plane which when minimized should result in a dislocation loop structure. The arguments are below:

`dim` - The box dimension which defines the normal to the loop plane. As of now this dimension must be a closed back direction, meaning that for fcc a box dimension has to be of the (111) family of planes. Either `x`, `y`, or `z`.

`n` - The number of atoms to delete on the loop plane

`x y z` - The centroid of the loop. 

`bx by bz` - The burgers vector for the dislocation

`poisson` - Poisson ratio for continuum solution

### Option Group

`-group select_type group_shape shape_arguments additional keywords`

This option selects a group of either elements, nodes, atoms and applies some transformation to them.

`select_type` - Either `nodes`, `atoms`, `elements`, `nodes/atoms`, `all`. When using the option `nodes` only nodes which are within the group are selected, `elements` selects elements based on whether the element center is within the group, `nodes/atoms` selects both nodes and atoms for the group.  `all` selects elements based on the element center and atoms based on their position.

`group_shape` - Specifies what shape the group takes and dictates which options must be passed. Each shape requires different arguments and these arguments are represented by the placeholder `shape_arguments`. The accepted group shapes and arguments are below:

*Block:*

`-group nodes block xlo xhi ylo yhi zlo zhi`

This selects a group residing in a block with edges perpendicular to the simulation cell. The block boundaries are given by `xlo xhi ylo yhi zlo zhi`. 

`additional keywords`- Represents the various transformations which can be performed on a group. These additional keywords are given below.

**Displace**

```
displace x y z 
```

This is similar to the mode merge `-shift` argument. This simply shift atoms and elements within the group by a vector `[x,y,z]`.

**Wrap** 

```
wrap	
```

This command wraps atoms back into the simulation cell as though periodic boundary conditions are being used. 

**Remesh**

```
remesh esize 
```

This command remeshes the atoms/elements within the group to the new element size `esize`. Currently only accepts an `esize` of 2 which refines it to full atomistics.

### Option overwrite 

```
-ow
```

If this option is passed then all files are automatically overwritten without asking the user.

## Position Specification

Specifying positions in cacmb can be done through a variety of ways. Examples of each format is shown below.

`val` - Where `val` is a number, then that value in Angstroms is used as the position. As an example, `11.1` would be read in as a position of 11.1 $\AA$.

`-inf` - This specifies the lower box boundary in the specific dimension. The vector `-inf -inf -inf`  specifies the bottom corner of the simulation cell which also acts as the simulation cell origin. The vector `-inf 10 3` instead puts only the x position at the simulation cell origin.

`inf` - Similar to `-inf` but references the upper boundary of the box in that dimension

`inf-val` - Using a minus sign reduces the position from the **upper boundary** by `val`. `inf-10` would be at a distance of $10 \AA$ from the upper boundary in that dimension.

`inf+val` - This increases the position from the **lower boundary**. `inf+10` would be a position $10\AA$ from the lower boundary within the cell.

`inf*val` - This gives you a fractional position in the simulation cell. As an example `inf*0.5` gives you the center point of the simulation cell. 

`rand` - Returns a random position that lies within the simulation cell.