pysips 0.0.0__py3-none-any.whl

pysips/__init__.py

@@ -0,0 +1,53 @@
+"""
+Notices:
+Copyright 2025 United States Government as represented by the Administrator of the National
+Aeronautics and Space Administration. No copyright is claimed in the United States under Title 17,
+ U.S. Code. All Other Rights Reserved.
+
+The NASA Software “PySIPS” (LAR-20644-1) calls the following third-party software, which is
+subject to the terms and conditions of its licensor, as applicable at the time of licensing.  The
+third-party software is not bundled or included with this software but may be available from the
+licensor.  License hyperlinks are provided here for information purposes only.
+
+NumPy
+https://numpy.org/devdocs/license.html
+Copyright (c) 2005-2025, NumPy Developers.
+All rights reserved.
+
+h5py
+https://github.com/h5py/h5py/blob/master/LICENSE
+Copyright (c) 2008 Andrew Collette and contributors
+All rights reserved.
+
+tqdm
+https://github.com/tqdm/tqdm/blob/master/LICENCE
+Copyright (c) 2013 noamraph
+
+SciPy
+https://github.com/scipy/scipy/blob/main/LICENSE.txt
+Copyright (c) 2001-2002 Enthought, Inc. 2003, SciPy Developers.
+All rights reserved.
+
+Disclaimers
+No Warranty: THE SUBJECT SOFTWARE IS PROVIDED "AS IS" WITHOUT ANY WARRANTY OF ANY KIND, EITHER
+EXPRESSED, IMPLIED, OR STATUTORY, INCLUDING, BUT NOT LIMITED TO, ANY WARRANTY THAT THE SUBJECT
+SOFTWARE WILL CONFORM TO SPECIFICATIONS, ANY IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS FOR A
+PARTICULAR PURPOSE, OR FREEDOM FROM INFRINGEMENT, ANY WARRANTY THAT THE SUBJECT SOFTWARE WILL BE
+ERROR FREE, OR ANY WARRANTY THAT DOCUMENTATION, IF PROVIDED, WILL CONFORM TO THE SUBJECT SOFTWARE.
+THIS AGREEMENT DOES NOT, IN ANY MANNER, CONSTITUTE AN ENDORSEMENT BY GOVERNMENT AGENCY OR ANY
+PRIOR RECIPIENT OF ANY RESULTS, RESULTING DESIGNS, HARDWARE, SOFTWARE PRODUCTS OR ANY OTHER
+APPLICATIONS RESULTING FROM USE OF THE SUBJECT SOFTWARE.  FURTHER, GOVERNMENT AGENCY DISCLAIMS
+ALL WARRANTIES AND LIABILITIES REGARDING THIRD-PARTY SOFTWARE, IF PRESENT IN THE ORIGINAL
+SOFTWARE, AND DISTRIBUTES IT "AS IS."
+
+Waiver and Indemnity:  RECIPIENT AGREES TO WAIVE ANY AND ALL CLAIMS AGAINST THE UNITED STATES
+GOVERNMENT, ITS CONTRACTORS AND SUBCONTRACTORS, AS WELL AS ANY PRIOR RECIPIENT.  IF RECIPIENT'S
+USE OF THE SUBJECT SOFTWARE RESULTS IN ANY LIABILITIES, DEMANDS, DAMAGES, EXPENSES OR LOSSES
+ARISING FROM SUCH USE, INCLUDING ANY DAMAGES FROM PRODUCTS BASED ON, OR RESULTING FROM,
+RECIPIENT'S USE OF THE SUBJECT SOFTWARE, RECIPIENT SHALL INDEMNIFY AND HOLD HARMLESS THE UNITED
+STATES GOVERNMENT, ITS CONTRACTORS, AND SUBCONTRACTORS, AS WELL AS ANY PRIOR RECIPIENT, TO THE
+EXTENT PERMITTED BY LAW.  RECIPIENT'S SOLE REMEDY FOR ANY SUCH MATTER SHALL BE THE IMMEDIATE,
+UNILATERAL TERMINATION OF THIS AGREEMENT.
+"""
+
+from .regressor import PysipsRegressor

