`BasicDataset`

class openff.qcsubmit.datasets.BasicDataset(*, qc_specifications: ~typing.Dict[str, ~openff.qcsubmit.common_structures.QCSpec] = {'default': QCSpec(method='B3LYP-D3BJ', basis='DZVP', program='psi4', spec_name='default', spec_description='Standard OpenFF optimization quantum chemistry specification.', store_wavefunction=<WavefunctionProtocolEnum.none: 'none'>, implicit_solvent=None, maxiter=200, scf_properties=[<SCFProperties.Dipole: 'dipole'>, <SCFProperties.Quadrupole: 'quadrupole'>, <SCFProperties.WibergLowdinIndices: 'wiberg_lowdin_indices'>, <SCFProperties.MayerIndices: 'mayer_indices'>], keywords={})}, driver: ~qcportal.singlepoint.record_models.SinglepointDriver = SinglepointDriver.energy, priority: str = 'normal', dataset_tags: ~typing.List[str] = ['openff'], compute_tag: str = 'openff', dataset_name: str, dataset_tagline: ~pydantic.v1.types.ConstrainedStrValue, type: ~typing.Literal['DataSet'] = 'DataSet', description: ~pydantic.v1.types.ConstrainedStrValue, metadata: ~openff.qcsubmit.common_structures.Metadata = Metadata(submitter='runner', creation_date=datetime.date(2026, 7, 24), collection_type=None, dataset_name=None, short_description=None, long_description_url=None, long_description=None, elements=set()), provenance: ~typing.Dict[str, str] = {}, dataset: ~typing.Dict[str, ~openff.qcsubmit.datasets.entries.DatasetEntry] = {}, filtered_molecules: ~typing.Dict[str, ~openff.qcsubmit.datasets.entries.FilterEntry] = {})[source]

The general QCFractal dataset class which contains all of the molecules and information about them prior to submission.

The class is a simple holder of the dataset and information about it and can do simple checks on the data before submitting it such as ensuring that the molecules have cmiles information and a unique index to be identified by.

Note:: The molecules in this dataset are all expanded so that different conformers are unique submissions.

Attributes

`components`	Gather the details of the components that were ran during the creation of this dataset.
`filtered`	A generator which yields a openff molecule representation for each molecule filtered while creating this dataset.
`molecules`	A generator that creates an openforcefield.topology.Molecule one by one from the dataset.
`n_components`	Return the amount of components that have been ran during generating the dataset.
`n_filtered`	Calculate the total number of molecules filtered by the components used in a workflow to create this dataset.
`n_molecules`	Calculate the number of unique molecules to be submitted.
`n_qc_specs`	Return the number of QCSpecs on this dataset.
`n_records`	Return the total number of records that will be created on submission of the dataset.
`type`
`dataset_name`
`dataset_tagline`
`description`
`metadata`
`provenance`
`dataset`
`filtered_molecules`
`driver`
`priority`
`dataset_tags`
`compute_tag`
`qc_specifications`

Methods

`__init__`(**kwargs)	Make sure the metadata has been assigned correctly if not autofill some information.
`add_molecule`(index, molecule[, extras, keywords])	Add a molecule to the dataset under the given index with the passed cmiles.
`add_qc_spec`(method, basis, program, ...[, ...])	Add a new qcspecification to the factory which will be applied to the dataset.
`clear_qcspecs`()	Clear out any current QCSpecs.
`construct`([_fields_set])	Creates a new model setting __dict__ and __fields_set__ from trusted or pre-validated data.
`copy`(*[, include, exclude, update, deep])	Duplicate a model, optionally choose which fields to include, exclude and change.
`coverage_report`(force_field[, verbose])	Returns a summary of how many molecules within this dataset would be assigned each of the parameters in a force field.
`dict`(args, *kwargs)	Overwrite the dict method to handle any enums when saving to yaml/json via a dict call.
`export_dataset`(file_name[, compression])	Export the dataset to file so that it can be used to make another dataset quickly.
`filter_molecules`(molecules, component, ...)	Filter a molecule or list of molecules by the component they failed.
`from_orm`(obj)
`get_molecule_entry`(molecule)	Search through the dataset for a molecule and return the dataset index of any exact molecule matches.
`json`(*[, include, exclude, by_alias, ...])	Generate a JSON representation of the model, include and exclude arguments as per dict().
`molecules_to_file`(file_name, file_type)	Write the molecules to the requested file type.
`parse_file`(file_name)	Create a Dataset object from a compressed json file.
`parse_obj`(obj)
`parse_raw`(b, *[, content_type, encoding, ...])
`remove_qcspec`(spec_name)	Remove a QCSpec from the dataset.
`schema`([by_alias, ref_template])
`schema_json`(*[, by_alias, ref_template])
`submit`(client[, ignore_errors, verbose])	Submit the dataset to a QCFractal server.
`to_tasks`()	Build a dictionary of single QCEngine tasks that correspond to this dataset organised by program name.
`update_forward_refs`(**localns)	Try to update ForwardRefs on fields based on this Model, globalns and localns.
`validate`(value)
`visualize`(file_name[, columns, toolkit])	Create a pdf file of the molecules with any torsions highlighted using either openeye or rdkit.

