forked from libsbmlsim/libsbmlsim
-
Notifications
You must be signed in to change notification settings - Fork 0
/
Copy pathREADME.txt
349 lines (311 loc) · 15.4 KB
/
README.txt
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
LibSBMLSim: The library for simulating SBML models
LibSBMLSim development team
http://fun.bio.keio.ac.jp/software/libsbmlsim/
mailto:[email protected]
-- Last modified: Tue, 05 Dec 2017 00:12:42 +0900
* Overview
LibSBMLSim is a library for simulating an SBML model which contains
Ordinary Differential Equations (ODEs). LibSBMLSim provides simple
command-line tool and several APIs to load an SBML model, perform
numerical integration (simulate) and export its results.
Both explicit and implicit methods are supported on libSBMLSim.
LibSBMLSim is confirmed to pass all SBML Level-2 Version 4 and Level-3
Version 1 core test cases (sbml-test-cases-2014-10-22.zip, available from
http://sourceforge.net/projects/sbml/files/test-suite/3.1.1/).
The libSBMLSim code is portable. It is written in C programming language
(ANSI C89) and it does not depend on other third-party libraries
except libSBML(*1).
The library should build and work without serious troubles on Unix
based operating systems (Linux, MacOSX and FreeBSD) and on Windows
(with Visual C++).
LibSBMLSim also provides several language bindings like Java, Python,
C# and Ruby. Perl binding is already included in the source tree, but
is not able to create through the single build process (see the
description below).
(*1 libSBML: http://sbml.org/Software/libSBML)
LibSBMLSim can be used to create your own SBML capable simulator,
plug-in, web based application and web services. The API is quite
straight forward. You can run a simulation and generate a result
file in Comma Separated Values (CSV) with a few lines of codes.
=== Python ============================
from libsbmlsim import *
r = simulateSBMLFromFile('sbml.xml', 20.0, 0.1, 10, 0, MTHD_RUNGE_KUTTA, 0)
write_csv(r, 'result.csv')
=======================================
Please see the 'API.txt' and 'examples' directory for further information
on libSBMLSim APIs.
* Installation
- Dependencies
LibSBMLSim requires libSBML to be installed on your system.
Please follow the instruction on (*1) and install libSBML.
LibSBML and its dependent libraries will be automatically installed
with Windows version of libSBMLSim Installer.
- Binary install of libSBMLSim
We have provided installer for Windows, MacOSX and Linux from libSBMLSim-1.3.
= Windows (both 32bit and 64bit)
Download libSBMLSim Installer for Windows (libsbmlsim-1.4.0-win{32,64}.exe)
and double-click the installer. It will ask few questions, and will
install libSBMLSim to
"C:\Program Files\libsbmlsim-1.3" (64bit)
"C:\Program Files (x86)\libsbmlsim-1.3" (32bit)
by default.
= MacOSX (64bit)
Download libSBMLSim Installer archive for MacOSX
(libsbmlsim-1.4.0-macosx-mavericks-x64.dmg) and double-click the .dmg file.
You will see an installer (libsbmlsim-1.4.0-macosx-mavericks-x64.pkg) in a
Finder window. Double-click the installer and follow the instructions.
It will install libSBMLSim to /usr/local .
= Linux (64bit)
Download libsbmlsim-1.4.0_amd64.deb, and install with the following
command in your terminal.
$ sudo dpkg -i libsbmlsim-1.4.0_amd64.deb
It will install libSBMLSim to /usr .
* Compile and Install from source code.
- Required software packages to compile libSBMLSim
CMake(*2) is required to compile libSBMLSim. Please download
and install CMake-2.8.12 or above from (*2) before building libSBMLSim.
If you want to use language bindings of libSBMLSim, please
download and install SWIG-2.0.4 or above from (*3).
(Note: If you installed SWIG from MacPorts, please install
swig-java, swig-python, swig-ruby, swig-csharp which are required
to compile language bindings for libSBMLSim.)
(*2 CMake: http://cmake.org/)
(*3 SWIG: http://swig.org/)
- How to build libSBMLSim
1. Extract the archive file
% tar xvzf libsbmlsim-1.4.0.tar.gz (for tar ball)
% unzip libsbmlsim-1.4.0.zip (for zip archive)
2. Compile
% mkdir libsbmlsim-1.4.0/build
% cd libsbmlsim-1.4.0/build
% cmake ..
% ccmake .
CUI from cmake will be launched. Please confirm that
cmake have automatically detected the installed location of
libSBML. You can check the installed location from the
following values:
(ex. on MacOSX)
LIBSBML_INCLUDE_DIR /usr/local/include
LIBSBML_LIBRARY /usr/local/lib/libsbml.dylib
If libSBML is not detected automatically, you can manually
specify the installed location through this menu.
If you want to build language bindings, please turn on the
corresponding compile option.
WITH_JAVA ... build with Java bindings
WITH_PYTHON ... build with Python bindings
WITH_RUBY ... build with Ruby bindings
WITH_CSHARP ... build with C# bindings
Once you press [c] key, cmake will run the configure procedure
and tries to detect SWIG, Java, Python, C# and Ruby (depending on
which language bindings you enabled). Hit [c] several times to
complete configuration. Once the configuration is done,
press [g] key and cmake will generate Makefile.
After Makefile is generated, just run
% make
% sudo make install
which will compile and install the library, command-line tool
and header files on your system. Default prefix (install
directory) is
- /usr/local ... on Linux and MacOSX
- C:\Program Files\libsbmlsim ... on Windows
(Note: You can change the prefix from the UI of ccmake)
Also, you can create binary installer by following command.
% make package
- Installed files
Following files are installed on your system.
= Unix based systems (Linux, MacOSX, etc.)
$prefix/bin/simulateSBML ... SBML simulator
$prefix/lib/libsbmlsim-static.a ... Static library
/libsbmlsim.dylib ... Dynamic library (on MacOSX)
/libsbmlsim.so ... Dynamic library (on Linux)
$prefix/include/libsbmlsim ... Header files
$prefix/share/libsbmlsim/ ... Sample files (SBML, results)
/c ... Sample C code
/cpp ... Sample C++ code
/csharp ... Sample C# code and language bindings
/java ... Sample Java code and language bingings
/python ... Sample Python code and language bingings
/ruby ... Sample Ruby code and language bingings
= Windows
$prefix\bin\simulateSBML.exe ... SBML simulator
$prefix\bin\sbmlsim.dll ... Dynamic library
$prefix\lib\sbmlsim-static.lib ... Static library
\sbmlsim.lib ... Lib file for dynamic library
$prefix\include\libsbmlsim ... Header files
$prefix\share\libsbmlsim\ ... Sample files (SBML, results)
\c ... Sample C code
\cpp ... Sample C++ code
\csharp ... Sample C# code and language bindings
\java ... Sample Java code and language bingings
\python ... Sample Python code and language bingings
(Note: Ruby binding is not supported on Windows)
* Usage
- simulateSBML
simulateSBML is a simple SBML simulator which accept SBML file as
an input, and then output "out.csv" as a result.
Usage: simulateSBML [option] filename(SBML)
-t # : specify simulation time (ex. -t 100 )
-s # : specify simulation step (ex. -s 100 )
-d # : specify simulation delta (ex. -d 0.01 [default:1/4096])
dt is calculated in (delta)*(time)/(step)
-a : print Species Value in Amount
-o file : specify result file (ex. -o output.csv )
-l : use lazy method for integration
-n : do not use lazy method
-v : prints version info
-A # : specify absolute tolerance for variable stepsize (ex. -A 1e-03 [default:1e-09])
-R # : specify relative tolerance for variable stepsize (ex. -R 0.1 [default:1e-06])
-M # : specify the max change rate of stepsize (ex. -M 1.5 [default:2.0])
-B : use bifurcation analysis
-m # : specify numerical integration algorithm (ex. -m 3 )
1: Runge-Kutta
2: AM1 & BD1 (implicit Euler)
3: AM2 (Crank Nicolson)
4: AM3
5: AM4
6: BD2
7: BD3
8: BD4
9: AB1 (explicit Euler)
10: AB2
11: AB3
12: AB4
13: Runge-Kutta-Fehlberg
14: Cash-Karp
(AM: Adams-Moulton, BD: Backward-Difference, AB: Adams-Bashforth.
Number after synonim specifies the order of integration.
For example, AM2 is "2nd order Adams-Moulton" method)
- Scripts for "SBML test cases"
LibSBMLSim provides scripts to easily run SBML test cases (*4)
and compare the results with it. Generated results are compatible
with Online SBML Test Suite (*4), so you can run all tests with
this scripts and upload the results to Online SBML Test Suite.
The scripts are not installed, you will find them under "testcases"
directory in the extracted source directory (libsbmlsim/testcases/).
libsbmlsim/testcases/simulateSBML ... SBML simulator
/runall.sh ... Script which will run all tests
/compare.pl
/genresult.pl
/wrapper.sh ... Wrapper script for SBML Test Runner
"simulateSBML" simulates SBML model and generates simulation result
as a CSV file, which is identical with the one installed under
$prefix/bin . "runall.sh" will call simulateSBML for all SBML test
cases, and compare the result with the one from SBML test cases.
"compare.pl" and "genresult.pl" are scripts which will support some
functions called from runall.sh.
The SBML test cases are not included in this distribution, so please
download them from (*5). After downloading sbml-test-cases-X.Y.Z.zip,
unzip the archive and move (or copy) "cases/" directory to
libsbmlsim/testcases directory. The directory structure will be:
libsbmlsim/testcases/simulateSBML ... SBML simulator
/runall.sh ... Script which will run all tests
/compare.pl
/genresult.pl
/wrapper.sh ... Wrapper script for SBML Test Runner
/cases/semantic/00001 ... Test case 1
/cases/semantic/00002 ... Test case 2
/cases/semantic/00003 ... Test case 3
/cases/semantic/...
Following command will test all 1,125 tests and print out the
results, whether the simulation result matches with the result
with the one from SBML test cases.
% ./runall.sh
00001: 5 : 50 : [S1,S2] : [S1,S2] : [S1,S2] : 1e-16 : 1e-10
print amount
time:5 step:50 dt:0.100000
Model 00001 ... [OK]
00002: 5.0 : 50 : [S1,S2] : [S1,S2] : [S1,S2] : 1e-16 : 1e-10
print amount
time:5 step:50 dt:0.100000
Model 00002 ... [OK]
00003: 5.0 : 50 : [S1,S2] : [S1,S2] : [S1,S2] : 1e-16 : 1e-10
print amount
time:5 step:50 dt:0.100000
Model 00003 ... [OK]
If the simulation result doesn't match with the one from
SBML test cases, then the result will be marked as "[NG]".
(*4 Online SBML Test Suite: http://sbml.org/Facilities/Online_SBML_Test_Suite)
(*5 SBML-test-cases-3.1.1 : http://sourceforge.net/projects/sbml/files/test-suite/3.1.1)
Note: Because 00983/00983-sbml-l3v1.xml is an invalid SBML document in
SBML-test-cases-3.1.1, libSBMLSim will not run a simulation for this
model. We confirmed that libSBMLSim will pass the test of
00983/00983-sbml-l3v1.xml from SBML-test-cases-3.2.0.
- Wrapper script for "SBML Test Runner"
As from v1.3.0, libSBMLSim provides a wrapper script, "wrapper.sh" for
SBML Test Runner (*6). By using wrapper.sh, uesrs can easily run all
SBML test cases on libSBMLSim through a Graphical User Interface of
SBML Test Runner.
To run libSBMLSim through SBML Test Runner, you have to create a
configuration for libSBMLSim from [Preference] menu on SBML Test Runner.
In the "Preferences" dialog, please assign a name to the configuration
(ex. libsbmlsim), and fill out the text fields as follows:
= Name: libsbmlsim
= Wrapper path: $some_where/libsbmlsim/testcases/wrapper.sh
= Output directory: $some_where/output
= Unsupported tags: comp, fbc
= Arguments to wrapper: %d %n %o %l %v
you can turn on "Wrapper can handle any SBML Level/Version" and
"Wrapper can be run in parallel".
After filling out the text fields, save the configuration and then
selecting [Test] -> [Run All Supported Tests] from the menu, SBML
Test Runner will run all test cases. You can browse its results on
its GUI.
(*6 SBML Test Runner: https://github.com/sbmlteam/sbml-test-suite)
* LibSBMLSim API and its language bindings
Example usage of libSBMLSim APIs are as follows.
Please see the 'API.txt' and 'examples' directory for further information
on libSBMLSim APIs.
- C, C++ API
=== C code ============================
#include "libsbmlsim/libsbmlsim.h"
...
/*
* Simulate sbml.xml to time=20 with dt=0.1, print_interval=10
* by 4th-order Runge-Kutta Method.
*/
myResult *r = simulateSBMLFromFile("sbml.xml", 20, 0.1, 10, 0, MTHD_RUNGE_KUTTA, 0);
/*
* Export simulation result as CSV file
*/
write_csv(r, "result.csv");
/*
* Free Result object
*/
free_myResult(r);
=====================================
- Java, Python, Ruby bindings
LibSBMLSim API is also provided for several language bindings.
=== Python ============================
from libsbmlsim import *
r = simulateSBMLFromFile('sbml.xml', 20.0, 0.1, 10, 0, MTHD_RUNGE_KUTTA, 0)
write_csv(r, 'result.csv')
=======================================
=== Java ==============================
import jp.ac.keio.bio.fun.libsbmlsim.*;
...
System.loadLibrary("sbmlsimj");
myResult r = libsbmlsim.simulateSBMLFromFile("sbml.xml", 20.0, 0.1, 10, 0, libsbmlsim.MTHD_RUNGE_KUTTA, 0);
libsbmlsim.write_csv(r, "result.csv");
=======================================
=== Ruby ==============================
require 'libsbmlsim'
r = Libsbmlsim::simulateSBMLFromFile('sbml.xml', 20.0, 0.1, 10, 0, Libsbmlsim::MTHD_RUNGE_KUTTA, 0)
Libsbmlsim::write_csv(r, 'result.csv')
=======================================
=== C# ================================
using System;
public class Test
{
static void Main()
{
myResult result = libsbmlsim.simulateSBMLFromFile("sbml.xml", 20.0, 0.1, 10, 0, libsbmlsim.MTHD_RUNGE_KUTTA, 0);
libsbmlsim.write_csv(result, "test.csv");
}
}
=======================================
Please see the 'API.txt' and 'examples' directory for further information.
The 'examples' directory contains sample code for test application
in several programming languages (C, C++, Java, Python, Ruby, C# and Perl).
Have fun!
--
LibSBMLSim development team <[email protected]>