pysips/crossover_proposal.py

@@ -0,0 +1,138 @@
+"""
+Crossover-Based Proposal Generator for Symbolic Regression Models.
+
+This module provides a crossover-based proposal mechanism for symbolic regression
+that creates new candidate models by combining genetic material from existing
+models. It implements genetic programming crossover operations using bingo's
+AGraphCrossover functionality within an MCMC or evolutionary algorithm framework.
+
+The crossover operation mimics biological reproduction by exchanging subtrees
+between two parent expressions to create offspring that inherit characteristics
+from both parents. This approach can effectively explore the space of symbolic
+expressions by combining successful components from different models.
+
+Key Features
+------------
+- Random partner selection from a configurable gene pool
+- Stochastic child selection (50/50 probability between two crossover offspring)
+- Avoids self-crossover by ensuring different parent selection
+- Updateable gene pool for adaptive sampling strategies
+- Seeded random number generation for reproducible results
+
+Crossover Mechanism
+-------------------
+The crossover operation works by:
+1. Selecting a random crossover point in each parent expression tree
+2. Swapping the subtrees at those points between the two parents
+3. Producing two offspring that combine features from both parents
+4. Randomly selecting one of the two offspring as the proposal
+
+This process allows successful expression fragments to be preserved and
+recombined in novel ways, potentially discovering better solutions through
+the exploration of hybrid models.
+
+Usage Example
+-------------
+>>> # Assume you have a collection of symbolic models
+>>> gene_pool = [model1, model2, model3, model4]  # List of AGraph models
+>>>
+>>> # Create crossover proposal generator
+>>> crossover = CrossoverProposal(gene_pool, seed=42)
+>>>
+>>> # Use in MCMC or evolutionary sampling
+>>> current_model = model1
+>>> new_proposal = crossover(current_model)
+>>>
+>>> # Update gene pool as better models are discovered
+>>> updated_pool = [best_model1, best_model2, new_good_model]
+>>> crossover.update(updated_pool)
+
+Integration Notes
+-----------------
+The update() method allows for dynamic gene pool management, enabling
+adaptive strategies where successful models from the sampling process
+can be added to influence future proposals.
+"""
+
+import numpy as np
+from bingo.symbolic_regression import (
+    AGraphCrossover,
+)
+
+
+class CrossoverProposal:
+    """A proposal operator that performs crossover between AGraph models.
+
+    This class implements a callable object that creates new models by performing
+    crossover operations between an input model and randomly selected partners
+    from a gene pool. It utilizes bingo's AGraphCrossover mechanism and randomly
+    selects one of the two children produced by each crossover operation.
+
+    Parameters
+    ----------
+    gene_pool : list of AGraph
+        A collection of AGraph models that will be used as potential partners
+        during crossover operations
+    seed : int, optional
+        Random seed for the internal random number generator, used to control
+        repeatability of operations
+    """
+
+    def __init__(self, gene_pool, seed=None):
+        self._crossover = AGraphCrossover()
+        self._gene_pool = gene_pool
+        self._rng = np.random.default_rng(seed)
+
+    def _select_other_parent(self, model):
+        ind = self._rng.integers(0, len(self._gene_pool))
+        while self._gene_pool[ind] == model:
+            ind = self._rng.integers(0, len(self._gene_pool))
+        return self._gene_pool[ind]
+
+    def _do_crossover(self, model, other_parent):
+        child_1, child_2 = self._crossover(model, other_parent)
+        if self._rng.random() < 0.5:
+            return child_1
+        return child_2
+
+    def __call__(self, model):
+        """Perform crossover between the input model and a randomly selected one from the gene pool.
+
+        This method randomly selects a parent from the gene pool, performs crossover between
+        the input model and the selected parent, and returns one of the two resulting children
+        with equal probability.
+
+        Parameters
+        ----------
+        model : AGraph
+            The model to be used as the first parent in the crossover operation
+
+        Returns
+        -------
+        AGraph
+            A new model resulting from crossover between the input model and a
+            randomly selected model from the gene pool
+        """
+        other_parent = self._select_other_parent(model)
+        new_model = self._do_crossover(model, other_parent)
+        return new_model
+
+    def update(self, gene_pool, *_, **__):
+        """Update the gene pool used for selecting crossover partners.
+
+        Parameters
+        ----------
+        gene_pool : iterable of AGraph
+            The new collection of AGraph models to use as the gene pool
+        *_ : tuple
+            Additional positional arguments (ignored)
+        **__ : dict
+            Additional keyword arguments (ignored)
+
+        Notes
+        -----
+        This method allows for updating the gene pool while maintaining the same
+        crossover behavior. The additional parameters are included for compatibility
+        with other proposal update interfaces but are not used.
+        """
+        self._gene_pool = list(gene_pool)

