diff --git a/docs/pages/FiberCpp/calculations/calculations.md b/docs/pages/FiberCpp/calculations/calculations.md index 7c00fabf..795300a8 100644 --- a/docs/pages/FiberCpp/calculations/calculations.md +++ b/docs/pages/FiberCpp/calculations/calculations.md @@ -46,7 +46,7 @@ where $K$ is a matrix containing the springs stiffness, $x$ is a vector containi and numerical methods exist to solve +Kx=F+ for $x$. -## Crossbridge links +## Cross-bridge links Myosin heads located at the thick filament nodes can attach to neighboring binding sites at the thin filament nodes, thus affecting the filament lattice framework. @@ -54,11 +54,11 @@ Myosin heads located at the thick filament nodes can attach to neighboring bindi cb_link

-A crossbridge located at the $j^{th}$ thick filament node which attaches to the $i^{th}$ node of the thin filament generates a force $f_{cb}$ given by: +A cross-bridge located at the $j^{th}$ thick filament node which attaches to the $i^{th}$ node of the thin filament generates a force $f_{cb}$ given by: ++f_{cb} = k_{cb} \, (m_j - a_i + x_{ps})++ -where $k_{cb}$ is the crossbridge spring stiffness and $x_{ps}$ is the crossbridge extension when deploying the power stroke. +where $k_{cb}$ is the cross-bridge spring stiffness and $x_{ps}$ is the crossbridge extension when deploying the power stroke. This additional force on the filaments should be added to the force-balance equations : @@ -74,7 +74,7 @@ The terms in red will add non-tridiagonal, opposite elements to the $K$ matrix: while the blue terms will contribute to the $F$ vector. -Crossbridge linking toughens the numerical solving of +K x = F+, which notably requires an iterative procedure to find a solution $x$ that satisfies a certain precision. +Cross-bridge linking toughens the numerical solving of +K x = F+, which notably requires an iterative procedure to find a solution $x$ that satisfies a certain precision. ## Titin @@ -94,7 +94,7 @@ Myosin Binding Protein C (MyBP-C) is a striated muscle contracting protein. It i MyBPC

