Opened 3 years ago
Closed 3 years ago
#24444 closed enhancement (fixed)
Deprecate CoordinatePatch and DifferentialForm to keep a single version of differential forms
Reported by:  egourgoulhon  Owned by:  

Priority:  major  Milestone:  sage8.2 
Component:  geometry  Keywords:  manifolds, differential forms 
Cc:  jvkersch, tscrim, niles, jason, mhampton  Merged in:  
Authors:  Eric Gourgoulhon  Reviewers:  Travis Scrimshaw 
Report Upstream:  N/A  Work issues:  
Branch:  520ee73 (Commits, GitHub, GitLab)  Commit:  520ee7315fbd2dfddd62f2add42e2f7e012b518b 
Dependencies:  Stopgaps: 
Description (last modified by )
At present differential forms are dealt with by different and incompatible parts of Sage: the CoordinatePatch version (implemented in #9650) and the manifold version (implemented in #18843).
All functionalities of the CoordinatePatch version (like wedge product and exterior derivative) are implemented in the manifold version, but the manifold one is more recent and provides more functionalities, like
 better display capabilities
 changing the coordinates (the CoordinatePatch version assumes a fixed coordinate system)
 evaluating the Lie derivative with respect to a vector field
 performing the interior product with a pvector
 evaluating the Hodge dual with respect to a metric
It is also more flexible:
 the indices may be chosen to start from 1 (or any other value) instead of 0
 one may use index notation with Einstein convention of summation on repeated indices
 the base ring is not limited to the Symbolic Ring.
As this ask.sagemath question reveals, keeping both versions is confusing and the current ticket is devoted to deprecate the CoordinatePatch version.
Change History (10)
comment:1 Changed 3 years ago by
comment:2 Changed 3 years ago by
Examples of functionalities avalaible only in the manifold version
The capability to access directly to the coordinate basis 1forms:
sage: X.coframe() Coordinate coframe (U, (dx,dy,dz)) sage: dx = X.coframe()[0] sage: dy = X.coframe()[1] sage: a = sin(z)*dx.wedge(dy) sage: a.display() sin(z) dx/\dy
The interior product with a vector field:
sage: v = U.vector_field('v') sage: v[:] = (y, z, x^2) sage: v.interior_product(f) 1form i_v f on the 3dimensional differentiable manifold U sage: v.interior_product(f).display() i_v f = x*z*sin(z) dx + (x^2*y*z  x*y*sin(z)) dy + y*z^2 dz
The Lie derivative with respect to a vector field:
sage: f.lie_derivative(v) 2form on the 3dimensional differentiable manifold U sage: f.lie_derivative(v).display() (x^3*cos(z)  2*x*y*z  y*sin(z)) dx/\dy + x*sin(z) dx/\dz + (x^2*y + z^2) dy/\dz
As an illustration, we may check that Cartan's identity Lie_{v} f = d(i_{v} f) + i_{v} df holds:
sage: f.lie_derivative(v) == (v.interior_product(f)).exterior_derivative() + \ ....: v.interior_product(f.exterior_derivative()) True
Computing the Hodge dual with respect to a given metric:
sage: h = U.metric('h') sage: h[0,0] = 1+y^2 sage: h[1,1] = 1+z^2 sage: h[2,2] = 1+x^2 sage: h.display() h = (y^2 + 1) dx*dx + (z^2 + 1) dy*dy + (x^2 + 1) dz*dz sage: f.hodge_dual(h) 1form *f on the 3dimensional differentiable manifold U sage: f.hodge_dual(h).display() *f = sqrt(y^2 + 1)*y*z/(sqrt(x^2 + 1)*sqrt(z^2 + 1)) dx + sqrt(x^2 + 1)*x*sin(z)/(sqrt(y^2 + 1)*sqrt(z^2 + 1)) dz
Computing new components under a change of coordinates:
sage: X2.<u,v,w> = U.chart() sage: X_to_X2 = X.transition_map(X2, [y+z, z+x, x+y]) sage: X_to_X2.inverse() Change of coordinates from Chart (U, (u, v, w)) to Chart (U, (x, y, z)) sage: g.display() # the default for g.display(X.frame(), X) g = y^2 dx  z dy + (2*x  y) dz sage: g.display(X2.frame(), X2) g = (1/8*u^2 + 1/4*(u + 2)*v  1/8*v^2  1/4*(u  v  2)*w  1/8*w^2  u) du + (1/8*u^2  1/4*(u  4)*v + 1/8*v^2 + 1/4*(u  v)*w + 1/8*w^2  1/2*u) dv + (1/8*u^2  1/4*(u + 4)*v + 1/8*v^2 + 1/4*(u  v)*w + 1/8*w^2 + 1/2*u) dw
Using the function display_comp
, which is more convenient for lengthy expressions:
sage: g.display_comp() # the default for g.display_comp(X.frame(), X) g_x = y^2 g_y = z g_z = 2*x  y sage: g.display_comp(X2.frame(), X2) g_u = 1/8*u^2 + 1/4*(u + 2)*v  1/8*v^2  1/4*(u  v  2)*w  1/8*w^2  u g_v = 1/8*u^2  1/4*(u  4)*v + 1/8*v^2 + 1/4*(u  v)*w + 1/8*w^2  1/2*u g_w = 1/8*u^2  1/4*(u + 4)*v + 1/8*v^2 + 1/4*(u  v)*w + 1/8*w^2 + 1/2*u
comment:3 Changed 3 years ago by
Regarding the code, both versions share the same trick for the storage of components: a dictionary whose keys are the indices, limited to nonredundant ones (i.e. only the components that cannot be deduced by antisymmetry). For the CoordinatePatch version and the same example as above, we have
sage: f x*sin(z)*dx/\dy + y*z*dy/\dz sage: f._components {(0, 1): x*sin(z), (1, 2): y*z} sage: f[1,0] # a component not stored but deduced by antisymmetry x*sin(z)
while for the manifold version, we have
sage: f.display() f = x*sin(z) dx/\dy + y*z dy/\dz sage: f.components() Fully antisymmetric 2indices components w.r.t. Coordinate frame (U, (d/dx,d/dy,d/dz)) sage: f.components()._comp {(0, 1): Scalar field on the 3dimensional differentiable manifold U, (1, 2): Scalar field on the 3dimensional differentiable manifold U} sage: for i, c in f.components()._comp.items(): ....: print("{}: {}".format(i, c.expr())) ....: (0, 1): x*sin(z) (1, 2): y*z sage: f[1,0] # a component not stored but deduced by antisymmetry x*sin(z)
Actually, the storage method of the CoordinatePatch version inspired the manifold one ;), as acknowledged in the AUTHORS section of the documentation.
comment:4 Changed 3 years ago by
 Description modified (diff)
