TORCphysics 0.0.1

A physics-based simulation platform of supercoiling-mediated regulation of gene expression.

TORCphysics: A Physical Model of DNA-Topology-Controlled Gene Expression

---

TORCphysics is a physics-based simulation framework to model gene expression regulated through DNA supercoiling. It simulates interactions between DNA-binding proteins such as RNA polymerases and topoisomerases, capturing both physical DNA properties and dynamics.

Transcription is modeled based on the twin-supercoiling domain model, and the simulation supports supercoiling-sensitive and non-sensitive promoters, as well as multi-stage binding kinetics. Outputs include transcription rates and time-series data, enabling direct comparisons with experimental results or kinetics inference via parameter search.

---

📦 Installation

Latest version from PyPI:

pip install torcphysics

TORCphysics paper version for reproducing results:

pip install git+https://github.com/Victor-93/TORCphysics.git@TORCphysics_paper

---

🚀 Quick Start

TORCphysics can be used from the command line or directly in Python scripts.

Each simulation requires four interconnected input files:

environment, sites and enzymes.

• The Environment input is composed by the DNA-binding molecules that have the capacity of binding particular DNA sites such as promoters or protein binding sites.
• Sites represent the binding sites of particular molecules, for example, RNA polymerases can bind gene start sites (promoters), while proteins bind their indicated binding sites.
• Enzymes correspond to the bound molecules (e.g., enzymes and proteins) to the DNA at the start of the simulation.
• Circuit input represents overall information about the simulated system, such as size, open (linear, .e.g., chromosomal) or closed (circular e.g., plasmid) structure, and the initial superhelical density.

Input	Description
circuit.csv	General information of gene circuit, such as open (linear, .e.g., chromosomal) or closed (circular e.g., plasmid) structure,and the initial superhelical density.. (Required)
environment.csv	List of DNA-binding molecules (e.g., RNAPs, topoisomerases, NAPs), that can bind particular DNA sites such as promoters or protein binding sites.
sites.csv	List of binding sites on the DNA (e.g., promoters, protein binding sites).
enzymes.csv	Initial state: DNA-bound molecules present at the beginning of the simulation.

⚠️ Inputs warnings
The only required input to run a simulation is circuit.csv. However, if sites.csv is not provided, molecules from the environment will not bind to the DNA. If environment.csv is missing, no molecules will bind to the sites. Lastly, if enzymes.csv is not provided, the simulation will start without any pre-bound molecules, but it will still run without issues.

---

🖥️ Command-Line Usage

Run a simulation with command:

TORCphysics -c circuit.csv -s sites.csv -e enzymes.csv -n environment.csv -o out -f 3000 -t 1.0 -r

This will simulate:

• 3000 frames with 1.0 second time step of the system described by the csv files.
• Outputs will be saved as dataframes and log files with prefix "out".

For more information type:

TORCphysics --help

---

🐍 Scripting Usage

TORCphysics can also be used via Python scripting for custom simulations:

from TORCphysics import Circuit

my_circuit = Circuit(
    circuit_filename="circuit.csv",
    sites_filename="sites.csv",
    enzymes_filename="enzymes.csv",
    environment_filename="environment.csv",
    output_prefix="out",
    frames=3000,
    series=True,
    continuation=False,
    dt=1.0
)

my_circuit.print_general_information()
my_circuit.run()

---

📚 Examples

Example files and Jupyter notebooks are available in the Examples/ directory:

• Example_1.ipynb — Single gene simulations and analysis.
• Example_2.ipynb — Multiple simulations with statistical analysis.
• Example_3.ipynb — Defining custom enzyme/site models using built-in models.

---

⚙️ Algorithms

Detailed documentation and algorithmic explanations coming soon on the Wiki

---

📖 Citation

If you use TORCphysics in your research, please cite the paper below:

TORCphysics paper coming soon!

---

📬 Contact

Questions or collaborations?

📧 [e-mail]

---

🔓 License

This project is licensed under the GNU General Public License v3.0 (GPLv3).
See the LICENSE file for more details.