diff --git a/doc/main.dox b/doc/main.dox --- a/doc/main.dox +++ b/doc/main.dox @@ -1,245 +1,245 @@ /** @mainpage @tableofcontents @section intro Introduction LHAPDF is a general purpose C++ interpolator, used for evaluating PDFs from discretised data files. Previous versions of LHAPDF were written in Fortran 77/90 and are documented at http://lhapdf.hepforge.org/lhapdf5/. LHAPDF6 vastly reduces the memory overhead of the Fortran LHAPDF (from gigabytes to megabytes!), entirely removes restrictions on numbers of concurrent PDFs, allows access to single PDF members without needing to load whole sets, and separates a new standardised PDF data format from the code library so that new PDF sets may be created and released easier and faster. The C++ LHAPDF6 also permits arbitrary parton contents via the standard PDG ID code scheme, is computationally more efficient (particularly if only one or two flavours are required at each phase space point, as in PDF reweighting), and uses a flexible metadata system which fixes many fundamental metadata and concurrency bugs in LHAPDF5. Compatibility routines are provided as standard for existing C++ and Fortran codes using the LHAPDF5 and PDFLIB legacy interfaces, so you can keep using your existing codes. But the new interface is much more powerful and pleasant to work with, so we think you'll want to switch once you've used it! LHAPDF6 is documented in more detail in http://arxiv.org/abs/1412.7420 @section installsec Installation The source files can be downloaded from https://www.hepforge.org/downloads/lhapdf Full installation and troubleshooting details are given at @ref install . @section sets Official PDF sets -In the move to LHAPDF6 we have migrated the most recent PDF set families of each -major PDF fitting group from LHAPDF5 to the new unified LHAPDF6 format. With a -few exceptions for particularly significant older PDF sets, this means an -effective age cutoff of ~2005 on the migrated sets. - -If you need older sets you are encouraged to convert the LHAPDF5 version to -LHAPDF6's data format: see the @ref migration page for details of this -procedure. We do not provide support for LHAPDF5, and a very strong case will -be needed for further "official" set migrations beyond the many already available -in LHAPDF6. - The following link takes you to the PDF sets which are currently available and officially supported: - @ref pdfsets The PDF set data files can be downloaded from -https://www.hepforge.org/archive/lhapdf/pdfsets/ and the latest versions are -installed (as tarballs and expanded into directories) on CERN CVMFS at +http://lhapdfsets.web.cern.ch/lhapdfsets/current/ +which is also available via CERN CVMFS at `/cvmfs/sft.cern.ch/lcg/external/lhapdfsets/current/`. Many users will find it easiest to just set their `LHAPDF_DATA_PATH` environment variable to point at this distributed filesystem area and use the preinstalled latest sets there. We also provide a script called `lhapdf` which can be used to query the catalogue of PDF sets and to install and update them from the command line. The user interface of this script is inspired by the Debian Linux `apt` package management system -- it accepts commands `list`, `update`, `install` and `upgrade`. Please run `lhapdf help` for full usage instructions. Please note that this script currently requires the LHAPDF library to have been built and installed with Python support. +The most recent PDF set families of each major PDF fitting group from LHAPDF5 +were migrated to the unified LHAPDF6 format. With a few exceptions for +particularly significant older PDF sets, this means an effective age cutoff of +~2005 on the migrated sets. + +If you need older sets you are encouraged to convert the LHAPDF5 version to +LHAPDF6's data format: see the @ref migration page for details of this +procedure. We do not provide support for LHAPDF5, and a very strong case will +be needed for further "official" set migrations beyond the many already available +in LHAPDF6. + If you want to add new PDF sets to the standard collection, please contact the LHAPDF authors at lhapdf@projects.hepforge.org. You are expected to create and validate these PDF data files yourself, and to fix and update them in the case of user-reported bugs in the public files. We will allocate appropriate PDF ID codes, which will need to be added to your new sets' `.info` files, and manage the indexing and distribution of the new files. Thanks for your support! @section usage Usage As for previous versions, LHAPDF6 is a programmatic library. It can be accessed via user code written in C++, and to a more limited extent from Python and Fortran programs. PDF sets (each of which is stored in a unique filesystem directory) should usually be installed in the `$prefix/share/LHAPDF/` directory (i.e. the PDF dirs are at the same level as the global `lhapdf.conf` file). To make use of PDF sets installed in other places, those search paths should be listed in the `LHAPDF_DATA_PATH` environment variable. [`LHAPDF_DATA_PATH` is an extension of the old `LHAPATH` variable which supports multiple search paths separated by colon (`:`) characters, cf. standard system paths like `PATH`, `LD_LIBRARY_PATH`, etc.] Here are some reference documents on the library design and the system of PDF/set/config metadata flags: - Design rationale: @ref design - PDF metadata flags: @ref config Many code usage examples are collected here: - Code examples: @ref codeexamples @subsection buildagainst Building against LHAPDF Using LHAPDF through Python just requires that the LHAPDF library and module be installed, then you can use it: there are no compilation or linking complexities. For C++ and Fortran, however, you need to compile your code against LHAPDF, which introduces some extra technical hurdles. Building your own program that uses LHAPDF6 is aided by the `lhapdf-config` script which can among other things produce the compiler flags needed to use LHAPDF. These include the `-I/path/to/include` flag to indicate the position of installed LHAPDF header files, and `-L/path/to/lib -lLHAPDF` flags for the library linker. The script is used in a compilation/linking command like this: g++ mycode.cc -o myexe `lhapdf-config --cflags --ldflags` If you are compiling a Fortran program against LHAPDF, the header files are not relevant, but the library details are. You will also need to explicitly link against the C++ standard library, which is done implicitly by C++ compilers: gfortran mycode.f90 -o myexe `lhapdf-config --ldflags` -lstdc++ @subsection runtimeld Runtime symbol resolution Finally, note that LHAPDF is primarily available as a "dynamic" shared library, i.e. a `.so` or `.dylib` (Mac) rather than a static `.a` library. The dynamic library needs to be found at runtime as well as at compile/link time. If your code compiled fine, but you get errors about "missing symbol" when you try to run your program, you probably need to add the LHAPDF lib directory path to your `LD_LIBRARY_PATH` environment variable (or `DYLD_LIBRARY_PATH` on Macs): export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:/path/to/lib @subsection strip Trick to remove unwanted PDF members A typical LHAPDF6 PDF set with error members is between 20 and 100 MB in size. If you only intend to use a subset of these (e.g. in MC production where you will only use the central member), you can simply remove the unneeded `.dat` files from the PDF set directory. It will work fine, as long as you don't try to load one of the missing members of course! In grid job submissions this can reduce the tarball of data that you send with your job by a large amount, since PDF sets often dominate such job tarballs. @subsection zip Trick to use zipped data files For special applications where PDF initialization speed or disk space are _very_ critical, you may wish to use zipped PDF data files. Since the data files are plain text, they compress well, by a factor of 4 or so, but for most applications this is largely irrelevant since you will usually not need to install more than about 100 MB of data files to use the main modern PDF sets, and set initialisation time is less than one second... and that happens only once per run. Actually reading zipped data files would make LHAPDF's code and (more importantly) build process much more awkward, so we haven't done that. However, if you really need to squeeze the maximum out of limited space and time then there is a trick you can play -- at least on Linux systems -- using `LD_PRELOAD`. This environment variable specifies libraries to be loaded before starting a process, and is a mechanism for replacing system library functions with modified versions. In this case, we can override the `open("foo")` function with a version which will attempt to transparently read `foo.gz`, uncompressed into the `/tmp` directory, by setting `LD_PRELOAD=/lib/uncompress.so` in your job. See the [zlibc](http://www.delorie.com/gnu/docs/zlibc/zlibc.3.html) documentation for more details. LHAPDF6 itself needs no modification, but you will need to `cd` into your PDF sets and run `for i in *.dat; do gzip $i; done` in each one that you want to compress. This is rather a hack and may not work on Macs... but it can be useful in special circumstances. Please let us know your experiences if you use it! @section authors Authors @include AUTHORS @section support Support and bug reporting If you need assistance with LHAPDF, please contact the authors at lhapdf@projects.hepforge.org . Please also send feature suggestions to this address: please don't contact individual developers if you can avoid it. We also accept compliments ;-) You are _very_ strongly advised to make sure that you are running the latest version of the LHAPDF library, since issues are often fixed in later releases. Please supply some information about which version you are using, what type of system and compiler you are using, a copy of the LHAPDF config.log file, a reasonably full copy of the errors you are getting, and the output of downloading and running this script: https://users.hepforge.org/~buckley/sysdebug.sh . Please do not send us screenshots of your terminal! To capture the output of a command, use a shell redirection like this: `make &> makelog.txt` or `bash sysdebug.sh &> sysdebug.txt` (you may prefer to use a redirection like `|& tee foolog.txt` but probably you don't need our advice if you have such preferences!) Lastly, please try to _read_ the configure/compiler/runtime error message: once decoded it may tell you something simple e.g. you have not got the required compiler, you are compiling against a 32 bit library on a 64 bit system, or you have not installed a PDF data file. If you can't parse the error messages then try Googling for generic-looking bits of the message before asking for direct assistance: there are often good explanations and solutions online. @section dev For developers To check out LHAPDF6 from Mercurial, use this command for read-only: `hg clone https://phab.hepforge.org/source/lhapdfhg/`, and this for read-write: `hg clone ssh://vcs@phab.hepforge.org/source/lhapdfhg` (requires a HepForge login account.) See the following pages: - Code browser: https://lhapdf.hepforge.org/files.html - @ref todolist - @ref todo - @ref migration - @ref codingstyle - @ref design @todo Add some developer build guides, including the autotools, Cython, etc. gotchas. @example ../examples/testpdf.cc @example ../examples/pythonexample.py @example ../examples/compatibility.cc @example ../tests/testgrid.cc @example ../tests/testinfo.cc @example ../tests/testindex.cc @example ../tests/testpaths.cc @example ../tests/testalphas.cc @example ../examples/analytic.cc @example ../examples/testpdfunc.cc */