Thanks to visit codestin.com
Credit goes to github.com

Skip to content

Commit 70a050d

Browse files
KiguliKiguli
committed
docs: add Sphinx documentation site
Furo-themed docs with installation (Docker/local/server), usage guide, computation model theory (CLF/CBC for all 4 system classes), and benchmark cases reference.
1 parent 81ca418 commit 70a050d

12 files changed

Lines changed: 1442 additions & 0 deletions

File tree

‎docs/Makefile‎

Lines changed: 19 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,19 @@
1+
# Minimal makefile for Sphinx documentation
2+
3+
# You can set these variables from the command line, and also
4+
# from the environment for the first two.
5+
SPHINXOPTS ?=
6+
SPHINXBUILD ?= sphinx-build
7+
SOURCEDIR = .
8+
BUILDDIR = _build
9+
10+
# Put it first so that "make" without argument is like "make help".
11+
help:
12+
@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
13+
14+
.PHONY: help Makefile
15+
16+
# Catch-all target: route all unknown targets to Sphinx using the new
17+
# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS).
18+
%: Makefile
19+
@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

‎docs/_static/custom.css‎

Lines changed: 111 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,111 @@
1+
/* Custom styles for TRUST documentation */
2+
3+
/* === Code Blocks === */
4+
pre {
5+
font-size: 0.85em;
6+
border-left: 3px solid var(--color-brand-primary);
7+
border-radius: 0 4px 4px 0;
8+
}
9+
10+
code.literal {
11+
padding: 1px 4px;
12+
}
13+
14+
/* === Section headings === */
15+
.content h2 {
16+
padding-left: 0.6rem;
17+
border-left: 3px solid var(--color-brand-primary);
18+
}
19+
20+
/* === Card styling === */
21+
.sd-card {
22+
transition: box-shadow 0.2s ease, transform 0.15s ease;
23+
border-top: 2px solid transparent;
24+
}
25+
26+
.sd-card:hover {
27+
box-shadow: 0 4px 12px rgba(0, 0, 0, 0.12);
28+
transform: translateY(-2px);
29+
border-top-color: var(--color-brand-primary);
30+
}
31+
32+
/* === Tables === */
33+
table.docutils td:last-child {
34+
font-weight: 600;
35+
color: var(--color-brand-primary);
36+
}
37+
38+
table.docutils tbody tr:nth-child(even) {
39+
background-color: var(--color-background-secondary);
40+
}
41+
42+
table.docutils thead th {
43+
background-color: var(--color-brand-primary);
44+
color: white;
45+
font-weight: 600;
46+
}
47+
48+
/* === Admonition accents === */
49+
.admonition.note {
50+
border-left-color: var(--color-brand-primary);
51+
}
52+
53+
.admonition.warning {
54+
border-left-color: #ff9800;
55+
}
56+
57+
.admonition.tip {
58+
border-left-color: #4caf50;
59+
}
60+
61+
/* === Horizontal rules === */
62+
hr {
63+
margin: 2.5rem 0;
64+
border: none;
65+
border-top: 2px solid var(--color-brand-primary);
66+
opacity: 0.2;
67+
}
68+
69+
/* === Hero accent bar === */
70+
.page-content > .content > section:first-child > p:first-of-type {
71+
font-size: 1.15em;
72+
color: var(--color-foreground-secondary);
73+
}
74+
75+
/* === Badge polish === */
76+
.sd-badge {
77+
font-weight: 600;
78+
letter-spacing: 0.02em;
79+
}
80+
81+
/* === Scrollbar === */
82+
::-webkit-scrollbar {
83+
width: 8px;
84+
}
85+
86+
::-webkit-scrollbar-thumb {
87+
background: var(--color-brand-primary);
88+
border-radius: 4px;
89+
opacity: 0.5;
90+
}
91+
92+
::-webkit-scrollbar-thumb:hover {
93+
opacity: 0.8;
94+
}
95+
96+
::-webkit-scrollbar-track {
97+
background: var(--color-background-secondary);
98+
}
99+
100+
/* === Dark mode adjustments === */
101+
body[data-theme="dark"] table.docutils td:last-child {
102+
color: var(--color-brand-content);
103+
}
104+
105+
body[data-theme="dark"] table.docutils thead th {
106+
background-color: #0D47A1;
107+
}
108+
109+
body[data-theme="dark"] .sd-card:hover {
110+
border-top-color: var(--color-brand-content);
111+
}

‎docs/cases/index.rst‎

