001    /**
002     * Copyright (C) 2007-2011, Jens Lehmann
003     *
004     * This file is part of DL-Learner.
005     *
006     * DL-Learner is free software; you can redistribute it and/or modify
007     * it under the terms of the GNU General Public License as published by
008     * the Free Software Foundation; either version 3 of the License, or
009     * (at your option) any later version.
010     *
011     * DL-Learner is distributed in the hope that it will be useful,
012     * but WITHOUT ANY WARRANTY; without even the implied warranty of
013     * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
014     * GNU General Public License for more details.
015     *
016     * You should have received a copy of the GNU General Public License
017     * along with this program.  If not, see <http://www.gnu.org/licenses/>.
018     */
019    
020    package org.dllearner.refinementoperators;
021    
022    import java.util.List;
023    import java.util.Set;
024    
025    import org.dllearner.core.owl.Description;
026    
027    /**
028     * Interface for all refinement operators based on OWL/Description Logics.
029     * A refinement operator
030     * maps a description to a set of descriptions. For downward refinement
031     * operators those descriptions are more special. For upward refinement
032     * operators, those descriptions are more general. 
033     * 
034     * @author Jens Lehmann
035     *
036     */
037    public interface RefinementOperator {
038    
039            /**
040             * Standard refinement operation.
041             * @param description The description, which will be refined.
042             * @return A set of refinements.
043             */
044            public Set<Description> refine(Description description);
045            
046            /**
047             * Optional refinement operation, where the learning algorithm can
048             * specify an additional bound on the length of descriptions. 
049             * 
050             * @param description The description, which will be refined.
051             * @param maxLength The maximum length of returned description, where length is defined by {@link Description#getLength()}.
052             * @return A set of refinements obeying the above restrictions.
053             */
054            public Set<Description> refine(Description description, int maxLength);
055                    
056            /**
057             * Optional refinement operation, where the learning algorithm can
058             * specify an additional bound on the length of descriptions and
059             * a list of known refinements, which do not need to be returned. 
060             * 
061             * @param description The description, which will be refined.
062             * @param maxLength The maximum length of returned description, where length is defined by {@link Description#getLength()}.
063             * @param knownRefinements A collection of known refinements, which do not need to be returned. 
064             * @return A set of refinements obeying the above restrictions.
065             */
066            public Set<Description> refine(Description description, int maxLength, List<Description> knownRefinements);
067            
068    }