---
title: penalties
sidebarTitle: penalties
---

# `catalax.neural.penalties.penalties`

## Classes

### `Penalties` <sup><a href="https://github.com/JR-1991/Catalax/blob/master/catalax/neural/penalties/penalties.py#L31" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>


A collection of penalty functions that can be applied to neural models during training.

This class manages multiple penalty functions and applies them collectively to a model.
Penalties are used to enforce constraints or encourage certain behaviors in the model
parameters during optimization.


**Methods:**

#### `add_penalty` <sup><a href="https://github.com/JR-1991/Catalax/blob/master/catalax/neural/penalties/penalties.py#L56" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
add_penalty(self, name: str, fun: Callable, alpha: float, **kwargs) -> Penalties
```

Add a penalty function to the collection.

**Args:**
- `name`: Name of the penalty
- `fun`: The penalty function to apply
- `alpha`: Strength coefficient for the penalty
- `**kwargs`: Additional keyword arguments for the penalty function

**Returns:**
- Self for method chaining


#### `update_alpha` <sup><a href="https://github.com/JR-1991/Catalax/blob/master/catalax/neural/penalties/penalties.py#L95" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
update_alpha(self, alpha: Optional[float], **kwargs) -> Penalties
```

Update the alpha parameter for all penalties.

**Args:**
- `alpha`: New alpha value to set for all penalties. If None, only penalties
specified in kwargs will be updated.
- `**kwargs`: Specific alpha values for individual penalties by name

**Returns:**
- New Penalties instance with updated alpha values


#### `for_neural_ode` <sup><a href="https://github.com/JR-1991/Catalax/blob/master/catalax/neural/penalties/penalties.py#L121" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
for_neural_ode(cls, l2_alpha: Optional[float] = 0.001, l1_alpha: Optional[float] = None) -> Penalties
```

Create a collection of penalties specifically designed for NeuralODE models.


#### `for_universal_ode` <sup><a href="https://github.com/JR-1991/Catalax/blob/master/catalax/neural/penalties/penalties.py#L145" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
for_universal_ode(cls, l2_gate_alpha: Optional[float] = 0.001, l1_gate_alpha: Optional[float] = None, l2_residual_alpha: Optional[float] = 0.001, l1_residual_alpha: Optional[float] = None, l2_mlp_alpha: Optional[float] = 0.001, l1_mlp_alpha: Optional[float] = None) -> Penalties
```

Create a collection of penalties specifically designed for UniversalODE models.


#### `for_rateflow` <sup><a href="https://github.com/JR-1991/Catalax/blob/master/catalax/neural/penalties/penalties.py#L201" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
for_rateflow(cls, alpha: float = 0.1, density_alpha: Optional[float] = None, bipolar_alpha: Optional[float] = None, conservation_alpha: Optional[float] = None, duplicate_reactions_alpha: Optional[float] = None, integer_alpha: Optional[float] = None, sparsity_alpha: Optional[float] = None, l2_alpha: Optional[float] = None, null_space_alpha: Optional[float] = None) -> Penalties
```

Create a collection of penalties specifically designed for NeuralRDE models.

This factory method creates a comprehensive set of penalties that are commonly
used with NeuralRDE models, including stoichiometric matrix penalties and
weight regularization penalties.

**Args:**
- `alpha`: Default penalty strength coefficient for all penalties
- `density_alpha`: Specific alpha for density penalty (sparsity of stoich matrix)
- `bipolar_alpha`: Specific alpha for bipolar penalty (mass balance)
- `conservation_alpha`: Specific alpha for conservation penalty
- `duplicate_reactions_alpha`: Specific alpha for duplicate reactions penalty
- `integer_alpha`: Specific alpha for integer penalty (encouraging integer coefficients)
- `sparsity_alpha`: Specific alpha for L1 sparsity penalty on stoich matrix
- `l2_alpha`: Specific alpha for L2 weight regularization

**Returns:**
- Penalties instance configured for NeuralRDE models


### `Penalty` <sup><a href="https://github.com/JR-1991/Catalax/blob/master/catalax/neural/penalties/penalties.py#L289" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>


A single penalty function with associated parameters.

This class wraps a penalty function along with its strength parameter (alpha)
and any additional keyword arguments needed for the function. It provides
validation to ensure the penalty function has the correct signature.


**Methods:**

#### `validate_function_signature` <sup><a href="https://github.com/JR-1991/Catalax/blob/master/catalax/neural/penalties/penalties.py#L327" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
validate_function_signature(cls, v: Callable) -> Callable
```

Validate that the penalty function has the required signature.

Ensures the penalty function can accept the required 'model' and 'alpha'
parameters that are needed for proper penalty computation.

**Args:**
- `v`: The penalty function to validate

**Returns:**
- The validated function

**Raises:**
- `ValueError`: If the function doesn't have required 'model' and 'alpha' parameters


#### `has_model_alpha_signature` <sup><a href="https://github.com/JR-1991/Catalax/blob/master/catalax/neural/penalties/penalties.py#L349" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
has_model_alpha_signature(func: Callable) -> bool
```

Check if a function has 'model' and 'alpha' parameters.

This is a simple check that looks for the presence of both required
parameter names in the function signature.

**Args:**
- `func`: Function to check

**Returns:**
- True if function has both 'model' and 'alpha' parameters


#### `validate_penalty_signature` <sup><a href="https://github.com/JR-1991/Catalax/blob/master/catalax/neural/penalties/penalties.py#L367" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
validate_penalty_signature(func: Callable) -> bool
```

Validate that a function has the required signature for penalties.

This method performs a more robust validation by attempting to bind
the required parameters to the function signature, which handles
cases with *args, **kwargs, and other parameter variations.

**Args:**
- `func`: Function to validate

**Returns:**
- True if function can accept 'model' and 'alpha' parameters

