Added Doxygen documentation generation. Currently not build by default, use make doc for that.

CMakeLists.txt

@@ -186,3 +186,14 @@ target_link_libraries(Hello lemmacore)
 add_dependencies(Hello YAML-CPP)
 
 
+# add a target to generate API documentation with Doxygen
+find_package(Doxygen)
+	if(DOXYGEN_FOUND)
+	configure_file(${CMAKE_CURRENT_SOURCE_DIR}/Documentation/Doxyfile.in ${CMAKE_CURRENT_BINARY_DIR}/Documentation/Doxyfile @ONLY)
+	add_custom_target(doc
+	${DOXYGEN_EXECUTABLE} ${CMAKE_CURRENT_BINARY_DIR}/Documentation/Doxyfile
+	WORKING_DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}
+	COMMENT "Generating API documentation with Doxygen" VERBATIM
+	)
+	endif(DOXYGEN_FOUND)
+

Documentation/dox/compiling.dox

@@ -0,0 +1,123 @@
+namespace Lemma{
+
+/**
+    \page Compiling
+
+<div class="lemmamainmenu"> 
+    \ref Intro     "Intro"
+  | \b   Compiling
+  | \ref Memory    "Memory management"
+  | \ref Minimal   "Minimal programme"
+  | \ref EmSources "EM Sources"
+</div>
+
+Compiling Lemma is fairly straightforward. The biggest hurdle is possibly installing
+the prerequisites, but on many platforms this is easy.
+
+\section Table Table of contents
+- \ref Prerequisites
+- \ref OptionalPrerequisites
+- \ref Downloading
+- \ref Configuring
+- \ref Building
+
+\section Prerequisites Prerequisites
+
+
+
+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.
+
+    \subsection Dependencies
+    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
+    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
+    well, but current C++ support is lacking. If you are using a different
+    compiler, please share your experiences with us.
+
+    The Visualization ToolKit (VTK) is used for visualisation throughout Lemma.
+    It is not an explicit dependency, but without it, you will not be able to
+    get any graphical output.
+
+    Eigen is  freely available  under the LGPL at
+    <http://eigen.tuxfamily.org>. The necessary components of Eigen will
+    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. 
+
+\section Downloading Acquiring the source
+Lemma is currently available from svn checkout only. Note that while Lemma is still in Beta only
+developers have access to the source code. Contact us if you would like to contribute. 
+\code
+svn co https://svn.lemmasoftware.org/lemma/trunk Lemma
+\endcode
+
+\section Configuring Configuring
+There is very little configuring to do. In the main Lemma directory you will find a file 
+called 'Examplesettings.py listed below'
+\include Examplesettings.py
+Configure this to your machine, and copy to a file named
+\code
+settings.py
+\endcode
+
+ If you have more questions about a parameter you can type
+\code
+scons -h
+\endcode
+For more information. After configuring, copy Examplesettings.py to a file called settings.py.
+
+\section Building
+To build the libraries simply type:
+\code
+scons  -j2
+\endcode
+To build the libraries and unit tests. The -j2 arguments tell scons how many threads compilation
+should occur on (parallel build). We recommend one per processor. Note, this only affects 
+the speed of the build, not whether or not Lemma will have OpenMP support.
+
+\section Installing
+To install the library simply type:
+\code
+scons  install
+\endcode
+To install to INSTALLDIR. Note depending on your machine, you may need sudo privileges to do this.
+Also, if you let INSTALLDIR=./lib this step will fail as those libraries are already located in Lemma/lib.
+
+Note that on a Mac, this step is crucial.    
+
+*/ 
+/** @} */ 
+}

Documentation/dox/emsource.dox

