Emily Boudreaux
6b57738330
Note for now much of the docs is LLM written. This was done to save time and focus on code development. The docs have been LOOSLEY reviewed. However, the code itself has been either fully written by hand or fully reviewed. Therefore, the docs should at the moment be seen as a loose resource rather than authoratiative (and this is on top of the general ability for docs to drift)
271 lines
13 KiB
Groff
271 lines
13 KiB
Groff
.TH "serif::equations::AngularMomentumConstraint" 3 "Version v0.0.1a" "SERiF" \" -*- nroff -*-
|
||
.ad l
|
||
.nh
|
||
.SH NAME
|
||
serif::equations::AngularMomentumConstraint \- Angular momentum constraint equation, which enforces a global constraint on the total angular momentum of a system\&.
|
||
|
||
.SH SYNOPSIS
|
||
.br
|
||
.PP
|
||
.PP
|
||
\fR#include <angular_momentum\&.hpp>\fP
|
||
.PP
|
||
Inherits \fBserif::equations::Contribution< discretization::forms::Operand< discretization::blocks::rotation::angular_velocity > >\fP\&.
|
||
.SS "Public Types"
|
||
|
||
.in +1c
|
||
.ti -1c
|
||
.RI "using \fBDensity\fP = \fBdiscretization::blocks::density::mass\fP"
|
||
.br
|
||
.ti -1c
|
||
.RI "using \fBResidualQuantity\fP = \fBdimensions::AngularMomentum\fP"
|
||
.br
|
||
.ti -1c
|
||
.RI "using \fBAngularVelocity\fP = \fBdiscretization::blocks::rotation::angular_velocity\fP"
|
||
.br
|
||
.ti -1c
|
||
.RI "using \fBDensityValue\fP = \fBdiscretization::forms::Operand\fP<\fBDensity\fP>"
|
||
.br
|
||
.ti -1c
|
||
.RI "using \fBAngularVelocityValue\fP = \fBdiscretization::forms::Operand\fP<\fBAngularVelocity\fP>"
|
||
.br
|
||
.ti -1c
|
||
.RI "using \fBOperands\fP = \fButils::types::TypeList\fP<\fBDensityValue\fP, \fBAngularVelocityValue\fP>"
|
||
.br
|
||
.in -1c
|
||
|
||
Public Types inherited from \fBserif::equations::Contribution< discretization::forms::Operand< discretization::blocks::rotation::angular_velocity > >\fP
|
||
.in +1c
|
||
.ti -1c
|
||
.RI "using \fBTest\fP"
|
||
.br
|
||
.RI "The test type of the contribution\&. "
|
||
.ti -1c
|
||
.RI "using \fBTestOperand\fP"
|
||
.br
|
||
.RI "The operand type of the contribution (associating a test function and a term) "
|
||
.ti -1c
|
||
.RI "using \fBSupport\fP"
|
||
.br
|
||
.RI "The domain support of the contribution (which then boils down to the dofs which are supported by the term on that test function) "
|
||
.in -1c
|
||
.SS "Public Member Functions"
|
||
|
||
.in +1c
|
||
.ti -1c
|
||
.RI "\fBAngularMomentumConstraint\fP (const double target_axial_angular_momentum, const \fBRigidRotation::Vector\fP &rotation_axis={0\&.0, 0\&.0, 1\&.0}, const \fBRigidRotation::Vector\fP &axis_origin={})"
|
||
.br
|
||
.RI "Prescribe Jₜ ≥ 0 and the axis through rₐ; Ω remains an unknown and may be signed in trial states\&. "
|
||
.ti -1c
|
||
.RI "\fBPointLinearization\fP< \fBOperands\fP > \fBevaluate\fP (const \fBEquationPoint\fP< \fBOperands\fP > &point) const"
|
||
.br
|
||
.RI "Evaluate the angular-momentum constraints point-wise integrand and its partial derivatives\&. "
|
||
.ti -1c
|
||
.RI "double \fBresidual_offset\fP () const"
|
||
.br
|
||
.RI "Return the residual offset for the angular-momentum constraint\&. "
|
||
.ti -1c
|
||
.RI "const \fBRigidRotation\fP & \fBrotation\fP () const noexcept"
|
||
.br
|
||
.RI "Inspect the physical rotation axis and origin\&. "
|
||
.in -1c
|
||
.SS "Static Public Member Functions"
|
||
|
||
.in +1c
|
||
.ti -1c
|
||
.RI "static int \fBadditional_order\fP (\fBDensityValue\fP, int position_order)"
|
||
.br
|
||
.RI "Return the additional quadrature degree for the density coupling\&. "
|
||
.ti -1c
|
||
.RI "static int \fBadditional_order\fP (\fBAngularVelocityValue\fP, int position_order)"
|
||
.br
|
||
.RI "Return the additional quadrature degree for the angular-velocity coupling\&. "
|
||
.ti -1c
|
||
.RI "static double \fBvalidation_integrand\fP (const \fBEquationPoint\fP< \fBOperands\fP > &, const \fBPointLinearization\fP< \fBOperands\fP > &physics)"
|
||
.br
|
||
.RI "Return the already computed inertia density, $\rho s^{2}$, for validation\&. "
|
||
.ti -1c
|
||
.RI "static void \fBvalidate_integral\fP (const double axial_moment_of_inertia)"
|
||
.br
|
||
.RI "Require the integrated axial moment of inertia to be finite and nonnegative\&. "
|
||
.in -1c
|
||
.SS "Static Public Attributes"
|
||
|
||
.in +1c
|
||
.ti -1c
|
||
.RI "static constexpr std::string_view \fBname\fP = 'angular momentum'"
|
||
.br
|
||
.in -1c
|
||
.SS "Private Attributes"
|
||
|
||
.in +1c
|
||
.ti -1c
|
||
.RI "double \fBm_target_axial_angular_momentum\fP"
|
||
.br
|
||
.RI "The prescribed total angular momentum along the rotation axis, $ J_{\text{target}} \geq 0 $\&. "
|
||
.ti -1c
|
||
.RI "\fBRigidRotation\fP \fBm_unit_rotation\fP"
|
||
.br
|
||
.RI "The unit rotation, storing the normalized axis and its origin, used to compute $s^{2}$ and its gradient\&. "
|
||
.in -1c
|
||
.SH "Detailed Description"
|
||
.PP
|
||
Angular momentum constraint equation, which enforces a global constraint on the total angular momentum of a system\&.
|
||
|
||
The point-wise integrand is given by $ j_\parallel = \rho \Omega s^2$, where $s^2 = |\hat{n} × (r − r_{c})|^2$ is the cylindrical radius squared, and $\hat{n}$ is the unit rotation axis\&. The solver will integrate this over the domain and compare it to the target angular momentum to enforce the constraint\&.
|
||
|
||
.PP
|
||
Use this equation in conjunction with a \fBRigidRotation\fP object to constrain the angular momentum of a system to some fixed value\&. Note that this constraint is weakly applied and therefore should be checked for convergence in the final solution\&.
|
||
|
||
.PP
|
||
\fBEquation\fP \fBContributions\fP
|
||
.PD 0
|
||
.IP "\(bu" 2
|
||
Residuals to the global angular momentum
|
||
.PP
|
||
|
||
.SH "Member Typedef Documentation"
|
||
.PP
|
||
.SS "using \fBserif::equations::AngularMomentumConstraint::AngularVelocity\fP = \fBdiscretization::blocks::rotation::angular_velocity\fP"
|
||
|
||
.SS "using \fBserif::equations::AngularMomentumConstraint::AngularVelocityValue\fP = \fBdiscretization::forms::Operand\fP<\fBAngularVelocity\fP>"
|
||
|
||
.SS "using \fBserif::equations::AngularMomentumConstraint::Density\fP = \fBdiscretization::blocks::density::mass\fP"
|
||
|
||
.SS "using \fBserif::equations::AngularMomentumConstraint::DensityValue\fP = \fBdiscretization::forms::Operand\fP<\fBDensity\fP>"
|
||
|
||
.SS "using \fBserif::equations::AngularMomentumConstraint::Operands\fP = \fButils::types::TypeList\fP<\fBDensityValue\fP, \fBAngularVelocityValue\fP>"
|
||
|
||
.SS "using \fBserif::equations::AngularMomentumConstraint::ResidualQuantity\fP = \fBdimensions::AngularMomentum\fP"
|
||
|
||
.SH "Constructor & Destructor Documentation"
|
||
.PP
|
||
.SS "serif::equations::AngularMomentumConstraint::AngularMomentumConstraint (const double target_axial_angular_momentum, const \fBRigidRotation::Vector\fP & rotation_axis = \fR{0\&.0, 0\&.0, 1\&.0}\fP, const \fBRigidRotation::Vector\fP & axis_origin = \fR{}\fP)\fR [inline]\fP, \fR [explicit]\fP"
|
||
|
||
.PP
|
||
Prescribe Jₜ ≥ 0 and the axis through rₐ; Ω remains an unknown and may be signed in trial states\&.
|
||
.SH "Member Function Documentation"
|
||
.PP
|
||
.SS "static int serif::equations::AngularMomentumConstraint::additional_order (\fBAngularVelocityValue\fP , int position_order)\fR [inline]\fP, \fR [static]\fP, \fR [nodiscard]\fP"
|
||
|
||
.PP
|
||
Return the additional quadrature degree for the angular-velocity coupling\&. At fixed density and position, $\delta j_{\parallel} = \rho s^{2}\delta \Omega$\&. The angular-velocity trial function is spatially constant\&. The remaining coefficient $\rho s^{2}$ has polynomial degree at most $p_{\rho} + 2p_{r}$\&.
|
||
|
||
.PP
|
||
\fBParameters\fP
|
||
.RS 4
|
||
\fIposition_order\fP Polynomial degree bound for physical position expressed in reference-element coordinates\&.
|
||
.RE
|
||
.PP
|
||
\fBReturns\fP
|
||
.RS 4
|
||
The coefficient degree bound $p_{\rho} + 2p_{r}$, excluding the geometry weight\&.
|
||
.RE
|
||
.PP
|
||
|
||
.SS "static int serif::equations::AngularMomentumConstraint::additional_order (\fBDensityValue\fP , int position_order)\fR [inline]\fP, \fR [static]\fP, \fR [nodiscard]\fP"
|
||
|
||
.PP
|
||
Return the additional quadrature degree for the density coupling\&. At fixed position and angular velocity, $\delta j_{\parallel} = \Omega s^{2} \delta \rho$\&. The backend already counts the density trial degree $p_{\rho}$\&. Since $\Omega$ is spatially constant and $s^{2}$ is quadratic in position, the remaining coefficient $\Omega s^{2}$ has polynomial degree at most $2p_{r}$\&.
|
||
|
||
.PP
|
||
\fBParameters\fP
|
||
.RS 4
|
||
\fIposition_order\fP Polynomial degree bound for physical position expressed in reference-element coordinates\&.
|
||
.RE
|
||
.PP
|
||
\fBReturns\fP
|
||
.RS 4
|
||
The coefficient degree bound $2p_{r}$, excluding the geometry weight\&.
|
||
.RE
|
||
.PP
|
||
|
||
.SS "\fBPointLinearization\fP< \fBOperands\fP > serif::equations::AngularMomentumConstraint::evaluate (const \fBEquationPoint\fP< \fBOperands\fP > & point) const\fR [inline]\fP, \fR [nodiscard]\fP"
|
||
|
||
.PP
|
||
Evaluate the angular-momentum constraints point-wise integrand and its partial derivatives\&. The point-wise integrand is calculated as $ j_\parallel = \rho \Omega s^2$ where $s^2 = |\hat{n} × (r − r_{c})|^2$ is the cylindrical radius squared\&. The partial derivatives are calculated as:
|
||
.IP "\(bu" 2
|
||
$ \frac{\partial j_\parallel}{\partial \rho} = \Omega s^2$
|
||
.IP "\(bu" 2
|
||
$ \frac{\partial j_\parallel}{\partial \Omega} = \rho s^2$
|
||
.IP "\(bu" 2
|
||
$ \nabla j_\parallel = 2 \rho\Omega\lambda_{\perp}$ where $\lambda_{\perp} = \hat{n} × (r − r_{c})$ is the displacement perpendicular to the rotation axis\&.
|
||
.PP
|
||
|
||
.PP
|
||
\fBNote\fP
|
||
.RS 4
|
||
There is a subtly here which may trick the careful programmer up\&. Note that we set the residual to $R = \rho\Omega s^{2}$; rather that the more obvious choice of $R = \rho\Omega s^{2} - J_{\text{target}}$\&. The important thing to remember is that these equations are evaluated point-wise\&. Put another way if you were to evaluate the physical residual as the local angular momentum contribution - the global angular momentum at some single point the meaning would be ill-defined\&. There is no local angular momentum constraint, we only have a global one\&. What we actually need to do is give the backend someone of knowing what the total angular momentum of the system is\&. Therefore what we return here is integrand of the residual which is then automatically integrated over the volume by the backend (so when integrating all these point wise contributions over the domain the backend will get the total angular momentum)\&. Further, if an equation supplies the method \fBresidual_offset()\fP (as this one does) then the backend will automatically subtract that from the integrated residual (e\&.g\&. the backend has computed the total angular momentum and then subtracts residual_offset to find the actual residual, which will approach 0 as the total angular momentum approaches the supplied value)\&. A heuristic which may be useful to keep in mind is that global constraints should supply a residual offset whereas local equations often will not need to\&.
|
||
.RE
|
||
.PP
|
||
\fBParameters\fP
|
||
.RS 4
|
||
\fIpoint\fP The point at which to evaluate the integrand and its partial derivatives\&.
|
||
.RE
|
||
.PP
|
||
|
||
.SS "double serif::equations::AngularMomentumConstraint::residual_offset () const\fR [inline]\fP, \fR [nodiscard]\fP"
|
||
|
||
.PP
|
||
Return the residual offset for the angular-momentum constraint\&. The backend integrates the point-wise residual contributions over the domain\&. The global constraint is satisfied when the total angular momentum equals the target value\&. Therefore we subtract the target from the integrated residual to get the actual residual\&.
|
||
|
||
.PP
|
||
\fBNote\fP
|
||
.RS 4
|
||
The backend automatically looks for this method and calls it if it exists\&.
|
||
.RE
|
||
.PP
|
||
\fBReturns\fP
|
||
.RS 4
|
||
The negative of the target axial angular momentum, $-J_{\\text{target}}$\&.
|
||
.RE
|
||
.PP
|
||
|
||
.SS "const \fBRigidRotation\fP & serif::equations::AngularMomentumConstraint::rotation () const\fR [inline]\fP, \fR [nodiscard]\fP, \fR [noexcept]\fP"
|
||
|
||
.PP
|
||
Inspect the physical rotation axis and origin\&.
|
||
.SS "static void serif::equations::AngularMomentumConstraint::validate_integral (const double axial_moment_of_inertia)\fR [inline]\fP, \fR [static]\fP"
|
||
|
||
.PP
|
||
Require the integrated axial moment of inertia to be finite and nonnegative\&. The operator backend supplies the integral of \fBvalidation_integrand()\fP\&. Failure rejects preparation of the candidate state\&. Passing this check does not establish nonnegative density everywhere or satisfaction of $\Omega I_{\parallel} - J_{\mathrm{target}} = 0$\&.
|
||
|
||
.PP
|
||
\fBParameters\fP
|
||
.RS 4
|
||
\fIaxial_moment_of_inertia\fP The integrated axial moment of inertia, $I_{\parallel} = \int_\star \rho s^{2}\,dV$\&.
|
||
.RE
|
||
.PP
|
||
|
||
.SS "static double serif::equations::AngularMomentumConstraint::validation_integrand (const \fBEquationPoint\fP< \fBOperands\fP > & , const \fBPointLinearization\fP< \fBOperands\fP > & physics)\fR [inline]\fP, \fR [static]\fP, \fR [nodiscard]\fP"
|
||
|
||
.PP
|
||
Return the already computed inertia density, $\rho s^{2}$, for validation\&. When an equation provides \fBvalidate_integral()\fP, the operator backend integrates this quantity over the equation's domain and passes the result to that method\&. Here the integral is the axial moment of inertia, $I_{\parallel} = \int_\star \rho s^{2}\,dV$\&.
|
||
|
||
.PP
|
||
The equation defines both the quantity to integrate and its admissibility requirements; the backend performs the integration\&. Here we require finite, nonnegative inertia as a necessary, but not sufficient, condition for a physically admissible mass distribution\&.
|
||
|
||
.PP
|
||
\fBParameters\fP
|
||
.RS 4
|
||
\fIphysics\fP The point-wise linearization, whose angular-velocity derivative already contains $\partial j_{\parallel}/\partial\Omega = \rho s^{2}$\&.
|
||
.RE
|
||
.PP
|
||
|
||
.SH "Member Data Documentation"
|
||
.PP
|
||
.SS "double serif::equations::AngularMomentumConstraint::m_target_axial_angular_momentum\fR [private]\fP"
|
||
|
||
.PP
|
||
The prescribed total angular momentum along the rotation axis, $ J_{\text{target}} \geq 0 $\&.
|
||
.SS "\fBRigidRotation\fP serif::equations::AngularMomentumConstraint::m_unit_rotation\fR [private]\fP"
|
||
|
||
.PP
|
||
The unit rotation, storing the normalized axis and its origin, used to compute $s^{2}$ and its gradient\&.
|
||
.SS "std::string_view serif::equations::AngularMomentumConstraint::name = 'angular momentum'\fR [static]\fP, \fR [constexpr]\fP"
|
||
|
||
|
||
.SH "Author"
|
||
.PP
|
||
Generated automatically by Doxygen for SERiF from the source code\&.
|