Avogadro::QtGui::RWMolecule#

class RWMolecule : public QObject#

The RWMolecule class is an editable molecule class that automatically populates an undo stack.

This class implements the molecule API and composes a QUndoStack (undoStack()). New undo commands are automatically generated and push each time a non-const method is called.

An interactive mode is supported that causes “noisy” commands, such as atom position changes, to be merged into a single command, saving memory keeping the stack usable during interactive editing of the molecule. Use setInteractive(bool) to toggle interactive mode.

Similarly, multiple sequences of commands can be compressed into a single named action using the QUndoStack’s macro capability. Call undoStack().beginMacro(tr(“User Description Of Change”)) to begin a macro, and undoStack().endMacro() when finished.

Unnamed Group

inline Index atomUniqueId(Index atomId) const#

Returns:: The unique id of the atom.

inline Index atomUniqueId(const AtomType &atom) const#

Returns:: The unique id of the atom.

Unnamed Group

bool removeAtom(Index atomId)#

Delete the specified atom from this molecule.

Note

This also removes all bonds connected to the atom.

Returns:: True on success, false otherwise.

inline bool removeAtom(const AtomType &atom)#

Delete the specified atom from this molecule.

Note

This also removes all bonds connected to the atom.

Returns:: True on success, false otherwise.

Unnamed Group

BondType addBond(Index atom1, Index atom2, unsigned char order = 1)#

Create a new bond in the molecule.

Parameters:

atom1 – The first atom in the bond.
atom2 – The second order in the bond.
order – The bond order.

Returns:

The new bond object. Will be invalid if atom1 or atom2 does not exist.

inline BondType addBond(const AtomType &atom1, const AtomType &atom2, unsigned char order = 1)#

Create a new bond in the molecule.

Parameters:

atom1 – The first atom in the bond.
atom2 – The second order in the bond.
order – The bond order.

Returns:

The new bond object. Will be invalid if atom1 or atom2 does not exist.

Unnamed Group

bool removeBond(Index bondId)#

Remove the requested bond.

Returns:: True on success, false otherwise.

inline bool removeBond(const BondType &bond)#

Remove the requested bond.

Returns:: True on success, false otherwise.

inline bool removeBond(Index atom1, Index atom2)#

Remove the requested bond.

Returns:: True on success, false otherwise.

inline bool removeBond(const AtomType &atom1, const AtomType &atom2)#

Remove the requested bond.

Returns:: True on success, false otherwise.

Unnamed Group

inline QUndoStack &undoStack()#

Returns:: The QUndoStack for this molecule.

inline const QUndoStack &undoStack() const#

Returns:: The QUndoStack for this molecule.

Public Types

typedef RWAtom AtomType#: Typedef for Atom class.

typedef PersistentAtom<RWMolecule> PersistentAtomType#: Typedef for PersistentAtom class.

typedef RWBond BondType#: Typedef for Bond class.

typedef PersistentBond<RWMolecule> PersistentBondType#: Typedef for PersistentBond class.

Public Functions

explicit RWMolecule(Molecule &mol, QObject *parent = nullptr)#: Construct a molecule with the atoms/bonds of mol.

~RWMolecule() override#

inline Molecule &molecule()#

inline const Molecule &molecule() const#

AtomType addAtom(unsigned char atomicNumber, bool usingPositions = true)#

Add a new atom to the molecule.

Parameters:

atomicNumber – The atomic number of the new atom.
usingPositions – Whether or not to use positions for this atom. Default is true. Set to false if the atom will not be using coordinates.

Returns:

The new Atom object.

AtomType addAtom(unsigned char atomicNumber, const Vector3 &position3d)#

Add a new atom to the molecule and set its position.

Parameters:

atomicNumber – The atomic number of the new atom.
position3d – The position of the atom.

Returns:

The new Atom object.

inline AtomType atom(Index atomId) const#

Obtain an atom object.

Parameters:: atomId – The index of the atom to return.
Returns:: The requested atom object. Will be invalid if atomId >= atomCount().

inline AtomType atomByUniqueId(Index atomUId) const#

Obtain an atom object from it’s unique id.

Parameters:: atomUId – The unique of the requested atom.
Returns:: The requested atom object. Will be invalid if atomUId is not in use.

inline Index atomCount() const#

Returns:: The number of atoms in the molecule.

Index atomCount(unsigned char atomicNumber) const#

