How to provide input parameters¶

All available input parameters are given below this page. They have minimal self-explanatory help and I recommend consulting the Supercell manual and tutorial to get further insight. Herein, I provide general information on how to set up input paramters for plugin.

Constructing `builder`¶

By having following lines in your submission script, you can get an input builder where you can assign each input:

from aiida.plugins import CalculationFactory

SupercellCalculation = CalculationFactory('supercell')
builder = SupercellCalculation.get_builder()

Then, each of inputs listed below, can be assigned to the builder. For example, the following snippet will set the calculate to True which results in calculation of electrostatic energies:

from aiida import orm

builder.calculate_coulomb_energies = orm.Bool(True)

Or the following snippet, will create a SinglefileData and then will provide it to builder as structure:

from aiida.orm import DataFactory

SinglefileData = DataFactory('singlefile')
singlefileobject = SinglefileData(file=absolute_path/to/CIF)
builder.structure = singlefileobject

Note Objects which are being assigned to builder has to be AiiDA data objects.

Below I provide a little bit of more explanation on few special input parameters:

charges¶

In case you want to provide the charges explicitly in run time (for example, giving structure as StructureData, or wanting to do the calculations with different set of charges), you can provide them as a Dict via charges input parameter. Herein, you may provide charge for each atom label available in the structure (if they are defined in StructureData), or you may use wildcards.

from aiida import orm

builder.charges = orm.Dict(dict={'Ca*': 2, 'Al*': 3, 'Si*': 4, 'O*': -2})

The above input will set the charges on all Ca sites to 2 and so on so forth.

random_seed¶

Usually you do not need to set this parameter. Supercell generates and use it during the run time. However, aiida-supercell parses and stores the used random_seed in output_parameters. It can be used for reproducing the results.

sample_structures¶

Supercell is very powerful in enumerating and sampling huge configuration spaces. Using the sample_structures input parameters, we can control how to sample structures for further calculations. We provide this input as Dict which accepts following keys:

random: number of structures to be sampled randomly.
low_energy: number of structures with lowest electrostatic energy to be sampled.
high_energy: number of structures with highest electrostatic energy to be sampled.
first: number of structures to be sampled from the beginning of enumeration
last: number of structures to be sampled from the end of enumeration
degeneracy: number of structures to be sample with the degenracy equal or smaller than the value.

For example,

builder.sample_structures = Dict(dict={
    'low_energy': 2,
    'high_energy': 2,
    'random': 2,
})

save_as_archive¶

In disordered materials, we often face cases where the number of resulting structures after enumeration are in the order of thousands, millions, and even billions. Therefore, it is not feasible to store all of them seperately. In these case, we can set the save_as_archive to True. All structures will be stored but in a single file named aiida_supercell.tar.gz and will be retrieved to the repository.

Available inputs and outputs¶

calcjobaiida_supercell.calculations.SupercellCalculation

This is a SupercellCalculation, subclass of JobCalculation, to prepare input for enumerating structures using Supercell program

Inputs:

calculate_coulomb_energies, Bool, optional – Whether to calculate Coulomb energies
charge_balance_method, Str, optional – Method to use for charge balancing
charges, Dict, optional – Dictionary of formal charges to be used
code, Code, required – The Code to use for this job.
merge_symmetric, Bool, optional – Whether to merge symmetrically distinct configurations
metadata, Namespace
Namespace Ports
- call_link_label, str, optional, non_db – The label to use for the CALL link if the process is called by another process.
- computer, Computer, optional, non_db – When using a “local” code, set the computer on which the calculation should be run.
- description, str, optional, non_db – Description to set on the process node.
- dry_run, bool, optional, non_db – When set to True will prepare the calculation job for submission but not actually launch it.
- label, str, optional, non_db – Label to set on the process node.
- options, Namespace
  Namespace Ports
  - account, str, optional, non_db – Set the account to use in for the queue on the remote computer
  - additional_retrieve_list, (list, tuple), optional, non_db – List of relative file paths that should be retrieved in addition to what the plugin specifies.
  - append_text, str, optional, non_db – Set the calculation-specific append text, which is going to be appended in the scheduler-job script, just after the code execution
  - custom_scheduler_commands, str, optional, non_db – Set a (possibly multiline) string with the commands that the user wants to manually set for the scheduler. The difference of this option with respect to the prepend_text is the position in the scheduler submission file where such text is inserted: with this option, the string is inserted before any non-scheduler command
  - environment_variables, dict, optional, non_db – Set a dictionary of custom environment variables for this calculation
  - import_sys_environment, bool, optional, non_db – If set to true, the submission script will load the system environment variables
  - input_filename, str, optional, non_db – Filename to which the input for the code that is to be run is written.
  - max_memory_kb, int, optional, non_db – Set the maximum memory (in KiloBytes) to be asked to the scheduler
  - max_wallclock_seconds, int, optional, non_db – Set the wallclock in seconds asked to the scheduler
  - mpirun_extra_params, (list, tuple), optional, non_db – Set the extra params to pass to the mpirun (or equivalent) command after the one provided in computer.mpirun_command. Example: mpirun -np 8 extra_params[0] extra_params[1] … exec.x
  - output_filename, str, optional, non_db
  - parser_name, str, optional, non_db
  - prepend_text, str, optional, non_db – Set the calculation-specific prepend text, which is going to be prepended in the scheduler-job script, just before the code execution
  - priority, str, optional, non_db – Set the priority of the job to be queued
  - qos, str, optional, non_db – Set the quality of service to use in for the queue on the remote computer
  - queue_name, str, optional, non_db – Set the name of the queue on the remote computer
  - resources, dict, required, non_db – Set the dictionary of resources to be used by the scheduler plugin, like the number of nodes, cpus etc. This dictionary is scheduler-plugin dependent. Look at the documentation of the scheduler for more details.
  - scheduler_stderr, str, optional, non_db – Filename to which the content of stderr of the scheduler is written.
  - scheduler_stdout, str, optional, non_db – Filename to which the content of stdout of the scheduler is written.
  - stash, Namespace – Optional directives to stash files after the calculation job has completed.
    
    Namespace Ports
    
    source_list, (tuple, list), optional, non_db – Sequence of relative filepaths representing files in the remote directory that should be stashed.
    
    stash_mode, str, optional, non_db – Mode with which to perform the stashing, should be value of `aiida.common.datastructures.StashMode.
    
    target_base, str, optional, non_db – The base location to where the files should be stashd. For example, for the copy stash mode, this should be an absolute filepath on the remote computer.
  - submit_script_filename, str, optional, non_db – Filename to which the job submission script is written.
  - withmpi, bool, optional, non_db
- store_provenance, bool, optional, non_db – If set to False provenance will not be stored in the database.
random_seed, Int, optional – Random seed number
sample_structures, Dict, optional – How to sample structures from huge configuration space
save_as_archive, Bool, optional – Whether to save resulting structures as archive
structure, (StructureData, SinglefileData), required – Input structure
supercell_size, List, required – Supercell size for enumeration
tolerance, Float, optional – The maximum distance (in Angstroms) between sites that should be contained within the same group.

Outputs:

output_parameters, Dict, required – the results of the calculation
output_structures, Namespace – relaxed structure
remote_folder, RemoteData, required – Input files necessary to run the process will be stored in this folder node.
remote_stash, RemoteStashData, optional – Contents of the stash.source_list option are stored in this remote folder after job completion.
retrieved, FolderData, required – Files that are retrieved by the daemon will be stored in this node. By default the stdout and stderr of the scheduler will be added, but one can add more by specifying them in CalcInfo.retrieve_list.