Plasmapy Documentation Release 0.2.0
Total Page:16
File Type:pdf, Size:1020Kb
PlasmaPy Documentation Release 0.2.0 PlasmaPy Community Sep 29, 2019 CONTENTS 1 Getting Started 3 2 User Documentation 11 3 Development Guide 201 4 Project Details 217 5 Index 229 Bibliography 231 Python Module Index 233 Index 235 i ii PlasmaPy Documentation, Release 0.2.0 PlasmaPy is an open source community-developed core Python 3.6+ package for plasma physics currently under development. CONTENTS 1 PlasmaPy Documentation, Release 0.2.0 2 CONTENTS CHAPTER ONE GETTING STARTED 1.1 Installing PlasmaPy Note: If you would like to contribute to PlasmaPy, please refer to the instructions on installing PlasmaPy for devel- opment. 1.1.1 Requirements PlasmaPy requires Python version 3.6 or newer, and is not compatible with Python 2.7. PlasmaPy requires the follow- ing packages for installation: • NumPy 1.13 or newer • SciPy 0.19 or newer • Astropy 2.0 or newer • colorama 0.3 or newer PlasmaPy also uses the following optional dependencies: • matplotlib 2.0 or newer • h5py 2.8 or newer • mpmath 1.0 or newer • lmfit 0.9.7 or newer PlasmaPy can be installed with all of the optional dependencies via pip install plasmapy[optional]. 1.1.2 Creating a conda environment We highly recommend installing PlasmaPy from a Python environment created using conda. Conda allows us to create and switch between Python environments that are isolated from each other and the system installation (in contrast to this xkcd), while also simplifying the distribution of binary and compiled dependencies. After installing conda, create a PlasmaPy environment by running: conda create -n plasmapy python=3.7 numpy scipy astropy matplotlib h5py lmfit mpmath ,!colorama -c conda-forge To activate this environment, run: 3 PlasmaPy Documentation, Release 0.2.0 conda activate plasmapy Once the environment is activated, then you may proceed with installation. 1.1.3 Installation Note: We recommend that new users create a conda environment. Installation with pip To install the most recent release of PlasmaPy on PyPI with pip into an existing Python environment alongside all optional dependencies, run pip install plasmapy[optional] To install a minimal set of dependencies (which does not guarantee that everything will run and may result in ImportError`s, skip `[all] and run simply pip install plasmapy Installation with conda You can get PlasmaPy from conda via conda install -c conda-forge plasmapy 1.1.4 Building and installing from source code Prerequisites Building PlasmaPy from source requires a C compiler such as gcc so that code generated by Cython may be compiled. Obtaining source code Stable release The source code for the most recent stable release of PlasmaPy can be downloaded from PyPI. Development version on GitHub If you have git installed on your computer, you may clone PlasmaPy’s GitHub repository and access source code from the most recent development version by running: git clone https://github.com/PlasmaPy/PlasmaPy.git 4 Chapter 1. Getting Started PlasmaPy Documentation, Release 0.2.0 The above command uses HTTPS, which is the default protocol and more straightforward to set up. If you have set up an SSH key, then an equivalent and more secure command is: git clone [email protected]:PlasmaPy/PlasmaPy.git If you do not have git installed on your computer, then you may download the most recent source code from PlasmaPy’s GitHub repository by selecting “Clone or Download”, which will give you the option to download a zip file. Note: The Contributing to PlasmaPy guide has instructions on how to fork a repository so that you may make pull requests. Building and installing In the top level directory, run python setup.py install or pip install . Testing a source code build Testing PlasmaPy requires: • pytest In the top level directory, run python setup.py test Building documentation Building and testing PlasmaPy documentation requires the following packages: • Sphinx • sphinx-gallery • sphinx_rtd_theme • sphinx-automodapi • pillow • numpydoc To build the documentation, run the following command in the top level directory of the repository: python setup.py build_docs The HTML files built by this command will be placed in the docs/_build/html subdirectory and can be read using a web browser. 1.1. Installing PlasmaPy 5 PlasmaPy Documentation, Release 0.2.0 1.2 Feedback and communication 1.2.1 Matrix chat If you have any questions, the quickest way to get a response is to ask on our Matrix/Gitter channel. 1.2.2 Mailing list We also have a mailing list that serves as a less volatile discussion forum. 1.2.3 Suggestion box We have a suggestion box if you would like to (optionally anonymously) suggest a feature/topic for consideration. These will be reposted on the mailing list or directly in GitHub issues, as appropriate, for further discussion. 1.2.4 Biweekly video calls We also have approximately bi-weekly online meetings at Jitsi, for which we have a calendar here and written meeting notes here. Come discuss plasma software with us! 1.3 Contributing to PlasmaPy There are numerous ways to contribute to PlasmaPy, including by providing code and documentation, suggesting and discussing ideas, submitting issues and bug reports, and engaging the broader plasma physics community. 1.3.1 Impostor syndrome disclaimer1 We want your help. No, really. There may be a little voice inside your head that is telling you that you’re not ready to be an open source contributor; that your skills aren’t nearly good enough to contribute. What could you possibly offer a project like this one? We assure you - the little voice in your head is wrong. If you can write code at all, you can contribute code to open source. Contributing to open source projects is a fantastic way to advance one’s coding skills. Writing perfect code isn’t the measure of a good developer (that would disqualify all of us!); it’s trying to create something, making mistakes, and learning from those mistakes. That’s how we all improve, and we are happy to help others learn. Being an open source contributor doesn’t just mean writing code, either. You can help out by writing documentation, tests, or even giving feedback about the project (and yes - that includes giving feedback about the contribution process). Some of these contributions may be the most valuable to the project as a whole, because you’re coming to the project with fresh eyes, so you can see the errors and assumptions that seasoned contributors have glossed over. 1 The imposter syndrome disclaimer was originally written by Adrienne Lowe for a PyCon talk. It was adapted in the README files for MetPy and yt, and was then adapted by PlasmaPy. 6 Chapter 1. Getting Started PlasmaPy Documentation, Release 0.2.0 1.3.2 Contributing code or documentation to PlasmaPy If you see something you’d like to work on amongst our issues, start hacking away on that! However, please announce your intent first in the relevant issue to make sure there is no work duplication. Please note that PlasmaPy has a PlasmaPy Community Code of Conduct. Issues marked by the community as help wanted mean just that - either they’re good contributions for outsiders or there’s an issue in the ongoing work that requires a second opinion. Please consider these first! Work on PlasmaPy is done via GitHub, so you’ll need a (free) account. If you are new to git, helpful resources include documentation on git basics and an interactive git tutorial. You must also install git locally on your computer. We highly recommend getting reasonably familiar with git by going through these tutorials or a Software Carpentry workshop prior to making code contributions. Do note that you can usually find help in the PlasmaPy Matrix chatroom. For actual guidelines for working on PlasmaPy, please see our PlasmaPy Development Guide. 1.3.3 Towncrier changelog entries Every pull request should include a changelog entry. Please see changelog/README.rst for instructions. To summarize, put a file like <PULL REQUEST>.<TYPE>.rst, where <PULL REQUEST> is a pull request num- ber, and <TYPE> is one of breaking, feature, bugfix, doc, removal, trivial. If unsure, ask a maintainer. Footnotes 1.4 PlasmaPy Community Code of Conduct The PlasmaPy community strives to follow the best practices in open source software development. New contributors are encouraged to join the team and contribute to the codebase. We anticipate/encourage a global participation from people with diverse backgrounds, skills, interests, and opinions. We believe that such diversity is critical in ensuring a growth of ideas in our community. 1.4.1 Our Pledge In the interest of fostering an open and welcoming environment, we as contributors and maintainers pledge to making participation in our project and our community a harassment-free experience for everyone, regardless of age, body size, disability, ethnicity, gender identity and expression, level of experience, nationality, personal appearance, race, religion, or sexual identity and orientation. 1.4.2 Our Standards Examples of behavior that contributes to creating a positive environment include: • Using welcoming and inclusive language • Being respectful of differing viewpoints and experiences • Gracefully accepting constructive criticism • Focusing on what is best for the community • Showing empathy towards other community members We as a community pledge to abide by the following guidelines: 1.4. PlasmaPy Community Code of Conduct 7 PlasmaPy Documentation, Release 0.2.0 • We pledge to treat all people with respect and provide a harassment- and bullying-free environment, regardless of age, sex, sexual orientation and/or gender identity, disability, physical appearance, body size, race, nationality, ethnicity, religion, and level of experience. In particular, sexual language and imagery, sexist, racist, or otherwise exclusionary jokes are not appropriate.