User Input Parameters

This page provides a comprehensive description of the several parameters a user can play with while creating an initial mesh and performing a quasistatic relaxation.

Lattice Generation

The table below explains the userinput parameters in latticegenerator_parameters.json.

AQCNES provides three major ways of creating an initial lattice. These correspond to the field method in the table above.

• NanoIndentation This option is used to generate atomistic and/or coarse-grained monocrystalline samples. The following input variables need to be specified for using this option:

"method": {
    "$type": "NanoIndentation",
    "domain_boundaries": {                 // specifies the lower and upper bounds of the simulation box 
      "lower": [
        -5000.0,
        -5000.0,
        -10000.0
      ],
      "upper": [
        5000.0,
        5000.0,
        0.1
      ]
    }
  }

Any lattice sites generated outside the lower and upper boundaries of the simulation domain are deleted.

• SymmetricGrainboundaries This option is used to generate atomistic bicrystalline samples. The following input variables need to be specified for using this option:

"method": {
    "$type": "SymmetricGrainboundaries", 
    "overlap_deletion_distance": 1.0,        // delete any lattice site that is closer than 1.0 to any another lattice site
    "delete_across_boundary": true,          // delete close enough lattices as specified above assuming periodic boundaries
    "domain_boundaries": {                   // specifies the lower and upper bounds of the simulation box 
      "lower": [
        -5000.0,
        -5000.0,
        -10000.0
      ],
      "upper": [
        5000.0,
        5000.0,
        0.1
      ]
    }
  }

This lattice generator is used to generate symmetric tilt grain boundaries. Any lattice sites generated outside the lower and upper boundaries of the simulation domain are deleted. The parameters overlap_deletion_distance and delete_across_boundary are used to avoid any two atoms being too close to each other to provide a better initial guess for the geometry.

• ReadCoordinates This option provides the flexibility to generate a mesh of any possible geometry by simply reading the atomic coordinates of a previously generated lattice. The atomic coordinates file must be written in a standard LAMMPS format. The following input variables need to be specified for using this option:

"method": {
    "$type": "SymmetricGrainboundaries", 
    "coordinates_file_name": "path/to/lattice_file"    
  }

Quasistatic Relaxation

Each sub-header below corresponds to a section of the userinput.json input file.

SimulationSettings

ThermalSettings

FIRERelaxation

This section includes the parameters for the optimizer FIRE (fast inertial relaxation engine). The optimum values for all of them have been borrowed from this manuscipt and it is recommended to use the same values.

PETSC

This section includes the parameters for PetSc solvers. Integrating PetSc solvers with FIRE is an ongoing work right now.

SolverTolerances

AQCNES requires the L1 norm of the physical, thermal, and periodic forces to reach below the user-specified tolerances to ensure convergence.

Periodicity

{
          "min_coordinate": -14.44,      // minimum value of any sampling atom coordinate in the corresponding Cartesian direction 
          "length": 28.88,               // periodic length of the simulation domain in the corresponding Cartesian direction
          "relaxation_constraint": false // Allow the periodic length to relax or not (analogous to NPT vs NVT simulations in MD)
        }

Multispecies (optional)

AQCNES supports simulating the equilibrium properties of a multi-element system (e.g. a binary alloy) by specifying the following parameters. This section is completely optional and can be skipped if simulating pure species.

Potentials

AQCNES provides the following options of specifying the inter-atomic potential to be used:

• EAM potentials: An embedded atom method (EAM) potential can be used simply by specifying the Potentials section as shown below.

"Potentials": {
            "material": {
                "$type": "SetflEAM",
                "potential_file_path": "path/to/eam/file",
                "potential_material_name": "user_specified_name",
                "funcfl_file": false
            }
        }

Note that the specified file is considered to be of a SETFL format by default. Make sure to specify "funcfl_file": true when using a FUNCFL file format. The potential_material_name is just a user-specified name of material which is appended to output file names.

• MEAM potentials: Modified embedded atom method (MEAM) potentials can be used as shown below.

"Potentials": {
            "material": {
                "$type": "Meam",
                "library_file_path": "path/to/meam_library_file",
                "parameter_file_path": "path/to/meam_parameter_file",
                "potential_material_name": "user_specified_name",
                "species": ["Cu","Al"]
            }
        }

The library and parameter files need to be specified for the MEAM potential separately. The field species should contain the chemical symbols of the elements present in your simulation. This is used to identify the correct parameters from the library file.

• KIM potential repository: OpenKIM is a repository of interatomic potentials which includes different types of pair, EAM, MEAM, and bond order potentials. Any potential available in this repository can be used in AQCNES by simply specifying the model name as shown below.

"Potentials": {
            "material": {
                "$type": "Meam",
                "atomic_mass": 63.546,
                "model_name": "EAM_NN_Johnson_1988_Cu__MO_887933271505_002",
                "species": ["Cu"]
            }
        }

Note that OpenKIM potentials are optimised for molecular dynamics simulations and hence using them can be a bit slow for this framework.

• GNN models: Using all the options specified above is combined with a third or fifth-order Gaussian quadrature for computing phase averaged energies and forces. However, this comes with its own set of limitations which can corrupt the simulation accuracy when dealing with amorphous systems or at higher temperatures (see here for further details). Hence, a GNN model can be used as a surrogate for phase-space averaging by specifying:

"Potentials": {
            "material": {
                "$type": "Meam",
                "model_path": "path/to/trained_GNN_model",
                "atomic_mass": 63.546,
                "potential_material_name": "user_specified_name"
            }
        }

Apart from this, some simple potentials have also been hardcoded in the software. These include:

• Extended Finnis Sinclair (EFS) potential for copper
• Yukawa type pair potential for silica

OutputPrintingChoices

ConsolePrintingChoices

NeighbourDisplays

This section can be used to output additional visualization vtu files for user-specified sampling atoms. This can help visualize atomic neighborhood movements during extreme deformations or near critical material defects. Approximate initial locations of the desired sampling atoms can be specified as an array of arrays as shown below:

"display_neighbourhoods_sampling_atoms": [
        [
          0.0,
          0.0,
          0.0
        ],
        [
          -5.41,
          -7.22,
          -5.41
        ],
        [
          5.41,
          -7.22,
          -5.41
        ]
      ]

The sampling atoms closest to the specified locations would be tracked along with their neighbors, and their information is dumped in a directory called neighborhoods.