FCIDump

QfFCIDump

struct QfFCIDump

Ein Hamilton-Operator für die elektronische Struktur im FCIDump-Format.

Begriffsbestimmung

Das FCIDump-Format wurde ursprünglich von Knowles und Handy im Jahr 1989 definiert [1]. Es handelt sich um ein weit verbreitetes Format zum Exportieren von Hamilton-Operatoren der elektronischen Struktur in eine Klartextdatei.

Die vorliegende Datenstruktur speichert lediglich die Informationen, die für die Konstruktion des sekundär quantisierten Operators relevant sind. Diese Implementierung geht jedoch über die ursprüngliche Definition hinaus, da sie das Laden beliebiger Spindaten unterstützt. Die folgende Tabelle zeigt, wie Integrale den Spinarten zugeordnet werden, je nachdem, in welche Intervalle die Indizes fallen (unter der Annahme einer Überschrift mit NORB=n):

Integraltyp	i	j	k	l
Konstante	${0}$	${0}$	${0}$	${0}$
1-Körper-Alpha	${0}$	${0}$	$[1,n]$	$[1,n]$
1-Körper-Beta	${0}$	${0}$	$[n+1,2n]$	$[n+1,2n]$
2-Körper-Alpha-Alpha	$[1,n]$	$[1,n]$	$[1,n]$	$[1,n]$
2-Körper-Alpha-Beta	$[1,n]$	$[1,n]$	$[n+1,2n]$	$[n+1,2n]$
2-Körper-Beta-Beta	$[n+1,2n]$	$[n+1,2n]$	$[n+1,2n]$	$[n+1,2n]$

Die einzigen erforderlichen Werte sind die 1-Körper-Alpha-Spin-Integrale.

Die Zwei-Körper-Integrale werden in der Reihenfolge „ $(ij|kl)$ “ angegeben, was der FCIDump-Konvention entspricht.

Datenlayout

Die Integrale werden unter Ausnutzung ihrer Permutationssymmetrie als abgeflachte Arrays gespeichert; dies entspricht auch dem Layout, das die elektronischen Integralgeneratoren ( Electronic Integrals ) erwarten. Schreibt man „ $n$ “ für die Anzahl der Orbitalen (qf_fcidump_norb()) und „ $\text{npair} = n (n + 1) / 2$ “, enthält eine einzelne Datenstruktur bis zu 5 Arrays:

Bereich	Länge	Inhalt
`one_body_a`	$\text{npair}$	Die $\alpha$ -Spin-1-Ein-Körper-Integrale.
`one_body_b`	$\text{npair}$	Die $\beta$ -Spin-1-Ein-Körper-Integrale.
`two_body_aa`	$\text{npair} (\text{npair} + 1) / 2$	Die 2-Körper-Integrale von „ $\alpha\alpha$ “.
`two_body_ab`	$\text{npair}^2$	Die 2-Körper-Integrale von „ $\alpha\beta$ “.
`two_body_bb`	$\text{npair} (\text{npair} + 1) / 2$	Die 2-Körper-Integrale von „ $\beta\beta$ “.

Die 1-Body-Arrays entsprechen dem abgeflachten unteren Dreieck einer $(n, n)$ -Matrix, indiziert als ia = i * (i + 1) / 2 + a mit a <= i. Die Arrays two_body_bb und two_body_aa sind 8-fach ( S8 ) symmetrisch: das abgeflachte untere Dreieck einer $(\text{npair}, \text{npair})$ -Matrix, deren eigene beiden Achsen jeweils ein solches Indexpaar bilden.

Warnung

two_body_ab wird anders verpackt als seine Geschwister. Sie ist nur 4-fach ( S4 ) symmetrisch, enthält also die gesamte Matrix „ $(\text{npair}, \text{npair})$ “ in zeilenorientierter Reihenfolge, indiziert als iajb = ia * npair + jb. Sein Zeilenpaar indiziert die Spinarten „ $\alpha$ “, sein Spaltenpaar die Spinarten „ $\beta$ “, sodass die Matrix beim Vertauschen der beiden Paare nicht symmetrisch ist.