-This protein interacts both with myosin and actin and is a modulator of cardiac contractility. In the model, MyBPC can attach to an actin binding site and act as a "non-force-generating crossbridge link" (meaning it cannot undergo a power stroke). Such C-links contribute to the force-balance equations: +This protein interacts both with myosin and actin and is a modulator of cardiac contractility. In the model, MyBPC can attach to an actin binding site and act as a "non-force-generating cross-bridge link" (meaning it cannot undergo a power stroke). Such C-links contribute to the force-balance equations: ++f_{pc} = k_{pc} \, (m_j - a_i)++ diff --git a/docs/pages/FiberCpp/testing_suite/force_balance_test/force_balance_test.md b/docs/pages/FiberCpp/testing_suite/force_balance_test/force_balance_test.md deleted file mode 100644 index cfc73b91..00000000 --- a/docs/pages/FiberCpp/testing_suite/force_balance_test/force_balance_test.md +++ /dev/null @@ -1,133 +0,0 @@ ---- -title: Force balance test -parent: Testing suite -grand_parent: FiberCpp -has_children: false -nav_order: 1 ---- - -# Force balance test - -As explained [here](../../calculations/calculations.html), FiberCpp solves a matrix equation of form +K x = F+, where +x+ is a vector containing the node positions of each filament, +K+ is the tridiagonal stiffness matrix, and +F+ is a vector containing the crossbridges, titin, and myosin-binding protein C forces. The solving algorithm uses the conjugate gradient method, which is an iterative method to obtain the solution +x+. In the option file, the user can define `x_pos_tol`, which is the algorithm tolerance (the algorithm stops at iteration #+n+ when +\mid x_{n} - x_{n-1} \mid \lt x_{pos_{tol}}+). - -The force-balance test is a Python code written to evaluate +\epsilon = K x - F+, which is a measurement of the solving algorithm precision. The testing code calculates the residual forces at each node, for both the thick and thin filaments. This residual force (or error force) is then divided by the filament springs stiffness to obtain a node position error in nm. This position error should get closer to zero as the position tolerance decreases. - -## What this test does - -The force-balance test: - -+ Runs 4 simulations in which a half-sarcomere is held isometric and activated in a solution with a pCa of 4.5. Each simulations is run with a decreasing `x_pos_tol`. - -+ Saves 4 status files (for each simulation) where the node positions for each thick and thin filament are stored. - -+ Computes the average maximal node position error for all thick/thin filaments from each dump file. - -The batch file containing the instructions for this test is: - -``` - -{ - "FiberSim_batch": { - "FiberCpp_exe": { - "relative_to": "this_file", - "exe_file": "../../bin/FiberCpp.exe" - }, - "job": [ - { - "relative_to": "this_file", - "model_file": "sim_input/model.json", - "options_file": "sim_input/options_0.json", - "protocol_file": "sim_input/pCa45_protocol.txt", - "results_file": "sim_output/0/results.txt", - "output_handler_file": "sim_input/output_handler_0.json" - }, - { - "relative_to": "this_file", - "model_file": "sim_input/model.json", - "options_file": "sim_input/options_1.json", - "protocol_file": "sim_input/pCa45_protocol.txt", - "results_file": "sim_output/1/results.txt", - "output_handler_file": "sim_input/output_handler_1.json" - }, - { - "relative_to": "this_file", - "model_file": "sim_input/model.json", - "options_file": "sim_input/options_2.json", - "protocol_file": "sim_input/pCa45_protocol.txt", - "results_file": "sim_output/2/results.txt", - "output_handler_file": "sim_input/output_handler_2.json" - }, - { - "relative_to": "this_file", - "model_file": "sim_input/model.json", - "options_file": "sim_input/options_3.json", - "protocol_file": "sim_input/pCa45_protocol.txt", - "results_file": "sim_output/3/results.txt", - "output_handler_file": "sim_input/output_handler_3.json" - } - ], - "batch_validation": [ - { - "validation_type": "force_balance", - "relative_to": "this_file", - "model_file": "sim_input/model.json", - "options_file": [ "sim_input/options_0.json", "sim_input/options_1.json", "sim_input/options_2.json", "sim_input/options_3.json" ], - "protocol_file": "sim_input/pCa45_protocol.txt", - "output_data_folder": "sim_output/analysis" - } - ] - } -} - -``` - -As explained above, this batch file consists in 4 jobs with the same protocol file but different [option files](../../../Structures/Options/Options.html). `x_pos_tol` from the option files ranges from 1 nm to 10 -12 nm. - -The last block called `batch_validation` provides the type of validation that must be run and the necessary files information. - -## Instructions - -Before proceeding, make sure that you have followed the [installation instructions](../../../installation/installation.html) and that you already tried to run the [getting started demos](../../../demos/getting_started/getting_started.html). - -### Getting ready - -+ Open an Anaconda Prompt - -+ Activate the FiberSim Anaconda Environment by executing: -``` -conda activate fibersim -``` -+ Change directory to `/code/FiberPy/FiberPy`, where `` is the directory where you installed FiberSim. - -### Run the test - -+ Type: - ``` -python Fiberpy.py run_batch "../../../testing_suite/force_balance/batch_force_balance.json" - ``` - -+ You should see text appearing in the terminal window, showing that the simulations are running. When it finishes (this should take less than one minute), you should see something similar to the image below. - -![command prompt](command_prompt.png) - -### Viewing the results - -Results and summary figures from the 4 simulations are written to different folders in `/testing_suite/force_balance/sim_output`. - - - -The folder `analysis` contains the file `filaments_error.png` which shows the maximal node position error as a function of `x_pos_tol` for the last time-step calculation. As expected, the error on the calculated node position decreases if `x_pos_tol` decreases. - - - - - - - - - - - - - - diff --git a/docs/pages/FiberCpp/testing_suite/kinetics_test/figures/active_to_inactive.png b/docs/pages/FiberCpp/testing_suite/kinetics_test/figures/active_to_inactive.png deleted file mode 100644 index b2839406..00000000 Binary files a/docs/pages/FiberCpp/testing_suite/kinetics_test/figures/active_to_inactive.png and /dev/null differ diff --git a/docs/pages/FiberCpp/testing_suite/kinetics_test/figures/inactive_to_active.png b/docs/pages/FiberCpp/testing_suite/kinetics_test/figures/inactive_to_active.png deleted file mode 100644 index e4853b58..00000000 Binary files a/docs/pages/FiberCpp/testing_suite/kinetics_test/figures/inactive_to_active.png and /dev/null differ diff --git a/docs/pages/FiberCpp/testing_suite/kinetics_test/kinetics_test.md b/docs/pages/FiberCpp/testing_suite/kinetics_test/kinetics_test.md deleted file mode 100644 index ca27476f..00000000 --- a/docs/pages/FiberCpp/testing_suite/kinetics_test/kinetics_test.md +++ /dev/null @@ -1,344 +0,0 @@ ---- -title: Kinetics test -parent: Testing suite -grand_parent: FiberCpp -has_children: true -nav_order: 2 ---- - -# Kinetics test - -FiberCpp also computes the kinetics for the actin binding sites, the myosin and the myosin-binding protein C molecules. At each time step, transition probabilities are calculated according to the rate laws implemented in the [model file](../../../structures/model/model.html) and transition events are implemented. - -The kinetics test is a Python code written to make sure that the transition events calculated by FiberCpp occur according to the rate laws that were specified in the model file. The kinetics test suite validates the thin and thick kinetics. - -## Thin filament kinetics - -Actin regulatory units are composed of binding sites that can transition from an inactive state to an active state, and vice-versa. At each time step, all the binding sites from a regulatory unit can transition together according to the rate constants `a_k_on` and `a_k_off` defined in the [model file](../../../structures/model/model.html). The probabilty of a regulatory unit activating is calculated using +a_{k_{on}} [Ca^{2+}]+, and the probability of a regulatory unit deactivating is calculated using +a_{k_{off}}+. These probabilities are also modulated by `a_k_coop`, which is a parameter quantifiying the inter-regulatory unit cooperativity: - -+ If no direct neighboring unit is activated, the activation rate is given by: - -++ a_{k_{on}} [Ca^{2+}] ++ - -+ If one direct neighboring unit is already activated, the activation rate is given by: - -++ a_{k_{on}} [Ca^{2+}] (1 + a_{k_{coop}})++ - -+ If the two direct neighboring units are already activated, the activation rate is given by: - -++ a_{k_{on}} [Ca^{2+}] (1 + 2 \, a_{k_{coop}})++ - -The same reasoning goes for the inactivating rate constant +a_{k_{off}}+. - - -### What this test does - -The actin kinetics test: - -+ Runs a simulations in which a half-sarcomere is held isometric and activated in a solution with a pCa of 6.0. - -+ Saves a status file at each time step, which contains the state of every regulatory unit. - -+ Assesses all the regulatory units state transitions occuring between two consecutive time-steps, and calculates the apparent rate constants. - -+ Compares the calculated rate constants with those provided in the model file. - -The batch file containing the instructions for this test is: - -``` -{ - "FiberSim_batch": { - "FiberCpp_exe": { - "relative_to": "this_file", - "exe_file": "../../bin/FiberCpp.exe" - }, - "job": [ - { - "relative_to": "this_file", - "model_file": "sim_input/model.json", - "options_file": "sim_input/options.json", - "protocol_file": "sim_input/pCa6_protocol.txt", - "results_file": "sim_output/results.txt", - "output_handler_file": "sim_input/output_handler.json" - } - ], - "batch_validation": [ - { - "validation_type": "a_kinetics", - "relative_to": "this_file", - "model_file": "sim_input/model.json", - "options_file": "sim_input/options.json", - "protocol_file": "sim_input/pCa6_protocol.txt", - "output_data_folder": "sim_output/analysis" - } - ] - } -} -``` - -As explained above, this batch file consists in a single job. The block called `batch_validation` provides the type of validation that must be run and the necessary files information. - - -### Instructions - -Before proceeding, make sure that you have followed the [installation instructions](../../../installation/installation.html) and that you already tried to run the [getting started demos](../../../demos/getting_started/getting_started.html). - -### Getting ready - -+ Open an Anaconda Prompt - -+ Activate the FiberSim Anaconda Environment by executing: -``` -conda activate fibersim -``` -+ Change directory to `/code/FiberPy/FiberPy`, where `` is the directory where you installed FiberSim. - -### Run the test - -+ Type: -``` -python Fiberpy.py run_batch "../../../testing_suite/thin_kinetics/batch_a_kinetics.json" -``` - -+ You should see text appearing in the terminal window, showing that the simulations are running. When it finishes (this can take ~30 minutes), you should see something similar to the image below. - -![command prompt](figures/command_prompt_a.png) - -### Viewing the results - -The results and summary figure from the simulation are written to files in `/testing_suite/thin_kinetics/sim_output` - - - -The `hs` folder contains the status files that were dumped at each time-step calculation. - -The `analysis` folder contains two figure files showing the calculated activating and deactivating rate constants for the three cooperative scenarios, as well as the model values. - - - - -## Thick filament kinetics - -Thick filaments are composed of myosin and myosin-binding protein C. The kinetics scheme for both molecules is defined in the model file, and examples will be provided below. -The transition parameters between each states are described in the `transition` blocks. The two following tests respectively verifiy the myosin and the myosin-binding protein C kinetics. - -## Myosin kinetics test - -### What this test does - -The myosin kinetics test: - -+ Runs a simulations in which a half-sarcomere is held isometric and activated in a solution with a pCa of 4.5. - -+ Saves a status file at each time step, which contains the state of every myosin molecules. - -+ Assesses all the myosin transitions occuring between two consecutive time-steps, and calculates the apparent rate constants. - -+ Compares the calculated rate constants with those provided in the following model file: - -``` -"m_kinetics": [ - { - "no_of_states": 3, - "max_no_of_transitions": 2, - "scheme": [ - { - "number": 1, - "type": "S", - "extension": 0, - "transition": [ - { - "new_state": 2, - "rate_type": "force_dependent", - "rate_parameters": [ - 100, - 100 - ] - } - ] - }, - { - "number": 2, - "type": "D", - "extension": 0, - "transition": [ - { - "new_state": 1, - "rate_type": "constant", - "rate_parameters": [ - 200 - ] - }, - { - "new_state": 3, - "rate_type": "gaussian", - "rate_parameters": [ - 200 - ] - } - ] - }, - { - "number": 3, - "type": "A", - "extension": 7.0, - "transition": [ - { - "new_state": 2, - "rate_type": "poly", - "rate_parameters": [ - 150, - 1, - 2 - ] - } - ] - } - ] - } - ] -``` - - -### Getting ready - -+ Open an Anaconda Prompt - -+ Activate the FiberSim Anaconda Environment by executing: -``` -conda activate fibersim -``` -+ Change directory to `/code/FiberPy/FiberPy`, where `` is the directory where you installed FiberSim. - -### Run the test - -+ Type: - ``` -python Fiberpy.py run_batch "../../../testing_suite/thick_kinetics/myosin/batch_m_kinetics.json" - ``` - -+ You should see text appearing in the terminal window, showing that the simulations are running. When it finishes (this can take ~20-30 minutes), you should see something similar to the image below. - -![command prompt](figures/command_prompt_m.PNG) - -### Viewing the results - -The results and summary figure from the simulation are written to files in `/testing_suite/thick_kinetics/myosin/sim_output` - - - -The `hs` folder contains the status files that were dumped at each time-step calculation. - -The `analysis` folder contains figure files showing the calculated rate laws for all myosin transitions, as well as the model rate laws. - -Transition #0 (from state 1 to state 2) is force-dependent, and the transition rate is plotted as a function of the node force. - - - -Transition #1 (from state 2 to state 1) is constant. - - - -Transition #2 (from state 2 to state 3) is stretch-dependent, and the transition rate is plotted as a function of the stretch values. Furthermore, the attachement probabilities are modulated by the angle difference between a myosin head and the nearest binding sites. Each panel represents an angle difference interval and shows the calculated and theoretical attachment rates for the mid-interval angle difference. - - - -Transition #3 (from state 3 to state 2) is stretch-dependent, and the transition rate is plotted as a function of the stretch values. - - - -## Myosin-binding protein C kinetics test - -### What this test does - -The mybpc kinetics test: - -+ Runs a simulations in which a half-sarcomere is held isometric and activated in a solution with a pCa of 4.5. - -+ Saves a status file at each time step, which contains the state of every mybpc molecule. - -+ Assesses all the mybpc transitions occuring between two consecutive time-steps, and calculates the apparent rate constants. - -+ Compares the calculated rate constants with those provided in the following model file: - -``` - "c_kinetics": [ - { - "no_of_states": 2, - "max_no_of_transitions": 1, - "scheme": [ - { - "number": 1, - "type": "D", - "extension": 0, - "transition": [ - { - "new_state": 2, - "rate_type": "gaussian_pc", - "rate_parameters": [ - 200 - ] - } - ] - }, - { - "number": 2, - "type": "A", - "extension": 0.0, - "transition": [ - { - "new_state": 1, - "rate_type": "poly", - "rate_parameters": [ - 150, - 1, - 2 - ] - } - ] - } - ] - } - ] -} -``` - -### Getting ready - -+ Open an Anaconda Prompt - -+ Activate the FiberSim Anaconda Environment by executing: -``` -conda activate fibersim -``` -+ Change directory to `/code/FiberPy/FiberPy`, where `` is the directory where you installed FiberSim. - -### Run the test - -+ Type: - ``` -python Fiberpy.py run_batch "../../../testing_suite/thick_kinetics/mybpc/batch_c_kinetics.json" - ``` - -+ You should see text appearing in the terminal window, showing that the simulations are running. When it finishes (this can take ~20-30 minutes), you should see something similar to the image below. - -![command prompt](figures/command_prompt_c.PNG) - -### Viewing the results - -The results and summary figure from the simulation are written to files in `/testing_suite/thick_kinetics/mybpc/sim_output` - - - -The `hs` folder contains the status files that were dumped at each time-step calculation. - -The `analysis` folder contains figure files showing the calculated rate laws for all mybpc transitions, as well as the model rate laws. - - - - - - - - - diff --git a/docs/pages/FiberCpp/testing_suite/testing_suite.md b/docs/pages/FiberCpp/testing_suite/testing_suite.md deleted file mode 100644 index bb0e45a1..00000000 --- a/docs/pages/FiberCpp/testing_suite/testing_suite.md +++ /dev/null @@ -1,16 +0,0 @@ ---- -title: Testing suite -parent: FiberCpp -has_children: true -nav_order: 4 ---- - -# Testing suite - -At each time step, FiberCpp calculates the position of each thick and thin filaments node by solving the force-balance matrix equation (see [here](../calculations/calculations.md) for more information). FiberCpp also computes the kinetics for the actin binding sites and the myosin/myosin-binding protein C molecules. In order to make sure that the calculations are done properly, we have developed a testing suite in Python. - - - - - - diff --git a/docs/pages/code_validation/actin/actin.md b/docs/pages/code_validation/actin/actin.md index d5023966..7081429c 100644 --- a/docs/pages/code_validation/actin/actin.md +++ b/docs/pages/code_validation/actin/actin.md @@ -6,3 +6,112 @@ nav_order: 2 --- # Actin + +Actin regulatory units are composed of binding sites that can transition from an inactive state to an active state, and vice-versa, as schematized below: + +