Returns:: The number of atoms in the molecule with the atomic number atomicNumber.

void clearAtoms()#: Delete all atoms from this molecule.

Note

This also removes all bonds.

void adjustHydrogens(Index atomId)#

Adjust hydrogens for an atom.

Note

Checks to make sure the atom is valid before adjusting the hydrogens.

Parameters:: atomId – The index of the atom.

void adjustHydrogens(const Core::Array<Index> &atomIds)#

Adjust hydrogens for multiple atoms.

Note

Checks to make sure the atoms are valid before adjusting the hydrogens.

Parameters:: atomIds – The indices for the atoms.

inline const Core::Array<unsigned char> &atomicNumbers() const#

Returns:: An array containing atomic numbers for all atoms in the molecule, indexed by atom index.

inline unsigned char atomicNumber(Index atomId) const#

Get the atomic number for the requested atom.

Parameters:: atomId – The index of the atom.
Returns:: The atomic number of the atom indexed at atomId, or Avogadro::InvalidElement if atomId is invalid.

bool setAtomicNumbers(const Core::Array<unsigned char> &nums)#

Replace the current array of atomic numbers.

Parameters:: nums – The new atomic number array. Must be of length atomCount().
Returns:: True on success, false otherwise.

bool setAtomicNumber(Index atomId, unsigned char atomicNumber)#

Set the atomic number of a single atom.

Parameters:

atomId – The index of the atom to modify.
atomicNumber – The new atomic number.

Returns:

True on success, false otherwise.

inline const Core::Array<Vector3> &atomPositions3d() const#

Note

May be empty if position information has not been set for any atoms.

Returns:: An array containing 3D coordinates for all atoms in the molecule, indexed by atom index.

inline Vector3 atomPosition3d(Index atomId) const#

Get the 3D position of a single atom.

Parameters:: atomId – The index of the atom.
Returns:: The position of the atom, or Vector3::Zero() if no position information has been set.

bool setAtomPositions3d(const Core::Array<Vector3> &pos, const QString &undoText = tr("Change Atom Positions"))#

Replace the current array of 3D atomic coordinates.

Parameters:

pos – The new coordinate array. Must be of length atomCount().
undoText – The undo text to be displayed for undo commands.

Returns:

True on success, false otherwise.

bool setAtomPosition3d(Index atomId, const Vector3 &pos, const QString &undoText = tr("Change Atom Position"))#

Set the 3D position of a single atom.

Parameters:

atomId – The index of the atom to modify.
pos – The new position of the atom.
undoText – The undo text to be displayed for undo commands.

Returns:

True on success, false otherwise.

inline std::string atomLabel(Index atomId) const#

bool setAtomLabel(Index atomId, const std::string &label, const QString &undoText = tr("Change Atom Label"))#

void setAtomSelected(Index atomId, bool selected, const QString &undoText = tr("Change Selection"))#: Set whether the specified atom is selected or not.

bool atomSelected(Index atomId) const#: Query whether the supplied atom index has been selected.

inline bool setAtomPosition2d(Index, const Vector2&)#

inline Vector2 atomPosition2d(Index)#

inline const Core::Array<Vector2> &atomPositions2d() const#

inline Core::AtomHybridization hybridization(Index atomId) const#

Get the hybridization for the requested atom.

Parameters:: atomId – The index of the atom.
Returns:: The hybridization of the atom indexed at atomId, or 0 if atomId is invalid.

bool setHybridization(Index atomId, Core::AtomHybridization hyb)#

Set the hybridization of a single atom.

Parameters:

atomId – The index of the atom to modify.
hyb – The new hybridization.

Returns:

True on success, false otherwise.

inline signed char formalCharge(Index atomId) const#

Get the formal charge for the requested atom.

Parameters:: atomId – The index of the atom.
Returns:: The formal charge of the atom indexed at atomId, or 0 if atomId is invalid.

bool setFormalCharge(Index atomId, signed char charge)#

Set the formal charge of a single atom.

Parameters:

atomId – The index of the atom to modify.
charge – The new formal charge.

Returns:

True on success, false otherwise.

inline Vector3ub color(Index atomId) const#

Get the color for the requested atom.

Parameters:: atomId – The index of the atom.
Returns:: The color of the atom indexed at atomId, or (0, 0, 0) if atomId is invalid. If no color is set for the given atomId, the default color for the atomic number of the atomId is returned.

