High-level library for NREL's SAM Simulation Core (SSC)
Project description
samlib
Samlib is a high-level Python wrapper to the SAM SSC library from the SAM SDK.
Overview
Samlib uses cffi to build Pythonic library bindings to the SAM SSC library. It includes typing stubs for static type analysis and code completion.
Installation
Install samlib using pip:
pip install samlib
Example usage
import samlib
from samlib.modules import pvsamv1
wfd = samlib.Data() # weather forecast data
wfd.lat = 38.743212
wfd.lon = -117.431238
...
data = pvsamv1.Data()
data.solar_resource_data = wfd
data.use_wf_albedo = 0
...
module = pvsamv1.Module()
module.exec(data)
# Use results saved in data
Versioning
Samlib uses semantic versioning with a twist. The version includes the SSC revision number after the API major version and before the remaining API version: major.REV.minor. This provides for pinning samlib to a particular API version or to a combination of API + SSC revision. The SSC revision is the final component of SSC release versions.
Here are a couple of examples:
samlib ~= 1.0
specifies samlib API version 0, using the latest SSC revision.samlib ~= 1.240.0
specifies samlib API version 0, using SSC revision 240 (which corresponds to SSC release 2020.2.29.r2.ssc.240)
The major version is incremented for potentially breaking samlib API changes while the minor version is incremented for non-breaking API changes. There may be additional .N suffixes for releases with duplicate SSC library revisions or rcN or .postN suffixes for release candidates or post-release, build-only updates.
License
Samlib is provided under a BSD 3-Clause license.
The SAM SSC, distributed in binary form in samlib wheels, is also licensed under a BSD 3-clause license.
Building
Building requires cmake >= 3.24, a C++ compiler, and the Python build
package, which can be installed with pip install --upgrade build
.
On windows, cmake can be installed using winget install --id Kitware.CMake
.
CMake and SSC options can be set using environment variables. See the CMake and SSC documentation for more details.
Environment variables may be provided to control the build.
Variables for building sdist or wheel targets:
SSC_RELEASE=TAG
: SSC revision to download and build; TAG should match an SSC tag from the NREL
SSC git repository in the form YYYY.MM.DD[.rcN].ssc.REV
. This variable is
required when building sdist or wheel distributions from git source.
SAMLIB_EXTRA_VERSION=X
: Append X to the generated wheel version
Variables for building wheel targets:
SSC_BUILD_DIR=PATH
: Absolute path to a build directory; can speed up repeated builds
SSC_BUILD_JOBS=N
: Number of parallel build jobs
SSC_BUILD_DEBUG=yes
: Enable debug build
SSC_PATCHES=LIST
: A space-separated list of patches (without suffix), from the patches directory, to apply before building
PLATFORM_NAME=NAME
: Build platform name (e.g., manylinux2010_x86_64) The wheel build target requires environment variables to control the build.
The build-samlib.py script provides a wrapper for building samlib source and wheel distributions and sets the appropriate environment variables based on the options provided during execution.
Universal wheels
Building universal (fat) wheels on macOS requires a recent SDK. Execute the following command, replacing the deployment target if desired.
env MACOSX_DEPLOYMENT_TARGET=10.9 CMAKE_OSX_ARCHITECTURES="arm64;x86_64" CFLAGS="-arch arm64 -arch x86_64" \
python build-samlib.py --build-dir build/macos --plat-name macosx_10_9_universal2
Building manylinux wheels
Building manylinux wheels requires docker and one of the manylinux docker images.
- Pull the latest manylinux image for the desired architecture:
docker pull quay.io/pypa/manylinux_2_28_x86_64
- Open a bash shell in the docker container:
docker run -it --rm --volume $PWD:/home/samlib:rw --user $UID:$GID --workdir /home/samlib quay.io/pypa/manylinux_2_28_x86_64 bash -l
- Build the wheel using the minimum supported Python version (3.10 at the time of this writing):
/opt/python/cp10-cp10/bin/python build-samlib.py --build-dir=build/manylinux --jobs=10 --plat-name=$AUDITWHEEL_PLAT
- Exit the shell and docker container:
exit
Optionally, this one command can be used to build a manylinux wheel:
docker pull quay.io/pypa/manylinux_2_28_x86_64 && \
docker run -it --rm --volume "$PWD":/home/samlib:rw --user "$UID:$GID" --workdir /home/samlib \
quay.io/pypa/manylinux_2_28_x86_64 bash -c \
'/opt/python/cp310-cp310/bin/python build-samlib.py --build-dir=build/manylinux --jobs=10 --plat-name="$AUDITWHEEL_PLAT"'
Build issues
The following are build issues that might occur and possible solutions.
C++ header not included
SSC revision 267, 268, and 274 may fail to build on Linux with the following error:
error: ‘numeric_limits’ is not a member of ‘std’
Applying the limits patch should fix the issue.
env SAMLIB_PATCHES="limits" ... pyproject-build
gcc with -Werror=alloc-size-larger-than=
Recent versions of gcc may produce an error similar to the following error when building:
error: argument 1 range [18446744056529682432, 18446744073709551608] exceeds maximum object size 9223372036854775807 [-Werror=alloc-size-larger-than=]
52 | dest = (type *) malloc( sizeof(type)*size ); \
| ~~~~~~^~~~~~~~~~~~~~~~~~~~~
This check can be disabled by setting CXXFLAGS="-Wno-error=alloc-size-larger-than="
:
env CXXFLAGS="-Wno-error=alloc-size-larger-than=" python build-smalib.py
Visual Studio is missing ATL build tools
If C++ ATL Build Tools haven't been installed for Visual Studio, the following error may be seen:
fatal error C1083: Cannot open include file: 'AtlBase.h': No such file or directory
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distributions
Hashes for samlib-1.290.1-cp310-abi3-win_amd64.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 3063ef6a71893fd9cc7a3ff44271a23bb93bb5c0770da6a788a6b8417fb090be |
|
MD5 | 29a90a6a01671819481d2eabaf613bb6 |
|
BLAKE2b-256 | 8cfa7bfc535e77140707c249845371966d63232087228ced9349702794affd61 |
Hashes for samlib-1.290.1-cp310-abi3-manylinux_2_28_x86_64.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 1fa8cae6783bcc1517e29564ee6fac4f327cbaedd45856dafba216ca7fbd3780 |
|
MD5 | 25c941a8fe914597ddbb4dfc7f4ab335 |
|
BLAKE2b-256 | f963ec493156445d815349f5c6c24f301f9be84f8a70f5fd6fbb704d692a8a94 |
Hashes for samlib-1.290.1-cp310-abi3-macosx_10_9_universal2.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 6f8cd4f239857870acd9a1adbee4fbc5393ffbb113c26d21d3dfce6756edf6f7 |
|
MD5 | 31467ee20f4aab058857f16f73782c2a |
|
BLAKE2b-256 | 3504d95d830915019b66cf58a3b805544f0da3f5d0b05877fcbf11eda36fc2d6 |