EnergyUnits Class Reference

The units energies are read in and shown in, shared application-wide. More...

#include <avogadro/qtgui/energyunits.h>

Inheritance diagram for EnergyUnits:

Public Types
enum class	Unit {   Hartree = 0 ,   ElectronVolt = 1 ,   KcalPerMol = 2 ,   KjPerMol = 3 }

Public Slots
void	setSourceUnit (Unit unit)
void	setDisplayUnit (Unit unit)
void	setUnits (Unit source, Unit display)

Signals
void	unitsChanged ()

Public Member Functions
Unit	sourceUnit () const
Unit	sourceUnit (const Core::Molecule &molecule) const
Unit	displayUnit () const
QString	displaySymbol () const
double	convert (double energy) const
double	convert (double energy, const Core::Molecule &molecule) const

Static Public Member Functions
static EnergyUnits *	instance ()
static QVector< Unit >	units ()
static QString	symbol (Unit unit)
static Unit	fromSymbol (const QString &symbol, bool *ok=nullptr)
static void	fillCombo (QComboBox *combo, Unit current)
static Unit	unitFromCombo (const QComboBox *combo, Unit fallback)
static bool	declaresUnit (const Core::Molecule &molecule)
static double	convert (double energy, Unit from, Unit to)

Detailed Description

Energies arrive from a file in whatever unit the program that wrote them used, and nothing in the file usually says which – so the user has to. Having said it once, they should not have to say it again in every window showing the same numbers, which is what this is for: one setting, kept in QSettings so it survives a restart, with a signal so that a conformer plot and a conformer table open at the same time cannot disagree.

#include <avogadro/qtgui/energyunits.h>
...
auto* units = EnergyUnits::instance();
connect(units, &EnergyUnits::unitsChanged, this, &MyView::refresh);
const double shown = units->convert(energyFromFile);

Member Enumeration Documentation

Unit

enum class Unit

strong

The units an energy can be read in or shown in.

The values are written to QSettings, so they are numbered explicitly: inserting a unit in the middle must not change what an existing setting means.

Member Function Documentation

instance()

EnergyUnits * instance ( )

static

Returns

the one instance, created on first use.

units()

QVector< Unit > units ( )

static

Returns

every unit, in the order a combo box should list them.

symbol()

QString symbol ( Unit unit )

static

Returns

the symbol for unit, such as "kcal/mol".

Not translated: these are the symbols chemists write, and the same in every locale.

fromSymbol()

Unit fromSymbol ( const QString & symbol, bool * ok = nullptr )

static

Returns

the unit that symbol names, such as "kcal/mol".

Spelling is taken loosely – case is ignored, and the handful of names the same unit goes by are accepted ("au" and "a.u." for Hartree, "kcal" for kcal/mol) – because the string may have come out of a file.

Parameters

ok	set to whether symbol named a unit at all; a name that is not recognised must not be silently treated as the default.

fillCombo()

void fillCombo ( QComboBox * combo, Unit current )

static

Fill combo with every unit in units(), selecting current, for any widget offering a choice of energy unit.

Replaces any items combo already had. Signals are blocked while it is filled, so this does not emit currentIndexChanged(); a caller that needs to react to the selection connects afterwards. The unit itself rides along in the item data, so the combo's order need not match the enum's. Does nothing if combo is null.

unitFromCombo()

Unit unitFromCombo ( const QComboBox * combo, Unit fallback )

static

Returns

the unit named by combo's current item, or fallback when that item carries no recognised unit – including when combo is null or empty.

sourceUnit() [1/2]

Unit sourceUnit

(

)

const

Returns

the unit energies read from a file are taken to be in.

sourceUnit() [2/2]

Unit sourceUnit

(

const Core::Molecule &

molecule

)

const

Returns

the unit molecule's energies are actually in: what the reader recorded when it knew, and otherwise sourceUnit(), which is the user's to say.

A reader that knows what its program writes – ORCA always writes Hartree – saves the user from having to say so, and must not be overridden by a setting they last touched for some other file.

declaresUnit()

bool declaresUnit ( const Core::Molecule & molecule )

static

Returns

true when molecule's own energies name their unit, so nothing needs asking. A dialog offering to set it should say so rather than looking like it is being ignored.

displayUnit()

Unit displayUnit

(

)

const

Returns

the unit energies are shown in.

displaySymbol()

QString displaySymbol

(

)

const

Returns

the symbol for the unit energies are shown in.

convert() [1/3]

double convert

(

double

energy

)

const

Returns

energy, read in sourceUnit(), expressed in displayUnit().

Meant for an energy difference. Converting a total energy is arithmetic all the same, but the answer is a number no one wants: total energies differ by hundreds of Hartree between methods and mean nothing on their own.

convert() [2/3]

double convert ( double energy, Unit from, Unit to )

static

Returns

energy converted from from to to.

convert() [3/3]

double convert	(	double	energy,
		const Core::Molecule &	molecule ) const

Returns

energy, read in molecule's own units, expressed in displayUnit(). Prefer this wherever the molecule is at hand.

setSourceUnit

void setSourceUnit ( Unit unit )

slot

Set the unit energies read from a file are taken to be in, saving it and telling everything showing an energy to go and look again.

setDisplayUnit

void setDisplayUnit ( Unit unit )

slot

Set the unit energies are shown in.

setUnits

void setUnits ( Unit source, Unit display )

slot

Set both at once, so that changing the pair emits one signal, not two.

unitsChanged

void unitsChanged ( )

signal

Emitted when either unit changes.

---

The documentation for this class was generated from the following file:

• energyunits.h