@@ -0,0 +1,72 @@
+namespace Lemma{
+
+/** 
+    \page EmSources 
+
+<div class="lemmamainmenu">             
+    \ref Intro     "Intro"
+  | \ref Compiling "Compiling"
+  | \ref Memory    "Memory management "
+  | \ref Minimal   "Minimal programme"  
+  | \b EM \b Sources
+</div>
+
+We support the following dipole types: 
+- Grounded electric
+- ungrounded electric
+- magnetic
+Each in horizontal and vertical polarizations. Dipoles may be placed anywhere in a model.
+
+\code
+    DipoleSource *dipole = DipoleSource::New();
+        dipole->SetType(GROUNDEDELECTRICDIPOLE);
+        dipole->SetPolarisation(XPOLARISATION);
+        //dipole->SetPolarisation(YPOLARISATION);
+        //dipole->SetPolarisation(ZPOLARISATION);
+
+        //dipole->SetType(UNGROUNDEDELECTRICDIPOLE);
+        //dipole->SetPolarisation(XPOLARISATION);
+        //dipole->SetPolarisation(YPOLARISATION);
+        //dipole->SetPolarisation(ZPOLARISATION);
+
+        //dipole->SetType(MAGNETICDIPOLE);
+        //dipole->SetPolarisation(XPOLARISATION);
+        //dipole->SetPolarisation(YPOLARISATION);
+        //dipole->SetPolarisation(ZPOLARISATION);
+
+        dipole->SetMoment(1);
+        dipole->SetLocation(1,1,-1e-4);
+        dipole->SetNumberOfFrequencies(1);
+        dipole->SetFrequency(0,2000);
+        dipole->SetPhase(0);
+\endcode
+Each of the above dipole types is shown in this example. Note the use of enumerations (ALLCAPS) instead of integer markers,
+making the code immediately obvious. The location is set in x,y,z order. A right hand coordinate system is used with 
+a pointing down. So this dipole is just in the air. 
+Only a sinlge frequency is computed, at 2000 Hz, and the phase is set to zero.
+
+\section Other Other sources
+Currently we also support arbitrary ungrounded wire loops. We plan to support grounded wire loops in the near future as well.
+
+For our example we will construct a wire antenna loop. To do this insert this code into your skeleton application shown on the previous page.
+
+\code 
+    PolygonalWireAntenna *pa = PolygonalWireAntenna::New();
+        pa->SetNumberOfPoints(5);
+        pa->SetPoint(0, Vector3r(   0,   0, -1e-3));
+        pa->SetPoint(1, Vector3r( 100,   0, -1e-3));
+        pa->SetPoint(2, Vector3r( 100, 100, -1e-3));
+        pa->SetPoint(3, Vector3r(   0, 100, -1e-3));
+        pa->SetPoint(4, Vector3r(   0,   0, -1e-3));
+        pa->SetNumberOfFrequencies(2);
+        pa->SetFrequency(0, 1000);
+        pa->SetFrequency(0, 5000);
+        pa->SetCurrent(10);
+        pa->SetNumberOfTurns(1);
+\endcode
+The code is basically self-explanitory. We are constructing a single turn wire loop with 5 points. The first and last 
+point are the same making this a loop, but that is not a requirement. All loops must be 'closed' in this fashion.
+We are interested in two frequencies: 1 and 5 kHz and we have a 10 A current running through a single turn wire.
+*/
+
+}

Documentation/dox/extending.dox

@@ -0,0 +1,7 @@
+namespace Lemma {
+
+/** 
+	\page Extending Extending
+	A page outlining how to extend Lemma classes.
+*/
+}

Documentation/dox/mem.dox

@@ -0,0 +1,101 @@
+namespace Lemma{
+
+/** 
+    \page Memory 
+
+<div class="lemmamainmenu"> 
+    \ref Intro     "Intro"
+  | \ref Compiling "Compiling"
+  | \b   Memory \b management 
+  | \ref Minimal   "Minimal programme"  
+  | \ref EmSources "EM Sources"
+</div>
+
+\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.
+- 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.
+
+\code 
+DerivedClass* Object = DerivedClass::New();
+Object->Delete();
+\endcode
+
+\warning It is important to note that the default constructors and destructors are protected 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.
+
+Many Lemma classes have other Lemma classes as data members. Classes may
+share these members, and depend on them being updated simultaneously. So 
+that a situation like this is not unusual. 
+\code 
+DerivedClass* Component = DerivedClass::New();
+AnotherDerivedClass* Object2 = AnotherDerivedClass::New();
+YetAnotherDerivedClass* Object3 = YetAnotherDerivedClass::New();
+Object2->AttachMyComponent(Component);
+Object3->AttachMyComponent(Component);
+Component->Update();       // All three classes use the updated Component
+\endcode
+At this point both Object2 and Object3 have an up to date Component and any 
+changes to Component can be seen by the Objects. Often these types of 
+connections are happening behind the scenes and end users should not be 
+troubled by any of this.
+
+Now in this example it is clear that if Component is deleted, than the objects 
+will contain dangling pointers. To avert this, calling the 
+ReferenceCountedObject::Delete() does not necessarily destroy the object.
+So that it would be safe -- continuing from the above example
+\code
+Component->Delete();                     // The 'Component' handle will no longer be used.
+Object2->CallMethodRelyingOnComponent(); // But we can still use the object
+\endcode
+
+\subsection what Whats going on?
+Whenever we declared a new handle to the object-- either by calling New, or implicitly in the Connect methods--
+the true 'Component' object updated a list of pointers that had handles to it. 
+
+\code
+DerivedClass* Component = DerivedClass::New();       // One Reference, 'Component'
+Object2->AttachMyComponent(Component);               // Two References, internal in Object2       
+Object3->AttachMyComponent(Component);               // Three References, internal in Object3
+Component->Delete();                                 // Two References, 'Component' is gone. 
+                                                     // DON'T USE Component->Method() ANYMORE!!!
+Object2->Delete();                                   // One Reference, Object2 releases handle upon Delete
+Object3->SomeFuntionReleasingComponent();            // Zero References, Component object is now deleted and
+                                                     // all memory is freed!
+\endcode
+
+\section So So what do I need to know?
+Not much. This is here to make life easy when doing high level programming. Just follow these simple rules
+- Allocate and free all variables with New and Delete, you have to do this as the default 
+versions are protected.
+
+- Once calling Delete on an object it is no longer safe to use that handle. For example don't call 
+Component->Delete(), and then call Component->Method(). Even if you 'know' that there are existing references
+and that it shouldn't have been deleted yet. Instead move your call to Delete down after your last direct use
+of each class. 
+
+- Remember to call Delete, thanks to reference counting it is safe to do this as soon as you are done 
+ using an object even if other classes are using it. If  you don't call Delete on objects you create, your
+ program <B>will</B> leak memory!
+
+- Revel in the fact that memory is being managed for you, and that dangling pointers are not a concern.
+
+*/
+
+}

