Package: samlib
samlibSamlibis a high-level Python wrapper to theSAMSSClibraryfrom theSAMSDK.OverviewSamlibusescffito build Pythonic library
bindings to theSAMSSClibrary. It includestypingstubs for static type
analysis and code completion.InstallationInstallsamlibusingpip:pipinstallsamlibExample usageimportsamlibfromsamlib.modulesimportpvsamv1wfd=samlib.Data()# weather forecast datawfd.lat=38.743212wfd.lon=-117.431238...data=pvsamv1.Data()data.solar_resource_data=wfddata.use_wf_albedo=0...module=pvsamv1.Module()module.exec(data)# Use results saved in dataVersioningSamlibuses semantic versioning with a twist. The version includes theSSCrevision number after the API major version and before the remaining API
version:major.REV.minor. This provides for pinningsamlibto a particular
API version or to a combination of API +SSCrevision. TheSSCrevision is
the final component ofSSCrelease versions.Here are a couple of examples:samlib ~= 0specifiessamlibAPI version 0, using the latestSSCrevision.samlib ~= 0.240specifiessamlibAPI version 0, usingSSCrevision 240
(which corresponds to SSC release2020.2.29.r2.ssc.240)The major version is incremented for potentially breakingsamlibAPI changes
while the minor version is incremented for non-breaking API changes. There may
be additional.Nsuffixes for releases with duplicateSSClibrary revisions
orrcNor.postNsuffixes for release candidates or post-release,
build-only updates.LicenseSamlibis provided under aBSD 3-Clause license.TheSAMSSC, distributed in binary form insamlibwheels, is also
licensed under aBSD 3-clause license.BuildingBuilding requirescmake>= 3.24, a C++ compiler, and the Pythonbuildpackage, which can be installed withpip install --upgrade build.On windows,cmakecan be installed usingwinget install --id Kitware.CMake.CMakeandSSCoptions can be set using environment variables. See theCMakeandSSCdocumentation 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 formYYYY.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 versionVariables for building wheel targets:SSC_BUILD_DIR=PATH: Absolute path to a build directory; can speed up repeated buildsSSC_BUILD_JOBS=N: Number of parallel build jobsSSC_BUILD_DEBUG=yes: Enable debug buildSSC_PATCHES=LIST: A space-separated list of patches (without suffix), from the patches
directory, to apply before buildingPLATFORM_NAME=NAME: Build platform name (e.g., manylinux2010_x86_64) Thewheelbuild target
requires environment variables to control the build.Thebuild-samlib.pyscript provides a wrapper for buildingsamlibsource
and wheel distributions and sets the appropriate environment variables based
on the options provided during execution.Universal wheelsBuilding universal (fat) wheels on macOS requires a recent SDK. Execute the
following command, replacing the deployment target if desired.envMACOSX_DEPLOYMENT_TARGET=10.9CMAKE_OSX_ARCHITECTURES="arm64;x86_64"CFLAGS="-arch arm64 -arch x86_64"\pythonbuild-samlib.py--build-dirbuild/macos--plat-namemacosx_10_9_universal2BuildingmanylinuxwheelsBuildingmanylinuxwheels requiresdockerand one of themanylinuxdocker images.Pull the latestmanylinuximage for the desired architecture:dockerpullquay.io/pypa/manylinux_2_28_x86_64Open a bash shell in the docker container:dockerrun-it--rm--volume$PWD:/home/samlib:rw--user$UID:$GID--workdir/home/samlibquay.io/pypa/manylinux_2_28_x86_64bash-lBuild a wheel for each desired Python version:/opt/python/cp38-cp38/bin/pythonbuild-samlib.py--build-dir=build/manylinux--jobs=10--plat-name=$AUDITWHEEL_PLATExit the shell and docker container:exitOptionally, this one command can be used to build wheels for a range of Python versions:dockerpullquay.io/pypa/manylinux_2_28_x86_64&&\dockerrun-it--rm--volume"$PWD":/home/samlib:rw--user"$UID:$GID"--workdir/home/samlib\quay.io/pypa/manylinux_2_28_x86_64bash-c\'for v in {10..12}; do /opt/python/cp3$v-cp3$v/bin/python build-samlib.py --build-dir=build/manylinux --jobs=10 --plat-name="$AUDITWHEEL_PLAT"; done'Build issuesThe following are build issues that might occur and possible solutions.C++ header not includedSSCrevision 267, 268, and 274 may fail to build on Linux with the following error:error: ‘numeric_limits’ is not a member of ‘std’Applying thelimitspatch should fix the issue.envSAMLIB_PATCHES="limits"...pyproject-buildgcc 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 settingCXXFLAGS="-Wno-error=alloc-size-larger-than=":envCXXFLAGS="-Wno-error=alloc-size-larger-than="pythonbuild-smalib.pyVisual Studio is missing ATL build toolsIfC++ ATL Build Toolshaven'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