Skip to main content

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.

  1. Pull the latest manylinux image for the desired architecture:
docker pull quay.io/pypa/manylinux_2_28_x86_64
  1. 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
  1. 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
  1. 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


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

samlib-1.290.1.tar.gz (19.4 kB view details)

Uploaded Source

Built Distributions

samlib-1.290.1-cp310-abi3-win_amd64.whl (8.7 MB view details)

Uploaded CPython 3.10+ Windows x86-64

samlib-1.290.1-cp310-abi3-manylinux_2_28_x86_64.whl (11.4 MB view details)

Uploaded CPython 3.10+ manylinux: glibc 2.28+ x86-64

samlib-1.290.1-cp310-abi3-macosx_10_9_universal2.whl (20.0 MB view details)

Uploaded CPython 3.10+ macOS 10.9+ universal2 (ARM64, x86-64)

File details

Details for the file samlib-1.290.1.tar.gz.

File metadata

  • Download URL: samlib-1.290.1.tar.gz
  • Upload date:
  • Size: 19.4 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/5.0.0 CPython/3.10.13

File hashes

Hashes for samlib-1.290.1.tar.gz
Algorithm Hash digest
SHA256 d117cf8aad43c3fd75f15983a7bbb36e4445ad113b60f0b5e1eda7cf463c05ff
MD5 ede77866c096e345f0d1a836e5b54574
BLAKE2b-256 7fb9b5eed55566d5c20a8299045a01ab470c6820e06843de4c5c17034a4664f8

See more details on using hashes here.

File details

Details for the file samlib-1.290.1-cp310-abi3-win_amd64.whl.

File metadata

  • Download URL: samlib-1.290.1-cp310-abi3-win_amd64.whl
  • Upload date:
  • Size: 8.7 MB
  • Tags: CPython 3.10+, Windows x86-64
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/5.0.0 CPython/3.10.13

File hashes

Hashes for samlib-1.290.1-cp310-abi3-win_amd64.whl
Algorithm Hash digest
SHA256 3063ef6a71893fd9cc7a3ff44271a23bb93bb5c0770da6a788a6b8417fb090be
MD5 29a90a6a01671819481d2eabaf613bb6
BLAKE2b-256 8cfa7bfc535e77140707c249845371966d63232087228ced9349702794affd61

See more details on using hashes here.

File details

Details for the file samlib-1.290.1-cp310-abi3-manylinux_2_28_x86_64.whl.

File metadata

File hashes

Hashes for samlib-1.290.1-cp310-abi3-manylinux_2_28_x86_64.whl
Algorithm Hash digest
SHA256 1fa8cae6783bcc1517e29564ee6fac4f327cbaedd45856dafba216ca7fbd3780
MD5 25c941a8fe914597ddbb4dfc7f4ab335
BLAKE2b-256 f963ec493156445d815349f5c6c24f301f9be84f8a70f5fd6fbb704d692a8a94

See more details on using hashes here.

File details

Details for the file samlib-1.290.1-cp310-abi3-macosx_10_9_universal2.whl.

File metadata

File hashes

Hashes for samlib-1.290.1-cp310-abi3-macosx_10_9_universal2.whl
Algorithm Hash digest
SHA256 6f8cd4f239857870acd9a1adbee4fbc5393ffbb113c26d21d3dfce6756edf6f7
MD5 31467ee20f4aab058857f16f73782c2a
BLAKE2b-256 3504d95d830915019b66cf58a3b805544f0da3f5d0b05877fcbf11eda36fc2d6

See more details on using hashes here.

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page