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.08 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

6
A collection 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
This is a work in progress.
Qusai Al Shidi's avatar
Qusai Al Shidi committed
9

10
11
Installation
------------
12

13
*Note*: swmfpy also is part of the SWMF and gets cloned into `SWMF/share/Python`. However, if you would like to [develop](CONTRIBUTING.markdown) for swmfpy make a clone and work that way and make a merge request.
14

15
16
17
18
There are two 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.

### Without Python venv

19
Install with [pip](https://pip.pypa.io/en/stable/):
20

21
```shell
Qusai Al Shidi's avatar
Qusai Al Shidi committed
22
23
$ python3 -m pip install --user wheel  # Might be necessary
$ python3 -m pip install --user git+https://gitlab.umich.edu/swmf_software/swmfpy.git@master
24
25
```

26
*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`
27

28
Then import it into your python project. 
Qusai Al Shidi's avatar
Qusai Al Shidi committed
29
30
31
32
33

```python
import swmfpy
```

34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
### 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
58
$ python3 -m pip install --user git+https://gitlab.umich.edu/swmf_software/swmfpy.git@master
59
60
61
62
63
64
65
66
67
68
69
70
71
72
```

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

If you have followed these carefully and still not been able to install please submit an Issue.

73
74
75
Documentation
-------------

76
77
78
An auto-documented version can be found [here](DOCUMENTATION.markdown).

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
79
80

```python
81
import swmfpy
Qusai Al Shidi's avatar
Qusai Al Shidi committed
82
83
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
84
```
Qusai Al Shidi's avatar
Autodoc    
Qusai Al Shidi committed
85

86
87
88
Issues
------

89
If you are experiencing any issues or bugs please go to the [Issues](https://gitlab.umich.edu/swmf_software/swmfpy/issues) page and create an issue. Make sure you include steps to recreate the problem in your post.
90
91
92
93
94
95
96

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

You can cite this software on LaTeX like this:

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