scipy.differentiate.

jacobian#

scipy.differentiate.jacobian(f, x, *, tolerances=None, maxiter=10, order=8, initial_step=0.5, step_factor=2.0, step_direction=0)[Quelle]#

Numerische Auswertung der Jacobi-Matrix einer Funktion.

Parameter:

faufrufbar

Die Funktion, deren Jacobi-Matrix gewünscht wird. Die Signatur muss

f(xi: ndarray) -> ndarray

wobei jedes Element von xi eine endliche reelle Zahl ist. Wenn die zu differenzierende Funktion zusätzliche Argumente akzeptiert, wrappen Sie sie (z.B. mit functools.partial oder lambda) und übergeben Sie die gewrappte aufrufbare Funktion an jacobian. f darf das Array xi nicht verändern. Siehe Hinweise bezüglich Vektorisierung und Dimensionalität der Ein- und Ausgabe.

xFloat-Array-ähnlich

Punkte, an denen die Jacobi-Matrix ausgewertet werden soll. Muss mindestens eine Dimension haben. Siehe Hinweise bezüglich Dimensionalität und Vektorisierung.

tolerancesDictionary von Floats, optional

Absolute und relative Toleranzen. Gültige Schlüssel des Dictionaries sind

atol - absolute Toleranz für die Ableitung
rtol - relative Toleranz für die Ableitung

Die Iteration wird gestoppt, wenn res.error < atol + rtol * abs(res.df). Die Standardwerte für atol ist die kleinste normale Zahl des entsprechenden Datentyps, und der Standardwert für rtol ist die Quadratwurzel der Präzision des entsprechenden Datentyps.

maxiterInteger, Standard: 10

Die maximale Anzahl von Iterationen, die der Algorithmus durchführen soll. Siehe Hinweise.

orderInteger, Standard: 8

Die (positive ganze Zahl) Ordnung der zu verwendenden Finite-Differenzen-Formel. Ungerade ganze Zahlen werden auf die nächste gerade ganze Zahl aufgerundet.

initial_stepfloat array_like, Standardwert: 0.5

Die (absolute) anfängliche Schrittgröße für die Approximation der Differenzialquotienten mittels finiter Differenzen. Muss mit x und step_direction broadcastbar sein.

step_factorFloat, Standard: 2.0

Der Faktor, um den die Schrittgröße in jeder Iteration *reduziert* wird; d. h. die Schrittgröße in Iteration 1 ist initial_step/step_factor. Wenn step_factor < 1, sind nachfolgende Schritte größer als der anfängliche Schritt; dies kann nützlich sein, wenn Schritte, die kleiner als ein bestimmter Schwellenwert sind, unerwünscht sind (z. B. aufgrund von subtraktiven Fehler).

step_directioninteger array_like

Ein Array, das die Richtung der Schritte der finiten Differenzen darstellt (z.B. für die Verwendung, wenn x nahe der Grenze des Definitionsbereichs der Funktion liegt). Muss mit x und initial_step broadcastbar sein. Wenn 0 (Standardwert), werden zentrale Differenzen verwendet; wenn negativ (z.B. -1), sind die Schritte nicht-positiv; und wenn positiv (z.B. 1), sind alle Schritte nicht-negativ.

Rückgabe:

res_RichResult

Ein Objekt, das einer Instanz von scipy.optimize.OptimizeResult ähnelt, mit den folgenden Attributen. Die Beschreibungen sind so formuliert, als wären die Werte Skalare; wenn f jedoch ein Array zurückgibt, sind die Ausgaben Arrays derselben Form.

successBool-Array

True, wenn der Algorithmus erfolgreich beendet wurde (Status 0); andernfalls False.

statusInteger-Array

Eine Ganzzahl, die den Exit-Status des Algorithmus darstellt.

0 : Der Algorithmus konvergierte gegen die angegebenen Toleranzen.
-1 : Die Fehlerschätzung stieg an, daher wurde die Iteration beendet.
-2 : Die maximale Anzahl von Iterationen wurde erreicht.
-3 : Ein nicht-endlicher Wert wurde angetroffen.

dffloat array

Die Jacobi-Matrix von f an der Stelle x, wenn der Algorithmus erfolgreich terminiert ist.

errorFloat-Array

Eine Schätzung des Fehlers: die Größe der Differenz zwischen der aktuellen Schätzung der Jacobi-Matrix und der Schätzung in der vorherigen Iteration.

nitint array

Die Anzahl der Iterationen des Algorithmus, die durchgeführt wurden.

nfevInteger-Array

Die Anzahl der Punkte, an denen f ausgewertet wurde.

Jedes Element eines Attributs ist mit dem entsprechenden Element von df verbunden. Zum Beispiel ist das Element i von nfev die Anzahl der Punkte, an denen f zur Berechnung des Elements i von df ausgewertet wurde.

Siehe auch

derivative, hessian

Hinweise

