sukrutrao / timetabler

A customizable timetabling software for educational institutions that encodes timetabling constraints as a SAT formula and solves them using a MaxSAT solver

Timetabler

This project generates a timetable given a set of inputs and constraints. It encodes constraints of the timetabling problem as a SAT formula in the Conjunctive Normal Form, and then calls a MaxSAT solver to solve the problem.

Installation

For Ubuntu/Debian users: Download the deb for the latest version of Timetabler from here and install it.

To build the project from source follow the steps below.

Prerequisities

This project requires following tools to build.

• cmake (version 3.10 or higher)
• g++ or any other C++ compiler with C++11 support
• zlib (On ubuntu: sudo apt install zlib1g-dev)
• libgmp (On ubuntu: sudo apt install libgmp-dev)

Dependencies

The following software are dependencies for this program:

• Open WBO 2.1
• yaml-cpp 0.6.2
• CSVparser
• PEGTL 2.7.0
• GoogleTest 1.8.1 (Optional, needed only for testing)

Get the code

The most recent stable release can be downloaded from here.

To get the latest code, use

$ git clone https://github.com/sukrutrao/Timetabler
$ cd Timetabler

Setting up the dependencies

Short method

To set up all the dependencies required, simply run the following command

$ ./install_dependencies.sh

If building with tests, use instead

$ ./install_dependencies.sh --enable-tests

If the above command fails, you can try installing the individual dependencies manually by following the instructions below.

Long method

This describes the process of setting up each dependency.

Open WBO 2.1

This needs to be built as a library. The following steps need to be followed:

• Clone the repository. $OPEN_WBO_PATH will be used to denote the path where the repository is cloned.

$ git clone https://github.com/sat-group/open-wbo.git $OPEN_WBO_PATH
$ cd $OPEN_WBO_PATH

• Build as a static library

$ LIB=open-wbo make libr

CSVparser

This does not require any setup other than cloning the repository. The path where this is cloned will be referred to as $CSVPARSER_PATH.

yaml-cpp

• Download yaml-cpp-0.6.2 and unpack it. $YAML_CPP_PATH will be used to denote the path where it is unpacked.
• Build the project

$ cd $YAML_CPP_PATH
$ mkdir build && cd build
$ cmake ..
$ make

PEGTL

• Download PEGTL 2.7.0 and unpack it. $PEGTL_PATH will be used to denote the path where it is unpacked.
• Build the project.

$ cd $PEGTL_PATH
$ mkdir build && cd build
$ cmake ..
$ make

GoogleTest

• Download GoogleTest 1.8.1 and unpack it. $GTEST_PATH will be used to denote the path where it is unpacked.
• Build the project

$ cd $GTEST_PATH
$ mkdir build && cd build
$ cmake ..
$ make

Building the project

• Build the project. Set the cmake variables OPEN_WBO_PATH, YAML_CPP_PATH, CSVPARSER_PATH and PEGTL_PATH appropriately.

$ mkdir build && cd build
$ cmake -DOPEN_WBO_PATH="../dependencies/open-wbo" -DYAML_CPP_PATH="../dependencies/yaml-cpp-yaml-cpp-0.6.2" -DCSVPARSER_PATH="../dependencies/CSVparser" -DPEGTL_PATH="../dependencies/PEGTL-2.7.0" -DENABLE_TESTS=Off ..
$ make timetabler

If building with tests, set GTEST_PATH appropriately and use

$ mkdir build && cd build
$ cmake -DOPEN_WBO_PATH="../dependencies/open-wbo" -DYAML_CPP_PATH="../dependencies/yaml-cpp-yaml-cpp-0.6.2" -DCSVPARSER_PATH="../dependencies/CSVparser" -DPEGTL_PATH="../dependencies/PEGTL-2.7.0" -DGTEST_PATH="../dependencies/googletest-release-1.8.1" -DENABLE_TESTS=On ..
$ make timetabler

• To run tests

$ make tests # Build tests
$ make test # Run tests

• Install

$ make install

Running the Timetabler

To execute the program, use

$ timetabler -f fields.yml -i input.csv -c custom.txt -o output.csv

where

• fields.yml is the path to the file containing the list of values a field can take and the weights for the constraints. This includes list of instructors, available classrooms, weights of clauses, etc.
• input.csv is the path to the file containing the input data. This file contains the course data input given to the solver as a CSV file.
• custom.txt is the path to the file containing the list of custom constraints. This file contains the custom constraints that can be provided to the solver using the grammar provided. For the full grammar, please refer to the Project Wiki.
• output.csv is the path to the file to which the output must be written to.

A detailed explanation on each file can be found in the Project Wiki.

For more options, see help

$ timetabler -h

Examples of Configuration files

Examples for configuration files can be found here. This contains some examples for the field information, the input, and custom constraints to be added to the solver.

For further details and examples, please refer to the Project Wiki.

Documentation

The project web page is sukrutrao.github.io/Timetabler.

Code documentation for this project can be found on Read the Docs.

Issues

If you have any queries, suggestions, or feature requests, or would like to report any bugs or issues, please open an issue on GitHub.