Die 1-Körper-Anordnungen „ $\beta$ “ (Spin 1) und die 2-Körper-Anordnungen „ $\alpha\beta$ “ / „ $\beta\beta$ “ sind nur in Dateien vorhanden, die uneingeschränkte Spindaten enthalten. Da sie alle drei nicht vorhanden sind, werden alle drei gleichzeitig qf_fcidump_is_unrestricted() gemeldet, und die Getter, die sie auslesen, werden gesperrt.

Die gespeicherten Werte sind die Integrale, wie sie in der Datei aufgeführt sind. Insbesondere enthalten sie nicht den herkömmlichen Faktor $\frac{1}{2}$ , der in den 2-Körper-Operatortermen vorkommt; daher beträgt qf_ferm_op_from_fcidump() der Koeffizient eines über gebildeten Operators die Hälfte des hier angegebenen Wertes.

Die Erstellung eines dichten Tensors vom Typ „ $(n, n)$ “ oder „ $(n, n, n, n)$ “ aus diesen Arrays (wie sie beispielsweise von Werkzeugen zur samplebasierten Diagonalisierung benötigt werden) ist Aufgabe des Aufrufers; die oben genannten Indexformeln sind für diese Erweiterung erforderlich.

[ 1 ]

1. Knowles und N. C. Handy, „Computer Physics Communications“ 54 (1989), S. 75–83.

Mitglieder

qf_fcidump_from_file

QfExitCode qf_fcidump_from_file(char *file_path, QfFCIDump **out)

Analysiert eine FCIDump-Datei.

Beispiel

Angenommen, Sie haben eine FCIDump-Datei namens molecule.fcidump, dann verwenden Sie diese Funktion wie folgt:

1QfFCIDump *fcidump = NULL;
2QfExitCode exit = qf_fcidump_from_file("molecule.fcidump", &fcidump);
3
4assert(exit == QfExitCode_Success);

Parameter

file_path – Der Pfad zur FCIDump-Datei.
out – Ein Zeiger auf den Zeiger, auf den die geparste FCIDump-Datenstruktur gesetzt wird. Es wird nur bei Erfolg beschrieben; bei einem Fehler bleibt es unverändert.

Rückgabe

Ein Exit-Code. Dies ist der Fall QfExitCode_ValueError , wenn die Datei nicht geöffnet oder gelesen werden kann oder wenn sie nicht dem FCIDump-Format entspricht (fehlende Header-Namensliste, fehlendes NORB oder Feld NELEC , fehlerhaftes Feld MS2 oder ein nicht unterstützter MO-Energiewert).

qf_fcidump_free

void qf_fcidump_free(QfFCIDump *fcidump)

Gibt eine vorhandene FCIDump-Datenstruktur frei.

Beispiel

1QfFCIDump *fcidump = NULL;
2qf_fcidump_from_file("molecule.fcidump", &fcidump);
3qf_fcidump_free(fcidump);

Parameter

fcidump – Ein Zeiger auf die FCIDump-Datenstruktur, die freigegeben werden soll.

qf_fcidump_norb

uint32_t qf_fcidump_norb(const QfFCIDump *fcidump)

Ruft die Anzahl der Orbitalen aus einem FCIDump ab.

Diese Nummer, $n$ , wird aus dem NORB=n Feld im Header der FCIDump-Datei extrahiert.

Beispiel

1QfFCIDump *fcidump = NULL;
2qf_fcidump_from_file("molecule.fcidump", &fcidump);
3uint32_t norb = qf_fcidump_norb(fcidump);

Parameter

fcidump – Ein Zeiger auf die FCIDump-Datenstruktur, die abgefragt werden soll.

Rückgabe

Die Anzahl der Orbitale.

qf_fcidump_nelec