Lines changed: 188 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,188 @@
1+
Benchmark Cases
2+
===============
3+
4+
TRUST includes 17 benchmark case studies with pre-configured trajectory data.
5+
Each case is stored in ``storage/cases/`` and can be used to verify the tool
6+
or as a starting point for new analyses.
7+
8+
Case Overview
9+
-------------
10+
11+
.. list-table::
12+
:header-rows: 1
13+
:widths: 35 10 10 10 15
14+
15+
* - Case
16+
- Time
17+
- Model
18+
- Dim
19+
- Specifications
20+
* - DC Motor
21+
- ct
22+
- LS
23+
- 2
24+
- Stability, Safety
25+
* - Room Temperature System 1
26+
- ct
27+
- LS
28+
- 2
29+
- Stability, Safety
30+
* - Two-Tank System
31+
- ct
32+
- LS
33+
- 2
34+
- Stability, Safety
35+
* - High-Order System (4D)
36+
- ct
37+
- LS
38+
- 4
39+
- Stability, Safety
40+
* - High-Order System (6D)
41+
- ct
42+
- LS
43+
- 6
44+
- Stability, Safety
45+
* - High-Order System (8D)
46+
- ct
47+
- LS
48+
- 8
49+
- Stability, Safety
50+
* - Lotka-Volterra Predator-Prey
51+
- ct
52+
- NPS
53+
- 2
54+
- Stability, Safety
55+
* - Van der Pol Oscillator
56+
- ct
57+
- NPS
58+
- 2
59+
- Stability, Safety
60+
* - DC Motor
61+
- dt
62+
- LS
63+
- 2
64+
- Stability, Safety
65+
* - Room Temperature System 1
66+
- dt
67+
- LS
68+
- 2
69+
- Stability, Safety
70+
* - Room Temperature System 2
71+
- dt
72+
- LS
73+
- 3
74+
- Stability, Safety
75+
* - Two-Tank System
76+
- dt
77+
- LS
78+
- 2
79+
- Stability, Safety
80+
* - High-Order System (4D)
81+
- dt
82+
- LS
83+
- 4
84+
- Stability, Safety
85+
* - High-Order System (6D)
86+
- dt
87+
- LS
88+
- 6
89+
- Stability, Safety
90+
* - High-Order System (8D)
91+
- dt
92+
- LS
93+
- 8
94+
- Stability, Safety
95+
* - Lotka-Volterra Predator-Prey
96+
- dt
97+
- NPS
98+
- 2
99+
- Stability, Safety
100+
* - Lorenz Attractor
101+
- dt
102+
- NPS
103+
- 3
104+
- Stability, Safety
105+
106+
----
107+
108+
File Format
109+
-----------
110+
111+
Each case directory contains up to six CSV data files and one supplementary
112+
input file:
113+
114+
.. list-table::
115+
:header-rows: 1
116+
:widths: 30 70
117+
118+
* - File
119+
- Description
120+
* - ``stability_X0T.csv``
121+
- :math:`X_0` matrix for stability analysis
122+
* - ``stability_X1T.csv``
123+
- :math:`X_1` matrix for stability analysis
124+
* - ``stability_U0T.csv``
125+
- :math:`U_0` matrix for stability analysis
126+
* - ``safety_X0T.csv``
127+
- :math:`X_0` matrix for safety analysis
128+
* - ``safety_X1T.csv``
129+
- :math:`X_1` matrix for safety analysis
130+
* - ``safety_U0T.csv``
131+
- :math:`U_0` matrix for safety analysis
132+
* - ``supplementary_inputs.txt``
133+
- Monomials, :math:`\Theta(x)`, state space, initial/unsafe sets
134+
135+
CSV files contain comma-separated floating-point values, one row per state
136+
dimension.
137+
138+
Supplementary Inputs
139+
~~~~~~~~~~~~~~~~~~~~
140+
141+
The ``supplementary_inputs.txt`` file lists additional inputs required for each
142+
specification, organised under ``-- Safety --`` and ``-- Stability --`` headers.
143+
144+
Example (from ``ctNPS_lotka_volterra_predator_prey_model``)::
145+
146+
-- Safety --
147+
Monomials: x1; x2; x1*x2
148+
State Space:
149+
x1: 0, 6
150+
x2: 0, 6
151+
Initial State:
152+
x1: 1.5, 2
153+
x2: 0.75, 1
154+
Unsafe State:
155+
x1: 4, 5
156+
x2: 3, 4
157+
158+
----
159+
160+
Using a Benchmark Case
161+
-----------------------
162+
163+
1. Select the appropriate **Class** and **Model** matching the case prefix
164+
(e.g., ``ctNPS`` = Continuous-Time, Non-Linear Polynomial)
165+
2. Upload the corresponding CSV files (``X0T.csv``, ``X1T.csv``, ``U0T.csv``)
166+
for your chosen specification (stability or safety)
167+
3. Enter the supplementary inputs from ``supplementary_inputs.txt``:
168+
monomials, :math:`\Theta(x)` (or use Autofill), and region bounds
169+
4. Click **Submit** to run the computation
170+
171+
----
172+
173+
Example Results
174+
---------------
175+
176+
The figures below illustrate safety results for selected benchmark cases. In
177+
each plot:
178+
179+
- Blue region: initial set
180+
- Red region(s): unsafe set(s)
181+
- Dashed blue line: :math:`\lambda` level set
182+
- Dashed red line: :math:`\gamma` level set
183+
- Black curves: closed-loop trajectories
184+
185+
.. note::
186+
187+
The benchmark figures were rendered using external MATLAB scripts not
188+
included in the repository.

0 commit comments

Comments
 (0)