code structure

The structure of the code is as follows ...

  src/ploughshare.h   - ploughshare implementation
  src/ploughshare.cxx

  src/fploughshare.h  - fortran interface
  src/fploughshare.cxx 

  example/main.cxx   - c++ working example
  
  example/fmain.f    - fortran working example 
  example/fmainc.cxx - c++ wrapper for main - needed to allow 
                        linking using g++ including the fortran 
                        run time library

The ploughshare code allows easy access to specific datasets, donloading them automatically if required. It installs the datasets locally in the

  share/ploughshare

directory of the install directory specified with the

--prefix

option during the code installation. The datasets have a specific naming convention, for example,

   atlas-atlas-dijets-arxiv-1112.6297

which is broken down as follows ...

  atlas            group id
  atlas            experiment from which the data originate
  dijets           short info name to distinguist from other datasets 
  arxiv-1112.6297 arxiv identifier for this data set

The grids within a dataset are listed such as

  share/ploughshare/atlas/atlas-atlas-dijets-arxiv-1112.6297/grids/atlas-atlas-dijets-arxiv-1112.6297-xsec000.root
  share/ploughshare/atlas/atlas-atlas-dijets-arxiv-1112.6297/grids/atlas-atlas-dijets-arxiv-1112.6297-xsec001.root
  share/ploughshare/atlas/atlas-atlas-dijets-arxiv-1112.6297/grids/atlas-atlas-dijets-arxiv-1112.6297-xsec002.root
  share/ploughshare/atlas/atlas-atlas-dijets-arxiv-1112.6297/grids/atlas-atlas-dijets-arxiv-1112.6297-xsec003.root  
  ...

ie the name of the dataset is also encoded into the name of the specific grid for additional robustness, which is appended with the index of the grid in the dataset, as eg

  xsec000

example code

There are simple code examples for both the c++ and fortran interfaces in the example directory

c++ interface

The ploughshare interface in c++ is very straightforward to use. After creating the ploughshare object, the grid datasets that are required are obtained with the

  fetch() 

method, and are downloaded if required. Once the datset has been downloaded, they will not be downloaded again, and are instead stored in the local share/ploughshare directory in the install area. To use the grids, the user must obtain the full path for the downloaded grids to be opened and then these can be opened as usual eg ...

#include "ploughshare.h"

...

  ploughshare p; 

  p.fetch("atlas-atlas-wpm-arxiv-1612.0.0.13") 
 
  std::cout << "dataset grids: " << p.grids("atlas-atlas-wpm-arxiv-1612.0.0.13") << std::endl;

  std::vector < std::string > grids = p.grids("atlas-atlas-z0-arxiv-1109.5141");

  for ( size_t i=0 ; i<grids.size() ; i++ ) { 
    
    /// open grids as normal ...
    appl::grid g(grids[i]);
 
    ...

  }

Additional information on the dataset can also be accessed via the database entry for the dataset if required ...

  ploughshare::dataset_t  ds = p.dataset("atlas-atlas-dijets-arxiv-1312.3524");
  std::cout << "dataset path:  " << ds.path() << std::endl;
  std::cout << "dataset grids: " << ds.grids() << std::endl;

fortran interface

To use the fortran interface you need to link against PLOUGHSHARELIBS=$(shell ploughshare-config --ldfflags) for the fortran interface rather than the usual --ldflags from the c++ only interface Then you can use as in the following example ...

      subroutine pltest

c--      ploughshare return stuff --
         character*1024 gridpath
         integer        ngrids

c--      function protoypes --
         integer fetch
         integer getnbins


c--      returned cross section data --
         integer nbins
         double precision xsec(512)

c--      odds n ends --
         integer i, j

         integer idgrid
	 integer tgrid

c--      fetch the ploughshare dataset --         
         ngrids = fetch( "atlas-atlas-dijets-arxiv-1312.3524" )

	 idgrid = 0

         do i = 1, ngrids

c--         get the full path to specific grid in the data set --
            call getgridpath( "atlas-atlas-dijets-arxiv-1312.3524", i-1,
     &                         gridpath )

c--         the readgrid() call increments the id of the input grid
c--         so we need to keep a copy of the original value to 
c--         subsequently access the grid that has been read in
            tgrid = igrid

c--         read the grid as usual, id is the user specified  ---
            call readgrid( idgrid, gridpath )

c--         number of bins in this grid ---   
            nbins = getnbins( tgrid )

            write (6,*) i, " gridpath: ", gridpath, ": nbins ", nbins

c--         do the actual convolution ---
            call convolute( tgrid, xsec )

            do j=1, nbins
               write (6,*) j, "xsec = ", xsec(j)
            end do

         end do
      end

the call to fetch() with a dataset name, should download and install the grids, and also return how many grids there are in the data set. To get the path for each grid to actually be opened

  call getgridpath( ... )

This takes the dataset name, and the index of the grid in the dataset (remember that C++ counts from 0 rather than 1, hence the i-1) and it also requires a string variable to return the path.

The number of characters in the string must be enough to hold the returned path, otherwise it will throw an exception, as there would be no way to return the path.

The gridpath is the full path to the file to open, so everything can then proceed as normal.