-
Notifications
You must be signed in to change notification settings - Fork 707
/
exceptions.h
2013 lines (1867 loc) · 84 KB
/
exceptions.h
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
// ---------------------------------------------------------------------
//
// Copyright (C) 1998 - 2022 by the deal.II authors
//
// This file is part of the deal.II library.
//
// The deal.II library is free software; you can use it, redistribute
// it, and/or modify it under the terms of the GNU Lesser General
// Public License as published by the Free Software Foundation; either
// version 2.1 of the License, or (at your option) any later version.
// The full text of the license can be found in the file LICENSE.md at
// the top level directory of deal.II.
//
// ---------------------------------------------------------------------
#ifndef dealii_exceptions_h
#define dealii_exceptions_h
#include <deal.II/base/config.h>
#include <exception>
#include <ostream>
#include <string>
#include <type_traits>
#ifdef DEAL_II_WITH_CUDA
# include <cusolverSp.h>
# include <cusparse.h>
#endif
DEAL_II_NAMESPACE_OPEN
/**
* This class is the base class for all exception classes. Do not use its
* methods and variables directly since the interface and mechanism may be
* subject to change. Rather create new exception classes using the
* <tt>DeclException</tt> macro family.
*
* See the
* @ref Exceptions
* module for more details on this class and what can be done with classes
* derived from it.
*
* @ingroup Exceptions
*/
class ExceptionBase : public std::exception
{
public:
/**
* Default constructor.
*/
ExceptionBase();
/**
* Copy constructor.
*/
ExceptionBase(const ExceptionBase &exc);
/**
* Destructor.
*/
virtual ~ExceptionBase() noexcept override = default;
/**
* Copy operator. This operator is deleted since exception objects
* are not copyable.
*/
ExceptionBase
operator=(const ExceptionBase &) = delete;
/**
* Set the file name and line of where the exception appeared as well as the
* violated condition and the name of the exception as a char pointer. This
* function also populates the stacktrace.
*/
void
set_fields(const char *file,
const int line,
const char *function,
const char *cond,
const char *exc_name);
/**
* Override the standard function that returns the description of the error.
*/
virtual const char *
what() const noexcept override;
/**
* Get exception name.
*/
const char *
get_exc_name() const;
/**
* Print out the general part of the error information.
*/
void
print_exc_data(std::ostream &out) const;
/**
* Print more specific information about the exception which occurred.
* Overload this function in your own exception classes.
*/
virtual void
print_info(std::ostream &out) const;
/**
* Print a stacktrace, if one has been recorded previously, to the given
* stream.
*/
void
print_stack_trace(std::ostream &out) const;
protected:
/**
* Name of the file this exception happens in.
*/
const char *file;
/**
* Line number in this file.
*/
unsigned int line;
/**
* Name of the function, pretty printed.
*/
const char *function;
/**
* The violated condition, as a string.
*/
const char *cond;
/**
* Name of the exception and call sequence.
*/
const char *exc;
/**
* The number of stacktrace frames that are stored in the following variable.
* Zero if the system does not support stack traces.
*/
int n_stacktrace_frames;
#ifdef DEAL_II_HAVE_GLIBC_STACKTRACE
/**
* Array of pointers that contains the raw stack trace.
*/
void *raw_stacktrace[25];
#endif
private:
/**
* Internal function that generates the c_string. Called by what().
*/
void
generate_message() const;
/**
* A pointer to the c_string that will be printed by what(). It is populated
* by generate_message()
*/
mutable std::string what_str;
};
#ifndef DOXYGEN
/**
* Declare an exception class derived from ExceptionBase without parameters.
*
* @note This and similar macro names are examples of preprocessor definitions
* in the deal.II library that are not prefixed by a string that likely makes
* them unique to deal.II. As a consequence, it is possible that other
* libraries your code interfaces with define the same name, and the result
* will be name collisions (see
* https://en.wikipedia.org/wiki/Name_collision). One can <code>\#undef</code>
* this macro, as well as all other macros defined by deal.II that are not
* prefixed with either <code>DEAL</code> or <code>deal</code>, by including
* the header <code>deal.II/base/undefine_macros.h</code> after all other
* deal.II headers have been included.
*
* @ingroup Exceptions
*/
# define DeclException0(Exception0) \
class Exception0 : public dealii::ExceptionBase \
{}
/**
* Declare an exception class derived from ExceptionBase that can take one
* runtime argument, but if none is given in the place where you want to throw
* the exception, it simply reverts to the default text provided when
* declaring the exception class through this macro.
*
* @note This and similar macro names are examples of preprocessor definitions
* in the deal.II library that are not prefixed by a string that likely makes
* them unique to deal.II. As a consequence, it is possible that other
* libraries your code interfaces with define the same name, and the result
* will be name collisions (see
* https://en.wikipedia.org/wiki/Name_collision). One can <code>\#undef</code>
* this macro, as well as all other macros defined by deal.II that are not
* prefixed with either <code>DEAL</code> or <code>deal</code>, by including
* the header <code>deal.II/base/undefine_macros.h</code> after all other
* deal.II headers have been included.
*
* @ingroup Exceptions
*/
# define DeclExceptionMsg(Exception, defaulttext) \
class Exception : public dealii::ExceptionBase \
{ \
public: \
Exception(const std::string &msg = defaulttext) \
: arg(msg) \
{} \
virtual ~Exception() noexcept \
{} \
virtual void \
print_info(std::ostream &out) const override \
{ \
out << " " << arg << std::endl; \
} \
\
private: \
const std::string arg; \
}
/**
* Declare an exception class derived from ExceptionBase with one additional
* parameter.
*
* @note This and similar macro names are examples of preprocessor definitions
* in the deal.II library that are not prefixed by a string that likely makes
* them unique to deal.II. As a consequence, it is possible that other
* libraries your code interfaces with define the same name, and the result
* will be name collisions (see
* https://en.wikipedia.org/wiki/Name_collision). One can <code>\#undef</code>
* this macro, as well as all other macros defined by deal.II that are not
* prefixed with either <code>DEAL</code> or <code>deal</code>, by including
* the header <code>deal.II/base/undefine_macros.h</code> after all other
* deal.II headers have been included.
*
* @ingroup Exceptions
*/
# define DeclException1(Exception1, type1, outsequence) \
class Exception1 : public dealii::ExceptionBase \
{ \
public: \
Exception1(type1 const &a1) \
: arg1(a1) \
{} \
virtual ~Exception1() noexcept \
{} \
virtual void \
print_info(std::ostream &out) const override \
{ \
out << " " outsequence << std::endl; \
} \
\
private: \
type1 const arg1; \
}
/**
* Declare an exception class derived from ExceptionBase with two additional
* parameters.
*
* @note This and similar macro names are examples of preprocessor definitions
* in the deal.II library that are not prefixed by a string that likely makes
* them unique to deal.II. As a consequence, it is possible that other
* libraries your code interfaces with define the same name, and the result
* will be name collisions (see
* https://en.wikipedia.org/wiki/Name_collision). One can <code>\#undef</code>
* this macro, as well as all other macros defined by deal.II that are not
* prefixed with either <code>DEAL</code> or <code>deal</code>, by including
* the header <code>deal.II/base/undefine_macros.h</code> after all other
* deal.II headers have been included.
*
* @ingroup Exceptions
*/
# define DeclException2(Exception2, type1, type2, outsequence) \
class Exception2 : public dealii::ExceptionBase \
{ \
public: \
Exception2(type1 const &a1, type2 const &a2) \
: arg1(a1) \
, arg2(a2) \
{} \
virtual ~Exception2() noexcept \
{} \
virtual void \
print_info(std::ostream &out) const override \
{ \
out << " " outsequence << std::endl; \
} \
\
private: \
type1 const arg1; \
type2 const arg2; \
}
/**
* Declare an exception class derived from ExceptionBase with three additional
* parameters.
*
* @note This and similar macro names are examples of preprocessor definitions
* in the deal.II library that are not prefixed by a string that likely makes
* them unique to deal.II. As a consequence, it is possible that other
* libraries your code interfaces with define the same name, and the result
* will be name collisions (see
* https://en.wikipedia.org/wiki/Name_collision). One can <code>\#undef</code>
* this macro, as well as all other macros defined by deal.II that are not
* prefixed with either <code>DEAL</code> or <code>deal</code>, by including
* the header <code>deal.II/base/undefine_macros.h</code> after all other
* deal.II headers have been included.
*
* @ingroup Exceptions
*/
# define DeclException3(Exception3, type1, type2, type3, outsequence) \
class Exception3 : public dealii::ExceptionBase \
{ \
public: \
Exception3(type1 const &a1, type2 const &a2, type3 const &a3) \
: arg1(a1) \
, arg2(a2) \
, arg3(a3) \
{} \
virtual ~Exception3() noexcept \
{} \
virtual void \
print_info(std::ostream &out) const override \
{ \
out << " " outsequence << std::endl; \
} \
\
private: \
type1 const arg1; \
type2 const arg2; \
type3 const arg3; \
}
/**
* Declare an exception class derived from ExceptionBase with four additional
* parameters.
*
* @note This and similar macro names are examples of preprocessor definitions
* in the deal.II library that are not prefixed by a string that likely makes
* them unique to deal.II. As a consequence, it is possible that other
* libraries your code interfaces with define the same name, and the result
* will be name collisions (see
* https://en.wikipedia.org/wiki/Name_collision). One can <code>\#undef</code>
* this macro, as well as all other macros defined by deal.II that are not
* prefixed with either <code>DEAL</code> or <code>deal</code>, by including
* the header <code>deal.II/base/undefine_macros.h</code> after all other
* deal.II headers have been included.
*
* @ingroup Exceptions
*/
# define DeclException4(Exception4, type1, type2, type3, type4, outsequence) \
class Exception4 : public dealii::ExceptionBase \
{ \
public: \
Exception4(type1 const &a1, \
type2 const &a2, \
type3 const &a3, \
type4 const &a4) \
: arg1(a1) \
, arg2(a2) \
, arg3(a3) \
, arg4(a4) \
{} \
virtual ~Exception4() noexcept \
{} \
virtual void \
print_info(std::ostream &out) const override \
{ \
out << " " outsequence << std::endl; \
} \
\
private: \
type1 const arg1; \
type2 const arg2; \
type3 const arg3; \
type4 const arg4; \
}
/**
* Declare an exception class derived from ExceptionBase with five additional
* parameters.
*
* @note This and similar macro names are examples of preprocessor definitions
* in the deal.II library that are not prefixed by a string that likely makes
* them unique to deal.II. As a consequence, it is possible that other
* libraries your code interfaces with define the same name, and the result
* will be name collisions (see
* https://en.wikipedia.org/wiki/Name_collision). One can <code>\#undef</code>
* this macro, as well as all other macros defined by deal.II that are not
* prefixed with either <code>DEAL</code> or <code>deal</code>, by including
* the header <code>deal.II/base/undefine_macros.h</code> after all other
* deal.II headers have been included.
*
* @ingroup Exceptions
*/
# define DeclException5( \
Exception5, type1, type2, type3, type4, type5, outsequence) \
class Exception5 : public dealii::ExceptionBase \
{ \
public: \
Exception5(type1 const &a1, \
type2 const &a2, \
type3 const &a3, \
type4 const &a4, \
type5 const &a5) \
: arg1(a1) \
, arg2(a2) \
, arg3(a3) \
, arg4(a4) \
, arg5(a5) \
{} \
virtual ~Exception5() noexcept \
{} \
virtual void \
print_info(std::ostream &out) const override \
{ \
out << " " outsequence << std::endl; \
} \
\
private: \
type1 const arg1; \
type2 const arg2; \
type3 const arg3; \
type4 const arg4; \
type5 const arg5; \
}
#else /*ifndef DOXYGEN*/
// Dummy definitions for doxygen:
/**
* Declare an exception class derived from ExceptionBase without parameters.
*
* @note This and similar macro names are examples of preprocessor definitions
* in the deal.II library that are not prefixed by a string that likely makes
* them unique to deal.II. As a consequence, it is possible that other
* libraries your code interfaces with define the same name, and the result
* will be name collisions (see
* https://en.wikipedia.org/wiki/Name_collision). One can <code>\#undef</code>
* this macro, as well as all other macros defined by deal.II that are not
* prefixed with either <code>DEAL</code> or <code>deal</code>, by including
* the header <code>deal.II/base/undefine_macros.h</code> after all other
* deal.II headers have been included.
*
* @ingroup Exceptions
*/
# define DeclException0(Exception0) \
/** @ingroup Exceptions */ \
static dealii::ExceptionBase &Exception0()
/**
* Declare an exception class derived from ExceptionBase that can take one
* runtime argument, but if none is given in the place where you want to throw
* the exception, it simply reverts to the default text provided when
* declaring the exception class through this macro.
*
* @note This and similar macro names are examples of preprocessor definitions
* in the deal.II library that are not prefixed by a string that likely makes
* them unique to deal.II. As a consequence, it is possible that other
* libraries your code interfaces with define the same name, and the result
* will be name collisions (see
* https://en.wikipedia.org/wiki/Name_collision). One can <code>\#undef</code>
* this macro, as well as all other macros defined by deal.II that are not
* prefixed with either <code>DEAL</code> or <code>deal</code>, by including
* the header <code>deal.II/base/undefine_macros.h</code> after all other
* deal.II headers have been included.
*
* @ingroup Exceptions
*/
# define DeclExceptionMsg(Exception, defaulttext) \
/** @ingroup Exceptions */ \
/** @dealiiExceptionMessage{defaulttext} */ \
static dealii::ExceptionBase &Exception()
/**
* Declare an exception class derived from ExceptionBase with one additional
* parameter.
*
* @note This and similar macro names are examples of preprocessor definitions
* in the deal.II library that are not prefixed by a string that likely makes
* them unique to deal.II. As a consequence, it is possible that other
* libraries your code interfaces with define the same name, and the result
* will be name collisions (see
* https://en.wikipedia.org/wiki/Name_collision). One can <code>\#undef</code>
* this macro, as well as all other macros defined by deal.II that are not
* prefixed with either <code>DEAL</code> or <code>deal</code>, by including
* the header <code>deal.II/base/undefine_macros.h</code> after all other
* deal.II headers have been included.
*
* @ingroup Exceptions
*/
# define DeclException1(Exception1, type1, outsequence) \
/** @ingroup Exceptions */ \
/** @dealiiExceptionMessage{outsequence} */ \
static dealii::ExceptionBase &Exception1(type1 arg1)
/**
* Declare an exception class derived from ExceptionBase with two additional
* parameters.
*
* @note This and similar macro names are examples of preprocessor definitions
* in the deal.II library that are not prefixed by a string that likely makes
* them unique to deal.II. As a consequence, it is possible that other
* libraries your code interfaces with define the same name, and the result
* will be name collisions (see
* https://en.wikipedia.org/wiki/Name_collision). One can <code>\#undef</code>
* this macro, as well as all other macros defined by deal.II that are not
* prefixed with either <code>DEAL</code> or <code>deal</code>, by including
* the header <code>deal.II/base/undefine_macros.h</code> after all other
* deal.II headers have been included.
*
* @ingroup Exceptions
*/
# define DeclException2(Exception2, type1, type2, outsequence) \
/** @ingroup Exceptions */ \
/** @dealiiExceptionMessage{outsequence} */ \
static dealii::ExceptionBase &Exception2(type1 arg1, type2 arg2)
/**
* Declare an exception class derived from ExceptionBase with three additional
* parameters.
*
* @note This and similar macro names are examples of preprocessor definitions
* in the deal.II library that are not prefixed by a string that likely makes
* them unique to deal.II. As a consequence, it is possible that other
* libraries your code interfaces with define the same name, and the result
* will be name collisions (see
* https://en.wikipedia.org/wiki/Name_collision). One can <code>\#undef</code>
* this macro, as well as all other macros defined by deal.II that are not
* prefixed with either <code>DEAL</code> or <code>deal</code>, by including
* the header <code>deal.II/base/undefine_macros.h</code> after all other
* deal.II headers have been included.
*
* @ingroup Exceptions
*/
# define DeclException3(Exception3, type1, type2, type3, outsequence) \
/** @ingroup Exceptions */ \
/** @dealiiExceptionMessage{outsequence} */ \
static dealii::ExceptionBase &Exception3(type1 arg1, type2 arg2, type3 arg3)
/**
* Declare an exception class derived from ExceptionBase with four additional
* parameters.
*
* @note This and similar macro names are examples of preprocessor definitions
* in the deal.II library that are not prefixed by a string that likely makes
* them unique to deal.II. As a consequence, it is possible that other
* libraries your code interfaces with define the same name, and the result
* will be name collisions (see
* https://en.wikipedia.org/wiki/Name_collision). One can <code>\#undef</code>
* this macro, as well as all other macros defined by deal.II that are not
* prefixed with either <code>DEAL</code> or <code>deal</code>, by including
* the header <code>deal.II/base/undefine_macros.h</code> after all other
* deal.II headers have been included.
*
* @ingroup Exceptions
*/
# define DeclException4(Exception4, type1, type2, type3, type4, outsequence) \
/** @ingroup Exceptions */ \
/** @dealiiExceptionMessage{outsequence} */ \
static dealii::ExceptionBase &Exception4(type1 arg1, \
type2 arg2, \
type3 arg3, \
type4 arg4)
/**
* Declare an exception class derived from ExceptionBase with five additional
* parameters.
*
* @note This and similar macro names are examples of preprocessor definitions
* in the deal.II library that are not prefixed by a string that likely makes
* them unique to deal.II. As a consequence, it is possible that other
* libraries your code interfaces with define the same name, and the result
* will be name collisions (see
* https://en.wikipedia.org/wiki/Name_collision). One can <code>\#undef</code>
* this macro, as well as all other macros defined by deal.II that are not
* prefixed with either <code>DEAL</code> or <code>deal</code>, by including
* the header <code>deal.II/base/undefine_macros.h</code> after all other
* deal.II headers have been included.
*
* @ingroup Exceptions
*/
# define DeclException5( \
Exception5, type1, type2, type3, type4, type5, outsequence) \
/** @ingroup Exceptions */ \
/** @dealiiExceptionMessage{outsequence} */ \
static dealii::ExceptionBase &Exception5( \
type1 arg1, type2 arg2, type3 arg3, type4 arg4, type5 arg5)
#endif /*ifndef DOXYGEN*/
/**
* Declare some exceptions that occur over and over. This way, you can simply
* use these exceptions, instead of having to declare them locally in your
* class. The namespace in which these exceptions are declared is later
* included into the global namespace by
* @code
* using namespace StandardExceptions;
* @endcode
*
* @ingroup Exceptions
*/
namespace StandardExceptions
{
/**
* @addtogroup Exceptions
* @{
*/
/**
* Exception denoting a division by zero.
*/
DeclExceptionMsg(ExcDivideByZero,
"A piece of code is attempting a division by zero. This is "
"likely going to lead to results that make no sense.");
/**
* Exception raised if a number is not finite.
*
* This exception should be used to catch infinite or not a number results
* of arithmetic operations that do not result from a division by zero (use
* ExcDivideByZero for those).
*
* The exception uses std::complex as its argument to ensure that we can use
* it for all scalar arguments (real or complex-valued).
*/
DeclException1(
ExcNumberNotFinite,
std::complex<double>,
<< "In a significant number of places, deal.II checks that some intermediate "
<< "value is a finite number (as opposed to plus or minus infinity, or "
<< "NaN/Not a Number). In the current function, we encountered a number "
<< "that is not finite (its value is " << arg1 << " and therefore "
<< "violates the current assertion).\n\n"
<< "This may be due to the fact that some operation in this function "
<< "created such a value, or because one of the arguments you passed "
<< "to the function already had this value from some previous "
<< "operation. In the latter case, this function only triggered the "
<< "error but may not actually be responsible for the computation of "
<< "the number that is not finite.\n\n"
<< "There are two common cases where this situation happens. First, your "
<< "code (or something in deal.II) divides by zero in a place where this "
<< "should not happen. Or, you are trying to solve a linear system "
<< "with an unsuitable solver (such as an indefinite or non-symmetric "
<< "linear system using a Conjugate Gradient solver); such attempts "
<< "oftentimes yield an operation somewhere that tries to divide "
<< "by zero or take the square root of a negative value.\n\n"
<< "In any case, when trying to find the source of the error, "
<< "recall that the location where you are getting this error is "
<< "simply the first place in the program where there is a check "
<< "that a number (e.g., an element of a solution vector) is in fact "
<< "finite, but that the actual error that computed the number "
<< "may have happened far earlier. To find this location, you "
<< "may want to add checks for finiteness in places of your "
<< "program visited before the place where this error is produced. "
<< "One way to check for finiteness is to use the 'AssertIsFinite' "
<< "macro.");
/**
* Trying to allocate a new object failed due to lack of free memory.
*/
DeclException1(ExcOutOfMemory,
std::size_t,
"Your program tried to allocate some memory but this "
"allocation failed. Typically, this either means that "
"you simply do not have enough memory in your system, "
"or that you are (erroneously) trying to allocate "
"a chunk of memory that is simply beyond all reasonable "
"size, for example because the size of the object has "
"been computed incorrectly."
"\n\n"
"In the current case, the request was for "
<< arg1 << " bytes.");
/**
* A memory handler reached a point where all allocated objects should have
* been released. Since this exception is thrown, some were still allocated.
*/
DeclException1(ExcMemoryLeak,
int,
<< "Destroying memory handler while " << arg1
<< " objects are still allocated.");
/**
* An error occurred reading or writing a file.
*/
DeclExceptionMsg(ExcIO,
"An input/output error has occurred. There are a number of "
"reasons why this may be happening, both for reading and "
"writing operations."
"\n\n"
"If this happens during an operation that tries to read "
"data: First, you may be "
"trying to read from a file that doesn't exist or that is "
"not readable given its file permissions. Second, deal.II "
"uses this error at times if it tries to "
"read information from a file but where the information "
"in the file does not correspond to the expected format. "
"An example would be a truncated file, or a mesh file "
"that contains not only sections that describe the "
"vertices and cells, but also sections for additional "
"data that deal.II does not understand."
"\n\n"
"If this happens during an operation that tries to write "
"data: you may be trying to write to a file to which file "
"or directory permissions do not allow you to write. A "
"typical example is where you specify an output file in "
"a directory that does not exist.");
/**
* An error occurred opening the named file.
*
* The constructor takes a single argument of type <tt>std::string</tt> naming
* the file.
*/
DeclException1(ExcFileNotOpen,
std::string,
<< "Could not open file " << arg1
<< "."
"\n\n"
"If this happens during an operation that tries to read "
"data: you may be "
"trying to read from a file that doesn't exist or that is "
"not readable given its file permissions."
"\n\n"
"If this happens during an operation that tries to write "
"data: you may be trying to write to a file to which file "
"or directory permissions do not allow you to write. A "
"typical example is where you specify an output file in "
"a directory that does not exist.");
/**
* Exception denoting a part of the library or application program that has
* not yet been implemented. In many cases, this only indicates that there
* wasn't much need for something yet, not that this is difficult to
* implement. It is therefore quite worth the effort to take a look at the
* corresponding place and see whether it can be implemented without too
* much effort.
*/
DeclExceptionMsg(ExcNotImplemented,
"You are trying to use functionality in deal.II that is "
"currently not implemented. In many cases, this indicates "
"that there simply didn't appear much of a need for it, or "
"that the author of the original code did not have the "
"time to implement a particular case. If you hit this "
"exception, it is therefore worth the time to look into "
"the code to find out whether you may be able to "
"implement the missing functionality. If you do, please "
"consider providing a patch to the deal.II development "
"sources (see the deal.II website on how to contribute).");
/**
* This exception usually indicates that some condition which the programmer
* thinks must be satisfied at a certain point in an algorithm, is not
* fulfilled. This might be due to some programming error above, due to
* changes to the algorithm that did not preserve this assertion, or due to
* assumptions the programmer made that are not valid at all (i.e. the
* exception is thrown although there is no error here). Within the library,
* this exception is most often used when we write some kind of complicated
* algorithm and are not yet sure whether we got it right; we then put in
* assertions after each part of the algorithm that check for some
* conditions that should hold there, and throw an exception if they do not.
*
* We usually leave in these assertions even after we are confident that the
* implementation is correct, since if someone later changes or extends the
* algorithm, these exceptions will indicate to them if they violate
* assumptions that are used later in the algorithm. Furthermore, it
* sometimes happens that an algorithm does not work in very rare corner
* cases. These cases will then be trapped sooner or later by the exception,
* so that the algorithm can then be fixed for these cases as well.
*/
DeclExceptionMsg(ExcInternalError,
"This exception -- which is used in many places in the "
"library -- usually indicates that some condition which "
"the author of the code thought must be satisfied at a "
"certain point in an algorithm, is not fulfilled. An "
"example would be that the first part of an algorithm "
"sorts elements of an array in ascending order, and "
"a second part of the algorithm later encounters an "
"element that is not larger than the previous one."
"\n\n"
"There is usually not very much you can do if you "
"encounter such an exception since it indicates an error "
"in deal.II, not in your own program. Try to come up with "
"the smallest possible program that still demonstrates "
"the error and contact the deal.II mailing lists with it "
"to obtain help.");
/**
* This exception is used in functions that may not be called (i.e. in pure
* functions) but could not be declared pure since the class is intended to
* be used anyway, even though the respective function may only be called if
* a derived class is used.
*/
DeclExceptionMsg(
ExcPureFunctionCalled,
"You (or a place in the library) are trying to call a "
"function that is declared as a virtual function in a "
"base class but that has not been overridden in your "
"derived class."
"\n\n"
"This exception happens in cases where the base class "
"cannot provide a useful default implementation for "
"the virtual function, but where we also do not want "
"to mark the function as abstract (i.e., with '=0' at the end) "
"because the function is not essential to the class in many "
"contexts. In cases like this, the base class provides "
"a dummy implementation that makes the compiler happy, but "
"that then throws the current exception."
"\n\n"
"A concrete example would be the 'Function' class. It declares "
"the existence of 'value()' and 'gradient()' member functions, "
"and both are marked as 'virtual'. Derived classes have to "
"override these functions for the values and gradients of a "
"particular function. On the other hand, not every function "
"has a gradient, and even for those that do, not every program "
"actually needs to evaluate it. Consequently, there is no "
"*requirement* that a derived class actually override the "
"'gradient()' function (as there would be had it been marked "
"as abstract). But, since the base class cannot know how to "
"compute the gradient, if a derived class does not override "
"the 'gradient()' function and it is called anyway, then the "
"default implementation in the base class will simply throw "
"an exception."
"\n\n"
"The exception you see is what happens in cases such as the "
"one just illustrated. To fix the problem, you need to "
"investigate whether the function being called should indeed have "
"been called; if the answer is 'yes', then you need to "
"implement the missing override in your class.");
/**
* This exception is used if some object is found uninitialized.
*/
DeclException0(ExcNotInitialized);
/**
* The object is in a state not suitable for this operation.
*/
DeclException0(ExcInvalidState);
/**
* This exception is raised if a functionality is not possible in the given
* dimension. Mostly used to throw function calls in 1d.
*
* The constructor takes a single <tt>int</tt>, denoting the dimension.
*/
DeclException1(ExcImpossibleInDim,
int,
<< "You are trying to execute functionality that is "
<< "impossible in " << arg1
<< "d or simply does not make any sense.");
/**
* This exception is raised if a functionality is not possible in the given
* combination of dimension and space-dimension.
*
* The constructor takes two <tt>int</tt>, denoting the dimension and the
* space dimension.
*/
DeclException2(ExcImpossibleInDimSpacedim,
int,
int,
<< "You are trying to execute functionality that is "
<< "impossible in dimensions <" << arg1 << ',' << arg2
<< "> or simply does not make any sense.");
/**
* A number is zero, but it should not be here.
*/
DeclExceptionMsg(ExcZero,
"In a check in the code, deal.II encountered a zero in "
"a place where this does not make sense. See the condition "
"that was being checked and that is printed further up "
"in the error message to get more information on what "
"the erroneous zero corresponds to.");
/**
* The object should have been filled with something before this member
* function is called.
*/
DeclExceptionMsg(ExcEmptyObject,
"The object you are trying to access is empty but it makes "
"no sense to attempt the operation you are trying on an "
"empty object.");
/**
* This exception is raised whenever the sizes of two objects were assumed
* to be equal, but were not.
*
* Parameters to the constructor are the first and second size, both of type
* <tt>int</tt>.
*/
DeclException2(ExcDimensionMismatch,
std::size_t,
std::size_t,
<< "Dimension " << arg1 << " not equal to " << arg2 << '.');
/**
* The first dimension should be either equal to the second or the third,
* but it is neither.
*/
DeclException3(ExcDimensionMismatch2,
std::size_t,
std::size_t,
std::size_t,
<< "Dimension " << arg1 << " neither equal to " << arg2
<< " nor to " << arg3 << '.');
/**
* This exception indicates that an index is not within the expected range.
* For example, it may be that you are trying to access an element of a
* vector which does not exist.
*
* The constructor takes three <tt>std::size_t</tt> arguments, namely
* <ol>
* <li> the violating index
* <li> the lower bound
* <li> the upper bound plus one
* </ol>
*/
DeclException3(
ExcIndexRange,
std::size_t,
std::size_t,
std::size_t,
<< "Index " << arg1 << " is not in the half-open range [" << arg2 << ','
<< arg3 << ")."
<< (arg2 == arg3 ?
" In the current case, this half-open range is in fact empty, "
"suggesting that you are accessing an element of an empty "
"collection such as a vector that has not been set to the "
"correct size." :
""));
/**
* This exception indicates that an index is not within the expected range.
* For example, it may be that you are trying to access an element of a
* vector which does not exist.
*
* The constructor takes three arguments, namely
* <ol>
* <li> the violating index
* <li> the lower bound
* <li> the upper bound plus one
* </ol>
*
* This generic exception differs from ExcIndexRange by allowing to specify
* the type of indices.
*/
template <typename T>
DeclException3(
ExcIndexRangeType,
T,
T,
T,
<< "Index " << arg1 << " is not in the half-open range [" << arg2 << ','
<< arg3 << ")."
<< (arg2 == arg3 ?
" In the current case, this half-open range is in fact empty, "
"suggesting that you are accessing an element of an empty "
"collection such as a vector that has not been set to the "
"correct size." :
""));
/**
* A number is too small.
*/
DeclException2(ExcLowerRange,
int,
int,
<< "Number " << arg1 << " must be larger than or equal "
<< arg2 << '.');
/**
* A generic exception definition for the ExcLowerRange above.
*/