bool setColor(Index atomId, Vector3ub color)#

Set the color of a single atom.

Parameters:

atomId – The index of the atom to modify.
color – The new color.

Returns:

True on success, false otherwise.

bool setLayer(Index atomId, size_t layer)#

inline size_t layer(Index atomId) const#

inline BondType bond(Index bondId) const#

Get a bond object.

Parameters:: bondId – The index of the requested bond.
Returns:: The requested bond object. Will be invalid if bondId >= bondCount().

BondType bond(Index atom1, Index atom2) const#

Get a bond object.

Parameters:

atom1 – The index of one atom in the bond.
atom2 – The index of the other atom in bond.

Returns:

The requested bond object. Will be invalid if atom1 or atom2 do not exist.

inline BondType bond(const AtomType &atom1, const AtomType &atom2) const#

Get a bond object.

Parameters:

atom1 – One atom in the bond.
atom2 – The other atom in bond.

Returns:

The requested bond object. Will be invalid if atom1 or atom2 are invalid.

inline BondType bondByUniqueId(Index bondUid) const#

Get a bond object from its unique id.

Parameters:: bondUid – The unique id of the bond.
Returns:: The requested bond object. Will be invalid if bondUid is not in use.

inline Index bondUniqueId(Index bondId) const#

Get the unique id of a bond.

Parameters:: bondId – The index of the requested bond.
Returns:: The unique id currently assigned to the bond at index bondId

inline Index bondUniqueId(const BondType &bond) const#

Get the unique id of a bond.

Parameters:: bond – The requested bond object.
Returns:: The unique id currently assigned to bond.

inline Index bondCount() const#

Returns:: The number of bonds in the molecule.

void clearBonds()#: Remove all bonds from the molecule.

inline Core::Array<BondType> bonds(const AtomType &atom) const#

Find bonds connected to an atom.

Parameters:: atom – The atom of interest.
Returns:: An array of bond objects that are attached to the specified atom.

inline Core::Array<BondType> bonds(const Index &atomId) const#

Find bonds connected to an atom.

Parameters:: atomId – The index for the atom of interest.
Returns:: An array of bond objects that are attached to the specified atom.

inline const Core::Array<unsigned char> &bondOrders() const#

Returns:: An array of bond orders for all bonds in the molecule, indexed by bond index.

inline unsigned char bondOrder(Index bondId) const#

Get the order of a bond.

Parameters:: bondId – The id of the bond.
Returns:: The bond order.

bool setBondOrders(const Core::Array<unsigned char> &orders)#

Replace the current array of bond orders.

Parameters:: orders – The new array.
Returns:: True on success, false on failure.

bool setBondOrder(Index bondId, unsigned char order)#

Set the order of a bond in the molecule.

Parameters:

bondId – The bond’s index.
order – The new order of the bond.

Returns:

True on success, false on failure.

inline const Core::Array<std::pair<Index, Index>> &bondPairs() const#

Returns:: An array of all bonded atoms in the molecule, indexed by bond index. Each bond pair is represented by a pair of atom indices.

inline std::pair<Index, Index> bondPair(Index bondId) const#

Get the set of bonded atoms corresponding to bondId.

Parameters:: bondId – The index of the requested bond.
Returns:: The bonded atom pair, represented as a pair of atom indices.

bool setBondPairs(const Core::Array<std::pair<Index, Index>> &pairs)#

Replace the current array of bonded atoms.

Note

The bonded atoms are represented as a pair of bond indices.

Note

If needed, the elements in pairs will be modified to ensure that the first atom index is less than the second.

Parameters:: pairs – The array.
Returns:: True on success, false on failure.

bool setBondPair(Index bondId, const std::pair<Index, Index> &pair)#

Set the bonded atoms for a bond.

Note

If needed, pair will be modified to ensure that the first atom index is less than the second.

Parameters:

bondId – The bond to modify.
pair – The new bond pair.

Returns:

True on success, false otherwise.

void addUnitCell()#: Add a default unit cell to the molecule. Does nothing if there already is a unit cell. Changes are emitted.

void removeUnitCell()#: Remove the unit cell from the molecule. Does nothing if there is no unit cell. Changes are emitted.

void modifyMolecule(const Molecule &newMolecule, Molecule::MoleculeChanges changes, const QString &undoText = QStringLiteral("Modify Molecule"))#

