# Essential Functions in sympy.vector (docstrings)¶

## matrix_to_vector¶

sympy.vector.matrix_to_vector(matrix, system)[source]

Converts a vector in matrix form to a Vector instance.

It is assumed that the elements of the Matrix represent the measure numbers of the components of the vector along basis vectors of ‘system’.

Parameters

matrix : SymPy Matrix, Dimensions: (3, 1)

The matrix to be converted to a vector

system : CoordSys3D

The coordinate system the vector is to be defined in

Examples

>>> from sympy import ImmutableMatrix as Matrix
>>> m = Matrix([1, 2, 3])
>>> from sympy.vector import CoordSys3D, matrix_to_vector
>>> C = CoordSys3D('C')
>>> v = matrix_to_vector(m, C)
>>> v
C.i + 2*C.j + 3*C.k
>>> v.to_matrix(C) == m
True


## express¶

sympy.vector.express(expr, system, system2=None, variables=False)[source]

Global function for ‘express’ functionality.

Re-expresses a Vector, Dyadic or scalar(sympyfiable) in the given coordinate system.

If ‘variables’ is True, then the coordinate variables (base scalars) of other coordinate systems present in the vector/scalar field or dyadic are also substituted in terms of the base scalars of the given system.

Parameters

The expression to re-express in CoordSys3D ‘system’

system: CoordSys3D

The coordinate system the expr is to be expressed in

system2: CoordSys3D

The other coordinate system required for re-expression (only for a Dyadic Expr)

variables : boolean

Specifies whether to substitute the coordinate variables present in expr, in terms of those of parameter system

Examples

>>> from sympy.vector import CoordSys3D
>>> from sympy import Symbol, cos, sin
>>> N = CoordSys3D('N')
>>> q = Symbol('q')
>>> B = N.orient_new_axis('B', q, N.k)
>>> from sympy.vector import express
>>> express(B.i, N)
(cos(q))*N.i + (sin(q))*N.j
>>> express(N.x, B, variables=True)
B.x*cos(q) - B.y*sin(q)
>>> d = N.i.outer(N.i)
>>> express(d, B, N) == (cos(q))*(B.i|N.i) + (-sin(q))*(B.j|N.i)
True


## curl¶

sympy.vector.curl(vect, coord_sys=None, doit=True)[source]

Returns the curl of a vector field computed wrt the base scalars of the given coordinate system.

Parameters

vect : Vector

The vector operand

coord_sys : CoordSys3D

The coordinate system to calculate the gradient in. Deprecated since version 1.1

doit : bool

If True, the result is returned after calling .doit() on each component. Else, the returned expression contains Derivative instances

Examples

>>> from sympy.vector import CoordSys3D, curl
>>> R = CoordSys3D('R')
>>> v1 = R.y*R.z*R.i + R.x*R.z*R.j + R.x*R.y*R.k
>>> curl(v1)
0
>>> v2 = R.x*R.y*R.z*R.i
>>> curl(v2)
R.x*R.y*R.j + (-R.x*R.z)*R.k


## divergence¶

sympy.vector.divergence(vect, coord_sys=None, doit=True)[source]

Returns the divergence of a vector field computed wrt the base scalars of the given coordinate system.

Parameters

vector : Vector

The vector operand

coord_sys : CoordSys3D

The coordinate system to calculate the gradient in Deprecated since version 1.1

doit : bool

If True, the result is returned after calling .doit() on each component. Else, the returned expression contains Derivative instances

Examples

>>> from sympy.vector import CoordSys3D, divergence
>>> R = CoordSys3D('R')
>>> v1 = R.x*R.y*R.z * (R.i+R.j+R.k)

>>> divergence(v1)
R.x*R.y + R.x*R.z + R.y*R.z
>>> v2 = 2*R.y*R.z*R.j
>>> divergence(v2)
2*R.z


sympy.vector.gradient(scalar_field, coord_sys=None, doit=True)[source]

Returns the vector gradient of a scalar field computed wrt the base scalars of the given coordinate system.

Parameters

scalar_field : SymPy Expr

The scalar field to compute the gradient of

coord_sys : CoordSys3D

The coordinate system to calculate the gradient in Deprecated since version 1.1

doit : bool

If True, the result is returned after calling .doit() on each component. Else, the returned expression contains Derivative instances

Examples

>>> from sympy.vector import CoordSys3D, gradient
>>> R = CoordSys3D('R')
>>> s1 = R.x*R.y*R.z
R.y*R.z*R.i + R.x*R.z*R.j + R.x*R.y*R.k
>>> s2 = 5*R.x**2*R.z
10*R.x*R.z*R.i + 5*R.x**2*R.k


## is_conservative¶

sympy.vector.is_conservative(field)[source]

Checks if a field is conservative.

Parameters

field : Vector

The field to check for conservative property

Examples

>>> from sympy.vector import CoordSys3D
>>> from sympy.vector import is_conservative
>>> R = CoordSys3D('R')
>>> is_conservative(R.y*R.z*R.i + R.x*R.z*R.j + R.x*R.y*R.k)
True
>>> is_conservative(R.z*R.j)
False


## is_solenoidal¶

sympy.vector.is_solenoidal(field)[source]

Checks if a field is solenoidal.

Parameters

field : Vector

The field to check for solenoidal property

Examples

>>> from sympy.vector import CoordSys3D
>>> from sympy.vector import is_solenoidal
>>> R = CoordSys3D('R')
>>> is_solenoidal(R.y*R.z*R.i + R.x*R.z*R.j + R.x*R.y*R.k)
True
>>> is_solenoidal(R.y * R.j)
False


## scalar_potential¶

sympy.vector.scalar_potential(field, coord_sys)[source]

Returns the scalar potential function of a field in a given coordinate system (without the added integration constant).

Parameters

field : Vector

The vector field whose scalar potential function is to be calculated

coord_sys : CoordSys3D

The coordinate system to do the calculation in

Examples

>>> from sympy.vector import CoordSys3D
>>> from sympy.vector import scalar_potential, gradient
>>> R = CoordSys3D('R')
>>> scalar_potential(R.k, R) == R.z
True
>>> scalar_field = 2*R.x**2*R.y*R.z
2*R.x**2*R.y*R.z


## scalar_potential_difference¶

sympy.vector.scalar_potential_difference(field, coord_sys, point1, point2)[source]

Returns the scalar potential difference between two points in a certain coordinate system, wrt a given field.

If a scalar field is provided, its values at the two points are considered. If a conservative vector field is provided, the values of its scalar potential function at the two points are used.

Returns (potential at point2) - (potential at point1)

The position vectors of the two Points are calculated wrt the origin of the coordinate system provided.

Parameters

field : Vector/Expr

The field to calculate wrt

coord_sys : CoordSys3D

The coordinate system to do the calculations in

point1 : Point

The initial Point in given coordinate system

position2 : Point

The second Point in the given coordinate system

Examples

>>> from sympy.vector import CoordSys3D, Point
>>> from sympy.vector import scalar_potential_difference
>>> R = CoordSys3D('R')
>>> P = R.origin.locate_new('P', R.x*R.i + R.y*R.j + R.z*R.k)
>>> vectfield = 4*R.x*R.y*R.i + 2*R.x**2*R.j
>>> scalar_potential_difference(vectfield, R, R.origin, P)
2*R.x**2*R.y
>>> Q = R.origin.locate_new('O', 3*R.i + R.j + 2*R.k)
>>> scalar_potential_difference(vectfield, R, P, Q)
-2*R.x**2*R.y + 18