comment:5 Changed 3 years ago by
 Description modified (diff)
comment:6 Changed 3 years ago by
 Branch set to public/manifolds/deprecate_DifferentialForm24444
 Cc jvkersch tscrim niles jason mhampton added
 Commit set to 520ee7315fbd2dfddd62f2add42e2f7e012b518b
New commits:
520ee73  Deprecate CoordinatePatch and DifferentialForm (trac #24444)

comment:7 Changed 3 years ago by
 Status changed from new to needs_review
The deprecation is implemented in the attached branch. Please review.
comment:8 followup: ↓ 9 Changed 3 years ago by
 Reviewers set to Travis Scrimshaw
 Status changed from needs_review to positive_review
 Type changed from defect to enhancement
LGTM.
comment:9 in reply to: ↑ 8 Changed 3 years ago by
Thanks for the review!
comment:10 Changed 3 years ago by
 Branch changed from public/manifolds/deprecate_DifferentialForm24444 to 520ee7315fbd2dfddd62f2add42e2f7e012b518b
 Resolution set to fixed
 Status changed from positive_review to closed
Illustration of similarities and differences
Let us declare a differential form of degree 2 with the CoordinatePatch version:
To perform the same thing with the manifold version, one should write (using a different Sage session to avoid any confusion):
Let us introduce another differential form, as a 1form; in the CoordinatePatch version:
In the manifold version, one may use the shortcut notation
g[:]
to set the components ofg
:The wedge product of
f
byg
is obtained in the same way in both methods: for CoordinatePatch:while for the manifold version:
The exterior derivative is computed via the method
diff()
in the CoordinatePatch version:and via the method
exterior_derivative()
in the manifold version:A shortcut is provided by the function
xder
, to be used as the operator d to compute df:A difference regards the parents: in the CoordinatePatch version, the 2form
f
and the 1formg
have the same parent, which is the graded algebra Omega(U) of all differential forms defined on U, and declared asF = DifferentialForms(U)
at the beginning of the session:In the manifold case, the parent of
f
is the set Omega^{2}(U) of 2forms on U, which is considered as a free module of rank 3 on the algebra C^{oo}(U) of scalar fields on U, while the parent ofg
is the set Omega^{1}(U) of 1forms on U, which is considered as another free module of rank 3 on C^{oo}(U):