# 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, 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

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, 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

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
```

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

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
>>> 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
```

## vector_integrate#

sympy.vector.integrals.vector_integrate(field, *region)[source]#

Compute the integral of a vector/scalar field over a a region or a set of parameters.

Examples

```>>> from sympy.vector import CoordSys3D, ParametricRegion, vector_integrate
>>> from sympy.abc import x, y, t
>>> C = CoordSys3D('C')
```
```>>> region = ParametricRegion((t, t**2), (t, 1, 5))
>>> vector_integrate(C.x*C.i, region)
12
```

Integrals over some objects of geometry module can also be calculated.

```>>> from sympy.geometry import Point, Circle, Triangle
>>> c = Circle(Point(0, 2), 5)
>>> vector_integrate(C.x**2 + C.y**2, c)
290*pi
>>> triangle = Triangle(Point(-2, 3), Point(2, 3), Point(0, 5))
>>> vector_integrate(3*C.x**2*C.y*C.i + C.j, triangle)
-8
```

Integrals over some simple implicit regions can be computed. But in most cases, it takes too long to compute over them. This is due to the expressions of parametric representation becoming large.

```>>> from sympy.vector import ImplicitRegion
>>> c2 = ImplicitRegion((x, y), (x - 2)**2 + (y - 1)**2 - 9)
>>> vector_integrate(1, c2)
6*pi
```

Integral of fields with respect to base scalars:

```>>> vector_integrate(12*C.y**3, (C.y, 1, 3))
240
>>> vector_integrate(C.x**2*C.z, C.x)
C.x**3*C.z/3
>>> vector_integrate(C.x*C.i - C.y*C.k, C.x)
(Integral(C.x, C.x))*C.i + (Integral(-C.y, C.x))*C.k
>>> _.doit()
C.x**2/2*C.i + (-C.x*C.y)*C.k
```