diff --git a/.run/ProperStudioTests.run.xml b/.run/ProperStudioTests.run.xml new file mode 100644 index 00000000..59074c86 --- /dev/null +++ b/.run/ProperStudioTests.run.xml @@ -0,0 +1,12 @@ + + + + + \ No newline at end of file diff --git a/.run/TestBitset.run.xml b/.run/TestBitset.run.xml new file mode 100644 index 00000000..432b3241 --- /dev/null +++ b/.run/TestBitset.run.xml @@ -0,0 +1,13 @@ + + + + + \ No newline at end of file diff --git a/.run/TestConstraints.run.xml b/.run/TestConstraints.run.xml new file mode 100644 index 00000000..17027569 --- /dev/null +++ b/.run/TestConstraints.run.xml @@ -0,0 +1,12 @@ + + + + + \ No newline at end of file diff --git a/.run/TestLessons.run.xml b/.run/TestLessons.run.xml new file mode 100644 index 00000000..00895c0c --- /dev/null +++ b/.run/TestLessons.run.xml @@ -0,0 +1,13 @@ + + + + + \ No newline at end of file diff --git a/.run/TestRooms.run.xml b/.run/TestRooms.run.xml new file mode 100644 index 00000000..0689ea0d --- /dev/null +++ b/.run/TestRooms.run.xml @@ -0,0 +1,13 @@ + + + + + \ No newline at end of file diff --git a/.run/TestTeachers.run.xml b/.run/TestTeachers.run.xml new file mode 100644 index 00000000..6d7fc1ad --- /dev/null +++ b/.run/TestTeachers.run.xml @@ -0,0 +1,13 @@ + + + + + \ No newline at end of file diff --git a/.run/TestTimeslot.run.xml b/.run/TestTimeslot.run.xml new file mode 100644 index 00000000..0653e051 --- /dev/null +++ b/.run/TestTimeslot.run.xml @@ -0,0 +1,14 @@ + + + + + \ No newline at end of file diff --git a/.run/TimeTable.run.xml b/.run/TimeTable.run.xml new file mode 100644 index 00000000..0f2c10df --- /dev/null +++ b/.run/TimeTable.run.xml @@ -0,0 +1,12 @@ + + + + \ No newline at end of file diff --git a/README.adoc b/README.adoc deleted file mode 100644 index 3d919318..00000000 --- a/README.adoc +++ /dev/null @@ -1,37 +0,0 @@ -# Department Scheduling Optimization System -There are two main part to this system. The java engine which handles scheduling department courses for an entire -semester while making sure constraints are followed. The backend portion of this project has the goal of solving the -issue of instructors/teachers having various names and handling the surveys instructors fill out, especially when they -use an old survey to fill out the current one. - -## Java Engine (in the java directory) -Why do we need this? Scheduling is an NP-Hard problem. Depending on the size of the problem, finding an optimal solution -is infeasible. Even if the problem is on the smaller side, it is not practical so manually schedule everything. Therefore, -the java engine automates this process while adhering to buisness constraints, avoiding conflicts, and giving instructors -their preferences. - -The java engine uses multiple solving phases to accomplish this. It has three phases. The construction phase, local search, -and local search. In that specific order. The first phase uses a construction heuristic build a feasible solution. Then -the local search will use the meta heuristic simulated annealing to correct any hard constraints (things that can't be -violated) until we reach a non-negative hard score or time has run out. The third phase will run if and only if the first -phase has successfully completed. This last phase use a combination of meta heuristics, mainly simulated annealing and -tabu search, to further improve the solution quality by improving the medium and soft scores (basically preferences or -schedule characteristics we prefer). - -The engine also allows for different configuration the solver can have. Some are mutually exclusive. These -configurations boil down to how we treat the prime time business constraint. In certain configurations, the solver engine -will attempt to compress time into the given time interval. - -To ensure instructors have their preference taken into account, their surveys should be stored in the backend and have -the instructor linked teacher DB record marking them as faculty or not. Therefore, if the use of the api is chosen, the -engine can read the survey DB records through the API endpoint. - -## Backend (in the backend directory) -The backend services are the support piece for the java engine. These services include a Django backend, PostgreSQL DB, -and pgAdmin. The backend is setup to use JWT Authentication and role based access control (RBAC). Authentication is -set globally. Therefore, if an api endpoint doesn't want auth, it has to explicitly be set. Better for security. - - -## What's next -Test coverage is currently run locally. The plan is to do use GitHub Actions to build CI/CD workflow to test/verify -code that is pushed \ No newline at end of file diff --git a/README.md b/README.md new file mode 100644 index 00000000..59ddd9ce --- /dev/null +++ b/README.md @@ -0,0 +1,170 @@ +# Department Scheduling Optimization System +This project has two main parts: the Java scheduling engine, which constructs semester schedules while enforcing constraints, and the backend, which stores instructor information such as names, emails, and survey responses. + +The documentation below is a quick setup guide to getting started. + +Before we get started note that I might use the words teachers and instructors interchangeably. +Also, when I use the word faculty, I use it to refer to instructors that need time off during a certain time of the week because they are tenured or on track. + +## Java Engine +For the in dpeth scheduling engine documentation go [here](java/hello-world/README.md) +**When working with the Java engine in Intellij, open the project up from this directory.** + +To utlize the Java engine you will need to have Java 17 on your system. Currently the java engine will require an IDE +so you can run the tool I've created. The IDE I will be showing in the guide will be IntelliJ. The software will also log +important information related to what it is doing. + +Nescessary files and location placement (Note file names are case sensitive and if a slug is include then it will be denoted as ``). +The software/tool will fall back to using the files in the case a connection can't be created, so it can be useful to include all the files. + +__Files necessary if using the backend:__ +- `.env` in [java/hello-world/src/main/resources](java/hello-world/src/main/resources). The backend has authentication include, so the following enviornment variables are needed. +An example .env file has also been given at the linked location + - API_USER_PASSWORD + - API_USER + +__Files necessary if not using the backend:__ +- Previous term survey: `_survey.csv` in +[java/hello-world/src/main/resources/input/](java/hello-world/src/main/resources/input/). +An example file is given called `term_survey.example.csv` in the location. +Note the order of the header is important for proper parsing. +- Current term survey: `_survey.csv` in +[java/hello-world/src/main/resources/input](java/hello-world/src/main/resources/input). +An example file is given called `term_survey.example.csv` in the location. +Note the order of the header is important for proper parsing. + +__Files necessary regardles of backend usage:__ +- Configuration for engine: `config.yaml` in +[java/hello-world/src/main/resources/constants/](java/hello-world/src/main/resources/constants/). +An example file is given. +- Tells us who teaches what: `schedule--` in +[java/hello-world/src/main/resources/input/](java/hello-world/src/main/resources/input/). +An example file is given at the location. +- Course name to configuration (already given): `semester-configurations.tsv` in +[java/hello-world/src/main/resources/constants/](java/hello-world/src/main/resources/constants/). +- File encoiding possible times (already given): `possibleTimes.csv` in +[java/hello-world/src/main/resources/constants/](java/hello-world/src/main/resources/constants/). +- Univesity site information of faculty: `faculty_website_list.tsv` +[java/hello-world/src/main/resources/constants/](java/hello-world/src/main/resources/constants/). +No example file given. +- Instructor name to canon file: `name_mappings.xlsx` in [java/hello-world/src/main/resources/constants/](java/hello-world/src/main/resources/constants/). +No example file is given here but the column order for the file is `email,name,canon`. + + +__Optional Files:__ +- `your_name_choice.json` [java/hello-world/src/main/resources/input/](java/hello-world/src/main/resources/input/). +An example file has been given for you to understand the formatting. +This file can be included if you want to add in prescheduled times. +For example, an instructor was scheduled in another department. + +Note I'll give you some of the files that aren't included. + +__Running the application__ +Once you have all those files in place you are ready to run the application. +Simply run [TimetableApp.java](java/hello-world/src/main/java/org/acme/schooltimetabling/TimetableApp.java) and the solutions will be printed out into your workind directory into a folder called `generated`. +The file name will be `__solution.xlsx`. +There will also be a file called `times_.json`, which will encode the times an instructor has been scheduled into a JSON file. + +**Note that I have added the configuraiton to run the application**. +You should be able to select it by hitting the drop down menu next to the button marked in step 5 in the guide below. +If no such thing exists, then follow the setup guide below. + +**Example intellij setup.** +In step 1 you will see pop up. Select `edit` under configuration. +In step 2 you will see a menu and you should choose the `Application` option. +In step 3 you will select the same options you see in the image. +![setup image example](./documentation_media/intellij_app_setup.png) + +For more information on how the Java scheduling engine works look at this [README file](java/hello-world/README.md) + +## Backend (in the backend directory) +For the backend focused documentation go [here](backend/README.md) +The workspace for all backend realated stuff is `backend` +Note that all the backend APIs are protected and therefore you will need to login to get your JWT tokens. + +__Prerequisites:__ +- **Python >= 3.10 and Poetry** + - I recommend running the command `poetry config virtualenvs.in-project true` because the enviornment will be created in the project folder. + This allows you to select the interpreter from the poetry virtualenv for better development. + - A [guide](https://python-poetry.org/docs/) for poetry setup +- **Docker** + - installation [documentation](https://docs.docker.com/engine/install/) + +__Files needed:__ +- .env placed at `backend` [directory](backend) +```bash +# required +PGADMIN_PASSWORD +POSTGRES_PASSWORD +# optional (defaults shown). For the purpose of the setup leave them out. +POSTGRES_USER=admin +POSTGRES_DB=scheduling +# change if you like +PGADMIN_EMAIL=example@example.com +``` +- .env placed at `backend/django_backend/scheduling_backend` [directory](backend/django_backend/scheduling_backend) +```bash +# required +POSTGRES_HOST=localhost +POSTGRES_PASSWORD +``` + +Start the Docker services from within the `backend` folder by running: +```bash +docker compose up -d +poetry env use python3 +poetry install +``` + +This should start of up the PostgreSQL (database), pgadmin (monitoring), and the Django backend. +Note that the suetup will mount the `backend/django_backend` directory into the continaer so development inside that directory on your host machine will be reflected in the container and vice versa + +**Setting up the Database** +If you have been given a `.dump` file then we can use it create our database tables and populate them by doing the following: +```bash +# This is assuming you kept the default in the .env file in your backend +# If this fails to run it could be because you have something else connected to the database +docker exec -i postgres-service pg_restore -d scheduling -U admin --clean --create < db.dump +``` + +__Running the backend__ +In either option the Java scheduling engine will assume that the server is listening on port `8002` + +Option 1: Docker +```bash +#first command necessary if container isn't running +docker start +docker exec -it django_service bash +#you should now be in the continaer +cd scheduling_backend/ +poetry run python -m manage run server 0.0.0.0:8002 +``` +Option 2: host machine +Navigate to `backend/django_backend/scheduling_backend` and run +``` +poetry run python -m manage run server 0.0.0.0:8002 +``` + +## Contributing +To keep the code base organized and reduce uncessary conflicts, don't push directly to stable and instead follow the guide below +1. Pull the lastest `stable` branch +``` +git checkout stable +git pull stable +``` +2. Create your own branch from `stable` +``` +git checkout -b your_feature +``` +3. Make your updates and push them to your branch +``` +git add . +git commit -m "your helpful commit message" +git push +``` +4. Make your pull request. This will trigger a CI workflow which will run tests + + +## What's next +- Refactor the Java engine file structure so tests can run in CI using the correct resource directories. +- Ensure ingested backend files always include correct instructor emails. The backend supports this, but the relevant code is currently commented out. diff --git a/backend/README.md b/backend/README.md index 19466ba5..6e1bf643 100644 --- a/backend/README.md +++ b/backend/README.md @@ -1,51 +1,107 @@ # Backend workspace -This workspace is soley dedicated to the backend. The backend has the default settings for to give authentication using JWT tokens and all api endpoints by default have authentication by default. In other words, the access token provided will be needed for accessing all api endpoints unless the api endpoint explicitly disabled auth. Ontop of authentication, authorization is also enabled across all endpoints using role based access control (RBAC). +This workspace is soley dedicated to the backend. +The backend has the default settings to include authentication using JWT tokens on all api endpoints. +In other words, and access token will be needed for accessing all api endpoints unless the api endpoint explicitly disabled auth. On top of authentication, authorization is also enabled across all endpoints using role based access control (RBAC). Roles can be created, managed, and assigned through the django admin. Furthermore, users can be created and managed through the django admin. -# Backend sevices setup -All backend services can be quickly setup using the docker compose file. A .env file will be needed in this directory (backend) as show below. The optional values have defaults in the docker compose file. If you use your own values, the DB backup command will need slight changes. The pgadmin variables will be needed for logging into the pgadmin. The Postgres variables will be need to connect to the db. +This guide of the backend will assume that you have everything backend related already setup from the [README](../README.md) file in the repo root. -The database has its own container built on the PostgreSQL image. +# PostgreSQL DB +The databse default name where everything is stored is called `scheduling` unless you otherwise specified in the `.env` file used when creating the service. -The backend has contiainer is built on a base python image. +There are 3 main tables called `api_history`, `api_teacher`, and `api_survey`. +The `teaher` table contains information about the teachers. +The `history` table keeps a record of names that teachers have had before. +This table has a many-to-one relationship to the `teacher` table. +The `survey` table keeps a record of surveys a teacher has. +This table has a many-to-one relationship to the `teacher` table. -The container used for monitoring is built using the PgAdmin image. -``` -#your .env file -POSTGRES_PASSWORD=${PASSWORD:-yourPostgresPassword} -PGADMIN_PASSWORD=${PASSWORD:-yourPgadminPassword} +The other tables you will encounter in the scheduling database are those setup by django to handle permissions and users. -#optional -PGADMIN_EMAIL=...... -POSTGRES_USER=...... -POSTGRES_DB=...... -``` -# Backend documentation -Another .env file will be needed from the backend. Location of this is basically wherever you launch the `manage.py` in `django_backend/scheduling_backend`. The `.env` file variables will be like the below. -``` -#this is the .env file for django backend -POSTGRES_PASSWORD=passwordFromDockerComposeFile -POSTGRES_HOST=hostUrlOfPostgres -``` -Api endpoint documentation is all in the Postman workspace. -# Quick overview -The api endpoint for getting tokens is {base_url}/api/token. +For information about the columns look at the pgAdmin [section](#pgadmin) to learn about inspecting the tables. -The teacher endpoints are at ```{base_url}/api/teachers/```. The survey endpoints are at ```{base_url}/api/surveys/```. The teacher endpoints are at ```{base_url}/api/history/```. +Note that when we are backing up or restoring the DB we shouldn't have anything connected to the database +__Backing up the DB__ +`docker exec postgres-service pg_dump -Fc -U admin scheduling > db.dump` -# Backing up the PostgreSQL DB -## Command to backup -docker exec postgres-service pg_dump -Fc -U admin scheduling > db.dump +__Restoring the DB from a backup__ +`docker exec -i postgres-service pg_restore -d postgres -U admin --clean --create < db.dump` -## Command to restore -docker exec -i postgres-service pg_restore -d postgres -U admin --clean --create < db.dump +Note that when using the commands, you can't be connected to the scheduling database. It must be some other db. If you want to know what db's are available, +run the command `docker exec -it postgres-service psql -U admin -d scheduling` to open a connection and shell in the container. +Then type `\l` to see the available DBs. -Note that when using the command the db you connect to can't be scheduling. It must be some other db. If you want to know what db's are available -run the command 'docker exec -it postgres-service psql -U admin -d scheduling' to open connection and shell then type '\l' to see the available DBs. +# pgAdmin +PG admin is one of the services created in the docker compose file. +This can be used to check what databases are setup, what tables exist, run SQL queries on a database, and many other things. +In order to do those things go to `http://localhost:15432/login?next=/` to log into your pgAdmin account. +Your credentials should be those from your .env file used when running `docker compose up`. The default username/email is example@example.com. -Note that when restoring to the scheduling database, you can't have any connection open to it. +Once you have loged in: +1. In the Object Explorer side tab we will right click Servers -> register -> server. +Then you should see a window appear. +2. In the `general` tab, give you server a name. It can be any name. +3. Navigate to the `Connection` tab. +Then enter `db` for the host name and enter the username and password from your `.env` file used for docker compose. +If your `.env` file didn't have a username then the default will be `admin`. +4. toggle the `Save password?` on, so we don't have to reenter our password. +5. Save the server. If you have an error make sure PostgreSQL is running. +6. Expand the new server you created, expand the databases, and select the scheduling database. +7. In the tool bar in the Object Explorer pane, click the button that looks like the database with a play button +8. You should see a new tab open that will allow you to run SQL queries and see the results of those queries -# Workflow -test it \ No newline at end of file +To inspect the tables click on servers -> the server you just setup -> Databases -> scheduling -> Schemas -> public -> Tables + +Example setup +![pgAdmin example setup](../documentation_media/pgadmin_example.png) + + + +# The Django Backend +__Quick overview__ + +The api endpoint for getting tokens is `{base_url}/api/token`. +The teacher endpoints are at ```{base_url}/api/teachers/```. +The survey endpoints are at ```{base_url}/api/surveys/```. +The history endpoints are at ```{base_url}/api/history/```. + +Another `.env` file will be needed for the backend as mentioned in the README file in the root directory. +The location of this is basically wherever you launch the `manage.py` in `django_backend/scheduling_backend`. +However, my instructions assume you have it in the same directory as `manage.py` (`./django_backend/scheduling_backend/`) + +All Django related files are in the `./django_backend/scheduling_backend` directory + +API endpoint documentation is all in the Postman workspace or upload this +[file](./documentation_media/backend_postman_docs.json) to your postman workspace. +When using the workspace make sure create and enviornment and the variables `base_url` and `jwt_access_token` are in it. +To get your access token, use the `JWT token pair` request example and copy the access token into your enviornemnt. + +Examples +![Postman enviornment example](../documentation_media/postman_env.png) +![Postman authentication example](../documentation_media/postman_auth.png) + + +__Creating users and permissions__ +If you setup the database with a `.dump` file given to you, you should have a superuser already. Otherwise run the following command +from the `./django_backend/scheduling_backend/` directory: `poetry run python -m manage createsuperuser`. + +Once you have a superuser go to http://localhost:8002/admin, port may vary depending on the port you gave when running the server. +Log into the admin portal and you should now be able manage users and persmissions + +# Django Admin Portal + +The Django admin portal provides a built-in interface for managing users and permissions within the application. + +Through this portal, administrators can: + +- Create, update, and delete user accounts +- Assign and manage user permissions +- Organize users into groups for easier permission management +- Control access to different parts of the application based on roles + +This makes it easy to manage authentication and authorization without needing to write custom interfaces. + +# CI workflows +The django backend comes with a test suite that can be ran. This same test suite will run when you make a pull request to merge into the `stable` branch. \ No newline at end of file diff --git a/documentation_media/backend_postman_docs.json b/documentation_media/backend_postman_docs.json new file mode 100644 index 00000000..dcf0d77f --- /dev/null +++ b/documentation_media/backend_postman_docs.json @@ -0,0 +1,603 @@ +{ + "info": { + "_postman_id": "43b83109-87bc-4d3e-a362-2206f72fea5c", + "name": "Backend Usage Examples", + "description": "This template contains a boilerplate for documentation that you can quickly customize and reuse.\n\n### How to use this template:\n\n- Replace the content given brackets (()) with your API's details.\n- Tips are formatted in `codespan` - feel free to read and remove them.\n \n\n---\n\n`Start with a brief overview of what your API offers.`\n\nThe ((product name)) provides many API products, tools, and resources that enable you to ((add product value here)).\n\n`You can also list the APIs you offer, link to the relevant pages, or do both in this section.`\n\n## **Getting started guide**\n\n`List the steps or points required to start using your APIs. Make sure to cover everything required to reach success with your API as quickly as possible.`\n\nTo start using the ((add APIs here)), you need to -\n\n`The points given below are from The Postman API's documentation. You can reference it to write your own getting started guide.`\n\n- You must use a valid API Key to send requests to the API endpoints. You can get your API key from Postman's [integrations dashboard](https://go.postman.co/settings/me/api-keys).\n- The API has [rate and usage limits](https://learning.postman.com/docs/developer/postman-api/postman-api-rate-limits/).\n- The API only responds to HTTPS-secured communications. Any requests sent via HTTP return an HTTP 301 redirect to the corresponding HTTPS resources.\n- The API returns request responses in JSON format. When an API request returns an error, it is sent in the JSON response as an error key.\n \n\n## Authentication\n\n`Add details on the authorization keys/tokens required, steps that cover how to get them, and the relevant error codes.`\n\nThe ((product name)) API uses ((add your API's authorization type)) for authentication.\n\n`The details given below are from the Postman API's documentation. You can reference it to write your own authentication section.`\n\nPostman uses API keys for authentication. You can generate a Postman API key in the [API keys](https://postman.postman.co/settings/me/api-keys) section of your Postman account settings.\n\nYou must include an API key in each request to the Postman API with the X-Api-Key request header.\n\n### Authentication error response\n\nIf an API key is missing, malformed, or invalid, you will receive an HTTP 401 Unauthorized response code.\n\n## Rate and usage limits\n\n`Use this section to cover your APIs' terms of use. Include API limits, constraints, and relevant error codes, so consumers understand the permitted API usage and practices.`\n\n`The example given below is from The Postman API's documentation. Use it as a reference to write your APIs' terms of use.`\n\nAPI access rate limits apply at a per-API key basis in unit time. The limit is 300 requests per minute. Also, depending on your plan, you may have usage limits. If you exceed either limit, your request will return an HTTP 429 Too Many Requests status code.\n\nEach API response returns the following set of headers to help you identify your use status:\n\n| Header | Description |\n| --- | --- |\n| `X-RateLimit-Limit` | The maximum number of requests that the consumer is permitted to make per minute. |\n| `X-RateLimit-Remaining` | The number of requests remaining in the current rate limit window. |\n| `X-RateLimit-Reset` | The time at which the current rate limit window resets in UTC epoch seconds. |\n\n### 503 response\n\nAn HTTP `503` response from our servers indicates there is an unexpected spike in API access traffic. The server is usually operational within the next five minutes. If the outage persists or you receive any other form of an HTTP `5XX` error, [contact support](https://support.postman.com/hc/en-us/requests/new/).\n\n### **Need some help?**\n\n`Add links that customers can refer to whenever they need help.`\n\nIn case you have questions, go through our tutorials ((link to your video or help documentation here)). Or visit our FAQ page ((link to the relevant page)).\n\nOr you can check out our community forum, there’s a good chance our community has an answer for you. Visit our developer forum ((link to developer forum)) to review topics, ask questions, and learn from others.\n\n`You can also document or add links to libraries, code examples, and other resources needed to make a request.`", + "schema": "https://schema.getpostman.com/json/collection/v2.1.0/collection.json", + "_exporter_id": "46090595" + }, + "item": [ + { + "name": "Authentication/Authorization", + "item": [ + { + "name": "JWT token pair", + "request": { + "method": "POST", + "header": [], + "body": { + "mode": "raw", + "raw": "{\r\n \"username\": \"yourusername\",\r\n \"password\": \"yourpassword\"\r\n}", + "options": { + "raw": { + "language": "json" + } + } + }, + "url": { + "raw": "{{base_url}}/api/token/", + "host": [ + "{{base_url}}" + ], + "path": [ + "api", + "token", + "" + ] + }, + "description": "The tokens are necessary to access all the endpoints. The `access token` is need when connecting to an endpoint for authentication. If this token expires, you can use the `refresh token` to send it to the [JWT new access token](https://eman-9291839.postman.co/workspace/Scheduling~6f11bb04-21c1-43e4-b125-5df67e856ccb/request/46090595-2adee7c2-cc6a-4c2e-9ebd-8cda973293dd?action=share&source=copy-link&creator=46090595&ctx=documentation) endpoint to get a new access token. Alternatively you could just got another pair of tokens. If the `refresh token` expires then you will have call this endpoint again.." + }, + "response": [] + }, + { + "name": "JWT new access token", + "request": { + "method": "POST", + "header": [], + "body": { + "mode": "raw", + "raw": "{\r\n \"refresh\": \"your_refresh_token_here\"\r\n}", + "options": { + "raw": { + "language": "json" + } + } + }, + "url": { + "raw": "{{base_url}}/api/token/refresh/", + "host": [ + "{{base_url}}" + ], + "path": [ + "api", + "token", + "refresh", + "" + ] + }, + "description": "Gives you a way to get a new token without logging back in. All you need is your refresh token" + }, + "response": [] + } + ] + }, + { + "name": "Teacher", + "item": [ + { + "name": "Retrieve all teachers", + "request": { + "auth": { + "type": "bearer", + "bearer": [ + { + "key": "token", + "value": "{{jwt_access_token}}", + "type": "string" + } + ] + }, + "method": "GET", + "header": [], + "url": { + "raw": "{{base_url}}/api/teachers/", + "host": [ + "{{base_url}}" + ], + "path": [ + "api", + "teachers", + "" + ] + }, + "description": "Retrieves all Teacher records in the database. If you want to query via department or faculty specifically look at [this](https://eman-9291839.postman.co/workspace/Scheduling~6f11bb04-21c1-43e4-b125-5df67e856ccb/request/46090595-df8f94eb-d5ce-480b-9bb8-914b71084146?action=share&source=copy-link&creator=46090595&ctx=documentation) for examples." + }, + "response": [] + }, + { + "name": "Retrieve by department and faculty", + "request": { + "auth": { + "type": "bearer", + "bearer": [ + { + "key": "token", + "value": "{{jwt_access_token}}", + "type": "string" + } + ] + }, + "method": "GET", + "header": [], + "url": { + "raw": "{{base_url}}/api/teachers/?department=csc&faculty=true&logic=or", + "host": [ + "{{base_url}}" + ], + "path": [ + "api", + "teachers", + "" + ], + "query": [ + { + "key": "department", + "value": "csc" + }, + { + "key": "faculty", + "value": "true" + }, + { + "key": "logic", + "value": "or" + } + ] + }, + "description": "The valid departments query optoins are \"cpe\" and \"csc\"; valid faculty query options are \"true\" and \"false\"; valid logic options are \"or\" and \"and\".\n\nQuery parameter options: \n`department`: \"cpe\", \"csc\"\n\n`faculty`: \"true\", \"false\"\n\n`logic`: \"or\", \"and\" (default) if not used\n\nWhen querying by both department and faculty, if no logic option is given then it will default to returning Teacher records that have both the department and facuty option given.\n\nIf not query by department or faculty is given, then it will return all Teacher records in the database;\n\nDoing `{{base_url}}/api/teachers/`" + }, + "response": [] + }, + { + "name": "Retrieve teacher by ID", + "request": { + "auth": { + "type": "bearer", + "bearer": [ + { + "key": "token", + "value": "{{jwt_access_token}}", + "type": "string" + } + ] + }, + "method": "GET", + "header": [], + "url": { + "raw": "{{base_url}}/api/teachers/5/", + "host": [ + "{{base_url}}" + ], + "path": [ + "api", + "teachers", + "5", + "" + ] + }, + "description": "Retrive a specific \"Teacher\" object in the database using their primary key (integer)." + }, + "response": [] + }, + { + "name": "Create teacher", + "request": { + "auth": { + "type": "bearer", + "bearer": [ + { + "key": "token", + "value": "{{jwt_access_token}}", + "type": "string" + } + ] + }, + "method": "POST", + "header": [ + { + "key": "Content-Type", + "value": "application/json" + } + ], + "body": { + "mode": "raw", + "raw": "[\r\n {\"canon\": \"eman\", \"non_canon\": \"edog\", \"email\": \"theOne@theOne.him\", \"cpe\": true, \"csc\": true, \"faculty\": true},\r\n {\"canon\": \"Norris, Lando\", \"non_canon\": \"papaya\", \"email\": \"norris@f1.champ\"},\r\n {\"canon\": \"Perez, Sergio\", \"non_canon\": \"Mexican Minister of Defense\" }\r\n]", + "options": { + "raw": { + "language": "json" + } + } + }, + "url": { + "raw": "{{base_url}}/api/teachers/create/", + "host": [ + "{{base_url}}" + ], + "path": [ + "api", + "teachers", + "create", + "" + ] + }, + "description": "This endpoint requires you to send a valid json payload. This payload can be a list of json objects or a json object. Look at the Body tab of the request for an example.\n\nThe valid fields for the payload are:\n\n```\n(REQUIRED, chars) canon: max_length=100, unique\n(REQUIRED, chars) non_canon: max_length=100, unique\n(OPTIONAL, email) email: unique, null, blank=True;\n(OPTIONAL, boolean) cpe: default=False\n(OPTIONAL, boolean) csc: default=False\n(OPTIONAL, boolean) faculty: default=False\n\n ```\n\nFor the boolean fields: you could use true or false as in the example body. Also, django allows for strings as seen in this [source code snippet](https://github.com/django/django/blob/9cc231e8243091519f5d627cd02ee40bbb853ced/django/db/models/fields/__init__.py#L1170).\n\nThe names used for the canon and non-canon fields will be stored in another table for potential future use." + }, + "response": [] + }, + { + "name": "creation/update via file", + "request": { + "auth": { + "type": "bearer", + "bearer": [ + { + "key": "token", + "value": "{{jwt_access_token}}", + "type": "string" + } + ] + }, + "method": "POST", + "header": [], + "body": { + "mode": "formdata", + "formdata": [ + { + "key": "file", + "type": "file", + "uuid": "7be3bade-0efa-49ad-8ff9-2ff41c0b2bcd", + "src": "postman-cloud:///1f0f718e-94f4-4ed0-b4c4-a647f94d03c0" + } + ] + }, + "url": { + "raw": "{{base_url}}/api/teachers/file/", + "host": [ + "{{base_url}}" + ], + "path": [ + "api", + "teachers", + "file", + "" + ] + }, + "description": "This endpoint will take in a file (excel, tsv, or csv) with columns `email`, `name` or `non_canon` (this column being the non-canon teacher's name), and `canon`. Furthermore it allows for optional `faculty` boolean column (use `true` or `false` values). For each row in the file, a unique `teacher` will be searched for with the given column fields. If a unique `teacher` is found its email, canon name and non-canon name will be updated. If one is not found then a new Teacher object will be created. If multiple teacher objects for a row then it will be marked skipped and marked as a failure.\n\nEmail field for a row can be left blank. Recommended to include the other two column fields.\n\nNote, when a `Teacher` object is created/found, the names they are given will be stored in the `history` table to keep a record of who has had the most recent name.\n\nNote, if a `Teacher` object can't be found by name in the `teacher` table, the endpoint will fall back to look for a name in the `history` table.\n\n**Example file contents:**\n\n| **email** | **name** | **canon** | **faculty** |\n| --- | --- | --- | --- |\n| [sandler@example.com](https://mailto:sandler@example.com) | Happy Gilmore | Sandler, Adam | false |\n| [rick@example.com](https://mailto:rick@example.com) | Rick Roll | Astley, Rick | |\n| | World cup champ | Messi | false |\n| [sandler@example.com](https://mailto:sandler@example.com) | Rick Roll | Messi | |\n\n**Resulting Endpoint response:**\n\n``` json\n{\n \"msg\": \"finished trying to update teachers\",\n \"success\": [\n {\n \"creation_status\": false,\n \"teacher\": {\n \"id\": 125,\n \"canon\": \"Sandler, Adam\",\n \"non_canon\": \"Happy Gilmore\",\n \"email\": \"sandler@example.com\",\n \"cpe\": false,\n \"csc\": false,\n \"faculty\": false\n }\n },\n {\n \"creation_status\": false,\n \"teacher\": {\n \"id\": 126,\n \"canon\": \"Astley, Rick\",\n \"non_canon\": \"Rick Roll\",\n \"email\": \"rick@example.com\",\n \"cpe\": false,\n \"csc\": false,\n \"faculty\": false\n }\n },\n {\n \"creation_status\": false,\n \"teacher\": {\n \"id\": 113,\n \"canon\": \"Messi\",\n \"non_canon\": \"World cup champ\",\n \"email\": null,\n \"cpe\": false,\n \"csc\": false,\n \"faculty\": false\n }\n }\n ],\n \"failed\": [\n {\n \"msg\": \"Multiple teacher entities with given fields\",\n \"attempt\": {\n \"canon\": \"Messi\",\n \"non_canon\": \"Rick Roll\",\n \"email\": \"sandler@example.com\"\n }\n }\n ]\n}\n\n ```" + }, + "response": [] + }, + { + "name": "bulk update", + "request": { + "auth": { + "type": "bearer", + "bearer": [ + { + "key": "token", + "value": "{{jwt_access_token}}", + "type": "string" + } + ] + }, + "method": "PATCH", + "header": [ + { + "key": "Content-Type", + "value": "application/json", + "type": "text" + } + ], + "body": { + "mode": "raw", + "raw": "[\r\n {\r\n \"lookup\": {\"id\": 10000, \"canon\": \"Perez, Sergio\"}, \r\n \"update_data\": {\"email\": \"theReturn@cadillac.org\", \"faculty\": true, \"random_invalid\": \"has no effect\"}\r\n }, \r\n {\r\n \"lookup\": {\"email\": \"norris@f1.champ\", \"canon\": \"eman\"}, \r\n \"update_data\": {\"email\": \"This entity update will fail\"}\r\n },\r\n {\r\n \"lookup\": {\"id\": 10000}, \r\n \"update_data\": {\"canon\": \"will fail\"}\r\n }\r\n]", + "options": { + "raw": { + "language": "json" + } + } + }, + "url": { + "raw": "{{base_url}}/api/teachers/update/bulk/", + "host": [ + "{{base_url}}" + ], + "path": [ + "api", + "teachers", + "update", + "bulk", + "" + ] + }, + "description": "This api should be used to update teacher entities in bulk. It will allow you to get a techer entity by their id (Primary Key), canon name, non canon name, or email. You can search by all of these simultaneously as well. You can update any part of a teacher entity except for its id (Primary Key).\n\nThe payload must be a list of objects, where each object has they keys `lookup` and `update_data` mapped to an object. The `lookup` object must have at least on of the following keys: `id, email, canon, non_canon`. The `update_data` object must have at least on of the following keys: `canon, non_canon, email, cpe, csc, faculty`. Note, any other keys in either the `lookup` or `update_data` mapped objects will be ignored.\n\nIf all the objects in the list are valid then the api will attempt to update all and report back which objects resulted in a succesful update and which failed.\n\nExample payload (Note, at least one key-value pair must be present in the `lookup` and `update_data` objects):\n\n``` json\n[\n {\n \"lookup\": {\"id\": 10000, \"canon\": \"Perez, Sergio\"}, \n \"update_data\": {\"email\": \"theReturn@cadillac.org\", \"faculty\": true, \"random_invalid\": \"has no effect\"}\n }, \n {\n \"lookup\": {\"email\": \"norris@f1.champ\", \"canon\": \"eman\"}, \n \"update_data\": {\"email\": \"This entity update will fail\"}\n },\n {\n \"lookup\": {\"id\": 10000}, \n \"update_data\": {\"canon\": \"will fail assuming 'id' isn't a primary key in the DB\"}\n }\n]\n\n ```\n\nExample response:\n\n``` json\n{\n \"msg\": \"finished trying to update teachers\",\n \"success\": [\n {\n \"msg\": \"success updating teacher with lookup: {'id': 10000, 'canon': 'Perez, Sergio'}\",\n \"teacher_data\": {\n \"id\": 85,\n \"canon\": \"Perez, Sergio\",\n \"non_canon\": \"Mexican Minister of Defense\",\n \"email\": \"theReturn@cadillac.org\",\n \"cpe\": false,\n \"csc\": false,\n \"faculty\": true\n }\n }\n ],\n \"failed\": [\n {\n \"msg\": \"failed to update teacher with lookup: {'email': 'norris@f1.champ', 'canon': 'eman'}\",\n \"error\": \"get() returned more than one Teacher -- it returned 2!\"\n },\n {\n \"msg\": \"failed to update teacher with lookup: {'id': 10000}\",\n \"error\": \"Teacher matching query does not exist.\"\n }\n ]\n}\n\n ```" + }, + "response": [] + }, + { + "name": "Delete teacher by ID", + "request": { + "auth": { + "type": "bearer", + "bearer": [ + { + "key": "token", + "value": "{{jwt_access_token}}", + "type": "string" + } + ] + }, + "method": "DELETE", + "header": [], + "url": { + "raw": "{{base_url}}/api/teachers/124/", + "host": [ + "{{base_url}}" + ], + "path": [ + "api", + "teachers", + "124", + "" + ] + }, + "description": "Deletes a \"Teacher\" object in the database using its primary key (integer)." + }, + "response": [] + } + ] + }, + { + "name": "History", + "item": [ + { + "name": "Find teacher", + "protocolProfileBehavior": { + "disableBodyPruning": true + }, + "request": { + "auth": { + "type": "bearer", + "bearer": [ + { + "key": "token", + "value": "{{jwt_access_token}}", + "type": "string" + } + ] + }, + "method": "GET", + "header": [], + "body": { + "mode": "formdata", + "formdata": [] + }, + "url": { + "raw": "{{base_url}}/api/history/?name=Stephen Beard", + "host": [ + "{{base_url}}" + ], + "path": [ + "api", + "history", + "" + ], + "query": [ + { + "key": "name", + "value": "Stephen Beard" + } + ] + }, + "description": "Endpoint allows you to query the History table by a teacher's name. If there is a hit the corresponding History record is returned.\n\nWhile this endpoint probably won't be used on it's own it could be useful for seeing if something exists in the DB\n\n``` json\n{\n \"msg\": \"History record matching query found\",\n \"data\": {\n \"id\": 7,\n \"is_canon\": true,\n \"name\": \"Messi\",\n \"teacher\": 113\n }\n}\n\n ```" + }, + "response": [] + }, + { + "name": "Delete by ID", + "request": { + "auth": { + "type": "bearer", + "bearer": [ + { + "key": "token", + "value": "{{jwt_access_token}}", + "type": "string" + } + ] + }, + "method": "DELETE", + "header": [] + }, + "response": [] + } + ] + }, + { + "name": "Survey", + "item": [ + { + "name": "Survey Uploads", + "request": { + "auth": { + "type": "bearer", + "bearer": [ + { + "key": "token", + "value": "{{jwt_access_token}}", + "type": "string" + } + ] + }, + "method": "POST", + "header": [], + "body": { + "mode": "formdata", + "formdata": [ + { + "key": "file", + "type": "file", + "uuid": "5b0d194b-2259-4915-94f0-bb8109657634", + "src": "///wsl.localhost/Ubuntu/home/eman/SeniorProject/backend/test_files/test_survey.csv" + }, + { + "key": "cur_term", + "value": "2254", + "type": "text", + "uuid": "be017435-a426-4fb4-88d0-0633637cf2a4" + }, + { + "key": "prev_term", + "value": "2252", + "type": "text", + "uuid": "788bbdf1-5501-4097-a22d-9b5456cf97fe" + } + ] + }, + "url": { + "raw": "{{base_url}}/api/surveys/file/", + "host": [ + "{{base_url}}" + ], + "path": [ + "api", + "surveys", + "file", + "" + ] + }, + "description": "Assuming the current quarter is 2254 and the previous is 2252. If a teacher bleeds forward it is assumed the bleed forward survey field is \"Yes, use the same as last term\".\n\n``` json\n{\n \"msg\": \"finish endpoint\",\n \"success\": [\n {\n \"msg\": \"teacher\",\n \"suvey_id\": 7,\n \"creation\": true,\n \"teacher_file_idx\": 0,\n \"teacher\": {\n \"id\": 85,\n \"canon\": \"Perez, Sergio\",\n \"non_canon\": \"Mexican Minister of Defense\",\n \"email\": \"theReturn@cadillac.org\",\n \"cpe\": false,\n \"csc\": false,\n \"faculty\": false\n }\n }\n ],\n \"failed\": []\n}\n\n ```\n\nAssuming the current quarter is 2258 and the previous is 2254\n\n``` json\n{\n \"msg\": \"finish endpoint\",\n \"success\": [\n {\n \"msg\": \"teacher\",\n \"suvey_id\": 8,\n \"creation\": true,\n \"teacher_file_idx\": 1,\n \"teacher\": {\n \"id\": 85,\n \"canon\": \"Perez, Sergio\",\n \"non_canon\": \"Mexican Minister of Defense\",\n \"email\": \"theReturn@cadillac.org\",\n \"cpe\": false,\n \"csc\": false,\n \"faculty\": false\n }\n },\n {\n \"msg\": \"teacher\",\n \"suvey_id\": 8,\n \"creation\": false,\n \"teacher_file_idx\": 2,\n \"teacher\": {\n \"id\": 85,\n \"canon\": \"Perez, Sergio\",\n \"non_canon\": \"Mexican Minister of Defense\",\n \"email\": \"theReturn@cadillac.org\",\n \"cpe\": false,\n \"csc\": false,\n \"faculty\": false\n }\n }\n ],\n \"failed\": [\n {\n \"msg\": \"suvery bled forward, but no previous survey found for the 2254 term\",\n \"teacher_file_idx\": 0,\n \"teacher\": {\n \"id\": 84,\n \"canon\": \"Norris, Lando\",\n \"non_canon\": \"papaya\",\n \"email\": \"norris@f1.champ\",\n \"cpe\": false,\n \"csc\": false,\n \"faculty\": false\n }\n },\n {\n \"msg\": \"No teacher found in Teacher's table. Fell back to History table and no objects found\",\n \"teacher_file_idx\": 3,\n \"associated_data\": {\n \"non_canon\": \"Does not Exist\"\n }\n }\n ]\n}\n\n ```" + }, + "response": [] + }, + { + "name": "get survey(s)", + "protocolProfileBehavior": { + "disableBodyPruning": true + }, + "request": { + "auth": { + "type": "bearer", + "bearer": [ + { + "key": "token", + "value": "{{jwt_access_token}}", + "type": "string" + } + ] + }, + "method": "GET", + "header": [], + "body": { + "mode": "raw", + "raw": "", + "options": { + "raw": { + "language": "json" + } + } + }, + "url": { + "raw": "{{base_url}}/api/surveys/?term=2254&name=Mexican Minister of Defense&all_flag=true", + "host": [ + "{{base_url}}" + ], + "path": [ + "api", + "surveys", + "" + ], + "query": [ + { + "key": "term", + "value": "2254" + }, + { + "key": "name", + "value": "Mexican Minister of Defense" + }, + { + "key": "all_flag", + "value": "true" + } + ] + }, + "description": "This endpoint will allow you to retrieve `Survey` objects from the `survey` table. Query parameters are to retrieve specific survey objects are `name`, `term`, and `all_flag`. If query parameters are passed, any `survey` object with that has the given parameter value will be returned. However, if the all_flag is set, `survey` objects returned must have all parameter values true.\n\n`name` parameter: name used for the survey(s) (non-canon name).\n\n`term` parmater: term the survey(s) was filled out for\n\n`all_flag` parameter: Valid values `true` and `false`. Flag indicating if all parameters must be set to true in returne survey object(s). If not included the flag is assumed to be false." + }, + "response": [] + }, + { + "name": "delete survey instance", + "request": { + "auth": { + "type": "bearer", + "bearer": [ + { + "key": "token", + "value": "{{jwt_access_token}}", + "type": "string" + } + ] + }, + "method": "DELETE", + "header": [], + "url": { + "raw": "{{base_url}}/api/surveys/1/", + "host": [ + "{{base_url}}" + ], + "path": [ + "api", + "surveys", + "1", + "" + ] + }, + "description": "Delete a `Survey` object in the DB via primairy key." + }, + "response": [] + } + ] + } + ], + "auth": { + "type": "apikey", + "apikey": [ + { + "key": "key", + "value": "X-API-Key", + "type": "string" + }, + { + "key": "value", + "value": "{{token}}", + "type": "string" + } + ] + }, + "event": [ + { + "listen": "prerequest", + "script": { + "type": "text/javascript", + "exec": [ + "" + ] + } + }, + { + "listen": "test", + "script": { + "type": "text/javascript", + "exec": [ + "" + ] + } + } + ], + "variable": [ + { + "key": "baseUrl", + "value": "https://farming-simulator.pstmn.io" + } + ] +} \ No newline at end of file diff --git a/documentation_media/intellij_app_setup.png b/documentation_media/intellij_app_setup.png new file mode 100644 index 00000000..1e8b6fd1 Binary files /dev/null and b/documentation_media/intellij_app_setup.png differ diff --git a/documentation_media/intellij_test_setup.png b/documentation_media/intellij_test_setup.png new file mode 100644 index 00000000..274ca650 Binary files /dev/null and b/documentation_media/intellij_test_setup.png differ diff --git a/documentation_media/pgadmin_example.png b/documentation_media/pgadmin_example.png new file mode 100644 index 00000000..915959bc Binary files /dev/null and b/documentation_media/pgadmin_example.png differ diff --git a/documentation_media/postman_auth.png b/documentation_media/postman_auth.png new file mode 100644 index 00000000..2f2246bc Binary files /dev/null and b/documentation_media/postman_auth.png differ diff --git a/documentation_media/postman_env.png b/documentation_media/postman_env.png new file mode 100644 index 00000000..84b3d574 Binary files /dev/null and b/documentation_media/postman_env.png differ diff --git a/java/hello-world/README.adoc b/java/hello-world/README.adoc deleted file mode 100644 index e85f66dd..00000000 --- a/java/hello-world/README.adoc +++ /dev/null @@ -1,19 +0,0 @@ -= School Timetabling (Java, Maven) - -Assign lessons to timeslots and rooms to produce a better schedule for teachers and students. - -* <> - -[[run]] -== Run the application - - -. Start the application with Maven: -+ -[source, shell] ----- -$ mvn verify -... -$ java -jar target/hello-world-run.jar ----- - diff --git a/java/hello-world/README.md b/java/hello-world/README.md new file mode 100644 index 00000000..763a5cca --- /dev/null +++ b/java/hello-world/README.md @@ -0,0 +1,112 @@ +# The Java Constraint Engine Workplace +The following will assume you have everything setup mentioned in the project root `README.md` file. + +# Important variables +__API connection__ +- `baseURL`: [./src/main/java/org/acme/schooltimetabling/apiCalls/ApiConstants.java](./src/main/java/org/acme/schooltimetabling/apiCalls/ApiConstants.java) +Any code realted to calling the endpoints will be in the apiCalls package. + +You can toggle the usage of the api by modyfing the `useApi` option with `true` or `false` in the config file +([example](./src/main/resources/constants/config.example.yaml)). + +__Constants__ +Most constants used throughout the this tool will be found in +[./src/main/java/org/acme/schooltimetabling/constants/Constants.java](./src/main/java/org/acme/schooltimetabling/constants/Constants.java). +Those constants include: +- `COURSE_CONFIGS`: Course configurations +- `SPECIAL_CODE_CONVERSION`: converting course codes from their abbreviated to non-abbreviated version +- `SKIP_Schedule`: special codes that we don't want to schedule +- `SKIP_CONFIGURATIONS`: class configurations we don't want to schedule +- `CHOSEN_CONFIGURATIONS`: configurations we only want to schedule (this seemed to be recently added in the python version so I have it here); +- `COURSE_TO_ROOMS`: maps courses that are room specific to their allowed rooms +- `STUDIO_STYLE_COURSES`: courses marked as studio style +- `TEACHER_NAME_TO_CANON`: stores teachers mapped to their canon name +- `FACULTY_LAST_NAMES`: stores last names of people who are faculty + +__Faculty times__ +If you want to change what times faculty member shouldn't be scheduled during, go to the file +[./src/main/java/org/acme/schooltimetabling/domain/teacher/Faculty.java](./src/main/java/org/acme/schooltimetabling/domain/teacher/Faculty.java). + +__Console print out__ +There is variable I have that prints out a verbose breakdown of what constraints have been violated. +You can toggle this using the `PRINT_DETAILED_SUMMARY` variable in the file +[./src/main/java/org/acme/schooltimetabling/TimetableApp.java](./src/main/java/org/acme/schooltimetabling/TimetableApp.java). + +# Problem objects +Classes containing planning entities (e.g. lessons) and planning variables (e.g. timeslots) can be found in the package +[./src/main/java/org/acme/schooltimetabling/domain/](./src/main/java/org/acme/schooltimetabling/domain/). +The classes that create instances of those objects are in the package +[./src/main/java/org/acme/schooltimetabling/helperClasses/Generators/](./src/main/java/org/acme/schooltimetabling/helperClasses/Generators/). + +# Saving the results and logs +The result will be saved into a folder in your working directory called `generated` in a file such as `2268_csc_solution.xlsx`. +This excel file will contain 3 sheets. +Those sheets will give you a view of when rooms are occupied, a view showing when instructors are busy, and list view of all the scheduled lessons. +The list view will also contain lessons that couldn't be scheduled and lessons that were skipped. +Lessons that couldn't be scheduled are those violating hard constraints, except those violating the 50/50 primetime constraint used in the aggressive version of the solver. +More information about the solver config phases [here](#configuring-the-solver) and modyfing the constraints +[here](#the-constraints). + +To modify the logging output go to the file [./src/main/resources/logback.xml](./src/main/resources/logback.xml). +The logging outputs will be placed into a directory called `logs` in your working directory. + + +# Configuring the solver phases +To modify and tune the solver solving phases go to the this file [./src/main/resources/solverConfig.xml](./src/main/resources/solverConfig.xml). There are times when the solver might still get stuck and it's better to fail fast and restart it. + +There are three phases: +1. The construction heuristic phase. This phase initializes all problem facts in a planning entity (lessons), prioritizing lessons that require more lab time. +To modify the priority go to the file +[./src/main/java/org/acme/schooltimetabling/domain/lesson/LessonComparator.java](./src/main/java/org/acme/schooltimetabling/domain/lesson/LessonComparator.java). +2. The local search phase: This phase will aim to bring the hard score down to 0 and ends the phase if achieved. +3. The local serach phase: Here I modify the heuristics so we can search more widely. +It also keeps the solver from running too long if there hasn't been any improvments. + + +# The Constraints +To view all constrants go the file +[./src/main/java/org/acme/schooltimetabling/solver/TimetableConstraintProvider.java](./src/main/java/org/acme/schooltimetabling/solver/TimetableConstraintProvider.java). + +In the `config.yaml` you have the ability to use the following settings to control what constraints are added and how they will behave to a certain extent. +- `aggressiveChoice` (options: `NONE`, `AGGRESSIVE`, `AGGRESSIVE_BOTH`, `AGGRESSIVE_PENALTY`, `AGGRESSIVE_REWARD`) + - `NONE`: models prime time as a soft contraint. Rewards time outside of it and penalizes time inside of prime time. + - `AGGRESSIVE`: This will model prime time as a hard constraint. It will penalize only when 50%+ of lecture time is in primetime. + - `AGGRESSIVE_BOTH`: Same as `AGGRESSIVE` + compresses all lectures into a certain time interval and penzalizes lessons outside the interval and reward lessons inside the interval. + I recommend using `AGGRESSIVE_PENALTY`. + - `AGGRESSIVE_REWARD`: Same as `AGGRESSIVE_BOTH` but without the penalty. + - `AGGRESSIVE_PENALTY`: Same as `AGGRESSIVE_BOTH` but without the rewarding. **The recommended one amongst the three** +- `compressStart` and `compressEnd`. +These are used when we choose the `AGGRESSIVE_BOTH`, `AGGRESSIVE_PENALTY`, or `AGGRESSIVE_REWARD` solver options. +The time interval you choose will be the time interval the solver will attempt to squeeze all lessons into. + + + +# Including prescheduled times +If instructors teach in multiple departments, you can include the times they have been already scheduled by providing a file. +The file should be a `json` placed in the [./src/main/resources/input/](./src/main/resources/input/) directory. +An example of the file has been provided in the same directory your file should be placed. + +Once your file containing preshceulded times is placed, create the key in your `config.yaml` named `prescheduledFileName` mapped to the value of your file name, as seen in this example [file](./src/main/resources/constants/config.example.yaml) + + + +# Testing +All testing classes can be found in the +[solver](./src/test/java/org/acme/schooltimetabling/solver/) +and +[TestClasses](./src/test/java/org/acme/schooltimetabling/TestClasses/) package. + +Before running any of these tests make sure that you have set testing option to `true` so all constraints are included and special test +behavior is setup. Look at this +[example](./src/main/resources/constants/config.example.yaml) +config file. + +I have tried to include the configurations for running the tests, so try to hit the drop down menu you see next to the play button on step 5. +Then choose the test you want to run. +If there aren't any or there is a test you want to inlcude, follow the image guide below. + +**Example setup in intellij** +On step 1 you will see pop up. Select `edit` under configuration. +On step 2 you will see a menu and you should choose the `JUnit` option. +On step 3 you will choose the same first 2 options and then choose the test class you want to run. +![example intellij test setup](../../documentation_media/intellij_test_setup.png) diff --git a/java/hello-world/src/main/resources/.example.env b/java/hello-world/src/main/resources/.example.env index 7982cdc4..6437de73 100644 --- a/java/hello-world/src/main/resources/.example.env +++ b/java/hello-world/src/main/resources/.example.env @@ -1,2 +1,4 @@ +#this env file's only purpose is to give us the credentials we need to access the api as an authorized user; +#the user who is given here only needs read only permissions for the "survey" and "teacher" records API_PASSWORD="userPassword" API_USER="userName" \ No newline at end of file