Class Avogadro::QtGui::RWMolecule

class Avogadro::QtGui::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 = QStringLiteral("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 = QStringLiteral("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.

void setAtomSelected(Index atomId, bool selected)

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.

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

See

setInteractive

Returns

True if interactive mode is enabled, false otherwise.

inline const Core::Array<Vector3> &forceVectors() const

Returns a vector of forces for the atoms in the molecule.

bool setForceVector(Index atomId, const Vector3 &pos, const QString &undoText = QStringLiteral("Change Force Vectors"))

Replace the current array of force vectors.

Parameters
  • pos – The new force vector array. Must be of length atomCount().

  • undoText – The undo text to be displayed for undo commands.

Returns

True on success, false otherwise.

Public Slots

void emitChanged(unsigned int change)

Force the molecule to emit the changed() signal.

Parameters

change – See changed().

Signals

void changed(unsigned int change)

Indicates that the molecule has changed.

The change variable indicates what has changed, i.e. if change & Atoms == true then atoms were changed in some way, and if change & Removed == true then one or more atoms were removed.

Parameters

change – Use the MoleculeChange enum to check what has changed.

Protected Functions

Index findAtomUniqueId(Index atomId) const
Index findBondUniqueId(Index bondId) const

Protected Attributes

Molecule &m_molecule

m_molecule still stored all data, this class acts upon it and builds an undo/redo stack that can be used to offer undo and redo.

bool m_interactive
QUndoStack m_undoStack

Friends

friend class UndoCommand
friend class Molecule