.. _usage:

=====
Usage
=====

Command Line
------------

AtomAccess is best run through its `web interface <https://atom-access.com/>`_, but advanced users can also run it from the command line.

.. code-block:: bash

    atom_access <molecule.xyz>

where ``<molecule.xyz>`` is the name of an `.xyz` file containing a set of atomic coordinates.
The `.xyz` file must have have a specific (XMOL) format, as detailed in :ref:`file_formats`.

The following additional command line arguments can be change the default
settings and enable additional options.

+-----------------------------+--------------------------------------------------------------------------+
|   Optional Argument(s)      |   Description                                                            |
+=============================+==========================================================================+
| ``--atom <integer>``        | Select the atom for which to calculate the accessibility.                |
|                             |                                                                          |
|                             | ``<integer>`` is the index of the desired atom (starting from 1).        |
|                             |                                                                          |
|                             | Default: `1`                                                             |
+-----------------------------+--------------------------------------------------------------------------+
| ``--cutoff <number>``       | Set the radial cutoff distance from the atom of interest.                |
|                             |                                                                          |
|                             | ``<number>`` is :math:`r_{\text{max}}` in Angstroms.                     |
|                             |                                                                          |
|                             | Default: `5`                                                             |
+-----------------------------+--------------------------------------------------------------------------+
| ``--density <integer>``     | Control the number of rays emanating from the atom of interest using the |
|                             |                                                                          |
|                             | Zaremba-Conroy-Wolfsberg (ZCW) density index.\                           |
|                             | :footcite:p:`zcw_z,zcw_c,zcw_w`                                          |
|                             |                                                                          |
|                             | ``<integer>`` is an integer between 0-15 - see Table 1                   |
|                             |                                                                          |
|                             | Default: `10`                                                            |
+-----------------------------+--------------------------------------------------------------------------+
| ``--quiet``                 | Suppress printing to the terminal.                                       |
+-----------------------------+--------------------------------------------------------------------------+
| ``--save_rays``             | Save the unblocked ray objects.                                          |
+-----------------------------+--------------------------------------------------------------------------+
| ``--plot``                  | Plot the unblocked rays in a web browser using plotly                    |
+-----------------------------+--------------------------------------------------------------------------+


.. table:: Table 1: Number of rays for each ZCW density index value 

    +-------------------+----------------+
    | ZCW density index | Number of rays |
    | :math:`\rho`      |                | 
    +===================+================+
    | 0                 | 21             |
    +-------------------+----------------+ 
    | 1                 | 34             |
    +-------------------+----------------+ 
    | 2                 | 55             |
    +-------------------+----------------+ 
    | 3                 | 89             |
    +-------------------+----------------+ 
    | 4                 | 144            |
    +-------------------+----------------+ 
    | 5                 | 233            |
    +-------------------+----------------+ 
    | 6                 | 377            |
    +-------------------+----------------+ 
    | 7                 | 610            |
    +-------------------+----------------+ 
    | 8                 | 987            |
    +-------------------+----------------+ 
    | 9                 | 1597           |
    +-------------------+----------------+ 
    | 10                | 2584           |
    +-------------------+----------------+ 
    | 11                | 4181           |
    +-------------------+----------------+ 
    | 12                | 6765           |
    +-------------------+----------------+ 
    | 13                | 10946          |
    +-------------------+----------------+ 
    | 14                | 17711          |
    +-------------------+----------------+ 
    | 15                | 28657          |
    +-------------------+----------------+ 


Scripting
---------

Thanks to its modular design, AtomAccess can be included in your own python scripts with ease.

As an example, the following script calculates the steric hindrance for a molecule with a given set of atomic coordinates.

.. code-block:: python
    
    import xyz_py as xyzp
    import atom_access as aa

    # Load xyz file
    labels, coords = xyzp.load_xyz('benzene.xyz')
    # Remove indices from labels
    # i.e. H2 --> H
    labels_nn = xyzp.remove_label_indices(labels)

    # Trace the rays
    # This returns a list of blocked and unblocked rays,
    # and the number of atoms which were excluded
    # by the radial cutoff
    blocked, unblocked, n_cut = aa.trace_rays(
        labels_nn,
        coords,
        centre=0,
        radial_cutoff=5,
        zcw_density=12
    )

    # calculate the percentage of unblocked rays
    total_rays = len(blocked) + len(unblocked)
    pc_unblocked = len(unblocked) / (total_rays) * 100.

    # Cluster rays using agglomerative clustering
    cluster_id = aa.cluster_rays(unblocked, zcw_density=12)

    # Quit if the rays are all blocked
    if not cluster_id.size:
        print('All Rays Blocked!')
        sys.exit()

    # Calculate size of each cluster as a percentage of the total number of rays
    clust_percent, _ = aa.cluster_size(cluster_id, total_rays)

    print(
        f'\nThere are {clust_percent.size:d} clusters'
    )

    for idx, x in enumerate(clust_percent):
        print(
            'Cluster {:d} contains {:.2f} % solid angle'.format(
                idx + 1, x
            )
        )

    # Print output file
    aa.generate_output(
        'output.txt',
        zcw_density=12,
        pc_unblocked=pc_unblocked,
        clust_percent=clust_percent,
        radial_cutoff=5,
        no_header=True
    )

To learn more about the available functions and their arguments, consult the :ref:`API` documentation.

.. footbibliography::