Adding in docs / demos

docs/pages/demos/demos.md

@@ -0,0 +1,45 @@
+---
+layout: default
+title: Demos
+has_children: True
+nav_order: 10
+---
+
+# Demos
+{:.no_toc}
+
+This section of the documentation demonstrates how to use FiberSim.
+
+A high-level overview is provided immediately below. The sub-pages provide examples that show how to:
+
++ simulate single trials
++ calculate force-pCa curves with optional step-length changes and/or k<sub>tr</sub> maneuvers
++ calculate force-velocity and force-power curves
++ compare models
++ simulate myofibrils composed of half-sarcomeres connected in series
++ run simulations with parameters selected from a defined parameter space
+
+## Note
+
+None of the simulations in the demonstrations have been fitted to data. They are designed to help people use the software and not intended to reproduce specific experimental results.
+
+# Overview
+
+The overarching strategy is to automate as much as possible.
+
+As shown below, users can run every demo on this site by launching FiberPy with the following files:
++ a model file
++ a setup file
++ an options file
+
+FiberPy handles everything else.
+
+The model file describes the properties of a *base* half-sarcomere and, in the case of myofibrils, how many of them are arranged in series.
+
+The setup file describes the experimental protocol (e.g. pCa levels, length-changes, loadeded shortening) and provides options for comparing simulations at different starting lengths, models with different parameters, etc.
+
+The options file provides fine control over the way FiberCpp runs simulations and, if desired, how FiberCpp will write status files to disk.
+
+The demos explain how to use most of FiberSim's current capabilities. If you want to try and use FiberSim to do something that is not documented, submit a request or contact us.
+
+<img src="images/FiberSim_workflow.png">

docs/pages/demos/pCa_curves/different_lengths/different_lengths.md

@@ -0,0 +1,88 @@
+---
+layout: default
+title: Different lengths
+has_children: false
+parent: pCa curves
+grand_parent: Demos
+nav_order: 2
+---
+
+# Single curve
+
+## Overview
+
+This demo shows how to simulate pCa curves at different lengths.
+
+## What this demo does
+
+This demo:
+
++ Builds on the [single pCa curve trial](../single_curve/single_curve.html) 
+and runs simulations in which a half-sarcomere is held at different lengths and subjected to a k<sub>tr</sub> maneuver at a range of pCa values
++ Analyses the data
++ Plots summaries of the simulation
+
+## Instructions
+
+If you need help with these step, check the [installation instructions](../../../installation/installation.html).
+
++ Open an Anaconda prompt
++ Activate the FiberSim environment
++ Change directory to `<FiberSim_repo>/code/FiberPy/FiberPy`
++ Run the command
+```
+ python FiberPy.py characterize "../../../demo_files/pCa_curves/different_lengths/base/setup.json"
+ ```
+
+### Viewing the results
+
+All of the results from the simulation are written to files in `<FiberSim_repo>/demo_files/pCa_curves/different_lengths/sim_data/sim_output`
+
+The file `superposed_traces.png` shows pCa, length, force per cross-sectional area (stress), and thick and thin filamnt properties plotted against time. The simulations at different lengths are plotted in different columns.
+
+<img src="images/superposed_traces.png" width="75%">
+
+Since the simulations included more than 1 pCa value, FiberPy created pCa curves `force_pCa.png`
+
+<img src="images/force_pCa.png" width="50%">
+
+and wrote summary data to `pCa_analysis.xlsx`
+
+<img src="images/excel_pCa.png" width="50%">
+
+Since the code simulated a k<sub>tr</sub> maneuver, FiberPy also created a figure showing the analyis of the tension recovery.
+
+<img src="images/k_tr_analysis.png" width="75%">
+
+and wrote summary data to `k_tr_analysis.xlsx`.
+
+<img src="images/excel_k_tr.png" width="50%">
+
+### How this worked
+
+The only difference between this simulation and the [single curve trial](../single_curve/single_curve.html) is that the three half-sarcomere lengths were specified in the characterization structure. If no length is specified, the simulations are based on the single length specified in the model file.
+
+````
+"characterization": [
+        {
+            "type": "pCa_length_control",
+            "relative_to": "this_file",
+            "sim_folder": "../sim_data",
+            "hs_lengths": [950, 1050, 1150],
+            "m_n": 9,
+            "pCa_values": [9, 6.5, 6.3, 6.1, 6.0, 5.9, 5.8, 5.7, 5.5, 4.5],
+            "sim_duration_s": 2.5,
+            "time_step_s": 0.001,
+            "pCa_step_up_s": 0.1,
+            "k_tr_start_s": 1.5,
+            "k_tr_duration_s": 0.02,
+            "k_tr_ramp_s": 0.001,
+            "k_tr_magnitude_nm": 100,
+            "k_tr_fit_time_s": [1.525, 2.45],
+            "output_image_formats": [ "png" ],
+            "figures_only": "False",
+            "trace_figures_on": "False"
+        }
+    ]
+````
+

