MeanField_SERiF/docs/man/man3/serif_discretization_forms_Operand.3

.TH "serif::discretization::forms::Operand< TermT, OperationT >" 3 "Version v0.0.1a" "SERiF" \" -*- nroff -*-
.ad l
.nh
.SH NAME
serif::discretization::forms::Operand< TermT, OperationT > \- Compile time representation of some operand\&. An operand associates a term to an operation type (e\&.g\&. the gradient of gravitational potential where gravitational potential is the term and gradient is the operation)\&.  

.SH SYNOPSIS
.br
.PP
.PP
\fR#include <operands\&.hpp>\fP
.SS "Public Types"

.in +1c
.ti -1c
.RI "using \fBterm_type\fP = TermT"
.br
.ti -1c
.RI "using \fBoperation_type\fP = OperationT"
.br
.in -1c
.SH "Detailed Description"
.PP 

.SS "template<blocks::Term TermT, IsOperation OperationT = Operation::Value>
.br
struct serif::discretization::forms::Operand< TermT, OperationT >"Compile time representation of some operand\&. An operand associates a term to an operation type (e\&.g\&. the gradient of gravitational potential where gravitational potential is the term and gradient is the operation)\&. 


.PP
\fBTemplate Parameters\fP
.RS 4
\fITermT\fP Term Type (e\&.g\&. gravitational potential, mass density) 
.br
\fIOperationT\fP The operation to associate to that term, must be one of the operations from \fBOperation\fP (enforced by satisfying \fBIsOperation\fP)\&.
.RE
.PP
\fBNote\fP
.RS 4
An operand does not know how to do anything\&. Like a lot of the other parts of SERiF at this level this is compile time metadata which allows the compiler to select the correct overloads, without runtime dispatch overhead, in order to run the correct computations\&. Do not be fooled into thinking that this actually has any computations buried within it\&.
.RE
.PP
As I say in the note this is a compile time representation of some metadata; however, because of that it may be challenging for a new developer to track where exactly this is used\&. Broadly this system is used so that a developer can inform the backend how to evaluate physical inputs and integrate point-wise contributions\&.

.PP
When used as the test operand of a Contribution, the operation applies to the test function\&. When used in a contribution's Operands list, it applies to a physical input field whose evaluated value is supplied to evaluate()\&.

.PP
Consider some scalar field $\lambda$ over the stellar domain which describes local point-wise residual contributions\&. A weak residual can be computed a number of ways; however, the most natural might be something like

.PP
\[R_i = \int_{\Omega_{\text{stellar}}} q_i \lambda\,dV
\approx \sum_{k=1}^{N_q} q_i(x_k)\lambda(x_k)W_k
\]
.PP
Here, $i$ identifies the test function and corresponding residual entry, while $k$ identifies a quadrature point\&. The weight $W_k$ includes both the quadrature weight and the geometric volume factor\&.

.PP
Or, for some vector field $\boldsymbol{\lambda}$ over the stellar domain which describes local point-wise residual contributions,

.PP
\[R_i = \int_{\Omega_{\text{stellar}}} \mathbf{v}_i\cdot\boldsymbol{\lambda}\,dV
\approx \sum_{k=1}^{N_q} \mathbf{v}_i(x_k)\cdot\boldsymbol{\lambda}(x_k)W_k
\]
.PP
However, a different operation on the test function may emerge from the weak-form derivation\&. Say, for example, you find that really you need the divergence of the test function paired with a scalar contribution $\lambda$, e\&.g\&.

.PP
\[R_i = \int_{\Omega_{\text{stellar}}} \left(\nabla\cdot\mathbf{v}_i\right)\lambda\,dV
\approx \sum_{k=1}^{N_q} \left(\nabla\cdot\mathbf{v}_i\right)(x_k)\lambda(x_k)W_k
\]
.PP
As there are a series of different, though effectively enumerable, options here, we can use a compile time tag to let the backend select, without runtime dispatch overhead, what operation needs to be applied to the test function\&. Evaluating that operation and performing the integration still require numerical work at runtime\&.

.PP
By default, if you do not specify an operation type (the second template parameter) then the operation type will default to \fBOperation::Value\fP, which seems to be the most common case, at least for this class of problems\&. In addition, the operand vocabulary includes the following tags, whose meanings when applied to test functions are:

.PP
.IP "\(bu" 2
\fBOperation::Gradient\fP ( $\int_{\Omega} \nabla q_i \cdot \boldsymbol{\lambda}\,dV$)
.IP "\(bu" 2
\fBOperation::Divergence\fP ( $\int_{\Omega} \left(\nabla\cdot\mathbf{v}_i\right)\lambda\,dV$)
.IP "\(bu" 2
\fBOperation::Curl\fP ( $\int_{\Omega} \left(\nabla\times\mathbf{v}_i\right)\cdot\boldsymbol{\lambda}\,dV$)
.IP "\(bu" 2
\fBOperation::NormalTrace\fP ( $\int_{\partial\Omega} \left(\hat{\mathbf{n}}\cdot\mathbf{v}_i\right)\lambda\,dS$)
.PP

.PP
\fBNote\fP
.RS 4
Declaring an operation tag does not itself provide a backend implementation\&. The current MFEM volume-equation backend supports Value and Divergence for its supported field spaces, and Gradient for scalar/vector H1 fields\&. Curl and NormalTrace require additional backend support; NormalTrace also requires an appropriate boundary integration path\&.
.RE
.PP
In the equation system you may find documentation for the "contributions" system, which uses the term in the test operand to determine which residual block receives the contribution, and its operation to determine how the test function enters the integrand\&. 
.SH "Member Typedef Documentation"
.PP 
.SS "template<blocks::Term TermT, IsOperation OperationT = Operation::Value> using \fBserif::discretization::forms::Operand\fP< TermT, OperationT >::operation_type = OperationT"

.SS "template<blocks::Term TermT, IsOperation OperationT = Operation::Value> using \fBserif::discretization::forms::Operand\fP< TermT, OperationT >::term_type = TermT"


.SH "Author"
.PP 
Generated automatically by Doxygen for SERiF from the source code\&.