pysips/laplace_nmll.py

@@ -0,0 +1,104 @@
+"""
+Laplace Approximation for Normalized Marginal Log-Likelihood Estimation.
+
+This module provides functionality for computing the Normalized Marginal Log-Likelihood
+(NMLL) using the Laplace approximation method. It integrates with the bingo symbolic
+regression library to evaluate the likelihood of symbolic mathematical models given
+observed data.
+
+The Laplace approximation is a method for approximating integrals that appear in
+Bayesian model selection, particularly useful for comparing different symbolic
+regression models. It approximates the marginal likelihood by making a Gaussian
+approximation around the maximum a posteriori (MAP) estimate of the parameters.
+
+Key Features
+------------
+- Integration with bingo's symbolic regression framework
+- Multiple optimization restarts to avoid local minima
+- Configurable scipy-based optimization backend
+- Automatic parameter bound initialization for robust optimization
+
+Usage Example
+-------------
+>>> import numpy as np
+>>> from bingo.symbolic_regression import AGraph
+>>>
+>>> # Generate sample data
+>>> X = np.random.randn(100, 2)
+>>> y = X[:, 0]**2 + X[:, 1] + np.random.normal(0, 0.1, 100)
+>>>
+>>> # Create NMLL evaluator
+>>> nmll_evaluator = LaplaceNmll(X, y, opt_restarts=3)
+>>>
+>>> # Evaluate a symbolic model (assuming you have an AGraph model)
+>>> # nmll_score = nmll_evaluator(model)
+
+Notes
+-----
+The multiple restart strategy helps ensure robust optimization by avoiding
+local minima in the parameter space, which is especially important for
+complex symbolic expressions.
+"""
+
+from bingo.symbolic_regression.explicit_regression import (
+    ExplicitTrainingData,
+    ExplicitRegression,
+)
+from bingo.local_optimizers.scipy_optimizer import ScipyOptimizer
+
+
+# pylint: disable=R0903
+class LaplaceNmll:
+    """Normalized Marginal Likelihood using Laplace approximation
+
+    Parameters
+    ----------
+    X : 2d Numpy Array
+        Array of shape [num_datapoints, num_features] representing the input features
+    y : 1d Numpy Array
+        Array of labels of shape [num_datapoints]
+    opt_restarts : int, optional
+        number of times to perform gradient based optimization, each with different
+        random initialization, by default 1
+    **optimizer_kwargs :
+        any keyword arguments to be passed to bingo's scipy optimizer
+    """
+
+    def __init__(self, X, y, opt_restarts=1, **optimizer_kwargs):
+        self._neg_nmll = self._init_neg_nmll(X, y)
+        self._deterministic_optimizer = self._init_deterministic_optimizer(
+            self._neg_nmll, **optimizer_kwargs
+        )
+        self._opt_restarts = opt_restarts
+
+    def _init_neg_nmll(self, X, y):
+        training_data = ExplicitTrainingData(X, y)
+        return ExplicitRegression(
+            training_data=training_data, metric="negative nmll laplace"
+        )
+
+    def _init_deterministic_optimizer(self, objective, **optimizer_kwargs):
+        if "param_init_bounds" not in optimizer_kwargs:
+            optimizer_kwargs["param_init_bounds"] = [-5, 5]
+        return ScipyOptimizer(objective, method="lm", **optimizer_kwargs)
+
+    def __call__(self, model):
+        """calaculates NMLL using the Laplace approximation
+
+        Parameters
+        ----------
+        model : AGraph
+            a bingo equation using the AGraph representation
+        """
+        self._deterministic_optimizer(model)
+        nmll = -self._neg_nmll(model)
+        consts = model.get_local_optimization_params()
+        for _ in range(self._opt_restarts - 1):
+            self._deterministic_optimizer(model)
+            trial_nmll = -self._neg_nmll(model)
+            if trial_nmll > nmll:
+                nmll = trial_nmll
+                consts = model.get_local_optimization_params()
+        model.set_local_optimization_params(consts)
+
+        return nmll