When reporting bugs, please provide sufficient information (such as the inputs and the configuration used) to reproduce the bug.

Contributing

To contribute to this project, please send a pull request.

License

This software is provided under the MIT License.

timetabler's Issues

Create test suite and mechanism to test on randomly generated test cases

I want 3 values for IsMinor ie. Yes, No, Lab

I want 3 values for IsMinor ie. Yes, No, Lab ? Can you give me some guidence for this ?

I have changed

Minor.h:

enum MinorType {
	/**
	 * Value when the Course is a minor course
	 */
    isMinorCourse,
    /**
     * Value when the Course is not a minor course
     */
    isNotMinorCourse,
    /**
     * Value when the Course is not a minor course
     */
    isLabCourse
};

Parsing Input:

std::string isMinorStr = parser[i]["is_minor"];
        int isMinor;
        if (isMinorStr == "Yes") {
            isMinor = 0;
            assignmentsThisCourse[FieldType::isMinor].push_back(l_True);
        } else if (isMinorStr == "No") {
            isMinor = 1;
            assignmentsThisCourse[FieldType::isMinor].push_back(l_False);
        } else if(isMinorStr == "Lab"){
            isMinor = 2;
            assignmentsThisCourse[FieldType::isMinor].push_back(l_False);
        }else{
            std::cout << "Input contains invalid IsMinor value (should be 'Yes' , 'No' or 'Lab')" << std::endl;
            exit(1);
        }

Parsing YML:

 IsMinor isMinor = MinorType::isNotMinorCourse;
        std::string isMinorString = slotNode["is_minor"].as<std::string>();
        if(isMinorString == "true"){
            isMinor = MinorType::isMinorCourse;
        }else if(isMinorString == "false") {
            isMinor = MinorType::isNotMinorCourse;
        }else if(isMinorString == "lab"){
            isMinor = MinorType::isLabCourse;
        }

Parser line 67:

timeTabler->data.isMinors.push_back(IsMinor(MinorType::isMinorCourse));
    timeTabler->data.isMinors.push_back(IsMinor(MinorType::isNotMinorCourse));
    timeTabler->data.isMinors.push_back(IsMinor(MinorType::isLabCourse));

ConstraintAdder:

Clauses ConstraintAdder::minorInMinorTime() {
    Clauses result;
    result.clear();
    std::vector<Course> courses = timeTabler->data.courses;
    for(int i = 0; i < courses.size(); i++) {
        /*
         * a minor course must be in a minor Slot.
         * a non-minor course must not be in a minor Slot.
         */
        if(courses[i].getIsMinor() == 2){
            Clauses antecedent1 = encoder->isLabCourse(i);
            Clauses consequent1 = encoder->slotInLabTime(i);
            result.addClauses(antecedent1>>consequent1);
            result.addClauses(consequent1>>antecedent1);
        }else{
            Clauses antecedent = encoder->isMinorCourse(i);
            Clauses consequent = encoder->slotInMinorTime(i);
            result.addClauses(antecedent>>consequent);
            result.addClauses(consequent>>antecedent);}

    }
    return result;
}


