API

Generics

from_file([load_path])

Creates a new FractalClient from file.

server_information()

Pull down various data on the connected server.

Add/Query Objects

query_kvstore(id[, full_return])

Queries items from the database’s KVStore

query_molecules([id, molecule_hash, …])

Queries molecules from the database.

add_molecules(mol_list[, full_return])

Adds molecules to the Server.

query_keywords([id, hash_index, limit, …])

Obtains KeywordSets from the server using keyword ids.

add_keywords(keywords[, full_return])

Adds KeywordSets to the server.

list_collections([collection_type, aslist])

Lists the available collections currently on the server.

get_collection(collection_type, name[, …])

Acquires a given collection from the server.

add_collection(collection[, overwrite, …])

Adds a new Collection to the server.

Records Querying

query_results([id, task_id, program, …])

Queries ResultRecords from the server.

query_procedures([id, task_id, procedure, …])

Queries Procedures from the server.

New Compute Tasks

add_compute(program, method, basis, driver, …)

Adds a “single” compute to the server.

add_procedure(procedure, program, …[, …])

Adds a “single” Procedure to the server.

add_service(service[, tag, priority, …])

Adds a new service to the service queue.

query_tasks([id, hash_index, program, …])

Checks the status of Tasks in the Fractal queue.

query_services([id, procedure_id, …])

Checks the status of services in the Fractal queue.

Function Definitions

qcportal.FractalClient.from_file(load_path: Optional[str] = None) → qcfractal.interface.client.FractalClient

Creates a new FractalClient from file. If no path is passed in, the current working directory and ~.qca/ are searched for “qcportal_config.yaml”

Parameters

load_path (Optional[str], optional) – Path to find “qcportal_config.yaml”, the filename, or a dictionary containing keys {“address”, “username”, “password”, “verify”}

Returns

A new FractalClient from file.

Return type

FractalClient

qcportal.FractalClient.server_information(self) → Dict[str, str]

Pull down various data on the connected server.

Returns

Server information.

Return type

Dict[str, str]

qcportal.FractalClient.query_kvstore(self, id: QueryObjectId, full_return: bool = False) → Dict[str, Any]

Queries items from the database’s KVStore

Parameters
  • id (QueryObjectId) – A list of KVStore id’s

  • full_return (bool, optional) – Returns the full server response if True that contains additional metadata.

Returns

A list of found KVStore objects in {“id”: “value”} format

Return type

Dict[str, Any]

qcportal.FractalClient.query_molecules(self, id: QueryObjectId = None, molecule_hash: QueryStr = None, molecular_formula: QueryStr = None, limit: Optional[int] = None, skip: int = 0, full_return: bool = False) → List[qcelemental.models.molecule.Molecule]

Queries molecules from the database.

Parameters
  • id (QueryObjectId, optional) – Queries the Molecule id field.

  • molecule_hash (QueryStr, optional) – Queries the Molecule molecule_hash field.

  • molecular_formula (QueryStr, optional) – Queries the Molecule molecular_formula field.

  • limit (Optional[int], optional) – The maximum number of Molecules to query

  • skip (int, optional) – The number of Molecules to skip in the query, used during pagination

  • full_return (bool, optional) – Returns the full server response if True that contains additional metadata.

Returns

A list of found molecules.

Return type

List[Molecule]

qcportal.FractalClient.add_molecules(self, mol_list: List[qcelemental.models.molecule.Molecule], full_return: bool = False) → List[str]

Adds molecules to the Server.

Parameters
  • mol_list (List[Molecule]) – A list of Molecules to add to the server.

  • full_return (bool, optional) – Returns the full server response if True that contains additional metadata.

Returns

A list of Molecule id’s in the sent order, can be None where issues occured.

Return type

List[str]

qcportal.FractalClient.query_keywords(self, id: QueryObjectId = None, *, hash_index: QueryStr = None, limit: Optional[int] = None, skip: int = 0, full_return: bool = False) → List[KeywordSet]

