Namespace qdk::chemistry::utils

namespace utils

Enums

enum class LogLevel

Log level enumeration for QDK Chemistry logging.

Values:

enumerator trace

Most verbose logging.

enumerator debug

Debug information.

enumerator info

General information.

enumerator warn

Warning messages.

enumerator error

Error messages.

enumerator critical

Critical errors.

enumerator off

Disable logging.

Functions

std::pair<size_t, size_t> compute_valence_space_parameters(std::shared_ptr<qdk::chemistry::data::Wavefunction> wavefunction, int charge)

Computes the default number of valence orbitals and electrons for a given structure and wavefunction.

This function analyzes the provided molecular structure and wavefunction to determine the number of electrons and orbitals in valence shell

Parameters:

  • wavefunction – Shared pointer to the wavefunction containing electronic structure information (structure is extracted from wavefunction->orbitals->basis_set)

  • charge – The total charge of the molecular system, which should be equal to the charge set in scf calculation

Returns:

A pair where:

  • first: Number of valence electrons

  • second: Number of valence orbitals

void log_trace_entering(const std::source_location &location = std::source_location::current())

Logs a standardized trace message for entering a function.

Automatically uses std::source_location to determine the calling function and logs a message in the form: “[context] Entering method_name”

This function is typically called via the QDK_LOG_TRACE_ENTERING() macro for convenience.

Example: 

void compute() {
  QDK_LOG_TRACE_ENTERING();  // Logs "[qdk:chemistry:...:compute] Entering"
  // ...
}

Parameters:

location – Automatically provided by std::source_location::current()

std::shared_ptr<qdk::chemistry::data::Orbitals> rotate_orbitals(std::shared_ptr<const qdk::chemistry::data::Orbitals> orbitals, const Eigen::VectorXd &rotation_vector, size_t num_alpha_occupied_orbitals, size_t num_beta_occupied_orbitals, bool restricted_external = false)

Rotate molecular orbitals using a rotation vector.

This function takes Orbitals and applies orbital rotations using a rotation vector, which can be taken from stability analysis eigenvectors.

The rotation is performed by:

  1. Unpacking the rotation vector into an anti-Hermitian matrix

  2. Computing the unitary rotation matrix via matrix exponential

  3. Applying the rotation to the molecular orbital coefficients

See also

data::StabilityResult

Note

restricted_external can break spin symmetry and solve external instabilities of RHF/RKS.

Note

This function assumes aufbau filling for occupation numbers.

Note

Orbital energies are invalidated by rotation and set to null.

Parameters:

  • orbitals – The Orbitals to rotate

  • rotation_vector – The rotation vector (eigenvector from stability analysis, corresponding to the lowest eigenvalue). See StabilityResult::eigenvector_format for detailed size and indexing requirements.

  • num_alpha_occupied_orbitals – Number of alpha occupied orbitals

  • num_beta_occupied_orbitals – Number of beta occupied orbitals

  • restricted_external – If true and orbitals are restricted, creates unrestricted orbitals with rotated coefficients for alpha spin and unrotated coefficients for beta spin. Default is false.

Throws:

std::runtime_error – if rotation vector size is invalid

Returns:

A new Orbitals object with rotated molecular orbital coefficients

class ContextLogger
#include <qdk/chemistry/utils/logger.hpp>

A logger wrapper that automatically prepends source context to messages.

This class wraps the global logger and automatically includes file/method context in every log message. It provides the same interface as spdlog::logger (trace, debug, info, warn, error, critical) but prepends source location info.

Use via the QDK_LOGGER() macro which captures the call site’s source location.

Example: 

QDK_LOGGER().info("Message with {} args", 2);
// Output: [timestamp] [info] [file:method] Message with 2 args

Public Functions

inline explicit ContextLogger(const std::source_location &loc)
inline void critical(const std::string &msg)
template<typename ...Args>
inline void critical(fmt::format_string<Args...> fmt, Args&&... args)
inline void debug(const std::string &msg)
template<typename ...Args>
inline void debug(fmt::format_string<Args...> fmt, Args&&... args)
inline void error(const std::string &msg)
template<typename ...Args>
inline void error(fmt::format_string<Args...> fmt, Args&&... args)
inline void info(const std::string &msg)
template<typename ...Args>
inline void info(fmt::format_string<Args...> fmt, Args&&... args)
inline void trace(const std::string &msg)
template<typename ...Args>
inline void trace(fmt::format_string<Args...> fmt, Args&&... args)
inline void warn(const std::string &msg)
template<typename ...Args>
inline void warn(fmt::format_string<Args...> fmt, Args&&... args)
class Logger
#include <qdk/chemistry/utils/logger.hpp>

Centralized logging utility wrapper around spdlog for QDK Chemistry.

This class provides a consistent interface for logging throughout the QDK Chemistry library, wrapping the spdlog library with project-specific defaults and conventions. It uses a single global logger instance for efficiency, while still providing per-file/function context in log messages.

Public Static Functions

static std::shared_ptr<spdlog::logger> get()

Get the global logger instance.

Returns the single global logger instance for QDK Chemistry. The logger is lazily initialized on first call and reused thereafter.

New logger is created with default settings:

  • Colored console output

  • Inherit global log level

  • Consistent timestamped format

Returns:

Shared pointer to the global logger instance

static LogLevel get_global_level()

Get the current global log level.

Returns the current global logging level. This uses mutex protection to ensure thread safety.

Returns:

The current global log level

static std::string get_source_context(const std::source_location &location = std::source_location::current())

Get a formatted source context string for the given location.

Returns a string like “qdk:chemistry:utils:logger:method_name” that identifies the source file and method. This is automatically used by the ContextLogger to prefix log messages with per-file context.

Parameters:

location – Source location (defaults to caller’s location)

Returns:

Formatted context string

static void set_global_level(LogLevel level)

Set the global log level for all loggers.

Changes the logging level for the global logger instance. Messages below this level will be suppressed.

Parameters:

level – The minimum log level to output