A Typical Workflow to Simulate Cytoskeletal Systems

Abstract

Many cytoskeletal systems are now sufficiently well known to permit their precise quantitative modeling. Microtubule and actin filaments are well characterized, and the associated proteins are often known, as well as their abundance and the interactions between these elements. Thus, computer simulations can be used to investigate the collective behavior of the system precisely, in a way that is complementary to experiments. Cytosim is an Open Source cytoskeleton simulation suite designed to handle large systems of flexible filaments with associated proteins such as molecular motors. It also offers the possibility to simulate passive crosslinkers, diffusible crosslinkers, nucleators, cutters, and discrete versions of the motors that only step on unoccupied lattice sites on a filament. Other objects complement the filaments by offering spherical or more complicated geometry that can be used to represent chromosomes, the nucleus, or vesicles in the cell.

Cytosim offers simple command-line tools for running a simulation and displaying its results, which are versatile and do not require programming skills. In this workflow, step-by-step instructions are given to i) install the necessary environment on a new computer, ii) configure Cytosim to simulate the contraction of a 2D actomyosin network, and iii) produce a visual representation of the system. Next, the system is probed by systematically varying a key parameter: the number of crosslinkers. Finally, the visual representation of the system is complemented by the numerical quantification of contractility to view, in a graph, how contractility depends on the composition of the system. Overall, these different steps constitute a typical workflow that can be applied with few modifications to tackle many other problems in the cytoskeletal field.

Introduction

The cytoskeleton consists of filaments within the cell and associated molecules such as molecular motors, which often constitute a dynamic meshwork with remarkable mechanical properties. The cytoskeleton exists in various configurations in different cell types across nearly all life forms. Its correct functioning is essential for fundamental cellular processes such as division, motility, and polarization. It also governs cell-to-cell mechanical interactions, thereby influencing the morphogenesis of tissues and organisms. The cytoskeleton underlies several functions and manifests itself in many biological processes. For example, the contraction of muscles is linked to the power stroke of myosin molecular motors on actin filaments. Another example is the maintenance of neurons, which relies on the movements of kinesin motors along microtubules located inside the axons of these neurons. Actin and microtubules are two preeminent types of cytoskeletal filaments, and without them, life as we know it would be impossible.

The cytoskeleton is essentially a biomechanical system, which cannot be reduced solely to its chemistry. Microtubules or actin filaments are built from thousands of monomers and extend over several micrometers. The conformations of these filaments in space and the forces that they can transmit to the plasma membrane, the nucleus, or other organelles are key aspects of their role in the cell. For example, a network of actin filaments and myosin motors, called the actomyosin cortex¹, generates forces to sustain cell motility and morphological changes in animal cells. A very different arrangement is seen in plant cells, where cortical microtubules direct the deposition of cellulose fibrils, thereby controlling the cell wall architecture, which ultimately determines how these cells will grow in the future².

While mechanics clearly play a substantial part in cytoskeletal operations, chemistry is equally important. Filaments grow via a self-assembly process whereby monomers find their docking site at the tip of the filament after diffusing through the cytoplasm³. At the molecular scale, assembly and disassembly at the tip of the filaments are, thus, determined by molecular affinities⁴. Similarly, proteins of the cytoskeleton diffuse, and binding and unbinding rates determine their affinity for the filaments they encounter. In the case of molecular motors, cycles of chemical reactions involving ATP hydrolysis are linked to movements along the filaments and, possibly, forces that accompany them⁵. Remarkably, the cytoskeleton offers many unusual challenges and a large variety of processes involving similar components. It is a rich playground at the interface between biology, chemistry, and physics.

Cytoskeletal systems are amenable to mathematical modeling. In fact, thanks to excellent research done in the past decades, the principal molecular constituents are most likely already identified, as illustrated with endocytosis⁶. In model organisms, such as yeast, the properties of these elements are known, as well as the system composition for some of their processes. For instance, the structure and material properties of microtubules⁷, as well as their number and average lengths at various stages of the mitotic spindle, have been described⁸. The number of kinesins that connect microtubules into a coherent mechanical structure is often known⁹. The speeds of many motors have been measured in vitro¹⁰. In addition, experimentalists can observe and quantify these systems in vivo under wild-type or mutated conditions. Combining theory alongside in vivo and in vitro experiments enables researchers to test whether the current knowledge about a cytoskeletal system is sufficient to explain its observed behavior. The use of mathematical and computational tools also allows us to make inferences of how components work collectively on the basis of assumptions derived from observations at the molecular scale, usually in simplified situations (e.g., single-molecule experiments).

The role of theory can be illustrated using a practical example: the beating of cilia. This beating is due to the movement of dynein motors along microtubules in the cilia. One may ask what determines the speed of the dynein motor in this system. One possible answer is that the maximum speed is constrained by the requirement to maintain a certain beating pattern. This would be understandable if the beating was under natural selection. In that case, if motors moved quicker, then the process would lose its desired qualities-the cilia would not beat as efficiently or even fail altogether. Although this is possible, a second alternative is that some intrinsic factor could limit dynein's speed.