Obtains KeywordSets from the server using keyword ids.

Parameters
  • id (QueryObjectId, optional) – A list of ids to query.

  • hash_index (QueryStr, optional) – The hash index to look up

  • limit (Optional[int], optional) – The maximum number of keywords to query

  • skip (int, optional) – The number of keywords to skip in the query, used during pagination

  • full_return (bool, optional) – Returns the full server response if True that contains additional metadata.

Returns

The requested KeywordSet objects.

Return type

List[KeywordSet]

qcportal.FractalClient.add_keywords(self, keywords: List[KeywordSet], full_return: bool = False) → List[str]

Adds KeywordSets to the server.

Parameters
  • keywords (List[KeywordSet]) – A list of KeywordSets to add.

  • full_return (bool, optional) – Returns the full server response if True that contains additional metadata.

Returns

A list of KeywordSet id’s in the sent order, can be None where issues occured.

Return type

List[str]

qcportal.FractalClient.list_collections(self, collection_type: Optional[str] = None, aslist: bool = False) → DataFrame

Lists the available collections currently on the server.

Parameters
  • collection_type (Optional[str], optional) – If None all collection types will be returned, otherwise only the specified collection type will be returned

  • aslist (bool, optional) – Returns a canonical list rather than a dataframe.

Returns

A dataframe containing the collection, name, and tagline.

Return type

DataFrame

qcportal.FractalClient.get_collection(self, collection_type: str, name: str, full_return: bool = False) → Collection

Acquires a given collection from the server.

Parameters
  • collection_type (str) – The collection type to be accessed

  • name (str) – The name of the collection to be accessed

  • full_return (bool, optional) – Returns the full server response if True that contains additional metadata.

Returns

A Collection object if the given collection was found otherwise returns None.

Return type

Collection

qcportal.FractalClient.add_collection(self, collection: Dict[str, Any], overwrite: bool = False, full_return: bool = False) → List[qcfractal.interface.models.common_models.ObjectId]

Adds a new Collection to the server.

Parameters
  • collection (Dict[str, Any]) – The full collection data representation.

  • overwrite (bool, optional) – Overwrites the collection if it already exists in the database, used for updating collection.

  • full_return (bool, optional) – Returns the full server response if True that contains additional metadata.

Returns

The ObjectId’s of the added collection.

Return type

List[ObjectId]

qcportal.FractalClient.query_results(self, id: QueryObjectId = None, task_id: QueryObjectId = None, program: QueryStr = None, molecule: QueryObjectId = None, driver: QueryStr = None, method: QueryStr = None, basis: QueryStr = None, keywords: QueryObjectId = None, status: QueryStr = 'COMPLETE', limit: Optional[int] = None, skip: int = 0, projection: QueryProjection = None, full_return: bool = False) → Union[List[RecordResult], Dict[str, Any]]

Queries ResultRecords from the server.

Parameters
  • id (QueryObjectId, optional) – Queries the Result id field.

  • task_id (QueryObjectId, optional) – Queries the Result task_id field.

  • program (QueryStr, optional) – Queries the Result program field.

  • molecule (QueryObjectId, optional) – Queries the Result molecule field.

  • driver (QueryStr, optional) – Queries the Result driver field.

  • method (QueryStr, optional) – Queries the Result method field.

  • basis (QueryStr, optional) – Queries the Result basis field.

  • keywords (QueryObjectId, optional) – Queries the Result keywords field.

  • status (QueryStr, optional) – Queries the Result status field.

  • limit (Optional[int], optional) – The maximum number of Results to query

  • skip (int, optional) – The number of Results to skip in the query, used during pagination

  • projection (QueryProjection, optional) – Filters the returned fields, will return a dictionary rather than an object.

  • full_return (bool, optional) – Returns the full server response if True that contains additional metadata.

Returns

Returns a List of found RecordResult’s without projection, or a dictionary of results with projection.

Return type

Union[List[RecordResult], Dict[str, Any]]

