# edinburgh-genome-foundry/dnachisel architecture

> Architecture diagram of the GitHub repository edinburgh-genome-foundry/dnachisel, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-03). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/edinburgh-genome-foundry/dnachisel
- Repository: https://github.com/edinburgh-genome-foundry/dnachisel

## Overview

DNA Chisel is a Python DNA-sequence optimizer, also usable from a CLI. Users define a sequence and constraints/objectives (directly or through annotated GenBank features), resolve constraint breaches, optimize objectives, then inspect or export the result. The graph shows the problem-solving stages, specification and evaluation layers, mutation representation, biological utilities, and reporting. Some subsystem links are documented by the README or SOURCE INDEX; unsampled implementation details are not inferred.

Main entry points: [`dnachisel/DnaOptimizationProblem/DnaOptimizationProblem.py`](https://github.com/edinburgh-genome-foundry/dnachisel/blob/master/dnachisel/DnaOptimizationProblem/DnaOptimizationProblem.py) (Optimization problem), [`dnachisel/builtin_specifications`](https://github.com/edinburgh-genome-foundry/dnachisel/tree/master/dnachisel/builtin_specifications) (Built-in specifications), [`dnachisel/cli.py`](https://github.com/edinburgh-genome-foundry/dnachisel/blob/master/dnachisel/cli.py) (Command-line interface), [`dnachisel/DnaOptimizationProblem/mixins/ConstraintsSolverMixin.py`](https://github.com/edinburgh-genome-foundry/dnachisel/blob/master/dnachisel/DnaOptimizationProblem/mixins/ConstraintsSolverMixin.py) (Constraint solver)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_problem["Problem solving"]
  node_problem["Optimization problem"]
  node_circular["Circular problem"]
  node_constraints["Constraint solver"]
  node_objectives["Objective optimizer"]
  node_mutation["Mutation space<br/>[MutationSpace.py]"]
  node_choice["Mutation choices<br/>[MutationChoice.py]"]
end

subgraph group_specs["Specifications"]
  node_specification["Specification model<br/>[Specification.py]"]
  node_builtin["Built-in specifications"]
  node_codon["Codon optimization"]
  node_patterns["Sequence patterns<br/>[SequencePattern.py]"]
  node_evaluation["Specification evaluation<br/>[SpecEvaluation.py]"]
  node_constraint_evals["Constraint evaluations"]
  node_objective_evals["Objective evaluations"]
end

subgraph group_sequence["Sequence tools"]
  node_location["Sequence locations<br/>[Location.py]"]
  node_biotools["Biological utilities"]
  node_record["GenBank records"]
end

subgraph group_interfaces["Interfaces and reports"]
  node_cli["Command-line interface<br/>[cli.py]"]
  node_genbank["Annotated GenBank input"]
  node_reports["Optimization reports"]
  node_report_translation["Specification annotations"]
end

node_user(("Sequence designer"))

node_user -->|"defines problem"| node_problem
node_user -->|"runs command"| node_cli
node_genbank -->|"supplies annotations"| node_cli
node_cli -.->|"processes record"| node_problem
node_problem -->|"resolves constraints"| node_constraints
node_problem -->|"optimizes objectives"| node_objectives
node_problem -->|"initializes mutation space"| node_mutation
node_mutation -->|"uses choices"| node_choice
node_constraints -->|"uses evaluations"| node_constraint_evals
node_objectives -->|"uses evaluations"| node_objective_evals
node_constraint_evals -.->|"groups results"| node_evaluation
node_objective_evals -.->|"groups results"| node_evaluation
node_builtin -->|"subclasses"| node_specification
node_codon -->|"extends model"| node_specification
node_builtin -->|"uses patterns"| node_patterns
node_builtin -->|"uses utilities"| node_biotools
node_patterns -->|"returns match locations"| node_location
node_problem -.->|"loads record input"| node_record
node_genbank -->|"is parsed as"| node_record
node_problem -->|"generates report"| node_reports
node_reports -->|"translates annotations"| node_report_translation
node_problem -.->|"supports circular problems"| node_circular

click node_cli "https://github.com/edinburgh-genome-foundry/dnachisel/blob/master/dnachisel/cli.py"
click node_problem "https://github.com/edinburgh-genome-foundry/dnachisel/blob/master/dnachisel/DnaOptimizationProblem/DnaOptimizationProblem.py"
click node_circular "https://github.com/edinburgh-genome-foundry/dnachisel/blob/master/dnachisel/DnaOptimizationProblem/CircularDnaOptimizationProblem.py"
click node_constraints "https://github.com/edinburgh-genome-foundry/dnachisel/blob/master/dnachisel/DnaOptimizationProblem/mixins/ConstraintsSolverMixin.py"
click node_objectives "https://github.com/edinburgh-genome-foundry/dnachisel/blob/master/dnachisel/DnaOptimizationProblem/mixins/ObjectivesMaximizerMixin.py"
click node_mutation "https://github.com/edinburgh-genome-foundry/dnachisel/blob/master/dnachisel/MutationSpace/MutationSpace.py"
click node_choice "https://github.com/edinburgh-genome-foundry/dnachisel/blob/master/dnachisel/MutationSpace/MutationChoice.py"
click node_specification "https://github.com/edinburgh-genome-foundry/dnachisel/blob/master/dnachisel/Specification/Specification.py"
click node_builtin "https://github.com/edinburgh-genome-foundry/dnachisel/tree/master/dnachisel/builtin_specifications"
click node_codon "https://github.com/edinburgh-genome-foundry/dnachisel/blob/master/dnachisel/builtin_specifications/codon_optimization/BaseCodonOptimizationClass.py"
click node_patterns "https://github.com/edinburgh-genome-foundry/dnachisel/blob/master/dnachisel/SequencePattern/SequencePattern.py"
click node_evaluation "https://github.com/edinburgh-genome-foundry/dnachisel/blob/master/dnachisel/Specification/SpecEvaluation/SpecEvaluation.py"
click node_constraint_evals "https://github.com/edinburgh-genome-foundry/dnachisel/blob/master/dnachisel/Specification/SpecEvaluation/ProblemConstraintsEvaluations.py"
click node_objective_evals "https://github.com/edinburgh-genome-foundry/dnachisel/blob/master/dnachisel/Specification/SpecEvaluation/ProblemObjectivesEvaluations.py"
click node_location "https://github.com/edinburgh-genome-foundry/dnachisel/blob/master/dnachisel/Location.py"
click node_biotools "https://github.com/edinburgh-genome-foundry/dnachisel/tree/master/dnachisel/biotools"
click node_record "https://github.com/edinburgh-genome-foundry/dnachisel/blob/master/dnachisel/biotools/genbank_operations.py"
click node_reports "https://github.com/edinburgh-genome-foundry/dnachisel/blob/master/dnachisel/reports/optimization_reports.py"
click node_report_translation "https://github.com/edinburgh-genome-foundry/dnachisel/blob/master/dnachisel/reports/SpecAnnotationsTranslator.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_problem,node_circular,node_constraints,node_objectives,node_mutation,node_choice toneBlue
class node_specification,node_builtin,node_codon,node_patterns,node_evaluation,node_constraint_evals,node_objective_evals toneAmber
class node_location,node_biotools,node_record toneMint
class node_cli,node_genbank,node_reports,node_report_translation toneRose
class node_user toneIndigo
```

## Components

### Problem solving

- [Optimization problem](https://github.com/edinburgh-genome-foundry/dnachisel/blob/master/dnachisel/DnaOptimizationProblem/DnaOptimizationProblem.py): `dnachisel/DnaOptimizationProblem/DnaOptimizationProblem.py`
- [Circular problem](https://github.com/edinburgh-genome-foundry/dnachisel/blob/master/dnachisel/DnaOptimizationProblem/CircularDnaOptimizationProblem.py): `dnachisel/DnaOptimizationProblem/CircularDnaOptimizationProblem.py`
- [Constraint solver](https://github.com/edinburgh-genome-foundry/dnachisel/blob/master/dnachisel/DnaOptimizationProblem/mixins/ConstraintsSolverMixin.py): `dnachisel/DnaOptimizationProblem/mixins/ConstraintsSolverMixin.py`
- [Objective optimizer](https://github.com/edinburgh-genome-foundry/dnachisel/blob/master/dnachisel/DnaOptimizationProblem/mixins/ObjectivesMaximizerMixin.py): `dnachisel/DnaOptimizationProblem/mixins/ObjectivesMaximizerMixin.py`
- [Mutation space](https://github.com/edinburgh-genome-foundry/dnachisel/blob/master/dnachisel/MutationSpace/MutationSpace.py): `dnachisel/MutationSpace/MutationSpace.py`
- [Mutation choices](https://github.com/edinburgh-genome-foundry/dnachisel/blob/master/dnachisel/MutationSpace/MutationChoice.py): `dnachisel/MutationSpace/MutationChoice.py`

### Specifications

- [Specification model](https://github.com/edinburgh-genome-foundry/dnachisel/blob/master/dnachisel/Specification/Specification.py): `dnachisel/Specification/Specification.py`
- [Built-in specifications](https://github.com/edinburgh-genome-foundry/dnachisel/tree/master/dnachisel/builtin_specifications): `dnachisel/builtin_specifications`
- [Codon optimization](https://github.com/edinburgh-genome-foundry/dnachisel/blob/master/dnachisel/builtin_specifications/codon_optimization/BaseCodonOptimizationClass.py): `dnachisel/builtin_specifications/codon_optimization/BaseCodonOptimizationClass.py`
- [Sequence patterns](https://github.com/edinburgh-genome-foundry/dnachisel/blob/master/dnachisel/SequencePattern/SequencePattern.py): `dnachisel/SequencePattern/SequencePattern.py`
- [Specification evaluation](https://github.com/edinburgh-genome-foundry/dnachisel/blob/master/dnachisel/Specification/SpecEvaluation/SpecEvaluation.py): `dnachisel/Specification/SpecEvaluation/SpecEvaluation.py`
- [Constraint evaluations](https://github.com/edinburgh-genome-foundry/dnachisel/blob/master/dnachisel/Specification/SpecEvaluation/ProblemConstraintsEvaluations.py): `dnachisel/Specification/SpecEvaluation/ProblemConstraintsEvaluations.py`
- [Objective evaluations](https://github.com/edinburgh-genome-foundry/dnachisel/blob/master/dnachisel/Specification/SpecEvaluation/ProblemObjectivesEvaluations.py): `dnachisel/Specification/SpecEvaluation/ProblemObjectivesEvaluations.py`

### Sequence tools

- [Sequence locations](https://github.com/edinburgh-genome-foundry/dnachisel/blob/master/dnachisel/Location.py): `dnachisel/Location.py`
- [Biological utilities](https://github.com/edinburgh-genome-foundry/dnachisel/tree/master/dnachisel/biotools): `dnachisel/biotools`
- [GenBank records](https://github.com/edinburgh-genome-foundry/dnachisel/blob/master/dnachisel/biotools/genbank_operations.py): `dnachisel/biotools/genbank_operations.py`

### Interfaces and reports

- [Command-line interface](https://github.com/edinburgh-genome-foundry/dnachisel/blob/master/dnachisel/cli.py): `dnachisel/cli.py`
- **Annotated GenBank input**
- [Optimization reports](https://github.com/edinburgh-genome-foundry/dnachisel/blob/master/dnachisel/reports/optimization_reports.py): `dnachisel/reports/optimization_reports.py`
- [Specification annotations](https://github.com/edinburgh-genome-foundry/dnachisel/blob/master/dnachisel/reports/SpecAnnotationsTranslator.py): `dnachisel/reports/SpecAnnotationsTranslator.py`

### Other components

- **Sequence designer**

## Connections

- Sequence designer → Optimization problem: defines problem
- Sequence designer → Command-line interface: runs command
- Annotated GenBank input → Command-line interface: supplies annotations
- Command-line interface → Optimization problem: processes record
- Optimization problem → Constraint solver: resolves constraints
- Optimization problem → Objective optimizer: optimizes objectives
- Optimization problem → Mutation space: initializes mutation space (evidence: `dnachisel/DnaOptimizationProblem/DnaOptimizationProblem.py`)
- Mutation space → Mutation choices: uses choices (evidence: `dnachisel/MutationSpace/MutationSpace.py`)
- Constraint solver → Constraint evaluations: uses evaluations (evidence: `dnachisel/DnaOptimizationProblem/mixins/ConstraintsSolverMixin.py`)
- Objective optimizer → Objective evaluations: uses evaluations (evidence: `dnachisel/DnaOptimizationProblem/mixins/ObjectivesMaximizerMixin.py`)
- Constraint evaluations → Specification evaluation: groups results
- Objective evaluations → Specification evaluation: groups results
- Built-in specifications → Specification model: subclasses (evidence: `dnachisel/builtin_specifications/AvoidHairpins.py`)
- Codon optimization → Specification model: extends model (evidence: `dnachisel/builtin_specifications/codon_optimization/BaseCodonOptimizationClass.py`)
- Built-in specifications → Sequence patterns: uses patterns (evidence: `dnachisel/builtin_specifications/AvoidPattern.py`)
- Built-in specifications → Biological utilities: uses utilities (evidence: `dnachisel/builtin_specifications/EnforceGCContent.py`)
- Sequence patterns → Sequence locations: returns match locations (evidence: `dnachisel/SequencePattern/SequencePattern.py`)
- Optimization problem → GenBank records: loads record input
- Annotated GenBank input → GenBank records: is parsed as
- Optimization problem → Optimization reports: generates report (evidence: `dnachisel/DnaOptimizationProblem/DnaOptimizationProblem.py`)
- Optimization reports → Specification annotations: translates annotations (evidence: `dnachisel/reports/optimization_reports.py`)
- Optimization problem → Circular problem: supports circular problems (evidence: `dnachisel/DnaOptimizationProblem/CircularDnaOptimizationProblem.py`)