__init__(**kwargs): Make sure the metadata has been assigned correctly if not autofill some information.

add_molecule(index: str, molecule: Molecule | None, extras: Dict[str, Any] | None = None, keywords: Dict[str, Any] | None = None, **kwargs) → None

Add a molecule to the dataset under the given index with the passed cmiles.

Args:

index:: The index that should be associated with the molecule in QCArchive.
molecule:: The instance of the molecule which contains its conformer information.
extras:: The extras that should be supplied into the qcportal.moldels.Molecule.
keywords:: Any extra keywords which are required for the calculation.

Note:

Each molecule in this basic dataset should have all of its conformers expanded out into separate entries. Thus here we take the general molecule index and increment it.

Add a new qcspecification to the factory which will be applied to the dataset.

Parameters:: method: The name of the method to use eg B3LYP-D3BJ basis: The name of the basis to use can also be None program: The name of the program to execute the computation spec_name: The name the spec should be stored under spec_description: The description of the spec store_wavefunction: what parts of the wavefunction that should be saved overwrite: If there is a spec under this name already overwrite it implicit_solvent: The implicit solvent settings if it is to be used. maxiter: The maximum number of SCF iterations that should be done. scf_properties: The list of SCF properties that should be extracted from the calculation. keywords: Program specific computational keywords that should be passed to

the program

clear_qcspecs() → None: Clear out any current QCSpecs.

classmethod construct(_fields_set: SetStr | None = None, **values: Any) → Model: Creates a new model setting __dict__ and __fields_set__ from trusted or pre-validated data. Default values are respected, but no other validation is performed. Behaves as if Config.extra = ‘allow’ was set since it adds all passed values

Duplicate a model, optionally choose which fields to include, exclude and change.

Parameters:

include – fields to include in new model
exclude – fields to exclude from new model, as with values this takes precedence over include
update – values to change/add in the new model. Note: the data is not validated before creating the new model: you should trust this data
deep – set to True to make a deep copy of the model

Returns:

new model instance

coverage_report(force_field: ForceField, verbose: bool = False) → Dict[str, Dict[str, int]]

Returns a summary of how many molecules within this dataset would be assigned each of the parameters in a force field.

Notes:

Parameters which would not be assigned to any molecules in the dataset will not be included in the returned summary.

Args:

force_field: The force field containing the parameters to summarize. verbose: If true a progress bar will be shown on screen.

Returns:

A dictionary of the form coverage[handler_name][parameter_smirks] = count which stores the number of molecules within this dataset that would be assigned to each parameter.

dict(*args, **kwargs): Overwrite the dict method to handle any enums when saving to yaml/json via a dict call.

export_dataset(file_name: str, compression: str | None = None) → None

Export the dataset to file so that it can be used to make another dataset quickly.

Args:

file_name:: The name of the file the dataset should be wrote to.
compression:: The type of compression that should be added to the export.

Raises:

UnsupportedFiletypeError: If the requested file type is not supported.

Note:

The supported file types are:

json

Additionally, the file will automatically compressed depending on the final extension if compression is not explicitly supplied:

json.xz
json.gz
json.bz2

Check serializers.py for more details. Right now bz2 seems to produce the smallest files.

filter_molecules(molecules: Molecule | List[Molecule], component: str, component_settings: Dict[str, Any], component_provenance: Dict[str, str]) → None

Filter a molecule or list of molecules by the component they failed.

Args:

molecules:: A molecule or list of molecules to be filtered.
component_settings:: The dictionary representation of the component that filtered this set of molecules.
component:: The name of the component.
component_provenance:: The dictionary representation of the component provenance.

classmethod from_orm(obj: Any) → Model

get_molecule_entry(molecule: Molecule | str) → List[str]

Search through the dataset for a molecule and return the dataset index of any exact molecule matches.

Args:: molecule: The smiles string for the molecule or an openforcefield.topology.Molecule that is to be searched for.
Returns:: A list of dataset indices which contain the target molecule.

json(*, include: AbstractSetIntStr | MappingIntStrAny | None = None, exclude: AbstractSetIntStr | MappingIntStrAny | None = None, by_alias: bool = False, skip_defaults: bool | None = None, exclude_unset: bool = False, exclude_defaults: bool = False, exclude_none: bool = False, encoder: Callable[[Any], Any] | None = None, models_as_dict: bool = True, **dumps_kwargs: Any) → str

