Added reaction probability to Libsmoldyn and Python APIs

CHANGELOG.md

@@ -1,5 +1,9 @@
 ## Changelog
 
+### 2.70 (10/24/22)
+
+- Allowed users to set reaction probability with Libsmoldyn and Python APIs
+
 ### 2.69 (10/17/22)
 
 - Fixed command entry mid-simulation.

CMakeLists.txt

@@ -30,7 +30,7 @@ if(NOT SMOLDYN_VERSION)
         else()
             # minute-ly release.
             string(TIMESTAMP STAMP "%Y%m%d%H%M")
-            set(SMOLDYN_VERSION "2.70.dev${STAMP}")
+            set(SMOLDYN_VERSION "2.71.dev${STAMP}")
         endif()
     endif()
 endif()

docs/Smoldyn/SmoldynCodeDoc.tex

@@ -42,7 +42,7 @@
 \pretolerance=10000
 
 \title{Smoldyn Code Documentation} 
-\subtitle{Version 2.69}
+\subtitle{Version 2.70}
 \date{\copyright October, 2022}
 \author{Steve Andrews}
 \maketitle
@@ -892,6 +892,33 @@ \subsection*{\_\_main\_\_.py}
 This file parses the command line arguments using the argparse standard library and then runs the model using \ttt{smoldyn.load\_model()}. This file includes the Python command-line options, including ``overwrite'', ``quit-at-end'', and ``args''. This code doesn't necessarily run. According to Dilawar, if Smoldyn is started with ``python3 -m smoldyn template.txt'', then this will execute the \_\_main\_\_.py file, with command line arguments passed to it. Here, the Python package is being used as a proxy for the Smoldyn executable.
 
 
