Usage#
Drop-in replacement#
Using cuNumeric as a replacement for NumPy is easy. Users only need to replace:
import numpy as np
with
import cunumeric as np
Running cuNumeric programs#
Using legate
#
The preferred way to run cuNumeric programs is with the legate
driver:
legate --cpus 2 --gpus 2 script.py <script options>
All legate
command line configuration options must come before the script
that is be executed. Any options after the script are passed on to the script.
It is also possible to pass the legate
command line configuration options
using the LEGATE_CONFIG
environment variable:
LEGATE_CONFIG="--cpus 2 --gpus 2" legate script.py <script options>
See the Configuration section Legate driver for more information.
Additionally, any Legion and Realm arguments may also be passed via the
LEGION_DEFAULT_ARGS
environment variable:
LEGION_DEFAULT_ARGS="-lg:sched 100 -ll:show_rsrv" legate script.py <script options>
Using standard Python#
It is also possible to run cuNumeric programs using the standard Python interpreter, with some limitations:
LEGATE_CONFIG="--cpus 2 --gpus 2" python script.py <script options>
When running programs with this method, Legate configuration options may only
be passed via the LEGATE_CONFIG
environment variable as shown above.
Additionally, any Legion and Realm arguments must also be passed via the
LEGION_DEFAULT_ARGS
environment variable:
LEGION_DEFAULT_ARGS="-lg:sched 100 -ll:show_rsrv" python script.py <script options>
Note
Usage of standard Python is intended as a quick on-ramp for users to try
out cuNumeric more easily. Several legate
command line configuration
options, especially for multi-node execution, are not available when
running programs with standard Python. See the output of legate --help
for more details.
Multi-node execution#
Using legate
#
Cunumeric programs can be run in parallel by using the --nodes
option to
the legate
driver, followed by the number of nodes to be used.
When running on 2+ nodes, a task launcher must be specified.
Legate currently supports using mpirun
, srun
, and jsrun
as task
launchers for multi-node execution via the --launcher
command like
arguments:
legate --launcher srun --nodes 2 script.py <script options>
See the Configuration section Multi-node execution for more configuration options.
Using a manual task manager#
mpirun -np N legate script.py <script options>
It is also possible to use “standard python” in place of the legate
driver.
Running Numpy programs without changes#
The lgpatch
script (in the same location as the legate
executable) can
help facilitate quick demonstrations of cunumeric
on existing codebases
that make use of numpy
.
To use this tool, invoke it as shown below, with the name of the program to patch:
lgpatch <program> -patch numpy
For example, here is a small test.py
program that imports and uses various
numpy
funtions:
# test.py
import numpy as np
input = np.eye(10, dtype=np.float32)
np.linalg.cholesky(input)
You can invoke lgpatch
to run test.py
using cunumeric
functions
instead, without any changes to the original source code. Any standard
cunumeric
runtime options (e.g. for Measuring API coverage) may
also be used:
$ CUNUMERIC_REPORT_COVERAGE=1 LEGATE_CONFIG="--cpus 4" lgpatch test.py -patch numpy
cuNumeric API coverage: 4/4 (100.0%)