Angenommen, wir möchten die Jacobi-Matrix einer Funktion \(f: \mathbf{R}^m \rightarrow \mathbf{R}^n\) auswerten. Weisen Sie den Variablen m und n die positiven ganzzahligen Werte von \(m\) und \(n\) zu, und lassen Sie ... ein beliebiges Tupel von ganzen Zahlen darstellen. Wenn wir die Jacobi-Matrix an einem einzigen Punkt auswerten möchten, dann

argument x muss ein Array der Form (m,) sein
argument f muss vektorisiert sein, um ein Array der Form (m, ...) zu akzeptieren. Die erste Achse repräsentiert die \(m\) Eingaben von \(f\); der Rest dient zur Auswertung der Funktion an mehreren Punkten in einem einzigen Aufruf.
argument f muss ein Array der Form (n, ...) zurückgeben. Die erste Achse repräsentiert die \(n\) Ausgaben von \(f\); der Rest dient dem Ergebnis der Auswertung der Funktion an mehreren Punkten.
Das Attribut df des Ergebnisobjekts wird ein Array der Form (n, m) sein, die Jacobi-Matrix.

Diese Funktion ist auch in dem Sinne vektorisiert, dass die Jacobi-Matrix mit einem einzigen Aufruf an k Punkten ausgewertet werden kann. In diesem Fall wäre x ein Array der Form (m, k), f würde ein Array der Form (m, k, ...) akzeptieren und ein Array der Form (n, k, ...) zurückgeben, und das Attribut df des Ergebnisses hätte die Form (n, m, k).

Angenommen, die gewünschte aufrufbare Funktion f_not_vectorized ist nicht vektorisiert; sie kann nur ein Array der Form (m,) akzeptieren. Eine einfache Lösung, um die erforderliche Schnittstelle zu erfüllen, ist das Wrappen von f_not_vectorized wie folgt:

def f(x):
    return np.apply_along_axis(f_not_vectorized, axis=0, arr=x)

Alternativ angenommen, die gewünschte aufrufbare Funktion f_vec_q ist vektorisiert, aber nur für 2D-Arrays der Form (m, q). Um die erforderliche Schnittstelle zu erfüllen, betrachten Sie:

def f(x):
    m, batch = x.shape[0], x.shape[1:]  # x.shape is (m, ...)
    x = np.reshape(x, (m, -1))  # `-1` is short for q = prod(batch)
    res = f_vec_q(x)  # pass shape (m, q) to function
    n = res.shape[0]
    return np.reshape(res, (n,) + batch)  # return shape (n, ...)

Übergeben Sie dann die gewrappte aufrufbare Funktion f als erstes Argument von jacobian.

Referenzen

[1]

Jacobi-Matrix und Determinante, Wikipedia, https://en.wikipedia.org/wiki/Jacobian_matrix_and_determinant

Beispiele

Die Rosenbrock-Funktion bildet von \(\mathbf{R}^m \rightarrow \mathbf{R}\) ab; die SciPy-Implementierung scipy.optimize.rosen ist vektorisiert, um ein Array der Form (m, p) zu akzeptieren und ein Array der Form p zurückzugeben. Angenommen, wir möchten die Jacobi-Matrix (auch Gradient genannt, da die Funktion einen Skalar zurückgibt) an der Stelle [0.5, 0.5, 0.5] auswerten.

>>> import numpy as np
>>> from scipy.differentiate import jacobian
>>> from scipy.optimize import rosen, rosen_der
>>> m = 3
>>> x = np.full(m, 0.5)
>>> res = jacobian(rosen, x)
>>> ref = rosen_der(x)  # reference value of the gradient
>>> res.df, ref
(array([-51.,  -1.,  50.]), array([-51.,  -1.,  50.]))

Als Beispiel für eine Funktion mit mehreren Ausgaben betrachten Sie Beispiel 4 aus [1].

>>> def f(x):
...     x1, x2, x3 = x
...     return [x1, 5*x3, 4*x2**2 - 2*x3, x3*np.sin(x1)]

Die tatsächliche Jacobi-Matrix ist gegeben durch

>>> def df(x):
...         x1, x2, x3 = x
...         one = np.ones_like(x1)
...         return [[one, 0*one, 0*one],
...                 [0*one, 0*one, 5*one],
...                 [0*one, 8*x2, -2*one],
...                 [x3*np.cos(x1), 0*one, np.sin(x1)]]

Auswertung der Jacobi-Matrix an einem beliebigen Punkt.

>>> rng = np.random.default_rng()
>>> x = rng.random(size=3)
>>> res = jacobian(f, x)
>>> ref = df(x)
>>> res.df.shape == (4, 3)
True
>>> np.allclose(res.df, ref)
True

Auswertung der Jacobi-Matrix an 10 beliebigen Punkten in einem einzigen Aufruf.

>>> x = rng.random(size=(3, 10))
>>> res = jacobian(f, x)
>>> ref = df(x)
>>> res.df.shape == (4, 3, 10)
True
>>> np.allclose(res.df, ref)
True