From c4b77d367b0b8754cdd5bd3469d6c5492fc3b368 Mon Sep 17 00:00:00 2001 From: Will Barnes Date: Wed, 12 Sep 2018 01:07:16 -0500 Subject: [PATCH] Doc updates --- README.md | 2 +- docs/index.md | 17 +++++++++++++---- 2 files changed, 14 insertions(+), 5 deletions(-) diff --git a/README.md b/README.md index 24903de..420b6ec 100644 --- a/README.md +++ b/README.md @@ -21,7 +21,7 @@ You can then run the tests to make sure everything is working alright, $ pytest ``` -**Note: hissw relies on executing several shell commands in the background and as a consequence Windows is (likely) not supported.** +**Note: hissw relies on executing several shell commands. This has not been tested on Windows.** ## Reporting Issues and Contributing Open an [issue on GitHub](https://github.com/wtbarnes/hissw/issues) to report a problem. [Pull requests](https://github.com/wtbarnes/hissw/pulls) welcome. diff --git a/docs/index.md b/docs/index.md index b86e4dd..a734c78 100644 --- a/docs/index.md +++ b/docs/index.md @@ -1,9 +1,11 @@ # hiss(w) + The [SolarSoftware](http://www.lmsal.com/solarsoft/) (SSW) stack contains nearly every piece of software a solar physicist needs. While libraries like [Astropy](http://www.astropy.org/), [SunPy](http://sunpy.org/), and [ChiantiPy](https://github.com/chianti-atomic/ChiantiPy) provide Python equivalents to many of these IDL packages, there's still a lot of functionality only available in SSW and not enough hours in the day to rewrite it all in Python. -**hissw** (pronounced hiss **or** hiss-SSW) is a (*VERY*) lightweight (~1 file) package that allows you to write IDL scripts (either inline or in a separate file) which use your installed SSW packages and return the results to your local Python namespace. hissw uses Jinja2 templates to generate SSW startup scripts and then runs your IDL code in the background. You can also use Jinja syntax to inject arguments from Python into IDL. The results are then saved to a file and then loaded back in using the amazing [`readsav()` function in `scipy.io`](https://docs.scipy.org/doc/scipy-0.14.0/reference/generated/scipy.io.readsav.html). +**hissw** (*hiss* (like a snake) + SSW) is a (*VERY*) lightweight (~1 file) Python package that allows you to write IDL scripts (either inline or in a separate file) which use your installed SSW packages and return the results to your local Python namespace. hissw uses Jinja2 templates to generate SSW startup scripts and then runs your IDL code using `subprocess`, i.e. the shell. You can also use Jinja syntax to inject arguments from Python into IDL. The results are then saved to a file and then loaded back in using the amazing [`readsav()` function in `scipy.io`](https://docs.scipy.org/doc/scipy-0.14.0/reference/generated/scipy.io.readsav.html). ## Install and Configuration + Install the dependencies with `conda` (preferred) or `pip`, ```shell @@ -32,7 +34,9 @@ ssw_home=/path/to/ssw/tree idl_home=/path/to/local/idl/install ``` -and then run the tests to make sure everything is working properly +Note that if you do not create this file, **you will be required to specify it each time you setup a SSW script environment**, using the keywords `ssw_home` and `idl_home`. + +If you've downloaded the source, you can run the tests (requires `pytest` to be installed) to make sure everything is working properly, ```shell $ pytest @@ -40,9 +44,14 @@ $ pytest ## Bridging the IDL-Python Gap the Bad Way... +hissw is a hack, albeit a clever one. In general, the methodology employed here (round-tripping everything in memory to disk) is a *terrible idea*. There's no shared memory between Python and IDL or anything fancy like that. If you're interested in something more complicated (and harder to install), you may want to check out the more official [Python-to-IDL bridge](https://www.harrisgeospatial.com/docs/Python.html). + ## Word(s) of Caution + +* Python-3 only * Unfortunately, a local install of of IDL **and** SSW is required -* Relies on executing shell commands with the `subprocess` module. As such, only Unix-like platforms (e.g. Linux, macOS) are supported -* Widgets and plotting will not work +* Relies on executing shell commands with the `subprocess` module. I've only tested this on Linux and macOS. **Windows users may encounter difficulties.** +* Be careful when injecting large pieces of data into your IDL script as this must be written to a file. It may be better to load it at (IDL) runtime. +* Widgets and plotting will (likely) **not** work * This has **not** been tested extensively against all SSW/IDL functionality. There are likely many cases where hissw will not work. [Bug reports](https://github.com/wtbarnes/hissw/issues) and [pull requests](https://github.com/wtbarnes/hissw/pulls) welcome!