Leonardo/it.grypho.scala.leonardo/it.grypho.scala.leonardo.vector

it.grypho.scala.leonardo.vector

Vector calculus — scalar and vector fields over an ordered coordinate tuple.

The differential operators grad, div, curl and laplacian, plus the multivariate derivative surface jacobian and hessian. Imports core + scalar + matrix, which is acyclic: nothing imports this package but parser. No equation import is needed — every operator returns a matrix or a scalar, never a relation.

A vector field is an n×1 matrix._Matrix, not a new carrier. The symbolic matrix already holds arbitrary _Expression cells, so every existing matrix operation applies to a field unchanged, and derive already distributes over it element-wise (_Matrix is _ElementWise). This is the argument that kept distributions out of a bespoke container elsewhere in this library: a new carrier is only worth it when something must read the value as one.

The operators are compositions of derive; the content here is the shape rules. Each one is a line of arithmetic over partial derivatives, so what the code actually spends its effort on is refusing the ill-shaped cases — a curl outside three dimensions, a component/coordinate count mismatch, a repeated coordinate. That is the rule that an analysis must describe what the library computes, applied to a domain where the wrong answer would look perfectly plausible.

The coordinate tuple is explicit and ordered, never inferred. grad(f) alone is meaningless: the order of the result's components has to come from somewhere, and reading it off freeVars would have to invent a convention (alphabetical? first-seen?) under which grad(x*y) and grad(y*x) could disagree. Every node therefore carries its Vector[_Variable].

Those variables follow the scalar._Taylor convention, not the binder convention: they appear free in the result — a gradient is a function of position — so they are excluded from children (so substitute cannot rewrite the coordinates the answer is phrased in) but are not binders in the _Derivative sense. _SolveSystem supplies only the list-shaped plumbing; _Taylor and domain._Domain supply the semantics.

Cartesian only for now (CoordinateSystem). The field ships from the start so the node shape is final and the curvilinear systems — cylindrical and spherical, via the general orthogonal curvilinear formulas — lands as an eval change and nothing else. Any other system stays symbolic rather than being answered with the Cartesian formula, which would be a confidently wrong result rather than an obviously missing one.

Attributes

Members list

Type members

Classlikes

The coordinate system a vector operator is evaluated in.

All three are orthogonal curvilinear, so a single set of formulas parameterised by the scale factors (Lamé coefficients) covers them — see _VectorOperator.scaleFactors. Writing the cylindrical and spherical operators out by hand would have put three definitions of each in the source, free to drift apart; there is one.

Cylindrical and Spherical are inherently three-dimensional, and the coordinates are identified by position, not by name — the user may call them anything:

Cylindrical — (r, θ, z): radial, azimuthal, axial.
Spherical — (r, θ, φ) with θ the polar angle (measured from the axis) and φ the azimuthal one. This is the physics convention; it cannot be inferred from the variable names, and choosing silently would make every spherical result wrong for half its readers, so it is stated here, in the cheat sheet and in the README.
SphericalMaths — the mathematics convention (r, θ, φ) with θ azimuthal and φ polar: the same geometry with the last two coordinates exchanged.

The difference between the two spherical cases is argument order, not naming. The operators read coords by position and never look at the spellings, so a reader who calls the polar angle φ but passes it second is already served by Spherical; SphericalMaths exists for those who pass it third.

Attributes

Supertypes: trait Enum

trait Serializable

trait Product

trait Equals

class Object

trait Matchable

class Any
Show all

curl(F, x, y, z) — the curl of a 3-D vector field, as a 3×1 column vector.

Three dimensions only. In 2-D the natural object is a scalar curl — a different result type, not a degenerate case of this one — and in higher dimensions the cross-product form does not exist at all. Every other arity is refused rather than guessed — the rule that an analysis must describe what the library actually computes.

Value parameters

coords: the three coordinates, in order
e: the vector field (3×1)
system: the coordinate system (only Cartesian evaluates)

Attributes

Supertypes: trait Serializable

trait Product

trait Equals

trait _VectorOperator

trait _Expression

class Object

trait Matchable

class Any
Show all

div(F, x, y, …) — the divergence of a vector field, a scalar.

Requires F to be an n×1 field with exactly one component per coordinate: div sums ∂Fᵢ/∂xᵢ, so a count mismatch has no meaning and stays symbolic.

Value parameters

coords: the ordered coordinate tuple
e: the vector field (n×1)
system: the coordinate system (only Cartesian evaluates)

Attributes

Supertypes: trait Serializable

trait Product

trait Equals

trait _VectorOperator

trait _Expression

class Object

trait Matchable

class Any
Show all

grad(f, x, y, …) — the gradient of a scalar field, as an n×1 column vector.

Value parameters

coords: the ordered coordinate tuple
e: the scalar field
system: the coordinate system (only Cartesian evaluates)

Attributes

Supertypes: trait Serializable

trait Product

trait Equals

trait _VectorOperator

trait _Expression

class Object

trait Matchable

class Any
Show all

hessian(f, x, y, …) — the n×n matrix of second partials, Hᵢⱼ = ∂²f/∂xᵢ∂xⱼ.

Symmetric for any field whose mixed partials commute (Clairaut), which the test suite pins rather than assumes.

Value parameters

coords: the ordered coordinate tuple
e: the scalar field
system: the coordinate system (only Cartesian evaluates)

Attributes

Supertypes: trait Serializable

trait Product

trait Equals

trait _VectorOperator

trait _Expression

class Object

trait Matchable

class Any
Show all

jacobian(F, x, y, …) — the m×n matrix of first partials, Jᵢⱼ = ∂Fᵢ/∂xⱼ.

Value parameters

coords: the n coordinates, in order
e: the vector field (m×1)
system: the coordinate system (only Cartesian evaluates)

Attributes

Supertypes: trait Serializable

trait Product

trait Equals

trait _VectorOperator

trait _Expression

class Object

trait Matchable

class Any
Show all

laplacian(f, x, y, …) — the Laplacian of a scalar field, a scalar.

Defined as div(grad(f)) rather than as its own sum of second derivatives, so the two can never disagree. That definition is why the curvilinear systems needed no change here: composing the curvilinear grad and div yields (1/J)·Σᵢ ∂/∂qᵢ (J/hᵢ² · ∂f/∂qᵢ), which is exactly the general orthogonal-curvilinear Laplacian — a formula written out separately would have been a second definition to keep in step, and this one cannot drift.

A vector argument stays symbolic, and now for a load-bearing reason rather than a cautious one: outside Cartesian coordinates the vector Laplacian is not the component-wise scalar Laplacian (it is grad(div F) − curl(curl F)), so answering it by mapping this scalar formula over the components would be wrong in exactly the systems the curvilinear systems add.

Value parameters

coords: the ordered coordinate tuple
e: the scalar field
system: the coordinate system (only Cartesian evaluates)

Attributes

Supertypes: trait Serializable

trait Product

trait Equals

trait _VectorOperator

trait _Expression

class Object

trait Matchable

class Any
Show all

Shared behaviour of the six vector-calculus operators.

Each carries the field or scalar e, the ordered coordinate tuple, and the coordinate system. The coordinates are excluded from children and carried through rebuild (the scalar._Taylor convention — see the package overview), so substitute cannot rewrite the variables the answer is phrased in.

Attributes

Supertypes: trait _Expression

class Object

trait Matchable

class Any
Known subtypes: class _Curl

class _Div

class _Grad

class _Hessian

class _Jacobian

class _Laplacian
Show all

In this article

Generated with