docs/pages/demos/pCa_curves/pCa_curves.md

@@ -0,0 +1,10 @@
+---
+layout: default
+title: pCa curves
+has_children: true
+parent: Demos
+nav_order: 1
+---
+
+# pCa curves
+

docs/pages/demos/pCa_curves/single_curve/single_curve.md

@@ -0,0 +1,87 @@
+---
+layout: default
+title: Single curve
+has_children: false
+parent: pCa curves
+grand_parent: Demos
+nav_order: 1
+---
+
+# Single curve
+
+## Overview
+
+This demo shows how to simulate a pCa curve with information about  k_tr.
+
+## What this demo does
+
+This demo:
+
++ Builds on the [single k_tr trial](../../single_trials/k_tr/k_tr.html) demo and runs simulations in which a half-sarcomere is subjected to a k<sub>tr</sub> maneuver at a range of pCa values
++ Plots summaries of the simulation
+
+## Instructions
+
+If you need help with these step, check the [installation instructions](../../../installation/installation.html).
+
++ Open an Anaconda prompt
++ Activate the FiberSim environment
++ Change directory to `<FiberSim_repo>/code/FiberPy/FiberPy`
++ Run the command
+```
+ python FiberPy.py characterize "../../../demo_files/pCa_curves/single_curve/base/setup.json"
+ ```
+
+### Viewing the results
+
+**Important note - some of these traces, particularly at lower activation levels, are noisy. This is because the code is only simulating 9 thick filaments and there are not enough cross-bridge events at low levels of activation to obtain smooth averages. You can increase the `m_n` parameter in the set-up file to get smoother records but the simulations take longer to run and might be frustrating for a demo. Note that `m_n` must be a integer squared [4, 9, 16, 25, 36 ... with a maximum value of 196].** 
+
+All of the results from the simulation are written to files in `<FiberSim_repo>/demo_files/pCa_curves/single_curve/sim_data/sim_output`
+
+The file `superposed_traces.png` shows pCa, length, force per cross-sectional area (stress), and thick and thin filamnt properties plotted against time.
+
+<img src="images/superposed_traces.png" width="50%">
+
+Since the simulations included more than 1 pCa value, FiberPy created a pCa curve `force_pCa.png`
+
+<img src="images/force_pCa.png" width="50%">
+
+and wrote summary data to `pCa_analysis.xlsx`
+
+<img src="images/excel_pCa.png" width="50%">
+
+Since the code simulated a k<sub>tr</sub> maneuver, FiberPy also created a figure showing the analyis of the tension recovery.
+
+<img src="images/k_tr_analysis.png" width="50%">
+
+and wrote summary data to `k_tr_analysis.xlsx`.
+
+<img src="images/excel_k_tr.png" width="50%">
+
+### How this worked
+
+The only difference between this simulation and the [single k_tr trial](../../single_trials/k_tr/k_tr.html) is that the additional pCa values have been added between the brackets.
+
+````
+"characterization": [
+        {
+            "type": "pCa_length_control",
+            "relative_to": "this_file",
+            "sim_folder": "../sim_data",
+            "m_n": 9,
+            "pCa_values": [9, 6.5, 6.3, 6.1, 6.0, 5.9, 5.8, 5.7, 5.5, 4.5],
+            "sim_duration_s": 2.5,
+            "time_step_s": 0.001,
+            "pCa_step_up_s": 0.1,
+            "k_tr_start_s": 1.5,
+            "k_tr_duration_s": 0.02,
+            "k_tr_ramp_s": 0.001,
+            "k_tr_magnitude_nm": 100,
+            "k_tr_fit_time_s": [1.525, 2.45],
+            "output_image_formats": [ "png" ],
+            "figures_only": "False",
+            "trace_figures_on": "False"
+        }
+    ]
+````
+

