Command Line Arguments
======================

Qbics should be run from Windows command prompt or Linux terminal. 

Run Qbics on a Single Node
-------------------------------------------

To run Qbics on a single node, you just need to give an input file name. You can redirect output to an arbitrary file.

.. code-block:: bash

    $ qbics-linux-cpu water.inp > water.out

Some optional arguments can be given:

.. list-table::
    :header-rows: 1
    :widths: 5 5 20
   
    * - Value
      - Default
      - Meaning
    * - ``-n``
      - ``1``
      - Define the number of OpenMP threads for each MPI process
    * - ``-s``
      - ``./``
      - Define the scratch path
    * - ``-m``
      - Unlimited
      - Define the maximum memory size in GB that a MPI process can use
    * - ``-d``
      - Unlimited
      - Define the maximum disk size in GB that a MPI process can use in the scratch path
    * - ``--gpu``
      - ``0``
      - Define the GPU device ID to be used

For ``-n``, the value should be **less than the number of physical CPU cores** of the node it is run on. 

For ``-s``, Qbics will use this path to write some computational temporary files. It should be on a **local, fast, and large** disk, and **not** ones, like NFS shared paths. For Windows users, the scratch path should be given in **Linux format**. For example, if the scratch path is ``D:\Jobs\Scratch`` (Windows format), then for Qbics you should type ``-d D:/Jobs/Scratch``.

For ``-m``, for example, ``-m 5.5`` means that each MPI process will use up to 5.5 GB of memory, no matter how many OpenMP threads there are. Of course, it should not exceed the total memory size of the node.

For ``-d``, for example, ``-d 900`` means that each MPI process will use up to 900 GB of disk, no matter how many OpenMP threads there are. Of course, it should not exceed the total disk size in the scratch path.

For ``--gpu``, for example, ``--gpu 0,2,3`` means that Qbics will use GPU device of ID ``0``, ``2``, ``3`` to do calculations.

Here is an example:

.. code-block:: bash

    $ qbics-linux-cpu water.inp -n 8 -m 30 -d 500 -s /scratch/zhang > water.out

This command will run Qbics with an input file ``water.inp``. The number of OpenMP threads is 8, maximum memory and disk size is 30 GB and 500 GB, respectively, and the scratch path is ``/scratch/zhang``.

.. Run Qbics on Multiple Nodes