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 NLR 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 macOS 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

2. 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

3. 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

4. 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