Documentation/dox/min.dox

@@ -0,0 +1,153 @@
+namespace Lemma{
+
+/** 
+\page Minimal 
+
+<div class="lemmamainmenu"> 
+    \ref Intro     "Intro"
+  | \ref Compiling "Compiling"
+  | \ref Memory    "Memory management"
+  | \b   Minimal \b programme
+  | \ref EmSources "EM Sources"
+</div>
+
+\section Download Download
+Lemma source code may be obtained via svn server 
+\code
+svn co http://cgem.ath.cx/repos/MR/Lemma Lemma
+\endcode
+
+Binary versions of the library for Microsoft Windows will be available for download shortly.
+
+To compile you will also need the Eigen3 linear algebra header library, freely available at
+<http://eigen.tuxfamily.org>. 
+We use the scons, a make replacement for builds which is available at <http://scons.org>.
+Finally a good C++ compiler is needed. We actively support gcc, intel, and 
+Microsoft Visual C++ 2010. Your mileage may vary with other compilers. Lemma has been sucessfully compiled on 
+Microsoft Windows, Mac OSX, many flavours of Linux 64 and 32 bit, and BSD's.  
+
+\section Exposing Exposing the API
+You may choose to either include individual pieces of Lemma, or instead to simply 
+include all of Lemma using '#include Lemma'. Examples will be shown both ways but 
+generally speaking including all of Lemma is a fine thing to do. All of the objects 
+are defined within the Lemma namespace, so you may want to use that, too.
+\code
+#include "Lemma"  
+using namespace Lemma;
+int main() {
+    // Any Lemma Code is OK
+} 
+\endcode
+
+\section Compiling_old
+Compiling Lemma code is fairly straightforward. For example using g++ 
+\code
+	g++ min.cpp -I/path/to/Lemma/include -L/path/to/Lemma/lib -llemma -lmatio -lticppd -lem1d 
+\endcode
+
+\subsection Libs Whoa, what are all those libs
+Compiling Lemma builds several libraries. The largest one is liblemma.so(dll). This contains all the Lemma classes.
+The libmatio is responsible for reading in MATLAB files and libticcppd is an XML reader/writer/parser. The libem1d library is a FORTRAN implimentation of a dipole em solver that is used for quality control and assurance. 
+We use scons to build Lemma. It is easy to extend scons to compile your applications as well, taking care of all 
+the compiler linker details.
+
+\section VTK 
+Lemma can be integrated with VTK to produce data visualizations. Using the VTK interfaces is a slightly more advanced
+topic and will be handled in a later tutorial.
+
+\section Small Small example application.
+We will now spend the next few pages building a Lemma application that computes fields from a wire loop in a time domain survey.
+
+When forward modelling geophysical data, it is natural to break up what is needed into several catagories: the transmitter, the receiver, the earth model, and the specific instrument.  In fact, these are exactly the classes needed by Lemma to execute a forward model.  Therefore, the first step will be to define these classes.  Continuing the code from above, we add class constructors:
+\code
+#include "Lemma"
+using namespace Lemma;
+int main() {
+	PolygonalWireAntenna* Trans = PolygonalWireAntenna::New();
+	ReceiverPoints* Receivers = ReceiverPoints::New();
+	LayeredEarthEM *Earth = LayeredEarthEM::New();
+
+	// More Lemma code to go here
+
+	return EXIT_SUCCESS;
+}
+\endcode
+
+Now that we have created objects for a transmitter, a receiver, and a layered earth model, we need to populate them with their appropriate parameters.
+
+For the transmitter, we will define a 100 metre by 100 metre loop just above the surface of the Earth with 1 A current and one turn.  We input the following after our new objects:
+
+\code
+	Trans->SetNumberOfPoints(5);
+	Trans->SetPoint(0, Vector3r(   0,   0, -1e-3));
+	Trans->SetPoint(1, Vector3r( 100,   0, -1e-3));
+	Trans->SetPoint(2, Vector3r( 100, 100, -1e-3));
+	Trans->SetPoint(3, Vector3r(   0, 100, -1e-3));
+	Trans->SetPoint(4, Vector3r(   0,   0, -1e-3));
+	Trans->SetCurrent(1);
+	Trans->SetNumberOfTurns(1);
+\endcode
+
+For the receiver location, we'll put one receiver in the centre of the transmitter loop.
+
+\code
+	Vector3r loc;
+	Real ox = 50.;
+	Real oy = 50.;
+	Real depth = -1.e-3;
+	Receivers->SetNumberOfReceivers(1);
+	loc << ox,oy,depth;
+	Receivers->SetLocation(0,loc);
+\endcode
+
+We now set our 5 layer earth model up, with conductivities in S/m.  The 5 layers include the air and basement halfspace.
+
+\code
+	Earth->SetNumberOfLayers(5);
+	Earth->SetLayerConductivity( (VectorXcr(5) << 0.,1.e-4,1.e-2,
+		1.e-4,1.e-6).finished() );
+	Earth->SetLayerThickness( (VectorXr(3) << 10,5,50).finished() );
+\endcode
+
+Finally, we set up an instrument object and attach these objects to it.  Since this is a time domain survey, we also define and attach the centre-gate times for a particular instrument.
+
+\code
+	VectorXr maintimes;
+	maintimes.resize(25);
+	maintimes << 	191.,216.,246.,286.,336.,400.,480.,584.,
+		714.,883.,1097.,1366.,1714.,2157.,2724.,3445.,4361.,
+		5535.,7032.,8858.,10724.,13151.,16196.,20047.,25012.;
+	maintimes = maintimes.array() /1000000;
+	InstrumentTem *instrument = InstrumentTem::New();
+	instrument->EMEarthModel(Earth);
+	instrument->SetTransmitLoop(Trans);
+	instrument->SetReceiver(Receivers);
+	instrument->SetTimes(maintimes);
+\endcode
+
+We are now ready to make the calculation and get our results.
+
+\code
+	instrument->MakeCalculation();
+	// Output results to file
+	std::ofstream outfile1;
+	outfile1.open("solution.out");
+	for (int ii=0;ii<ntimes;ii++) {
+		outfile1 << instrument->GetMeasurements()(ii,0)<<"    "<<
+			instrument->GetMeasurements()(ii,1)<<std::endl;
+	}
+	outfile1.close();
+
+	//A little cleanup
+	instrument->Delete();
+	Trans->Delete();
+	Earth->Delete();
+	Receivers->Delete();
+\endcode
+
+Congrats! You have used Lemma to create a forward modelling program.  Hopefully now you can see how easy it is to use Lemma to create powerful programs.
+
+
+*/
+}
+//\include utdipolesource.cpp

Documentation/dox/tutorial.dox

@@ -0,0 +1,85 @@
+namespace Lemma{
+
+/**
+    \page   Tutorial
+
+   A basic tutorial outlining the goals of Lemma, how to acquire and use it, and how to extend it 
+   for your own purposes. 
+
+   - \subpage Intro - Introduction to the project
+   - \subpage Compiling - how to compile the library
+   - \subpage Memory - our implementation of garbage collection, and what it means to you
+   - \subpage Minimal - compiling your first minimal Lemma application
+   - \subpage EmSources - Electromagnetic sources
+    
+  \page   Intro
+  <div class="lemmamainmenu">  
+    \b   Intro      
+  | \ref Compiling "Compiling"
+  | \ref Memory    "Memory management"
+  | \ref Minimal   "Minimal programme"  
+  | \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.
+
+\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.
+- 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.
+- 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
+ programming and C++ is a much more natural choice for an OO project. 
+- 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 
+\code
+DGEMM ( TRANSA, TRANSB, M, N, K, ALPHA, A, LDA, B, LDB, BETA, C, LDC )
+\endcode  
+ is superior to
+\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 
+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 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
+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. 
+*/
+
+/** @} */
+}