qcportal.FractalClient.query_procedures(self, id: QueryObjectId = None, task_id: QueryObjectId = None, procedure: QueryStr = None, program: QueryStr = None, hash_index: QueryStr = None, status: QueryStr = 'COMPLETE', limit: Optional[int] = None, skip: int = 0, projection: QueryProjection = None, full_return: bool = False) → Union[List[RecordBase], Dict[str, Any]]

Queries Procedures from the server.

Parameters
  • id (QueryObjectId, optional) – Queries the Procedure id field.

  • task_id (QueryObjectId, optional) – Queries the Procedure task_id field.

  • procedure (QueryStr, optional) – Queries the Procedure procedure field.

  • program (QueryStr, optional) – Queries the Procedure program field.

  • hash_index (QueryStr, optional) – Queries the Procedure hash_index field.

  • status (QueryStr, optional) – Queries the Procedure status field.

  • limit (Optional[int], optional) – The maximum number of Procedures to query

  • skip (int, optional) – The number of Procedures to skip in the query, used during pagination

  • projection (QueryProjection, optional) – Filters the returned fields, will return a dictionary rather than an object.

  • full_return (bool, optional) – Returns the full server response if True that contains additional metadata.

Returns

Returns a List of found RecordResult’s without projection, or a dictionary of results with projection.

Return type

Union[List[‘RecordBase’], Dict[str, Any]]

qcportal.FractalClient.add_compute(self, program: str, method: str, basis: str, driver: str, keywords: Optional[qcfractal.interface.models.common_models.ObjectId], molecule: Union[qcfractal.interface.models.common_models.ObjectId, qcelemental.models.molecule.Molecule, List[Union[str, qcelemental.models.molecule.Molecule]]], priority: str = None, tag: str = None, full_return: bool = False) → qcfractal.interface.models.rest_models.ComputeResponse

Adds a “single” compute to the server.

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

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

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

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

  • keywords (Union[str, None]) – The KeywordSet ObjectId to use with the given compute

  • molecule (Union[str, Molecule, List[Union[str, Molecule]]]) – The Molecules or Molecule ObjectId’s to compute with the above methods

  • priority (str, optional) – The priority of the job {“HIGH”, “MEDIUM”, “LOW”}. Default is “MEDIUM”.

  • tag (str, optional) – The computational tag to add to your compute, managers can optionally only pull based off the string tags. These tags are arbitrary, but several examples are to use “large”, “medium”, “small” to denote the size of the job or “project1”, “project2” to denote different projects.

  • full_return (bool, optional) – Returns the full server response if True that contains additional metadata.

Returns

An object that contains the submitted ObjectIds of the new compute. This object has the following fields:
  • ids: The ObjectId’s of the task in the order of input molecules

  • submitted: A list of ObjectId’s that were submitted to the compute queue

  • existing: A list of ObjectId’s of tasks already in the database

Return type

ComputeResponse

qcportal.FractalClient.add_procedure(self, procedure: str, program: str, program_options: Dict[str, Any], molecule: Union[qcfractal.interface.models.common_models.ObjectId, qcelemental.models.molecule.Molecule, List[Union[str, qcelemental.models.molecule.Molecule]]], priority: str = None, tag: str = None, full_return: bool = False) → qcfractal.interface.models.rest_models.ComputeResponse

Adds a “single” Procedure to the server.

Parameters
  • procedure (str) – The computational procedure to spawn {“optimization”}

  • program (str) – The program to use for the given procedure (e.g., “geomeTRIC”)

  • program_options (Dict[str, Any]) – Additional options and specifications for the given procedure.

  • molecule (Union[ObjectId, Molecule, List[Union[str, Molecule]]]) – The Molecules or Molecule ObjectId’s to use with the above procedure

  • priority (str, optional) – The priority of the job {“HIGH”, “MEDIUM”, “LOW”}. Default is “MEDIUM”.

  • tag (str, optional) – The computational tag to add to your procedure, managers can optionally only pull based off the string tags. These tags are arbitrary, but several examples are to use “large”, “medium”, “small” to denote the size of the job or “project1”, “project2” to denote different projects.

  • full_return (bool, optional) – Returns the full server response if True that contains additional metadata.

