Platypus is an open source library of particle-in-cell (PIC) plasma simulators. These simulators are designed to be both very easy to use through a simple Python API and easy to understand, with well documented and cleanly written code. Platypus is intended as an educational tool, and is not meant to be a replacement for more sophisticated simulators.
Platypus currently includes the following simulators:
- 1-D electrostatic
- 2-D electrostatic
- 3-D electrostatic
- 2-D electromagnetic (in development)
The respository also includes scripts for creating graphs, videos, and other visulatizations of the simulation results. There are also numerous example simulations that users can copy and modify.
Platypus will ultimately include two sets of simulations. The first set of simulations is PyPlatypus, a pure Python3 implementation that is designed to be easy to understand but not optimized for performance. All of the simulations currently implemented and under development are PyPlatypus simulations. An optimized, high performance version of Platypus written in C++14 will be implemented at a later date. The ultimate goal is to have a CUDA GPU implementation of Platypus. Currently, basically everything interesting is located in the PyPlatypus directory.
New features will first be added to PyPlatypus and tested before they graduate and are implemented in C++.
The following sections give a quick overview on how to install, run simulations, and create visualizations with PyPlatypus. Check out the dedicated README for PyPlatypus for a lot more details. Since only the Python3 PyPlatypus version is currently, available, this README has some information duplicated from the dedicated PyPlatypus page.
Below is an illustration of a 1-D two-stream instability, generated by PyPlatypus.
phase.mp4
- Environment
- Installation
- Running your first simulation
- Repository contents
- Contributors and Contact
- Note on Naming
- License
PyPlatypus has the following system requirements:
Python
python3.6+
numpy
matplotlib
scipy
Other
ffmpeg
The Python dependencies can all be installed with pip. You can check if
ffmpeg is installed by running which ffmpeg. If nothing is
printed then it's not installed. If you are running macOS, install ffmpeg
with brew install ffmpeg or sudo apt install ffmpeg if you are
using Ubuntu.
Platypus was developed on macOS and is not guaranteed to run on Windows. It should run fine on any Unix based OS, but this has yet to be tested.
The installation instructions require the user to have some familiarity with using the terminal. To install Platypus, first clone the repository using the terminal:
git clone https://github.com/timsliu/platypus.git
Next, navigate to the Python source file and install the PyPlatypus Python library:
cd platypus/py_platypus/src/
pip3 install -e .
Then, you will need to add the root of the platypus directory to your
~/.bashrc file as an environment variable:
export PLATYPUS_HOME=`/path/to/platypus`
Finally, source your ~/.bashrc for the new environment variable
to take effect:
source ~/.bashrc
Make sure you have all the system requirements listed under Environment installed.
PyPlatypus includes several example simulations that you can run without
writing any lines of code. This section gives a quick overview of how to run
a simulation, and be sure to check out the dedicated PyPlatypus README page for more details.
To view the example simulations, navigate to the
simulations sub directory of PyPlatypus:
cd platypus/py_platypus/simulations
ls
This will list the various simulations that are already included in the repository. Each simulation is simply a Python file that can be executed like any normal python file:
python3 two_stream_1d.py
When the simulation finishes, navigate to the out directory and find
the folder with the same name as the simulation:
cd platypus/py_platypus/out/two_stream_1d
Here you will find a graphs directory, a data directory, and a file
called params.json. Open the graphs directory to view various
visualizations gnerated by PyPlatypus.
This section describes the organization of the Platypus repository.
Output directory for binaries and object files.
PyPlatypus is a Python based collection of PIC simulators. They are a more lightweight, low performance version of the Platypus PIC simulators. PyPlatypus is primarily meant for developing and testing the algorithms used in the PIC simulators, and are also meant to be easier to understand than the optimized Platypus simulators. PyPlatypus has the following organization:
py_platypus
|- out: outputs from running simulations
|- simulations: example simulations using PyPlatypus
|- src: actual PyPlatypus Python library and Python egg
|- py_platypus:
|- models: PIC simulators
|- utils: various utility functions used by the simulators
|- vis: visualization tools
|- test: test scripts for PyPlatypus
|- unit_tests: unit tests for PyPlatypus
|- demo_tests: simulations for demonstrating and testing specific features
Folder containing the test harness and test scripts for Platypus.
C++ source for Platypus.
Python scripts for parsing simulation arguments, checking that the passed parameters are within bounds, and running the C++ Platypus binary.
Python scripts for data analysis and creating visualizations.
Platypus is an open source project created and maintained by Timothy Liu. You can contact him at timsliu.org/contact.
The official name of the project is Platypus (capital P) and the name of the Python implemention is PyPlatypus (capital P, camel case style). However, the Python code in this repository follows the convention that variables are snake_case and class names are CamelCase. The camel case "PyPlatypus" spelling is found only in the documentation, while folders and code use the snake case spelling "py_platypus".
Platypus is distributed under the MIT open source license. For the full
license contents, please see LICENSE.