updated qubo_lab / readme: basic steps

README.md

@@ -18,6 +18,17 @@ pipenv shell
 ~~~
 aktiviert werden.
 
+## Kompilieren
+Führen sie folgende Anweisungen aus, um die notwendigen libraries zu kompilieren.
+
+~~~bash
+qubo_lab/SconsLocal/scons.py -C ./qubo_lab/ --init
+~~~
+
+~~~bash
+./qubo_lab/SconsLocal/scons.py -C ./qubo_lab/
+~~~
+
 ## Datenbanken einrichten
 Es werden zwei Datenbanken benötigt, eine MySQL und eine MongoDB Datenbank. In der MongoDB Datenbank werden Objekte wie SAT-Instanzen, QUBOS, oder D-Wave SampleSets gespeichert. Die MySQL Datenbank wird dazu verwendet, um Daten aus diesen Objekten zu extrahieren und diese anschließend zu untersuchen. Damit die Datenbanken genutzt werden können muss im Hauptverzeichnis ein File namens **database.config** angelegt werden, welches folgende Struktur aufzuweisen hat.
 
@@ -39,6 +50,9 @@ database = ...
 
 Bei **[INSTANCE_POOL]** handelt es sich um die MongoDB Datenbank und bei **[EXPERIMENT_DB]** um die MySQL Datenbank.
 