uint32_t qf_fcidump_nelec(const QfFCIDump *fcidump)

Ruft die Anzahl der Elektronen aus einem FCIDump ab.

Diese Nummer, $n$ , wird aus dem NELEC=n Feld im Header der FCIDump-Datei extrahiert.

Beispiel

1QfFCIDump *fcidump = NULL;
2qf_fcidump_from_file("molecule.fcidump", &fcidump);
3uint32_t nelec = qf_fcidump_nelec(fcidump);

Parameter

fcidump – Ein Zeiger auf die FCIDump-Datenstruktur, die abgefragt werden soll.

Rückgabe

Die Anzahl der Elektronen.

qf_fcidump_ms2

uint32_t qf_fcidump_ms2(const QfFCIDump *fcidump)

Ruft die Spinquantenzahl aus einem FCIDump ab.

Diese Nummer, $S$ , wird aus dem MS2=S Feld im Header der FCIDump-Datei extrahiert.

Beispiel

1QfFCIDump *fcidump = NULL;
2qf_fcidump_from_file("molecule.fcidump", &fcidump);
3uint32_t ms2 = qf_fcidump_ms2(fcidump);

Parameter

fcidump – Ein Zeiger auf die FCIDump-Datenstruktur, die abgefragt werden soll.

Rückgabe

Die Spinquantenzahl (mit 2 multipliziert, um einen ganzzahligen Wert zu gewährleisten).

qf_fcidump_is_unrestricted

bool qf_fcidump_is_unrestricted(const QfFCIDump *fcidump)

Prüft, ob ein FCIDump uneingeschränkte (spinabhängige) Integrale enthält.

Die 1-Körper-Anordnungen mit Beta-Spin und die 2-Körper-Anordnungen mit Alpha-Beta bzw. Beta-Beta liegen genau dann vor, wenn dies zurückgegeben wird true; sie fehlen immer gemeinsam. Verwende es, um qf_fcidump_get_one_body_tril_b(), und qf_fcidump_get_two_body_tril_ab() zu schützen qf_fcidump_get_two_body_tril_bb().

Beispiel

1QfFCIDump *fcidump = NULL;
2qf_fcidump_from_file("molecule.fcidump", &fcidump);
3
4bool unrestricted = qf_fcidump_is_unrestricted(fcidump);

Parameter

fcidump – Ein Zeiger auf die FCIDump-Datenstruktur, die abgefragt werden soll.

Rückgabe

true sofern die Beta-Spin-Integrale vorhanden sind.

qf_fcidump_has_constant

bool qf_fcidump_has_constant(const QfFCIDump *fcidump)

Prüft, ob ein FCIDump einen konstanten Energie-Offset liefert.

Verwende dies zum Schutz qf_fcidump_constant(). Dies ist unabhängig von qf_fcidump_is_unrestricted(): Eine spinbeschränkte Datei kann durchaus eine Konstante enthalten.

Beispiel

1QfFCIDump *fcidump = NULL;
2qf_fcidump_from_file("molecule.fcidump", &fcidump);
3
4bool has_constant = qf_fcidump_has_constant(fcidump);

Parameter

fcidump – Ein Zeiger auf die FCIDump-Datenstruktur, die abgefragt werden soll.

Rückgabe

true wenn die Datei eine ganzzahlige Zeile enthielt, deren vier Indizes alle Null waren.

qf_fcidump_constant

double qf_fcidump_constant(const QfFCIDump *fcidump)

Ruft den konstanten Energie-Offset aus einem FCIDump ab.

Dies ist der Wert der Integralzeile, deren vier Indizes alle Null sind; bei einem Hamilton-Operator der Elektronenstruktur entspricht dies der Kernabstoßungsenergie.

Beispiel

1QfFCIDump *fcidump = NULL;
2qf_fcidump_from_file("molecule.fcidump", &fcidump);
3
4double constant = 0.0;
5if (qf_fcidump_has_constant(fcidump)) {
6    constant = qf_fcidump_constant(fcidump);
7}

