Metadata-Version: 2.4
Name: repast4py
Version: 1.3.0
Summary: repast4py package
Home-page: https://repast.github.io/repast4py.site/index.html
Author: Nick Collier
Author-email: ncollier@anl.gov
Maintainer: Nick Collier
Maintainer-email: ncollier@anl.gov
License: BSD 3-Clause License
Project-URL: Git Repostitory, https://github.com/Repast/repast4py
Project-URL: Issue Tracker, https://github.com/Repast/repast4py/issues
Project-URL: Documentation, https://repast.github.io/repast4py.site/guide/user_guide.html
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Science/Research
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Scientific/Engineering
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: System :: Distributed Computing
Requires-Python: <3.15,>=3.10
Description-Content-Type: text/markdown
License-File: LICENSE.txt
Requires-Dist: numpy
Requires-Dist: numba
Requires-Dist: torch
Requires-Dist: networkx>=2.6.2
Requires-Dist: pyyaml
Requires-Dist: Cython
Requires-Dist: typing_extensions; python_version < "3.8.0"
Requires-Dist: dill
Requires-Dist: mpi4py
Dynamic: license-file
Dynamic: requires-dist
Dynamic: summary

# Repast for Python (Repast4Py)

[![codecov](https://codecov.io/gh/Repast/repast4py/branch/develop/graph/badge.svg?token=JCDU2LT8G2)](https://codecov.io/gh/Repast/repast4py/branch/develop)

## Build Status
| Master | Develop |
| ------ |-------- |
| [![unit tests](https://github.com/Repast/repast4py/actions/workflows/tests.yml/badge.svg?branch=master)](https://github.com/Repast/repast4py/actions/workflows/tests.yml) | [![unit tests](https://github.com/Repast/repast4py/actions/workflows/tests.yml/badge.svg?branch=develop)](https://github.com/Repast/repast4py/actions/workflows/tests.yml) |

<!-- <table>
  <tr>
    <td><b>Master</b></td>
    <td><b>Develop</b></td>
  </tr>
  <tr>
    <td><a href="https://circleci.com/gh/Repast/repast4py/tree/master"><img src="https://github.com/Repast/repast4py/actions/workflows/tests.yml/badge.svg?branch=master" alt="Build Status"/></a></td>
    <td><a href="https://circleci.com/gh/Repast/repast4py/tree/develop"><img src="https://circleci.com/gh/Repast/repast4py/tree/develop.svg?style=shield" alt="Build Status"/> </a></td>
  </tr>
</table> -->

## Repast4Py

Repast for Python (Repast4Py) is the newest member of the [Repast Suite](https://repast.github.io) of 
free and open source agent-based modeling and simulation software.
It builds on  [Repast HPC](https://repast.github.io/repast_hpc.html), and provides the ability to build large, distributed agent-based models (ABMs) that span multiple processing cores. 
Distributed ABMs enable the development of complex systems models that capture the 
scale and relevant details of many problems of societal importance. Where Repast HPC is 
implemented in C++ and is more HPC expert focused, Repast4Py is a Python package and is 
designed to provide an easier on-ramp for researchers from diverse scientific communities to apply large-scale distributed ABM methods. 
Repast4Py is released under the BSD-3 open source license, and leverages [Numba](https://numba.pydata.org),
[NumPy](https://numpy.org), and [PyTorch](https://pytorch.org) packages, and the Python C API 
to create a scalable modeling system that can exploit the largest HPC resources and emerging computing architectures. See our paper on Repast4Py for additional information about the design and implementation.

Collier, N. T., Ozik, J., & Tatara, E. R. (2020). Experiences in Developing a Distributed Agent-based Modeling Toolkit with Python. 2020 IEEE/ACM 9th Workshop on Python for High-Performance and Scientific Computing (PyHPC), 1–12. https://doi.org/10.1109/PyHPC51966.2020.00006

### Requirements

Repast4Py requires Python 3.10+

The default multiprocess distributed version of Repast4Py can run on Linux, macOS and Windows
provided there is a working MPI implementation installed and mpi4py is supported. On Windows,
we recommend using the Windows Subsystem for Linux (WSL)and following the Linux install
instructions. Installation instructions for
WSL can be found [here](https://docs.microsoft.com/en-us/windows/wsl/install). 

A native Windows install that does not require MPI or
a C/C++ compiler is also available. Installation instructions are [here](https://repast.github.io/repast4py.site/windows_install.html). This mode can be used to develop models that are amenable to Python's built-in multiprocessing
or thread-based parallelism, enabling forms of parallelism other than distributed MPI.

NOTE: A non-mpi install is also available for Linux and Mac, but a C/C++
compiler is currently still required to compile Repast4Py's native code. See [No MPI Installation](#no-mpi-installation). 

Repast4Py also requires PyTorch. On Linux, the default PyTorch wheel on PyPI bundles
NVIDIA CUDA libraries; if you have no NVIDIA GPU, see
[CPU-only PyTorch](#cpu-only-pytorch) for installing the smaller CPU-only build
**before** installing Repast4Py.


#### MPI Installation

Under Linux, MPI can be installed using your OS's package manager. For example, 
under Ubuntu 24.04 (and thus WSL), the mpich MPI implementation can be installed with:

***Linux and WSL***
```bash
$ sudo apt install mpich
```

Installation instructions for MPI on macOS can be found
[here](https://repast.github.io/repast4py.site/macos_mpi_install.html).

A typical campus cluster, or HPC resource will have MPI and mpi4py installed. 
Check the resource's documentation on available software for more details.

### Installation

Repast4Py can be downloaded and installed from PyPI using pip. 
Since Repast4Py includes native MPI C++ code that needs to be compiled,
the compiler environment variables `CC` and `CXX` must be set
to the `mpicxx` (or `mpic++`) compiler wrapper provided by your MPI installation.

Depending on the operating system and setuptools version, the `CXX` variable may
also need to be set.

***Linux, macOS, and WSL***
```bash
env CC=mpicxx CXX=mpicxx pip install repast4py
```

The preferred install is into a Python virtual environment. See
[here](https://repast.github.io/repast4py.site/guide/user_guide.html#_installation)
for additional installation instructions.

__NOTE__: If you see an error message about a missing `python.h` header file when
installing Repast4Py under Ubuntu (or other Linuxes), you will need to install
a python dev package using your OS's package manager. For example, assuming
Python 3.12, `sudo apt install python3.12-dev` will work for Ubuntu.

#### No MPI Installation

Repast4Py can also be installed in a *no-mpi* mode that requires neither a
native MPI installation nor mpi4py.

A C++ compiler and the Python development headers are still required to compile
Repast4Py's native extensions, but no MPI compiler wrapper is needed. Set the
`R4PY_NO_MPI` environment variable when installing:

***Linux, macOS, and WSL***
```bash
env R4PY_NO_MPI=1 pip install repast4py
```

NOTE: A no-mpi installation can only be run as a single process. Launching it
across multiple processes (e.g. `mpirun -n 2`) is an error and the program will exit;
for distributed multi-rank runs use the default installation above with a working
MPI.

IMPORTANT: Do **not** install the no-mpi version and the mpi version of Repast4Py in the same Python environment.

#### CPU-only PyTorch

Repast4Py uses PyTorch in its value layer raster implementation, 
and the default Linux PyTorch wheels on PyPI with GPU support can be very large
(e.g. several gigabytes). For models that do not use value layers or for
non-GPU Linux environments, the CPU-only build can be used. 

This is only relevant on Linux. The macOS and Windows wheels on PyPI are CPU-only already.
A cluster or HPC resource may also provide PyTorch itself, so check the resource's
documentation before installing your own. Install the
CPU-only build from PyTorch's own package index **before** installing Repast4Py:

***Linux and WSL***
```bash
$ pip install torch --index-url https://download.pytorch.org/whl/cpu
$ env CC=mpicxx CXX=mpicxx pip install repast4py
```

The same two steps work for a no-mpi installation,
substituting `env R4PY_NO_MPI=1 pip install repast4py` for the
second command.

The CPU-only wheels carry a `+cpu` version suffix that pip prefers over the plain
version.

To check which build is installed:

***Linux and WSL***
```bash
$ python -c "import torch; print(torch.__version__)"
2.14.0+cpu
```

A `+cpu` suffix is the CPU-only build. A plain version number, or a `+cu...` suffix, is a
CUDA build.


### Documentation

* [User's Guide](https://repast.github.io/repast4py.site/guide/user_guide.html)
* [API Docs](https://repast.github.io/repast4py.site/apidoc/index.html)
* [Example Models](https://repast.github.io/repast4py.site/examples/examples.html)

### Contact and Support

* [GitHub Issues](https://github.com/Repast/repast4py/issues)
* [GitHub Repository](https://github.com/Repast/repast4pyV)

In addition to filing issues on GitHub, support is also available via
[Stack Overflow](https://stackoverflow.com/questions/tagged/repast4py). 
Please use the `repast4py` tag to ensure that we are notified of your question. 
Software announcements will be made on the 
[repast-interest](http://lists.sourceforge.net/lists/listinfo/repast-interest) mailing list.

Jonathan Ozik is the Repast project lead. Please contact him through 
the [Argonne Staff Directory](https://www.anl.gov/staff-directory) if you
have project-related questions.
