ploughshare is hosted by Hepforge, IPPP Durham


Documentation

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 stores the datasets locally in installed
  share/ploughshare
directory with a specific naming convention, eg
   atlas-atlas-dijets-arxiv-1112.6297
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 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 example code 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 grids = p.grids("atlas-atlas-z0-arxiv-1109.5141");

  for ( size_t i=0 ; i&ltgrids.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.