Note: The default ITS GitLab runner is a shared resource and is subject to slowdowns during heavy usage.
You can run your own GitLab runner that is dedicated just to your group if you need to avoid processing delays.

README.md 3.03 KB
Newer Older
1
2
![swmfpy logo](share/logo/swmfpy.png "swmfpy")

Qusai Al Shidi's avatar
Qusai Al Shidi committed
3
4
swmfpy
======
Qusai Al Shidi's avatar
Qusai Al Shidi committed
5

Qusai Al Shidi's avatar
Qusai Al Shidi committed
6
A library of tools to make it easier to work with Python and Space Weather Modeling Framework (SWMF) together.
Qusai Al Shidi's avatar
Qusai Al Shidi committed
7

8
9
Installation
------------
10

Qusai Al Shidi's avatar
Qusai Al Shidi committed
11
*Note*: swmfpy also is part of the SWMF and gets cloned into `SWMF/share/Python` for bundling purposes only. However, if you would like to [develop](CONTRIBUTING.markdown) for swmfpy make a clone and work that way and make a merge request.
12

Qusai Al Shidi's avatar
Qusai Al Shidi committed
13
There are two *supported* methods of installing swmfpy with with a virtual environment and without a virtual environment. Only use the virtual environment if your current environment is giving you trouble.
14
15
16

### Without Python venv

17
Install with [pip](https://pip.pypa.io/en/stable/):
18

Qusai Al Shidi's avatar
Qusai Al Shidi committed
19
20
```bash
$ pip install swmfpy || python3 -m pip install swmfpy || python3 -m pip install --user swmfpy
21
22
```

Qusai Al Shidi's avatar
Qusai Al Shidi committed
23
*Note*: Depending on your system [pip](https://pip.pypa.io/en/stable/) may be ran in other ways: `python3 -m pip` or `python -m pip` or `pip`
24

25
Then import it into your python project. 
Qusai Al Shidi's avatar
Qusai Al Shidi committed
26
27
28
29
30

```python
import swmfpy
```

31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
### With Python venv

Use this method if the above method is giving you trouble.

Set up a python 3 virtual environment:

```bash
$ python3 -m venv ~/.venv
```

This is important, make sure that it is in your `.profile` or `.bash_profile`:

```bash
$ echo "source ~/.venv/bin/activate" >> ~/.profile
```

*Note*: You might need to use `activate.csh` instead if using `csh` and `activate.fish` in your `~/.config/fish/config.fish` instead if using `fish` shell. You are most likely using `bash` so no need to worry.

Next install the software. This will take a long time as you will be compiling `numpy` from scratch.

```bash
$ source ~/.venv/bin/activate
$ python3 -m pip install --user wheel -vvv
$ python3 -m pip install --user cython -vvv
Qusai Al Shidi's avatar
Qusai Al Shidi committed
55
$ python3 -m pip install --user swmfpy -vvv
56
57
58
59
60
61
62
63
64
65
66
67
```

If you are using `tmux` or `GNU Screen` on a supercomputer you can safely detach your session and power off your computer and come back another time.

This should be fully installed now. You should be able to import:

```python
import swmfpy
```

### Troubleshooting

Qusai Al Shidi's avatar
Qusai Al Shidi committed
68
69
If you have followed these carefully and still not been able to install
please submit an Issue.
70

71
72
73
Documentation
-------------

74
75
An auto-documented version can be found [here](DOCUMENTATION.markdown).

Qusai Al Shidi's avatar
Qusai Al Shidi committed
76
77
However, documentation is included as docstrings.
Use python's *dir()* and *help()* inbuilt functions to see documentation.
Qusai Al Shidi's avatar
Qusai Al Shidi committed
78
79

```python
80
import swmfpy
Qusai Al Shidi's avatar
Qusai Al Shidi committed
81
82
help(swmfpy)  # To see list of functions
help(swmfpy.io.read_gm_log)  # To see the function documentation
Qusai Al Shidi's avatar
Qusai Al Shidi committed
83
```
Qusai Al Shidi's avatar
Autodoc    
Qusai Al Shidi committed
84

85
86
87
Issues
------

Qusai Al Shidi's avatar
Qusai Al Shidi committed
88
89
90
If you are experiencing any issues or bugs please go to the Issues page on
[gitlab](https://gitlab.umich.edu/swmf_software/swmfpy/issues) or [github](https://github.com/MSTEM-QUDA/swmfpy/issues)
page and create an issue. Make sure you follow the templates.
91
92
93
94
95
96
97

How to cite
-----------

You can cite this software on LaTeX like this:

```latex
Qusai Al Shidi's avatar
Qusai Al Shidi committed
98
@software{swmfpy,
Qusai Al Shidi's avatar
CI    
Qusai Al Shidi committed
99
  author = {{Al Shidi, Qusai}},
100
  title = {swmfpy},
Qusai Al Shidi's avatar
Qusai Al Shidi committed
101
  url = {https://gitlab.umich.edu/swmf_software/swmfpy},
102
103
104
105
  version = {2020.5},
  date = {2020-06-19},
}
```