pysips/metropolis.py

@@ -0,0 +1,126 @@
+"""
+Metropolis-Hastings MCMC Implementation for Symbolic Regression.
+
+This module provides a specialized Metropolis-Hastings Markov Chain Monte Carlo
+(MCMC) sampler designed for symbolic regression models. It extends the smcpy
+VectorMCMC class to handle symbolic expressions (bingo AGraph objects) as parameters,
+with custom proposal mechanisms and likelihood evaluation for equation discovery.
+
+The implementation supports both single-process and multiprocess likelihood
+evaluation, making it suitable for computationally intensive symbolic regression
+tasks where model evaluation is the computational bottleneck.
+
+Algorithm Overview
+------------------
+The Metropolis algorithm follows the standard accept/reject framework:
+
+1. **Proposal Generation**: Uses a provided proposal function to generate
+   new symbolic expressions from current ones
+
+2. **Likelihood Evaluation**: Computes log-likelihood for proposed expressions
+   using the provided likelihood function
+
+3. **Accept/Reject Decision**: Accepts or rejects proposals based on the
+   Metropolis criterion comparing likelihoods
+
+4. **Chain Evolution**: Iteratively builds a Markov chain of symbolic
+   expressions that converges to the target distribution
+
+The key adaptation for symbolic regression is handling discrete, structured
+parameter spaces (symbolic expressions) rather than continuous parameters.
+
+Example Integration
+-------------------
+>>> from bingo.symbolic_regression import AGraph
+>>>
+>>> def likelihood_func(model):
+...     # Evaluate model on data and return log-likelihood
+...     return model.evaluate_fitness_vector(X, y)
+>>>
+>>> def proposal_func(model):
+...     # Generate new model via mutation
+...     return mutate(model)
+>>>
+>>> mcmc = Metropolis(
+...     likelihood=likelihood_func,
+...     proposal=proposal_func,
+...     prior=uniform_prior,
+...     multiprocess=True
+... )
+
+Implementation Notes
+--------------------
+- Uniform priors are assumed (evaluate_log_priors returns ones)
+- Proposal updates are called after each sampling round to maintain
+  an adaptive gene pool for crossover operations
+- Fitness values are cached on AGraph objects to avoid redundant computation
+- The implementation handles vectorized operations for efficiency
+"""
+
+from multiprocessing import Pool
+import numpy as np
+from smcpy import VectorMCMC
+
+
+class Metropolis(VectorMCMC):
+    """Class for running basic MCMC w/ the Metropolis algorithm
+
+    Parameters
+    ----------
+    likelihood : callable
+        Computes marginal log likelihood given a bingo AGraph
+    proposal : callable
+        Proposes a new AGraph conditioned on an existing AGraph; must be
+        symmetric.
+    """
+
+    def __init__(self, likelihood, proposal, prior, multiprocess=False):
+        super().__init__(
+            model=None,
+            data=None,
+            priors=[prior],
+            log_like_func=lambda *x: likelihood,
+            log_like_args=None,
+        )
+        self._equ_proposal = proposal
+        self.proposal = lambda x, z: np.array(
+            [[self._equ_proposal(xi)] for xi in x.flatten()]
+        )
+        self._is_multiprocess = multiprocess
+
+    def smc_metropolis(self, inputs, num_samples, cov=None):
+        """
+        Parameters
+        ----------
+        model : AGraph
+            model at which Markov chain initiates
+        num_samples : int
+            number of samples in the chain; includes burnin
+        """
+        log_priors, log_like = self._initialize_probabilities(inputs)
+
+        for _ in range(num_samples):
+
+            inputs, log_like, _, _ = self._perform_mcmc_step(
+                inputs, None, log_like, log_priors
+            )
+
+        self._equ_proposal.update(gene_pool=inputs.flatten())
+
+        return inputs, log_like
+
+    def evaluate_model(self, _=None):
+        return None
+
+    def evaluate_log_priors(self, inputs):
+        return np.ones((inputs.shape[0], 1))
+
+    def evaluate_log_likelihood(self, inputs):
+        if self._is_multiprocess:
+            with Pool() as p:
+                log_like = p.map(self._log_like_func, inputs.flatten())
+            for l, xi in zip(log_like, inputs.flatten()):
+                xi.fitness = l
+        else:
+            log_like = [self._log_like_func(xi) for xi in inputs.flatten()]
+        return np.c_[log_like]

