QCPortal API Reference#

class PortalClient(address, username=None, password=None, verify=True, show_motd=True, *, cache_dir=None, cache_max_size=0, memory_cache_key=None)[source]#

Bases: PortalClientBase

Main class for interacting with a QCArchive server

Parameters:
  • address (str) – The host or IP address of the FractalServer instance, including protocol and port if necessary (”https://ml.qcarchive.molssi.org”, “http://192.168.1.10:8888”)

  • username (Optional[str]) – The username to authenticate with.

  • password (Optional[str]) – The password to authenticate with.

  • verify (bool) – Verifies the SSL connection with a third party server. This may be False if a FractalServer was not provided an SSL certificate and defaults back to self-signed SSL keys.

  • show_motd (bool) – If a Message-of-the-Day is available, display it

  • cache_dir (Optional[str]) – Directory to store an internal cache of records and other data

  • cache_max_size (int) – Maximum size of the cache directory

  • memory_cache_key (Optional[str]) – If set, all clients with the same memory_cache_key will share an in-memory cache. If not specified, a unique one will be generated, meaning this client will not share a memory-based cache with any other clients. Not used if cache_dir is set.

get_server_information()[source]#

Request general information about the server

Returns:

Server information.

Return type:

Dict[str, Any]

get_motd()[source]#

Gets the Message-of-the-Day (MOTD) from the server

Return type:

str

set_motd(new_motd)[source]#

Sets the Message-of-the-Day (MOTD) on the server

Parameters:

new_motd (str) –

Return type:

str

list_datasets()[source]#
list_datasets_table()[source]#
Return type:

str

print_datasets_table()[source]#
Return type:

None

get_dataset(dataset_type, dataset_name)[source]#
Parameters:
  • dataset_type (str) –

  • dataset_name (str) –

query_dataset_records(record_id, dataset_type=None)[source]#
Parameters:
  • record_id (int | Iterable[int]) –

  • dataset_type (Iterable[str] | None) –

get_dataset_by_id(dataset_id)[source]#
Parameters:

dataset_id (int) –

dataset_from_cache(file_path)[source]#
Parameters:

file_path (str) –

Return type:

BaseDataset

create_dataset_view(dataset_id, file_path, include=None, overwrite=False)[source]#
Parameters:
  • dataset_id (int) –

  • file_path (str) –

  • include (Iterable[str] | None) –

  • overwrite (bool) –

get_dataset_status_by_id(dataset_id)[source]#
Parameters:

dataset_id (int) –

Return type:

Dict[str, Dict[RecordStatusEnum, int]]

add_dataset(dataset_type, name, description=None, tagline=None, tags=None, group=None, provenance=None, visibility=True, default_tag='*', default_priority=PriorityEnum.normal, metadata=None, owner_group=None, existing_ok=False)[source]#
Parameters:
  • dataset_type (str) –

  • name (str) –

  • description (str | None) –

  • tagline (str | None) –

  • tags (List[str] | None) –

  • group (str | None) –

  • provenance (Dict[str, Any] | None) –

  • visibility (bool) –

  • default_tag (str) –

  • default_priority (PriorityEnum) –

  • metadata (Dict[str, Any] | None) –

  • owner_group (str | None) –

  • existing_ok (bool) –

Return type:

BaseDataset

delete_dataset(dataset_id, delete_records)[source]#
Parameters:
  • dataset_id (int) –

  • delete_records (bool) –

get_molecules(molecule_ids, missing_ok=False)[source]#

Obtains molecules with the specified IDs from the server

Parameters:
  • molecule_ids (int | Sequence[int]) – A single molecule ID, or a list (or other sequence) of molecule IDs

  • missing_ok (bool) – If set to True, then missing molecules will be tolerated, and the returned list of Molecules will contain None for the corresponding IDs that were not found.

Returns:

Molecules, in the same order as the requested ids. If given a sequence of ids, the return value will be a list. Otherwise, it will be a single Molecule.

Return type:

Molecule | None | List[Molecule | None]

query_molecules(*, molecule_hash=None, molecular_formula=None, identifiers=None, limit=None)[source]#

Query molecules by attributes.

Do not rely on the returned molecules being in any particular order.

Parameters:
  • molecule_hash (str | Iterable[str] | None) – Queries molecules by hash

  • molecular_formula (str | Iterable[str] | None) – Queries molecules by molecular formula. Molecular formulas are not order-sensitive (e.g. “H2O == OH2 != Oh2”).

  • identifiers (Dict[str, str | Iterable[str]] | None) – Additional identifiers to search for (smiles, etc)

  • limit (int | None) – The maximum number of Molecules to return. Note that the server limit is always obeyed.

Returns:

An iterator that can be used to retrieve the results of the query

Return type:

MoleculeQueryIterator

add_molecules(molecules)[source]#

Add molecules to the server database

If the same molecule (defined by having the same hash) already exists, then the existing molecule is kept and that particular molecule is not added.

Parameters:

molecules (Sequence[Molecule]) – A list of Molecules to add to the server.

Returns:

Metadata about what was inserted, and a list of IDs of the molecules in the same order as the molecules parameter.

Return type:

Tuple[InsertMetadata, List[int]]

modify_molecule(molecule_id, name=None, comment=None, identifiers=None, overwrite_identifiers=False)[source]#

Modify molecules on the server

This is only capable of updating the name, comment, and identifiers fields (except molecule_hash and molecular formula).

If a molecule with that id does not exist, an exception is raised

Parameters:
  • molecule_id (int) – ID of the molecule to modify

  • name (str | None) – New name for the molecule. If None, name is not changed.

  • comment (str | None) – New comment for the molecule. If None, comment is not changed

  • identifiers (Dict[str, Any] | Identifiers | None) – A new set of identifiers for the molecule

  • overwrite_identifiers (bool) – If True, the identifiers of the molecule are set to be those given exactly (ie, identifiers that exist in the DB but not in the new set will be removed). Otherwise, the new set of identifiers is merged into the existing ones. Note that molecule_hash and molecular_formula are never removed.

Returns:

Metadata about the modification/update.

Return type:

UpdateMetadata

delete_molecules(molecule_ids)[source]#

Deletes molecules from the server

This will not delete any molecules that are in use

Parameters:

molecule_ids (int | Sequence[int]) – An id or list of ids to query.

Returns:

Metadata about what was deleted

Return type:

DeleteMetadata

get_records(record_ids, missing_ok=False, *, include=None)[source]#

Obtain records of all types with specified IDs

This function will return record objects of the given ID no matter what the type is. All records are unique by ID (ie, an optimization will never have the same ID as a singlepoint).

Records will be returned in the same order as the record ids.

Parameters:
  • record_ids (int | Sequence[int]) – Single ID or sequence/list of records to obtain

  • missing_ok (bool) – If set to True, then missing records will be tolerated, and the returned records will contain None for the corresponding IDs that were not found.

  • include (Iterable[str] | None) – Additional fields to include in the returned record

Returns:

A list of records. If missing_ok was specified, None will be substituted for a record that was not found.

Return type:

List[BaseRecord | None] | BaseRecord | None

query_records(*, record_id=None, record_type=None, manager_name=None, status=None, dataset_id=None, parent_id=None, child_id=None, created_before=None, created_after=None, modified_before=None, modified_after=None, owner_user=None, owner_group=None, limit=None, include=None)[source]#

Query records of all types based on common fields

This is a general query of all record types, so it can only filter by fields that are common among all records.

Do not rely on the returned records being in any particular order.

Parameters:
  • record_id (int | Iterable[int] | None) – Query records whose ID is in the given list

  • record_type (str | Iterable[str] | None) – Query records whose type is in the given list

  • manager_name (str | Iterable[str] | None) – Query records that were completed (or are currently runnning) on a manager is in the given list

  • status (RecordStatusEnum | Iterable[RecordStatusEnum] | None) – Query records whose status is in the given list

  • dataset_id (int | Iterable[int] | None) – Query records that are part of a dataset is in the given list

  • parent_id (int | Iterable[int] | None) – Query records that have a parent is in the given list

  • child_id (int | Iterable[int] | None) – Query records that have a child is in the given list

  • created_before (datetime | str | None) – Query records that were created before the given date/time

  • created_after (datetime | str | None) – Query records that were created after the given date/time

  • modified_before (datetime | str | None) – Query records that were modified before the given date/time

  • modified_after (datetime | str | None) – Query records that were modified after the given date/time

  • owner_user (int | str | Iterable[int | str] | None) – Query records owned by a user in the given list (usernames or IDs)

  • owner_group (int | str | Iterable[int | str] | None) – Query records owned by a group in the given list (group names or IDS)

  • limit (int) – The maximum number of records to return. Note that the server limit is always obeyed.

  • include (Iterable[str] | None) – Additional fields to include in the returned record

Returns:

An iterator that can be used to retrieve the results of the query

Return type:

RecordQueryIterator[BaseRecord]

reset_records(record_ids)[source]#

Resets running or errored records to be waiting again

Parameters:

record_ids (int | Sequence[int]) –

Return type:

UpdateMetadata

cancel_records(record_ids)[source]#

Marks running, waiting, or errored records as cancelled

A cancelled record will not be picked up by a manager.

Parameters:

record_ids (int | Sequence[int]) –

Return type:

UpdateMetadata

invalidate_records(record_ids)[source]#

Marks a completed record as invalid

An invalid record is one that supposedly successfully completed. However, after review, is not correct.

Parameters:

record_ids (int | Sequence[int]) –

Return type:

UpdateMetadata

delete_records(record_ids, soft_delete=True, delete_children=True)[source]#

Delete records from the database

If soft_delete is True, then the record is just marked as deleted and actually deletion may happen later. Soft delete can be undone with undelete

Parameters:
  • record_ids (int | Sequence[int]) – Reset the status of these record ids

  • soft_delete – Don’t actually delete the record, just mark it for later deletion

  • delete_children (bool) – If True, attempt to delete child records as well

Return type:

DeleteMetadata

uninvalidate_records(record_ids)[source]#

Undo the invalidation of records

Parameters:

record_ids (int | Sequence[int]) –

Return type:

UpdateMetadata

uncancel_records(record_ids)[source]#

Undo the cancellation of records

Parameters:

record_ids (int | Sequence[int]) –

Return type:

UpdateMetadata

undelete_records(record_ids)[source]#

Undo the (soft) deletion of records

Parameters:

record_ids (int | Sequence[int]) –

Return type:

UpdateMetadata

modify_records(record_ids, new_tag=None, new_priority=None)[source]#

Modify the tag or priority of a record

Parameters:
  • record_ids (int | Sequence[int]) –

  • new_tag (str | None) –

  • new_priority (PriorityEnum | None) –

Return type:

UpdateMetadata

add_comment(record_ids, comment)[source]#

Adds a comment to records

Parameters:
  • record_ids (int | Sequence[int]) – The record or records to add the comments to

  • comment (str) – The comment string to add. Your username will be added automatically

Returns:

Metadata about which records were updated

Return type:

UpdateMetadata

get_waiting_reason(record_id)[source]#

Get the reason a record is in the waiting status

The return is a dictionary, with a ‘reason’ key containing the overall reason the record is waiting. If appropriate, there is a ‘details’ key that contains information for each active compute manager on why that manager is not able to pick up the record’s task.

Parameters:

record_id (int) – The record ID to test

Returns:

A dictionary containing information about why the record is not being picked up by compute managers

Return type:

Dict[str, Any]

add_singlepoints(molecules, program, driver, method, basis, keywords=None, protocols=None, tag='*', priority=PriorityEnum.normal, owner_group=None, find_existing=True)[source]#

Adds new singlepoint computations to the server

This checks if the calculations already exist in the database. If so, it returns the existing id, otherwise it will insert it and return the new id.

This will add one record per molecule.

Parameters:
  • molecules (int | Molecule | List[int | Molecule]) – The Molecules or Molecule ids to compute with the above methods

  • program (str) – The computational program to execute the result with (e.g., “rdkit”, “psi4”).

  • driver (str) – The primary result that the compute will acquire {“energy”, “gradient”, “hessian”, “properties”}

  • method (str) – The computational method to use (e.g., “B3LYP”, “PBE”)

  • basis (str | None) – The basis to apply to the computation (e.g., “cc-pVDZ”, “6-31G”)

  • keywords (Dict[str, Any] | None) – The program-specific keywords for the computation

  • protocols (AtomicResultProtocols | Dict[str, Any] | None) – Protocols for storing more/less data for each computation

  • tag (str) – The tag for the task. This will assist in routing to appropriate compute managers.

  • priority (PriorityEnum) – The priority of the job (high, normal, low). Default is normal.

  • owner_group (str | None) – Group with additional permission for these records

  • find_existing (bool) – If True, search for existing records and return those. If False, always add new records

Returns:

Metadata about the insertion, and a list of record ids. The ids will be in the order of the input molecules

Return type:

Tuple[InsertMetadata, List[int]]

get_singlepoints(record_ids, missing_ok=False, *, include=None)[source]#

Obtain singlepoint records with the specified IDs.

Records will be returned in the same order as the record ids.

Parameters:
  • record_ids (int | Sequence[int]) – Single ID or sequence/list of records to obtain

  • missing_ok (bool) – If set to True, then missing records will be tolerated, and the returned records will contain None for the corresponding IDs that were not found.

  • include (Iterable[str] | None) – Additional fields to include in the returned record

Returns:

If a single ID was specified, returns just that record. Otherwise, returns a list of records. If missing_ok was specified, None will be substituted for a record that was not found.

Return type:

SinglepointRecord | None | List[SinglepointRecord | None]

query_singlepoints(*, record_id=None, manager_name=None, status=None, dataset_id=None, parent_id=None, created_before=None, created_after=None, modified_before=None, modified_after=None, program=None, driver=None, method=None, basis=None, keywords=None, molecule_id=None, owner_user=None, owner_group=None, limit=None, include=None)[source]#

Queries singlepoint records on the server

Do not rely on the returned records being in any particular order.

Parameters:
  • record_id (int | Iterable[int] | None) – Query records whose ID is in the given list

  • manager_name (str | Iterable[str] | None) – Query records that were completed (or are currently runnning) on a manager is in the given list

  • status (RecordStatusEnum | Iterable[RecordStatusEnum] | None) – Query records whose status is in the given list

  • dataset_id (int | Iterable[int] | None) – Query records that are part of a dataset is in the given list

  • parent_id (int | Iterable[int] | None) – Query records that have a parent is in the given list

  • created_before (datetime | str | None) – Query records that were created before the given date/time

  • created_after (datetime | str | None) – Query records that were created after the given date/time

  • modified_before (datetime | str | None) – Query records that were modified before the given date/time

  • modified_after (datetime | str | None) – Query records that were modified after the given date/time

  • program (str | Iterable[str] | None) – Query records whose program is in the given list

  • driver (SinglepointDriver | Iterable[SinglepointDriver] | None) – Query records whose driver is in the given list

  • method (str | Iterable[str] | None) – Query records whose method is in the given list

  • basis (str | Iterable[str | None] | None) – Query records whose basis is in the given list

  • keywords (Dict[str, Any] | Iterable[Dict[str, Any]] | None) – Query records with these keywords (exact match)

  • molecule_id (int | Iterable[int] | None) – Query records whose molecule (id) is in the given list

  • owner_user (int | str | Iterable[int | str] | None) – Query records owned by a user in the given list

  • owner_group (int | str | Iterable[int | str] | None) – Query records owned by a group in the given list

  • limit (int | None) – The maximum number of records to return. Note that the server limit is always obeyed.

  • include (Iterable[str] | None) – Additional fields to include in the returned record

Returns:

An iterator that can be used to retrieve the results of the query

Return type:

RecordQueryIterator[SinglepointRecord]

add_optimizations(initial_molecules, program, qc_specification, keywords=None, protocols=None, tag='*', priority=PriorityEnum.normal, owner_group=None, find_existing=True)[source]#

Adds new geometry optimization calculations to the server

This checks if the calculations already exist in the database. If so, it returns the existing id, otherwise it will insert it and return the new id.

This will add one record per initial molecule.

Parameters:
  • initial_molecules (int | Molecule | List[int | Molecule]) – Initial molecule/geometry to optimize

  • program (str) – Which program to use for the optimization (ie, geometric)

  • qc_specification (QCSpecification) – The method, basis, etc, to optimize the geometry with

  • keywords (Dict[str, Any] | None) – Program-specific keywords for the optimization program (not the qc program)

  • protocols (OptimizationProtocols | None) – Protocols for storing more/less data for each computation (for the optimization)

  • tag (str) – The tag for the task. This will assist in routing to appropriate compute managers.

  • priority (PriorityEnum) – The priority of the job (high, normal, low). Default is normal.

  • owner_group (str | None) – Group with additional permission for these records

  • find_existing (bool) – If True, search for existing records and return those. If False, always add new records

Returns:

Metadata about the insertion, and a list of record ids. The ids will be in the order of the input molecules

Return type:

Tuple[InsertMetadata, List[int]]

get_optimizations(record_ids, missing_ok=False, *, include=None)[source]#

Obtain optimization records with the specified IDs.

Records will be returned in the same order as the record ids.

Parameters:
  • record_ids (int | Sequence[int]) – Single ID or sequence/list of records to obtain

  • missing_ok (bool) – If set to True, then missing records will be tolerated, and the returned records will contain None for the corresponding IDs that were not found.

  • include (Iterable[str] | None) – Additional fields to include in the returned record

Returns:

If a single ID was specified, returns just that record. Otherwise, returns a list of records. If missing_ok was specified, None will be substituted for a record that was not found.

Return type:

OptimizationRecord | None | List[OptimizationRecord | None]

query_optimizations(*, record_id=None, manager_name=None, status=None, dataset_id=None, parent_id=None, child_id=None, created_before=None, created_after=None, modified_before=None, modified_after=None, program=None, qc_program=None, qc_method=None, qc_basis=None, initial_molecule_id=None, final_molecule_id=None, owner_user=None, owner_group=None, limit=None, include=None)[source]#

Queries optimization records on the server

Do not rely on the returned records being in any particular order.

Parameters:
  • record_id (int | Iterable[int] | None) – Query records whose ID is in the given list

  • manager_name (str | Iterable[str] | None) – Query records that were completed (or are currently runnning) on a manager is in the given list

  • status (RecordStatusEnum | Iterable[RecordStatusEnum] | None) – Query records whose status is in the given list

  • dataset_id (int | Iterable[int] | None) – Query records that are part of a dataset is in the given list

  • parent_id (int | Iterable[int] | None) – Query records that have a parent is in the given list

  • child_id (int | Iterable[int] | None) – Query records that have a child (singlepoint calculation) is in the given list

  • created_before (datetime | str | None) – Query records that were created before the given date/time

  • created_after (datetime | str | None) – Query records that were created after the given date/time

  • modified_before (datetime | str | None) – Query records that were modified before the given date/time

  • modified_after (datetime | str | None) – Query records that were modified after the given date/time

  • program (str | Iterable[str] | None) – Query records whose optimization program is in the given list

  • qc_program (str | Iterable[str] | None) – Query records whose qc program is in the given list

  • qc_method (str | Iterable[str] | None) – Query records whose method is in the given list

  • qc_basis (str | Iterable[str | None] | None) – Query records whose basis is in the given list

  • initial_molecule_id (int | Iterable[int] | None) – Query records whose initial molecule (id) is in the given list

  • final_molecule_id (int | Iterable[int] | None) – Query records whose final molecule (id) is in the given list

  • owner_user (int | str | Iterable[int | str] | None) – Query records owned by a user in the given list

  • owner_group (int | str | Iterable[int | str] | None) – Query records owned by a group in the given list

  • limit (int | None) – The maximum number of records to return. Note that the server limit is always obeyed.

  • include (Iterable[str] | None) – Additional fields to include in the returned record

Returns:

An iterator that can be used to retrieve the results of the query

Return type:

RecordQueryIterator[OptimizationRecord]

add_torsiondrives(initial_molecules, program, optimization_specification, keywords, tag='*', priority=PriorityEnum.normal, owner_group=None, find_existing=True)[source]#

Adds new torsiondrive computations to the server

This checks if the calculations already exist in the database. If so, it returns the existing id, otherwise it will insert it and return the new id.

This will add one record per set of molecules

Parameters:
  • initial_molecules (List[List[int | Molecule]]) – Molecules to start the torsiondrives. Each torsiondrive can start with multiple molecules, so this is a nested list

  • program (str) – The program to run the torsiondrive computation with (“torsiondrive”)

  • optimization_specification (OptimizationSpecification) – Specification of how each optimization of the torsiondrive should be run

  • keywords (TorsiondriveKeywords | Dict[str, Any]) – The torsiondrive keywords for the computation

  • tag (str) – The tag for the task. This will assist in routing to appropriate compute managers.

  • priority (PriorityEnum) – The priority of the job (high, normal, low). Default is normal.

  • owner_group (str | None) – Group with additional permission for these records

  • find_existing (bool) – If True, search for existing records and return those. If False, always add new records

Returns:

Metadata about the insertion, and a list of record ids. The ids will be in the order of the input molecules

Return type:

Tuple[InsertMetadata, List[int]]

get_torsiondrives(record_ids, missing_ok=False, *, include=None)[source]#

Obtain torsiondrive records with the specified IDs.

Records will be returned in the same order as the record ids.

Parameters:
  • record_ids (int | Sequence[int]) – Single ID or sequence/list of records to obtain

  • missing_ok (bool) – If set to True, then missing records will be tolerated, and the returned records will contain None for the corresponding IDs that were not found.

  • include (Iterable[str] | None) – Additional fields to include in the returned record

Returns:

If a single ID was specified, returns just that record. Otherwise, returns a list of records. If missing_ok was specified, None will be substituted for a record that was not found.

Return type:

TorsiondriveRecord | None | List[TorsiondriveRecord | None]

query_torsiondrives(*, record_id=None, manager_name=None, status=None, dataset_id=None, parent_id=None, child_id=None, created_before=None, created_after=None, modified_before=None, modified_after=None, program=None, optimization_program=None, qc_program=None, qc_method=None, qc_basis=None, initial_molecule_id=None, owner_user=None, owner_group=None, limit=None, include=None)[source]#

Queries torsiondrive records on the server

Do not rely on the returned records being in any particular order.

Parameters:
  • record_id (int | Iterable[int] | None) – Query records whose ID is in the given list

  • manager_name (str | Iterable[str] | None) – Query records that were completed (or are currently runnning) on a manager is in the given list

  • status (RecordStatusEnum | Iterable[RecordStatusEnum] | None) – Query records whose status is in the given list

  • dataset_id (int | Iterable[int] | None) – Query records that are part of a dataset is in the given list

  • parent_id (int | Iterable[int] | None) – Query records that have a parent is in the given list

  • child_id (int | Iterable[int] | None) – Query records that have a child (optimization calculation) is in the given list

  • created_before (datetime | str | None) – Query records that were created before the given date/time

  • created_after (datetime | str | None) – Query records that were created after the given date/time

  • modified_before (datetime | str | None) – Query records that were modified before the given date/time

  • modified_after (datetime | str | None) – Query records that were modified after the given date/time

  • program (str | Iterable[str] | None) – Query records whose torsiondrive program is in the given list

  • optimization_program (str | Iterable[str] | None) – Query records whose optimization program is in the given list

  • qc_program (str | Iterable[str] | None) – Query records whose qc program is in the given list

  • qc_method (str | Iterable[str] | None) – Query records whose method is in the given list

  • qc_basis (str | Iterable[str] | None) – Query records whose basis is in the given list

  • initial_molecule_id (int | Iterable[int] | None) – Query records whose initial molecule (id) is in the given list

  • owner_user (int | str | Iterable[int | str] | None) – Query records owned by a user in the given list

  • owner_group (int | str | Iterable[int | str] | None) – Query records owned by a group in the given list

  • limit (int | None) – The maximum number of records to return. Note that the server limit is always obeyed.

  • include (Iterable[str] | None) – Additional fields to include in the returned record

Returns:

An iterator that can be used to retrieve the results of the query

Return type:

RecordQueryIterator[TorsiondriveRecord]

add_gridoptimizations(initial_molecules, program, optimization_specification, keywords, tag='*', priority=PriorityEnum.normal, owner_group=None, find_existing=True)[source]#

Adds new gridoptimization computations to the server

This checks if the calculations already exist in the database. If so, it returns the existing id, otherwise it will insert it and return the new id.

This will add one record per initial molecule

Parameters:
  • initial_molecules (int | Molecule | Sequence[int | Molecule]) –

    Molecules to start the gridoptimizations. Each gridoptimization starts with

    a single molecule.

  • program (str) – The program to run the gridoptimization computation with (“gridoptimization”)

  • optimization_specification (OptimizationSpecification) – Specification of how each optimization of the gridoptimization should be run

  • keywords (GridoptimizationKeywords | Dict[str, Any]) – The gridoptimization keywords for the computation

  • tag (str) – The tag for the task. This will assist in routing to appropriate compute managers.

  • priority (PriorityEnum) – The priority of the job (high, normal, low). Default is normal.

  • owner_group (str | None) – Group with additional permission for these records

  • find_existing (bool) – If True, search for existing records and return those. If False, always add new records

Returns:

Metadata about the insertion, and a list of record ids. The ids will be in the order of the input molecules

Return type:

Tuple[InsertMetadata, List[int]]

get_gridoptimizations(record_ids, missing_ok=False, *, include=None)[source]#

Obtain gridoptimization records with the specified IDs.

Records will be returned in the same order as the record ids.

Parameters:
  • record_ids (int | Sequence[int]) – Single ID or sequence/list of records to obtain

  • missing_ok (bool) – If set to True, then missing records will be tolerated, and the returned records will contain None for the corresponding IDs that were not found.

  • include (Iterable[str] | None) – Additional fields to include in the returned record

Returns:

If a single ID was specified, returns just that record. Otherwise, returns a list of records. If missing_ok was specified, None will be substituted for a record that was not found.

Return type:

GridoptimizationRecord | None | List[GridoptimizationRecord | None]

query_gridoptimizations(*, record_id=None, manager_name=None, status=None, dataset_id=None, parent_id=None, child_id=None, created_before=None, created_after=None, modified_before=None, modified_after=None, program=None, optimization_program=None, qc_program=None, qc_method=None, qc_basis=None, initial_molecule_id=None, owner_user=None, owner_group=None, limit=None, include=None)[source]#

Queries gridoptimization records on the server

Do not rely on the returned records being in any particular order.

Parameters:
  • record_id (int | Iterable[int] | None) – Query records whose ID is in the given list

  • manager_name (str | Iterable[str] | None) – Query records that were completed (or are currently runnning) on a manager is in the given list

  • status (RecordStatusEnum | Iterable[RecordStatusEnum] | None) – Query records whose status is in the given list

  • dataset_id (int | Iterable[int] | None) – Query records that are part of a dataset is in the given list

  • parent_id (int | Iterable[int] | None) – Query records that have a parent is in the given list

  • child_id (int | Iterable[int] | None) – Query records that have a child (optimization calculation) is in the given list

  • created_before (datetime | str | None) – Query records that were created before the given date/time

  • created_after (datetime | str | None) – Query records that were created after the given date/time

  • modified_before (datetime | str | None) – Query records that were modified before the given date/time

  • modified_after (datetime | str | None) – Query records that were modified after the given date/time

  • program (str | Iterable[str] | None) – Query records whose gridoptimization program is in the given list

  • optimization_program (str | Iterable[str] | None) – Query records whose optimization program is in the given list

  • qc_program (str | Iterable[str] | None) – Query records whose qc program is in the given list

  • qc_method (str | Iterable[str] | None) – Query records whose method is in the given list

  • qc_basis (str | Iterable[str | None] | None) – Query records whose basis is in the given list

  • initial_molecule_id (int | Iterable[int] | None) – Query records whose initial molecule (id) is in the given list

  • owner_user (int | str | Iterable[int | str] | None) – Query records owned by a user in the given list

  • owner_group (int | str | Iterable[int | str] | None) – Query records owned by a group in the given list

  • limit (int | None) – The maximum number of records to return. Note that the server limit is always obeyed.

  • include (Iterable[str] | None) – Additional fields to include in the returned record

Returns:

An iterator that can be used to retrieve the results of the query

Return type:

RecordQueryIterator[GridoptimizationRecord]

add_reactions(stoichiometries, program, singlepoint_specification, optimization_specification, keywords, tag='*', priority=PriorityEnum.normal, owner_group=None, find_existing=True)[source]#

Adds new reaction computations to the server

Reactions can have a singlepoint specification, optimization specification, or both; at least one must be specified. If both are specified, an optimization is done, followed by a singlepoint computation. Otherwise, only the specification that is specified is used.

This checks if the calculations already exist in the database. If so, it returns the existing id, otherwise it will insert it and return the new id.

This will add one record per set of molecules

Parameters:
  • stoichiometries (Sequence[Sequence[Sequence[float, Union[int, Molecule]]]]) – Coefficients and molecules of the reaction. Each reaction has multiple molecules/coefficients, so this is a nested list

  • program (str) – The program for running the reaction computation (“reaction”)

  • singlepoint_specification (Optional[QCSpecification]) – The specification for singlepoint energy calculations

  • optimization_specification (Optional[OptimizationSpecification]) – The specification for optimization calculations

  • keywords (ReactionKeywords) – The keywords for the reaction calculation/service

  • tag (str) – The tag for the task. This will assist in routing to appropriate compute managers.

  • priority (PriorityEnum) – The priority of the job (high, normal, low). Default is normal.

  • owner_group (Optional[str]) – Group with additional permission for these records

  • find_existing (bool) – If True, search for existing records and return those. If False, always add new records

Returns:

Metadata about the insertion, and a list of record ids. The ids will be in the order of the input molecules

Return type:

Tuple[InsertMetadata, List[int]]

get_reactions(record_ids, missing_ok=False, *, include=None)[source]#

Obtain reaction records with the specified IDs.

Records will be returned in the same order as the record ids.

Parameters:
  • record_ids (int | Sequence[int]) – Single ID or sequence/list of records to obtain

  • missing_ok (bool) – If set to True, then missing records will be tolerated, and the returned records will contain None for the corresponding IDs that were not found.

  • include (Iterable[str] | None) – Additional fields to include in the returned record

Returns:

If a single ID was specified, returns just that record. Otherwise, returns a list of records. If missing_ok was specified, None will be substituted for a record that was not found.

Return type:

ReactionRecord | None | List[ReactionRecord | None]

query_reactions(*, record_id=None, manager_name=None, status=None, dataset_id=None, parent_id=None, child_id=None, created_before=None, created_after=None, modified_before=None, modified_after=None, program=None, optimization_program=None, qc_program=None, qc_method=None, qc_basis=None, molecule_id=None, owner_user=None, owner_group=None, limit=None, include=None)[source]#

Queries reaction records on the server

Do not rely on the returned records being in any particular order.

Parameters:
  • record_id (int | Iterable[int] | None) – Query records whose ID is in the given list

  • manager_name (str | Iterable[str] | None) – Query records that were completed (or are currently runnning) on a manager is in the given list

  • status (RecordStatusEnum | Iterable[RecordStatusEnum] | None) – Query records whose status is in the given list

  • dataset_id (int | Iterable[int] | None) – Query records that are part of a dataset is in the given list

  • parent_id (int | Iterable[int] | None) – Query records that have a parent is in the given list

  • child_id (int | Iterable[int] | None) – Query records that have a child (optimization calculation) is in the given list

  • created_before (datetime | str | None) – Query records that were created before the given date/time

  • created_after (datetime | str | None) – Query records that were created after the given date/time

  • modified_before (datetime | str | None) – Query records that were modified before the given date/time

  • modified_after (datetime | str | None) – Query records that were modified after the given date/time

  • program (str | Iterable[str] | None) – Query records whose reaction program is in the given list

  • optimization_program (Iterable[str | None] | None) – Query records whose optimization program is in the given list

  • qc_program (str | Iterable[str] | None) – Query records whose qc program is in the given list

  • qc_method (str | Iterable[str] | None) – Query records whose method is in the given list

  • qc_basis (str | Iterable[str] | None) – Query records whose basis is in the given list

  • molecule_id (int | Iterable[int] | None) – Query reactions that contain a molecule (id) is in the given list

  • owner_user (int | str | Iterable[int | str] | None) – Query records owned by a user in the given list

  • owner_group (int | str | Iterable[int | str] | None) – Query records owned by a group in the given list

  • limit (int | None) – The maximum number of records to return. Note that the server limit is always obeyed.

  • include (Iterable[str] | None) – Additional fields to include in the returned record

Returns:

An iterator that can be used to retrieve the results of the query

Return type:

RecordQueryIterator[ReactionRecord]

add_manybodys(initial_molecules, program, singlepoint_specification, keywords, tag='*', priority=PriorityEnum.normal, owner_group=None, find_existing=True)[source]#

Adds new manybody expansion computations to the server

This checks if the calculations already exist in the database. If so, it returns the existing id, otherwise it will insert it and return the new id.

This will add one record per initial molecule.

Parameters:
  • initial_molecules (Sequence[int | Molecule]) – Initial molecules for the manybody expansion. Must have > 1 fragments.

  • program (str) – The program to run the manybody computation with (“manybody”)

  • singlepoint_specification (QCSpecification) – Specification for the singlepoint calculations done in the expansion

  • keywords (ManybodyKeywords) – The keywords for the manybody program

  • tag (str) – The tag for the task. This will assist in routing to appropriate compute managers.

  • priority (PriorityEnum) – The priority of the job (high, normal, low). Default is normal.

  • owner_group (str | None) – Group with additional permission for these records

  • find_existing (bool) – If True, search for existing records and return those. If False, always add new records

Returns:

Metadata about the insertion, and a list of record ids. The ids will be in the order of the input molecules

Return type:

Tuple[InsertMetadata, List[int]]

get_manybodys(record_ids, missing_ok=False, *, include=None)[source]#

Obtain manybody records with the specified IDs.

Records will be returned in the same order as the record ids.

Parameters:
  • record_ids (int | Sequence[int]) – Single ID or sequence/list of records to obtain

  • missing_ok (bool) – If set to True, then missing records will be tolerated, and the returned records will contain None for the corresponding IDs that were not found.

  • include (Iterable[str] | None) – Additional fields to include in the returned record

Returns:

If a single ID was specified, returns just that record. Otherwise, returns a list of records. If missing_ok was specified, None will be substituted for a record that was not found.

Return type:

ManybodyRecord | None | List[ManybodyRecord | None]

query_manybodys(*, record_id=None, manager_name=None, status=None, dataset_id=None, parent_id=None, child_id=None, created_before=None, created_after=None, modified_before=None, modified_after=None, program=None, qc_program=None, qc_method=None, qc_basis=None, initial_molecule_id=None, owner_user=None, owner_group=None, limit=None, include=None)[source]#

Queries reaction records on the server

Do not rely on the returned records being in any particular order.

Parameters:
  • record_id (int | Iterable[int] | None) – Query records whose ID is in the given list

  • manager_name (str | Iterable[str] | None) – Query records that were completed (or are currently runnning) on a manager is in the given list

  • status (RecordStatusEnum | Iterable[RecordStatusEnum] | None) – Query records whose status is in the given list

  • dataset_id (int | Iterable[int] | None) – Query records that are part of a dataset is in the given list

  • parent_id (int | Iterable[int] | None) – Query records that have a parent is in the given list

  • child_id (int | Iterable[int] | None) – Query records that have a child (optimization calculation) is in the given list

  • created_before (datetime | str | None) – Query records that were created before the given date/time

  • created_after (datetime | str | None) – Query records that were created after the given date/time

  • modified_before (datetime | str | None) – Query records that were modified before the given date/time

  • modified_after (datetime | str | None) – Query records that were modified after the given date/time

  • program (str | Iterable[str] | None) – Query records whose reaction program is in the given list

  • qc_program (str | Iterable[str] | None) – Query records whose qc program is in the given list

  • qc_method (str | Iterable[str] | None) – Query records whose qc method is in the given list

  • qc_basis (str | Iterable[str] | None) – Query records whose qc basis is in the given list

  • initial_molecule_id (int | Iterable[int] | None) – Query manybody calculations that contain an initial molecule (id) is in the given list

  • owner_user (int | str | Iterable[int | str] | None) – Query records owned by a user in the given list

  • owner_group (int | str | Iterable[int | str] | None) – Query records owned by a group in the given list

  • limit (int | None) – The maximum number of records to return. Note that the server limit is always obeyed.

  • include (Iterable[str] | None) – Additional fields to include in the returned record

Returns:

An iterator that can be used to retrieve the results of the query

Return type:

RecordQueryIterator[ManybodyRecord]

add_nebs(initial_chains, program, singlepoint_specification, optimization_specification, keywords, tag='*', priority=PriorityEnum.normal, owner_group=None, find_existing=True)[source]#

Adds neb calculations to the server

This checks if the calculations already exist in the database. If so, it returns the existing id, otherwise it will insert it and return the new id.

This will add one record per set of molecules

Parameters:
  • initial_chains (List[List[int | Molecule]]) – The initial chains to run the NEB calculations on . Each NEB calculation starts with a single chain (list of molecules), so this is a nested list

  • program (str) – The program to run the neb computation with (“geometric”)

  • singlepoint_specification (QCSpecification) – Specification of how each singlepoint (gradient/hessian) should be run

  • optimization_specification (OptimizationSpecification | None) – Specification of how any optimizations of the torsiondrive should be run

  • keywords (NEBKeywords | Dict[str, Any]) – The torsiondrive keywords for the computation

  • tag (str) – The tag for the task. This will assist in routing to appropriate compute managers.

  • priority (PriorityEnum) – The priority of the job (high, normal, low). Default is normal.

  • owner_group (str | None) – Group with additional permission for these records

  • find_existing (bool) – If True, search for existing records and return those. If False, always add new records

Returns:

Metadata about the insertion, and a list of record ids. The ids will be in the order of the input molecules

Return type:

Tuple[InsertMetadata, List[int]]

get_nebs(record_ids, missing_ok=False, *, include=None)[source]#

Obtain NEB records with the specified IDs.

Records will be returned in the same order as the record ids.

Parameters:
  • record_ids (int | Sequence[int]) – Single ID or sequence/list of records to obtain

  • missing_ok (bool) – If set to True, then missing records will be tolerated, and the returned records will contain None for the corresponding IDs that were not found.

  • include (Iterable[str] | None) – Additional fields to include in the returned record

Returns:

If a single ID was specified, returns just that record. Otherwise, returns a list of records. If missing_ok was specified, None will be substituted for a record that was not found.

Return type:

NEBRecord | None | List[NEBRecord | None]

query_nebs(*, record_id=None, manager_name=None, status=None, dataset_id=None, parent_id=None, child_id=None, created_before=None, created_after=None, modified_before=None, modified_after=None, program=None, qc_program=None, qc_method=None, qc_basis=None, molecule_id=None, owner_user=None, owner_group=None, limit=None, include=None)[source]#

Queries neb records from the server

Do not rely on the returned records being in any particular order.

Parameters:
  • record_id (int | Iterable[int] | None) – Query records whose ID is in the given list

  • manager_name (str | Iterable[str] | None) – Query records that were completed (or are currently runnning) on a manager is in the given list

  • status (RecordStatusEnum | Iterable[RecordStatusEnum] | None) – Query records whose status is in the given list

  • dataset_id (int | Iterable[int] | None) – Query records that are part of a dataset is in the given list

  • parent_id (int | Iterable[int] | None) – Query records that have a parent is in the given list

  • child_id (int | Iterable[int] | None) – Query records that have a child (optimization calculation) is in the given list

  • created_before (datetime | str | None) – Query records that were created before the given date/time

  • created_after (datetime | str | None) – Query records that were created after the given date/time

  • modified_before (datetime | str | None) – Query records that were modified before the given date/time

  • modified_after (datetime | str | None) – Query records that were modified after the given date/time

  • program (str | Iterable[str] | None) – Query records whose torsiondrive program is in the given list

  • qc_program (str | Iterable[str] | None) – Query records whose qc program is in the given list

  • qc_method (str | Iterable[str] | None) – Query records whose method is in the given list

  • qc_basis (str | Iterable[str] | None) – Query records whose basis is in the given list

  • molecule_id (int | Iterable[int] | None) – Query records whose initial chains contain a molecule (id) that is in the given list

  • owner_user (int | str | Iterable[int | str] | None) – Query records owned by a user in the given list

  • owner_group (int | str | Iterable[int | str] | None) – Query records owned by a group in the given list

  • limit (int | None) – The maximum number of records to return. Note that the server limit is always obeyed.

  • include (Iterable[str] | None) – Additional fields to include in the returned record

Returns:

An iterator that can be used to retrieve the results of the query

Return type:

RecordQueryIterator[NEBRecord]

get_managers(names, missing_ok=False)[source]#

Obtain manager information from the server with the specified names

Parameters:
  • names (str | Sequence[str]) – A manager name or list of names

  • missing_ok (bool) – If set to True, then missing managers will be tolerated, and the returned managers will contain None for the corresponding managers that were not found.

Returns:

If a single name was specified, returns just that manager. Otherwise, returns a list of managers. If missing_ok was specified, None will be substituted for a manager that was not found.

Return type:

ComputeManager | None | List[ComputeManager | None]

query_managers(*, manager_id=None, name=None, cluster=None, hostname=None, status=None, modified_before=None, modified_after=None, limit=None)[source]#

Queries manager information on the server

Parameters:
  • manager_id (int | Iterable[int] | None) – ID assigned to the manager (this is not the UUID. This should be used very rarely).

  • name (str | Iterable[str] | None) – Queries managers whose name is in the given list

  • cluster (str | Iterable[str] | None) – Queries managers whose assigned cluster is in the given list

  • hostname (str | Iterable[str] | None) – Queries managers whose hostname is in the given list

  • status (RecordStatusEnum | Iterable[RecordStatusEnum] | None) – Queries managers whose status is in the given list

  • modified_before (datetime | str | None) – Query for managers last modified before a certain time

  • modified_after (datetime | str | None) – Query for managers last modified after a certain time

  • limit (int | None) – The maximum number of managers to return. Note that the server limit is always obeyed.

Returns:

An iterator that can be used to retrieve the results of the query

Return type:

ManagerQueryIterator

query_server_stats(*, before=None, after=None, limit=None)[source]#

Query server statistics

These statistics are captured at certain times, and are available for querying (as long as they are not deleted)

Parameters:
  • before (datetime | str | None) – Return statistics captured before the specified date/time

  • after (datetime | str | None) – Return statistics captured after the specified date/time

  • limit (int | None) – The maximum number of statistics entries to return. Note that the server limit is always obeyed.

Returns:

An iterator that can be used to retrieve the results of the query

Return type:

ServerStatsQueryIterator

delete_server_stats(before)[source]#

Delete server statistics from the server

Parameters:

before (datetime) – Delete statistics captured before the given date/time

Returns:

The number of statistics entries deleted from the server

Return type:

int

query_access_log(*, module=None, method=None, before=None, after=None, user=None, limit=None)[source]#

Query the server access log

This log contains information about who accessed the server, and when.

Parameters:
  • module (str | Iterable[str] | None) – Return log entries whose module is in the given list

  • method (str | Iterable[str] | None) – Return log entries whose access_method is in the given list

  • before (datetime | str | None) – Return log entries captured before the specified date/time

  • after (datetime | str | None) – Return log entries captured after the specified date/time

  • user (int | str | Iterable[int | str] | None) – User name or ID associated with the log entry

  • limit (int | None) – The maximum number of log entries to return. Note that the server limit is always obeyed.

Returns:

An iterator that can be used to retrieve the results of the query

Return type:

AccessLogQueryIterator

delete_access_log(before)[source]#

Delete access log entries from the server

Parameters:

before (datetime) – Delete access log entries captured before the given date/time

Returns:

The number of access log entries deleted from the server

Return type:

int

query_error_log(*, error_id=None, user=None, before=None, after=None, limit=None)[source]#

Query the server’s internal error log

This log contains internal errors that are not always passed to the user.

Parameters:
  • error_id (int | Iterable[int] | None) – Return error log entries whose id is in the list

  • user (int | str | Iterable[int | str] | None) – Return error log entries whose user name or ID is in the list

  • before (datetime | str | None) – Return error log entries captured before the specified date/time

  • after (datetime | str | None) – Return error log entries captured after the specified date/time

  • limit (int | None) – The maximum number of log entries to return. Note that the server limit is always obeyed.

Returns:

An iterator that can be used to retrieve the results of the query

Return type:

ErrorLogQueryIterator

delete_error_log(before)[source]#

Delete error log entries from the server

Parameters:

before (datetime) – Delete error log entries captured before the given date/time

Returns:

The number of error log entries deleted from the server

Return type:

int

get_internal_job(job_id)[source]#

Gets information about an internal job on the server

Parameters:

job_id (int) –

Return type:

InternalJob

query_internal_jobs(*, job_id=None, name=None, user=None, runner_hostname=None, status=None, last_updated_before=None, last_updated_after=None, added_before=None, added_after=None, scheduled_before=None, scheduled_after=None, limit=None)[source]#

Queries the internal job queue on the server

Parameters:
  • job_id (Optional[int, Iterable[int]]) – ID assigned to the job

  • name (Optional[Union[str, Iterable[str]]]) – Queries jobs whose name is in the given list

  • user (Optional[Union[int, str, Iterable[Union[int, str]]]]) – User name or ID associated with the log entry

  • runner_hostname (Optional[Union[str, Iterable[str]]]) – Queries jobs that were run/are running on a given host

  • status (Optional[Union[InternalJobStatusEnum, Iterable[InternalJobStatusEnum]]]) – Queries jobs whose status is in the given list

  • last_updated_before (Optional[Union[datetime, str]]) – Query for jobs last updated before a certain time

  • last_updated_after (Optional[Union[datetime, str]]) – Query for jobs last updated after a certain time

  • added_before (Optional[Union[datetime, str]]) – Query for jobs added before a certain time

  • added_after (Optional[Union[datetime, str]]) – Query for jobs added after a certain time

  • scheduled_before (Optional[Union[datetime, str]]) – Query for jobs scheduled to run before a certain time

  • scheduled_after (Optional[Union[datetime, str]]) – Query for jobs scheduled to run after a certain time

  • limit (Optional[int]) – The maximum number of jobs to return. Note that the server limit is always obeyed.

Returns:

An iterator that can be used to retrieve the results of the query

Return type:

InternalJobQueryIterator

cancel_internal_job(job_id)[source]#

Cancels (to the best of our ability) an internal job

Parameters:

job_id (int) –

delete_internal_job(job_id)[source]#
Parameters:

job_id (int) –

query_access_summary(*, group_by='day', before=None, after=None)[source]#

Obtains summaries of access data

This aggregate data is created on the server, so you don’t need to download all the log entries and do it yourself.

Parameters:
  • group_by (str) – How to group the data. Valid options are “user”, “hour”, “day”, “country”, “subdivision”

  • before (datetime | str | None) – Query for log entries with a timestamp before a specific time

  • after (datetime | str | None) – Query for log entries with a timestamp after a specific time

Return type:

AccessLogSummary

list_roles()[source]#

List all user roles on the server

Return type:

List[RoleInfo]

get_role(rolename)[source]#

Get information about a role on the server

Parameters:

rolename (str) –

Return type:

RoleInfo

add_role(role_info)[source]#

Adds a role with permissions to the server

If not successful, an exception is raised.

Parameters:

role_info (RoleInfo) –

Return type:

None

modify_role(role_info)[source]#

Modifies the permissions of a role on the server

If not successful, an exception is raised.

Returns:

A copy of the role as it now appears on the server

Parameters:

role_info (RoleInfo) –

Return type:

RoleInfo

delete_role(rolename)[source]#

Deletes a role from the server

This will not delete any role to which a user is assigned

Will raise an exception on error

Parameters:

rolename (str) – Name of the role to delete

Return type:

None

list_groups()[source]#

List all user groups on the server

Return type:

List[GroupInfo]

get_group(groupname_or_id)[source]#

Get information about a group on the server

Parameters:

groupname_or_id (int | str) –

Return type:

GroupInfo

add_group(group_info)[source]#

Adds a group with permissions to the server

If not successful, an exception is raised.

Parameters:

group_info (GroupInfo) –

Return type:

None

delete_group(groupname_or_id)[source]#

Deletes a group on the server

Deleted groups will be removed from all users groups list

Parameters:

groupname_or_id (int | str) –

list_users()[source]#

List all user roles on the server

Return type:

List[UserInfo]

get_user(username_or_id=None)[source]#

Get information about a user on the server

If the username is not supplied, then info about the currently logged-in user is obtained.

Parameters:

username_or_id (int | str | None) – The username or ID to get info about

Returns:

Information about the user

Return type:

UserInfo

add_user(user_info, password=None)[source]#

Adds a user to the server

Parameters:
  • user_info (UserInfo) – Info about the user to add

  • password (str | None) – The user’s password. If None, then one will be generated

Returns:

The password of the user (either the same as the supplied password, or the server-generated one)

Return type:

str

modify_user(user_info)[source]#

Modifies a user on the server

The user is determined by the id field of the input UserInfo, although the id and username are checked for consistency.

Depending on the current user’s permissions, some fields may not be updatable.

Parameters:

user_info (UserInfo) – Updated information for a user

Returns:

The updated user information as it appears on the server

Return type:

UserInfo

change_user_password(username_or_id=None, new_password=None)[source]#

Change a users password

If the username is not specified, then the current logged-in user is used.

If the password is not specified, then one is automatically generated by the server.

Parameters:
  • username_or_id (int | str | None) – The name or ID of the user whose password to change. If None, then use the currently logged-in user

  • new_password (str | None) – Password to change to. If None, let the server generate one.

Returns:

The new password (either the same as the supplied one, or the server generated one

Return type:

str

delete_user(username_or_id)[source]#

Delete a user from the server

Parameters:

username_or_id (int | str) –

Return type:

None

property encoding: str#
classmethod from_file(server_name=None, config_path=None)#

Creates a new client given information in a file.

If no path is passed in, the current working directory and finally ~/.qca are searched for “qcportal_config.yaml”

Parameters:
  • server_name (str | None) – Name/alias of the server in the yaml file

  • config_path (str | None) – Full path to a configuration file, or a directory containing “qcportal_config.yaml”.

make_request(method, endpoint, response_model, *, body_model=None, url_params_model=None, body=None, url_params=None, allow_retries=True)#
Parameters:
  • method (str) –

  • endpoint (str) –

  • response_model (Type[_V] | None) –

  • body_model (Type[_T] | None) –

  • url_params_model (Type[_U] | None) –

  • body (_T | Dict[str, Any] | None) –

  • url_params (_U | Dict[str, Any] | None) –

  • allow_retries (bool) –

Return type:

_V

ping()#

Pings the server to see if it is up

Returns:

True if the server is up and responded to the ping. False otherwise

Return type:

bool

class MoleculeQueryIterator(client, query_filters)[source]#

Bases: QueryIteratorBase[Molecule]

Iterator for molecule queries

This iterator transparently handles batching and pagination over the results of a molecule query.

Construct an iterator

Parameters:
  • client – QCPortal client object used to contact/retrieve data from the server

  • query_filters (MoleculeQueryFilters) – The actual query information to send to the server

reset()#

Starts retrieval of results from the beginning again