Warnung

Rufe diese Funktion nur auf, wenn zurückgibt qf_fcidump_has_constant()true ; andernfalls löst der Aufruf einen Panikfehler aus.

Parameter

fcidump – Ein Zeiger auf die FCIDump-Datenstruktur, die abgefragt werden soll.

Rückgabe

Der konstante Energieversatz.

qf_fcidump_get_one_body_tril_a

void qf_fcidump_get_one_body_tril_a(const QfFCIDump *fcidump, double **out, uint64_t *out_len)

Bietet Lesezugriff auf die Alpha-Spin-1-Körperintegrale.

Siehe auch

Die Erläuterung zum internen Datenaufbau finden Sie hier.

Beispiel

1QfFCIDump *fcidump = NULL;
2qf_fcidump_from_file("molecule.fcidump", &fcidump);
3
4double *integrals;
5uint64_t len;
6qf_fcidump_get_one_body_tril_a(fcidump, &integrals, &len);

Anmerkung

Diese Funktion nutzt den internen Puffer von FCIDump, anstatt ihn zu kopieren. Der zurückgegebene Zeiger bleibt nur so lange gültig, bis die Datenstruktur freigegeben wird; geben Sie ihn nicht selbst frei.

Parameter

fcidump – Ein Zeiger auf die FCIDump-Datenstruktur, auf deren Elemente zugegriffen werden soll.
out – Ein Zeiger auf das Double-Array, in das die Integrale geschrieben werden sollen.
out_len – Ein Zeiger auf die Ganzzahl, in die die Länge des Ausgabearrays geschrieben werden soll.

qf_fcidump_get_one_body_tril_b

void qf_fcidump_get_one_body_tril_b(const QfFCIDump *fcidump, double **out, uint64_t *out_len)

Bietet schreibgeschützten Zugriff auf die Beta-Spin-1-Körperintegrale.

Siehe auch

Die Erläuterung zum internen Datenaufbau finden Sie hier.

Beispiel

1QfFCIDump *fcidump = NULL;
2qf_fcidump_from_file("molecule.fcidump", &fcidump);
3
4double *integrals;
5uint64_t len;
6qf_fcidump_get_one_body_tril_b(fcidump, &integrals, &len);

Warnung

Rufen Sie diese Funktion nur für eine Datenstruktur auf, die uneingeschränkte Spin-Daten enthält. Überprüfen Sie dies zunächst qf_fcidump_is_unrestricted() ; andernfalls kommt es zu einer Panik.

Anmerkung

Parameter

fcidump – Ein Zeiger auf die FCIDump-Datenstruktur, auf deren Elemente zugegriffen werden soll.
out – Ein Zeiger auf das Double-Array, in das die Integrale geschrieben werden sollen.
out_len – Ein Zeiger auf die Ganzzahl, in die die Länge des Ausgabearrays geschrieben werden soll.

qf_fcidump_get_two_body_tril_aa

void qf_fcidump_get_two_body_tril_aa(const QfFCIDump *fcidump, double **out, uint64_t *out_len)

Bietet Lesezugriff auf die Alpha-Alpha-Spin-2-Körper-Integrale.

Siehe auch

Die Erläuterung zum internen Datenaufbau finden Sie hier.

Beispiel

1QfFCIDump *fcidump = NULL;
2qf_fcidump_from_file("molecule.fcidump", &fcidump);
3
4double *integrals;
5uint64_t len;
6qf_fcidump_get_two_body_tril_aa(fcidump, &integrals, &len);

Anmerkung

Die Werte entsprechen der chemischen Reihenfolge ( $(ij|kl)$ ) und enthalten keinen Faktor von $\frac{1}{2}$ .

Parameter

