Getting started

QGen is available through PyPi. So first let's get that with

pip install QGen 

Next, lets think about the types of question we'd like to generate some instances of. Let's start with something simple just to demonstrate how to use QGen. Imagine you're teaching an elementary math class with about 20 students and for their homework you'd like to test how well your students can add two numbers. The question might look like this

What is 11 + 13?

Well, say you wanted to give each student 10 questions. You're a teacher at a modern day school so this institution uses some online learning platform that can help out a bit. Let's take for example Moodle. Ideally you would want each student to see a different set of pairs of numbers so at a higher level the question looks like this

What is {some number} + {some number}?

Okay, so now we have somewhat of an idea of how we'd make our template.

A template for QGen is just a YAML file, so let's start by creating that file and name it say test.yml. First tag will be to name the question, let's call it SimpleAddition and the answer is going to be a number so let's set the type to numerical and let's also give it a reasonable title as well. So the file looks like this now

    title:'Simple addition question ' 
    type:'numerical'```

We also know what we want in the body of the question do let's put that in

`SimpleAddition:
    title:'Simple addition question ' 
    type:'numerical'
    body: >
           What is {some number} + {some number}`

Braces are used in qgen to replace parameters with values, only thing is no spaces are allowed so let's fix that a bit 

`SimpleAddition:
    title:'Simple addition question ' 
    type:'numerical'
    body: >
           What is {num1} + {num2}?`

Now we need to define how to replace {num1} and {num2} on each instance of the question. qgen does that by using a params tag, under params you would name the parameter and specify what generator is to be used. 

`SimpleAddition:
  title:'Simple addition question ' 
  type:'numerical'
  body: >
         What is {num1} + {num2}?
  params:
    num1:
      randint:
        start: 1
        end:100
    num2:
      randint:
        start: 1
        end:100`

In this case the generator used is randint, randint is a built in generator in qgen that generates a random integer within a given range which is defined through named parameters start and end (inclusive).

Now, let's talk about what the answer for each instance of the question should look. As you can imagine answers are defined under the answer tag. So, we need to ensure that the answer is always the sum of whatever replaces {num1} and {num2}. qgen provides a way to evaluate code using Python syntax, we chose Python because it's simple and intuitive syntax seemed best for the task. 

In qgen any text within $ tags are evaluated as Python code. So we need to evaluate the sum of {num1} and {num2} in Python, simply its just {num1} + {num2} but to have it evaluated we enclose as follows  ${num1} + {num2}$. So now we add this to the file

`SimpleAddition:
  title:'Simple addition question ' 
  type:'numerical'
  body: >
         What is {num1} + {num2}?
  params:
    num1:
      randint:
        start: 1
        end:100
    num2:
      randint:
        start: 1
        end:100
  answer:
    -'${num1} + {num2}$'`

We now have a complete file that can be used to generate a large number of questions. Now save this file and let's get back to Python