For example, the cell may not have enough ATP to make dynein faster, or the protein movements required for dynein's activity just could not be accelerated. In that case, if the motors could be made faster despite the physical limits, the beating would be improved. A third possibility, of course, is that changing the speed does not affect the process significantly, which might be advantageous to the organism by providing some "robustness" against uncontrollable factors. Amongst these three possibilities, one can identify the correct one by calculating the beating pattern from dynein's properties. Indeed, a suitable mathematical model should predict how the beating pattern is affected by varying dynein's speed and is not subject to the limits that exist in the physical world. Naturally, the validity of the model must be verified, but even "incorrect" models can generate interesting ideas.

The model can take the form of an analytical framework or be a numerical simulation of the system. Either way, the gap between the molecular scale and the functional scale remains an obstacle, and developing these models is not a straightforward task, since several mechanical and chemical processes need to be integrated into the equations describing the biological system. Theory comes in various forms, offering different tradeoffs between simplicity and realism. Increasing the degree of details in a model is not always advantageous as it may limit our ability to solve the equations or, in other words, to derive the predictions of the theory. The same tradeoff exists for simulations. The modelers will have to select the ingredients of the system to be considered while ignoring certain aspects. These key decisions will depend strongly on the objective of the study. Nowadays, the extraordinary improvements in computer hardware make it possible to simulate many cytoskeletal systems with enough details over a sufficient time to analyze their comportment. This will often generate unexpected ideas and novel directions in research. For example, simulations similar to the ones that will be used in this protocol led to a back-of-the-envelope calculation that can predict the contractility of a network based on its composition¹¹.

Numerical methods are ubiquitous in engineering and physical sciences, and their use in biology is growing. Today, virtually all our technological whatchamacallit (watches, phones, cars, and computers) has been first conceived on a computer, and powerful software exist to do this. Given a well-characterized cytoskeletal system and assuming that an appropriate level of description has been determined, several issues must still be solved before it can be simulated. For the simplest problems, the most appropriate route of action might be to write a simulation "by coding from scratch", in other words, starting with a generic programming language or a mathematical platform such as MATLAB. This has the advantage that the author of the code will have an intimate knowledge of what has been implemented and knows exactly how the software works. This route is, however, not without risk, and it is not uncommon to witness doctoral students spending most of their working time writing code rather than addressing scientific questions.

The alternative is to use software conceived by others, but this is not without risks either; any large source code tends to spontaneously acquire the traits of an impenetrable black box, despite the most admirable efforts of their authors to prevent it. Using black boxes is surely not a scientist's dream. A large source code can also become a liability, and it may be quicker to start from scratch than to modify an existing code base to make it do something different. To mitigate this problem, one can always invite the authors of the software to help, but this may not be sufficient. Frequently, there is a difference of scientific culture between the authors of the software and the people that would like to use it, which means that many implicit assumptions need to be clarified. By making the code Open Source, it is expected that more people will be involved in the development of the software and to maintain its documentation, thus improving its quality. All these are important issues that must be given proper consideration before any investment is made. Nevertheless, the only way to progress in the long term is to promote solid software solutions, used and maintained by a broad community with common scientific interests.

Although this protocol uses Cytosim, there are other Open Source tools that might be able to simulate the same system, for example, AFINES¹², MEDYAN¹³, CyLaKS¹⁴, aLENS¹⁵, and AKYT¹⁶, to name a few. Unfortunately, comparing these projects is beyond the scope of the article. Here, step-by-step instructions are given to simulate a contractile 2D actomyosin network. This system is simple and makes use of the better-established capacities of Cytosim. Cytosim is built around a cross-platform core engine that can run simulations in 2D or 3D. It has a modular code base, making it easily customizable to perform particular tasks. Cytosim is equally stable and efficient in 3D and has been successfully used in the past to investigate diverse problems involving microtubules and actin filaments: the association of two asters of microtubules¹⁷, the movement of nuclei in the cells^18,19, endocytosis⁶, cytokinesis²⁰, the formation of the mitotic spindle²¹, the movements of the mitotic spindle²², the capture of chromosomes²³, the contraction of actomyosin networks^11,24, and the mechanics of the microtubule ring in blood platelets²⁵, and the capacities developed for these projects have been maintained in the code. The workflow described here can be adapted to many other problems. It makes use of the Unix command line, which may be unfamiliar to some readers. Using the command line is, however, the most portable and convenient way to automate the process of running simulations. Integrated graphical user interfaces aim to offer easy, intuitive access to a software, but this often comes at the expense of generality. The objective of this article is to illustrate an approach that can easily be modified or adapted to other problems. Notes are provided to explain the meaning of the commands.

To simulate an actomyosin network, filaments are modeled as oriented lines and represented by vertices distributed along their length (Figure 1). This is an intermediate level of description, common in polymer physics, that ignores the genuine 3D nature of the filaments but allows the bending to be calculated. Filaments may grow and shrink at their ends, following different models that cover both actin and microtubule phenomenology. In cells, filaments are organized primarily through interactions that constrain their motion, for example, the attachment to other filaments or simply confinement within the cell. In Cytosim, all such interactions are linearized and combined in a large matrix²⁶. The equations describing the motion of all filament vertices are derived from this matrix, assuming a viscous medium and random fluctuating terms representing Brownian motion. These equations are solved numerically to obtain the motion of the filaments together with all the forces acting on them in a self-consistent and efficient manner²⁶. Superimposed on this mechanical engine, there is a stochastic engine that simulates discrete events, such as the attachments and detachments of molecular motors or the assembly dynamics of filaments. In summary, Cytosim first uses simulated dynamics to calculate the mechanics of a network of filaments, connected in any arbitrary manner, and, second, stochastic methods to simulate the binding, unbinding, and diffusion of proteins that connect or affect the filaments.

