There are a variety of long-standing conventions that have become standard
across the project. This list will be amended as conventions come up, so please
refer to it regularly for updates:
Fail loudly: Silent failure is strongly discouraged. Code should
defensively guard against unexpected or unsupported cases and raise
explicit exceptions (e.g., NotImplementedError) rather than silently
producing incorrect or ambiguous results. Some of the most difficult
Pyomo bugs to diagnose arise from silently incorrect mathematics.
Document and enforce assumptions: When behavior that a user could
reasonably expect is ambiguous, code should clearly document the
assumptions being made and fail loudly when those assumptions are
violated.
Print statements: Avoid printing or writing directly to stdout. Pyomo is a
library, not an application, and copious output can interfere with downstream
tools and workflows. Use the appropriate logger instead. Print
information only when the user has enabled or requested it.
Logging: Use Python’s logging framework for diagnostic and
informational output. Loggers should generally be created using
logging.getLogger(__name__) to ensure messages are properly scoped
and can be enabled or filtered at the module or package level.
Active components define the model: Pyomo models are defined as the
set of active components reachable from the root Block. Not all
modeling objects are active components (notably, Var objects are
not). Algorithms and writers should respect this distinction when
traversing or interpreting models.
Avoid iterating over variables directly: Direct iteration over
variables using m.component_data_objects(Var, ...) is rarely
appropriate, as it returns all variables declared on the model
hierarchy regardless of their mathematical relevance. When gathering
variables associated with a model formulation, prefer utilities such as
get_vars_from_components with Constraint or
(Constraint, Objective) as the component types.
Writers must validate component types: Writers and solver-facing
infrastructure should explicitly detect and warn about active
Pyomo components they do not recognize. Pyomo supports extended
modeling environments (e.g., DAE and GDP), and silently ignoring
unexpected structures can result in invalid solver input. The utility
categorize_valid_components in pyomo.repn.util may be used to
assist with this validation.
Do not use names as identifiers: Component names and strings should
generally not be used to track Pyomo components within algorithms or
writers. Names are not guaranteed to be unique or stable across model
transformations. Prefer data structures from
pyomo.common.collections that support using components directly as
keys.
Environment imports: Import the main Pyomo environment as
import pyomo.environ as pyo. Avoid all uses of import *.
Export lists: Do not define __all__ in modules.
Public symbols are determined by naming and documentation, not explicit lists.
Circular imports: Make every effort to avoid circular imports. When
circular imports are absolutely necessary, leverage attempt_import()
to explicitly break the cycle. To help with this, some module namespaces
have additional requirements:
Naming conventions: Follow PEP 8 naming conventions, including
descriptive snake_case for functions and variables and
PascalCase for classes. Functions should generally be named as verb
phrases, while classes should be noun-like representations of concepts.
Avoid code duplication: Repeated or copy-pasted code is strongly
discouraged. Duplication increases maintenance burden and often leads
to inconsistent behavior. When code patterns begin to repeat,
contributors are encouraged to refactor common functionality or
discuss design alternatives with the core development team.
URLs: All links in code, comments, and documentation must use https
rather than http wherever possible.
File headers: Every .py file must begin with the standard Pyomo
copyright header:
# ____________________________________________________________________________________
#
# Pyomo: Python Optimization Modeling Objects
# Copyright (c) 2008-2026 National Technology and Engineering Solutions of Sandia, LLC
# Under the terms of Contract DE-NA0003525 with National Technology and Engineering
# Solutions of Sandia, LLC, the U.S. Government retains certain rights in this
# software. This software is distributed under the 3-clause BSD License.
# ____________________________________________________________________________________
Update the year range as appropriate when modifying files.
Full commit history: We do not squash-merge Pull Requests,
preferring to retain the entire commit history.
Pull Request naming: Pull Request titles are added to the CHANGELOG
and the release notes. The Pyomo development team reserves the right to
alter titles as appropriate to ensure they fit the look and feel of
other titles in the CHANGELOG.