001package org.cpsolver.studentsct.online;
002
003import org.apache.log4j.Logger;
004import org.cpsolver.ifs.assignment.Assignment;
005import org.cpsolver.ifs.util.DataProperties;
006import org.cpsolver.studentsct.StudentSectioningModel;
007import org.cpsolver.studentsct.model.Enrollment;
008import org.cpsolver.studentsct.model.Request;
009import org.cpsolver.studentsct.model.Section;
010import org.cpsolver.studentsct.online.expectations.AvoidUnbalancedWhenNoExpectations;
011import org.cpsolver.studentsct.online.expectations.OverExpectedCriterion;
012import org.cpsolver.studentsct.online.expectations.PercentageOverExpected;
013
014/**
015 * An online model. A simple extension of the {@link OnlineSectioningModel} class that allows to set the over-expected
016 * criterion (see {@link OverExpectedCriterion}). This class is particularly useful in passing the over-expected criterion to the 
017 * online sectioning algorithms and heuristics.<br><br>
018 * The over-expected criterion can be passed as a constructor parameter, or given using the OverExpectedCriterion.Class parameter.
019 * It defaults to {@link AvoidUnbalancedWhenNoExpectations}.
020 * 
021 * @version StudentSct 1.3 (Student Sectioning)<br>
022 *          Copyright (C) 2014 Tomas Muller<br>
023 *          <a href="mailto:muller@unitime.org">muller@unitime.org</a><br>
024 *          <a href="http://muller.unitime.org">http://muller.unitime.org</a><br>
025 * <br>
026 *          This library is free software; you can redistribute it and/or modify
027 *          it under the terms of the GNU Lesser General Public License as
028 *          published by the Free Software Foundation; either version 3 of the
029 *          License, or (at your option) any later version. <br>
030 * <br>
031 *          This library is distributed in the hope that it will be useful, but
032 *          WITHOUT ANY WARRANTY; without even the implied warranty of
033 *          MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
034 *          Lesser General Public License for more details. <br>
035 * <br>
036 *          You should have received a copy of the GNU Lesser General Public
037 *          License along with this library; if not see <a href='http://www.gnu.org/licenses'>http://www.gnu.org/licenses</a>.
038 * 
039 */
040public class OnlineSectioningModel extends StudentSectioningModel {
041    private static Logger sLog = Logger.getLogger(OnlineSectioningModel.class);
042    private OverExpectedCriterion iOverExpectedCriterion;
043
044    public OnlineSectioningModel(DataProperties properties) {
045        super(properties);
046        try {
047            @SuppressWarnings("unchecked")
048            Class<OverExpectedCriterion> overExpectedCriterionClass = (Class<OverExpectedCriterion>)
049                Class.forName(properties.getProperty("OverExpectedCriterion.Class", AvoidUnbalancedWhenNoExpectations.class.getName()));
050            iOverExpectedCriterion = overExpectedCriterionClass.getConstructor(DataProperties.class).newInstance(properties);
051        } catch (Exception e) {
052                sLog.error("Unable to create custom over-expected criterion (" + e.getMessage() + "), using default.", e);
053                iOverExpectedCriterion = new PercentageOverExpected(properties);
054        }
055    }
056
057    public OnlineSectioningModel(DataProperties config, OverExpectedCriterion criterion) {
058        super(config);
059        iOverExpectedCriterion = criterion;
060    }
061    
062    /**
063     * Get over-expected criterion
064     * @return over-expected criterion
065     */
066    public OverExpectedCriterion getOverExpectedCriterion() { return iOverExpectedCriterion; }
067    
068    /**
069     * Set over-expected criterion
070     * @param overExpectedCriterion over-expected criterion
071     */
072    public void setOverExpectedCriterion(OverExpectedCriterion overExpectedCriterion) { iOverExpectedCriterion = overExpectedCriterion; }
073    
074    /**
075     * Expectation penalty, to be minimized (computed using {@link OverExpectedCriterion#getOverExpected(Assignment, Section, Request)})
076     * @param assignment current assignment
077     * @param section section in question
078     * @param request student course request
079     * @return expectation penalty (typically 1.0 / number of subparts when over-expected, 0.0 otherwise)
080     */
081    public double getOverExpected(Assignment<Request, Enrollment> assignment, Section section, Request request) {
082        return getOverExpectedCriterion().getOverExpected(assignment, section, request);
083    }
084
085}