Submitting computations#
Calculations can be submitted to the server with the add_ functions of a client.
These functions generally take input molecules and a specification.
It is generally possible to submit many calculations at once by supplying a list of input molecules
rather than a single molecule. This will create one computation per molecule, but all with the same specification.
Note
Some computations (like torsiondrives) take multiple input molecules for a single computation, and therefore adding multiple computations requires a nested list.
Hint
If working with lots of calculations, it is almost always better to use a dataset. Datasets allow for coordinating large numbers of similar calculations.
The add_ functions return two objects. The first is qcportal.metadata_models.InsertMetadata
about the insertion, which describes which records were inserted/created, and which already
existed on the server (see Interpreting metadata).
The second object is a list of record IDs, in the order of the input molecule(s). It is always a list, even if only one record is added.
# Add a single computation
>>> mol = Molecule(symbols=['H', 'H'], geometry=[0.0, 0.0, 0.0, 0.0, 0.0, 1.0])
>>> meta, ids = client.add_singlepoints(mol, 'psi4', 'energy', 'hf', 'sto-3g')
>>> print(meta)
InsertMetadata(error_description=None, errors=[], inserted_idx=[0], existing_idx=[])
>>> print(ids)
[940]
# Multiple computations
>>> mol2 = Molecule(symbols=['H', 'H'], geometry=[0.0, 0.0, 0.0, 0.0, 0.0, 2.0])
>>> meta, ids = client.add_singlepoints([mol, mol2], 'psi4', 'energy', 'hf', 'sto-3g')
>>> print(meta)
InsertMetadata(error_description=None, errors=[], inserted_idx=[1], existing_idx=[0])
>>> print(ids)
[940, 941]
The specifics of the add_ functions depends on the type of computation. See the documentation
for different records.
Tag & Priority#
The routing tag and/or priority of a record/task can be specified with the add_ functions as
well. Tasks with a higher priority will be claimed before lower priorities. Priorities can be
specified either as a string or integer (0 = ‘low’, 1 = ‘normal’, 2 = ‘high’),
or as an enum member (like PriorityEnum.high).
See PriorityEnum.
# Add a single computation
>>> mol = Molecule(symbols=['H', 'H'], geometry=[0.0, 0.0, 0.0, 0.0, 0.0, 1.0])
>>> meta, ids = client.add_singlepoints(mol, 'psi4', 'energy', 'b3lyp', 'def2-tzvp', tag='small_mem', priority='high')
>>> print(meta)
InsertMetadata(error_description=None, errors=[], inserted_idx=[0], existing_idx=[])
>>> record = client.get_records(ids[0])
>>> print(record.task.tag)
'small_mem'
Record Deduplication#
New computations that match existing records will not be added; instead, the IDs of the existing records are returned.
What counts as a duplicate calculation varies depending on the type of calculation, but in general is quite strict. This means that small differences will likely result in new calculations being added. Some features that are usually considered are:
Molecules are identical within a tolerance
The program to be used in the computation matches
Basis set and methods exactly match
Keywords and protocols exactly match
Some things that are not considered when finding duplicate calculations:
status
tags
priority
Note
Automatic de-duplication will likely be relaxed in the future, and users will have more fine-grained control of when to de-duplicate.