You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
This guide provides instructions for submitting and formatting new code in `OTP`.
3
+
This guide provides instructions for submitting and formatting new code in OTP.
4
4
5
5
## Submitting Changes
6
6
7
-
Changes to `OTP` should be proposed as a pull request and undergo a review process before being merged. New code must be free of warnings and errors and adhere to the style guidelines (see also [The style guidelines](## Style guidelines)).
7
+
Changes to OTP should be proposed as a pull request and undergo a review process before being merged. New code must be free of warnings and errors and adhere to the [style guidelines](#style-guidelines).
8
8
9
9
## Creating a Problem
10
10
11
-
Each problem defines a package under `+otp` that contains all files used by the problem. To add a new test problem follow these steps:
11
+
Each problem defines a package under `+otp` that contains all files used by the problem. When creating a new problem we recommend duplicating an existing problem package, e.g., [Lorenz63](https://github.com/ComputationalScienceLaboratory/ODE-Test-Problems/blob/master/toolbox/+otp/+lorenz63) or [Brusselator](https://github.com/ComputationalScienceLaboratory/ODE-Test-Problems/blob/master/toolbox/+otp/+brusselator), then renaming and editing the contents as needed.
12
12
13
-
1. Check out the latest version of `OTP`:
13
+
To add a new test problem from scratch follow these steps:
2. Create a new folder in the `src/+opt/` directory. Follow the same naming conventions as the existing problems. Start the name with `+` to maintain the structure of the Matlab/Octave package. Also create a subfolder named `+presets` in the new problem folder:
22
+
2. Create a new folder in the `toolbox/+opt/` directory with a name that starts with `+` to indicate it is a package. Also create a subfolder named `+presets` in the new problem folder:
21
23
22
24
```bash
23
-
mkdir src/+opt/+newtest
24
-
mkdir src/+opt/+newtest/+presets
25
-
cd src/+opt/+newtest/
25
+
mkdir toolbox/+opt/+example
26
+
cd toolbox/+opt/+example
27
+
mkdir +presets
26
28
```
27
29
28
-
3. The minimal set of files needed inside the problem folder to set up a new test problem are:
29
-
* The right-hand-side function named as `f.m`
30
-
* The problem class to initialize problem objects and its methods and properties
31
-
* The parameters class defines the parameters of the new problem
32
-
* A `Canonical.m` preset inside the `+presets` subfolder to set the initial condition and parameters in your case
33
-
34
-
```bash
35
-
touch f.m
36
-
touch NewTestProblem.m
37
-
touch NewTestParameters.m
38
-
touch +presets/Canonical.m
39
-
```
30
+
3. The minimal set of files needed inside the problem folder to set up a new example problem are:
31
+
* The right-hand side (RHS) function named as `f.m`
32
+
* The problem class to specify properties, override plotting and solver options, and convert parameters into arguments for RHS functions
33
+
* The parameters class
34
+
* A `Canonical.m` preset inside the `+presets` subfolder to set standard initial condition and parameters.
The right-hand-side structure provides various derivatives of the problem. They are implemented in separate function files. The right-hand-side function `f.m`, which is the time-derivative of the state `y` is defined as a function with at least two arguments `f(t,y)`. If the right-hand-side function needs other parameters they can also be passed to this function:
40
+
### The RHS Function
44
41
45
-
```Matlab
42
+
The RHS function `f.m`, which is the time-derivative of the state `y`, is defined as a function with at least two arguments. If parameters are needed, they can be added as arguments.
46
43
47
-
function dy = f(t, y, Param1, ...)
48
-
dy = ...
44
+
```matlab
45
+
function dy = f(t, y, param1, ...)
46
+
dy = ...
49
47
end
50
-
51
48
```
52
49
53
-
For more information about this formulation please refer to our [paper](https://github.com/ComputationalScienceLaboratory/ODE-Test-Problems/blob/master/paper/paper.md).
54
-
55
-
## The Problem Class
50
+
Other functions associated with an `otp.RHS` like the Jacobian and mass matrix should be implemented in separate `.m` files with the same function signature as `f.m`.
56
51
57
-
A problem package must contain a class named `<Name>Problem.m` that is a subclass of `otp.Problem`. There are two
58
-
methods that must be implemented: the constructor and `onSettingsChanged`. Optionally, one can override functions such as `internalPlot` and `internalSolve` to provide problem-specific defaults. Partitioned problems can add custom right-hand-side functions
59
-
as class properties with private write access. The property name should start with `RHS`, e.g., `RHSStiff`.
52
+
### The Problem Class
60
53
61
-
The template for a new class of problems called `NewTest` looks like:
54
+
A problem package must contain a class named `<Name>Problem.m` that is a subclass of `otp.Problem`. There are two methods that must be implemented: the constructor and `onSettingsChanged`. Optionally, one can override functions such as `internalPlot` and `internalSolve` to provide problem-specific defaults. Partitioned problems can add custom RHS functions as class properties with private write access. The property name should start with `RHS`, e.g., `RHSStiff`.
62
55
63
-
```Matlab
64
-
65
-
classdef NewTestProblem < otp.Problem
56
+
A basic template for a new class of problems called `Example` looks like
66
57
58
+
```matlab
59
+
classdef ExampleProblem < otp.Problem
67
60
methods
68
-
function obj = NewTestProblem(timeSpan, y0, parameters)
sol = internalSolve@otp.Problem(obj, 'AbsTol', 1e-50, varargin{:});
104
91
end
105
92
end
106
93
end
107
-
108
94
```
109
95
110
-
## The Parameters Class
111
-
112
-
A problem package must also contain a class named `<Name>Parameters.m`. It only needs to provide public properties for each of the problem parameters; no constructor or methods are needed. Note that property validation is currently not supported in Octave. Therefore, we use a custom comment syntax that is parsed by the installer to optionally include validation. The following is an example of a parameter class with property validation:
96
+
### The Parameters Class
113
97
98
+
A problem package must also contain a class named `<Name>Parameters.m` that is a subclass of `otp.Parameters`. It needs to provide public properties for each of the problem parameters and a constructor which forwards arguments to the superclass constructor; no methods are needed. Note that property validation is currently not supported in Octave. Therefore, we use a custom comment syntax that is parsed by the installer to optionally include validation. The following is an example of a parameter class with property validation:
Within a problem package, there should be a subpackage named `+presets`. This contains subclasses of `<Name>Problem`
130
-
that specify the timespan, initial conditions, and parameters. Typically, only the constructor needs to be implemented
131
-
in a preset class.
114
+
### Adding presets
132
115
133
-
In our example, we add the `Canonical.m` preset inside the `+presets` subfolder containing:
116
+
Within a problem package, there should be a subpackage named `+presets`. This contains subclasses of `<Name>Problem` that specify the time span, initial conditions, and parameters. Typically, only the constructor needs to be implemented in a preset class.
134
117
135
-
```Matlab
118
+
In our example, we add a `Canonical.m` preset inside the `+presets` subfolder.
recommend duplicating an existing problem package, then renaming and editing the contents as needed.
158
-
159
-
[This is a minimal example of](https://github.com/ComputationalScienceLaboratory/ODE-Test-Problems/tree/81cf4e473c34fe04d70280d0a78222a4c75fd775/src/%2Botp/%2Bnewtest) the completed test problem started in this tutorial. It implements the trivial ODE $y'(t) = 1, y(0) = 1$ and can be used as a template to implement simple test problems.
160
-
161
-
162
-
An example of a more sophisticated problem with implemented Jacobians is the [Lorenz63 problem](https://github.com/ComputationalScienceLaboratory/ODE-Test-Problems/blob/master/src/+otp/+lorenz63). For an example of split right-hand-side PDE, see [the Brusselator problem](https://github.com/ComputationalScienceLaboratory/ODE-Test-Problems/blob/master/src/+otp/+brusselator).
163
-
164
136
165
137
## Style Guidelines
166
138
167
-
In order for this project to maintain a consistent coding style, the following conventions should be used. These
168
-
standards match those most commonly used in MATLAB's code and documentation.
139
+
In order for this project to maintain a consistent coding style, the following conventions should be used. These standards largely match those most commonly used in MATLAB's code and documentation.
169
140
170
141
### Line Formatting
171
142
@@ -205,8 +176,7 @@ car = struct('make', 'Ford', 'modelYear', 2020);
205
176
206
177
### Packages
207
178
208
-
Package names should be completely lowercase and start with a plus symbol. No capitalization or special character is
209
-
used to distinguish between words.
179
+
Package names should be completely lowercase and start with a plus symbol. No capitalization or special character is used to distinguish between words.
210
180
211
181
```matlab
212
182
% Example
@@ -216,8 +186,7 @@ help otp.utils.PhysicalConstants
216
186
217
187
### Classes
218
188
219
-
Class names and properties should be written in Pascal case. When the name contains an acronym, all letters should be
220
-
capitalized. Methods should be written in camel case.
189
+
Class names and properties should be written in Pascal case. When the name contains an acronym, all letters should be capitalized. Methods should be written in camel case.
0 commit comments