Skip to content

New instructions (README and Webpage) #50

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
pilarcoordinates wants to merge 3 commits into
base: public
Choose a base branch
from
Open

New instructions (README and Webpage) #50

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
0aca754
New instructions (README and webpage)
Feb 3, 2026
95f4e65
Reworked instructions
Feb 10, 2026
6c95cc4
Merge branch 'public' into instructions
pilarcoordinates Feb 10, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
140 changes: 31 additions & 109 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,132 +1,54 @@
# IFDIFF - A Matlab Toolkit for ODEs with State˗Dependent Switches
# IFDIFF - A MATLAB Toolkit for ODEs with State˗Dependent Switches
[![Open in MATLAB Online](https://www.mathworks.com/images/responsive/global/open-in-matlab-online.svg)](https://matlab.mathworks.com/open/github/v1?repo=andreassommer/ifdiff&file=toolbox/doc/GettingStarted.mlx)

The software package IFDIFF deals with the solution and algorithmic generation of sensitivities in
ordinary differential equations with implicit (state-dependent) non-differentiabilites ("switches")
in the right-hand side that is given as Matlab program code with non-differentiable operators such as
`min`, `max`, `abs`, `sign`, as well as `if`-branching. IFDIFF automatically generates only necessary
switching functions, outputs them as Matlab code, and detects switching points accurately up to
machine precision.
The software package IFDIFF comprises:
- **Automatic detection and processing** of state-dependent switching events in ODE IVPs
- **Automatic generation** of only the necessary **switching functions** (exported as MATLAB code)
- Accurate switching point detection up to machine precision
- Detection and handling of **Filippov sliding mode**
- ODEs with state-jumps and model switches
- **Sensitivity generation** for switched ODEs, ODEs with state-jumps and Filippov ODEs

Sensitivities can be generated w.r.t. the initial values and w.r.t. a given parameter set.

See the [IFDIFF page](https://andreassommer.github.io/ifdiff/) for a mathematical introduction with example.
For a mathematical introduction and illustrative examples, see the
[IFDIFF project page](https://andreassommer.github.io/ifdiff/).

The file [Readme_Example.m](./toolbox/examples/Readme_Example.m) contains a self-explaining Matlab script similar to the
contents below.
A compact, self-explanatory MATLAB example is provided in this file. ([`Readme_Example.m`](./toolbox/examples/Readme_Example.m))

</br>



# First Run Prerequisites

Before using IFDIFF, it is mandatory to run the `make_mtreeplus` script once.
After starting Matlab, change to the IFDIFF directory and type `make_mtreeplus`.
This scripts generates a modified copy of Matlab's own parser class `mtree`, on which IFDIFF heavily relies.

It is advisable to initialize the paths needed for IFDIFF by invoking
`initIFDIFF();` once on every new matlab session.

</br>


# Installation

# Usage

Make sure that you've followed the [First Run Prerequisites](#first-run-prerequisites).

The following commands exemplarily show the usage on the canonical example.

## 1. Preprocessing of Right Hand Side

The preprocessing analyses and transforms the right hand side function `canonicalExampleRHS.m`.
Preprocessing generates the `datahandle`, the central structure for switching detection and handling.
We set ODE solver and its options as usual. If not set, default values are used.

```matlab
initIFDIFF(); % Initialise the paths for ifdiff -- needed only once per Matlab session
integrator = @ode45;
odeoptions = odeset('AbsTol', 1e-14, 'RelTol', 1e-12);
datahandle = prepareDatahandleForIntegration('canonicalExampleRHS', 'integrator', integrator, 'options', odeoptions);
```
There are two ways to install IFDIFF.

## Installation Method (Recommended)

## 2. Integration (Forward Solution)
1. Download the current release file `IFDIFF_Toolbox.mltbx`.
2. Open MATLAB and navigate to the directory containing the file.
3. Right-click the file and select **Open**.
Copy link
Collaborator

@Schlevidon Schlevidon Feb 24, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The word "Open" should be replaced with "Install".

4. For a detailed introduction, open `GettingStarted.mlx`, which is included with the toolbox.

Define initial values, parameter values, and integration horizon, and call `solveODE` to start the integration.
`solveODE` returns a Matlab `sol` structure, that can be evalated using `deval`.
It is an augmented version of the solution structures returned by Matlab's very own integrator suite
(see https://de.mathworks.com/help/matlab/ref/deval.html#bu7iw_j-sol)
Note: You can also open the Getting Started guide directly in
[MATLAB Online](https://matlab.mathworks.com/open/github/v1?repo=andreassommer/ifdiff&file=toolbox/doc/GettingStarted.mlx) and then continue with the [First Run Prerequisites](#first-run-prerequisites).

```matlab
tspan = [0 20];
initialvalues = [1;0];
parameters = 5.437;
sol = solveODE(datahandle, tspan, initialvalues, parameters);
T = 0:0.1:20;
X = deval(sol,T);
plot(T,X)
```
## Installation Method (Alternative)

1. Navigate to a location of your choice on your PC (e.g. Desktop).
2. Clone the repository `git clone https://github.com/andreassommer/ifdiff.git`
3. Open MATLAB and navigate to the cloned `ifdiff` directory.

## 3. Sensitivity Generation

The sensitivity generation currently supports 1st order forward sensitivities w.r.t. initial state and parameters.
It is possible to generate sensitivities using external numerical differentiation (flags `END_full`, `END_piecewise`)
or using the variational differential equations (flag `VDE`).

Usually, method `VDE` delivers vest results in terms of accuracy, as it calculates error-controlled sensitivities.
It uses the variational differential equations on each interval and performes updates at the switching points to
ensure accurate sensitivities at the precalculated forward solution. However, the occuring augmented differential
system might be large size and thus slow to compute.
Required state derivatives of the right hand side are approximated using automated finite differencing.

The method `END_piecewise` computes the interval sensitivities using external numerical differentiation (finite differencing)
and connects these using the same updates as used in the VDE method. This requires multiple evaluations of interval solutions,
but might be faster on larger systems.

When using `END_full`, external numerical differention is used on multiple full horizon solutions. The individual
trajectories are calculated with switching point detection. Thus, no updates between switches are required.
In general, this approach is less accurate and slower than `END_piecewise`, but might be the a good choice
for highly instable ODEs.

1. Choose step sizes for finite differencing (also used in method `VDE` for generating state derivatives of the rhs).

```matlab
dim_y = size(sol.y,1); // state dimension
dim_p = length(parameters); // number of parameters
FDstep = generateFDstep(dim_y,dim_p);
```

The `generateDFstep` function accepts several options influencing e.g. step length.
See the documentation or the file for more information


2. Build the sensitivity function. In this example, the `END_piecewise` method is chosen.

```matlab
sensitivity_function = generateSensitivityFunction(datahandle, sol, FDstep, 'method', 'END_piecewise');
```
</br>

The following table lists several name-value pairs that can be used to configure `generateSensitivityFunction`
# Usage

| Parameters | Possible values | Defaults |
| ----------------------- | ----------------------------------------------------------------------------------- | ------------------------------------- |
| calcGy | true/false - flag indicating to calculate state sensitivities | true |
| calcGp | true/false - flag indicating to calculate parameter sensitivities | true |
| Gmatrices_intermediate | true/false - flag indicating to store update matrics | false |
| save_intermediates | true/false - flag indicating to store intermediate calculations | true |
| integrator | Function handle for ODE solver in Matlab (e.g. ode45) | Integrator used by ifdiff |
| integrator_options | Options struct generated for ODE solver | Integrator options used by ifdiff |
| method | String with VDE/END_piecewise/END_full | VDE |
| directions_y | Matrix containing directions for directional derivatives w.r.t initial values. | Identity matrix with dimension n_y |
| directions_p | Matrix containing directions for directional derivatives w.r.t parameters. | Identity matrix with dimension n_p |
Onnce every new MATLAB session run
Copy link
Collaborator

@Schlevidon Schlevidon Feb 24, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Typo: "Onnce" -> "Once"


`initIFDIFF();`

3. Evaluate the sensitivity function at specific times.
to initialize the required paths. Then IFDIFF is ready to use.

```matlab
t = 0:0.1:20;
sensitivities = sensitivity_function(t);
```
The first time the command is executed, a copy of MATLAB's internal parser class `mtree` is created on which IFDIFF heavily relies.
For a step-by-step usage example and background explanation, see the [IFDIFF project page](https://andreassommer.github.io/ifdiff/).
Loading