Bläddra i källkod

Dox updates

enhancement_3
Trevor Irons 8 år sedan
förälder
incheckning
2d36da5850
3 ändrade filer med 94 tillägg och 73 borttagningar
  1. 20
    29
      Documentation/dox/compiling.dox
  2. 26
    11
      Documentation/dox/mem.dox
  3. 48
    33
      Documentation/dox/tutorial.dox

+ 20
- 29
Documentation/dox/compiling.dox Visa fil

@@ -21,33 +21,32 @@ the prerequisites, but on many platforms this is easy.
21 21
 - \ref Configuring
22 22
 - \ref Building
23 23
 
24
-\section Prerequisites Prerequisites
25
-
24
+\section OptionalPrerequisites Optional Prerequisites
25
+- VTK - The Visualization ToolKit is a powerful data visualization framework. This is
26
+  an optional dependency, but some functionality will be missing without it. Any
27
+  version after 6.0 is fine. VTK is available under a BSD license from <http://vtk.org>
28
+  Again--on Linux-- most package managers offer VTK. Compiling from source is not
29
+  terribly difficult, but requires installing CMake as well. 
26 30
 
31
+\note Some Lemma modules may impose additional (optional or mandatory) prerequisites, see the 
32
+      module documentation.  
27 33
 
28
-You will need to acquire the following free packages:
29
-- SCons - SCons is a make replacement that is written in Python. It is easily
30
-  configurable and directly controls the build process. It is not a Makefile
31
-  intermediary like some similar applications. It is freely available at
32
-  <http://scons.org>. On Linux, your package manager very likely provides this. On
33
-  Windows it is slightly more complicated. But, hey, Windows is easy... right? That's why 
34
-  you use it :)  The process is well documented on the SCons
35
-  website. You might guess that we aren't huge Windows fans.
36
-- Eigen3 - Eigen is a header-only linear algebra template library. It is made
37
-  available under the Gnu Lesser Public License. It is available at
38
-  <http://eigen.tuxfamily.org>. Please note that Lemma uses Version 3 of the Library.
34
+\section Prerequisites Prerequisites
35
+Lemma uses CMake to manage the build process (https://cmake.org). CMake is free software 
36
+that is easy to install on about any operating system.  
39 37
 
40 38
     \subsection Dependencies
39
+    Hard dependencies are 
40
+
41 41
     The only dependencies are the Eigen linear algebra Library v3, a
42 42
     C++ compiler and scons.
43
-    (Currently a fortran compiler is needed too, see above)
44 43
 
45 44
     The following compilers are fully supported and tested: gnu, mingw,
46 45
     and intelc. Several routines are parallelised for shared memory platforms
47 46
     using OpenMP. Any of the above compilers is able to be used with OpenMP.
48 47
     Microsoft's Visual C++ compiler will likely be supported for stable
49
-    releases, but is not actively tested. (Also the current FORTRAN compiler
50
-    dependency limits this compiler as well.) Eigen extensively uses template
48
+    releases, but is not actively tested. 
49
+    Eigen extensively uses template
51 50
     meta programming, the Borland compiler has been shown to be subpar at
52 51
     optimizing this type of code and will likely never be supported actively.
53 52
     A new compiler clang, is being developed and may prove to be promising as
@@ -63,19 +62,11 @@ You will need to acquire the following free packages:
63 62
     be included in stable releases of Lemma.
64 63
     Scons is a make replacement built on top of Python, and is also free.
65 64
 
66
-\section OptionalPrerequisites Optional Prerequisites
67
-- VTK - The Visualization ToolKit is a powerful data visualization framework. This is
68
-  an optional dependency, but some functionality will be missing without it. Any
69
-  version after 5.4 is fine. VTK is available under a BSD license from <http://vtk.org>
70
-  Again-- on Linux-- most package managers offer VTK. Compiling from source is not
71
-  terribly difficult, but requires installing CMake as well. Strangely (wink wink) this is 
72
-  harder under Windows.
73
-- Qt - Limited GUI support is provided leveraging the Qt framework. You will need to have 
74
-  the development version of Qt 4 installed to use this. 
75
-- Boost - Several classes use Boost. Lemma ships with a minimalist part of Boost and should compile 
76
-	without it. However, if you are getting Boost errors while compiling, install the development version 
77
-	 of boost. Note that Ubuntu ships with a very old Boost that has caused some issues. 
78
-	Also, the Python wrapper requires boost.python and is not shipped with Lemma. 
65
+- Eigen3 - Eigen is a header-only linear algebra template library. It is made
66
+  available under the Gnu Lesser Public License. It is available at
67
+  <http://eigen.tuxfamily.org>. Please note that Lemma uses Version 3 of the Library.
68
+
69
+
79 70
 
80 71
 \section Downloading Acquiring the source
81 72
 Lemma is currently available from svn checkout only. Note that while Lemma is still in Beta only

+ 26
- 11
Documentation/dox/mem.dox Visa fil

@@ -14,31 +14,46 @@ namespace Lemma{
14 14
 \section MemoryManagement Memory Management
15 15
 
16 16
 \subsection Reference Reference counting and memory management
17
-Lemma makes extensive use of reference counting. We do this for a variety of 
18
-reasons. 
19
-- It is not uncommon for multiple objects to have the same instantiations 
20
-of an object as members.
17
+
18
+\note Previous versions of Lemma used an internal reference counting mechanism, what 
19
+	is described below represents a significant change in the structure, philosophy, 
20
+	and internals of Lemma. To a large extent this has been possible due to changes 
21
+	in the C++ language specifications since C++-0x. These changes should improve the 
22
+	readability of Lemma code, decrease errors, improve performance, and reduce code length.
23
+	The C++-17 standard promises to close a remaining oddities in the Lemma API, discussed below. 
24
+
25
+Lemma relies heavily on smart pointer which utilize internal reference counting for several reasons: 
26
+- It is not uncommon for multiple objects to have the same instantiations of an object as members.
21 27
 - Making copies of each object is not a viable option because the objects may be large, and they must all update simultaneously.
22 28
 - Without reference counting it is very easy to leave dangling pointers.
23 29
 - It is much easier to write code, as local copies of objects can be deleted 
24 30
 as soon as they are no longer used within that context. The memory will not be 
25 31
 freed and the object persists as long as other objects still reference it.   
26 32
 
27
-The base class for all Lemma objects is ReferenceCountedObject. 
28
-The interface requires that all derived, non-abstract classes have <B>New</B> and <B>Delete</B> methods. So that objects may be created and destoyed with the 
29
-following syntax.
33
+The C++-0x standard introduced std::shared_ptr as a widely available, standard-compliant, high performance option to use 
34
+in instances like this. The other smart pointer types specifically weak_ptr and unique_ptr are less handy in our application. As such, 
35
+all Lemma classes expose a factory method returning a shared_ptr as the only publicly available means by which to construct objects. 
36
+Internally, in cases where higher performance can be realized, manual memory management is employed.  
37
+
38
+The base class for all Lemma objects is LemmaObject. 
39
+The interface requires that all derived, non-abstract classes have <B>NewSP</B> and <B>DeSerialize</B> methods. These methods are the only 
40
+mechanisms by which you should be creating Lemma objects. 
30 41
 
31 42
 \code 
32
-DerivedClass* Object = DerivedClass::New();
33
-Object->Delete();
43
+std::shared_ptr< DerivedClass > Object = DerivedClass::NewSP();
44
+// Or alternatively 
45
+auto Object2 = DerivedClass::NewSP();
34 46
 \endcode
35 47
 
36
-\warning It is important to note that the default constructors and destructors are protected so the following code is <B>NOT</B> valid.
48
+\warning It is important to note that the default constructors and destructors are inaccessible so the following code is <B>NOT</B> valid.
37 49
 \code 
38 50
 DerivedClass* Object = new DerivedClass;
39 51
 delete Object; 
40 52
 \endcode
41
-The reasons for this will hopefully be clear soon.
53
+Interestingly, the default constructors and destructors <B>are</B> public, however they are locked using a key struct 
54
+<a href=http://stackoverflow.com/questions/8147027/how-do-i-call-stdmake-shared-on-a-class-with-only-protected-or-private-const/8147326#8147326> (link)</a>. 
55
+The reason that this is necessary, is this arrangement allows for the use of std::make_shared to construct objects. The performance increase of this was 
56
+chosen over the higher overhead associated with making the default methods protected. 
42 57
 
43 58
 Many Lemma classes have other Lemma classes as data members. Classes may
44 59
 share these members, and depend on them being updated simultaneously. So 

+ 48
- 33
Documentation/dox/tutorial.dox Visa fil

@@ -21,28 +21,52 @@ namespace Lemma{
21 21
   | \ref EmSources "EM Sources"
22 22
   </div>
23 23
 
24
-Some basic information about Lemma to get you started. If you are familiar with
25
-C++ and API's you can skip this page.
26
-
27 24
 \section C Why C++?
28
-We get this a lot as most EM software seems to be written in fortran or Matlab. We
29
-begin by discussing why we didn't choose certain languages/platforms.
25
+We get this a lot as most EM software seems to be written in Fortran or Matlab. 
26
+C++ has developed into a fast powerful language appropriate for scientific computing. 
27
+The language is undeniably complex and can be intimidating (lots of bad C++ code is out there).
28
+However, it is also possible to generate high performance, intuitive, flexible software using 
29
+C++. In Lemma we take advantage of several recent changes to the language such that our public 
30
+interface is simple to use, does not require manual memory management, and lets scientists focus on 
31
+the problem at hand. The biggest hurdle for newcomers is often getting used to the object oriented 
32
+approach we have taken. Rather than provide programs performing specific tasks Lemma exposes a 
33
+flexible application programming interface (API) which can be though of as building blocks used 
34
+to construct programs or projects.   
35
+
36
+\subsection API An API? What's that?
37
+Lemma is not a program. It's an API, or an Application Programming Interface.
38
+This offers a lot of advantages over traditional programs. 
39
+- First, its flexible. Its easy to put together components to do exactly what 
40
+  you want and nothing more. 
41
+- Second, its extendible. If we have a class that does almost what you want, but is missing 
42
+  something, you can just extend a class. 
43
+- Third, it limits the amount of file IO you might need to do. We deviate from the Unix philosophy 
44
+  of piping text streams between small applications, mainly because doing so is difficult on some 
45
+  operating systems (I'm looking at you Windows), as well as cumbersome when used in graphical 
46
+  user interfaces.
47
+- Four, it enforces a consistent design and feel across the project. Once becoming familiar with 
48
+  how Lemma objects are constructed, it becomes simple to use new building blocks. Think of the 
49
+  objects as Lego's, since they are all constructed to work together, you can build anything. If 
50
+  instead you have a mix of Lego, Lincoln Logs, and Tinker Toys you will be more more limited 
51
+  in how you can use the pieces together.  
30 52
 
31
-\subsection  Fortran Why not fortran?
32
-We have  lots of reasons for choosing C++ over fortran, some of them better than others.
33
-- We know it better, and we like it better. Too many hours debugging old 
34
-  FORTRAN subroutines has left us jaded.
53
+\subsection  Fortran Why not Fortran?
54
+We have  lots of reasons for choosing C++ over Fortran, some of them better than others.
55
+- We know C++ better, and we like it better. Too many hours debugging old 
56
+  FORTRAN 77 subroutines has left us jaded.
35 57
 - Easy integration with existing libraries. For example Lemma has built in 
36 58
 support for VTK, an extremely powerful visualization package. We also include 
37
-MATLAB file IO readers and an XML parser. Providing fortran wrappers for all 
38
-of this would be a huge undertaking.
59
+MATLAB file IO readers, an XML parser, and YAML class serialization. Providing Fortran 
60
+wrappers for all of this would be a huge undertaking.
39 61
 - Flexibility. Lemma is NOT a program, its an API that lets you build 
40
- applications that fit your needs. This approach is a natural fit for object oriented
62
+ applications that fit your needs. This approach is a natural fit for object oriented (OO)
41 63
  programming and C++ is a much more natural choice for an OO project. 
64
+ In spite of advances in the language, Fortran is still more geared towards procedural 
65
+ programming paradigms (for better or worse). 
42 66
 - Infinitely better interface. We leverage the Eigen 
43 67
    <http://eigen.tuxfamily.org>  linear algebra package
44 68
   to deliver expressive, fast code. Their benchmarks are right in line with 
45
-  fast BLAS and LAPACK implimentations. If you honestly feel that 
69
+  fast BLAS and LAPACK implementations. If you honestly feel that 
46 70
 \code
47 71
 DGEMM ( TRANSA, TRANSB, M, N, K, ALPHA, A, LDA, B, LDB, BETA, C, LDC )
48 72
 \endcode  
@@ -50,35 +74,26 @@ DGEMM ( TRANSA, TRANSB, M, N, K, ALPHA, A, LDA, B, LDB, BETA, C, LDC )
50 74
 \code
51 75
   C = A*B.transpose(); 
52 76
 \endcode 
53
- you are living in denial. Check the benchmarks if you are still skeptical. 
54
-- We know fortran 2003 has come a long way, but hey, so has C++. Give it a 
77
+ you are living in denial. Check out the benchmarks if you are still sceptical
78
+http://eigen.tuxfamily.org/index.php?title=Benchmark 
79
+- We know Fortran has come a long way since FORTRAN 77, but hey, so has C++. Give it a 
55 80
 chance.
56 81
 
57
-\subsection Matlab Ok, so why not MATLAB?
58
-First its closed source, second most large MATLAB programs suffer severe 
59
-performance issues. Third, support for object-oriented programming is a joke. 
60
-Finally, its also expensive and we don't think the graphics are all
61
-that great.
82
+\subsection MATLAB Why not MATLAB?
83
+MATLAB is a closed source environment that is severely restrictive. The Lemma license is pro-business, 
84
+we are happy if Lemma is used in commercial code and programs. MATLAB code is expensive and difficult to 
85
+distribute in binary form. Also, the object oriented aspects of the MATLAB language feel a bit bolted on, and 
86
+cumbersome to use.  We prefer to avoid MATLAB for these reasons. 
62 87
 
63 88
 \subsection Python How about Python?
64
-We like Python. While large 100% native Python applications are often very slow, it is easy to wrap fast C++ and Fortran routines around a Python interface. 
65
-We actually plan on doing this in the future, and it is likely that at some 
66
-point this may be the most common way to use Lemma. Lots of great visualization
89
+We like Python. While large 100% native Python applications are often very slow, it is easy to wrap fast C++ and 
90
+Fortran routines around a Python interface. We actually plan on doing this in the future, and it is likely that at 
91
+some point this may be a common way to use Lemma. Lots of great visualization
67 92
 solutions exist in Python (including VTK) and it is a great programming environment. The hard
68 93
 part is that Eigen relies heavily on Expression templates that cannot be 
69 94
 trivially wrapped into a python interface. So any python interface would have 
70 95
 to be carefully constructed. We would welcome help in this department.
71 96
 In the mean-time our API is elegant and easy to use.
72
-
73
-\section API An API? What's that?
74
-Lemma is not a program. It's an API, or an Application Programming Interface.
75
-This offers a lot of advantages over traditional programs. 
76
-- First, its flexible. Its easy to put together components to do exactly what 
77
-  you want and nothing more. 
78
-- Second, its extendible. If we have a class that does almost what you want, you
79
-  can just extend a class. 
80
-- Third, it limits the amount of file IO you might need to do.
81
-- Four, there are lots of other good reasons too. Just give it a try. 
82 97
 */
83 98
 
84 99
 /** @} */

Laddar…
Avbryt
Spara