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