R E A D M E


Product Name:           rgang
Product Version:        3.9.5
Date (yyyy.mm.dd):      2025.12.08

------------------------------------------------------------------------

                                   ORIGIN
                                   ======
Author

    Ron Rechenmacher

    Fermi National Accelerator Laboratory - Mail Station 234
    P.O Box 500
    Batavia, IL 60510
    Internet: rgang-support@fnal.gov

Fermilab Standard Government Sponsorship Notice

    This work was performed at Fermi National Accelerator Laboratory,
    which is operated by Universities Research Association, Inc., under
    contract DE-AC02-76CHO3000 with the U.S. Department of Energy.

Acknowledgements

    The name "rgang" and the original shell versions came from Marc Mengel;
    Kurt Ruthmansdorfer added to and modified the original versions; Jon
    Bakken added "copy mode"; and Ron Rechenmacher added the "nway" (including
    parallel execution) "tree structure" concepts.


------------------------------------------------------------------------

                             TERMS AND CONDITIONS
                             ====================

This software has been made freely available with a request for
collaborative input subject to standard Fermitools Terms and Conditions
in the LICENSE file.

------------------------------------------------------------------------

                             PRODUCT DESCRIPTION
                             ===================
rgang is a tool which allows one to execute commands on or distribute files
to many nodes (computers). It incorporates an algorithm to build a tree-like
structure (or "worm" structure) to allow the distribution processing time to
scale very well to 1000 or more nodes.


Documentation
-------------
Documentation is included with the product/software. An online version can
be found at: https://github.com/fermitools/rgang

Required Hardware and Software
------------------------------
Python is required. The end user can attempt to make a "frozen" version of
rgang.py to remove this requirement.

Product Installation
--------------------
Copy the python script (<distdir>/bin/rgang.py) to
  /usr/local/bin or /usr/bin or where every you
choose, renaming it to whatever you choose.

Note <distdir>/bin/rgang is sym-link to rgang.py and when a large number of
nodes (i.e > 200) are specified, python will need to be installed on remote nodes.
If one creates a "frozen" version of rgang.py, the preceding may not be required.
A "frozen" version may not work on some systems due to incompatibilities
between it and the system that the frozen version was created on.

If the default "remote" commands (remote-shell[ssh] and remote-copy [scp])
are not appropriate, the python script can be modified OR a "pre-script"
created that sets the appropriate options
and then exec's the python script or
"frozen" version.  Example:
   #!/bin/sh
   # this script file can be named "rgang"
   exec python rgang.py --rsh=ssh --rcp=scp "$@"

or the RGANG_RSH and RGANG_RCP environment variables can be set.


Running the Software
--------------------
See the documentation or usage/help from rgang -h or rgang -vh.


------------------------------------------------------------------------

                                   SUPPORT
                                   =======

Help with the installation or use of rgang is available by sending
mail to

                        rgang-support@fnal.gov

which is auto-forwarded to the group in charge of rgang support at
Fermilab.

This software is furnished by Fermilab on an "as is" basis as a service
to the wider community with the goal of stimulating collaborative use
and further development.

Provision of the software implies no commitment of support by Fermilab.

The Fermilab Computing Division is open to discussing other levels of
support for use of the software with responsible and committed users and
collaborators.

Use of the software in experiments at Fermilab will be assured of a
level of support as agreed to through the standard Memorandum Of
Understanding process.

Users may send mail to the mail address given above, with the
expectation that it will be read and noted.