1 // Copyright (c) 2017-2026, Lawrence Livermore National Security, LLC and other CEED contributors.
2 // All Rights Reserved. See the top-level LICENSE and NOTICE files for details.
4 // SPDX-License-Identifier: BSD-2-Clause
8 #include <ceed-impl.h>
11 #include <ceed/jit-tools.h>
34   char              name[CEED_MAX_RESOURCE_LEN];  member
38   int (*init)(Ceed ceed, const char *name, CeedQFunction qf);
43 /// ----------------------------------------------------------------------------
45 /// ----------------------------------------------------------------------------
52   @param[in] name       Name for this backend to respond to
60   @return An error code: 0 - success, otherwise - failure
64 int CeedQFunctionRegister(const char *name, const char *source, CeedInt vec_length, CeedQFunctionUs…  in CeedQFunctionRegister()  argument
69   CeedDebugEnv("Gallery Register: %s", name);  in CeedQFunctionRegister()
73       strncpy(gallery_qfunctions[num_qfunctions].name, name, CEED_MAX_RESOURCE_LEN);  in CeedQFunctionRegister()
74       gallery_qfunctions[num_qfunctions].name[CEED_MAX_RESOURCE_LEN - 1] = 0;  in CeedQFunctionRegister()
76       gallery_qfunctions[num_qfunctions].source[CEED_MAX_RESOURCE_LEN - 1] = 0;  in CeedQFunctionRegister()
93   @param[in]  field_name  Name of `CeedQFunction` field
102   @return An error code: 0 - success, otherwise - failure
108   CeedCall(CeedStringAllocCopy(field_name, (char **)&(*f)->field_name));  in CeedQFunctionFieldSet()
109   (*f)->size      = size;  in CeedQFunctionFieldSet()
110   (*f)->eval_mode = eval_mode;  in CeedQFunctionFieldSet()
123   @return An error code: 0 - success, otherwise - failure
137           "      Name: \"%s\"\n%s"  in CeedQFunctionFieldView()
151   @return An error code: 0 - success, otherwise - failure
165   @return An error code: 0 - success, otherwise - failure
180   @return An error code: 0 - success, otherwise - failure
185   qf->is_fortran = status;  in CeedQFunctionSetFortranStatus()
191 /// ----------------------------------------------------------------------------
193 /// ----------------------------------------------------------------------------
203   @return An error code: 0 - success, otherwise - failure
208   *vec_length = qf->vec_length;  in CeedQFunctionGetVectorLength()
219   @return An error code: 0 - success, otherwise - failure
224   if (num_input) *num_input = qf->num_input_fields;  in CeedQFunctionGetNumArgs()
225   if (num_output) *num_output = qf->num_output_fields;  in CeedQFunctionGetNumArgs()
230   @brief Get the name of the `CeedQFunction`.
231 …Use the `name` if created via @ref CeedQFunctionCreateInteriorByName(), otherwise return the kerne…
234   @param[out] name Variable to store `CeedQFunction` name
236   @return An error code: 0 - success, otherwise - failure
240 int CeedQFunctionGetName(CeedQFunction qf, const char **name) {  in CeedQFunctionGetName()  argument
241   if (qf->is_gallery) {  in CeedQFunctionGetName()
242     *name = qf->gallery_name;  in CeedQFunctionGetName()
244     CeedCall(CeedQFunctionGetKernelName(qf, name));  in CeedQFunctionGetName()
250   @brief Get the name of the user function for a `CeedQFunction`
253   @param[out] kernel_name Variable to store string holding kernel name
255   @return An error code: 0 - success, otherwise - failure
260   if (!qf->kernel_name) {  in CeedQFunctionGetKernelName()
263     if (qf->user_source) {  in CeedQFunctionGetKernelName()
264       const char *kernel_name     = strrchr(qf->user_source, ':') + 1;  in CeedQFunctionGetKernelName()
272     qf->kernel_name = kernel_name_copy;  in CeedQFunctionGetKernelName()
275   *kernel_name = qf->kernel_name;  in CeedQFunctionGetKernelName()
285   @return An error code: 0 - success, otherwise - failure
290   if (!qf->source_path && qf->user_source) {  in CeedQFunctionGetSourcePath()
295     const char *kernel_name     = strrchr(qf->user_source, ':') + 1;  in CeedQFunctionGetSourcePath()
299     CeedCall(CeedCheckFilePath(ceed, qf->user_source, &is_absolute_path));  in CeedQFunctionGetSourcePath()
301       absolute_path = (char *)qf->user_source;  in CeedQFunctionGetSourcePath()
303       CeedCall(CeedGetJitAbsolutePath(ceed, qf->user_source, &absolute_path));  in CeedQFunctionGetSourcePath()
307     size_t source_len = strlen(absolute_path) - kernel_name_len - 1;  in CeedQFunctionGetSourcePath()
311     qf->source_path = source_path_copy;  in CeedQFunctionGetSourcePath()
316   *source_path = (char *)qf->source_path;  in CeedQFunctionGetSourcePath()
334   @return An error code: 0 - success, otherwise - failure
361   @return An error code: 0 - success, otherwise - failure
366   *f = qf->function;  in CeedQFunctionGetUserFunction()
378   @return An error code: 0 - success, otherwise - failure
384   if (qf->ctx) CeedCall(CeedQFunctionContextReferenceCopy(qf->ctx, ctx));  in CeedQFunctionGetContext()
396   @return An error code: 0 - success, otherwise - failure
425   @return An error code: 0 - success, otherwise - failure
454   @return An error code: 0 - success, otherwise - failure
461   if (qf->is_fortran) {  in CeedQFunctionGetInnerContext()
465     *ctx = fortran_ctx->inner_ctx;  in CeedQFunctionGetInnerContext()
482   @return An error code: 0 - success, otherwise - failure
510   @return An error code: 0 - success, otherwise - failure
537   @return An error code: 0 - success, otherwise - failure
542   *is_identity = qf->is_identity;  in CeedQFunctionIsIdentity()
552   @return An error code: 0 - success, otherwise - failure
557   *is_writable = qf->is_context_writable;  in CeedQFunctionIsContextWritable()
567   @return An error code: 0 - success, otherwise - failure
572   *(void **)data = qf->data;  in CeedQFunctionGetData()
582   @return An error code: 0 - success, otherwise - failure
587   qf->data = data;  in CeedQFunctionSetData()
597   @return An error code: 0 - success, otherwise - failure
602   *is_immutable = qf->is_immutable;  in CeedQFunctionIsImmutable()
611   @return An error code: 0 - success, otherwise - failure
616   qf->is_immutable = true;  in CeedQFunctionSetImmutable()
625   @return An error code: 0 - success, otherwise - failure
643   *flops = qf->user_flop_estimate;  in CeedQFunctionGetFlopsEstimate()
649 /// ----------------------------------------------------------------------------
651 /// ----------------------------------------------------------------------------
671   @return An error code: 0 - success, otherwise - failure
673   See \ref CeedQFunctionUser for details on the call-back function `f` arguments.
680   if (!ceed->QFunctionCreate) {  in CeedQFunctionCreateInterior()
691 …"Provided path to source does not include function name. Provided: \"%s\"\nRequired: \"\\abs_path\…  in CeedQFunctionCreateInterior()
694 …CeedCall(CeedObjectCreate(ceed, CeedQFunctionView_Object, CeedQFunctionDestroy_Object, &(*qf)->obj…  in CeedQFunctionCreateInterior()
695   (*qf)->vec_length          = vec_length;  in CeedQFunctionCreateInterior()
696   (*qf)->is_identity         = false;  in CeedQFunctionCreateInterior()
697   (*qf)->is_context_writable = true;  in CeedQFunctionCreateInterior()
698   (*qf)->function            = f;  in CeedQFunctionCreateInterior()
699   (*qf)->user_flop_estimate  = -1;  in CeedQFunctionCreateInterior()
705     (*qf)->user_source = user_source_copy;  in CeedQFunctionCreateInterior()
707   CeedCall(CeedCalloc(CEED_FIELD_MAX, &(*qf)->input_fields));  in CeedQFunctionCreateInterior()
708   CeedCall(CeedCalloc(CEED_FIELD_MAX, &(*qf)->output_fields));  in CeedQFunctionCreateInterior()
709   CeedCall(ceed->QFunctionCreate(*qf));  in CeedQFunctionCreateInterior()
714   @brief Create a `CeedQFunction` for evaluating interior (volumetric) terms by name
717   @param[in]  name Name of `CeedQFunction` to use from gallery
720   @return An error code: 0 - success, otherwise - failure
724 int CeedQFunctionCreateInteriorByName(Ceed ceed, const char *name, CeedQFunction *qf) {  in CeedQFunctionCreateInteriorByName()  argument
729   CeedCheck(name, ceed, CEED_ERROR_INCOMPLETE, "No CeedQFunction name provided");  in CeedQFunctionCreateInteriorByName()
732     const char *curr_name = gallery_qfunctions[i].name;  in CeedQFunctionCreateInteriorByName()
733     for (n = 0; curr_name[n] && curr_name[n] == name[n]; n++) {  in CeedQFunctionCreateInteriorByName()
747   CeedCall(gallery_qfunctions[match_index].init(ceed, name, *qf));  in CeedQFunctionCreateInteriorByName()
749   // Copy name  in CeedQFunctionCreateInteriorByName()
750   CeedCall(CeedStringAllocCopy(name, (char **)&(*qf)->gallery_name));  in CeedQFunctionCreateInteriorByName()
751   (*qf)->is_gallery = true;  in CeedQFunctionCreateInteriorByName()
759 …edElemRestriction` and `CeedBasis`, such as restriction and prolongation operators for p-multigrid.
768   @return An error code: 0 - success, otherwise - failure
780   (*qf)->is_identity = true;  in CeedQFunctionCreateIdentity()
794 …Note: If the value of `*qf_copy` passed to this function is non-NULL, then it is assumed that `*qf…
800   @return An error code: 0 - success, otherwise - failure
815   @param[in]     field_name Name of `CeedQFunction` field
830   @return An error code: 0 - success, otherwise - failure
840   for (CeedInt i = 0; i < qf->num_input_fields; i++) {  in CeedQFunctionAddInput()
841 …CeedCheck(strcmp(field_name, qf->input_fields[i]->field_name), CeedQFunctionReturnCeed(qf), CEED_E…  in CeedQFunctionAddInput()
842               "CeedQFunction field names must be unique. Duplicate name: %s", field_name);  in CeedQFunctionAddInput()
844   for (CeedInt i = 0; i < qf->num_output_fields; i++) {  in CeedQFunctionAddInput()
845 …CeedCheck(strcmp(field_name, qf->output_fields[i]->field_name), CeedQFunctionReturnCeed(qf), CEED_…  in CeedQFunctionAddInput()
846               "CeedQFunction field names must be unique. Duplicate name: %s", field_name);  in CeedQFunctionAddInput()
848 …CeedCall(CeedQFunctionFieldSet(&qf->input_fields[qf->num_input_fields], field_name, size, eval_mod…  in CeedQFunctionAddInput()
849   qf->num_input_fields++;  in CeedQFunctionAddInput()
857   @param[in]     field_name Name of `CeedQFunction` field
872   @return An error code: 0 - success, otherwise - failure
883   for (CeedInt i = 0; i < qf->num_input_fields; i++) {  in CeedQFunctionAddOutput()
884 …CeedCheck(strcmp(field_name, qf->input_fields[i]->field_name), CeedQFunctionReturnCeed(qf), CEED_E…  in CeedQFunctionAddOutput()
887   for (CeedInt i = 0; i < qf->num_output_fields; i++) {  in CeedQFunctionAddOutput()
888 …CeedCheck(strcmp(field_name, qf->output_fields[i]->field_name), CeedQFunctionReturnCeed(qf), CEED_…  in CeedQFunctionAddOutput()
891 …CeedCall(CeedQFunctionFieldSet(&qf->output_fields[qf->num_output_fields], field_name, size, eval_m…  in CeedQFunctionAddOutput()
892   qf->num_output_fields++;  in CeedQFunctionAddOutput()
907   @return An error code: 0 - success, otherwise - failure
914   if (num_input_fields) *num_input_fields = qf->num_input_fields;  in CeedQFunctionGetFields()
915   if (input_fields) *input_fields = qf->input_fields;  in CeedQFunctionGetFields()
916   if (num_output_fields) *num_output_fields = qf->num_output_fields;  in CeedQFunctionGetFields()
917   if (output_fields) *output_fields = qf->output_fields;  in CeedQFunctionGetFields()
922   @brief Get the name of a `CeedQFunctionField`
925   @param[out] field_name Variable to store the field name
927   @return An error code: 0 - success, otherwise - failure
932   *field_name = qf_field->field_name;  in CeedQFunctionFieldGetName()
942   @return An error code: 0 - success, otherwise - failure
947   *size = qf_field->size;  in CeedQFunctionFieldGetSize()
957   @return An error code: 0 - success, otherwise - failure
962   *eval_mode = qf_field->eval_mode;  in CeedQFunctionFieldGetEvalMode()
972   @param[out] field_name Variable to store the field name
976   @return An error code: 0 - success, otherwise - failure
993   @return An error code: 0 - success, otherwise - failure
998   CeedCall(CeedQFunctionContextDestroy(&qf->ctx));  in CeedQFunctionSetContext()
999   qf->ctx = ctx;  in CeedQFunctionSetContext()
1019   @return An error code: 0 - success, otherwise - failure
1024   qf->is_context_writable = is_writable;  in CeedQFunctionSetContextWritable()
1037 …CeedCheck(flops >= 0, CeedQFunctionReturnCeed(qf), CEED_ERROR_INCOMPATIBLE, "Must set non-negative…  in CeedQFunctionSetUserFlopsEstimate()
1038   qf->user_flop_estimate = flops;  in CeedQFunctionSetUserFlopsEstimate()
1048   @return Error code: 0 - success, otherwise - failure
1063   @return Error code: 0 - success, otherwise - failure
1078   @return Error code: 0 - success, otherwise - failure
1084   const char *name;  in CeedQFunctionView()  local
1094   CeedCall(CeedQFunctionGetName(qf, &name));  in CeedQFunctionView()
1095   fprintf(stream, "%s%sCeedQFunction - %s\n", tabs, qf->is_gallery ? "Gallery " : "User ", name);  in CeedQFunctionView()
1097 …fprintf(stream, "%s  %" CeedInt_FMT " input field%s:\n", tabs, qf->num_input_fields, qf->num_input…  in CeedQFunctionView()
1098   for (CeedInt i = 0; i < qf->num_input_fields; i++) {  in CeedQFunctionView()
1099     CeedCall(CeedQFunctionFieldView(qf->input_fields[i], i, 1, tabs, stream));  in CeedQFunctionView()
1102 …fprintf(stream, "%s  %" CeedInt_FMT " output field%s:\n", tabs, qf->num_output_fields, qf->num_out…  in CeedQFunctionView()
1103   for (CeedInt i = 0; i < qf->num_output_fields; i++) {  in CeedQFunctionView()
1104     CeedCall(CeedQFunctionFieldView(qf->output_fields[i], i, 0, tabs, stream));  in CeedQFunctionView()
1116   @return An error code: 0 - success, otherwise - failure
1146   @return An error code: 0 - success, otherwise - failure
1153 …CeedCheck(qf->Apply, CeedQFunctionReturnCeed(qf), CEED_ERROR_UNSUPPORTED, "Backend does not suppor…  in CeedQFunctionApply()
1156 …ber of quadrature points %" CeedInt_FMT " must be a multiple of %" CeedInt_FMT, Q, qf->vec_length);  in CeedQFunctionApply()
1158   CeedCall(qf->Apply(qf, Q, u, v));  in CeedQFunctionApply()
1167   @return An error code: 0 - success, otherwise - failure
1177   if ((*qf)->Destroy) {  in CeedQFunctionDestroy()
1178     CeedCall((*qf)->Destroy(*qf));  in CeedQFunctionDestroy()
1181   for (CeedInt i = 0; i < (*qf)->num_input_fields; i++) {  in CeedQFunctionDestroy()
1182     CeedCall(CeedFree(&(*(*qf)->input_fields[i]).field_name));  in CeedQFunctionDestroy()
1183     CeedCall(CeedFree(&(*qf)->input_fields[i]));  in CeedQFunctionDestroy()
1185   for (CeedInt i = 0; i < (*qf)->num_output_fields; i++) {  in CeedQFunctionDestroy()
1186     CeedCall(CeedFree(&(*(*qf)->output_fields[i]).field_name));  in CeedQFunctionDestroy()
1187     CeedCall(CeedFree(&(*qf)->output_fields[i]));  in CeedQFunctionDestroy()
1189   CeedCall(CeedFree(&(*qf)->input_fields));  in CeedQFunctionDestroy()
1190   CeedCall(CeedFree(&(*qf)->output_fields));  in CeedQFunctionDestroy()
1193   CeedCall(CeedQFunctionContextDestroy(&(*qf)->ctx));  in CeedQFunctionDestroy()
1195   CeedCall(CeedFree(&(*qf)->user_source));  in CeedQFunctionDestroy()
1196   CeedCall(CeedFree(&(*qf)->source_path));  in CeedQFunctionDestroy()
1197   CeedCall(CeedFree(&(*qf)->gallery_name));  in CeedQFunctionDestroy()
1198   CeedCall(CeedFree(&(*qf)->kernel_name));  in CeedQFunctionDestroy()
1199   CeedCall(CeedObjectDestroy_Private(&(*qf)->obj));  in CeedQFunctionDestroy()