class rgpot::cache::PotentialCache

Overview

Caches potential energy and force calculations using RocksDB. More…

#include <PotentialCache.hpp>
 
class PotentialCache {
public:
    // construction
 
    PotentialCache(const std::string& db_path, bool create_if_missing = true);
    PotentialCache();
    ~PotentialCache();
 
    // methods
 
    void set_db(rocksdb::DB* db);
    void deserialize_hit(const std::string& value, double& energy, rgpot::types::AtomMatrix& forces);
    void add_serialized(const KeyHash& key, double energy, const rgpot::types::AtomMatrix& forces);
    std::optional<std::string> find(const KeyHash& key);
};

Detailed Documentation

Caches potential energy and force calculations using RocksDB.

Construction

PotentialCache(const std::string& db_path, bool create_if_missing = true)

Constructor opens the DB at the given path.

Initializes the RocksDB options, specifically setting create_if_missing. It attempts to open the database at the specified path. If the open fails, an error is printed to stderr and the internal database pointer remains null. If successful, the own_db_ flag is set to true.

Parameters:

db_path	Path to the RocksDB database.
create_if_missing	Toggle creation of DB if absent.

PotentialCache()

Default constructor.

~PotentialCache()

Destructor.

Checks if the class owns the database pointer. If so, it deletes the rocksdb::DB instance to prevent memory leaks.

Methods

void set_db(rocksdb::DB* db)

Helper for manual pointer setting.

This function allows for manually injecting a RocksDB pointer. If the current instance already owns a database, it is deleted before accepting the new pointer. Ownership is transferred away from this class (own_db_ set to false), implying the caller manages the new pointer’s lifetime or it is a shared resource.

Warning

Use with caution to avoid double-free or memory leaks if the passed pointer is managed elsewhere.

Parameters:

db	Pointer to an existing RocksDB instance.

Returns:

Void.

void deserialize_hit(const std::string& value, double& energy, rgpot::types::AtomMatrix& forces)

Deserializes a cache hit into output containers.

Performs a binary copy (std::memcpy) from the serialized string buffer back into the energy variable and force matrix.

The layout is assumed to be: [double energy] [double force_0] ... [double force_N]

Parameters:

value	Serialized string from the cache.
energy	Reference to store the energy.
forces	Reference to store the forces.

Returns:

Void.

void add_serialized(const KeyHash& key, double energy, const rgpot::types::AtomMatrix& forces)

Adds a serialized calculation to the cache.

Serializes the energy and forces into a contiguous binary buffer. The buffer size is calculated as sizeof(double) + N * sizeof(double). This buffer is then stored in RocksDB using the provided key.

Note

If the database is not initialized, this function returns immediately.

Parameters:

key	Unique hash key for the configuration.
energy	Calculated energy.
forces	Calculated forces.

Returns:

Void.

std::optional<std::string> find(const KeyHash& key)

Searches the cache for a specific key.

Queries the RocksDB instance for the given key.

Parameters:

key	Unique hash key.

Returns:

Optional string containing the serialized data.

std::optional containing the serialized string if found, or std::nullopt if the key does not exist or the DB is closed.