```Please Guide me what else should I do.

Improve error messages

Current error messages do not specifically point to the source of error, fix this.

Create a video tutorial on how to install/use etc.

It may be nice to have series of short videos on how to install and/or how to use with a few small examples. One can create these videos using screen recording utilities (such as recordmydesktop for Ubuntu).

This is purely for enhancement of the documentation and user education and is in no way critical for the functionality.

Use glog for logging

Use glog for logging messages, warnings and errors, at various verbosity levels as specified.

Issue with PEGTL

It would be better to help setting up taocpp/pegtl
Because I'm finding difficulty in achieving to do so.
Thank you

Custom constraints for "COURSES EXCEPT LIST ..."

See title

Use GoogleTest for testing

Add unit tests.

Two course Could not be at same day

Is it possible that we add a constrain that two course could not be held at same day ?

Use Tseitin encoding to decrease memory usage

terminate called after throwing an instance of 'std::bad_alloc'
  what():  std::bad_alloc
Aborted (core dumped)

What is the reason of this ERROR.

I entered 50 courses and slots and teachers are enough. but while adding constraints the process is terminated.

Thanks in advance.

timetabler -f fields.yml -i input.csv -c custom.txt -o output.csv

i have been trying to run your program after a couple of errors i arrived at (timetabler -f fields.yml -i input.csv -c custom.txt -o output.csv) and the output is always(Run as timetabler fields.yml input.csv custom.txt output.csv) how can i start the project to see the interface

Change Makefile to CMake

Currently, Makefile is being used. We have to change it to CMake with customizable path options for other dependencies. (Currently, paths are hardcoded in Makefile)

After migrating to CMake build, add .travis.yml to test for build errors.

Unclear terminology

It is not clear to me what a Course is versus a Program
Or a time versus a Slot.
Can these be explained better?

Add comments in all the files

What is segments in Fields.yml .

Please, Add a little description, what are Segments ? What is the use of segments ?

Error parsing constraints

I have successfully build the project but having this error for this input from the example directory

 nagasai@Nagasai:~/Timetabler/examples/example2$ timetabler -f ./fields.yaml -i 
 ./input.csv -c ./custom.txt -o ./output.csv

ERROR for the above input

 [INFO]    Input is valid
 [ERROR]   ./custom.txt:1:0(0) Error parsing custom constraints

While my custom.txt includes:

COURSE {C1} IN SLOT {D} WEIGHT -1
COURSE EXCEPT {C1, C2} UNBUNDLE NOT IN CLASSROOM {CL2, CL3} WEIGHT -1
COURSE EXCEPT {C1, C4} UNBUNDLE IN SLOT {A, B} WEIGHT -1

Create release

@GoodDeeds Please create a release of a stable version. The changes regarding Tseitin encoding etc can be done later.

error: /usr/bin/ld: cannot find -lopen-wbo

What am I doing wrong?
error: /usr/bin/ld: cannot find -lopen-wbo

marcos@dev-pc:~/Developer/timetable-projects/GoodDeeds$ make 
Compiling src/fields/course.cpp...
Compiling src/fields/classroom.cpp...
Compiling src/fields/is_minor.cpp...
Compiling src/fields/instructor.cpp...
Compiling src/fields/program.cpp...
Compiling src/fields/segment.cpp...
Compiling src/fields/slot.cpp...
Compiling src/cclause.cpp...
Compiling src/clauses.cpp...
Compiling src/constraint_adder.cpp...
Compiling src/constraint_encoder.cpp...
Compiling src/parser.cpp...
Compiling src/time_tabler.cpp...
Compiling src/tsolver.cpp...
Compiling ../GoodDeeds-include-CSVparser/CSVparser.cpp...
Compiling src/utils.cpp...
Compiling src/custom_parser.cpp...
Compiling src/data.cpp...
Compiling src/main.cpp...
Building executable...
/usr/bin/ld: cannot find -lopen-wbo
collect2: error: ld returned 1 exit status
Makefile:58: recipe for target 'bin/Timetabler' failed
make: *** [bin/Timetabler] Error 1

successful - make open-wbo

marcos@dev-pc:~/Developer/timetable-projects/open-wbo$ make
..
..
..
..
Linking: open-wbo ( /home/marcos/Developer/timetable-projects/open-wbo/MaxSAT.o /home/marcos/Developer/timetable-projects/open-wbo/Encoder.o /home/marcos/Developer/timetable-projects/open-wbo/MaxSAT_Partition.o /home/marcos/Developer/timetable-projects/open-wbo/ParserPB.o /home/marcos/Developer/timetable-projects/open-wbo/MaxSATFormula.o /home/marcos/Developer/timetable-projects/open-wbo/Main.o utils/System.o utils/Options.o core/Solver.o ../../encodings/Enc_CNetworks.o ../../encodings/Enc_Ladder.o ../../encodings/Enc_MTotalizer.o ../../encodings/Enc_GTE.o ../../encodings/Enc_Totalizer.o ../../encodings/Enc_SWC.o ../../encodings/Encodings.o ../../algorithms/Alg_PartMSU3.o ../../algorithms/Alg_OLL.o ../../algorithms/Alg_LinearSU.o ../../algorithms/Alg_MSU3.o ../../algorithms/Alg_WBO.o ../../graph/Graph.o ../../graph/Graph_Algorithms.o ../../graph/Graph_Communities.o )

in open-wbo/Makefile, I added
VERSION = core
SATSOLVER = "MiniSAT 2.2"
SOLVERDIR = minisat2.2
NSPACE = Minisat

[INFO] Input is valid [ERROR] custom.txt:1:0(0) Error parsing custom constraints

i have

Command line arguments

• Use some library to parse command line arguments
• Specify detailed instructions to use using --help
• One option is to use getopt (Better alternatives are to be searched)
• Another option is to contribute to cppopts

TODO: Command line arguments

• Verbosity level (Will be addressed in #36)
• File paths specified as --fields=fields.yml (See #30)

Improve documentation

• Update custom constraints grammar.
• Move documentation from wiki to docs/ folder
• Add video tutorials (See #20)
• Improve documentation/wiki (See #41)

Add support for multiple instructors

Each course can currently have only one instructor. This should be changed to allow multiple instructors to be specified per course, along with the segments for which each instructor teaches the course.

Weights corresponding to custom constraints are not added correctly

• SAME, NOT SAME Bug
• Weights assigned to custom constraints Bug

Custom Constraints (NOT) has no Effect

COURSE * INSTRUCTOR {T1} NOT IN SLOT {MO1,TU1} WEIGHT -1

This line in custom constraints file should restrict T1's class in Slot MO1 and TU1 but it is assigning these slots to T1's course.

Please Help!

Remove IITH specific statement in the description

On the project homepage "GoodDeeds/Timetabler" under the "<>Code" tab one see the following statement

"
Encode timetabling constraints as a SAT formula and solve using a MaxSAT solver to generate a Timetable for IITH https://timetabler.readthedocs.io"

The tool can be used to generate timetable for any weekly schedule. It may be good to remove the word "IITH" as it gives the wrong impression that the scope of this tool is limited for IITH fractal system only.