Generic edit that changes the current molecule to be newMolecule. Also sets the text for the undo command to be undoText. Changes are emitted.

Parameters:

newMolecule – The new molecule to be set.
changes – The changes to be emitted.
undoText – The text description for the undo command.

void appendMolecule(const Molecule &addMolecule, const QString &undoText = QStringLiteral("Append Molecule"))#

Generic edit that adds newMolecule to the current molecule. Also sets the text for the undo command to be undoText. Changes are emitted.

Parameters:

addMolecule – The new molecule to be set.
undoText – The text description for the undo command.

void editUnitCell(Matrix3 cellMatrix, Core::CrystalTools::Options opts)#

Edit the unit cell by replacing the current cell matrix with a new cell matrix. Changes are emitted.

Parameters:

cellMatrix – The new cell matrix to be set.
opts – If TransformAtoms is specified, the atoms in molecule are adjusted so that their fractional (lattice) coordinates are preserved. This option is ignored if the input molecule has no unit cell.

void wrapAtomsToCell()#: Wrap atoms to the unit cell. Changes are emitted.

void rotateCellToStandardOrientation()#: Rotate cell to standard orientation. Changes are emitted.

void setCellVolume(double newVolume, Core::CrystalTools::Options options)#

Scale a cell’s volume. Changes are emitted.

Parameters:

newVolume – The new volume to be set.
options – If CrystalTools::TransformAtoms is set, then the atoms will be transformed during the scaling.

void buildSupercell(unsigned int a, unsigned int b, unsigned int c)#

Build a supercell. Changes are emitted.

Parameters:

a – The final number of units along the A vector (at least 1).
b – The final number of units along the B vector (at least 1).
c – The final number of units along the C vector (at least 1).

void niggliReduceCell()#: Perform a Niggli reduction on the cell. Changes are emitted.

bool reduceCellToPrimitive(double cartTol = 1e-5)#

Use spglib to reduce the cell to its primitive form. Changes are emitted.

Parameters:: cartTol – Cartesian tolerance for primitive reduction.
Returns:: True if the algorithm succeeded, and false if it failed.

bool conventionalizeCell(double cartTol = 1e-5)#

Use spglib to convert the cell to its conventional form. Changes are emitted.

Parameters:: cartTol – Cartesian tolerance for conventionalization.
Returns:: True if the algorithm succeeded, and false if it failed.

bool symmetrizeCell(double cartTol = 1e-5)#

Use spglib to symmetrize the cell. Changes are emitted.

Parameters:: cartTol – Cartesian tolerance for symmetrization.
Returns:: True if the algorithm succeeded, and false if it failed.

bool fillUnitCell(unsigned short hallNumber, double cartTol = 1e-5)#

Fill unit cell using transforms for the space group. Changes are emitted.

Parameters:

hallNumber – The hall number to be used for transforming the cell.
cartTol – Cartesian tolerance for comparing atom positions.

Returns:

True if the algorithm succeeded, and false if it failed.

bool reduceCellToAsymmetricUnit(unsigned short hallNumber, double cartTol = 1e-5)#

Use transforms to reduce a cell to its asymmetric unit. Changes are emitted.

Parameters:

hallNumber – The hall number to be used for obtaining the transforms.
cartTol – Cartesian tolerance for comparing atom positions.

Returns:

True if the algorithm succeeded, and false if it failed.

inline void beginMergeMode(const QString &undoName = QStringLiteral("Draw"))#

Call this function when you wish to merge all undo commands. It turns on interactive mode to merge similar undo commands in a series (in order to save space), and it uses QUndoStack’s beginMacro() to merge dissimilar undo commands together. You must call endMergeMode() to end the merging section (undo and redo are unavailable while merge mode is on).

Parameters:: undoName – The name of the undo command

inline void endMergeMode()#: Call this function when you wish merge mode to end. This will turn off interactive mode, and it will call QUndoStack’s endMacro(). All of the undo commands pushed between beginMergeMode() and endMergeMode() will be merged into one undo command. beginMergeMode() should have been called before this is called.

inline void setInteractive(bool b)#

Begin or end an interactive edit.

If enabled, certain undo operations will be merged together. For instance, an editor dragging an atom through space in response to mouse movement will only generate a single undo command containing the initial and final positions and discard the intermediate states. If disabled, each intermediate action will appear in the undo log.

inline bool isInteractive() const#