Computational Creativity Course, Spring 2019

The main repository for the group software projects.

Each group should fork this project, contribute to the forked project (by cloning it locally for each group member and pushing to the forked project) and then do pull requests to this project a couple of times during the course. See how to do pull requests and the deadline for the first pull request below.

Relevant links:

• Fork a repo
• About pull requests
• Creating a pull request from a fork

Use Python 3.6+ in the projects forked from this repository.

Repository structure

As each group is ultimately contributing to the same repository, we need to ensure that the groups are working solely on their own code between the pull requests. The following repository structure is defined to meet this need:

# Holds machinery to unite groups' projects. The groups should not add or alter any files in the root folder.
root/
    # Main ignore file for the git. Generally you should not alter this, but create your own at group_folder/.gitignore
    # In case you definitely need to alter this, contact course staff.
    .gitignore
    # Main script to unite the group projects. Will be developed further by the course staff during the course.
    main.py
    # Config file used by main.py to know which project folders to import.
    main_config.json
    # This readme
    README.rst
    # General requirements for the project. See below for details.
    requirements.txt

    # Folder for possible shared resources.
    resources/
        # Some sample inputs the groups can use in their development. Will be developed further during the course.
        sample_inputs.py

        # Some resource generated by the groupX which may be used by other groups.
        groupX_resource.txt

    # Example group's folder
    group_example/
        # Config file used by the root folder's main.py to know:
        # (1) which module to import from the group's folder
        # (2) which class to instantiate from the module
        # (3) which keyword arguments to use when initialising the class instance
        config.json

        # The module holding the class to instantiate. See its source for details.
        main.py

    # Other example group's folder, similar to the above, but with different file name and initialisation arguments
    # to demonstrate config.json
    group_example2/
        config.json
        example.py

    # Your group's folder (created by you, see below)
    your_group_name/
        # Your group's config
        config.json

        # Your group's module to import, specified in config.json.
        rlyeh_is_rising.py

        # Possible sub git ignore file for your needs (e.g. ignore any images created by your creator so that they
        # do not clutter the repository).
        .gitignore

        # Some other stuff you may end up developing
        text_samples.txt
        db.sqlite

The first pull request:

Create your first pull request after you have:

1. Forked the repo
2. Made a folder into the repo with your group name
   • Change the group name to match Python module naming, e.g. group "We Are the Best" should have folder "we_are_the_best"
3. Copied contents of the either one of the pre-existing group examples to your folder
4. Changed (the class name and the module name if you so wish and) self.domain of your creator.
5. Reflected the class name and module name changes to your-group-folder/config.json
6. Changed your creator's create-function to return (dummy) artifact(s) in your domain. That is, the returned artifact may pre-exist in your folder.
   • Titles should return str.
   • Poems should return str.
   • Images should return absolute paths to the generated images, either in 'png' or 'jpg' format.
   • Music should return absolute path to either 'wav' (compressed formats are discussable if needed) or to an image file of the generated sheet music in 'png' or 'jpg' format.
   • The return format of other domains should be discussed with the course staff.
7. Remembered to add the metadata dictionary containing 'evaluation' keyword with (dummy) value to each returned artifact.
8. Checked that the code is working by running main.py using main config file (check main_config.json but create another one for testing purposes) containing only your own folder.

Make your first pull request before Sun 17.3. 23.59.

You may have already began your software development in the first pull request (i.e. done more than the points above), but the code must be runnable for each pull request.

Get the code running

1. Fork the repo in github (once per group)
2. Clone your forked repo (for each group member)
3. Install Python 3.6+
4. Create python virtual environment in your cloned repo's root using: python3.6 -m venv env
5. Activate virtualenv using: source env/bin/activate
6. Install general requirements: pip install -r requirements.txt

Now you should be able to run the two example groups using python main.py and see some output (and definitely not any errors).

Anytime you want to work on the code, you need to run step 5. again. You can exit the virtual environment by typing deactivate. You can also configure your IDE, e.g. PyCharm, to use virtual environment.

Libraries included in the general requirements

We have included a set of common packages and some frameworks focusing on particular domains in requirements.txt. They are already included merely for convenience, and you are not required to use any of them. The packages are:

• NumPy: The fundamental library used to do fast numeric computations in Python. Used everywhere.

• SciPy: The library used to do scientific computations.

• Scikit-learn: Machine learning library for Python.

• Scikit-image: Image processing library for Python. Easy to use, but restricted implementations.

• Opencv-python: Python bindings with prebuilt binaries for OpenCV (the computer vision library used by everyone doing CV).

  • The prebuilt binaries included should be available for all the common architectures, thus you do not need to compile OpenCV yourself.

• NLTK: Natural language toolkit for Python. Used for ... wait for it ... natural language processing.

We have not included any deep learning libraries, as there are multiple valid choices. The library choice can be discussed if several groups are using deep learning.

Adding your own dependencies

It is possible (and probable) that you want to add your own code dependencies to your group's project. Generally, all libraries which can be installed using 'pip' can be used. We just need to coordinate between the groups that each group uses the same version of the library.

Add any extra dependencies to your_group_folder/requirements.txt (create one if it does not exist), and mention this in your pull request. The course staff will merge them to the root folder's requirements.txt based on the pull requests and other groups may then install them using pip install -r requirements.txt to ensure coherence between the groups.

If you need to use any libraries which are not found from 'pip', then first evaluate how crucial it would be for your project and contact the course staff if it turns out to be really needed. We will see what we can do. However, as the project's idea is simply to demonstrate computational creativity techniques in practice, the general requirements should be kept to minimum.

Keep your repository in sync

The groups are excepted to sync their own personal repository with the main repository after each pull request (the course staff will announce when this can be done after each round of pull requests). Follow the instructions in Fork a repo and Syncing a fork to achieve this.

After each sync, there might be new dependencies from other groups. These requirements should have been merged to the root folder's requirements.txt.

To obtain the new required libraries and frameworks, run 'pip' again with your virtual environment activated:

> source env/bin/activate
> pip install -r requirements.txt

Operations after week 3 pull requests

1. Sync your repo
2. Install mysqlclient (with your virtual environment activated): pip install mysqlclient
3. Install requirements (in the root folder): pip install -r requirements.txt
4. (Optional) See group_picasso/README.rst for the download link to their prebuilt model.