+ +

+ +At each time step, all the binding sites from a regulatory unit can transition together according to the rate constants `a_k_on` and `a_k_off` defined in the [model file](../../structures/model/model.html). The probabilty of a regulatory unit activating is calculated using +a_{k_{on}} [Ca^{2+}]+, and the probability of a regulatory unit deactivating is calculated using +a_{k_{off}}+. These probabilities are also modulated by `a_k_coop`, which is a parameter quantifiying the inter-regulatory unit cooperativity: + ++ If no direct neighboring unit is activated, the activation rate is given by: + +++ a_{k_{on}} [Ca^{2+}] ++ + ++ If one direct neighboring unit is already activated, the activation rate is given by: + +++ a_{k_{on}} [Ca^{2+}] (1 + a_{k_{coop}})++ + ++ If the two direct neighboring units are already activated, the activation rate is given by: + +++ a_{k_{on}} [Ca^{2+}] (1 + 2 \, a_{k_{coop}})++ + +The same reasoning goes for the inactivating rate constant +a_{k_{off}}+. + + +## What this test does + +The actin kinetics test: + ++ Runs a simulations in which a half-sarcomere is held isometric and activated in a solution with a pCa of 6.0. + ++ Saves a status file at each time step, which contains the state of every regulatory unit. + ++ Assesses all the regulatory units state transitions occuring between two consecutive time-steps, and calculates the apparent rate constants. + ++ Compares the calculated rate constants with those provided in the model file. + +The batch file containing the instructions for this test is: + +``` +{ + "FiberSim_batch": { + "FiberCpp_exe": { + "relative_to": "this_file", + "exe_file": "../../bin/FiberCpp.exe" + }, + "job": [ + { + "relative_to": "this_file", + "model_file": "sim_input/model.json", + "options_file": "sim_input/options.json", + "protocol_file": "sim_input/pCa6_protocol.txt", + "results_file": "sim_output/results.txt", + "output_handler_file": "sim_input/output_handler.json" + } + ], + "batch_validation": [ + { + "validation_type": "a_kinetics", + "relative_to": "this_file", + "model_file": "sim_input/model.json", + "options_file": "sim_input/options.json", + "protocol_file": "sim_input/pCa6_protocol.txt", + "output_data_folder": "sim_output/analysis" + } + ] + } +} +``` + +As explained above, this batch file consists in a single job. The block called `batch_validation` provides the type of validation that must be run and the necessary files information. + + +## Instructions + +Before proceeding, make sure that you have followed the [installation instructions](../../installation/installation.html) and that you already tried to run the [getting started demos](../../demos/getting_started/getting_started.html). + +### Getting ready + ++ Open an Anaconda Prompt + ++ Activate the FiberSim Anaconda Environment by executing: +``` +conda activate fibersim +``` ++ Change directory to `/code/FiberPy/FiberPy`, where `` is the directory where you installed FiberSim. + +### Run the test + ++ Type: +``` +python Fiberpy.py run_batch "../../../testing_suite/thin_kinetics/batch_a_kinetics.json" +``` + ++ You should see text appearing in the terminal window, showing that the simulations are running. When it finishes (this can take ~15 minutes), you should see something similar to the image below. + +![command prompt](command_prompt_a.png) + +### Viewing the results + +The results and summary figure from the simulation are written to files in `/testing_suite/thin_kinetics/sim_output` + + + +The `hs` folder contains the status files that were dumped at each time-step calculation. + +The `analysis` folder contains two figure files showing the calculated activating and deactivating rate constants for the three cooperative scenarios, as well as the model values. + + + diff --git a/docs/pages/code_validation/actin/actin_kinetics.png b/docs/pages/code_validation/actin/actin_kinetics.png new file mode 100644 index 00000000..11090176 Binary files /dev/null and b/docs/pages/code_validation/actin/actin_kinetics.png differ diff --git a/docs/pages/code_validation/actin/active_to_inactive.png b/docs/pages/code_validation/actin/active_to_inactive.png new file mode 100644 index 00000000..05b1457a Binary files /dev/null and b/docs/pages/code_validation/actin/active_to_inactive.png differ diff --git a/docs/pages/FiberCpp/testing_suite/kinetics_test/figures/command_prompt_a.PNG b/docs/pages/code_validation/actin/command_prompt_a.PNG similarity index 100% rename from docs/pages/FiberCpp/testing_suite/kinetics_test/figures/command_prompt_a.PNG rename to docs/pages/code_validation/actin/command_prompt_a.PNG diff --git a/docs/pages/code_validation/actin/inactive_to_active.png b/docs/pages/code_validation/actin/inactive_to_active.png new file mode 100644 index 00000000..da77a96b Binary files /dev/null and b/docs/pages/code_validation/actin/inactive_to_active.png differ diff --git a/docs/pages/FiberCpp/testing_suite/kinetics_test/figures/sim_output_thin.PNG b/docs/pages/code_validation/actin/sim_output_thin.PNG similarity index 100% rename from docs/pages/FiberCpp/testing_suite/kinetics_test/figures/sim_output_thin.PNG rename to docs/pages/code_validation/actin/sim_output_thin.PNG diff --git a/docs/pages/code_validation/code_validation.md b/docs/pages/code_validation/code_validation.md index 40d69222..ead0e4dc 100644 --- a/docs/pages/code_validation/code_validation.md +++ b/docs/pages/code_validation/code_validation.md @@ -7,7 +7,14 @@ nav_order: 6 # Code Validation {:.no_toc} -At each time step, FiberCpp calculates the position of each thick and thin filaments node by solving the force-balance matrix equation. FiberCpp also computes the kinetics for the actin binding sites and the myosin/myosin-binding protein C molecules. In order to make sure that the calculations are done properly, we have developed a testing suite in Python. +At each time step, FiberCpp calculates the position of each thick and thin filaments node. FiberCpp also computes the kinetics for the actin binding sites and the myosin/myosin-binding protein C molecules. In order to make sure that the calculations are done properly, we have developed a testing suite in Python. -* TOC -{:toc} \ No newline at end of file +## Force-balance Test + +As explained [here](../FiberCpp/calculations/calculations.html), FiberCpp solves a matrix equation of form +K x = F+, where +x+ is a vector containing the node positions, +K+ is the tridiagonal stiffness matrix, and +F+ is a vector containing the cross-bridges, titin, and myosin-binding protein C forces. The force-balance test is a Python code written to evaluate the accuracy of the algorithm calculations. + +## Kinetics Test + +FiberCpp also computes the kinetics for the actin binding sites, the myosin and the myosin-binding protein C molecules. At each time step, transition probabilities are calculated according to the rate laws implemented in the [model file](../structures/model/model.html) and transition events are implemented. + +The kinetics test is a Python code written to make sure that the transition events calculated by FiberCpp occur according to the rate laws that were specified in the model file. The kinetics test suite validates actin, myosin, and myosin-binding protein C (MyBPC) kinetics. diff --git a/docs/pages/FiberCpp/testing_suite/force_balance_test/command_prompt.png b/docs/pages/code_validation/force_balance/command_prompt.png similarity index 100% rename from docs/pages/FiberCpp/testing_suite/force_balance_test/command_prompt.png rename to docs/pages/code_validation/force_balance/command_prompt.png diff --git a/docs/pages/FiberCpp/testing_suite/force_balance_test/filaments_error.png b/docs/pages/code_validation/force_balance/filaments_error.png similarity index 100% rename from docs/pages/FiberCpp/testing_suite/force_balance_test/filaments_error.png rename to docs/pages/code_validation/force_balance/filaments_error.png diff --git a/docs/pages/code_validation/force_balance/force_balance.md b/docs/pages/code_validation/force_balance/force_balance.md index 2dc5ae81..de41109d 100644 --- a/docs/pages/code_validation/force_balance/force_balance.md +++ b/docs/pages/code_validation/force_balance/force_balance.md @@ -6,3 +6,115 @@ nav_order: 1 --- # Force-balance + +FiberCpp solves a matrix equation of form +K x = F+, where +x+ is a vector containing the node positions, +K+ is the tridiagonal stiffness matrix, and +F+ is a vector containing the cross-bridges, titin, and myosin-binding protein C forces. The solving algorithm uses the conjugate gradient method, which is an iterative method to obtain the solution +x+. In the [option file](../../structures/options/options.html), the user can define `x_pos_tol`, which is the algorithm tolerance (the algorithm stops at iteration #+n+ when +\mid x_{n} - x_{n-1} \mid \lt x_{pos_{tol}}+). + +The force-balance test is a Python code written to evaluate +\epsilon = K x - F+, which is a measurement of the solving algorithm precision. The testing code calculates the residual forces at each node, for both the thick and thin filaments. This residual force (or error force) is then divided by the filament springs stiffness to obtain a node position error in nm. This position error should get closer to zero as the position tolerance decreases. + +## What this test does + +The force-balance test: + ++ Runs 4 simulations in which a half-sarcomere is held isometric and activated in a solution with a pCa of 4.5. Each simulations is run with a decreasing `x_pos_tol`. + ++ Saves 4 status files (for each simulation) where the node positions for each thick and thin filament are stored. + ++ Computes the average maximal node position error for all thick/thin filaments from each dump file. + +The batch file containing the instructions for this test is: + +``` + +{ + "FiberSim_batch": { + "FiberCpp_exe": { + "relative_to": "this_file", + "exe_file": "../../bin/FiberCpp.exe" + }, + "job": [ + { + "relative_to": "this_file", + "model_file": "sim_input/model.json", + "options_file": "sim_input/options_0.json", + "protocol_file": "sim_input/pCa45_protocol.txt", + "results_file": "sim_output/0/results.txt", + "output_handler_file": "sim_input/output_handler_0.json" + }, + { + "relative_to": "this_file", + "model_file": "sim_input/model.json", + "options_file": "sim_input/options_1.json", + "protocol_file": "sim_input/pCa45_protocol.txt", + "results_file": "sim_output/1/results.txt", + "output_handler_file": "sim_input/output_handler_1.json" + }, + { + "relative_to": "this_file", + "model_file": "sim_input/model.json", + "options_file": "sim_input/options_2.json", + "protocol_file": "sim_input/pCa45_protocol.txt", + "results_file": "sim_output/2/results.txt", + "output_handler_file": "sim_input/output_handler_2.json" + }, + { + "relative_to": "this_file", + "model_file": "sim_input/model.json", + "options_file": "sim_input/options_3.json", + "protocol_file": "sim_input/pCa45_protocol.txt", + "results_file": "sim_output/3/results.txt", + "output_handler_file": "sim_input/output_handler_3.json" + } + ], + "batch_validation": [ + { + "validation_type": "force_balance", + "relative_to": "this_file", + "model_file": "sim_input/model.json", + "options_file": [ "sim_input/options_0.json", "sim_input/options_1.json", "sim_input/options_2.json", "sim_input/options_3.json" ], + "protocol_file": "sim_input/pCa45_protocol.txt", + "output_data_folder": "sim_output/analysis" + } + ] + } +} + +``` + +As explained above, this batch file consists in 4 jobs with the same protocol file but different [option files](../../structures/options/options.html)). `x_pos_tol` from the option files ranges from 1 nm to 10 -12 nm. + +The last block called `batch_validation` provides the type of validation that must be run and the necessary files information. + +## Instructions + +Before proceeding, make sure that you have followed the [installation instructions](../../installation/installation.html) and that you already tried to run the [getting started demos](../../demos/getting_started/getting_started.html). + +### Getting ready + ++ Open an Anaconda Prompt + ++ Activate the FiberSim Anaconda Environment by executing: +``` +conda activate fibersim +``` ++ Change directory to `/code/FiberPy/FiberPy`, where `` is the directory where you installed FiberSim. + +### Run the test + ++ Type: + ``` +python Fiberpy.py run_batch "../../../testing_suite/force_balance/batch_force_balance.json" + ``` + ++ You should see text appearing in the terminal window, showing that the simulations are running. When it finishes (this should take less than one minute), you should see something similar to the image below. + +![command prompt](command_prompt.png) + +### Viewing the results + +Results and summary figures from the 4 simulations are written to different folders in `/testing_suite/force_balance/sim_output`. + + + +The folder `analysis` contains the file `filaments_error.png` which shows the maximal node position error as a function of `x_pos_tol` for the last time-step calculation. As expected, the error on the calculated node position decreases if `x_pos_tol` decreases. + + diff --git a/docs/pages/FiberCpp/testing_suite/force_balance_test/output_folder.PNG b/docs/pages/code_validation/force_balance/output_folder.PNG similarity index 100% rename from docs/pages/FiberCpp/testing_suite/force_balance_test/output_folder.PNG rename to docs/pages/code_validation/force_balance/output_folder.PNG diff --git a/docs/pages/FiberCpp/testing_suite/kinetics_test/figures/command_prompt_c.PNG b/docs/pages/code_validation/mybpc/command_prompt_c.PNG similarity index 100% rename from docs/pages/FiberCpp/testing_suite/kinetics_test/figures/command_prompt_c.PNG rename to docs/pages/code_validation/mybpc/command_prompt_c.PNG diff --git a/docs/pages/FiberCpp/testing_suite/kinetics_test/figures/iso_0_transition_0_mybpc.png b/docs/pages/code_validation/mybpc/iso_0_transition_0_mybpc.png similarity index 100% rename from docs/pages/FiberCpp/testing_suite/kinetics_test/figures/iso_0_transition_0_mybpc.png rename to docs/pages/code_validation/mybpc/iso_0_transition_0_mybpc.png diff --git a/docs/pages/FiberCpp/testing_suite/kinetics_test/figures/iso_0_transition_1_mybpc.png b/docs/pages/code_validation/mybpc/iso_0_transition_1_mybpc.png similarity index 100% rename from docs/pages/FiberCpp/testing_suite/kinetics_test/figures/iso_0_transition_1_mybpc.png rename to docs/pages/code_validation/mybpc/iso_0_transition_1_mybpc.png diff --git a/docs/pages/code_validation/mybpc/mybpc.md b/docs/pages/code_validation/mybpc/mybpc.md index 2bace592..130e4eeb 100644 --- a/docs/pages/code_validation/mybpc/mybpc.md +++ b/docs/pages/code_validation/mybpc/mybpc.md @@ -6,3 +6,103 @@ nav_order: 4 --- # MyBPC + +The following test verifies MyBPC kinetics for the 2-state model schematized below. + +

