﻿Binomial

--- Natural Number Simulation for Complex Systems ---

    Complex Reaction System Laboratory
    
    Copyright (c) 2022 Takashi Sato
    
    This software is released under the MIT License. http://opensource.org/licenses/mit-license.php*/



Description

This programs provide a natural number simulation to explore complex reaction systems. The numbers in this calculation means molecular numbers, cell numbers, living individual numbers, etc. This program contains time evolution algorithm code for calculating those natural numbers. You can use this program instead of conventional ordinary differencial equations(OEDs). OEDs can deal with phenomenon of vourious numerical systems. The Number Simulation also can solve those numerical reaction systems based on random natural number by binomial probability. This program enables non-stop calculation, and simple usage by input file writing. Enjoy this smart simulator.


Categories

 complex system, system biorogy, A-life, simulation 


File structuer

 This program uses six python files and one input file as shown below.

    1. binomial_v014.py (main program)
        This is a main program. This contains reading process of a input file and 
        a main loop for calculation. 
    2. element_31.py
        The element class in this file defines elements in the input files. Elements
        are molecules or various cells or living individuals, and/or etc.
    3. reaction_42.py
        Classes in this file define several reactions for the elements in the input file.
    4. utility_41.py
         This program contains utilities for plotting process, file saving, time managing, and so on.
    5. setting_06.py
         This program contains utilities for input file setting.
    6. reactionManage_04.py  
           This file provides reaction process management codes.
    7. polymer_11.py
             Under constraction.

              
 The program is developed by Spyder IDE 5.1.5 on Ubuntu 22.04.1 LT, 20 January 2023.

  

