README

===========
pyAMI.atlas
===========

pyAMI 5 is a major upgrade of the AMI python client. The command line syntax
has been rationalized, with improved help functions. The code has been split
into a core layer and an experiment specific layer. This documentation is
specific for the ATLAS layer.

pyAMI is available in the ATLAS software release and also installed centrally
on LXPLUS (CVFMS and AFS). pyAMI can be installed standalone on a laptop.
Instructions are given below for Linux, OSX and Windows.

.. warning:: All commands are simply subcommands of ``ami_atlas``. On centrally
    installed versions of pyAMI we have made an alias so that ``ami`` is
    redirected to ``ami_atlas`` and the instructions below are for this installation.

.. note:: The legacy version of pyAMI (pyAMI 4.1.3) is documented `here <https://ami.in2p3.fr/pyAMI-4.1.3/>`__.

A few examples
==============

List runs for 2012 in a period or multiple periods::

    ami list runs --year 12 --data-periods A B

List AOD datasets matching a pattern::

    ami list datasets --type AOD data14_cos%

Display dataset information::

    ami show dataset info data13_2p76TeV.00219364.physics_MinBias.merge.NTUP_HI.f519_m1313

Display dataset provenance::

    ami show dataset prov data13_2p76TeV.00219364.physics_MinBias.merge.NTUP_HI.f519_m1313

List the files in a dataset:: 

    ami list files -LHC data13_2p76TeV.00219364.physics_MinBias.merge.NTUP_HI.f519_m1313

.. note:: pyAMI also provides an API allowing you to perform all of the same queries from within your own Python program.

LXPLUS (CVMFS and AFS)
======================

pyAMI is installed centrally on LXPLUS at CERN. To begin using pyAMI simply::

    export ATLAS_LOCAL_ROOT_BASE=/cvmfs/atlas.cern.ch/repo/ATLASLocalRootBase
    source $ATLAS_LOCAL_ROOT_BASE/user/atlasLocalSetup.sh
    localSetupPyAMI

pyAMI is also available through AFS::

    source /afs/cern.ch/atlas/software/tools/pyAMI/setup.sh

Standalone installation
=======================

pyAMI 5 is compatible with Python 2.6, 2.7 and 3.X.

Automatic installation for LINUX and MAC OSX
--------------------------------------------

.. warning:: If you have an earlier version of pyAMI installed please uninstall it first: ``pip uninstall pyAMI``

Automatically install the latest version of pyAMI with `pip <http://pypi.python.org/pypi/pip>`_::

    pip install --user pyAMI_atlas

or with ``easy_install`` (deprecated)::

    easy_install --user pyAMI_atlas

Omit the ``--user`` for a system-wide installation (requires root privileges).
Add ``${HOME}/.local/bin`` to your ``${PATH}`` if using ``--user`` and if it
is not there already (put this in your .bashrc)::

    # For LINUX
    export PATH=${HOME}/.local/bin${PATH:+:$PATH}

    # For MAC OSX
    export PATH=${HOME}/Library/Python/2.7/bin${PATH:+:$PATH}

Execute the post-install script::

    ami_atlas_post_install

To upgrade an existing installation with `pip <http://pypi.python.org/pypi/pip>`_::

    pip install --upgrade pyAMI_core
    pip install --upgrade pyAMI_atlas
    ami_atlas_post_install

or with ``easy_install`` (deprecated)::

    easy_install --upgrade pyAMI_core
    easy_install --upgrade pyAMI_atlas
    ami_atlas_post_install

Automatic installation for WINDOWS
----------------------------------

.. warning:: If you have an earlier version of pyAMI installed please uninstall it first: ``pip uninstall pyAMI``

1. Install `Python 2.7.X <https://www.python.org/downloads/>`_

2. ``python.exe`` should be in ``C:\Python27``. You must adjust your paths in the
   Windows environment. If you do not know how to do this follow the instructions
   here `www.java.com/en/download/help/path.xml <http://www.java.com/en/download/help/path.xml>`__.
   Add to the path::

    C:\PYTHON27;C:\PYTHON27\Scripts

3. Download and install `pip <https://bootstrap.pypa.io/get-pip.py>`__
   (for easy installation of dependences)::

    python get-pip.py

4. Install pyAMI::

    pip install pyAMI_atlas

5. Execute the post-install script::

    ami_atlas_post_install

To upgrade an existing installation::

   pip install --upgrade pyAMI_core
   pip install --upgrade pyAMI_atlas
   ami_atlas_post_install

Authentication
==============

VOMS authentication is supported::

    voms-proxy-init -voms atlas

If gLite is not available, the alternative option is to connect with your
username and password. You can set up an encrypted configuration file by running::

    ami auth

You will only need to do this once since your credentials are stored in
``~/.pyami/pyami.cfg`` for later use. If your credentials change just run
``ami auth`` again. If you would like to keep your pyAMI configuration in a
directory other than ``~/.pyami`` then set the environment variable
``PYAMI_CONFIG_DIR``.