+ +

+ +In this model, MyBPC (yellow) is able to bind to an active actin binding site and transition from an unbound to a bound state. + +## What this test does + +The MyBPC kinetics test: + ++ Runs a simulations in which a half-sarcomere is held isometric and activated in a solution with a pCa of 4.5. + ++ Saves a status file at each time step, which contains the state of every mybpc molecule. + ++ Assesses all the mybpc transitions occuring between two consecutive time-steps, and calculates the apparent rate constants. + ++ Compares the calculated rate constants with those provided in the following model file: + +``` + "c_kinetics": [ + { + "no_of_states": 2, + "max_no_of_transitions": 1, + "scheme": [ + { + "number": 1, + "type": "D", + "extension": 0, + "transition": [ + { + "new_state": 2, + "rate_type": "gaussian_pc", + "rate_parameters": [ + 200 + ] + } + ] + }, + { + "number": 2, + "type": "A", + "extension": 0.0, + "transition": [ + { + "new_state": 1, + "rate_type": "poly", + "rate_parameters": [ + 150, + 1, + 2 + ] + } + ] + } + ] + } + ] +} +``` + +## Instructions + +Before proceeding, make sure that you have followed the [installation instructions](../../installation/installation.html) and that you already tried to run the [getting started demos](../../demos/getting_started/getting_started.html). + +### Getting ready + ++ Open an Anaconda Prompt + ++ Activate the FiberSim Anaconda Environment by executing: +``` +conda activate fibersim +``` ++ Change directory to `/code/FiberPy/FiberPy`, where `` is the directory where you installed FiberSim. + +### Run the test + ++ Type: + ``` +python Fiberpy.py run_batch "../../../testing_suite/thick_kinetics/mybpc/batch_c_kinetics.json" + ``` + ++ You should see text appearing in the terminal window, showing that the simulations are running. When it finishes (this can take ~20-30 minutes), you should see something similar to the image below. + +![command prompt](command_prompt_c.PNG) + +### Viewing the results + +The results and summary figure from the simulation are written to files in `/testing_suite/thick_kinetics/mybpc/sim_output` + + + +The `hs` folder contains the status files that were dumped at each time-step calculation. + +The `analysis` folder contains figure files showing the calculated rate laws for all mybpc transitions, as well as the model rate laws. + + + diff --git a/docs/pages/code_validation/mybpc/mybpc_kinetics.png b/docs/pages/code_validation/mybpc/mybpc_kinetics.png new file mode 100644 index 00000000..6ae2b6e4 Binary files /dev/null and b/docs/pages/code_validation/mybpc/mybpc_kinetics.png differ diff --git a/docs/pages/FiberCpp/testing_suite/kinetics_test/figures/sim_output_mybpc.PNG b/docs/pages/code_validation/mybpc/sim_output_mybpc.PNG similarity index 100% rename from docs/pages/FiberCpp/testing_suite/kinetics_test/figures/sim_output_mybpc.PNG rename to docs/pages/code_validation/mybpc/sim_output_mybpc.PNG diff --git a/docs/pages/FiberCpp/testing_suite/kinetics_test/figures/command_prompt_m.PNG b/docs/pages/code_validation/myosin/command_prompt_m.PNG similarity index 100% rename from docs/pages/FiberCpp/testing_suite/kinetics_test/figures/command_prompt_m.PNG rename to docs/pages/code_validation/myosin/command_prompt_m.PNG diff --git a/docs/pages/FiberCpp/testing_suite/kinetics_test/figures/iso_0_transition_0.png b/docs/pages/code_validation/myosin/iso_0_transition_0.png similarity index 100% rename from docs/pages/FiberCpp/testing_suite/kinetics_test/figures/iso_0_transition_0.png rename to docs/pages/code_validation/myosin/iso_0_transition_0.png diff --git a/docs/pages/FiberCpp/testing_suite/kinetics_test/figures/iso_0_transition_1.png b/docs/pages/code_validation/myosin/iso_0_transition_1.png similarity index 100% rename from docs/pages/FiberCpp/testing_suite/kinetics_test/figures/iso_0_transition_1.png rename to docs/pages/code_validation/myosin/iso_0_transition_1.png diff --git a/docs/pages/FiberCpp/testing_suite/kinetics_test/figures/iso_0_transition_2.png b/docs/pages/code_validation/myosin/iso_0_transition_2.png similarity index 100% rename from docs/pages/FiberCpp/testing_suite/kinetics_test/figures/iso_0_transition_2.png rename to docs/pages/code_validation/myosin/iso_0_transition_2.png diff --git a/docs/pages/FiberCpp/testing_suite/kinetics_test/figures/iso_0_transition_3.png b/docs/pages/code_validation/myosin/iso_0_transition_3.png similarity index 100% rename from docs/pages/FiberCpp/testing_suite/kinetics_test/figures/iso_0_transition_3.png rename to docs/pages/code_validation/myosin/iso_0_transition_3.png diff --git a/docs/pages/code_validation/myosin/myosin.md b/docs/pages/code_validation/myosin/myosin.md index 34cfe397..b382b3c6 100644 --- a/docs/pages/code_validation/myosin/myosin.md +++ b/docs/pages/code_validation/myosin/myosin.md @@ -6,3 +6,141 @@ nav_order: 3 --- # Myosin + +Thick filaments are composed of myosin and myosin-binding protein C. The kinetics scheme for both molecules is defined in the [model file](../../structures/model/model.html). + +The following test verifies myosin kinetics for the 3-state model schematized below. + +

