001package org.cpsolver.studentsct.online.expectations;
002
003import org.cpsolver.ifs.assignment.Assignment;
004import org.cpsolver.ifs.util.DataProperties;
005import org.cpsolver.studentsct.model.Enrollment;
006import org.cpsolver.studentsct.model.Request;
007import org.cpsolver.studentsct.model.Section;
008import org.cpsolver.studentsct.model.Subpart;
009
010/**
011 * Avoid unbalanced sections when there are no expectations. When there are
012 * expectations, the {@link FractionallyOverExpected} is used. If there are no
013 * expectations, sections that would have more students than given by the
014 * balance are marked as over-expected. The target fill ratio is proportional to
015 * the section size, a section is considered unbalanced, when the target fill is
016 * exceeded by more than OverExpected.Disbalance percentage (defaults to 0.1).
017 * Unlimited sections are also balanced, when General.BalanceUnlimited parameter
018 * is set to true (defaults to false).<br>
019 * <br>
020 * A class of an offering with no expectations is over-expected when the number
021 * of enrolled students (including the student in question) minus the target
022 * fill is over the OverExpected.Disbalance portion of the section limit.
023 * 
024 * @version StudentSct 1.3 (Student Sectioning)<br>
025 *          Copyright (C) 2014 Tomáš Müller<br>
026 *          <a href="mailto:muller@unitime.org">muller@unitime.org</a><br>
027 *          <a href="http://muller.unitime.org">http://muller.unitime.org</a><br>
028 * <br>
029 *          This library is free software; you can redistribute it and/or modify
030 *          it under the terms of the GNU Lesser General Public License as
031 *          published by the Free Software Foundation; either version 3 of the
032 *          License, or (at your option) any later version. <br>
033 * <br>
034 *          This library is distributed in the hope that it will be useful, but
035 *          WITHOUT ANY WARRANTY; without even the implied warranty of
036 *          MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
037 *          Lesser General Public License for more details. <br>
038 * <br>
039 *          You should have received a copy of the GNU Lesser General Public
040 *          License along with this library; if not see <a
041 *          href='http://www.gnu.org/licenses'>http://www.gnu.org/licenses</a>.
042 * 
043 */
044public class FractionallyUnbalancedWhenNoExpectations extends FractionallyOverExpected {
045    private Double iDisbalance = 0.1;
046    private boolean iBalanceUnlimited = false;
047
048    public FractionallyUnbalancedWhenNoExpectations(DataProperties config) {
049        super(config);
050        iDisbalance = config.getPropertyDouble("OverExpected.Disbalance", iDisbalance);
051        iBalanceUnlimited = config.getPropertyBoolean("General.BalanceUnlimited", iBalanceUnlimited);
052    }
053
054    public FractionallyUnbalancedWhenNoExpectations(Double percentage, Double maximum, Double disbalance) {
055        super(percentage, maximum);
056        iDisbalance = disbalance;
057    }
058
059    public FractionallyUnbalancedWhenNoExpectations(Double percentage, Double maximum) {
060        this(percentage, maximum, null);
061    }
062
063    public FractionallyUnbalancedWhenNoExpectations(Double percentage) {
064        this(percentage, null, null);
065    }
066
067    public FractionallyUnbalancedWhenNoExpectations() {
068        this(null, null, null);
069    }
070
071    /**
072     * Return allowed disbalance, defaults to 0.1 (parameter OverExpected.Disbalance)
073     * 
074     * @return allowed disbalance
075     */
076    public Double getDisbalance() {
077        return iDisbalance;
078    }
079
080    /**
081     * Is balancing of unlimited sections enabled (parameter General.BalanceUnlimited)
082     * @return true if balancing of unlimited sections is enabled
083     */
084    public boolean isBalanceUnlimited() {
085        return iBalanceUnlimited;
086    }
087
088    /**
089     * Get maximum
090     * @param section given section
091     * @param defaultValue default value (if not set)
092     * @return maximum
093     */
094    public double getMaximum(Section section, double defaultValue) {
095        return getMaximum() == null || getMaximum() <= 0.0 ? defaultValue : getMaximum();
096    }
097
098    @Override
099    public double getOverExpected(Assignment<Request, Enrollment> assignment, Section section, Request request) {
100        Subpart subpart = section.getSubpart();
101
102        if (hasExpectations(subpart) && section.getLimit() > 0)
103            return super.getOverExpected(assignment, section, request);
104
105        if (getDisbalance() == null || getDisbalance() < 0.0)
106            return 0.0;
107
108        double enrlConfig = request.getWeight() + getEnrollment(assignment, subpart.getConfig(), request);
109        int subparts = section.getSubpart().getConfig().getSubparts().size();
110        int limit = getLimit(section);
111        double enrl = request.getWeight() + getEnrollment(assignment, section, request);
112
113        if (limit > 0) {
114            // sections have limits -> desired size is section limit x (total
115            // enrollment / total limit)
116            double desired = (enrlConfig / getLimit(subpart)) * limit;
117            if (enrl - desired >= Math.max(1.0, getDisbalance() * limit)) {
118                double max = getMaximum(section, limit);
119                return Math.min(max, enrl - desired) / (max * subparts);
120            }
121        } else if (isBalanceUnlimited()) {
122            // unlimited sections -> desired size is total enrollment / number
123            // of sections
124            double desired = enrlConfig / subpart.getSections().size();
125            if (enrl - desired >= Math.max(1.0, getDisbalance() * desired)) {
126                double max = getMaximum(section, desired);
127                return Math.min(max, enrl - desired) / (max * subparts);
128            }
129        }
130
131        return 0.0;
132    }
133
134    @Override
135    public String toString() {
136        return "fbal(" + getPercentage() + "," + getMaximum() + "," + getDisbalance() + ")";
137    }
138}