================================================================================
SynCAD -- Synthetic Circuit Automated Design (Ver 1.)
================================================================================
SynCAD is an end-to-end automated pipeline that converts a Boolean logic
specification into a physically constructible linear DNA sequence for
expression in E. coli.
Starting from a Verilog file, the tool runs logic synthesis, assigns
characterised biological repressor gates, and assembles the final DNA
sequence -- all in one pipeline.
================================================================================
PIPELINE OVERVIEW
================================================================================
Verilog (.v)
|
v
table2logic.py <-- Yosys-based NOR/NAND logic synthesis
|
v
Synthesised .v + circuit diagram (.png)
|
v
logic2circuit.py <-- Hill-function biological gate assignment
|
v
Gate assignment results (.csv)
|
v
linear_DNA_sequence_from_circuits.py <-- Eugene rule-based DNA assembly
|
v
DNA sequences (.txt)
A Streamlit GUI (synCAD_ver1.py) integrates all three steps into a single
browser window.
================================================================================
REPOSITORY CONTENTS
================================================================================
table2logic.py Step 1 -- Yosys wrapper for logic synthesis
logic2circuit.py Step 2 -- Biological gate assignment
linear_DNA_sequence_from_circuits.py Step 3 -- Linear DNA sequence generation
synCAD_ver1.py Streamlit GUI (all three steps)
genetic_part_sequences.xlsx Built-in genetic parts database
Eco1C1G1T1_Eugene_device_rule.txt Eugene device-level ordering rules
Eco1C1G1T1_Eugene_gate_rule.txt Eugene gate-level ordering rules
SynCAD_guide.pdf Full user guide
================================================================================
REQUIREMENTS
================================================================================
- Python >= 3.9
- Yosys (must be on $PATH) https://yosyshq.net/yosys/
Install Python packages:
pip install streamlit pandas tqdm networkx matplotlib openpyxl
Verify Yosys:
yosys -V
================================================================================
QUICK START
================================================================================
GUI (recommended)
-----------------
streamlit run synCAD_ver1.py
Open http://localhost:8501, upload a Verilog file, set input levels,
and click [Run SynCAD].
Command line
------------
# Step 1 -- logic synthesis
python3 table2logic.py --input my_circuit.v --gate NOR
# Step 2 -- biological gate assignment
python3 logic2circuit.py \
-v output_my_circuit_NOR.v \
-i in1:0.01,1.0 in2:0.01,1.0 \
-k 3 --save-csv results.csv
# Step 3 -- DNA sequence generation
python3 linear_DNA_sequence_from_circuits.py \
--graph circuit_assigned.pkl \
--parts genetic_part_sequences.xlsx \
--gate-rule Eco1C1G1T1_Eugene_gate_rule.txt \
--device-rule Eco1C1G1T1_Eugene_device_rule.txt \
--output DNA_sequence_result.txt
================================================================================
STEP-BY-STEP REFERENCE
================================================================================
------------------------------------------------------------------------
Step 1 -- table2logic.py
------------------------------------------------------------------------
Wraps Yosys to synthesise a Verilog design using NOR and/or NAND gates.
Input: Verilog file. The top-level module MUST be named "example".
Example Verilog:
module example(input a, input b, output out);
assign out = ~(a | b);
endmodule
Usage:
python3 table2logic.py --input <FILE.v> [--gate NOR] [--gate NAND]
Flag Default Description
--------------- ----------- -------------------------------------------
--input / -i (required) Path to input Verilog file
--gate / -g NOR Gate type(s): NOR, NAND, OR, AND
Outputs:
output_{stem}_{GATES}.v synthesised gate-level Verilog
{stem}_{GATES}.png circuit diagram
------------------------------------------------------------------------
Step 2 -- logic2circuit.py
------------------------------------------------------------------------
Exhaustively searches all valid biological repressor gate assignments for
the synthesised circuit. Each assignment is scored by the worst-case
ON/OFF ratio using Hill-function kinetics.
Usage:
python3 logic2circuit.py \
-v <synthesised.v> \
-i name:low,high [name:low,high ...] \
[-k 3] [--quiet] [--save-csv <path>]
Flag Default Description
----------------- ----------- -------------------------------------------
--verilog / -v (required) Synthesised Verilog from Step 1
--inputs / -i (required) Input signal levels as name:low,high (REU)
--topk / -k 3 Number of top results to report
--quiet off Suppress progress bar
--save-csv none Save ranked results to CSV
Scoring:
score = min over outputs (
min(output | Boolean == TRUE) /
max(output | Boolean == FALSE)
)
A higher score means better separation between HIGH and LOW states.
Built-in gate library: 21 characterised repressor gates from the
Cello v2 Eco1C1G1T1 dataset. No two gates from the same gene family
can be assigned to the same circuit.
------------------------------------------------------------------------
Step 3 -- linear_DNA_sequence_from_circuits.py
------------------------------------------------------------------------
Assembles the final linear DNA sequence from a gate-assigned circuit
graph, applying Eugene compositional design rules to filter valid
part orderings.
Usage:
python3 linear_DNA_sequence_from_circuits.py \
--graph <circuit_assigned.pkl> \
--parts genetic_part_sequences.xlsx \
--gate-rule Eco1C1G1T1_Eugene_gate_rule.txt \
--device-rule Eco1C1G1T1_Eugene_device_rule.txt \
[--output DNA_sequence_result.txt]
Flag Default Description
--------------- ------------------------- --------------------------------
--graph (required) Gate-assigned NetworkX DiGraph
--parts (required) Genetic parts Excel workbook
--gate-rule (required) Eugene gate-level rule file
--device-rule (required) Eugene device-level rule file
--output DNA_sequence_result.txt Output file path
The input .pkl file must be a NetworkX DiGraph where each internal node
has 'RBS' and 'Repressor' node attributes (e.g. from Cello gate
assignment). Currently supports 3-4 inputs, 1 output.
================================================================================
BIOLOGICAL BACKGROUND
================================================================================
Genetic logic gates are implemented with transcription factor repressors
modelled by the Hill equation:
f(x) = y_min + (y_max - y_min) / (1 + (x/K)^n)
x input protein concentration (REU)
K repression threshold (REU)
n Hill coefficient (cooperativity)
y_min minimum expression level (REU)
y_max maximum expression level (REU)
Gate parameters are sourced from the Cello v2 Eco1C1G1T1 characterisation
dataset.
================================================================================
GRAPHICAL INTERFACE
================================================================================
streamlit run synCAD_ver1.py
-> http://localhost:8501
The GUI has three sections:
1. Input design
Upload Verilog, select gates, set input signal ranges.
2. Run Steps 1 & 2
One-click logic synthesis + gate assignment.
Download synthesised Verilog, circuit diagram, and results CSV.
3. DNA Sequence Generation (optional)
Upload circuit graph (.pkl) + Eugene rule files.
Download final DNA sequences.
================================================================================
TROUBLESHOOTING
================================================================================
Problem Fix
------------------------------ ------------------------------------------------
Logic synthesis fails Yosys not on $PATH, or top module != "example"
Gate assignment: no results Input low == high, or too many gates for the
available gene families
DNA generation fails .pkl nodes missing RBS/Repressor attributes,
or unsupported input/output count
================================================================================
ACKNOWLEDGEMENTS
================================================================================
This program was developed with reference to CelloCAD
(https://github.com/CIDARLAB/cello), a genetic circuit design automation
tool developed by the CIDAR Lab at Boston University.
================================================================================
AUTHOR
================================================================================
Euijin Seo
ufoooo1391@postech.ac.kr
POSTECH