From 8b2e745fe96c54200a5a4cb288309f6f506b805a Mon Sep 17 00:00:00 2001 From: Gustaw Lippa <34194983+gustawlippa@users.noreply.github.com> Date: Sat, 30 Jan 2021 20:26:01 +0100 Subject: [PATCH] Add README in english --- README.md | 200 ++++++----------------------------------------- doc/pl/README.md | 183 +++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 209 insertions(+), 174 deletions(-) create mode 100644 doc/pl/README.md diff --git a/README.md b/README.md index a47101c..83e483c 100644 --- a/README.md +++ b/README.md @@ -1,183 +1,35 @@ -Na naszą bibliotekę składają się moduły odpowiadające pewnym -funkcjonalnościom albo automatom. Odpowiednie moduły oraz udostępniane -przez nie obiekty i funkcje wyglądają tak: +# Quantum Finite Automata -- **PFA** (*Probabilistic Finite Automata*) to moduł odpowiadający za - symulację PFA +This library provides implementations of multiple quantum finite automata +models. - Jego główna klasa, *PFA*, zawiera metody: +## Implemented automata models - - *init(alphabet, initialstate, transition_matrices, - acceptance_vector)* - konstruktor automatu, przyjmuje jako - argumenty alfabet, stan początkowy, macierze przejść oraz wektor - akceptacji +* **PFA** - Probabilistic Finite Automaton +* **MO1QFA** - Measure-Once Quantum Finite Automaton +* **MM1QFA** - Measure-Many Quantum Finite Automaton +* **GQFA** - General Quantum Finite Automaton - - *process(word)* - symulacja pojedynczego słowa. Jako argument - przyjmuje słowo, zwraca krotkę *(prawdopodobieństwo akceptacji, - możliwy błąd)* +### Helper modules - W module dostępne są również przykładowe symulacje: +* **LanguageChecker** - used to check a language against an automaton using +multiple acceptance conditions +* **LanguageGenerator** - generates language samples from regular expressions +* **Plotter** - plots the results obtained from running a LanguageChecker - - *dfa_example()* - przykładowa symulacja DFA (*ang. Deterministic - Finite Automata*) +[Here](./doc/pl/README.md) is the modules' overview in polish. - - *pfa_example()* - przykładowa symulacja PFA - - - *example()* - wywołuje oba wyżej wymienione przykłady - - Uruchomienie modułu spowoduje wywołanie funkcji *example()*. - -- **MO1QFA** (*Measure-Once Quantum Finite Automata*) to moduł - odpowiadający za symulację MO-1QFA - - Jego główna klasa, *MO1QFA*, zawiera metody: - - - *init(alphabet, initial_state, transition_matrices, - projective_measurement)* - konstruktor automatu, przyjmuje jako - argumenty alfabet, stan początkowy, macierze przejść oraz - macierz reprezentującą końcowy pomiar - - - *process(word)* - symulacja pojedynczego słowa. Jako argument - przyjmuje słowo, zwraca krotkę *(prawdopodobieństwo akceptacji, - możliwy błąd)* - - W module dostępne są również przykładowe symulacje: - - - *mo_1qfa_example1()* - przykładowa symulacja - - - *mo_1qfa_example2()* - przykładowa symulacja - - - *mo_1qfa_example3()* - przykładowa symulacja - - - *mo_1qfa_example4()* - przykładowa symulacja - - - *example()* - wywołuje wszystkie wyżej wymienione przykłady - - Uruchomienie modułu spowoduje wywołanie funkcji *example()*. - -- **MM1QFA**(*Measure-Many Quantum Finite Automata*) to moduł - odpowiadający za symulację MM-1QFA - - Jego główna klasa, *MM1QFA*, zawiera metody: - - - *init(alphabet, initial_state, transition_matrices, - projective_measurement_accept, projective_measurement_reject, - projective_measurement_non)* - konstruktor automatu, przyjmuje - jako argumenty alfabet, stan początkowy, macierze przejść oraz - macierze pomiarów rzutowych. Argument *projectivemeasurementnon* - jest opcjonalny - w przypadku podania jedynie macierzy - rozpinających przestrzenie stanów akceptujących oraz - odrzucających zostanie wyliczona automatycznie - - - *process(word)* - symulacja pojedynczego słowa. Jako argument - przyjmuje słowo, zwraca krotkę *(prawdopodobieństwo akceptacji, - możliwy błąd)* - - W module dostępna jest również przykładowe symulacja *example()*. - Uruchomienie modułu spowoduje wywołanie funkcji *example()*. - -- **GQFA** (*General Quantum Finite Automata*) to moduł odpowiadający - za symulację GQFA - - Jego główna klasa, *GQFA*, zawiera metody: - - - *init(alphabet, initial_state, transition_matrices, - projective_measurements)* - Konstruktor automatu, przyjmuje jako - argumenty alfabet, stan początkowy, macierze przejść oraz - macierze pomiarów rzutowych (dla każdego symbolu alfabetu) - - - *process(word)* - symulacja pojedynczego słowa. Jako argument - przyjmuje słowo, zwraca krotkę *(prawdopodobieństwo akceptacji, - możliwy błąd)* - - W module dostępna jest również przykładowa symulacja *example()*. - Uruchomienie modułu spowoduje wywołanie funkcji *example()*. - -- **LanguageChecker** to moduł odpowiadający za sprawdzanie akceptacji - języka przez dany automat przy różnych trybach działania - - Jego główna klasa, *LanguageChecker*, zawiera metody: - - - *init(automata, language, not_in_language)* - konstruktor obiektu, - przyjmuje jako argumenty zdefiniowany uprzednio automat, listę - słów należących do języka oraz listę słów nienależących do - języka - - - *check_language()* - metoda sprawdzająca wszystkie tryby - akceptacji języka. Zwraca słownik trybów akceptacji, przy - których automat rozpoznaje język, gdzie kluczem jest nazwa a - wartością parametry danego trybu. W przypadku, gdy automat nie - rozpoznaje języka w danym trybie, nie występuje on w zwracanym - słowniku. Możliwe jest sprawdzenie konkretnego trybu akceptacji, - lecz zalecane jest używanie właśnie tej metody, gdyż zwraca - pełną informację na temat badanego automatu - - - *check_cutpoint()* - metoda sprawdzająca tryb akceptacji *z - punktem odcięcia*. Zwraca *False*, jeżeli automat nie akceptuje - języka w tym trybie, lub wartość punktu odcięcia, jeżeli - akceptuje - - - *check_isolated_cutpoint()* - metoda sprawdzająca tryb akceptacji - *z odizolowanym punktem odcięcia*. Zwraca *False*, jeżeli - automat nie akceptuje języka w tym trybie, lub krotkę - ($\lambda$, $\epsilon$, wartość błędu) jeżeli akceptuje. W tym - trybie, jeżeli wartość $\epsilon$ jest tego samego rzędu - wielkości, co wartość błędu, nie jesteśmy w stanie jednoznacznie - stwierdzić, czy automat rozpoznaje dany język - - - *check_monte_carlo()* - metoda sprawdzająca tryb akceptacji - *metodą Monte Carlo*. Zwraca *False*, jeżeli automat nie - akceptuje języka w tym trybie, lub $\epsilon$, jeżeli akceptuje - - - *check_bounded_error()* - metoda sprawdzająca tryb akceptacji *z - ograniczonym błędem*. Zwraca *False*, jeżeli automat nie - akceptuje języka w tym trybie, lub $\epsilon$, jeżeli akceptuje - - - *check_positive_unbounded()* - metoda sprawdzająca tryb akceptacji - *z pozytywnie jednostronnie nieograniczonym błędem*. Zwraca - *False*, jeżeli automat nie akceptuje języka w tym trybie lub - *True*, jeżeli akceptuje - - - *check_negative_unbounded()* - metoda sprawdzająca tryb akceptacji - *z negatywnie jednostronnie nieograniczonym błędem*. Zwraca - *False*, jeżeli automat nie akceptuje języka w tym trybie lub - *True*, jeżeli akceptuje - -- **LanguageGenerator** to moduł odpowiadający za generowanie słów - należących oraz nienależących do języka - - Jego główna klasa, *LanguageGenerator*, zawiera metody: - - - *init(regex, alphabet)* - konstruktor obiektu, przyjmuje jako - argumenty wyrażenie regularne opisujące język oraz jego alfabet. - Dodatkowo, jeżeli w wyrażeniu regularnym pojawi się ,,\\a”, - zostanie on automatycznie podmieniony na ,,[alphabet]”, czyli - klasę liter alfabetu, co pozwala na zwięźlejsze pisanie wyrażeń - regularnych w wielu częstych przypadkach - - - *get_language_sample(n, short_words_percent, max_len)* - metoda - odpowiedzialna za generowanie próbki języka. Przyjmuje jako - parametry ilość słów do wygenerowania, procentową zawartość - krótkich słów w tym zbiorze oraz maksymalną długość słowa. - Zwraca krotkę (słowa należące do języka, słowa nienależące do - języka) - - W module dostępny jest również przykład generowania słów: - - - *example()* - przykładowe generowanie słów należących oraz - nienależących do języka - - Uruchomienie modułu spowoduje wywołanie funkcji *example()*. - -- **Plotter** to moduł odpowiadający za graficzne przedstawienie - trybów akceptacji języka oraz ich parametrów - - Jego główna klasa, *Plotter* zawiera metody: - - - *init(language_checker)* - konstruktor obiektu, przyjmuje jako - argument obiekt klasy *LanguageChecker* - - - *plot()* - metoda tworząca graficzne przedstawienie trybów - akceptacji +## Citation +If you have used our library and and would like to cite its usage, we please use the following BibTeX entry. Thanks! +``` +@article{lippa2020simulations, + title={Simulations of Quantum Finite Automata.}, + author={Lippa, G and Makie{\l}a, K and Kuta, M}, + journal={Computational Science--ICCS 2020}, + volume={12142}, + pages={441--450}, + year={2020} +} +``` diff --git a/doc/pl/README.md b/doc/pl/README.md new file mode 100644 index 0000000..e11c182 --- /dev/null +++ b/doc/pl/README.md @@ -0,0 +1,183 @@ +Na naszą bibliotekę składają się moduły odpowiadające pewnym +funkcjonalnościom albo automatom. Odpowiednie moduły oraz udostępniane +przez nie obiekty i funkcje wyglądają tak: + +- **PFA** (*Probabilistic Finite Automaton*) to moduł odpowiadający za + symulację PFA + + Jego główna klasa, *PFA*, zawiera metody: + + - *init(alphabet, initialstate, transition_matrices, + acceptance_vector)* - konstruktor automatu, przyjmuje jako + argumenty alfabet, stan początkowy, macierze przejść oraz wektor + akceptacji + + - *process(word)* - symulacja pojedynczego słowa. Jako argument + przyjmuje słowo, zwraca krotkę *(prawdopodobieństwo akceptacji, + możliwy błąd)* + + W module dostępne są również przykładowe symulacje: + + - *dfa_example()* - przykładowa symulacja DFA (*ang. Deterministic + Finite Automaton*) + + - *pfa_example()* - przykładowa symulacja PFA + + - *example()* - wywołuje oba wyżej wymienione przykłady + + Uruchomienie modułu spowoduje wywołanie funkcji *example()*. + +- **MO1QFA** (*Measure-Once Quantum Finite Automaton*) to moduł + odpowiadający za symulację MO-1QFA + + Jego główna klasa, *MO1QFA*, zawiera metody: + + - *init(alphabet, initial_state, transition_matrices, + projective_measurement)* - konstruktor automatu, przyjmuje jako + argumenty alfabet, stan początkowy, macierze przejść oraz + macierz reprezentującą końcowy pomiar + + - *process(word)* - symulacja pojedynczego słowa. Jako argument + przyjmuje słowo, zwraca krotkę *(prawdopodobieństwo akceptacji, + możliwy błąd)* + + W module dostępne są również przykładowe symulacje: + + - *mo_1qfa_example1()* - przykładowa symulacja + + - *mo_1qfa_example2()* - przykładowa symulacja + + - *mo_1qfa_example3()* - przykładowa symulacja + + - *mo_1qfa_example4()* - przykładowa symulacja + + - *example()* - wywołuje wszystkie wyżej wymienione przykłady + + Uruchomienie modułu spowoduje wywołanie funkcji *example()*. + +- **MM1QFA**(*Measure-Many Quantum Finite Automaton*) to moduł + odpowiadający za symulację MM-1QFA + + Jego główna klasa, *MM1QFA*, zawiera metody: + + - *init(alphabet, initial_state, transition_matrices, + projective_measurement_accept, projective_measurement_reject, + projective_measurement_non)* - konstruktor automatu, przyjmuje + jako argumenty alfabet, stan początkowy, macierze przejść oraz + macierze pomiarów rzutowych. Argument *projectivemeasurementnon* + jest opcjonalny - w przypadku podania jedynie macierzy + rozpinających przestrzenie stanów akceptujących oraz + odrzucających zostanie wyliczona automatycznie + + - *process(word)* - symulacja pojedynczego słowa. Jako argument + przyjmuje słowo, zwraca krotkę *(prawdopodobieństwo akceptacji, + możliwy błąd)* + + W module dostępna jest również przykładowe symulacja *example()*. + Uruchomienie modułu spowoduje wywołanie funkcji *example()*. + +- **GQFA** (*General Quantum Finite Automaton*) to moduł odpowiadający + za symulację GQFA + + Jego główna klasa, *GQFA*, zawiera metody: + + - *init(alphabet, initial_state, transition_matrices, + projective_measurements)* - Konstruktor automatu, przyjmuje jako + argumenty alfabet, stan początkowy, macierze przejść oraz + macierze pomiarów rzutowych (dla każdego symbolu alfabetu) + + - *process(word)* - symulacja pojedynczego słowa. Jako argument + przyjmuje słowo, zwraca krotkę *(prawdopodobieństwo akceptacji, + możliwy błąd)* + + W module dostępna jest również przykładowa symulacja *example()*. + Uruchomienie modułu spowoduje wywołanie funkcji *example()*. + +- **LanguageChecker** to moduł odpowiadający za sprawdzanie akceptacji + języka przez dany automat przy różnych trybach działania + + Jego główna klasa, *LanguageChecker*, zawiera metody: + + - *init(automaton, language, not_in_language)* - konstruktor obiektu, + przyjmuje jako argumenty zdefiniowany uprzednio automat, listę + słów należących do języka oraz listę słów nienależących do + języka + + - *check_language()* - metoda sprawdzająca wszystkie tryby + akceptacji języka. Zwraca słownik trybów akceptacji, przy + których automat rozpoznaje język, gdzie kluczem jest nazwa a + wartością parametry danego trybu. W przypadku, gdy automat nie + rozpoznaje języka w danym trybie, nie występuje on w zwracanym + słowniku. Możliwe jest sprawdzenie konkretnego trybu akceptacji, + lecz zalecane jest używanie właśnie tej metody, gdyż zwraca + pełną informację na temat badanego automatu + + - *check_cutpoint()* - metoda sprawdzająca tryb akceptacji *z + punktem odcięcia*. Zwraca *False*, jeżeli automat nie akceptuje + języka w tym trybie, lub wartość punktu odcięcia, jeżeli + akceptuje + + - *check_isolated_cutpoint()* - metoda sprawdzająca tryb akceptacji + *z odizolowanym punktem odcięcia*. Zwraca *False*, jeżeli + automat nie akceptuje języka w tym trybie, lub krotkę + ($\lambda$, $\epsilon$, wartość błędu) jeżeli akceptuje. W tym + trybie, jeżeli wartość $\epsilon$ jest tego samego rzędu + wielkości, co wartość błędu, nie jesteśmy w stanie jednoznacznie + stwierdzić, czy automat rozpoznaje dany język + + - *check_monte_carlo()* - metoda sprawdzająca tryb akceptacji + *metodą Monte Carlo*. Zwraca *False*, jeżeli automat nie + akceptuje języka w tym trybie, lub $\epsilon$, jeżeli akceptuje + + - *check_bounded_error()* - metoda sprawdzająca tryb akceptacji *z + ograniczonym błędem*. Zwraca *False*, jeżeli automat nie + akceptuje języka w tym trybie, lub $\epsilon$, jeżeli akceptuje + + - *check_positive_unbounded()* - metoda sprawdzająca tryb akceptacji + *z pozytywnie jednostronnie nieograniczonym błędem*. Zwraca + *False*, jeżeli automat nie akceptuje języka w tym trybie lub + *True*, jeżeli akceptuje + + - *check_negative_unbounded()* - metoda sprawdzająca tryb akceptacji + *z negatywnie jednostronnie nieograniczonym błędem*. Zwraca + *False*, jeżeli automat nie akceptuje języka w tym trybie lub + *True*, jeżeli akceptuje + +- **LanguageGenerator** to moduł odpowiadający za generowanie słów + należących oraz nienależących do języka + + Jego główna klasa, *LanguageGenerator*, zawiera metody: + + - *init(regex, alphabet)* - konstruktor obiektu, przyjmuje jako + argumenty wyrażenie regularne opisujące język oraz jego alfabet. + Dodatkowo, jeżeli w wyrażeniu regularnym pojawi się ,,\\a”, + zostanie on automatycznie podmieniony na ,,[alphabet]”, czyli + klasę liter alfabetu, co pozwala na zwięźlejsze pisanie wyrażeń + regularnych w wielu częstych przypadkach + + - *get_language_sample(n, short_words_percent, max_len)* - metoda + odpowiedzialna za generowanie próbki języka. Przyjmuje jako + parametry ilość słów do wygenerowania, procentową zawartość + krótkich słów w tym zbiorze oraz maksymalną długość słowa. + Zwraca krotkę (słowa należące do języka, słowa nienależące do + języka) + + W module dostępny jest również przykład generowania słów: + + - *example()* - przykładowe generowanie słów należących oraz + nienależących do języka + + Uruchomienie modułu spowoduje wywołanie funkcji *example()*. + +- **Plotter** to moduł odpowiadający za graficzne przedstawienie + trybów akceptacji języka oraz ich parametrów + + Jego główna klasa, *Plotter* zawiera metody: + + - *init(language_checker)* - konstruktor obiektu, przyjmuje jako + argument obiekt klasy *LanguageChecker* + + - *plot()* - metoda tworząca graficzne przedstawienie trybów + akceptacji + +