pysips/mutation_proposal.py

@@ -0,0 +1,220 @@
+"""
+Mutation-Based Proposal Generator for Symbolic Regression Models.
+
+This module provides a proposal mechanism for symbolic regression that uses
+bingo's AGraph mutation operations to generate new candidate models from existing
+ones. It is designed to work within Markov Chain Monte Carlo (MCMC) sampling
+frameworks where new model proposals are needed at each step.
+
+The module implements a configurable mutation strategy that can perform various
+types of structural changes to symbolic mathematical expressions, including
+adding/removing nodes, changing operations, modifying parameters, and pruning
+or expanding expression trees.
+
+Key Features
+------------
+- Multiple mutation types: command, node, parameter, prune, and fork mutations
+- Configurable probabilities for each mutation type
+- Repeat mutation capability for more dramatic changes
+- Ensures non-identical proposals (prevents proposing the same model)
+- Seeded random number generation for reproducible results
+- Integration with bingo's ComponentGenerator for operator management
+
+Mutation Types
+--------------
+Command Mutation
+    Changes the operation at a node (e.g., '+' to '*')
+Node Mutation
+    Replaces a node with a new randomly generated subtree
+Parameter Mutation
+    Modifies the numeric constants in the expression
+Prune Mutation
+    Removes a portion of the expression tree
+Fork Mutation
+    Adds a new branch to the expression tree
+Repeat Mutation
+    Recursively applies additional mutations with specified probability
+
+Usage Example
+-------------
+>>> # Create a mutation proposal generator
+>>> proposal = MutationProposal(
+...     X_dim=3,  # 3 input features
+...     operators=["+", "subtract", "multiply", "divide"],
+...     terminal_probability=0.2,
+...     command_probability=0.3,
+...     node_probability=0.2,
+...     seed=42
+... )
+>>>
+>>> # Use in MCMC sampling (assuming you have a model)
+>>> # new_model = proposal(current_model)
+
+Notes
+-----
+The proposal generator ensures that new proposals are always different from
+the input model by repeatedly applying mutations until a change occurs. This
+prevents MCMC chains from getting stuck with identical consecutive states.
+
+The update() method is provided for compatibility with adaptive MCMC frameworks
+but currently performs no operations, as the mutation probabilities are fixed
+at initialization.
+"""
+
+import numpy as np
+from bingo.symbolic_regression import (
+    ComponentGenerator,
+    AGraphMutation,
+)
+
+
+class MutationProposal:
+    """Proposal functor that performs bingo's Agraph mutation
+
+    Parameters
+    ----------
+    x_dim : int
+        dimension of input data (number of features in dataset)
+    operators : list of str
+        list of equation primatives to allow, e.g. ["+", "subtraction", "pow"]
+    terminal_probability : float, optional
+        [0.0-1.0] probability that a new node will be a terminal, by default 0.1
+    constant_probability : float, optional
+        [0.0-1.0] probability that a new terminal will be a constant, by default
+        weighted the same as a single feature of the input data
+    command_probability : float, optional
+        probability of command mutation, by default 0.2
+    node_probability : float, optional
+        probability of node mutation, by default 0.2
+    parameter_probability : float, optional
+        probability of parameter mutation, by default 0.2
+    prune_probability : float, optional
+        probability of pruning (removing a portion of the equation), by default 0.2
+    fork_probability : float, optional
+        probability of forking (adding an additional branch to the equation),
+        by default 0.2
+    repeat_mutation_probability : float, optional
+        probability of a repeated mutation (applied recursively). default 0.0
+    seed : int, optional
+        random seed used to control repeatability
+    """
+
+    # pylint: disable=R0913,R0917
+    def __init__(
+        self,
+        x_dim,
+        operators,
+        terminal_probability=0.1,
+        constant_probability=None,
+        command_probability=0.2,
+        node_probability=0.2,
+        parameter_probability=0.2,
+        prune_probability=0.2,
+        fork_probability=0.2,
+        repeat_mutation_probability=0.0,
+        seed=None,
+    ):
+        self._rng = np.random.default_rng(seed)
+
+        component_generator = ComponentGenerator(
+            input_x_dimension=x_dim,
+            terminal_probability=terminal_probability,
+            constant_probability=constant_probability,
+        )
+        for comp in operators:
+            component_generator.add_operator(comp)
+
+        self._mutation = AGraphMutation(
+            component_generator,
+            command_probability,
+            node_probability,
+            parameter_probability,
+            prune_probability,
+            fork_probability,
+        )
+        self._repeat_mutation_prob = repeat_mutation_probability
+
+    def _do_mutation(self, model):
+        new_model = self._mutation(model)
+        while self._rng.random() < self._repeat_mutation_prob:
+            new_model = self._mutation(new_model)
+        return new_model
+
+    def __call__(self, model):
+        """
+        Apply mutation to generate a new symbolic expression model.
+
+        This method takes a symbolic regression model (AGraph) as input and returns
+        a new model created by applying one or more mutation operations. The method
+        guarantees that the returned model is different from the input model by
+        repeating mutations if necessary.
+
+        Parameters
+        ----------
+        model : AGraph
+            The input symbolic regression model to be mutated. This should be a
+            bingo AGraph instance representing a mathematical expression.
+
+        Returns
+        -------
+        AGraph
+            A new symbolic regression model created by applying mutation(s) to
+            the input model. Guaranteed to be different from the input model.
+
+        Mutation Process
+        ---------------
+        1. **Initial Mutation**: Applies the configured mutation operation to the model
+        2. **Repeat Mutations**: May apply additional mutations based on repeat_mutation_probability
+        3. **Difference Check**: Ensures the new model differs from the original one
+        4. **Repeated Attempts**: If the mutation produces an identical model, tries again
+
+        Notes
+        -----
+        - The mutation type applied is selected probabilistically based on the
+        probabilities specified during initialization (command_probability,
+        node_probability, etc.)
+        - The repeat mutation feature allows for more dramatic changes by applying
+        multiple mutations in sequence with probability repeat_mutation_probability
+        - This method will always return a different model, never the same as the input
+
+        See Also
+        --------
+        AGraphMutation : Bingo's mutation implementation used internally
+        """
+        new_model = self._do_mutation(model)
+        while new_model == model:
+            new_model = self._do_mutation(model)
+        return new_model
+
+    def update(self, *args, **kwargs):
+        """
+        Update method for compatibility with adaptive MCMC frameworks.
+
+        This method is provided to maintain API compatibility with other proposal
+        mechanisms that support adaptive behavior. In the current implementation,
+        the method is a no-op as the mutation proposal does not adapt its behavior
+        based on sampling history.
+
+        Parameters
+        ----------
+        *args : tuple
+            Positional arguments (not used in the current implementation).
+        **kwargs : dict
+            Keyword arguments (not used in the current implementation).
+
+        Returns
+        -------
+        None
+            This method does not return any value.
+
+        Notes
+        -----
+        Future versions might implement adaptive behavior such as:
+        - Adjusting mutation probabilities based on acceptance rates
+        - Learning which mutation types are more effective for a given problem
+
+        In composite proposal mechanisms that combine multiple proposal types
+        (such as RandomChoiceProposal), this method will be called as part
+        of the update process, but currently has no effect on this proposal.
+        """
+        # pass