fcidump – Ein Zeiger auf die FCIDump-Datenstruktur, auf deren Elemente zugegriffen werden soll.
out – Ein Zeiger auf das Double-Array, in das die Integrale geschrieben werden sollen.
out_len – Ein Zeiger auf die Ganzzahl, in die die Länge des Ausgabearrays geschrieben werden soll.

qf_fcidump_get_two_body_tril_ab

void qf_fcidump_get_two_body_tril_ab(const QfFCIDump *fcidump, double **out, uint64_t *out_len)

Bietet Lesezugriff auf die Alpha-Beta-Spin-2-Körper-Integrale.

Siehe auch

Die Erläuterung zum internen Datenaufbau finden Sie hier.

Beispiel

1QfFCIDump *fcidump = NULL;
2qf_fcidump_from_file("molecule.fcidump", &fcidump);
3
4double *integrals;
5uint64_t len;
6qf_fcidump_get_two_body_tril_ab(fcidump, &integrals, &len);

Warnung

Anmerkung

Die Werte entsprechen der chemischen Reihenfolge ( $(ij|kl)$ ) und enthalten keinen Faktor von $\frac{1}{2}$ .

Warnung

Im Gegensatz zu den anderen 2-Körper-Anordnungen weist diese nur eine 4-fache ( S4 ) Symmetrie auf: Sie enthält die vollständige Matrix (npair, npair) , deren Zeilenpaare die Alpha-Spin- und deren Spaltenpaare die Beta-Spin-Spezies indizieren. Sie ist daher nicht symmetrisch, wenn man die beiden Paare vertauscht.

Parameter

fcidump – Ein Zeiger auf die FCIDump-Datenstruktur, auf deren Elemente zugegriffen werden soll.
out – Ein Zeiger auf das Double-Array, in das die Integrale geschrieben werden sollen.
out_len – Ein Zeiger auf die Ganzzahl, in die die Länge des Ausgabearrays geschrieben werden soll.

qf_fcidump_get_two_body_tril_bb

void qf_fcidump_get_two_body_tril_bb(const QfFCIDump *fcidump, double **out, uint64_t *out_len)

Bietet Lesezugriff auf die Beta-Beta-Spin-2-Körper-Integrale.

Siehe auch

Die Erläuterung zum internen Datenaufbau finden Sie hier.

Beispiel

1QfFCIDump *fcidump = NULL;
2qf_fcidump_from_file("molecule.fcidump", &fcidump);
3
4double *integrals;
5uint64_t len;
6qf_fcidump_get_two_body_tril_bb(fcidump, &integrals, &len);

Warnung

Anmerkung

Die Werte entsprechen der chemischen Reihenfolge ( $(ij|kl)$ ) und enthalten keinen Faktor von $\frac{1}{2}$ .

Parameter

fcidump – Ein Zeiger auf die FCIDump-Datenstruktur, auf deren Elemente zugegriffen werden soll.
out – Ein Zeiger auf das Double-Array, in das die Integrale geschrieben werden sollen.
out_len – Ein Zeiger auf die Ganzzahl, in die die Länge des Ausgabearrays geschrieben werden soll.

Konvertierung

Operator-Darstellungen, die aus einer Instanz von konstruiert werden können, stellen QfFCIDump eine Funktion qf_*_from_fcidump bereit:

qf_ferm_op_from_fcidump

QfFermionOperator *qf_ferm_op_from_fcidump(const QfFCIDump *fcidump)

Erstellt eine :c:struct:QfFermionOperator aus einer :c:structQfFCIDump:.

Beispiel

1QfFCIDump *fcidump = NULL;
2qf_fcidump_from_file("molecule.fcidump", &fcidump);
3QfFermionOperator *op = qf_ferm_op_from_fcidump(fcidump);

Parameter

fcidump – Ein Zeiger auf die FCIDump-Datenstruktur.

Rückgabe

Ein Zeiger auf den erstellten Operator.

War diese Seite hilfreich?

Melden Sie auf GitHub einen Fehler, einen Tippfehler oder fordern Sie Inhalte an.