README.markdown 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,
98
99
  author = {{Qusai Al Shidi}},
  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},
}
```