Actual source code: htool.c
1: #include <petsc/private/petscimpl.h>
2: #include <petscmathtool.h>
4: /*@C
5: MatHtoolGetHierarchicalMat - Retrieves the opaque pointer to a Htool virtual matrix stored in a `MATHTOOL`.
7: Not Collective; No Fortran Support
9: Input Parameter:
10: . A - hierarchical matrix
12: Output Parameter:
13: . distributed_operator - opaque pointer to a Htool virtual matrix
15: Level: advanced
17: .seealso: [](ch_matrices), `Mat`, `MATHTOOL`
18: @*/
19: PETSC_EXTERN PetscErrorCode MatHtoolGetHierarchicalMat(Mat A, void *distributed_operator)
20: {
21: PetscFunctionBegin;
23: PetscAssertPointer(distributed_operator, 2);
24: PetscUseMethod(A, "MatHtoolGetHierarchicalMat_C", (Mat, void *), (A, distributed_operator));
25: PetscFunctionReturn(PETSC_SUCCESS);
26: }
28: /*@C
29: MatHtoolSetKernel - Sets the kernel and context used for the assembly of a `MATHTOOL`.
31: Collective; No Fortran Support
33: Input Parameters:
34: + A - hierarchical matrix
35: . kernel - computational kernel (or `NULL`)
36: - kernelctx - kernel context (if kernel is `NULL`, the pointer must be of type `htool::VirtualGenerator<PetscScalar> *`)
38: Level: advanced
40: .seealso: [](ch_matrices), `Mat`, `MATHTOOL`, `MatCreateHtoolFromKernel()`
41: @*/
42: PetscErrorCode MatHtoolSetKernel(Mat A, MatHtoolKernelFn *kernel, void *kernelctx)
43: {
44: PetscFunctionBegin;
47: if (!kernel) PetscAssertPointer(kernelctx, 3);
48: PetscTryMethod(A, "MatHtoolSetKernel_C", (Mat, MatHtoolKernelFn *, void *), (A, kernel, kernelctx));
49: PetscFunctionReturn(PETSC_SUCCESS);
50: }
52: /*@
53: MatHtoolGetPermutationSource - Gets the permutation associated to the source cluster for a `MATHTOOL` matrix.
55: Not Collective
57: Input Parameter:
58: . A - hierarchical matrix
60: Output Parameter:
61: . is - permutation
63: Level: advanced
65: .seealso: [](ch_matrices), `Mat`, `MATHTOOL`, `MatHtoolGetPermutationTarget()`, `MatHtoolUsePermutation()`
66: @*/
67: PetscErrorCode MatHtoolGetPermutationSource(Mat A, IS *is)
68: {
69: PetscFunctionBegin;
71: PetscAssertPointer(is, 2);
72: PetscUseMethod(A, "MatHtoolGetPermutationSource_C", (Mat, IS *), (A, is));
73: PetscFunctionReturn(PETSC_SUCCESS);
74: }
76: /*@
77: MatHtoolGetPermutationTarget - Gets the permutation associated to the target cluster for a `MATHTOOL` matrix.
79: Not Collective
81: Input Parameter:
82: . A - hierarchical matrix
84: Output Parameter:
85: . is - permutation
87: Level: advanced
89: .seealso: [](ch_matrices), `Mat`, `MATHTOOL`, `MatHtoolGetPermutationSource()`, `MatHtoolUsePermutation()`
90: @*/
91: PetscErrorCode MatHtoolGetPermutationTarget(Mat A, IS *is)
92: {
93: PetscFunctionBegin;
95: PetscAssertPointer(is, 2);
96: PetscUseMethod(A, "MatHtoolGetPermutationTarget_C", (Mat, IS *), (A, is));
97: PetscFunctionReturn(PETSC_SUCCESS);
98: }
100: /*@
101: MatHtoolUsePermutation - Sets whether a `MATHTOOL` matrix should permute input (resp. output) vectors following its internal source (resp. target) permutation.
103: Logically Collective
105: Input Parameters:
106: + A - hierarchical matrix
107: - use - Boolean value
109: Level: advanced
111: .seealso: [](ch_matrices), `Mat`, `MATHTOOL`, `MatHtoolGetPermutationSource()`, `MatHtoolGetPermutationTarget()`
112: @*/
113: PetscErrorCode MatHtoolUsePermutation(Mat A, PetscBool use)
114: {
115: PetscFunctionBegin;
118: PetscTryMethod(A, "MatHtoolUsePermutation_C", (Mat, PetscBool), (A, use));
119: PetscFunctionReturn(PETSC_SUCCESS);
120: }
122: /*@
123: MatHtoolUseRecompression - Sets whether a `MATHTOOL` matrix should use recompression.
125: Logically Collective
127: Input Parameters:
128: + A - hierarchical matrix
129: - use - Boolean value
131: Level: advanced
133: .seealso: [](ch_matrices), `Mat`, `MATHTOOL`
134: @*/
135: PetscErrorCode MatHtoolUseRecompression(Mat A, PetscBool use)
136: {
137: PetscFunctionBegin;
140: PetscTryMethod(A, "MatHtoolUseRecompression_C", (Mat, PetscBool), (A, use));
141: PetscFunctionReturn(PETSC_SUCCESS);
142: }
144: /*@
145: MatHtoolGetEpsilon - Gets the relative error tolerance in Frobenius norm used by a `MATHTOOL` matrix.
147: Not Collective
149: Input Parameter:
150: . A - hierarchical matrix
152: Output Parameter:
153: . epsilon - relative error tolerance
155: Level: advanced
157: .seealso: [](ch_matrices), `Mat`, `MATHTOOL`, `MatHtoolSetEpsilon()`
158: @*/
159: PetscErrorCode MatHtoolGetEpsilon(Mat A, PetscReal *epsilon)
160: {
161: PetscFunctionBegin;
163: PetscAssertPointer(epsilon, 2);
164: PetscUseMethod(A, "MatHtoolGetEpsilon_C", (Mat, PetscReal *), (A, epsilon));
165: PetscFunctionReturn(PETSC_SUCCESS);
166: }
168: /*@
169: MatHtoolSetEpsilon - Sets the relative error tolerance in Frobenius norm used by a `MATHTOOL` matrix.
171: Logically Collective
173: Input Parameters:
174: + A - hierarchical matrix
175: - epsilon - relative error tolerance
177: Level: advanced
179: .seealso: [](ch_matrices), `Mat`, `MATHTOOL`, `MatHtoolGetEpsilon()`
180: @*/
181: PetscErrorCode MatHtoolSetEpsilon(Mat A, PetscReal epsilon)
182: {
183: PetscFunctionBegin;
186: PetscTryMethod(A, "MatHtoolSetEpsilon_C", (Mat, PetscReal), (A, epsilon));
187: PetscFunctionReturn(PETSC_SUCCESS);
188: }
190: /*@
191: MatHtoolGetEta - Gets the admissibility condition parameter used by a `MATHTOOL` matrix.
193: Not Collective
195: Input Parameter:
196: . A - hierarchical matrix
198: Output Parameter:
199: . eta - admissibility condition parameter
201: Level: advanced
203: .seealso: [](ch_matrices), `Mat`, `MATHTOOL`, `MatHtoolSetEta()`
204: @*/
205: PetscErrorCode MatHtoolGetEta(Mat A, PetscReal *eta)
206: {
207: PetscFunctionBegin;
209: PetscAssertPointer(eta, 2);
210: PetscUseMethod(A, "MatHtoolGetEta_C", (Mat, PetscReal *), (A, eta));
211: PetscFunctionReturn(PETSC_SUCCESS);
212: }
214: /*@
215: MatHtoolSetEta - Sets the admissibility condition parameter used by a `MATHTOOL` matrix.
217: Logically Collective
219: Input Parameters:
220: + A - hierarchical matrix
221: - eta - admissibility condition parameter
223: Level: advanced
225: .seealso: [](ch_matrices), `Mat`, `MATHTOOL`, `MatHtoolGetEta()`
226: @*/
227: PetscErrorCode MatHtoolSetEta(Mat A, PetscReal eta)
228: {
229: PetscFunctionBegin;
232: PetscTryMethod(A, "MatHtoolSetEta_C", (Mat, PetscReal), (A, eta));
233: PetscFunctionReturn(PETSC_SUCCESS);
234: }
236: /*@
237: MatHtoolGetMaxClusterLeafSize - Gets the maximum size of a leaf in the cluster tree used by a `MATHTOOL` matrix.
239: Not Collective
241: Input Parameter:
242: . A - hierarchical matrix
244: Output Parameter:
245: . size - maximum leaf size
247: Level: advanced
249: .seealso: [](ch_matrices), `Mat`, `MATHTOOL`, `MatHtoolSetMaxClusterLeafSize()`
250: @*/
251: PetscErrorCode MatHtoolGetMaxClusterLeafSize(Mat A, PetscInt *size)
252: {
253: PetscFunctionBegin;
255: PetscAssertPointer(size, 2);
256: PetscUseMethod(A, "MatHtoolGetMaxClusterLeafSize_C", (Mat, PetscInt *), (A, size));
257: PetscFunctionReturn(PETSC_SUCCESS);
258: }
260: /*@
261: MatHtoolSetMaxClusterLeafSize - Sets the maximum size of a leaf in the cluster tree used by a `MATHTOOL` matrix.
263: Logically Collective
265: Input Parameters:
266: + A - hierarchical matrix
267: - size - maximum leaf size
269: Level: advanced
271: .seealso: [](ch_matrices), `Mat`, `MATHTOOL`, `MatHtoolGetMaxClusterLeafSize()`
272: @*/
273: PetscErrorCode MatHtoolSetMaxClusterLeafSize(Mat A, PetscInt size)
274: {
275: PetscFunctionBegin;
278: PetscTryMethod(A, "MatHtoolSetMaxClusterLeafSize_C", (Mat, PetscInt), (A, size));
279: PetscFunctionReturn(PETSC_SUCCESS);
280: }
282: /*@
283: MatHtoolGetMinTargetDepth - Gets the minimum depth of the target cluster tree used by a `MATHTOOL` matrix.
285: Not Collective
287: Input Parameter:
288: . A - hierarchical matrix
290: Output Parameter:
291: . depth - minimum depth of the target cluster tree
293: Level: advanced
295: .seealso: [](ch_matrices), `Mat`, `MATHTOOL`, `MatHtoolSetMinTargetDepth()`, `MatHtoolGetMinSourceDepth()`
296: @*/
297: PetscErrorCode MatHtoolGetMinTargetDepth(Mat A, PetscInt *depth)
298: {
299: PetscFunctionBegin;
301: PetscAssertPointer(depth, 2);
302: PetscUseMethod(A, "MatHtoolGetMinTargetDepth_C", (Mat, PetscInt *), (A, depth));
303: PetscFunctionReturn(PETSC_SUCCESS);
304: }
306: /*@
307: MatHtoolSetMinTargetDepth - Sets the minimum depth of the target cluster tree used by a `MATHTOOL` matrix.
309: Logically Collective
311: Input Parameters:
312: + A - hierarchical matrix
313: - depth - minimum depth of the target cluster tree
315: Level: advanced
317: .seealso: [](ch_matrices), `Mat`, `MATHTOOL`, `MatHtoolGetMinTargetDepth()`, `MatHtoolSetMinSourceDepth()`
318: @*/
319: PetscErrorCode MatHtoolSetMinTargetDepth(Mat A, PetscInt depth)
320: {
321: PetscFunctionBegin;
324: PetscTryMethod(A, "MatHtoolSetMinTargetDepth_C", (Mat, PetscInt), (A, depth));
325: PetscFunctionReturn(PETSC_SUCCESS);
326: }
328: /*@
329: MatHtoolGetMinSourceDepth - Gets the minimum depth of the source cluster tree used by a `MATHTOOL` matrix.
331: Not Collective
333: Input Parameter:
334: . A - hierarchical matrix
336: Output Parameter:
337: . depth - minimum depth of the source cluster tree
339: Level: advanced
341: .seealso: [](ch_matrices), `Mat`, `MATHTOOL`, `MatHtoolSetMinSourceDepth()`, `MatHtoolGetMinTargetDepth()`
342: @*/
343: PetscErrorCode MatHtoolGetMinSourceDepth(Mat A, PetscInt *depth)
344: {
345: PetscFunctionBegin;
347: PetscAssertPointer(depth, 2);
348: PetscUseMethod(A, "MatHtoolGetMinSourceDepth_C", (Mat, PetscInt *), (A, depth));
349: PetscFunctionReturn(PETSC_SUCCESS);
350: }
352: /*@
353: MatHtoolSetMinSourceDepth - Sets the minimum depth of the source cluster tree used by a `MATHTOOL` matrix.
355: Logically Collective
357: Input Parameters:
358: + A - hierarchical matrix
359: - depth - minimum depth of the source cluster tree
361: Level: advanced
363: .seealso: [](ch_matrices), `Mat`, `MATHTOOL`, `MatHtoolGetMinSourceDepth()`, `MatHtoolSetMinTargetDepth()`
364: @*/
365: PetscErrorCode MatHtoolSetMinSourceDepth(Mat A, PetscInt depth)
366: {
367: PetscFunctionBegin;
370: PetscTryMethod(A, "MatHtoolSetMinSourceDepth_C", (Mat, PetscInt), (A, depth));
371: PetscFunctionReturn(PETSC_SUCCESS);
372: }
374: /*@
375: MatHtoolGetBlockTreeConsistency - Gets whether a `MATHTOOL` matrix enforces block tree consistency.
377: Not Collective
379: Input Parameter:
380: . A - hierarchical matrix
382: Output Parameter:
383: . block_tree_consistency - whether block tree consistency is enforced
385: Level: advanced
387: .seealso: [](ch_matrices), `Mat`, `MATHTOOL`, `MatHtoolSetBlockTreeConsistency()`
388: @*/
389: PetscErrorCode MatHtoolGetBlockTreeConsistency(Mat A, PetscBool *block_tree_consistency)
390: {
391: PetscFunctionBegin;
393: PetscAssertPointer(block_tree_consistency, 2);
394: PetscUseMethod(A, "MatHtoolGetBlockTreeConsistency_C", (Mat, PetscBool *), (A, block_tree_consistency));
395: PetscFunctionReturn(PETSC_SUCCESS);
396: }
398: /*@
399: MatHtoolSetBlockTreeConsistency - Sets whether a `MATHTOOL` matrix should enforce block tree consistency.
401: Logically Collective
403: Input Parameters:
404: + A - hierarchical matrix
405: - block_tree_consistency - whether to enforce block tree consistency
407: Level: advanced
409: .seealso: [](ch_matrices), `Mat`, `MATHTOOL`, `MatHtoolGetBlockTreeConsistency()`
410: @*/
411: PetscErrorCode MatHtoolSetBlockTreeConsistency(Mat A, PetscBool block_tree_consistency)
412: {
413: PetscFunctionBegin;
416: PetscTryMethod(A, "MatHtoolSetBlockTreeConsistency_C", (Mat, PetscBool), (A, block_tree_consistency));
417: PetscFunctionReturn(PETSC_SUCCESS);
418: }
420: /*@
421: MatHtoolGetCompressorType - Gets the type of compressor used by a `MATHTOOL` matrix.
423: Not Collective
425: Input Parameter:
426: . A - hierarchical matrix
428: Output Parameter:
429: . compressor - type of compressor
431: Level: advanced
433: .seealso: [](ch_matrices), `Mat`, `MATHTOOL`, `MatHtoolCompressorType`, `MatHtoolSetCompressorType()`
434: @*/
435: PetscErrorCode MatHtoolGetCompressorType(Mat A, MatHtoolCompressorType *compressor)
436: {
437: PetscFunctionBegin;
439: PetscAssertPointer(compressor, 2);
440: PetscUseMethod(A, "MatHtoolGetCompressorType_C", (Mat, MatHtoolCompressorType *), (A, compressor));
441: PetscFunctionReturn(PETSC_SUCCESS);
442: }
444: /*@
445: MatHtoolSetCompressorType - Sets the type of compressor used by a `MATHTOOL` matrix.
447: Logically Collective
449: Input Parameters:
450: + A - hierarchical matrix
451: - compressor - type of compressor
453: Level: advanced
455: .seealso: [](ch_matrices), `Mat`, `MATHTOOL`, `MatHtoolCompressorType`, `MatHtoolGetCompressorType()`
456: @*/
457: PetscErrorCode MatHtoolSetCompressorType(Mat A, MatHtoolCompressorType compressor)
458: {
459: PetscFunctionBegin;
462: PetscTryMethod(A, "MatHtoolSetCompressorType_C", (Mat, MatHtoolCompressorType), (A, compressor));
463: PetscFunctionReturn(PETSC_SUCCESS);
464: }
466: /*@
467: MatHtoolGetClusteringType - Gets the type of clustering used by a `MATHTOOL` matrix.
469: Not Collective
471: Input Parameter:
472: . A - hierarchical matrix
474: Output Parameter:
475: . clustering - type of clustering
477: Level: advanced
479: .seealso: [](ch_matrices), `Mat`, `MATHTOOL`, `MatHtoolClusteringType`, `MatHtoolSetClusteringType()`
480: @*/
481: PetscErrorCode MatHtoolGetClusteringType(Mat A, MatHtoolClusteringType *clustering)
482: {
483: PetscFunctionBegin;
485: PetscAssertPointer(clustering, 2);
486: PetscUseMethod(A, "MatHtoolGetClusteringType_C", (Mat, MatHtoolClusteringType *), (A, clustering));
487: PetscFunctionReturn(PETSC_SUCCESS);
488: }
490: /*@
491: MatHtoolSetClusteringType - Sets the type of clustering used by a `MATHTOOL` matrix.
493: Logically Collective
495: Input Parameters:
496: + A - hierarchical matrix
497: - clustering - type of clustering
499: Level: advanced
501: .seealso: [](ch_matrices), `Mat`, `MATHTOOL`, `MatHtoolClusteringType`, `MatHtoolGetClusteringType()`
502: @*/
503: PetscErrorCode MatHtoolSetClusteringType(Mat A, MatHtoolClusteringType clustering)
504: {
505: PetscFunctionBegin;
508: PetscTryMethod(A, "MatHtoolSetClusteringType_C", (Mat, MatHtoolClusteringType), (A, clustering));
509: PetscFunctionReturn(PETSC_SUCCESS);
510: }
512: /*@C
513: MatCreateHtoolFromKernel - Creates a `MATHTOOL` from a user-supplied kernel.
515: Collective; No Fortran Support
517: Input Parameters:
518: + comm - MPI communicator
519: . m - number of local rows (or `PETSC_DECIDE` to have calculated if `M` is given)
520: . n - number of local columns (or `PETSC_DECIDE` to have calculated if `N` is given)
521: . M - number of global rows (or `PETSC_DETERMINE` to have calculated if `m` is given)
522: . N - number of global columns (or `PETSC_DETERMINE` to have calculated if `n` is given)
523: . spacedim - dimension of the space coordinates
524: . coords_target - coordinates of the target
525: . coords_source - coordinates of the source
526: . kernel - computational kernel (or `NULL`)
527: - kernelctx - kernel context (if kernel is `NULL`, the pointer must be of type `htool::VirtualGenerator<PetscScalar> *`)
529: Output Parameter:
530: . B - matrix
532: Options Database Keys:
533: + -mat_htool_max_cluster_leaf_size size - maximal leaf size in cluster tree
534: . -mat_htool_epsilon epsilon - relative error in Frobenius norm when approximating a block
535: . -mat_htool_eta eta - admissibility condition tolerance
536: . -mat_htool_min_target_depth depth - minimal cluster tree depth associated with the rows
537: . -mat_htool_min_source_depth depth - minimal cluster tree depth associated with the columns
538: . -mat_htool_block_tree_consistency (false|true) - block tree consistency
539: . -mat_htool_recompression (false|true) - use recompression
540: . -mat_htool_compressor (sympartialACA|fullACA|SVD) - type of compression
541: - -mat_htool_clustering (PCARegular|PCAGeometric|BoundingBox1Regular|BoundingBox1Geometric) - type of clustering
543: Level: intermediate
545: .seealso: [](ch_matrices), `Mat`, `MatCreate()`, `MATHTOOL`, `PCSetCoordinates()`, `MatHtoolSetKernel()`, `MatHtoolCompressorType`, `MatHtoolClusteringType`, `MatHtoolGetEpsilon()`, `MatHtoolSetEpsilon()`, `MatHtoolGetEta()`, `MatHtoolSetEta()`, `MatHtoolGetMaxClusterLeafSize()`, `MatHtoolSetMaxClusterLeafSize()`, `MatHtoolGetMinTargetDepth()`, `MatHtoolSetMinTargetDepth()`, `MatHtoolGetMinSourceDepth()`, `MatHtoolSetMinSourceDepth()`, `MatHtoolGetBlockTreeConsistency()`, `MatHtoolSetBlockTreeConsistency()`, `MatHtoolGetCompressorType()`, `MatHtoolSetCompressorType()`, `MatHtoolGetClusteringType()`, `MatHtoolSetClusteringType()`, `MATH2OPUS`, `MatCreateH2OpusFromKernel()`
546: @*/
547: PetscErrorCode MatCreateHtoolFromKernel(MPI_Comm comm, PetscInt m, PetscInt n, PetscInt M, PetscInt N, PetscInt spacedim, const PetscReal coords_target[], const PetscReal coords_source[], MatHtoolKernelFn *kernel, void *kernelctx, Mat *B)
548: {
549: Mat A;
551: PetscFunctionBegin;
552: PetscCall(MatCreate(comm, &A));
554: PetscAssertPointer(coords_target, 7);
555: PetscAssertPointer(coords_source, 8);
557: if (!kernel) PetscAssertPointer(kernelctx, 10);
558: PetscCall(MatSetSizes(A, m, n, M, N));
559: PetscCall(MatSetType(A, MATHTOOL));
560: PetscCall(MatSetUp(A));
561: PetscUseMethod(A, "MatHtoolCreateFromKernel_C", (Mat, PetscInt, const PetscReal[], const PetscReal[], MatHtoolKernelFn *, void *), (A, spacedim, coords_target, coords_source, kernel, kernelctx));
562: *B = A;
563: PetscFunctionReturn(PETSC_SUCCESS);
564: }