Announcing SAMpy - a more pythonic sscapi wrapper

9 posts / 0 new
Last post
Announcing SAMpy - a more pythonic sscapi wrapper

Hi all-

Like others on this list, I've struggled to get the python to work how I want it. My solution can now be found as an open source python module called SAMpy.

See for code, install, and usage instructions.

As I see it, the current official sscapi python integration suffers from a few issues:

(1) The shared library (dll, so, etc.) paths are hard coded and assume execution local to the SDK.

(2) The api is very low level and not very "pythonic". In particular, it's clumsy to set values and to retrieve results and does not work with my favored data structures, like dicts and pandas DataFrames.

(3) There is no support for templating inputs for parametric runs.

(4) The api is not compatible with Python 3, including incompatible print formats and string <-> c handling.

All of these are addressed by the linked module. The upshot is that you can configure the path to the ssc shared library, you configure modules with dicts of named values that are mapped into ssc_data, and you can extract results into a pandas DataFrame.

As an aside, I was not aware of solarjoe's and sjschneider's efforts to provide python 3 support when I wrote the module, but I hope it is seen as providing a broader set of functionality rather than yet another python 3 fix!

I consider this a very early release, so please let me know any problems you encounter or ideas for applications you have via GitHub issues or further discussion here.

Sam (no relation to SAM!)


There has already been some work done on this and a Python 2/3 wrapper is available (with decorators).

Please take a look at it. Does your code have advantages? I guess we should try to maintain
only a single Python interface.


Maybe we should split the code, e.g. using a very thin wrapper, maybe maintained by NREL (
and a module providing your convenience functions and the Pythonic approach.


Hi solarjoe. As I noted in my original post, I was not aware of your prior work when I started the project, but I did read through all of it prior to posting and don't think SAMpy is all that duplicative. I consider the python 3 support of SAMpy to be a means to an end, where the goal was a more pythonic interface to SAM. You can setup model runs using values in Python dicts that are automatically set into ssc_data structures and you can extract modeled time series as Pandas DataFrames. Soon it will have the ability to parse and implement the value setting functions of lk scripts so you can based python runs of SAM off of "templates" exported from the SAM GUI.

Having said that, I tend to find decorators to be a bit more indirect and obtuse than explicit type conversion within specific functions. So, unsurprisingly, I do have a preference for the way I handled py3 support in my adaptation of SSC. In addition, I added some user friendly config prompts so that you can identify the location of the ssc shared objects at run time and these are saved to a primitive json config file that can also store an absolute path to your SAM install and weather files.

No matter how python 3 support is achieved, my hope is that one or another of the approaches becomes official within the SAM SDK so no one else has to figure out how to support it or find our respective projects. I would be happy to merge or otherwise acknowledge and eliminate redundancy.



Hello Sam,

you are right. In the end it is important that the wrapper becomes official.
Though I think they will rather use some thin wrapper.
But I think it is also fine to have your pythonic convenience functions in a separate
The aim of our wrapper and the decorators is not to support Python 3, rather to support Python 2 AND 3.
I think that way it is more likely it will become official. The decorator is pretty explicit :)

Kind regards,


Yes. My language was imprecise. Since python 2 is currently supported by the SDK, I was commenting on the *addition* of python 3 support. py3samsdk, SAMpy, and the official SDK should all support both seamlessly. In the long run, I would be happy to migrate SAMpy to rely on the wrapped sscapi from py3samsdk. Then there will be less overlap in functionality and less confusion around how to proceed.

One idea for taking decoration further: you could use class inheritance (i.e. write a class that extends the SDK's PySSC) to eliminate py2 print statements and allow the user to supply the dll_dir without replicating the underlying sscapi code. Then you could use introspection to dynamically decorate all functions with python 3 compatible ctype behavior. This would track changes to the SDK code without requiring a manual replication, but you'd need to get on your path so you could inherit from it.


Which of windows/osx/linux are you guys currently running your implementations on typically?


Windows 7, 64-bit, Python 3.4

Linux should also work, maybe with a minor adjustment to locate the library.

No idea about OSX.


Sorry for the late reply.
Thanks for the suggestion about the decoration, I have to look into that when I have more time.
But I agree, the dll_dir was something I also struggled with in the beginning and I stated
to hard-code it. So this would be a good solution to workaround that.

Theme by Danetsoft and Danang Probo Sayekti inspired by Maksimer