Getting started

    You can run your program by  six dot(.)-py files above and one input file.
  The input file is writtn by plane text, which have .txt extension.
  The file should have four sections, *Time, *Element, *Reaction, and *Plot.
 Create one main project folder.
  Locate six dot(.)-py files in a program-file holder. The program-file holder locate in the main holder.
  make an another holder in the master holder to locate input files. (Look at "Folder structure.pdf")
      
   You need to change a input file name in the binomial_v014.py to run by Spyder.
  Running the binomial_v013.py, the calculation starts, and plots appeare in the plot window. 
  Test file explanation below is inp_immune_323.txt. Below show explanation of four sections;
  *Time, *Element, *Reaction, and *Plot. The ** in below example means comment line. 
   
    1. *Time
           You need to write start time, end time, 
         console-printout interval time, plot-out interval time, csv-file output interval time, and the unit. 
         You can only write natural numbers. 
         The zero, 0 is available in the line. Calculations executes by every one interval.
           
         Format:
           *Time
            start time, end time, console out interval, plot out interval, csv-file out interval, time unit
         
         Example:
           *Time, 
           ** start, end, console out, plot out, csv out, time unit
                  0, 14400, 1440, 14400, 1440,  min

    2. *Element
           You write element items you want to simulate. 
         You can set the element name, initial number, color for plotting and marker for plotting. 
          Markers are available as follows for example.
           ["o", "v", "^", "<", ">","1", "2", "3", "4", "8",  \
           "s", "p", "*", "h", "H", "+", "x", "D", "d", "|", "_"]
           You can omit color and marker.
           
         Format:
           *Element
            element name, initial number, plot color, plot marker
               --- --- --- 
               --- --- --- 

         Example:
           *Element
           ** 0:element name, 1:initial number, 2:plot color, 3:plot marker
           virus, 500, Black, 8
           cell, 100000, Green, s
           virusCell, 0, p
           macrophage, 5000, 
           macrophageActive, 0,
           macrophageWithVirus, 0, 
           dendricCell, 2000, Blue,  
           dendricMHC, 0, Red,  
           naiveTh1, 10000, Green
           activeTh1, 0, 
           IFN, 0, Blue
           IL-12, 0

    3. *Reaction
          You define reactions for elements above. 
        Many reaction types are available as below. 
        Reaction multi; rM defines a reaction concerned with many kind of elements.  

              r1_0 : One kind of element decreases its number.
              r1_1 : One kind of element change to anothor kind of element. 
              r1_2 : One kind of element separate to two kind of element.
              r1_3 : One kind of element separate to three kind of element.
              r2_1 : Two kinds of element react, and change to one element.
              r2_2 : Two kinds of element react, and change to two kinds of element.
              r2_3 : Two kinds of element react, and change to three kinds of element.
              r3_1 : Three kinds of element react, and change to one kind of element.
              r3_2 : Three kinds of element react, and change to two kinds of element.
              r3_3 : Three kinds of element react, and change to three kinds of element.
              rM   : Some kinds of element react, and change to another some kinds element. 
              r1_+ : One kind of element increases its number by linear. 
              r1_- : One kind of element decreases its number by linear.    
        
          All reaction definition need reaction elements and created elements,
        and the reaction order for the elements. 
        For example, if one kind of element A becomes two kinds of elements: X and Y. 
        Below statement shows one A becomes two X and three Y. 
        
                   r1_2, 001, 1, A, 0.5, 2, X, 3, Y
        
        The first term is reaction type.
        the second is a name for identification.
        The third term and the forth one, “1, A” is reaction order and the element name.
        The fifth one, 0.5 is a reaction probability parameter.
        The sixth and the seventh, “1, X" is reaction order and a generated element name.
        The eigth and the nineth, “1, Y" is reaction order and an another generated element name.
       
         Reaction order have to be a natural number. 
       Element name have to be defined in *Element. 
       
         The rM allows many kinds of elements in before and after in the reaction definition.  
       Three-line statement defines one reaction. An example is shown below.
       
            rM,   002,  1, A, 10, B, 10, C, 2, D, 100, E
                         1000
                        1, X, 1, Y, 10, Z, 3, W  
                        
       , where five kind of elements react, and create four kind of elements.
       The numbers before element name show reaction orders as like other reaction definitions. 
       The first line defines reacting elements. The third line defines as created elements. 
       You can describe many elements in line. The second line is the reaction probability parameter. 

         The *Reaction needs a global normalization parameter, if definitions of reactions contain r2_1, 
       r2_2, r2_3, r3_1, r3_2, r3_3, rM. 
       This parameter controls reaction probability through the algorithm.
       
         The reaction probability parameters and the global normalization parameter 
       can be real numbers. In the format as below, A, B, X, Y are element name
      defined in the *Element items. The pi stands for a probability parameter of
      each reaction. 

         Format:
          *Reaction, global normalization parameter
           r1_2, name, a, A, p1, x, X, y, Y
           r1_1, name, a, A, p2, x, X
           r1_0, name, a, A, p3
           r2_2, name, a, A, b, B, p4, x, X, y, Y
           r2_1, name, a, A, b, B, p5, x, X
           rM,   name, a, A, b, B, c, C, d, D, e, E, -------
                       p6
                       x, X, y, Y, z, Z, w, W, -------
           --- --- --- 
           --- --- --- 

         Example:
           *Reaction, 100000000
           r2_1, 001,  10, virus, 1, cell, 0.04, 1, virusCell
           r1_1, 002,   1, virusCell, 0.001, 100, virus
           r2_1, 003,   1, macrophage, 1, virus, 0.9, 1, macrophageWithVirus
           rM,   004,   1, macrophageWithVirus,  
                          0.9, 
                        1, macrophageWithVirus, 10, IFN, 10, IL-12
           r1_1, 005,   1, macrophageWithVirus, 0.1, 1, macrophage
           r2_1, 006,   1, virus, 1, dendricCell, 10, 1, dendricMHC
           rM,   007,   1, naiveTh1, 1, dendricMHC, 10, IFN, 10, IL-12
                        10000,
                        1, activeTh1, 1, dendricMHC
           r1_2, 013,   1, activeTh1, 1, 10, IFN, 1, activeTh1
           r2_1, 014,   1, macrophage, 2, IFN, 10, 1, macrophageActive 
           r2_1, 015,   1, macrophageActive, 10, virus, 1, 1, macrophageWithVirus
           r1_1, 018,   1, dendricMHC, 0.0002, 1, dendricCell
           r1_1, 019,   1, macrophageActive, 0.002, 1, macrophage
           r1_1, 020,   1, activeTh1, 0.001, 1, naiveTh1
           r1_0, 021,   1, IFN, 0.01
    
4. *Plot 
      This section defines plotting condition. 
      Elements written in the same line are shown in one figure. 
      The plot-type is linear or log.
     
         Format:
          *Plot, plot-type
           A, X, Y
           B, W
           F
           --- --- --- 
           --- --- ---          
    
        Example:
         *Plot
           virus, virusCell, macrophageWithVirus
           cell, virusCell
           macrophage, macrophageActive, macrophageWithVirus
           dendricMHC, dendricCell
           IFN, IL-12
           activeTh1, naiveTh1
         
         
Executing a program

    Two excuting processes are abailable.
  You needs two holders in a master holder at least. One holder contains the six program files.
  The other holder should contains input text files like as mentioned above Getting started.  
  (Look at "Folder structure.pdf")
  
     1. Spyder
        
          One executing method use spyder in anaconda3. Open the main file, binomial_v014.py from Spyder. 
         You should write input file name in the appropriate line as follows,
         
              fName = 'inp_test_031.txt'
         
         "Run file" command in Spyder executes the input file. Results files will be put
          in a new holder which is created in the input file holder.
          
     2. command line
     
           Preparing holders are same as for 1.Spyder case.
           Open a terminal, and change directory to the program files　located directory.
           you write a command line in a terminal as follows.
           
                  $ python binomial_v014.py inp_test_031.txt 
                  
              Return the line and the program starts.
              Result files will be located in a new created holder like as 1.spyder. 
       
             













