001/* Copyright (C) 2013 TU Dortmund
002 * This file is part of LearnLib, http://www.learnlib.de/.
003 * 
004 * LearnLib is free software; you can redistribute it and/or
005 * modify it under the terms of the GNU Lesser General Public
006 * License version 3.0 as published by the Free Software Foundation.
007 * 
008 * LearnLib is distributed in the hope that it will be useful,
009 * but WITHOUT ANY WARRANTY; without even the implied warranty of
010 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
011 * Lesser General Public License for more details.
012 * 
013 * You should have received a copy of the GNU Lesser General Public
014 * License along with LearnLib; if not, see
015 * <http://www.gnu.de/documents/lgpl.en.html>.
016 */
017package de.learnlib.api;
018
019import net.automatalib.automata.fsa.DFA;
020import net.automatalib.automata.transout.MealyMachine;
021import net.automatalib.words.Word;
022import de.learnlib.oracles.DefaultQuery;
023
024
025
026/**
027 * Basic interface for a model inference algorithm.
028 * 
029 * Actively inferring models (such as DFAs or Mealy machines) consists of the construction
030 * of an initial hypothesis, which is subsequently refined using counterexamples
031 * (see {@link EquivalenceOracle}). 
032 * 
033 * @author Maik Merten <maikmerten@googlemail.com>
034 * @author Malte Isberner <malte.isberner@gmail.com>
035 *
036 * @param <M> model class.
037 * @param <I> input symbol class.
038 * @param <O> output class.
039 */
040public interface LearningAlgorithm<M, I, O> {
041        
042        public static interface DFALearner<I> extends LearningAlgorithm<DFA<?,I>,I,Boolean> {}
043        public static interface MealyLearner<I,O> extends LearningAlgorithm<MealyMachine<?,I,?,O>,I,Word<O>> {}
044        
045        /**
046         * Starts the model inference process, creating an initial hypothesis in the provided
047         * model object. Please note that it should be illegal to invoke this method twice.
048         */
049        public void startLearning();
050        
051        /**
052         * Triggers a refinement of the model by providing a counterexample.
053         * A counterexample is a query which exposes different behavior of the real SUL compared
054         * to the hypothesis. Please note that invoking this method before an initial
055         * invocation of {@link #startLearning()} should be illegal.
056         * 
057         * @param ceQuery the query which exposes diverging behavior, as posed to the real SUL
058         * (i.e. with the SULs output).
059         * @return <tt>true</tt> if the counterexample triggered a refinement of the hypothesis,
060         * <tt>false</tt> otherwise (i.e., it was no counterexample).
061         */
062        public boolean refineHypothesis(DefaultQuery<I, O> ceQuery);
063        
064        /**
065         * Returns the current hypothesis model.
066         * <p>
067         * N.B.: By the contract of this interface, the model returned by this method may not be
068         * modified (i.e., M generally should refer to an immutable interface), and its validity
069         * is retained only until the next invocation of {@link #refineHypothesis(DefaultQuery)}. If
070         * older hypotheses have to be maintained, a copy of the returned model must be made
071         * Please note that it should be illegal to invoke this method before an initial invocation
072         * of {@link #startLearning()}.
073         * @return the current hypothesis model.
074         */
075        public M getHypothesisModel();
076}