Structure & Identifiers¶
A Structure
is the core qcio
object for representing a molecule or molecular super structure in 3D space. Structure
objects can be created directly from symbol
and geometry
information (geometry must be in Bohr
), from SMILES strings, from xyz
files, or opened from Structure
objects previously saved to disk.
qcio.Structure
¶
Structure(**data: Any)
A Structure object with atoms and their corresponding cartesian coordinates, charge, multiplicity, and identifiers such as name, smiles, etc.
Attributes:
Name | Type | Description |
---|---|---|
symbols |
List[str]
|
The atomic symbols of the structure. |
geometry |
SerializableNDArray
|
The geometry of the structure in Cartesian coordinates. Units are Bohr (AU). |
identifiers |
Identifiers
|
Identifiers for the structure such as name, smiles, etc. |
charge |
int
|
The molecular charge. |
multiplicity |
int
|
The molecular multiplicity. |
connectivity |
List[Tuple[int, int, float]]
|
Explicit description of the bonds between atoms. Each tuple
contains the indices of the atoms in the bond and the order of the bond.
E.g., |
extras |
Dict[str, Any]
|
Additional information to bundle with the object. Use for schema development and scratch space. |
ids |
Identifiers
|
|
geometry_angstrom |
ndarray
|
|
atomic_numbers |
List[int]
|
|
formula |
str
|
|
Example
from qcio import Structure
structure = Structure(
symbols=["H", "O", "H"],
geometry=[[0.0, 0.0, 0.0], [0.0, 0.0, 1.0], [0.0, 0.0, 2.0]],
charge=0, # optional; defaults to 0
multiplicity=1, # optional; defaults to 1
identifiers={"smiles": "CCO"}, # optional
)
Source code in qcio/models/structure.py
127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 |
|
from_smiles
classmethod
¶
from_smiles(
smiles: str,
*,
program: str = "rdkit",
force_field: str = "MMFF94s",
multiplicity: int = 1
) -> Self
Create a new Structure object from a SMILES string.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
smiles |
str
|
The SMILES string. |
required |
program |
str
|
The program to use for the conversion. Defaults to "rdkit". |
'rdkit'
|
force_field |
str
|
The force field to use. E.g., UFF, MMFF94, MMFF94s, etc. |
'MMFF94s'
|
multiplicity |
int
|
The multiplicity of the structure. |
1
|
Returns:
Type | Description |
---|---|
Self
|
A Structure object with identifiers for SMILES and canonical SMILES. |
Example
struct = Structure.from_smiles("CN1C=NC2=C1C(=O)N(C(=O)N2C)C")
print(struct.ids.smiles)
# Output: 'CN1C=NC2=C1C(=O)N(C(=O)N2C)C'
print(struct.ids.canonical_smiles)
# Output: 'CN1C=NC2=C1C(=O)N(C(=O)N2C)C'
Source code in qcio/models/structure.py
253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 |
|
from_xyz
classmethod
¶
from_xyz(
xyz_str: str,
*,
charge: Optional[int] = None,
multiplicity: Optional[int] = None
) -> Self
Create a Structure from an XYZ file or string.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
xyz_str |
str
|
The XYZ string. |
required |
charge |
Optional[int]
|
The molecular charge of the structure. If not provided, will read from the XYZ string if set or default to 0. |
None
|
multiplicity |
Optional[int]
|
The molecular multiplicity of the structure. If not provided, will read from the XYZ string if set or default to 1. |
None
|
Note
Will read qcio data such as charge
and multiplicity
from the comments
line with a qcio_key=value
format (if it is present). Also will read in
qcio__identifiers_* keys and additional non-qcio comments.
Example
struct = Structure.from_xyz(xyz_str)
Source code in qcio/models/structure.py
288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 352 353 354 355 356 357 358 359 360 361 362 363 |
|
to_smiles
¶
to_smiles(
program: str = "rdkit", hydrogens: bool = False
) -> str
Generate the canonical SMILES representation of the structure.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
program |
str
|
The program to use for the conversion. Defaults to "rdkit". |
'rdkit'
|
hydrogens |
bool
|
Whether to include hydrogens in the SMILES string. Defaults to False. |
False
|
Returns:
Type | Description |
---|---|
str
|
The canonical SMILES representation of the structure. |
Example
struct.to_smiles()
'CN1C=NC2=C1C(=O)N(C(=O)N2C)C'
Source code in qcio/models/structure.py
422 423 424 425 426 427 428 429 430 431 432 433 434 435 436 437 438 439 |
|
to_xyz
¶
to_xyz(precision: int = 17) -> str
Return an xyz string representation of the structure.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
precision |
int
|
The number of decimal places to include in the xyz file. Default 17 which captures all precision of float64. |
17
|
Notes:
Will add qcio data such as charge and multiplicity to the comments line with
a qcio_key=value
format.
Source code in qcio/models/structure.py
441 442 443 444 445 446 447 448 449 450 451 452 453 454 455 456 457 458 459 460 461 462 463 464 465 466 467 468 469 470 471 472 473 474 475 476 477 478 479 480 |
|
distance
¶
distance(
i: int,
j: int,
units: DistanceUnits = DistanceUnits.bohr,
) -> float
Calculate the distance between two atoms.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
i |
int
|
The index of the first atom. |
required |
j |
int
|
The index of the second atom. |
required |
units |
DistanceUnits
|
The units to return the distance in. Defaults to "bohr". May be "bohr" or "angstrom". |
bohr
|
Returns:
Type | Description |
---|---|
float
|
The distance between the atoms in units (Bohr or Angstrom). |
Example
struct.distance(0, 1)
1.34
Source code in qcio/models/structure.py
397 398 399 400 401 402 403 404 405 406 407 408 409 410 411 412 413 414 415 416 417 418 419 420 |
|
add_smiles
¶
add_smiles(
*, program: str = "rdkit", hydrogens: bool = False
) -> None
Add SMILES data to the identifiers. The SMILES will be generated from the structure using the specified program.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
program |
str
|
The program to use to generate the SMILES. Defaults to "rdkit". |
'rdkit'
|
hydrogens |
bool
|
Whether to include hydrogens in the SMILES string. Defaults to False. |
False
|
Example
struct.add_smiles()
struct.ids.smiles
'CCO'
struct.ids.canonical_smiles
'CCO'
Source code in qcio/models/structure.py
490 491 492 493 494 495 496 497 498 499 500 501 502 503 504 505 506 507 508 509 510 511 512 513 514 515 516 517 518 519 520 521 522 523 524 |
|
qcio.Identifiers
¶
Structure identifiers.
Attributes:
Name | Type | Description |
---|---|---|
name |
Optional[str]
|
A human-readable, common name for the structure. |
name_IUPAC |
Optional[str]
|
The IUPAC name of the structure. |
smiles |
Optional[str]
|
The SMILES representation of the structure. |
canonical_smiles |
Optional[str]
|
The canonical SMILES representation of the structure. |
canonical_smiles_program |
Optional[str]
|
The program used to generate the canonical SMILES. |
canonical_explicit_hydrogen_smiles |
Optional[str]
|
The canonical explicit hydrogen SMILES representation of the structure. |
canonical_isomeric_smiles |
Optional[str]
|
The canonical isomeric SMILES representation of the structure. |
canonical_isomeric_explicit_hydrogen_smiles |
Optional[str]
|
The canonical isomeric explicit hydrogen SMILES representation of the structure. |
canonical_isomeric_explicit_hydrogen_mapped_smiles |
Optional[str]
|
The canonical isomeric explicit hydrogen mapped SMILES representation of the structure. |
inchi |
Optional[str]
|
The InChI representation of the structure. |
inchikey |
Optional[str]
|
The InChIKey representation of the structure. |
pubchem_cid |
Optional[str]
|
The PubChem Compound ID of the structure. |
pubchem_sid |
Optional[str]
|
The PubChem Substance ID of the structure. |
pubchem_conformerid |
Optional[str]
|
The PubChem Conformer ID of the structure. |
extras |
Dict[str, Any]
|
Additional information to bundle with the object. Use for schema development and scratch space. |
qcio.DistanceUnits
¶
Distance units for the Structure.distance method.
Attributes:
Name | Type | Description |
---|---|---|
bohr |
str
|
The distance in Bohr. |
angstrom |
str
|
The distance in Angstrom. |