Generate a JSON representation of the model, include and exclude arguments as per dict().

encoder is an optional function to supply as default to json.dumps(), other arguments as per json.dumps().

molecules_to_file(file_name: str, file_type: str) → None

Write the molecules to the requested file type.

Args:

file_name:: The name of the file the molecules should be stored in.
file_type:: The file format that should be used to store the molecules.

Important:

The supported file types are:

SMI
INCHI
INCKIKEY

classmethod parse_file(file_name: str)

Create a Dataset object from a compressed json file.

Args:: file_name: The name of the file the dataset should be created from.

classmethod parse_obj(obj: Any) → Model

classmethod parse_raw(b: str | bytes, *, content_type: str = None, encoding: str = 'utf8', proto: Protocol = None, allow_pickle: bool = False) → Model

remove_qcspec(spec_name: str) → None

Remove a QCSpec from the dataset.

Parameters:: spec_name: The name of the spec that should be removed.
Note:: The QCSpec settings are not mutable and so they must be removed and a new one added to ensure they are fully validated.

classmethod schema(by_alias: bool = True, ref_template: str = default_ref_template) → DictStrAny

classmethod schema_json(*, by_alias: bool = True, ref_template: str = default_ref_template, **dumps_kwargs: Any) → str

submit(client: PortalClient, ignore_errors: bool = False, verbose: bool = False) → Dict

Submit the dataset to a QCFractal server.

Args:

client:: Instance of a portal client
ignore_errors:: If the user wants to submit the compute regardless of errors set this to True. Mainly to override basis coverage.
verbose:: If progress bars and submission statistics should be printed True or not False.

Returns:

A dictionary of the compute response from the client for each specification submitted.

Raises:

MissingBasisCoverageError:: If the chosen basis set does not cover some of the elements in the dataset.

to_tasks() → Dict[str, List[AtomicInput]][source]: Build a dictionary of single QCEngine tasks that correspond to this dataset organised by program name. The tasks can be passed directly to qcengine.compute.

classmethod update_forward_refs(**localns: Any) → None: Try to update ForwardRefs on fields based on this Model, globalns and localns.

classmethod validate(value: Any) → Model

visualize(file_name: str, columns: int = 4, toolkit: Literal['openeye', 'rdkit'] | None = None) → None

Create a pdf file of the molecules with any torsions highlighted using either openeye or rdkit.

Args:

file_name:: The name of the pdf file which will be produced.
columns:: The number of molecules per row.
toolkit:: The option to specify the backend toolkit used to produce the pdf file.

to_tasks() → Dict[str, List[AtomicInput]][source]: Build a dictionary of single QCEngine tasks that correspond to this dataset organised by program name. The tasks can be passed directly to qcengine.compute.

add_molecule(index: str, molecule: Molecule | None, extras: Dict[str, Any] | None = None, keywords: Dict[str, Any] | None = None, **kwargs) → None

Add a molecule to the dataset under the given index with the passed cmiles.

Args:

index:: The index that should be associated with the molecule in QCArchive.
molecule:: The instance of the molecule which contains its conformer information.
extras:: The extras that should be supplied into the qcportal.moldels.Molecule.
keywords:: Any extra keywords which are required for the calculation.

Note:

Each molecule in this basic dataset should have all of its conformers expanded out into separate entries. Thus here we take the general molecule index and increment it.

Add a new qcspecification to the factory which will be applied to the dataset.

Parameters:: method: The name of the method to use eg B3LYP-D3BJ basis: The name of the basis to use can also be None program: The name of the program to execute the computation spec_name: The name the spec should be stored under spec_description: The description of the spec store_wavefunction: what parts of the wavefunction that should be saved overwrite: If there is a spec under this name already overwrite it implicit_solvent: The implicit solvent settings if it is to be used. maxiter: The maximum number of SCF iterations that should be done. scf_properties: The list of SCF properties that should be extracted from the calculation. keywords: Program specific computational keywords that should be passed to

the program

clear_qcspecs() → None: Clear out any current QCSpecs.

property components: List[Dict[str, str | Dict[str, str]]]: Gather the details of the components that were ran during the creation of this dataset.

classmethod construct(_fields_set: SetStr | None = None, **values: Any) → Model: Creates a new model setting __dict__ and __fields_set__ from trusted or pre-validated data. Default values are respected, but no other validation is performed. Behaves as if Config.extra = ‘allow’ was set since it adds all passed values

Duplicate a model, optionally choose which fields to include, exclude and change.

Parameters:

include – fields to include in new model
exclude – fields to exclude from new model, as with values this takes precedence over include
update – values to change/add in the new model. Note: the data is not validated before creating the new model: you should trust this data
deep – set to True to make a deep copy of the model

Returns:

new model instance