+ +

+ +In this model, dimers of myosin heads (red) can transition together from the super-relaxed state (SRX) to the disordered-relaxed state (DRX). Then each myosin head is able to bind to an active binding site (blue) and transition to a force-generating state (FG). + +## What this test does + +The myosin kinetics test: + ++ Runs a simulations in which a half-sarcomere is held isometric and activated in a solution with a pCa of 4.5. + ++ Saves a status file at each time step, which contains the state of every myosin molecules. + ++ Assesses all the myosin transitions occuring between two consecutive time-steps, and calculates the apparent rate constants. + ++ Compares the calculated rate constants with those provided in the following model file (the transition parameters between each states are described in the `transition` blocks): + +``` +"m_kinetics": [ + { + "no_of_states": 3, + "max_no_of_transitions": 2, + "scheme": [ + { + "number": 1, + "type": "S", + "extension": 0, + "transition": [ + { + "new_state": 2, + "rate_type": "force_dependent", + "rate_parameters": [ + 100, + 100 + ] + } + ] + }, + { + "number": 2, + "type": "D", + "extension": 0, + "transition": [ + { + "new_state": 1, + "rate_type": "constant", + "rate_parameters": [ + 200 + ] + }, + { + "new_state": 3, + "rate_type": "gaussian", + "rate_parameters": [ + 200 + ] + } + ] + }, + { + "number": 3, + "type": "A", + "extension": 7.0, + "transition": [ + { + "new_state": 2, + "rate_type": "poly", + "rate_parameters": [ + 150, + 1, + 2 + ] + } + ] + } + ] + } + ] +``` + + +## Instructions + +Before proceeding, make sure that you have followed the [installation instructions](../../installation/installation.html) and that you already tried to run the [getting started demos](../../demos/getting_started/getting_started.html). + + +### Getting ready + ++ Open an Anaconda Prompt + ++ Activate the FiberSim Anaconda Environment by executing: +``` +conda activate fibersim +``` ++ Change directory to `/code/FiberPy/FiberPy`, where `` is the directory where you installed FiberSim. + +### Run the test + ++ Type: + ``` +python Fiberpy.py run_batch "../../../testing_suite/thick_kinetics/myosin/batch_m_kinetics.json" + ``` + ++ You should see text appearing in the terminal window, showing that the simulations are running. When it finishes (this can take ~20-30 minutes), you should see something similar to the image below. + +![command prompt](command_prompt_m.PNG) + +### Viewing the results + +The results and summary figure from the simulation are written to files in `/testing_suite/thick_kinetics/myosin/sim_output` + + + +The `hs` folder contains the status files that were dumped at each time-step calculation. + +The `analysis` folder contains figure files showing the calculated rate laws for all myosin transitions, as well as the model rate laws. + +Transition #0 (from state 1 to state 2) is force-dependent, and the transition rate is plotted as a function of the node force. + + + +Transition #1 (from state 2 to state 1) is constant. + + + +Transition #2 (from state 2 to state 3) is stretch-dependent, and the transition rate is plotted as a function of the stretch values. Furthermore, the attachement probabilities are modulated by the angle difference between a myosin head and the nearest binding sites. Each panel represents an angle difference interval and shows the calculated and theoretical attachment rates for the mid-interval angle difference. + + + +Transition #3 (from state 3 to state 2) is stretch-dependent, and the transition rate is plotted as a function of the stretch values. + + \ No newline at end of file diff --git a/docs/pages/code_validation/myosin/myosin_kinetics.png b/docs/pages/code_validation/myosin/myosin_kinetics.png new file mode 100644 index 00000000..51c30240 Binary files /dev/null and b/docs/pages/code_validation/myosin/myosin_kinetics.png differ diff --git a/docs/pages/FiberCpp/testing_suite/kinetics_test/figures/sim_output_myosin.PNG b/docs/pages/code_validation/myosin/sim_output_myosin.PNG similarity index 100% rename from docs/pages/FiberCpp/testing_suite/kinetics_test/figures/sim_output_myosin.PNG rename to docs/pages/code_validation/myosin/sim_output_myosin.PNG