SymMaps
The package is generally used to set up and navigate systems of equations/variables using symbols defined over pandas indices. The package contains the following useful classes:
Helper classes (base.py)
symMaps/base.py defines three small helper classes that simplifies the task of making adjustments to symbols defined over pandas indices. An introduction to the class is added as part of the documentation for the SimplySys (docs_SimpleSys.ipynb). Here is a short description of the helper classes:
Lag
```
Utility for creating lagged versions of pandas indices and Series.
The Lag class provides static helpers that shift a pandas Index or Series
backwards (i.e. create index/value pairs corresponding to v[index - lag]).
It supports 1D indices and MultiIndex objects via level or dict specifications.
Key methods
- series(v, lag, level=None, fkeep=False, bfill='exo', exo=0):
Return a pd.Series with values shifted according to `lag`. Handles options:
fkeep: keep forward-shifted indices outside original domain.
bfill: how to backfill values not present in original series ('exo','ss', False).
exo: numeric value used when bfill == 'exo'.
- idx(idx, lag, level=None):
Return a shifted Index (or MultiIndex) corresponding to lag specification.
Typical usage
- Create lagged parameters or variables before adding them to linear
constraints in LPSys (see symMaps.lpSys.LPSys.initA_lag).
```
Lead
```
Lead is a thin wrapper around Lag that applies a forward shift.
Lead inverts the sign of the lag input and then calls the Lag helpers.
This allows callers to express leads (future indices) using the same
interface as lags. All parameters and options are passed through to Lag.
Example:
Lead.series(v, lead, fkeep=True, bfill=False)
```
Roll
```
Utilities to 'roll' (circularly shift) pandas indices and Series.
Roll performs circular rotations of index levels. Unlike Lag, Roll does not
create new index elements; it permutes existing ones. Methods mirror those
of Lag but use numpy.roll semantics. Useful for circular boundary conditions
or categorical index rotations.
Key methods
- series(v, roll, level=None): return a Series whose index is rolled.
- idx(idx, roll, level=None): return rolled Index or MultiIndex.
```
SimpleSys (simpleSys.py)
symMaps.simplySys.py defines a simple way of navigating a collection of symbols defined over pandas indices in the class SimpleSys. The notebook docs_SimpleSys.ipynb goes through the setup and shows examples of how to use this.
Linear programming (lpSys.py)
symMaps.lpSys.py defines three classes that are especially useful for navigating linear programming problems. The main class here is LPSys that includes a lot of different methods to set up sparse coefficient matrices for LP problems. See docs_LPSys for a documentation of this class. Here is a brief description of the class:
```
LPSys — a helper for building and compiling linear programs using pandas indices.
Purpose
- Provide a high-level, index-aware API for declaring variables, constraints
and their linear relationships using pandas Index / MultiIndex objects.
- Maintain sparse definitions (series over partial domains) and compile them
into the dense structures required by solvers (e.g. scipy.optimize.linprog).
Key concepts / attributes
- self.v: dict mapping variable name -> domain (pd.Index, pd.MultiIndex or None for scalar).
- self.eq, self.ub: dict mapping constraint name -> domain (pd.Index, pd.MultiIndex or None for scalar).
- self.lp: dict-like store for problem components:
- 'A_eq' / 'A_ub' : AMDictionaries of AMatrix objects (matrix coefficients).
- 'c', 'l', 'u' etc: coefficient dictionaries (GpyDict / pandas Series).
- self.maps: compiled mappings from pandas domains to stacked global variable indices.
- self.len: dict of lengths for domains (used when building arrays).
- self.out: compiled arguments (A, b, c, bounds) ready for solver.
Important methods (high-level)
- compileMaps(): build internal mappings (self.maps) from declared domains (self.v, self.eq, self.ub).
- compileParams() / compileParams(...): convert self.lp parameter dicts to solver vectors/matrices.
- initA_infer(name, series, v, constr, attr='eq'): add AMatrix using inference from series index.
- initA_lag(...), initA_roll(...): helpers to add matrix coefficients where the variable
index is a lag/roll (calls symMaps.base.Lag / Lead / Roll utilities).
- lazyA(...), lazyA_lag(...): broadcast a (possibly partial) coefficient series across
combined domains and add as AMatrix; variants handle lag/roll mappings before broadcasting.
- sparse_bounds() / dense_bounds(): helpers to convert bound declarations to solver bounds.
- unloadSol(sol): map solver solution back to pandas Series / dictionaries for variables and duals.
Notes on lags/leads/rolls
- This class uses Lag, Lead and Roll utilities (defined in symMaps.base) to transform
pandas indices/series before building matrix blocks. These utilities are expected
to return aligned pd.Index / pd.Series objects that match the intended constraint domains.
- When adding lagged coefficients, the constraint domain and variable domain can be
different; initA_lag / lazyA_lag handle mapping between them via index transformations.
Usage (brief example)
self.v = {'y': pd.MultiIndex.from_product([t, i])}
self.eq = {'vec_tx0': t[1:]}
self.compileMaps()
# add parameter defined on y domain
par = pd.Series(..., index=self.v['y'])
# add a lagged coefficient that aligns par[t-1,i] with constraint vec_tx0[t]
self.initA_lag('vec_tx0_y', series=par, v='y', constr='vec_tx0', attr='eq',
lag=1, level='t', fkeep=False, bfill=False)
Implementation details
- Internally uses lightweight AMatrix objects and AMDict containers to keep the
model sparse until compileParams() is called.
- Many methods accept scalar, 1d or nd index inputs and dispatch based on
pandas Index vs MultiIndex types.
See also
- symMaps.base.Lag, Lead, Roll — helpers for index/series transformations.
- AMatrix, AMDict definitions in this module (below) — low-level matrix block abstractions.
```
Metadata
Release files for symMaps 0.0.4
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| symmaps-0.0.4.tar.gz | 18.6 kB | Without provenance | Details for symmaps-0.0.4.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| symmaps-0.0.4-py3-none-any.whl | Python 3 | none | any | Details for symmaps-0.0.4-py3-none-any.whl |
Total release size: 38.5 kB
Release files / symmaps-0.0.4.tar.gz
| Download URL | symmaps-0.0.4.tar.gz |
|---|---|
| Size | 18.6 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
630437b8a81163c772b039a067e35a8e734bd9f6e843d205d56d07c810390fec
|
|
BLAKE2b-256 checksum How to use checksums |
c6eb9ff5f9bb9845c1f646e0fd71d678719321e31057b36fedc08645ca25a14c
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.12.4
|
Release files / symmaps-0.0.4-py3-none-any.whl
| Download URL | symmaps-0.0.4-py3-none-any.whl |
|---|---|
| Size | 19.9 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
1e875d9d2990fa5107b80057d7b199561344960a94389e2af26328df4635f93b
|
|
BLAKE2b-256 checksum How to use checksums |
708fd75f1815258afedd1b02f5444fd1d8d6aeeb327f1dc7c9984ae656c52f6c
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.12.4
|
Security for symMaps 0.0.4
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.