+## Verbindung zum D-Wave Solver
+Der Zugriff auf einen D-Wave Solver setzt ein **dwave.config** file im Hauptverzeichnis voraus. Weitere Informationen hierzu finden sie in der offiziellen [Dokumentation](https://docs.ocean.dwavesys.com/projects/cloud-client/en/latest/index.html) des D-Wave Cloud Clients :
+
 ## Datensatz generieren
 Ein k-SAT-Instanzen Datensatz mit einer fixer  Klauselanzahl und logistisch verteilen Variablenanzahlen kann mit folgendem Python script erzeugt werden. Rufen sie hierzu einfach den interaktiven Modus von Python auf
 
@@ -69,4 +83,219 @@ pool = rip.create_random_logistic_pool(logistic_variable_distr_params, 250, inst
 for instance in pool:
 	instacne_id = script.write_instance_to_pool_db(instance_db, instance)
 	script.add_instance_to_experiment_scope(instance_db, "scope_name", instacne_id)
-~~~
+~~~
+
+## Daten über k-SAT-Instanzen extrahieren
+
+Für die spätere Analyse werden Daten über die k-SAT-Instanzen extrahiert und in einer Tabelle der MySQL Datenbank gespeichert.
+
+Legen Sie hierfür folgende Tabelle an.
+~~~sql
+CREATE TABLE `instances` (
+  `instance_id` char(24) NOT NULL DEFAULT '',
+  `number_of_clauses` int(11) DEFAULT NULL,
+  `number_of_variables` int(11) DEFAULT NULL,
+  PRIMARY KEY (`instance_id`)
+) ENGINE=InnoDB DEFAULT CHARSET=latin1;
+~~~
+
+Anschließend können sie mit diesem Python code extrahiert werden.
+
+~~~python
+from qubo_lab.util import script
+
+instance_db = script.connect_to_instance_pool()
+
+script.extract_instance_parameters()
+~~~
+Sie werden nun nach einigen dingen gefragt, folgende Tabelle erklärt die Bedeutungen der Abfragen:
+
+Abfrage| Erklärung
+----------|---------------
+scope: | Name des Experiment-Scopes (**scope_name**)
+table name: | Name der gerade erstellten Tabelle ("instances")
+
+## Minisat ausführen
+Als nächstes muss der Minisat Solver auf dem gerade generierten Datensatz gelaufen lassen werden.
+Hierzu führen sie vom Hauptverzeichnis
+~~~bash
+./qubo_lab/build/release/runMinisat
+~~~
+aus. Wenn sie nach dem Datenbanken Konfigurationsfile gefragt werden, geben sie das oben beschriebene **database.config** file an. Als "Experiment scope" geben sie den **scope_name** aus dem Abschnitt *Datensatz generieren* an.
+Anschließend müssen die Ergebnisse des Minisat Solvers extrahiert werden. Hierfür muss eine Tabelle in der Experiment Datenbank angelegt werden:
+
+~~~sql
+CREATE TABLE `minisat_runs` (
+  `run_id` char(24) NOT NULL DEFAULT '',
+  `instance_id` char(24) DEFAULT NULL,
+  `satisfiable` tinyint(1) DEFAULT NULL,
+  PRIMARY KEY (`run_id`)
+) ENGINE=InnoDB DEFAULT CHARSET=latin1;
+~~~
+
+Ist diese Tabelle angelegt, können die Ergebnisse extrahiert werden führen sie hierzu folgenden Python code aus.
+
+~~~python
+from qubo_lab.util import data_extraction
+
+data_extraction.extract_minisat_results()
+~~~
+Sie werden nun nach einigen dingen gefragt, folgende Tabelle erklärt die Bedeutungen der Abfragen:
+
+Abfrage| Erklärung
+----------|---------------
+scope: | Name des Experiment-Scopes (**scope_name**)
+table name: | Name der gerade erstellten Tabelle ("minisat_runs")
+
+## SAT < WMIS Reduktion
+Zuerst müssen die QUBOs dieser Reduktion erstellt und in der MongoDB Datenbank abgespeichert werden, was durch folgenden Python code erledigt wird.
+
+~~~python
+from qubo_lab.util import script
+
+instance_db = script.connect_to_instance_pool()
+
+script.create_wmis_qubos_for_scope(instance_db, "scope_name")
+~~~
+
+Im nächsten Schritt müssen die erzeugten QUBOs auf dem Hardwaregraphen des D-Wave Solvers eingebettet werden.
+
+~~~python
+from qubo_lab.util import script
+from qubo_lab.util import queries
+from qubo_lab.util import graph
+from dwave.system.samplers import DWaveSampler
+
+instance_db = script.connect_to_instance_pool()
+
+solver_graph = graph.create_qpu_solver_nxgraph(DWaveSampler().solver)
+
+qubos = queries.Qubo_scope_query(instance_db, "wmis_qubos")
+qubos.query("scope_name")
+
+script.find_embeddings_for_scope(instance_db, solver_graph, qubos)
+~~~
+
+Führen sie (**find_embeddings_for_scope(...)**) solange aus bis alle für alle qubos ein Embedding gefunden wurde. Sollte dies nicht möglich sein, sind die QUBOs zu groß für den Hardwaregraphen.
+Nun können die QUBOs dem D-Wave Solver übergeben werden. Führen sie hierzu das script
+~~~bash
+./qubo_lab/run_sampler_on_scope.py
+~~~
+aus. Folgende Tabelle erklärt wieder die Abfragen des scripts:
+
+Abfrage | Erklärung
+--------- |--------------
+choose mode: | wählen Sie hier **qpu** um den D-Wave Solver auszuwählen
+ising/qubo collection: | die collection in der die QUBOs gespeichert sind ("wmis_qubos")
+scope: | der oben angelegte Experiment-Scope ("scope_name")
+annealing time (in us): | die Annealzeit des D-Wave Solvers pro Sample
+number of reads per instance: | die Anzahl der Sample pro Instanz
+qubo_negation: | wählen Sie hier **false** - die QUBOs müssen nicht negiert werden
+save as run (numbered): | die Nummer des Durchlaufs
+
+
+Nachdem der D-Wave Sovler alle Instanzen bearbeitet hat,  muss zunächst wieder eine Tabelle erstellt werden,
+
+~~~sql
+CREATE TABLE `wmis_qpu_results` (
+  `result_id` char(24) NOT NULL DEFAULT '',
+  `run` int(11) DEFAULT NULL,
+  `instance_id` char(24) DEFAULT NULL,
+  `number_of_found_assignments` int(11) DEFAULT NULL,
+  `chain_break_fraction` float DEFAULT NULL,
+  `num_occurrences` int(11) DEFAULT NULL,
+  `energy` float DEFAULT NULL,
+  `satisfiable` tinyint(1) DEFAULT NULL,
+  `anneal_time` int(11) DEFAULT NULL,
+  `energy_reach` int(11) DEFAULT NULL,
+  `sample_size` int(11) DEFAULT NULL,
+  PRIMARY KEY (`result_id`)
+) ENGINE=InnoDB DEFAULT CHARSET=latin1;
+~~~
+
+um anschließend daten aus den Ergebnissen des D-Wave Solvers zu extrahieren:
+
+~~~python
+from qubo_lab.util import script
+
+instance_db = script.connect_to_instance_pool()
+
+script.extract_wmis_qpu_results()
+~~~
+
+Abfrage| Erklärung
+----------|---------------
+scope: | Name des Experiment-Scopes (**scope_name**)
+result collection: | "wmis_qubos"
+table name: | Name der gerade erstellten Tabelle ("wmis_qpu_results")
+
+## Variablenhauptstrang Methode
+Zuerst müssen wieder die QUBOs der Variablenhauptstrang Methode erstellt werden.
+
+~~~python
+from qubo_lab.util import script
+
+instance_db = script.connect_to_instance_pool()
+
+script.create_wmis_2_qubos_for_scope(instance_db, "scope_name")
+~~~
+
+Anschließend müssen wieder die Embeddings gefunden werden.
+
+~~~python
+from qubo_lab.util import script
+from qubo_lab.util import queries
+from qubo_lab.util import graph
+from dwave.system.samplers import DWaveSampler
+
+instance_db = script.connect_to_instance_pool()
+
+solver_graph = graph.create_qpu_solver_nxgraph(DWaveSampler().solver)
+
+qubos = queries.Ising_scope_query(instance_db, "wmis_2_qubos")
+qubos.query("scope_name")
+
+script.find_embeddings_for_scope(instance_db, solver_graph, qubos)
+~~~
+
+Nun können sie wieder den D-Wave Sampler über die Instanzen laufen lassen.
+
+~~~bash
+./qubo_lab/run_sampler_on_scope.py
+~~~
+
+Achten sie darauf bei der Abfrage der *"Ising/qubo collection"* diesmal "wmis_2_qubos" anzugeben.
+
+Nun erstellen sie erneut eine Tabelle für die zu extrahierenden Daten.
+~~~sql
+CREATE TABLE `wmis_2_qpu_results` (
+  `result_id` char(24) NOT NULL DEFAULT '',
+  `run` int(11) DEFAULT NULL,
+  `instance_id` char(24) DEFAULT NULL,
+  `number_of_found_assignments` int(11) DEFAULT NULL,
+  `chain_break_fraction` float DEFAULT NULL,
+  `num_occurrences` int(11) DEFAULT NULL,
+  `energy` float DEFAULT NULL,
+  `satisfiable` tinyint(1) DEFAULT NULL,
+  `anneal_time` int(11) DEFAULT NULL,
+  `energy_reach` int(11) DEFAULT NULL,
+  `sample_size` int(11) DEFAULT NULL,
+  PRIMARY KEY (`result_id`)
+) ENGINE=InnoDB DEFAULT CHARSET=latin1;
+~~~
+
+Ist die Tabelle erstellt können die Daten extrahiert werden.
+
+~~~python
+from qubo_lab.util import script
+
+instance_db = script.connect_to_instance_pool()
+
+script.extract_wmis_2_qpu_results()
+~~~
+
+Abfrage| Erklärung
+----------|---------------
+scope: | Name des Experiment-Scopes (**scope_name**)
+result collection: | "wmis_qubos"
+table name: | Name der gerade erstellten Tabelle ("wmis_2_qpu_results")

qubo_lab

@@ -1 +1 @@
-Subproject commit 34fa1811952406eb375ef428eb4d6cf8d8986142
+Subproject commit 5c2bd8bdefa3da3bba5f02de6e7973368d2f717a