docs/pages/demos/single_trials/isometric_activation/isometric_activation.md

@@ -0,0 +1,99 @@
+---
+layout: default
+title: Isometric activation
+has_children: false
+parent: Single trials
+grand_parent: Demos
+nav_order: 1
+---
+
+# Isometric activation
+
+## Overview
+
+This demo shows how to run a single isometric simulation.
+
+## What this demo does
+
+This demo:
+
++ Runs a single simulation in which a half-sarcomere is held isometric and activated in a solution with a pCa of 4.5
++ Plots a summary of the simulation
+
+## Instructions
+
+If you need help with these step, check the [installation instructions](../../../installation/installation.html).
+
++ Open an Anaconda prompt
++ Activate the FiberSim environment
++ Change directory to `<FiberSim_repo>/code/FiberPy/FiberPy`
++ Run the command
+```
+ python FiberPy.py characterize "../../../demo_files/single_trials/isometric_activation/base/setup.json"
+ ```
+
++ You should see text appearing in the terminal window, showing that the simulations are running. When it finishes (this may take a few minutes), you should see something similar to the image below.
+
+<img src="images/after_simulation.png" width="100%">
+
+### Viewing the results
+
+All of the results from the simulation are written to files in `<FiberSim_repo>/demo_files/single_trials/isometric_activation/sim_data/sim_output`
+
+The file `superposed_traces.png` shows pCa, length, force per cross-sectional area (stress), and thick and thin filamnt properties plotted against time.
+
+<img src="images/superposed_traces.png" width="50%">
+
+The myosin and myosin binding protein-C rates are shown in
+
+<img src="images/rates.png" width="50%">
+
+The result files are in `<FiberSim_repo>/demo_files/single_trials/isometric_activation/sim_data/sim_output/1`
+
+<img src="images/sim_output_1_directory.png" width="75%">
+
+### How this worked
+
+FiberPy ran a single simulation based on `setup.json`.
+
+````
+{
+  "FiberSim_setup":
+  {
+    "FiberCpp_exe": {
+      "relative_to": "this_file",
+      "exe_file": "../../../../bin/FiberCpp.exe"
+    },
+    "model": {
+      "relative_to": "this_file",
+      "options_file": "sim_options.json",
+      "model_files": ["model.json"]
+    },
+    "characterization": [
+        {
+            "type": "pCa_length_control",
+            "relative_to": "this_file",
+            "sim_folder": "../sim_data",
+            "m_n": 9,
+            "pCa_values": [4.5],
+            "sim_duration_s": 1,
+            "time_step_s": 0.001,
+            "output_image_formats": [ "png" ],
+            "figures_only": "False",
+            "trace_figures_on": "False"
+        }
+    ]
+  }
+}
+````
+
+The first section labeled `"FiberCpp_exe"` showed FiberPy where to find the main FiberCpp software. This demo can use relative paths because the demos are part of the repository.
+
+The next section, titled `"model"` shows where to find the base model and the simulation options.
+
+The last section says:
++ run a `pCa_length_control` simulation
++ write the data to the relative path `../sim_data`
++ run a simulation with 9 thick filaments (this number has to be an integer squared [16, 25, etc.] with bigger numbers taking longer but producing smoother traces)
++ the pCa is 4.5
++ the simulation is 1 s long with 1 ms resolution