coverage_report(force_field: ForceField, verbose: bool = False) → Dict[str, Dict[str, int]]

Returns a summary of how many molecules within this dataset would be assigned each of the parameters in a force field.

Notes:

Parameters which would not be assigned to any molecules in the dataset will not be included in the returned summary.

Args:

force_field: The force field containing the parameters to summarize. verbose: If true a progress bar will be shown on screen.

Returns:

A dictionary of the form coverage[handler_name][parameter_smirks] = count which stores the number of molecules within this dataset that would be assigned to each parameter.

dict(*args, **kwargs): Overwrite the dict method to handle any enums when saving to yaml/json via a dict call.

export_dataset(file_name: str, compression: str | None = None) → None

Export the dataset to file so that it can be used to make another dataset quickly.

Args:

file_name:: The name of the file the dataset should be wrote to.
compression:: The type of compression that should be added to the export.

Raises:

UnsupportedFiletypeError: If the requested file type is not supported.

Note:

The supported file types are:

json

Additionally, the file will automatically compressed depending on the final extension if compression is not explicitly supplied:

json.xz
json.gz
json.bz2

Check serializers.py for more details. Right now bz2 seems to produce the smallest files.

filter_molecules(molecules: Molecule | List[Molecule], component: str, component_settings: Dict[str, Any], component_provenance: Dict[str, str]) → None

Filter a molecule or list of molecules by the component they failed.

Args:

molecules:: A molecule or list of molecules to be filtered.
component_settings:: The dictionary representation of the component that filtered this set of molecules.
component:: The name of the component.
component_provenance:: The dictionary representation of the component provenance.

property filtered: Molecule

A generator which yields a openff molecule representation for each molecule filtered while creating this dataset.

Note:: Modifying the molecule will have no effect on the data stored.

get_molecule_entry(molecule: Molecule | str) → List[str]

Search through the dataset for a molecule and return the dataset index of any exact molecule matches.

Args:: molecule: The smiles string for the molecule or an openforcefield.topology.Molecule that is to be searched for.
Returns:: A list of dataset indices which contain the target molecule.

Generate a JSON representation of the model, include and exclude arguments as per dict().

encoder is an optional function to supply as default to json.dumps(), other arguments as per json.dumps().

property molecules: Generator[Molecule, None, None]

A generator that creates an openforcefield.topology.Molecule one by one from the dataset.

Note:: Editing the molecule will not effect the data stored in the dataset as it is immutable.

molecules_to_file(file_name: str, file_type: str) → None

Write the molecules to the requested file type.

Args:

file_name:: The name of the file the molecules should be stored in.
file_type:: The file format that should be used to store the molecules.

Important:

The supported file types are:

SMI
INCHI
INCKIKEY

property n_components: int: Return the amount of components that have been ran during generating the dataset.

property n_filtered: int: Calculate the total number of molecules filtered by the components used in a workflow to create this dataset.

property n_molecules: int

Calculate the number of unique molecules to be submitted.

Notes:

This method has been improved for better performance on large datasets and has been tested on an optimization dataset of over 10500 molecules.
This function does not calculate the total number of entries of the dataset see n_records

property n_qc_specs: int: Return the number of QCSpecs on this dataset.

property n_records: int

Return the total number of records that will be created on submission of the dataset.

Note:

The number returned will be different depending on the dataset used.
The amount of unique molecule can be found using n_molecules

classmethod parse_file(file_name: str)

Create a Dataset object from a compressed json file.

Args:: file_name: The name of the file the dataset should be created from.

remove_qcspec(spec_name: str) → None

Remove a QCSpec from the dataset.

Parameters:: spec_name: The name of the spec that should be removed.
Note:: The QCSpec settings are not mutable and so they must be removed and a new one added to ensure they are fully validated.

submit(client: PortalClient, ignore_errors: bool = False, verbose: bool = False) → Dict

Submit the dataset to a QCFractal server.

Args:

client:: Instance of a portal client
ignore_errors:: If the user wants to submit the compute regardless of errors set this to True. Mainly to override basis coverage.
verbose:: If progress bars and submission statistics should be printed True or not False.

Returns:

A dictionary of the compute response from the client for each specification submitted.

Raises:

MissingBasisCoverageError:: If the chosen basis set does not cover some of the elements in the dataset.

classmethod update_forward_refs(**localns: Any) → None: Try to update ForwardRefs on fields based on this Model, globalns and localns.

visualize(file_name: str, columns: int = 4, toolkit: Literal['openeye', 'rdkit'] | None = None) → None

Create a pdf file of the molecules with any torsions highlighted using either openeye or rdkit.

Args:

file_name:: The name of the pdf file which will be produced.
columns:: The number of molecules per row.
toolkit:: The option to specify the backend toolkit used to produce the pdf file.