+% Python calling sequence
+\section{Python calling sequence}
+
+The Python interface can be better understood by considering what happens when it is called.
+
+Example. The user's Python script includes \ttt{s.addReaction("rxn", subs=[A,B], prds=[C], rate=-1, binding\_radius=0.05, reaction\_probability=0.1)}. This sends control to the \ttt{addReaction} method in smoldyn.py (line 2130). That creates a Python reaction object, which is defined in smoldyn.py line 1272 and instantiated in the \ttt{\_\_init\_\_} method in line 1286. This method adds the reaction to the simulation with \ttt{self.simulation.addReaction}, which connects to a module.cpp line that reads \ttt{.def("addReaction", ...} (line 1129) and then on to the libsmoldyn.cpp function \ttt{smolAddReaction} (line 1775). This line, finally, connects to the Smoldyn core code, by calling \ttt{RxnAddReaction}, which is in smolreact.c.
+
+Control then moves back up the stack to the reaction instantiation in smoldyn.py, where the rate needs to get set next. The instantiation runs the method \ttt{self.setRate}, which is also in smoldyn.py, in line 1396 and reads \ttt{def setRate(self, rate, reaction\_probability=0.0, binding\_radius=0.0):}. This has the line \ttt{self.simulation.setReactionRate}, which connects to module.cpp \ttt{.def("setReactionRate",...}, goes to libsmoldyn.cpp function \ttt{smolSetReactionRate}, and then on to the Smoldyn core with \ttt{RxnSetValue}.
+
+The following table summarizes these connections.
+
+\begin{longtable}[c]{lll}
+File & Line & Code \\
+\hline
+User code & &\ttt{s.addReaction("rxn", subs=[A,B], prds=[C], rate=1)} \\
+smoldyn.py & 2130 & \hspace{0.2cm} \ttt{def addReaction(...)} \\
+smoldyn.py & 1272 & \hspace{0.4cm} \ttt{class Reaction(object): }...\ttt{ def \_\_init\_\_(...)} \\
+module.cpp & 1129 & \hspace{0.6cm} \ttt{.def("addReaction",...)} \\
+libsmoldyn.cpp & 1775 & \hspace{0.8cm} \ttt{enum ErrorCode smolAddReaction(simptr sim,...)} \\
+smolreact.c & 2044 & \hspace{1cm} \ttt{rxnptr RxnAddReaction(simptr sim,...)} \\
+smoldyn.py & 1396 & \hspace{0.6cm} \ttt{def setRate(self, rate,...)} \\
+module.cpp & 1190 & \hspace{0.8cm} \ttt{.def("setReactionRate",...)} \\
+libsmoldyn.cpp & 1887 & \hspace{1cm} \ttt{enum ErrorCode smolSetReactionRate(simptr sim,...)} \\
+smolreact.c & 1721 & \hspace{1.2cm} \ttt{int RxnSetValue(simptr sim,...)}
+
+\end{longtable}
+
 % Chapter: Files, macros, variables, etc.
 \chapter{C code: files, macros, variables, etc.}
 
@@ -6853,6 +6880,9 @@ \subsection*{Modifications for version 2.69 (released 10/17/22)}
 \item Fixed bug in which commands added mid-simulation were not added to the command queue.
 \item Fixed bug in the Python interface, in which commands with an `@' timing type weren't accepting an ``on'' time.
 
+\subsection*{Modifications for version 2.70 (released 10/24/22)}
+\item Fixed bug, or maybe just a lack of feature availablility, in libsmoldyn and Python interface in which reaction probabilities could not be set for bimolecular reactions.
+
 \end{itemize}
 
 

docs/Smoldyn/SmoldynManual.tex

@@ -92,7 +92,7 @@
 
 
 \title{Smoldyn User's Manual}
-\subtitle{Version 2.69}
+\subtitle{Version 2.70}
 \date{\copyright October, 2022}
 \author{Steve Andrews}
 \maketitle
@@ -4900,7 +4900,7 @@ \section{Reactions}
 \hfill \\
 C/C++: \ttt{enum ErrorCode smolSetReactionRate(simptr sim, int order, char *reaction, double rate, int isinternal)}\\
 Python: \ttt{ErrorCode setReactionRate(int order, str reaction, float rate, int isinternal)}\\
-Set the reaction rate to \ttt{rate}. If this value is to be interpreted as an internal reaction rate parameter, meaning the production rate for zeroth order reactions, the reaction probability for first order reactions, or the binding radius for second order reactions, then set \ttt{isinternal} to 1. Rather than calling this function at all, it's usually easier to use the \ttt{rate} parameter of the \ttt{smolAddReaction} function, although that doesn't cope with internal rate values.
+Set the reaction rate to \ttt{rate}. If this value is to be interpreted as an internal reaction rate parameter, meaning the production rate for zeroth order reactions, the reaction probability for first order reactions, or the binding radius for second order reactions, then set \ttt{isinternal} to 1. Rather than calling this function at all, it's usually easier to use the \ttt{rate} parameter of the \ttt{smolAddReaction} function, although that doesn't cope with internal rate values. As a new feature in version 2.70, set \ttt{isinternal} to 2 to set the reaction probability for bimolecular reactions.
 
 \item[SetReactionRegion]
 \hfill \\

examples/S95_regression/output_270/ReflectToNewSpecies_270_out.txt

@@ -0,0 +1,23 @@
+C(solution) -0.357922 0.0613253 55
+B(solution) 1.15343 3.41728 56
+B(solution) 0.705288 3.11171 38
+B(solution) 2.1669 1.75707 48
+B(solution) -0.164554 0.998179 2
+B(solution) -0.650107 1.99753 43
+C(solution) -1.12781 -1.90779 54
+B(solution) 1.98938 0.586683 41
+B(solution) -2.53428 2.99092 45
+C(solution) -2.00884 -0.38033 49
+B(solution) 2.41065 0.508777 30
+B(solution) -0.915844 -1.83496 53
+B(solution) -0.491033 0.893189 44
+B(solution) 1.59549 0.937907 11
+B(solution) -2.59478 -2.47797 47
+B(solution) -3.37513 0.963243 46
+C(solution) 0.130363 -0.65898 52
+B(solution) -0.382171 -1.29061 23
+B(solution) 2.16319 -1.8457 22
+C(solution) 1.39249 0.972339 50
+B(solution) 0.302106 -0.421039 4
+C(solution) -2.05749 0.506893 42
+C(solution) 0.940912 1.9385 57

examples/S95_regression/output_270/abba_270_out.txt

@@ -0,0 +1,139 @@
+ABBA(solution) 46.3035 58.8208 1624
+A(solution) 57.7307 80.5214 1694
+ABB(solution) 82.5781 24.5531 1561
+ABB(solution) 6.00617 97.4613 1574
+A(solution) 68.9879 98.8645 1498
+B(solution) 68.8963 32.6788 1136
+ABB(solution) 95.6276 32.2705 1502
+A(solution) 8.11104 3.44165 1081
+AB(solution) 70.0718 20.0393 1613
+B(solution) 38.4872 4.45604 1451
+B(solution) 2.3366 7.35065 1609
+B(solution) 27.9455 66.9527 1551
+B(solution) 39.9558 40.3408 1544
+AB(solution) 67.8041 90.5702 1245
+A(solution) 3.71953 16.0886 1247
+BB(solution) 23.8989 23.1836 1562
+AB(solution) 14.4419 95.6903 1587
+B(solution) 63.3477 47.2307 736
+ABBA(solution) 82.4461 31.7218 1642
+B(solution) 37.531 12.2986 1635
+AB(solution) 32.6979 85.8078 1697
+B(solution) 90.2134 61.5987 1617
+A(solution) 91.0555 5.8703 1608
+B(solution) 19.0061 33.7864 1591
+B(solution) 64.6386 70.4236 1648
+AB(solution) 69.7327 16.3972 1427
+AB(solution) 55.9005 68.1525 1494
+ABB(solution) 67.8429 62.5507 1657
+AB(solution) 38.8158 20.3319 1631
+A(solution) 76.4052 88.2722 716
+AB(solution) 21.0761 54.3293 1420
+B(solution) 85.98 98.4729 566
+A(solution) 19.8712 36.2168 1062
+AB(solution) 70.7099 70.5292 1627
+B(solution) 78.862 58.9558 1481
+BB(solution) 29.4209 20.8682 1655
+AB(solution) 34.5939 83.3536 1625
+B(solution) 99.9769 54.49 1577
+A(solution) 82.565 20.5696 1560
+B(solution) 97.7187 27.8144 1536
+BB(solution) 30.9268 80.6037 1652
+B(solution) 89.4958 24.7922 1424
+B(solution) 45.935 75.8825 1671
+AB(solution) 32.7501 51.3415 1704
+A(solution) 99.2024 52.2884 1616
+AB(solution) 34.9537 45.0067 1696
+B(solution) 28.7298 81.4369 1491
+A(solution) 58.2608 98.7332 58
+B(solution) 24.3345 83.6734 1701
+B(solution) 21.8863 74.6042 1559
+B(solution) 79.1031 33.397 1425
+ABB(solution) 39.9501 17.4944 1698
+A(solution) 73.7162 49.4611 585
+A(solution) 96.1844 48.9809 1507
+AB(solution) 50.1428 7.47575 1679
+A(solution) 29.551 75.0078 1651
+A(solution) 11.2043 13.5622 1241
+ABB(solution) 84.9868 61.8705 1571
+A(solution) 45.4787 55.0642 1135
+AB(solution) 29.1436 36.6221 1682
+B(solution) 59.578 4.75735 1499
+BB(solution) 52.4691 10.9535 1678
+A(solution) 59.2123 27.4037 571
+B(solution) 10.3696 55.5942 1528
+A(solution) 27.9614 75.3954 1490
+B(solution) 89.1757 69.1036 1659
+AB(solution) 99.2789 82.8818 1526
+ABB(solution) 38.0515 57.34 1489
+AB(solution) 22.9264 87.2587 1553
+A(solution) 11.2322 38.6631 431
+A(solution) 30.3142 54.8411 981
+ABBA(solution) 29.1005 73.6399 1630
+AB(solution) 16.4571 59.5268 1693
+A(solution) 66.0595 36.7878 549
+ABB(solution) 9.02642 19.9385 1692
+AB(solution) 10.3364 3.057 1605
+A(solution) 4.62286 84.1483 241
+A(solution) 20.143 39.2373 1110
+A(solution) 12.0056 18.7195 1312
+A(solution) 77.982 19.3055 563
+B(solution) 49.9156 17.2105 1665
+A(solution) 14.7263 36.1113 1535
+A(solution) 81.933 82.4655 1207
+A(solution) 24.7224 29.1723 1590
+A(solution) 39.4145 99.1342 1024
+BB(solution) 67.6548 87.7443 1506
+BB(solution) 27.4596 35.6993 1667
+A(solution) 91.4141 6.55212 1487
+A(solution) 73.7318 17.7251 1610
+A(solution) 80.2296 87.5744 883
+A(solution) 14.8036 39.7811 471
+B(solution) 12.6818 42.5295 1538
+B(solution) 61.6112 79.6464 1695
+A(solution) 49.2705 13.7017 1677
+A(solution) 50.8563 71.1389 1670
+AB(solution) 78.7603 43.9697 1674
+A(solution) 32.3243 66.7615 1273
+A(solution) 49.3639 92.7307 46
+B(solution) 97.3325 25.1559 1708
+A(solution) 67.5224 81.0715 1505
+ABB(solution) 47.5082 62.2276 1699
+B(solution) 12.4071 49.7438 1628
+B(solution) 3.68375 54.4788 1218
+B(solution) 21.4408 93.4523 1564
+B(solution) 70.482 42.4237 1001
+A(solution) 22.0335 63.2516 1344
+A(solution) 18.9598 47.9127 1054
+AB(solution) 10.7444 75.2443 1690
+A(solution) 94.3107 99.6595 1601
+B(solution) 52.3305 72.7436 1361
+A(solution) 25.1216 37.2383 1666
+A(solution) 49.1906 62.8809 1096
+A(solution) 30.1336 73.893 1495
+AB(solution) 13.796 70.0412 1566
+BB(solution) 10.2538 7.88075 1504
+A(solution) 16.1321 96.8096 1295
+A(solution) 2.99806 73.7281 84
+A(solution) 38.776 62.7925 1280
+ABB(solution) 51.6308 2.58026 1653
+A(solution) 71.3619 69.0635 1478
+A(solution) 51.4099 26.1088 35
+AB(solution) 39.908 64.0243 1389
+AB(solution) 69.9289 72.8645 1240
+A(solution) 86.2431 78.3754 650
+A(solution) 8.56043 17.933 1503
+BB(solution) 90.098 4.64897 1706
+A(solution) 44.858 19.2698 1664
+A(solution) 64.951 62.2964 1647
+B(solution) 29.0953 9.83326 1686
+A(solution) 25.7904 22.2982 1654
+A(solution) 68.482 59.4403 1656
+A(solution) 84.0165 66.6426 1658
+A(solution) 36.8815 17.1281 1660
+AB(solution) 35.2544 8.74738 1685
+A(solution) 21.989 83.4361 1700
+A(solution) 91.0593 2.92143 1705
+A(solution) 98.1303 26.7744 1707
+A(solution) 3.19965 46.0179 1709
+B(solution) 2.56838 46.9873 1710

examples/S95_regression/output_270/addspecies_270_out.txt

@@ -0,0 +1,48 @@
+red(solution) 90.4972 81.0502 100
+red(solution) 98.0589 93.3756 69
+red(solution) 33.1146 17.3923 50
+red(solution) 70.9055 33.6384 97
+red(solution) 25.0498 2.61051 62
+red(solution) 8.71548 4.60089 21
+red(solution) 1.30789 7.46917 54
+red(solution) 67.5984 28.6199 57
+red(solution) 42.0532 51.8614 92
+red(solution) 4.06433 7.25128 22
+red(solution) 93.7256 73.1283 90
+red(solution) 10.9712 93.2922 41
+red(solution) 27.1614 37.8607 73
+red(solution) 32.5828 85.6121 18
+red(solution) 39.4303 86.2192 51
+red(solution) 59.6057 20.9658 13
+red(solution) 35.7113 86.7862 46
+red(solution) 17.9327 13.1199 83
+red(solution) 94.2678 89.8163 60
+red(solution) 9.56222 37.7048 81
+red(solution) 81.6425 75.7432 27
+red(solution) 71.548 87.2117 79
+red(solution) 96.0011 59.9704 4
+red(solution) 17.237 37.2606 28
+green(solution) 61.7398 11.6186 122
+green(solution) 23.9821 91.4083 175
+green(solution) 58.3028 56.9074 198
+green(solution) 72.3253 20.371 136
+green(solution) 88.3772 17.6881 105
+green(solution) 50.0295 29.4867 168
+green(solution) 71.6295 84.8946 194
+green(solution) 93.3559 5.78477 154
+green(solution) 94.6177 38.4568 116
+green(solution) 14.1762 94.8959 131
+green(solution) 83.3449 23.0791 101
+green(solution) 26.3303 58.9103 189
+green(solution) 45.614 46.9224 147
+green(solution) 16.3556 16.0441 102
+green(solution) 16.5464 72.6081 149
+green(solution) 23.7187 32.3751 169
+green(solution) 79.7783 38.6115 144
+green(solution) 64.4804 77.2588 158
+green(solution) 66.7818 72.966 162
+green(solution) 38.4539 39.4039 181
+green(solution) 54.3873 74.826 138
+green(solution) 76.6529 76.8657 179
+green(solution) 97.9165 79.0709 178
+green(solution) 42.252 73.2819 177

examples/S95_regression/output_270/allostery_270_out.txt

@@ -0,0 +1,20 @@
+green(solution) 2 25 2008
+green(solution) 0 10 1986
+red(solution) 2 10 2021
+green(solution) 0 20 2020
+green(solution) 2 15 2000
+blue(solution) -2 20 4
+green(solution) 2 20 1975
+blue(solution) 4 10 17
+red(solution) 0 5 2028
+blue(solution) -2 25 5
+blue(solution) 4 5 16
+green(solution) 2 5 2005
+blue(solution) -2 5 1
+blue(solution) -2 10 2
+blue(solution) 4 25 20
+blue(solution) -2 15 3
+blue(solution) 4 20 19
+blue(solution) 4 15 18
+green(solution) 0 15 1999
+red(solution) 0 25 2031