The workflow illustrated here was frequently followed to initially explore a system using Cytosim. The critical step for many potential users is likely to be the installation of the software components. Distributing the software as a source code fulfills the imperatives of Open Science, but it is prone to errors since the developers of the software have access to only a limited pool of architecture to test the program. Compilation may fail as operating systems differ. The instructions provided here are likely to become obsolete as computer systems and source codes evolve. Thus, periodically checking the latest instructions online is essential. In case of trouble, it is highly encouraged that users report back by posting on the relevant feedback channel (currently Cytosim's homepage on Gitlab) to help fix the problem.

Protocol

NOTE: The protocol consists of these steps: platform preparation for Windows 10, MacOS, and Linux; the installation of Cytosim; configuration of the simulation and test run and the graphical display; multiple runs, varying a parameter: the number of crosslinkers in the network; generating a graph to view how contractility is affected by the number of crosslinkers; parallel runs; and random sampling. All text following a ">" are commands that are to be entered verbatim in the terminal window. The ">" represents the terminal prompt and must not be included, but all other characters are important.

1. Platform preparation

NOTE: Depending on the OS (MacOS, Windows 10, or Linux), follow step 1.1, step 1.2, or step 1.3.

1. Preparation (MacOS)
   1. Install Xcode Command Line Tools by opening the Terminal (in Applications/Utilities), and enter:
      gt; xcode-select --install
   2. To view or edit Cytosim's code, install Xcode from the Apple App Store (https://apps.apple.com/us/app/Xcode/id497799835?mt=12).
      NOTE: Xcode's built-in editor is perfectly suitable. Other code-oriented editors would also work, for example, TextMate. For using TextMate, download and follow instructions from https://macromates.com.
2. Preparation (Windows)
   NOTE: For Windows 10 or higher, Cytosim can run using the "Windows Subsystem for Linux" (WSL), as described below. An alternative for an older version is Cygwin, but instructions are not provided here.
   1. Update the computer operating system to fulfill the requirements for WSL 2: Windows 10 version 1903 or higher, with Build 18362 or higher, for x64 systems and Version 2004 or higher, with Build 19041 or higher, for ARM64 systems. For subsequent version updates, check https://docs.microsoft.com/en-us/windows/release-health/release-information.
   2. Type Turn Windows features on and off in the search box of the taskbar. Manually enable () Virtual Machine Platform and () Windows Subsystem for Linux. Click OK and restart Windows.
   3. Go to Windows Microsoft Store and search for Ubuntu. Download and install the current release (Ubuntu 20.04 LTS as of 03.2022)
   4. Click Launch to start the Ubuntu Terminal. If asked to download the latest WSL2 Linux Kernel, proceed by following the instructions that will be provided. Install the update and relaunch Ubuntu.
   5. Follow the terminal instructions to Enter new UNIX username and set a password. Once the user account is set up, launch Ubuntu from the search box of the Windows task bar. Open the home directory (aka "."), from the command window:
      > explorer.exe .
   6. Install a WSL-compatible X-Window server, for example, Xming: https://sourceforge.net/projects/xming/
   7. Start the X-Window server, Xming by double-clicking on the Xming icon; select Multiple Windows. Hereafter, open the Ubuntu terminal and follow step 1.3 (Linux).
3. Preparation (Linux)
   NOTE: These instructions are appropriate for Linux distributions that use the APT package manager. These commands must be modified for distributions such as Red Hat Linux that use a different package manager. In this case, follow the instructions of the Linux distribution to install the same packages.
   1. Update the Linux system:
      > sudo apt-get update
      > sudo apt-get upgrade
   2. Install a C++ compiler and GNU's make (https://www.gnu.org/software/make):
      > sudo apt-get install build-essential
   3. Install BLAS/LAPACK Libraries (http://www.netlib.org/lapack):
      > sudo apt-get install libblas-dev liblapack-dev
   4. Install OpenGL developer library and header files (https://www.mesa3d.org):
      > sudo apt-get install mesa-common-dev
   5. Install the GLEW library (http://glew.sourceforge.net):
      > sudo apt-get install libglew-dev
   6. Install the freeGLUT library (http://freeglut.sourceforge.net):
      > sudo apt-get install freeglut3-dev
   7. Install the GIT version control system (https://git-scm.com):
      > sudo apt-get install git
   8. Install the X11 tests programs (e.g., xeyes, xclock, xcalc):
      > sudo apt-get install x11-apps
   9. Adjust the environment variable DISPLAY:
      > export DISPLAY=:0
      1. Try to open a X11 window:
         > xeyes
      2. If this works, proceed to step 2. If the error is failed to open the display, try a different DISPLAY value.
      3. Find the IP address of the WSL2 machine:
         > cat /etc/resolv.conf
      4. If the IP number appears, e.g., "nameserver 10.16.0.7", use this IP number instead of X.X.X.X below:
         > export DISPLAY= X.X.X.X:0
         > xeyes
      5. If this works, proceed to step 2. If "play" fails to "open the display", try to run it from within an "xterm" window:
         > sudo apt install xterm
         > xterm -display :0
      6. In the new window that opens, type:
         > xeyes

2. Installation of Cytosim

NOTE: These steps are similar for any OS: MacOS, WSL, and Linux. In the following section, commands will be issued in the terminal, and the "current working directory" should be set to the directory in which the simulation was compiled. This directory will be referred to as being the base directory. Alternatively, everything can be done in a separate directory if files are copied as needed. If unfamiliar with the command line, consider following a tutorial, for example, https://www.learnenough.com/command-line-tutorial or https://learnpythonthehardway.org/book/appendixa.html.

1. Download Cytosim source code:
   > git clone https://gitlab.com/f-nedelec/cytosim.git cytosim
   NOTE: A Gitlab account is not necessary to download the code. This should create a new subdirectory "cytosim" in the current directory.
2. Compile:
   > cd cytosim
   > make
   1. Check that three files are created in a subdirector "bin" by running:
      > ls bin
   2. If step 2.2.1 fails, try this alternative method to compile by installing cmake (https://cmake.org):
      > mkdir b
      > cd b
      > cmake ..
      > make
      > cd ..
3. Check executables:
   > bin/sim info
   > bin/play info
   1. Verify that both executables have been compiled to perform 2D simulations. Look for the following output of the "info" queries above:
      Dimension: 2 Periodic: 1 Precision: 8 bytes
   2. If this is not the case, and only then, modify the file "src/math/dim.h" (open, edit to change DIM to 2, save) and recompile Cytosim:
      > make clean
      > make
4. Test run
   1. Copy three executables:
      > cp bin/sim sim
      > cp bin/play play
      > cp bin/report report
   2. Create a new directory:
      > mkdir run
   3. Copy and rename the standard configuration file:
      > cp cym/fiber.cym run/config.cym
   4. Start the simulation:
      > cd run
      > ../sim
   5. Visualize the results of the simulation:
      > ../play
      1. Press the space bar to animate. Press h for help on keyboard shortcuts.
      2. To quit the program, on MacOS try -Q, or CTRL-Q, or select Quit from the menu. As a last resort, enter CTRL-C in the terminal window from which "play" was started.
   6. Run in live mode:
      > ../play live

3. Configuration of the simulation

1. Install a code-oriented text editor (e.g., TextMate, SublimeText) if not already available.
   Open the editor and open the file "config.cym", located in the "run" directory created in step 2.4.2. Become familiar with the different sections of the configuration file, which is a copy of "fiber.cym" (Supplementary File 1).
   NOTE: Cytosim usually only reads one configuration file ending with ".cym". All modifications will be made here to "config.cym". See Supplementary Table S1 for a list of parameters.
2. Modify the simulation by making the following changes to "config.cym":
   radius=5 → radius=3
   new 1 filament → new 100 filament
3. Save the file without changing its name or location (overwrite "config.cym"). Switch to the Terminal Window, and check that the simulation is modified as expected with:
   > ../play live
   NOTE: The radius of the circle is specified in micrometers (µm), as are all distances in Cytosim. Cytosim follows a system of units adapted to the scale of the cell, derived from micrometers, piconewtons, and seconds.
4. In the paragraph "set fiber filament", make the following changes:
   rigidity=20 → rigidity=0.1
   segmentation= 0.5 → segmentation=0.2
   confine=inside, 200, cell → confine= inside, 10, cell
   In the paragraph "new filament", change:
   length=12 → length=2
   Reduce the time to be simulated by changing:
   run 5000 system → run 1000 system
   NOTE: This adjusts the filament's properties. The paragraph "set" defines persistent properties of the filaments, while parameters in "new" are usually initial conditions. The bending rigidity is specified in pN µm². The segmentation is the approximate distance between the vertices describing the filaments in micrometers (µm). It needs to be reduced if filaments are made more flexible. The last change reduces the stiffness (pN/µm) of the confinement potential associated with the "cell" edges. The length declared in the "new" paragraph (2 µm) is the initial length of the filaments, and since in this model the filaments are not dynamic, their lengths will not change. It is a recommended to sign the configuration file, by editing the first line:
   ​% Your name, date, place
   1. Check the validity of the configuration file (repeat step 3.3).
5. Create passive connectors.
   1. Add a new paragraph to "config.cym", before the lines with the "new" and "run" command, to define a molecular activity with affinity to the filaments:
      set hand binder {
      binding_rate = 10
      binding_range = 0.01
      unbinding_rate = 0.2
      }
   2. To define bifunctional entities, add another paragraph just below:
      set couple crosslinker {
      hand1 = binder
      hand2 = binder
      stiffness = 100
      diffusion = 10
      }
   3. Add a "new" command after the previous paragraphs and before the "run" command:
      new 1000 crosslinker
      NOTE: In Cytosim, rates are specified in units of s⁻¹ and the range in micrometers (µm). The stiffness is specified in units of piconewtons per micrometer (pN/µm) and the diffusion coefficient in micrometers squared per second (µm²/s). The order of the commands in the configuration file is important, and these paragraphs must appear before any "run" command, otherwise they will not be effective. To learn more about Cytosim's objects, follow the tutorial in "tuto_introduction.md", which is in a subfolder "doc" of the base directory: doc/tutorials/.
6. Create bifunctional motors.
   1. Add a new paragraph to "config.cym", before the lines with the "new" and "run" command:
      set hand motor {
      binding_rate = 10
      binding_range = 0.01
      unbinding_rate = 0.2
      activity = move
      unloaded_speed = 1
      stall_force = 3
      }
   2. Add another paragraph, following the previous one:
      set couple complex {
      hand1 = motor
      hand2 = motor
      stiffness = 100
      diffusion = 10
      ​}
   3. Add a "new" command after the previous paragraphs and before the "run" command:
      new 200 complex
      NOTE: The "activity = move" specifies a motor that moves continuously over the filament. The motor obeys a linear force-velocity curve (Figure 1) characterized by the unloaded speed (µm/s) and the stall force (piconewton). At each time-step, τ, it moves by a distance, v × τ. Using "activity = none" would specify a molecule that does not move, and since this is the default activity, one could simply omit "activity" altogether. Other activities are possible, for example, "activity = walk" would specify a motor with discrete steps along the filament. The "unloaded_speed" is positive for a plus-end directed motor. Specifying a negative value would make the motor move toward the minus-ends. This is further explained in Cytosim's first tutorial (see link in step 3.5.2).
7. Save the file.
   Check the simulation:
   > ../play live
   Run the simulation:
   > ../sim
   Visualize the results:
   > ../play
   Copy the final configuration file to the base directory:
   > cp config.cym ../config.cym
   NOTE: Your final file should be similar to Supplementary File 2 ("jove.cym"). Note how much time was needed to compute this simulation. In the following sections, this time will be multiplied by the number of simulations made to generate a graph where a parameter is varied.

4. Parameter sweep

NOTE: In this section, the number of crosslinkers in the network is systematically varied.

1. Import Python scripts.
   1. Create a subdirectory "byn", inside the base directory:
       > mkdir byn
   2. Copy three scripts from the standard Cytosim distribution:
      > cp python/run/preconfig.py byn/preconfig
      > cp python/look/scan.py byn/.
      > cp python/look/make_page.py byn/.
      NOTE: For safety, copies of these files are provided as Supplementary File 3, Supplementary File 4, and Supplementary File 5 with this article.
2. Make the files executable:
   > chmod +x byn/preconfig
   > chmod +x byn/scan.py
   > chmod +x byn/make_page.py
   1. Check that the scripts execute correctly:
      > byn/preconfig help
      > byn/scan.py help
      > byn/make_page.py help
      ​NOTE: This should print a description of how each command can be used. It is possible to modify the PATH variable to call the scripts more simply; see https://en.wikipedia.org/wiki/PATH_(variable).
   2. Troubleshooting
      1. If the error is "command not found", check the path specified, which should correspond to the location of the file. If there is another type of error because the OS does not provide python2, edit the three .py files and modify the shebang, which is the first line of each file (just add "3"):
         #!/usr/bin/env python → #!/usr/bin/env python3
3. Copy the configuration file to make it a "template" (Supplementary File 6):
   > cp config.cym config.cym.tpl
4. Edit the template configuration file. In the code editor, open the file "config.cym.tpl", located in the base directory. Change one line to introduce a variable text element:
   new 1000 crosslinker → new [[range(0,4000,100)]] crosslinker
   NOTE: Preconfig will recognize the code contained in the double brackets and replace it with a value obtained by executing this code in Python. In Python "range(X,Y,S)" specifies integers from X to Y, with an increment of S; in this case [0, 100, 200, 300, ... 4000]. The intent is to change the number of crosslinkers added to the simulation.
5. Generate config files from the template:
   > byn/preconfig run%04i/config.cym config.cym.tpl
   NOTE: This should create 40 files, one for each value specified in "range(0,4000,100)". The names of the files to be generated by Preconfig are specified by "run%04i/config.cym". With this specific code, Preconfig will generate "run0000/config.cym", "run0001/config.cym", etc. It will actually make the directories "run0000", "run0001", etc., and create a file "config.cym" in each of them. Check Preconfig's help for more details (run "byn/preconfig help"). In case of error, check that the command is typed exactly. Every character counts.
6. Run all simulations sequentially:
   > byn/scan.py '../sim' run????
   ​NOTE: The program "scan.py" will execute the quoted command in the list of directories provided. In this case, this list of directories is specified by "run????". The question mark is a wild card that matches any one character. Hence, "run????" matches any name starting with "run" and followed by exactly four characters. Alternatively, one could use "run*" to generate the same list, since "*" matches any string.
   1. In case of problems, execute this command from a new terminal window to run "sim" sequentially into all the directories created in step 4.5. Wait for approximately 30 min for the process to complete, but this depends very much on the computer capacities. Reduce the amount of calculation requested by editing "config.cym":
      run 1000 system → run 500 system
7. Visualize some simulations:
   > ./play run0010
   > ./play run0020
8. Generate images for all simulations:
   > byn/scan.py '../play image size=256 frame=10' run????
9. Generate an HTML summary page:
   > byn/make_page.py tile=5 run????
   1. Open "page.html" in a web browser.

5. Making a graph

NOTE: In this section, a plot is made from the results of the parameter sweep.

1. Check the report executable:
   > cd run
   > ../report network:size
   ​NOTE: For each frame in the trajectory, this will print some comments and two numbers, corresponding to "polymer" and "surface". Only the network "surface" (last column) will be used.
   1. Specifically restrict the information to one frame using:
      > ../report network:size frame=10
   2. Remove comments to make the output easier to process:
      > ../report network:size frame=10 verbose=0
   3. Finally, redirect the output to a file using the Unix pipe facility (">"):
      > ../report network:size frame=10 verbose=0 > net.txt
   4. Print the content of the file to terminal for verification:
      > cat net.txt
      NOTE: This should print two numbers. The second one is the surface covered by the network in the 10th frame. To execute the same operation in all "run" directories, change directory:
      > cd ..
2. Generate a report in each simulation subdirectory:
   > byn/scan.py '../report network:size frame=10 verbose=0 > net.txt' run????
   NOTE: Again, scan.py will execute the quoted command in all directories specified by "run????". The command is the last one tried in step 5.1. This will generate a file "net.txt" in every directory (try "ls run????").
3. Examine these numbers:
   ​> byn/scan.py 'cat net.txt' run????
   1. Add the "+" option to concatenate the name of the directory and the command's output:
      > byn/scan.py + 'cat net.txt' run????
4. Collect these numbers into a file:
   > byn/scan.py + 'cat net.txt' run???? > results.txt
5. Clean the file "results.txt" by deleting the repeated text that is not numeric. Open "result.txt" in the code editor, and use the "replace text" to remove all "run" strings. Remove only three letters, and keep the numbers; "run0000" should become "0000".
   NOTE: This should leave a file with only numbers organized in three columns.
6. Generate a contractility plot from the data in "result.txt". Use any method to generate a plot using column 1 for X and column 3 for Y. Label the X-axis as number of crosslinkers/100. Label the Y-axis as surface (micrometer^2).
7. Store all simulations in a separate directory:
   > mkdir save1
   > mv run???? save1

6. Alternative method for making a graph

1. Add a report command at the end of "config.cym.tpl" on a new line after the closing "}" of the run command:
   report network:size net.txt { verbose = 0 }
2. Generate config files:
   > byn/preconfig run%04i/config.cym config.cym.tpl
3. Run all simulations using parallel threads:
   > byn/scan.py '../sim' run???? njobs=4
   1. Adjust the number of jobs (njobs=4), depending on the computer's capacity. Monitor the usage of the CPU resources, for example, by the Activity Monitor App on MacOS.
4. Collect the data:
   > byn/scan.py + 'cat net.txt' run???? > results.txt
5. Make a plot, same as in steps 5.5 and 5.6.
6. Store all the previous runs in a separate directory:
   > mkdir save2
   > mv run???? save2

7. Improved plot using random sampling

NOTE: A variable is sampled here using a generator function from the "random" module of Python.

1. In the code editor, open the template configuration file "config.cym.tpl", located in the base directory. Add two lines, just before the "new crosslinker":
   [[num = int(random.uniform(0,4000))]]
   %[[num]] xlinkers
   Also change the "new" command to use this variable:
   new [[range(0,4000,100)]] crosslinker → new [[num]] crosslinker
   NOTE: The first line creates a random variable "num". The second line prints the parameter value. The "%" character is important since it will instruct Cytosim to skip the line. Soon "xlinkers" will serve as a recognizable tag, and it must appear only once in each file.
   1. At the very end of "config.cym.tpl", ensure that there is a report instruction:
      report network:size net.txt { verbose = 0 }
2. Generate config files:
   > byn/preconfig run%04i/config.cym 42 config.cym.tpl
   NOTE: This should generate 42 files. This number can be increased if the computer is fast enough. The values generated randomly can be seen by using the Unix tool "grep" to search files:
   > grep xlinkers run????/config.cym
3. Run all simulations in parallel:
   > byn/scan.py '../sim' run???? njobs=4
   NOTE: Adjust the number of jobs to the computer's capacity. For the best results, the variable "njobs" should be set equal to the number of cores of the computer.
4. Collect the data using a single command:
   > byn/scan.py + 'grep xlinkers config.cym; cat net.txt' run???? > results.txt
   NOTE: The "+" option of scan.py will concatenate all the output of the command to a single line. In this case, the command is actually composed of two commands separated by a semi-column (";"). Data collection can always be automated with a Python script.
5. Clean the file. Open "result.txt" in the code editor. To ensure that all the data corresponding to one simulation are contained in one line, delete all occurrences of the string "xlinkers" and remove the "%" characters at the start of each line. Finally, save "result.txt", which should be neatly organized in three columns of numeric values.
6. Make a graph to plot the data by repeating step 5.6, but label the X-axis as number of crosslinkers
7. Save the dataset into a new subdirectory:
   >mkdir set1
   > mv run???? set1/.
   > mv results.txt set1/.
8. Calculate another dataset by repeating steps 7.2-7.6, and then repeat step 7.8, replacing "set1" by "set2" in all three commands.
9. Make a combined plot.
   1. Concatenate the two data files:
      > cat set?/results.txt > results.txt
      NOTE: The new "result.txt" should be larger.
   2. Plot data to make a combined graph, as described in step 7.7.

8. Fully automated pipeline

NOTE: In this part, all operations requiring manual intervention are replaced by commands. When this is done, it will be possible to write a single script that performs all the steps automatically. This script can be run on a remote computer such as a compute farm.

1. Use the Unix "sed" command to "clean" the results.txt file, replacing step 7.6.
   1. Remove the "%" at the beginning of lines:
      > sed -e 's/%//g' results.txt > tmp.txt
   2. Remove "xlinkers":
      > sed -e 's/xlinkers//g' tmp.txt > results.txt
2. Write a script to call all the commands successively in the right order.
   1. Use different languages: bash or Python.
   2. Create a file "pipeline.bash", and copy all the commands needed to run the pipeline.
   3. Execute the script:
      > bash pipeline.bash
3. Use an automated plotting script.
   NOTE: It can be advantageous to remove all manual intervention. Many tools exist to generate a PDF plot directly from a data file, for example, gnuplot (http://www.gnuplot.info), PyX (https://pyx-project.org), or Seplot (https://pypi.org/project/seplot/).

Representative Results

In section 2, successful compilation of Cytosim using "make" should produce sim, play, and report in the subdirectory "bin". The output of step 2.3 ("sim info") should indicate "Dimension: 2" among other things. In section 3,the configuration file should be similar to jove.cym, provided as Supplementary File 1. In section 4,images obtained in step 4.8 from simulations should be similar to the one shown in Figure 2. The HTML summary page obtained in step 4.9 is shown in Figure 3. In section 5 and section 6, expected plots are shown in Figure 4. For section 7, representative plots are shown in Figure 5.

Figure 1: Modeling assumptions and the development of a network simulation. Left: some of Cytosim's modeling assumptions. Filaments are represented by line segments of identical length joined to account for bending elasticity. Connectors are composed of two units (a, b) linked together by a Hookean spring. Units can bind to filaments that are within their binding range ε, with a prescribed binding rate k_on. They unbind spontaneously at a rate k_off or upon reaching the end of the filaments. Connectors made of two units can connect two filaments. These units can represent different activities. In this work, "binders" are passive elements that bind/unbind without moving, and "motors" actively move along filaments. They move toward the plus ends of the filament, and the force opposed to this movement affects the speed of translocation, following the equation shown on the figure. The speed v of the motors obeys a linear force-velocity curve, characterized by the unloaded speed v₀ (µm/s) and the stall force f₀ (pN). Any opposing force f would reduce the speed of the movement. Right: Network simulation developed in this protocol. Black lines represent the filaments. Tiny green and orange dots represent the motor and the crosslinkers. Please click here to view a larger version of this figure.

Figure 2: Graphical representation of the networks. Three different systems are represented here at the same time (t = 5 s). The three simulations (left, center, right) contain the same amount of motors (green) but different amounts of crosslinkers (orange) and contract at different rates, as can be seen from the area reached after 5 s, which is different on every panel. Please click here to view a larger version of this figure.

Figure 3: HTML page to access simulation results. Example of the HTML page as generated in section 4.8. The page presents images, here all at the same time point (t = 100 s), and links to non-image files. The system's composition can be accessed by clicking on the "config.cym" link located above each simulation, which should open the parameter file corresponding to each run. The file is contained in the directory as indicated in black above each image. Please click here to view a larger version of this figure.

Figure 4: Contraction plot from regular parameter sampling. This plot is obtained in protocol step 5 and step 6. The number of crosslinkers in the system is varied regularly (X-axis). The resulting contractility (Y-axis) is obtained directly from the coordinates of the vertices describing the filaments (see protocol step 5.1). A maximum of contractility is obtained with ~1,000 crosslinkers. Please click here to view a larger version of this figure.

Figure 5: Contraction plot from randomized sampling of the parameter. This type of plot is obtained in protocol step 7. The plot is as described in Figure 4, but points are randomly distributed along the X-axis. Please click here to view a larger version of this figure.

Supplementary Table S1: Description of the parameters used in the simulation. Please click here to download this Table.

Supplementary File 1: fiber.cym. Configuration file used to start protocol step 3. Please click here to download this File.

Supplementary File 2: jove.cym. Configuration file (obtained at the end of protocol step 3). Please click here to download this File.

Supplementary File 3: preconfig. Versatile file generator. Please click here to download this File.

Supplementary File 4: scan.py. Python script to execute command in subdirectories. Please click here to download this File.

Supplementary File 5: make_page.py. Python script to generate HTML summary pages. Please click here to download this File.

Supplementary File 6: config.cym.tpl. Template configuration file (protocol step 4). Please click here to download this File.

Discussion

The method outlined in this article relies on three small and independent Python programs, which were used in diverse ways throughout the described protocol. The first script preconfig is a versatile tool that can replace the need for writing custom Python scripts²⁷. It is used to generate multiple configuration files from a single template file, specifying which parameter should be varied and how it should be varied. To vary multiple parameters, one can simply add more code snippets into the template file, and preconfig will generate all the possible combinations. One advantage of the template method is that all the information about the variations (which parameters are varied and how) is contained in a single file, with a minimal amount of code. The script "scan.py" is also versatile and is used to execute commands into subdirectories. Finally, "make_page.py" produces an HTML page to view the results of multiple simulations side-by-side. This takes advantage of the fact that browsers have been highly optimized to display panels of images. This script becomes particularly useful when multiple graphs are made (e.g., using scan.py) in the simulation subdirectories. There are many alternatives to the approach described here, and some programmers script in bash or prefer to write C programs to perform these tasks. Python, however, offers the advantage of a clean and modern syntax, and upon interpretation, Python scripts often work "out of the box" on modern architecture, including most high-performance clusters. The most significant drawback is that, since Python is constantly evolving, it is possible that these scripts may malfunction in a different version of Python. It is important here, as well, to use the latest versions and report any troublesome issues.

Varying a parameter is a standard approach to determine the influence that this parameter may have on a system. This technique requires setting a range over which to perform the variations. This range should be chosen according to what is believed to be realistic in vivo. When this is not known, physical or numerical considerations can help narrow down the choice. For example, if the total simulation time is T, then it is probably futile to probe rates (R) corresponding to exceedingly rare events, such that R × T << 1. In general, multiple parameters are varied, and the different ranges can be refined iteratively. Upon examination of the previous results, one may choose a region of parameter space where interesting transitions are occurring. It is essential to quantify such occurrences using a metric consisting of a few numerical values (ideally one) to characterize the behavior of the system. In the case of the actomyosin network, a natural choice was to estimate the surface of the network after a fixed amount of "simulated time" (achieved at frame 10) to monitor the contractility of the system. Given that the network is homogeneous and covers a disc, the surface S covered by the network was estimated from the filament's P vertice positions x_i:

with the center of mass

This choice was justified previously^11,24. Finding a good metric that is simple, robust, and biologically relevant impacts the entire study. This calculation is done by Cytosim's report "network:size" command and is, thus, the quantity plotted on the Y-axis of all graphs. Implementing new report calculations requires only basic knowledge of C++ and Cytosim's code structure. Occasionally, it can be more convenient to use a Python script to calculate a metric from quantities exported by Cytosim, particularly if a python module already does part of the job.

Sweeping a parameter using random variables (protocol section 6) offers several advantages compared to a regular variation (protocol section 3). First, it does not require one to decide how many values will be sampled. In fact, at any time, more points can be added to the dataset. Similarly, missing data points will be unnoticed, which is not the case for regular variations. Large computing clusters are not always reliable, and the failure of a computer node may result in the loss of some data points. With regular sampling, one must identify and reschedule the missing jobs and wait for their completion. The random sampling strategy avoids this issue. More importantly, perhaps, random sampling avoids the inadvertent introduction of correlation when multiple parameters are varied. For example, if a parameter X is varied with factors 1, 2, 4, 8, etc., and a second parameter Y is also varied in the same way, then their ratio is varied in a more limited way. In other words, a regular grid in high dimensions can have many levels of hidden symmetries, for example, diagonals. With random sampling, any combination of parameters is also a random variable, and thus, no apriorism is hidden in the sampling strategy. Another advantage is that random sampling permits the data to be split easily into pools of equivalent sizes, and thus, variations can be estimated with a bootstrapping method, a posteriori. The method also has some drawbacks. Random sampling requires more simulations to cover a certain area of parameter space with the same precision compared to regular sampling, because its points are not regularly spaced. Some amount of computation is wasted when two simulations are performed with nearly identical parameter values. Another shortcoming of random sampling is that, even with a high sampling rate, some areas of the parameter space will remain unexplored. It is also more difficult to plot variations over two parameters, such as a surface embedded in 3D or a color-coded 2D area, but this can still be done. Plots showing variation against only one parameter, however, are easy to make and offer more insights than equivalent plots obtained with regular sampling, because they include noise in all directions (compare Figure 4 and Figure 5).

The 2D actomyosin network can be calculated rapidly. It uses ubiquitous elements of the cytoskeleton: filaments, molecular motors, and crosslinkers. Cytosim can simulate many other systems, and different components can be included simply by adding extra commands to the configuration file. It is often possible to directly copy-paste from the many examples provided with the source code, which illustrate different classes of objects present in cells, for example, microtubules, centrosomes, the nucleus. There are, of course, limitations to the degree of complexity that can be handled by the software/hardware combination and the investigator. Overly complex systems require longer calculation times and are hard to explore numerically. However, nature offers us plenty of relatively small cytoskeletal systems for which the current software-hardware combination is sufficient. The field is still in its infancy, and, while the future looks bright and open, the challenges are enormous, and teams should be working together to develop the best software solutions. There are few alternatives to using computers outside bench work when it comes to analyzing complex systems like the ones found in living cells. There are, however, many ways to use computers with this aim, and Cytosim only represents one possible approach. Cytosim has been in constant development for the past 20 years, and, although it is already a large-scale project, many aspects of the cytoskeleton are not covered. Yet, it has been used by many groups independently of its authors, and the resulting publications^{28,29,30,31,32,33,34,35,36,37} are a clear testimony that the existing capabilities are sufficient for many research projects. These capabilities were often expended independently of Cytosim's main authors, which testifies that the code is modular and sufficiently clearly organized to permit this.

Materials

Name	Company	Catalog Number	Comments
A personal computer			MacOS, Windows 10 or Linux
config.cym.tpl			template configuration file; https://gitlab.com/f-nedelec/cytosim.git
jove.cym			Cytosim configuration file
make_page.py			Python script; https://github.com/nedelec/make_page.py
preconfig			Python script; https://github.com/nedelec/preconfig
scan.py			Python script; https://github.com/nedelec/scan.py