Dox updates

Documentation/dox/compiling.dox

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

Documentation/dox/mem.dox

@@ -14,31 +14,46 @@ namespace Lemma{
 \section MemoryManagement Memory Management
 
 \subsection Reference Reference counting and memory management
-Lemma makes extensive use of reference counting. We do this for a variety of 
-reasons. 
-- It is not uncommon for multiple objects to have the same instantiations 
-of an object as members.
+
+\note Previous versions of Lemma used an internal reference counting mechanism, what 
+	is described below represents a significant change in the structure, philosophy, 
+	and internals of Lemma. To a large extent this has been possible due to changes 
+	in the C++ language specifications since C++-0x. These changes should improve the 
+	readability of Lemma code, decrease errors, improve performance, and reduce code length.
+	The C++-17 standard promises to close a remaining oddities in the Lemma API, discussed below. 
+
+Lemma relies heavily on smart pointer which utilize internal reference counting for several reasons: 
+- It is not uncommon for multiple objects to have the same instantiations of an object as members.
 - Making copies of each object is not a viable option because the objects may be large, and they must all update simultaneously.
 - Without reference counting it is very easy to leave dangling pointers.
 - It is much easier to write code, as local copies of objects can be deleted 
 as soon as they are no longer used within that context. The memory will not be 
 freed and the object persists as long as other objects still reference it.   
 
-The base class for all Lemma objects is ReferenceCountedObject. 
-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 
-following syntax.
+The C++-0x standard introduced std::shared_ptr as a widely available, standard-compliant, high performance option to use 
+in instances like this. The other smart pointer types specifically weak_ptr and unique_ptr are less handy in our application. As such, 
+all Lemma classes expose a factory method returning a shared_ptr as the only publicly available means by which to construct objects. 
+Internally, in cases where higher performance can be realized, manual memory management is employed.  
+
+The base class for all Lemma objects is LemmaObject. 
+The interface requires that all derived, non-abstract classes have <B>NewSP</B> and <B>DeSerialize</B> methods. These methods are the only 
+mechanisms by which you should be creating Lemma objects. 
 
 \code 
-DerivedClass* Object = DerivedClass::New();
-Object->Delete();
+std::shared_ptr< DerivedClass > Object = DerivedClass::NewSP();
+// Or alternatively 
+auto Object2 = DerivedClass::NewSP();
 \endcode
 
-\warning It is important to note that the default constructors and destructors are protected so the following code is <B>NOT</B> valid.
+\warning It is important to note that the default constructors and destructors are inaccessible so the following code is <B>NOT</B> valid.
 \code 
 DerivedClass* Object = new DerivedClass;
 delete Object; 
 \endcode
-The reasons for this will hopefully be clear soon.
+Interestingly, the default constructors and destructors <B>are</B> public, however they are locked using a key struct 
+<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>. 
+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 
+chosen over the higher overhead associated with making the default methods protected. 
 
 Many Lemma classes have other Lemma classes as data members. Classes may
 share these members, and depend on them being updated simultaneously. So 

Documentation/dox/tutorial.dox

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