Structure & Identifiers¶
A Structure is the core qcdata 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 xyz files, or opened from Structure objects previously saved to disk. with_geometry(positions) returns a validated copy at new positions, the way to make an input at a new geometry.
qcdata.Structure
¶
A molecular structure: atoms, Cartesian coordinates, charge, and multiplicity.
Optionally carries identifiers such as name and SMILES and explicit bond connectivity.
Attributes:
| Name | Type | Description |
|---|---|---|
symbols |
list[str]
|
The atomic symbols of the structure. |
geometry |
SerializableMatrix
|
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
|
|
from_xyz
classmethod
¶
from_xyz(
xyz_str: str,
*,
charge: int | None = None,
multiplicity: int | None = None,
) -> Self
Create a Structure from an XYZ file or string.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
xyz_str
|
str
|
The XYZ string. |
required |
charge
|
int | None
|
The molecular charge of the structure. If not provided, will read from the XYZ string if set or default to 0. |
None
|
multiplicity
|
int | None
|
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 qcdata data such as charge and multiplicity from the comments
line with a qcdata_key=value format (if it is present). Also will read in
qcdata__identifiers_* keys and additional non-qcdata comments.
Example
struct = Structure.from_xyz(xyz_str)
Source code in src/qcdata/models/structure.py
271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 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 | |
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 qcdata data such as charge and multiplicity to the comments line with
a qcdata_key=value format.
Source code in src/qcdata/models/structure.py
439 440 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 | |
with_geometry
¶
with_geometry(geometry: Any) -> Self
Return a validated copy at new positions.
The copy has the same atoms, charge, multiplicity, connectivity, identifiers and extras. It is the way to make an input at a new geometry:
moved = ProgramInput.from_spec(inp, inp.structure.with_geometry(positions))
ProgramInput.from_spec keeps the specification (program, model, keywords,
subprograms, files) and leaves out given, whose results belong to the old
geometry; pass structures=inp.structures to keep the other roles.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
geometry
|
Any
|
The new positions in bohr, n_atoms x 3 (or flat). |
required |
Returns:
| Type | Description |
|---|---|
Self
|
The structure at the new positions. |
Raises:
| Type | Description |
|---|---|
ValidationError
|
The positions do not fit the atoms. |
Source code in src/qcdata/models/structure.py
389 390 391 392 393 394 395 396 397 398 399 400 401 402 403 404 405 406 407 408 409 410 411 412 413 414 | |
distance
¶
distance(i: int, j: int, units: LengthUnit = 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
|
LengthUnit
|
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 src/qcdata/models/structure.py
416 417 418 419 420 421 422 423 424 425 426 427 428 429 430 431 432 433 434 435 436 437 | |
add_identifiers
¶
add_identifiers(**identifiers: str | None) -> None
Add an identifier to the structure.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
identifiers
|
str | None
|
The identifiers to add to the structure. |
{}
|
Example
struct.add_identifiers(name="water")
struct.ids.name
'water'
struct.add_identifier(smiles="CCO")
struct.ids.smiles
'CCO'
Source code in src/qcdata/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 | |
qcdata.Identifiers
¶
Structure identifiers.
Attributes:
| Name | Type | Description |
|---|---|---|
name |
str | None
|
A human-readable, common name for the structure. |
name_IUPAC |
str | None
|
The IUPAC name of the structure. |
smiles |
str | None
|
The SMILES representation of the structure. |
canonical_smiles |
str | None
|
The canonical SMILES representation of the structure. |
canonical_smiles_program |
str | None
|
The program used to generate the canonical SMILES. |
canonical_explicit_hydrogen_smiles |
str | None
|
The canonical explicit hydrogen SMILES representation of the structure. |
canonical_isomeric_smiles |
str | None
|
The canonical isomeric SMILES representation of the structure. |
canonical_isomeric_explicit_hydrogen_smiles |
str | None
|
The canonical isomeric explicit hydrogen SMILES representation of the structure. |
canonical_isomeric_explicit_hydrogen_mapped_smiles |
str | None
|
The canonical isomeric explicit hydrogen mapped SMILES representation of the structure. |
inchi |
str | None
|
The InChI representation of the structure. |
inchikey |
str | None
|
The InChIKey representation of the structure. |
pubchem_cid |
str | None
|
The PubChem Compound ID of the structure. |
pubchem_sid |
str | None
|
The PubChem Substance ID of the structure. |
pubchem_conformerid |
str | None
|
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. |
Use identifiers= to set identifiers and .ids as a read-only shortcut. The former ids= constructor argument, Molecule alias, and deprecated SMILES helper have been removed. Use qcinf for SMILES conversion.