Returns

An object that contains the submitted ObjectIds of the new procedure. This object has the following fields:
  • ids: The ObjectId’s of the task in the order of input molecules

  • submitted: A list of ObjectId’s that were submitted to the compute queue

  • existing: A list of ObjectId’s of tasks already in the database

Return type

ComputeResponse

qcportal.FractalClient.query_tasks(self, id: QueryObjectId = None, hash_index: QueryStr = None, program: QueryStr = None, status: QueryStr = None, base_result: QueryStr = None, limit: Optional[int] = None, skip: int = 0, projection: QueryProjection = None, full_return: bool = False) → List[Dict[str, Any]]

Checks the status of Tasks in the Fractal queue.

Parameters
  • id (QueryObjectId, optional) – Queries the Tasks id field.

  • hash_index (QueryStr, optional) – Queries the Tasks hash_index field.

  • program (QueryStr, optional) – Queries the Tasks program field.

  • status (QueryStr, optional) – Queries the Tasks status field.

  • base_result (QueryStr, optional) – Queries the Tasks base_result field.

  • limit (Optional[int], optional) – The maximum number of Tasks to query

  • skip (int, optional) – The number of Tasks to skip in the query, used during pagination

  • projection (QueryProjection, optional) – Filters the returned fields, will return a dictionary rather than an object.

  • full_return (bool, optional) – Returns the full server response if True that contains additional metadata.

Returns

A dictionary of each match that contains the current status and, if an error has occured, the error message.

Return type

List[Dict[str, Any]]

Examples

>>> client.query_tasks(id="5bd35af47b878715165f8225", projection={"status": True})
[{"status": "WAITING"}]
qcportal.FractalClient.add_service(self, service: Union[qcfractal.interface.models.gridoptimization.GridOptimizationInput, qcfractal.interface.models.torsiondrive.TorsionDriveInput], tag: Optional[str] = None, priority: Optional[str] = None, full_return: bool = False) → qcfractal.interface.models.rest_models.ComputeResponse

Adds a new service to the service queue.

Parameters
  • service (Union[GridOptimizationInput, TorsionDriveInput]) – An available service input

  • tag (Optional[str], optional) – The compute tag to add the service under.

  • priority (Optional[str], optional) – The priority of the job within the compute queue.

  • full_return (bool, optional) – Returns the full server response if True that contains additional metadata.

Returns

An object that contains the submitted ObjectIds of the new service. This object has the following fields:
  • ids: The ObjectId’s of the task in the order of input molecules

  • submitted: A list of ObjectId’s that were submitted to the compute queue

  • existing: A list of ObjectId’s of tasks already in the database

Return type

ComputeResponse

qcportal.FractalClient.query_services(self, id: QueryObjectId = None, procedure_id: QueryObjectId = None, hash_index: QueryStr = None, status: QueryStr = None, limit: Optional[int] = None, skip: int = 0, full_return: bool = False) → List[Dict[str, Any]]

Checks the status of services in the Fractal queue.

Parameters
  • id (QueryObjectId, optional) – Queries the Services id field.

  • procedure_id (QueryObjectId, optional) – Queries the Services procedure_id field, or the ObjectId of the procedure associated with the service.

  • hash_index (QueryStr, optional) – Queries the Services procedure_id field.

  • status (QueryStr, optional) – Queries the Services status field.

  • limit (Optional[int], optional) – The maximum number of Services to query

  • skip (int, optional) – The number of Services to skip in the query, used during pagination

  • full_return (bool, optional) – Returns the full server response if True that contains additional metadata.

Returns

A dictionary of each match that contains the current status and, if an error has occurred, the error message.

Return type

List[Dict[str, Any]]

Examples

>>> client.query_services(id="5bd35af47b878715165f8225", projection={"status": True})
[{"status": "RUNNING"}]