samlib 1.290.1

Description:

samlib 1.290.1

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