RomCom User Guide§
Reduced Order Modelling via GSA/GPR, by Robert A. Milton and Solomon F. Brown.
Danger
This documentation is currently under construction
Welcome§
The RomCom Python library performs Reduction of Order by Marginalization (ROM) Computations via Global Sensitivity Analysis (GSA) using Gaussian Process Regression (GPR). The mathematics behind this software is covered in some detail in the following preprint Milton and Brown 2025.
- GPR§
Gaussian Process Regression. A quite general technique for representing a functional dataset as a (Gaussian) stochastic process described thoroughly in [Rasmussen and Williams 2005].
- GSA§
Global Sensitivity Analysis. This Assesses and ranks the relevance of a system’s inputs to its outputs by a variety of methods covered broadly in [Saltelli et al. 2007] and [Razavi et al. 2021]. RomCom deals exclusively with the variance based method of Ilya M. Sobol, extended to novel Sobol’ matrices.
- ROM§
Reduction of Order by Marginalization. A novel approach to locating an Active Subspace (AS) using conditional variances or Sobol’ indices. In the Active Subspace technique [Constantine 2014] the input basis is rotated to align with the eigenvectors of the squared Jacobian vector. In ROM, the input basis is rotated to maximise the Sobol’ index of the first \(m\) inputs.
We recommend reading this page up to the general Glossary, which is intended for reference. RomCom considers source code and User Guide as one: Conventions and Glossary entries apply equally to both, within format limitations.
Installation§
Detailed installation instructions are contained in RomCom’s README.md.
Contents§
We recommend reading Intro, Usage and Data, in that order, then experiment.
Conventions§
RomCom abides by the spirit of PEP 8, which allows conventions to be flexed, but only when needs must. `Annotations`_ demonstrate this.
RomCom abides by the letter of PEP 8 except for:
source code line wraps at 114 characters, to fit web browsers.
a neurotic aversion to ugly under_scores and BLOCK_CAPS.
Names§
RomCom views any Python entity as falling into one of three categories, each with its own naming convention.
- namespace§
Packages and modules are referred to in lowercase (abbreviations or single words).
- Class§
Classes and Types are referred to in UpperCamelCase. The User Guide italicizes AbstractClasses – i.e those not instantiable as objects.
- object§
Anything which is neither namespace nor Class is referred to in lowerCamelCase. This includes classInstances, classAttributes and instanceAttributes.
Constants§
Constancy in RomCom is determined by scope, not name. Every namespace or Class attribute in RomCom is a constant which must not be modified. Bespoke constants should be implemented by subclassing, leaving the RomCom parent unmodified. An UpperCamelCase constant refers to a Class, a lowerCamelCase constant does not.
Type Annotations§
RomCom is copiously annotated, in the spirit of a statically typed library.
Type annotation is the subject of rc.base.definitions, which simply extends
Python Standard Library typing.
For aliasing and naming conflict resolution, rc.base.definitions imports the core libraries pandas,
numpy, torch, and wraps them in aliasing classes Pd, Np, Tc. This provides the namespace/Class duals
pd | Pd, np | Np, and tc | Tc.
Character Set§
^
RomCom assumes UTF-8 encoding but actually uses only one non-ASCII character, the Box Drawing Light Vertical │ (U+2502).
It denotes probablistic conditioning, which delimits categories in a semantically coherent and instructive way.
Semantics affect function in RomCom file generation, so they are expressed using a character unlikely to occur in user data.
User data may safely contain any printable UTF character except │, including the common Vertical Line | (U+007C, ASCII x7C) which is noticeably shorter.
If needs must, the category delimiter can be changed globally in user code by resetting the constant
rc.data.models.Normalization.defaultMetaData['category delimiter'] before any RomCom code is executed.
Internal Code Conventions§
Begin every source file with:
# BSD 3-Clause License.
#
# Copyright (c) 2019-2025 Robert A. Milton. All rights reserved.
#
# Redistribution and use in source and binary forms, with or without modification, are permitted provided that
# the following conditions are met:
#
# 1. Redistributions of source code must retain the above copyright notice, this list of conditions and the
# following disclaimer.
#
# 2. Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the
# following disclaimer in the documentation and/or other materials provided with the distribution.
#
# 3. Neither the name of the copyright holder nor the names of its contributors may be used to endorse or
# promote products derived from this software without specific prior written permission.
#
# THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED
# WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A
# PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY
# DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
# PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
# CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE
# OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE,
# EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
# TODO: \"\"\" DOCSTRING.\"\"\"
from __future__ import annotations
from rc.base.definitions import *
from rc import [WHATEVER IS NEEDED]
import [EXTERNAL LIBRARIES AS NEEDED]
import [PYTHON STANDARD LIBRARIES AS NEEDED]
Internal Documentation Conventions§
RomCom uses Sphinx for documentation, which is written in reStructuredText (reST). The documentation is generated from the source code, so it is important to keep the documentation in sync with the code. For a full rebuild of the documentation, run the following commands from the root directory of the RomCom repository:
python utilities.py clean
sphinx-build -M html sourcedir outputdir
Python References§
The coding paradigm and style of RomCom borrows heavily from three essential references
The Python Standard Library by the Python Software Foundation.
The Lizard Book by Luciano Ramalho.
Effective Python by Brett Slatkin.
Extensive use is made of the following third-party Python libraries
pandas for data storage and manipulation.
numpy for numerical computations.
torch for tensor computations.
scipy for miscellaneous scientific computations.
and, of course, the common language which binds us together
- Python§
- The Python Standard Library by the Python Software Foundation.§
RomCom is enormously grateful to these authors for the breathtaking quality and scope of their work.
Glossary§
RomCom is, for better or worse, laced with Python lingo. The User Guide follows Python convention by using | to denote logical OR.