nrel-pysam-legacy

Unofficial CPython 3.14 rebuild of NREL-PySAM 4.2.0, retaining the original SSC 280 simulation engine and battery models.

The distribution is named nrel-pysam-legacy; its import namespace is PySAMLegacy. This is a compatibility fork, not an official NREL/NLR release.

pip install nrel-pysam-legacy==4.2.0.post2

It can be installed alongside nlr-pysam, which uses PySAM. Legacy native libraries have distinct filenames and SONAMEs, preventing engine collisions. If upgrading from 4.2.0.post1, uninstall that release first and reinstall nlr-pysam: the old release shared its files with the PySAM namespace.

import PySAMLegacy.BatteryStateful as BatteryStateful

battery = BatteryStateful.default("LFPGraphite")

This release targets ordinary (GIL-enabled) CPython 3.14 on Linux x86-64. Free-threaded Python, other Python versions, and other platforms are not claimed to be supported by this build.

The Python extensions are compiled for CPython 3.14. The original native SSC and SAM API libraries, defaults, Python helpers, and type stubs originate from the published 4.2.0 wheel. PySAMLegacy.__version__ remains 4.2.0, identifying the upstream model; the distribution version is 4.2.0.post2.

The generated wrappers consistently import PySAMLegacy.AdjustmentFactors to avoid loading its static type twice under different module names. An invalid decrement of a local pointer's reference count is also removed. The original wrapper fixes are recorded in python314-wrapper.patch. Namespace references now use PySAMLegacy; native ELF linking metadata is changed to isolate the libraries. Simulation code is unchanged.

Upstream code and binary redistribution are covered by the included BSD 3-Clause license. See PROVENANCE.json for pinned sources and checksums.

Choose the engine per simulation without changing global imports:

from importlib import import_module

namespace = {"current": "PySAM", "legacy": "PySAMLegacy"}[payload["pysam_engine"]]
battery_module = import_module(f"{namespace}.BatteryStateful")
battery_tools = import_module(f"{namespace}.BatteryTools")
battery = battery_module.default("LFPGraphite")

Keep models, sizing helpers, and native pointers within the selected namespace. The simulator must carry this selection per simulation; this package does not add a payload field to the simulator automatically.