# samlib
_Samlib_ is a high-level Python wrapper to the [_SAM_ _SSC_ library](https://github.com/NREL/ssc/)
from the [_SAM_ SDK](https://sam.nrel.gov/sdk).
## Overview
_Samlib_ uses [cffi](https://pypi.org/project/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*:
```shell
pip install samlib
```
## Example usage
```python
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](LICENSE).
The _SAM_ _SSC_, distributed in binary form in _samlib_ wheels, is also
licensed under a [BSD 3-clause license](SSC-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_](https://cmake.org/cmake/help/latest/) and
[_SSC_](https://github.com/NREL/SAM/wiki) 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.
```shell
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](https://github.com/pypa/manylinux) docker images.
1. Pull the latest *manylinux* image for the desired architecture:
```shell
docker pull quay.io/pypa/manylinux_2_28_x86_64
```
2. Open a bash shell in the docker container:
```shell
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):
```shell
/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:
```shell
exit
```
Optionally, this one command can be used to build a manylinux wheel:
```shell
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.
#### <limits> 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.
```shell
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="`:
```shell
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
```
Raw data
{
"_id": null,
"home_page": null,
"name": "samlib",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.10",
"maintainer_email": null,
"keywords": "NREL, SAM, SSC, System Advisor Model, model, techno-economic",
"author": null,
"author_email": "Brandon Carpenter <brandon@avantus.com>",
"download_url": "https://files.pythonhosted.org/packages/7f/b9/b5eed55566d5c20a8299045a01ab470c6820e06843de4c5c17034a4664f8/samlib-1.290.1.tar.gz",
"platform": null,
"description": "# samlib\n\n_Samlib_ is a high-level Python wrapper to the [_SAM_ _SSC_ library](https://github.com/NREL/ssc/)\nfrom the [_SAM_ SDK](https://sam.nrel.gov/sdk).\n\n\n## Overview\n\n_Samlib_ uses [cffi](https://pypi.org/project/cffi/) to build Pythonic library\nbindings to the _SAM_ _SSC_ library. It includes _typing_ stubs for static type\nanalysis and code completion.\n\n\n## Installation\n\nInstall _samlib_ using *pip*:\n```shell\npip install samlib\n```\n\n\n## Example usage\n\n```python\nimport samlib\nfrom samlib.modules import pvsamv1\n\nwfd = samlib.Data() # weather forecast data\nwfd.lat = 38.743212\nwfd.lon = -117.431238\n...\n\ndata = pvsamv1.Data()\ndata.solar_resource_data = wfd\ndata.use_wf_albedo = 0\n...\n\nmodule = pvsamv1.Module()\nmodule.exec(data)\n\n# Use results saved in data\n```\n\n\n## Versioning\n\n_Samlib_ uses semantic versioning with a twist. The version includes the _SSC_\nrevision number after the API major version and before the remaining API\nversion: _major.REV.minor_. This provides for pinning _samlib_ to a particular\nAPI version or to a combination of API + _SSC_ revision. The _SSC_ revision is\nthe final component of _SSC_ release versions.\n\nHere are a couple of examples:\n* `samlib ~= 1.0` specifies _samlib_ API version 0, using the latest _SSC_ revision.\n* `samlib ~= 1.240.0` specifies _samlib_ API version 0, using _SSC_ revision 240\n (which corresponds to SSC release _2020.2.29.r2.ssc.240_)\n\nThe major version is incremented for potentially breaking _samlib_ API changes\nwhile the minor version is incremented for non-breaking API changes. There may\nbe additional _.N_ suffixes for releases with duplicate _SSC_ library revisions\nor _rcN_ or _.postN_ suffixes for release candidates or post-release,\nbuild-only updates.\n\n\n## License\n\n_Samlib_ is provided under a [BSD 3-Clause license](LICENSE).\n\nThe _SAM_ _SSC_, distributed in binary form in _samlib_ wheels, is also\nlicensed under a [BSD 3-clause license](SSC-LICENSE).\n\n\n## Building\n\nBuilding requires _cmake_ >= 3.24, a C++ compiler, and the Python _build_\npackage, which can be installed with `pip install --upgrade build`.\n\nOn windows, _cmake_ can be installed using `winget install --id Kitware.CMake`.\n\n_CMake_ and _SSC_ options can be set using environment variables. See the\n[_CMake_](https://cmake.org/cmake/help/latest/) and\n[_SSC_](https://github.com/NREL/SAM/wiki) documentation for more details.\n\nEnvironment variables may be provided to control the build.\n\n#### Variables for building sdist or wheel targets:\n\nSSC_RELEASE=TAG\n\n: SSC revision to download and build; TAG should match an SSC tag from the NREL\n SSC git repository in the form `YYYY.MM.DD[.rcN].ssc.REV`. This variable is\n required when building sdist or wheel distributions from git source.\n\nSAMLIB_EXTRA_VERSION=X\n\n: Append X to the generated wheel version\n\n#### Variables for building wheel targets:\n\nSSC_BUILD_DIR=PATH\n\n: Absolute path to a build directory; can speed up repeated builds\n\nSSC_BUILD_JOBS=N\n\n: Number of parallel build jobs\n\nSSC_BUILD_DEBUG=yes\n\n: Enable debug build\n\nSSC_PATCHES=LIST\n\n: A space-separated list of patches (without suffix), from the patches\n directory, to apply before building\n\nPLATFORM_NAME=NAME\n\n: Build platform name (e.g., manylinux2010_x86_64) The _wheel_ build target\n requires environment variables to control the build.\n\nThe _build-samlib.py_ script provides a wrapper for building _samlib_ source\nand wheel distributions and sets the appropriate environment variables based\non the options provided during execution.\n\n\n### Universal wheels\n\nBuilding universal (fat) wheels on macOS requires a recent SDK. Execute the\nfollowing command, replacing the deployment target if desired.\n\n```shell\nenv MACOSX_DEPLOYMENT_TARGET=10.9 CMAKE_OSX_ARCHITECTURES=\"arm64;x86_64\" CFLAGS=\"-arch arm64 -arch x86_64\" \\\n python build-samlib.py --build-dir build/macos --plat-name macosx_10_9_universal2\n```\n\n\n### Building *manylinux* wheels\n\nBuilding *manylinux* wheels requires *docker* and one of the\n[manylinux](https://github.com/pypa/manylinux) docker images.\n\n1. Pull the latest *manylinux* image for the desired architecture:\n```shell\ndocker pull quay.io/pypa/manylinux_2_28_x86_64\n```\n2. Open a bash shell in the docker container:\n```shell\ndocker run -it --rm --volume $PWD:/home/samlib:rw --user $UID:$GID --workdir /home/samlib quay.io/pypa/manylinux_2_28_x86_64 bash -l\n```\n3. Build the wheel using the minimum supported Python version (3.10 at the time of this writing):\n```shell\n/opt/python/cp10-cp10/bin/python build-samlib.py --build-dir=build/manylinux --jobs=10 --plat-name=$AUDITWHEEL_PLAT\n```\n4. Exit the shell and docker container:\n```shell\nexit\n```\n\nOptionally, this one command can be used to build a manylinux wheel:\n```shell\ndocker pull quay.io/pypa/manylinux_2_28_x86_64 && \\\ndocker run -it --rm --volume \"$PWD\":/home/samlib:rw --user \"$UID:$GID\" --workdir /home/samlib \\\n quay.io/pypa/manylinux_2_28_x86_64 bash -c \\\n '/opt/python/cp310-cp310/bin/python build-samlib.py --build-dir=build/manylinux --jobs=10 --plat-name=\"$AUDITWHEEL_PLAT\"'\n```\n\n\n### Build issues\n\nThe following are build issues that might occur and possible solutions.\n\n#### <limits> C++ header not included\n\n_SSC_ revision 267, 268, and 274 may fail to build on Linux with the following error:\n\n```\nerror: \u2018numeric_limits\u2019 is not a member of \u2018std\u2019\n```\n\nApplying the _limits_ patch should fix the issue.\n\n```shell\nenv SAMLIB_PATCHES=\"limits\" ... pyproject-build\n```\n\n#### gcc with -Werror=alloc-size-larger-than=\n\nRecent versions of gcc may produce an error similar to the following error when building:\n\n```\nerror: argument 1 range [18446744056529682432, 18446744073709551608] exceeds maximum object size 9223372036854775807 [-Werror=alloc-size-larger-than=]\n 52 | dest = (type *) malloc( sizeof(type)*size ); \\\n | ~~~~~~^~~~~~~~~~~~~~~~~~~~~\n```\n\nThis check can be disabled by setting `CXXFLAGS=\"-Wno-error=alloc-size-larger-than=\"`:\n\n```shell\nenv CXXFLAGS=\"-Wno-error=alloc-size-larger-than=\" python build-smalib.py\n```\n\n#### Visual Studio is missing ATL build tools\n\nIf _C++ ATL Build Tools_ haven't been installed for Visual Studio, the following error may be seen:\n\n```\nfatal error C1083: Cannot open include file: 'AtlBase.h': No such file or directory\n```\n",
"bugtrack_url": null,
"license": null,
"summary": "High-level library for NREL's SAM Simulation Core (SSC)",
"version": "1.290.1",
"project_urls": {
"Source Code": "https://bitbucket.org/avantus/samlib"
},
"split_keywords": [
"nrel",
" sam",
" ssc",
" system advisor model",
" model",
" techno-economic"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "3504d95d830915019b66cf58a3b805544f0da3f5d0b05877fcbf11eda36fc2d6",
"md5": "31467ee20f4aab058857f16f73782c2a",
"sha256": "6f8cd4f239857870acd9a1adbee4fbc5393ffbb113c26d21d3dfce6756edf6f7"
},
"downloads": -1,
"filename": "samlib-1.290.1-cp310-abi3-macosx_10_9_universal2.whl",
"has_sig": false,
"md5_digest": "31467ee20f4aab058857f16f73782c2a",
"packagetype": "bdist_wheel",
"python_version": "cp310",
"requires_python": ">=3.10",
"size": 19950024,
"upload_time": "2024-05-09T20:25:49",
"upload_time_iso_8601": "2024-05-09T20:25:49.510819Z",
"url": "https://files.pythonhosted.org/packages/35/04/d95d830915019b66cf58a3b805544f0da3f5d0b05877fcbf11eda36fc2d6/samlib-1.290.1-cp310-abi3-macosx_10_9_universal2.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "f963ec493156445d815349f5c6c24f301f9be84f8a70f5fd6fbb704d692a8a94",
"md5": "25c941a8fe914597ddbb4dfc7f4ab335",
"sha256": "1fa8cae6783bcc1517e29564ee6fac4f327cbaedd45856dafba216ca7fbd3780"
},
"downloads": -1,
"filename": "samlib-1.290.1-cp310-abi3-manylinux_2_28_x86_64.whl",
"has_sig": false,
"md5_digest": "25c941a8fe914597ddbb4dfc7f4ab335",
"packagetype": "bdist_wheel",
"python_version": "cp310",
"requires_python": ">=3.10",
"size": 11371076,
"upload_time": "2024-05-09T20:26:02",
"upload_time_iso_8601": "2024-05-09T20:26:02.215724Z",
"url": "https://files.pythonhosted.org/packages/f9/63/ec493156445d815349f5c6c24f301f9be84f8a70f5fd6fbb704d692a8a94/samlib-1.290.1-cp310-abi3-manylinux_2_28_x86_64.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "8cfa7bfc535e77140707c249845371966d63232087228ced9349702794affd61",
"md5": "29a90a6a01671819481d2eabaf613bb6",
"sha256": "3063ef6a71893fd9cc7a3ff44271a23bb93bb5c0770da6a788a6b8417fb090be"
},
"downloads": -1,
"filename": "samlib-1.290.1-cp310-abi3-win_amd64.whl",
"has_sig": false,
"md5_digest": "29a90a6a01671819481d2eabaf613bb6",
"packagetype": "bdist_wheel",
"python_version": "cp310",
"requires_python": ">=3.10",
"size": 8744191,
"upload_time": "2024-05-09T20:26:14",
"upload_time_iso_8601": "2024-05-09T20:26:14.618907Z",
"url": "https://files.pythonhosted.org/packages/8c/fa/7bfc535e77140707c249845371966d63232087228ced9349702794affd61/samlib-1.290.1-cp310-abi3-win_amd64.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "7fb9b5eed55566d5c20a8299045a01ab470c6820e06843de4c5c17034a4664f8",
"md5": "ede77866c096e345f0d1a836e5b54574",
"sha256": "d117cf8aad43c3fd75f15983a7bbb36e4445ad113b60f0b5e1eda7cf463c05ff"
},
"downloads": -1,
"filename": "samlib-1.290.1.tar.gz",
"has_sig": false,
"md5_digest": "ede77866c096e345f0d1a836e5b54574",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.10",
"size": 19354,
"upload_time": "2024-05-09T20:26:19",
"upload_time_iso_8601": "2024-05-09T20:26:19.387912Z",
"url": "https://files.pythonhosted.org/packages/7f/b9/b5eed55566d5c20a8299045a01ab470c6820e06843de4c5c17034a4664f8/samlib-1.290.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-05-09 20:26:19",
"github": false,
"gitlab": false,
"bitbucket": true,
"codeberg": false,
"bitbucket_user": "avantus",
"bitbucket_project": "samlib",
"lcname": "samlib"
}
JSON