How to do your first steps with Marlin

Newcomers are recommended to read the manual for a start to ILC software.

Getting the software environment

There are two different possibilities.

How to run Marlin for the first time ever (DESY PC, Scientific Linux 4/5)

Create a working directory, setup the environment and copy the examples

  mkdir MarlinWorkdir 
  cd MarlinWorkdir

Following you set the environment variables for Marlin in the current shell. If necessary (Marlin complains about missing libraries or cannot find processors), execute the following command again. It might be good idea to write it into a shell script and amend the paths of your own libraries later. Mind to execute this script with source! Note: 

  source /afs/desy.de/project/ilcsoft/sw/i386_gcc41_sl5/v01-11-pre03/init_ilcsoft.sh

Now you can copy the example processor: 

  cp -rp  $MARLIN/examples/mymarlin .
  cd mymarlin

In mymarlin you should find a CMakeLists.txt where you can set the project dependencies. You might want to add some dependencies, e. g. ROOT and MarlinReco: 

### DEPENDENCIES ############################################################

FIND_PACKAGE( ILCUTIL REQUIRED COMPONENTS ILCSOFT_CMAKE_MODULES )
FIND_PACKAGE( ROOT 5.27 )
FIND_PACKAGE( MarlinReco )

# load default settings from ILCSOFT_CMAKE_MODULES
INCLUDE( ilcsoft_default_settings )


FIND_PACKAGE( Marlin 1.0 REQUIRED ) # minimum required Marlin version
INCLUDE_DIRECTORIES( ${Marlin_INCLUDE_DIRS} )
LINK_LIBRARIES( ${Marlin_LIBRARIES} )
ADD_DEFINITIONS( ${Marlin_DEFINITIONS} )

FOREACH( pkg ROOT MarlinReco )
    IF( ${pkg}_FOUND )
        INCLUDE_DIRECTORIES( ${${pkg}_INCLUDE_DIRS} )
        LINK_LIBRARIES( ${${pkg}_LIBRARIES} )
        ADD_DEFINITIONS( ${${pkg}_DEFINITIONS} )
    ENDIF()
ENDFOREACH()

The CMakeLists.txt file does also define your compiler settings. You might notice that some of the currently installed processor will give error messages and fail to compile, if you try to do so yourself. In this case you have to remove the -pedantic flag 

# definitions to pass to the compiler
ADD_DEFINITIONS( "-Wall -ansi" )

Of course you should still write your own processors such, that they also compile with the -pedantic flag set.

Marlin uses the cmake tool to generate the makefile. You have to tell cmake the paths where to find the modules you would like to use, in this case Marlin, LCIO and RAIDA, which is the minimum to read an LCIO file and produce a histogram. An example cmake file is delivered with each ilcsoft version. Further modules can be added in an analogous way. cmake likes to have a build directory to store the output of make, i.e. you will find your libraries in MarlinWorkdir/build/lib. The make install command copies the stuff into your working directory, i.e. into MarlinWorkdir/lib. After that, the build directory could be removed. 

  mkdir build
  cd build
  cmake -C $ILCSOFT/ILCSoft.cmake ..
  make
  make install
  cd ..

You need two input files: An LCIO file with the events you would like to process and the GEAR file which holds the matching detector geometry.

Run Marlin

You have to set the MARLIN_DLL variable to tell Marlin where the shared library of your example processor can be found. Now you can run Marlin. At the first run you should get yourself an example steering file with the -x option. You might want to edit it and set the MaxRecordNumber to something small for the first try. 

  export MARLIN_DLL=$MARLIN_DLL:[path to your working directory]/lib/libmymarlin.so
  $MARLIN/bin/Marlin -x > test.xml

The xml-steering file

The test.xml file contains a very small section "execute". Only these processors will actually be called. For each of them and for all others, there are "processor" sections below. Note that the processor's class name is _not_ given under "name", but under "type". The "name" can be arbitrary as long as it is identical in the "execute" and "processor" sections. This allows to run the same algorithm twice with different parameters.

Open the test.xml in an editor (e.g. emacs test.xml &). Add the processor "MyMyProcessor" of type "MyProcessor" to the "execute" section. Now it should look like 

 <execute>
  <processor name="MyAIDAProcessor"/>
  <processor name="MyTestProcessor"/>  
  <processor name="MyMyProcessor"/>  
  <processor name="MyLCIOOutputProcessor"/>  
 </execute>

Then set "MaxRecordNumber" to 4 and the output format of "MyAIDAProcessor" to root. Insert your lcio file in "LCIOInputFiles" und the GEAR geometry file in "GearXMLFile". Run Marlin again: 

  $MARLIN/bin/Marlin test.xml

If that did not work, try the parameter -c (consistency check). Marlin will print out information about input files, collections etc. which might help to find the error. 

  $MARLIN/bin/Marlin -c test.xml

Now you should find a file aida_file.root which contains a histogram with the energy of all (!) MC particles.

Known "features" of recent versions

How to add a new processor to Marlin

If you followed the above, you have now a working processor of type MyProcessor, which you can modify and run. The next thing you probably would like to do is to actually add a new processor in a new directory.

You can also place several processors in the same directory (= same project = same library). For that purpose you only have to copy and rename the processor files, edit the steering file and recompile the processor as described above. Advantage: Less files to maintain when you switch to a new ilcsoft version.

How to use an external (static) library

Once you have your own processor, you may also want to use there code from another library, say "/pathtomylibrary/libmylib.a" which has it's include files in "/pathtomylibrary/include". If it doesn't happen to have a cmake module (which is of course preferred!), you can have do the following:

Then you can include the header files in MyProcessor.cc as with

include "include/someheaderfile.h"

in the # LIBRARY # section modify the line

TARGET_LINK_LIBRARIES( lib_${PROJECT_NAME} )

to

TARGET_LINK_LIBRARIES( lib_${PROJECT_NAME} "/pathtomylibrary/libmylib.a" )

or, better, add _before_ the ADD_LIBRARY command

LINK_DIRECTORIES( "/pathtomylibrary" )

LINK_LIBRARIES( mylib )

Marlin (last edited 2011-11-30 16:03:10 by MoritzBeckmann)