LaTeX source file
Prev |  | Next

## LaTeX source file

This section describes the LaTeX commands that allows you to design your exam answer sheets from a LaTeX source file. If you chose another format for your source file, you can skip this section. The MCQ can be described as a LaTeX file using the automultiplechoice package. You can check the LaTeX file you are designing at any moment by compiling it with the latex command, then visualizing the resulting dvi file.

We start with a few examples giving quick illustrations of how to build LaTeX files for MCQs; the corresponding tex file are available as templates, so that one can create a new MCQ project starting with one of these templates.

### A simple example

    \documentclass[a4paper]{article}

    \usepackage[utf8x]{inputenc}
    \usepackage[T1]{fontenc}

    \usepackage[box,completemulti]{automultiplechoice}
    \begin{document}

    \onecopy{10}{

    %%% beginning of the test sheet header:

    \noindent{\bf QCM  \hfill TEST}

    \vspace*{.5cm}
    \begin{minipage}{.4\linewidth}
    \centering\large\bf Test\\ Examination on Jan., 1st, 2008\end{minipage}
    \namefield{\fbox{
                    \begin{minipage}{.5\linewidth}
                      Firstname and lastname:

                      \vspace*{.5cm}\namefielddots
                      \vspace*{1mm}
                    \end{minipage}
             }}

    \begin{center}\em
    Duration : 10 minutes.

      No documents allowed. The use of electronic calculators is forbidden.

      Questions using the sign \multiSymbole{} may have
      zero, one or several correct answers.  Other questions have a single correct answer.

      Negative points may be attributed to \emph{very
        bad} answers.
    \end{center}
    \vspace{1ex}

    %%% end of the header

    \begin{question}{prez}
      Among the following persons, which one has ever been a President of the French Republic?
      \begin{choices}
        \correctchoice{René Coty}
        \wrongchoice{Alain Prost}
        \wrongchoice{Marcel Proust}
        \wrongchoice{Claude Monet}
      \end{choices}
    \end{question}

    \begin{questionmult}{pref}
      Among the following cities, which ones are French prefectures?
      \begin{choices}
        \correctchoice{Poitiers}
        \wrongchoice{Sainte-Menehould}
        \correctchoice{Avignon}
      \end{choices}
    \end{questionmult}

    % \AMCaddpagesto{3}

    }

    \end{document}

A few extra details on this example:

| The packages inputenc and fontenc allow one to use the UTF-8 encoding. You can of course modify them depending on the encoding you want to use.
| The options used here for the automultiplechoice LaTeX package prevent questions from being split between two pages (`box`) and to automatically complete any multiple choice question by a standard answer allowing the student to mention that, in her/his opinion, none of the listed answers is correct (`completemulti`).
| The onecopy command produces as many (distinct) realizations of the MCQ test as desired (here 10). See the section called “Description of a copy” for an alternative syntax using an environment.
| Lines that start here describe the header of the test-sheet.
| The namefield command specifies where students write their name or a barcode (see the section called “ With a barcode”). Will be completed with \namefielddots if you use `pdfform` option (see the section called “Package options”).
| The namefielddots command insert a dotted line or a field to fill if the `pdfform` option is avaible (see the section called “Package options”).
| The environments question and choices allow one to build a multiple choice question for which there is a single correct answer. A unique identifier for the question has to be specified (here: prez).
| The environments questionmult and choices allow one to build a multiple choice question that may have zero, one or several correct answers. Student are asked to check all the boxes corresponding to an answer that she/he thinks is correct, or the last box (added automatically thanks to the `completemulti` option used in the reference to the package in line 6).
| Uncomment this line to add enough blank pages to get a 3-pages copy (seethe section called “Number of pages”).
| This marks the end of the onecopy command (started at line 9).

### An example with groups of questions and shuffling

In this example, we want the order in which questions appear in the MCQ test to be different from one realization of the test to the other, but still keeping together questions dealing with the same subject. To this end, we create two groups of questions, within which questions are shuffled at random.

    \documentclass[a4paper]{article}

    \usepackage[utf8x]{inputenc}
    \usepackage[T1]{fontenc}

    \usepackage[box,completemulti]{automultiplechoice}
    \begin{document}

    %%% preparation of the groups

    \setdefaultgroupmode{withoutreplacement}

    \element{geographie}{
      \begin{question}{Paris}
        In which continent is Paris?
        \begin{choices}
          \correctchoice{Europe}
          \wrongchoice{Africa}
          \wrongchoice{Asia}
          \wrongchoice{planet Mars}
        \end{choices}
      \end{question}
    }

    \element{geographie}{
      \begin{question}{Cameroon}
        Which is the capital city of Cameroon?
        \begin{choices}
          \correctchoice{Yaoundé}
          \wrongchoice{Douala}
          \wrongchoice{Abou-Dabi}
        \end{choices}
      \end{question}
    }

    \element{histoire}{
      \begin{question}{Marignan}
        In which year did the battle of Marignan take place?
        \begin{choiceshoriz}
          \correctchoice{1515}
          \wrongchoice{1915}
          \wrongchoice{1519}
        \end{choiceshoriz}
      \end{question}
    }

    \element{histoire}{
      \begin{questionmult}{Nantes}
        What can be said about the \emph{Édit de Nantes}?
        \begin{choices}
          \correctchoice{It was signed in 1598}
          \correctchoice{Il has been revoked by Louis XIV}
          \wrongchoice{It was signed by Henri II}
        \end{choices}
      \end{questionmult}
    }

    %%% copies

    \onecopy{10}{

    %%% beginning of the test sheet header:

    \noindent{\bf QCM  \hfill TEST}

    \vspace*{.5cm}
    \begin{minipage}{.4\linewidth}
      \centering\large\bf History and geography\\ Examination on Jan. 1st, 2008
    \end{minipage}
    \namefield{\fbox{\begin{minipage}{.5\linewidth}
    Firstname and lastname:

    \vspace*{.5cm}\dotfill
    \vspace*{1mm}
    \end{minipage}}}

    %%% end of the header

    \begin{center}
      \hrule\vspace{2mm}
      \bf\Large Geography
      \vspace{1mm}\hrule
    \end{center}

    \insertgroup{geographie}

    \begin{center}
      \hrule\vspace{2mm}
      \bf\Large History
      \vspace{2mm}\hrule
    \end{center}

    \insertgroup{histoire}

    }

    \end{document}

### An example with a separate answer sheet

In this example, one wants the check-boxes to be put together in a separate sheet. This makes cheating more difficult, and, more importantly, it is enough to scan a single sheet per student, which makes things easier if one has to do a manual scan. In this example, the number of questions is limited: they fit into a single page, so that such a layout would not be really useful in this particular case. It is up to you to modify this example in order to use this layout with a large number of questions!

    \documentclass[a4paper]{article}

    \usepackage[utf8x]{inputenc}
    \usepackage[T1]{fontenc}

    \usepackage[box,completemulti,separateanswersheet]{automultiplechoice}
    \begin{document}

    \AMCrandomseed{1237893}

    \def\AMCformQuestion#1{{\sc Question #1:}}

    \setdefaultgroupmode{withoutreplacement}

    \element{general}{
      \begin{question}{prez}
        Among the following persons, which one has ever been a President of the French Republic?
        \begin{choices}
          \correctchoice{René Coty}
          \wrongchoice{Alain Prost}
          \wrongchoice{Marcel Proust}
          \wrongchoice{Claude Monet}
        \end{choices}
      \end{question}
    }

    \element{general}{
      \begin{questionmult}{pref}
        Among the following cities, which ones are French prefectures?
        \begin{choices}
          \correctchoice{Poitiers}
          \wrongchoice{Sainte-Menehould}
          \correctchoice{Avignon}
        \end{choices}
      \end{questionmult}
    }

    \element{general}{
      \begin{question}{nb-ue}
        How many different states were members of the European Union in Jan. 2009?
        \begin{choiceshoriz}[o]
          \wrongchoice{15}
          \wrongchoice{21}
          \wrongchoice{25}
          \correctchoice{27}
          \wrongchoice{31}
        \end{choiceshoriz}
      \end{question}
    }

    \onecopy{5}{

    %%% beginning of the test sheet header:

    \noindent{\bf QCM  \hfill TEST}

    \vspace*{.5cm}
    \begin{minipage}{.4\linewidth}
      \centering\large\bf Test\\ Examination on Jan. 1st, 2008
    \end{minipage}

    \begin{center}\em
    Duration : 10 minutes.

      No documents allowed. The use of electronic calculators is forbidden.

      Questions using the sign \multiSymbole{} may have
      zero, one or several correct answers.  Other questions have a single correct answer.

      Negative points may be attributed to \emph{very
        bad} answers.

    \end{center}
    \vspace{1ex}

    %%% end of the header

    \insertgroup{general}

    \AMCcleardoublepage

    % \AMCaddpagesto{3}

    \AMCformBegin

    %%% beginning of the answer sheet header

    {\large\bf Answer sheet:}
    \hfill \namefield{\fbox{
        \begin{minipage}{.5\linewidth}
          Firstname and lastname:

          \vspace*{.5cm}\namefielddots
          \vspace*{1mm}
        \end{minipage}
      }}

    \begin{center}
      \bf\em Answers must be given exclusively on this sheet:
      answers given on the other sheets will be ignored.
    \end{center}

    %%% end of the answer sheet header

    \AMCform

    % \AMCaddpagesto{5}

    }

    \end{document}

The following remarks should make the above example clearer :

| The `separateanswersheet` option is what allows us to do what we wanted.
| One can re-define in this manner the way the questions are identified on the answer sheet (this line is optional).
| This page break is put before the special page where the check-boxes are put together. If one does recto-verso printing, it is preferable to use \AMCcleardoublepage so that this page is printed apart from the others. In the case of recto printing, one can simply use \clearpage.
| Uncomment to get three pages for the question part of each copy, see the section called “Number of pages”. (Here, the command is commented so no effect.)
| This command marks the beginning of the answer sheet part. Its use is necessary for the appropriate treatment of the questions which appear only in that part, e.g. those generated by \AMCcodeGrid.
| Students should normally write their name on the answer sheet!
| The namefielddots command insert a dotted line or a field to fill if the `pdfform` option is avaible (see the section called “Package options”).
| The LaTeX command \AMCform writes all the check-boxes.
| Uncomment to get five pages for the whole copy (question+answer sheet), see the section called “Number of pages”.

| Warning
When one uses a separate answer sheet, letters (or digits, if one uses the option `digits`, see the section called “Package options”) are written in the check-boxes. To achieve a correct detection of the checked boxes, one has to ask students to completely fill the relevant boxes (checking by simply drawing a cross would not suffice). One also has to tune the gray level threshold (defining the proportion of black dots in a box above which that box is considered to be checked) to a value of order 0.5.

### Description of the LaTeX commands

#### Package options

To use the automultiplechoice package, one uses the line

    \usepackage[...]{automultiplechoice}

where the dots are replaced by a list of options separated by commas. Here are the available options:

- `lang=`XX``: sets the subject language to `XX`. At present, only DE (German), ES (Spanish), FR (French), IT (Italian), JA (Japanese), NL (Dutch), NO (Norwegian) and PT (Portuguese) are available. Several strings added by automultiplechoice will be translated, such as "None of these answers are correct", see option `completemulti`.

- `pdfform`: creates a pdf file to fill.

- `box`: puts every question in a block, so that it cannot be split by a page break.

  | Note
  You may occasionally cancel this option for each question with the command \AMCnobloc.
      {\AMCnobloc%
        \begin{question}{nb-ue}
          How many different states were members of the European Union in Jan. 2009?
          \begin{choiceshoriz}[o]
            \wrongchoice{15}
            \wrongchoice{21}
            \wrongchoice{25}
            \correctchoice{27}
            \wrongchoice{31}
          \end{choiceshoriz}
        \end{question}
      }%

- `asbox`: same as `box`, but inside the separate answer sheet.

- `completemulti`: automatically adds a "None of these answers are correct" choice at the end of each multiple question. Thus, for these questions, a distinction can be made between no answer and the answer consisting in treating none of the listed answers as correct. This behavior can be forced or canceled for a particular question using one of the commands \AMCcompleteMulti or \AMCnoCompleteMulti inside the corresponding questionmult environment.

- `noshuffle`: stops the automatic shuffling of the answers for every question

- `noshufflegroups`: stops the automatic shuffling of the group for the test (see Groups of questions)

- `answers`: produces the corrected version of the MCQ test, not the test sheet itself.

- `indivanswers` : produces the corrected version of each MCQ test.

- `separateanswersheet`: requires that all check-boxes be put together at the end of the test sheet (usually, this option is used when one wants to have only one sheet to scan per student - see the example in An example with a separate answer sheet).

- `digits`: if one uses the `separateanswersheet` option, the `digits` option requires the question to be identified with digits rather than with letters (which corresponds to the default setting).

- `outsidebox`: when using `separateanswersheet`, this option asks to print letters (or digits) outside the boxes on the answer sheet.

- `init` : initializes the random generator from time. This option is only for testing: don’t use it for a real exam!

- `insidebox`: when not using `separateanswersheet`, this options asks to print letters (or digits) inside the boxes to be filled by the students.

- `catalog`: use this option to make a catalog of your questions to be used to compose future exams. No need to use \onecopy with this layout.

- `keys=line`: allow one-line key printing in catalog mode.

- `postcorrect`: use this option if you want to give the correct answers after scans analysis, from a teacher completed answer sheet - see the section called “Post correcting” for details.

- `fullgroups` : cancels the use of the optional parameter of \insertgroup and \copygroup, so that each group is always fully inserted and fully copied. (see Groups of questions)

- `storebox` :If you choose to change the boxes' shape (square by default, see Check-box presentation style) as ovals or circles, you may communicate this option to automultiplechoice to use `\storebox` rather than `\savebox` to store the design of the boxes.

- `automarks`: in `separateanswersheet` mode, use this option if you want to cancel marks printing on the subject pages. They will only be print on the answer sheet pages. To change the way pages numbers are print on the subject pages, redefine the \AMCsubjectPageTag command:

      \renewcommand\AMCsubjectPageTag{%
        \fbox{\texttt{\the\AMCid@etud:\thepage}}%
      }

  | Warning
  Only use `automarks` option if no data are to be collected on the subjects pages, as AMC won't be able to process these pages.

- `nopage`: use this option if you don't need margins, corner circles and page identification boxes, that is if the document is not intended to be used with AMC (for example to produce exercises lists).

- `nowatermark`: remove the watermark (draft) if you compile withoutAMC. Very hazardous.

- `survey`: to create a machine readable questionnaire in high typographical quality https://gitlab.com/CSaalbach/surveyamc-project/-/blob/master/surveyamc_tutorial.pdf..

#### Description of a copy

The LaTeX source code describing the content of the test sheet has to be included in a call to the command \onecopy, the first argument being the number of distinct realizations to be produced, and the second argument being the code used to generate a realization.

    \onecopy{50}{ ... }

An alternative syntax is available, using the examcopy environment, where the number of realizations is an option (default is 5).

    \begin{examcopy}[50]
    ...
    \end{examcopy}

| Note
To use examcopy, you need the environ package to be installed, which is not available in the TeX Live 2007 distribution, still used in Ubuntu distributions up to version 9.10 (Karmic Koala).

To differentiate between odd and even-numbered copy, use \exemplairepair command.

The command \AMCStudentNumber get the copy number.

#### Questions and answers

| Important
Do not nest a question inside a another environment question or tabularx otherwise exporting the notes will be incomplete (see Exporting the scores list).

##### Simple questions

For simple questions (a single correct answer), one uses the following model:

    \begin{question}{identifier}
      Here is the question...
      \begin{choices}
        \correctchoice{The correct answer}
        \wrongchoice{A wrong answer}
        \wrongchoice{Another wrong answer}
      \end{choices}
    \end{question}

##### Multiple questions

Multiple questions (those for which no, one, or several answers can be correct) use the `questionmult` environment instead of `question`.

##### Open questions

One can sometimes require some open questions to be added to the subject. One way to do so is to reserve boxes use to the teacher for these questions. After the exam, the teacher reads the completed answer sheets and tick the boxes according to the answers written by the students for open questions. He will then scan the sheets and let AMC correct the multiple choice questions and integrate the open questions scores into the marks.

    \begin{question}{open}
      Define \emph{inflation}.
      \AMCOpen{lines=5}{\wrongchoice[W]{w}\scoring{0}\wrongchoice[P]{p}\scoring{1}\correctchoice[C]{c}\scoring{2}}
    \end{question}

In this example, the teacher will get three boxes. If the first (labeled W for wrong) is ticked, the student will get 0 points. If the second (labeled P for partial) is ticked, the student will get 1 point. If the third (labeled C for correct) is ticked, the student will get 2 points.

The first argument to \AMCOpen is a comma separated list of options. The available options are:

lineup=`bool`

  if `true`, the answering area and the scoring boxes will be on the same line. If `false` (this is default), the answering area is enclosed in a frame and placed below the scoring boxes.

lineuptext=`text`

  if `lineup=true`, the text and ansewering area will be on the same line.

lines=`num`

  sets the number of lines for the answer. Default value is `1`.

lineheight=`dim`

  sets the height of each line. Default value is `1cm`.

dots=`bool`

  if `true` (Default), each line will be realized by a line of dots.

contentcommand=`cmdname`

  Use this option if you want to customize the content of the answer area. You will have to define a \`cmdname` command that has to produce the content.

hspace=`dim`

  sets the space between boxes in the marking area.

backgroundcol=`color`

  sets the background color of the marking area.

foregroundcol=`color`

  sets the foreground color of the marking area.

scan=`bool`

  if `false`, the boxes are not scanned (this can be useful if you plan to use manual data capture only to mark this question, and don't want to take into account the students drawings on the boxes). Defaults to `true`.

annotate=`bool`

  if `false` (default value), the boxes from this question won't be annotated when annotating the answer sheets (only the score will be written).

question=`text`

  sets a short text that helps the examiner to identify the question. This text will be written before the scoring boxes, only if a separate answer sheet is used.

  The question's identifier will be displayed if you type question in the options list.

answer=`text`

  sets a short text that will be written in the answering area for corrected answer sheets.

| Tip
Use the command \savebox, outside the onecopy command, to display a longer text with linebreaks.
    \newsavebox{\correcbox}
    \savebox{\correcbox}{\parbox{5cm}{\color{red}{Here a linebreak\\or\\here...}}}
Call out the boxe's contents:
    \AMCOpen{lines=4,lineheight=0.15cm, answer= \usebox{\correcbox}}{the scoring}

| Warning
If the answer contains a comma or the equal sign, `text` must be bracketed by braces. If the answer contains commands \command or definitions \def, you must add \protect.
    \FPeval\aRandomVariable{round(3+8*random,2)}
    \FPeval\aCalculateVariable{round(\aRandomVariable*9.81,2)}

    \AMCOpen{answer={m=\protect\SI{\aRandomVariable}{\kilo\gram},%
    P=\protect\SI{\aCalculateVariable}{\newton}}{the scoring}

width=`dim`

  sets the width of the frame enclosing the answering area when `lineup=false`. Default value is `.95\linewidth`.

framerule=`dim`

  sets the line width for the frame enclosing the answering area.

framerulecol=`color`

  sets the frame color for the answering area.

boxmargin=`dim`

  sets the margin around the scoring boxes.

boxframerule=`dim`

  sets the line width for the frame around the scoring boxes.

boxframerulecol=`color`

  sets the color of the frame around the scoring boxes.

You can set other default values (for the whole exam) for all these parameters using the command \AMCopenOpts, like

    \AMCopenOpts{boxframerule=2pt,boxframerulecol=red}

Moreover, a little text can be written in the marking area to tell the students not to tick these boxes, redefining the \AMCotextReserved command, as:

    \def\AMCotextReserved{\emph{Reserved}}

When using separate answer sheets, the text added to each open question can also be defined, as:

    \def\AMCotextGoto{\par{\bf\emph{Please write the answer on the separate answer sheet.}}}

| Tip
if the number of boxes is significant, use this tip (\parbox) to force a linebreak.
    \AMCOpen{lines=6}{
              \hbox{\parbox{8.5cm}{
              \wrongchoice[F]{F}\scoring{0}
    			    \wrongchoice[1]{1}\scoring{1}
    			    \wrongchoice[2]{2}\scoring{2}
    			    \wrongchoice[3]{3}\scoring{3}
    			    \wrongchoice[4]{4}\scoring{4}
    			    \wrongchoice[5]{5}\scoring{5}
    			    \wrongchoice[6]{6}\scoring{6}
    			    \wrongchoice[7]{7}\scoring{7}
    			    \wrongchoice[8]{8}\scoring{8}
    			    \wrongchoice[9]{9}\scoring{9}
    			    \correctchoice[10]{10}\scoring{10}
                        }}
                }

##### Indicative question

When the answer to the question is not supposed to be taken into account in the grading, one uses the `\QuestionIndicative` command, as in the following example:

    \begin{question}{difficulty}\QuestionIndicative
      \scoring{auto=0,v=-1,e=-2}
      Did you find this class easy or difficult? Please answer on a scale from 0 (very difficult) to 5
      (very easy).
      \begin{choiceshoriz}[o]
        \correctchoice{0}
        \correctchoice{1}
        \correctchoice{2}
        \correctchoice{3}
        \correctchoice{4}
        \correctchoice{5}
      \end{choiceshoriz}
    \end{question}

##### Identifier

| Important
One must use a different identifier for every question. An identifier can be made of digits, letters, and simple characters (but do not use e.g. underscores, braces or brackets, that have a special meaning in LaTeX files). Don't end your question identifier with an integer enclosed in square brackets, as this syntax is reserved to codes input.

The style of the identifier may be

    group.identifier

or

    group:identifier

(see Language package) to get the total of a one group of questions when exporting notes (see Exporting the scores list).

##### Question numbers, see also the section called “Questions presentation style”

###### display section N°.question N°

    \makeatletter
    \def\AMCbeginQuestion#1#2{\par\noindent{\bf \the\c@section.#1} #2\hspace*{1em}}
    \makeatother
    %use with amsmath package
    \numberwithin{AMCquestionaff}{section}

###### Reset the numeration

One can modify the number of the next question with the `\AMCnumero command`. At the beginning of each realization of the test, a call to

    \AMCnumero{1}

is done, but this command can be used at any place.

###### Do not display the number

When you want to hide the number for a particular question and do not want to increase the question number, use \AMCquestionNumberfalse command as in the following example:

    {
      \AMCquestionNumberfalse
      \def\AMCbeginQuestion#1#2{}
      \begin{question}
        ...
      \end{question}
    }

| Warning
With nominative sheets (see Nominative sheets), set up it with a new command in the preamble.
    \def\Iswitch{\def\AMCbeginQuestion##1##2{}\AMCquestionNumberfalse}
and use it when you need it. (Do not forget to type inside brackets to limit the effect) :
    {\Iswitch
     \begin{question}{Number}
       Choose the greater.
       \begin{choiceshoriz}[o]
         \wrongchoice{200}\wrongchoice{2}\wrongchoice{20}\wrongchoice{200}\correctchoice{600}
       \end{choiceshoriz}
     \end{question}
    }
In this example, the question number will not be displayed through the command \AMCquestionNumberfalse.

###### Questions counter

The internal counter is `AMCquestionaff`. To display the total number of pages at the beginning, it is necessary declare the totcount package. Here an example:

    documentclass[a4paper]{article}

    \usepackage[utf8x]{inputenc}
    \usepackage[T1]{fontenc}

    \usepackage[english,box,completemulti]{automultiplechoice}
    \usepackage{totcount}
    \regtotcounter{AMCquestionaff}
    \begin{document}

    \exemplaire{10}{

    There is \total{AMCquestionaff} questions.

    \noindent{\bf QCM  \hfill TEST}

    \vspace*{.5cm}
    \begin{minipage}{.4\linewidth}
    \centering\large\bf Test\end{minipage}
    \champnom{\fbox{
                    \begin{minipage}{.5\linewidth}
                      Name and surname :

                      \vspace*{.5cm}\dotfill
                      \vspace*{1mm}
                    \end{minipage}
             }}

    \begin{question}{prez}
        Among the following persons, which one has ever been a President of the French Republic?
        \begin{choices}
          \correctchoice{René Coty}
          \wrongchoice{Alain Prost}
          \wrongchoice{Marcel Proust}
          \wrongchoice{Claude Monet}
        \end{choices}
      \end{question}
    \end{question}

      \begin{questionmult}{pref}
        Among the following cities, which ones are French prefectures?
        \begin{choices}
          \correctchoice{Poitiers}
          \wrongchoice{Sainte-Menehould}
          \correctchoice{Avignon}
        \end{choices}
      \end{questionmult}

    % \AMCaddpagesto{3}

    %\theAMCquestionaff
    }

    \end{document}

##### Putting answers on multiple columns

To put the answers on two columns, one can use the multicol package: load it in the preamble (just after the reference to the package automultiplechoice for instance) with

    \usepackage{multicol}

and include the choices environment inside a multicols environment in the following manner:

    \begin{multicols}{2}
      \begin{choices}
        \correctchoice{The correct answer}
        \wrongchoice{A wrong answer}
        \wrongchoice{Another wrong answer}
      \end{choices}
    \end{multicols}

For even shorter answers, one can require questions to be printed following one another, using the `choiceshoriz` environment instead of `choices`.

To put answers on several columns (and thus save space), one can embed the `choices` environment in a `multicols` environment, using the LaTeX package multicol.

If, moreover, the answers do not fit into a single line, an answer might be split over several columns, which might be a little puzzling for the reader. The \AMCBoxedAnswers command was defined in order to prevent this phenomenon, by embedding each answer into a box. Here is an example of use:

    \begin{question}{two columns}
      What is a bird ?
      \begin{multicols}{2}\AMCBoxedAnswers
        \begin{choices}
          \correctchoice{It is an animal with wings, laying eggs. There are birds with all sorts of colors.}
          \wrongchoice{It is a large piece of furniture, made of wood, and used most of the time to store
          household linen}
          \wrongchoice{It is a steam machine devised to seal cans at high speed.}
        \end{choices}
      \end{multicols}
    \end{question}

Let us note that it is also possible to parameterize the vertical space between two answer blocks, thanks to the dimension `AMCinterBrep`:

    \AMCinterBrep=.5ex

##### One-letter answers

Sometimes this is not necessary to write some long text to describe answers, and one letter or symbol is enough. When using a separate answer sheet, it is quite annoying to print the boxes both on the question and on the answer sheet. In such cases, use \AMCBoxOnly instead of the `choices` environment:

    \begin{question}{arm}
      Which letter shows the \textit{arm} on the diagram?
      \AMCBoxOnly{ordered=true}{\wrongchoice[A]{}\correctchoice[B]{}%
        \wrongchoice[C]{}\wrongchoice[D]{}}
    \end{question}

The first argument to \AMCBoxOnly is a comma separated list of options. The available options are:

help=`text`

  prints some reminder text before the boxes on the separate answer sheet.

ordered=`bool`

  if `true` (the default value is `false`), the answers won't be shuffled.

##### Explanation for the answers of a question

To provide explanation for the answers of a question, one can use the \explain command. The explanations are optional and are only displayed in the Solution and Catalog file.

| Warning
Not displayed in the individual solution. To get around this, type in preamble:
    \makeatletter
    \renewcommand{\explain}[1]{%
      \ifAMC@correc%
      \AMCif@env{question}{\par\noindent{\AMC@loc@explain#1}}{\AMC@error@explain}\vspace{1ex}%
      \else%
      \AMCif@env{question}{}{\AMC@error@explain}%
      \fi%
    }
    \makeatother

Here is a simple example:

    \begin{question}{explanation}
      Which has the highest elevation among the following?
      \begin{choices}
          \correctchoice{Sagarmatha}
          \wrongchoice{K2}
          \wrongchoice{Mont Blanc}
          \wrongchoice{Aconcagua}
      \end{choices}
      \explain{Sagarmatha which literally means `Head of sky' is the native name of
               Mount Everest, the highest mountain in the world.}
    \end{question}

| Note
The explain command must be typed inside `question` like environments only. This includes `question`, `questionmult` and `questionmultx` environments.

By default this command prints Explanation: before each explanations. This behavior can be changed using the \AMCtext command (see section the section called “Customizing some texts inserted by AMC”).

If you want to change this default behavior only for some questions and not for all just use the \AMCtext command before the \explain command as in the following example:

    \begin{question}{elevation}
      Which has the highest elevation among the following?
      \begin{choices}
          \correctchoice{Sagarmatha}
          \wrongchoice{K2}
          \wrongchoice{Mont Blanc}
          \wrongchoice{Aconcagua}
      \end{choices}
      \explain{Sagarmatha which literally means `Head of sky' is the native name of
             Mount Everest, the highest mountain in the world.}
    \end{question}

    \begin{question}{odd}
      Pick the odd one out.
      \begin{choices}
          \correctchoice{Kilimanjaro}
          \wrongchoice{Himalayas}
          \wrongchoice{Alps}
          \wrongchoice{Andes}
      \end{choices}
      \AMCtext{explain}{\textit{\textbf{Reason: }}}
      \explain{Kilimanjaro is a mountain while the rest are mountain ranges.}
    \end{question}

    \begin{questionmult}{himalaya}
      Among the following which is in the Himalayas?
      \begin{choices}
          \correctchoice{Mount Everest}
          \correctchoice{K2}
          \wrongchoice{Mont Blanc}
          \wrongchoice{Aconcagua}
      \end{choices}
      \explain{Aconcagua is located in the Andes mountain range while Mont Blanc
                     is located in the Alps.}
    \end{questionmult}

This will now print Explanation: before the explanations of first and third question but Reason: before the explanation of second question.

##### Keep the original order of the answers

To keep the original order of the answers and prevent shuffling for this specific question, one can use the `o` option of the `choices` environment, replacing line 3 by the following:

    \begin{choices}[o]

###### Last choice

You may force AMC to let one or more answers as last choices with the command \lastchoices.

    \begin{question}{color}
      Which color?
      \begin{choiceshoriz}
        \wrongchoice{red}
        \wrongchoice{blue}
        \wrongchoice{yellow}
        \lastchoices
        \correctchoice{transparent}
        \wrongchoice{can't say}
      \end{choiceshoriz}
    \end{question}

    \begin{questionmult}{number}
      How many?
      \begin{choiceshoriz}
        \wrongchoice{none}
        \correctchoice{one}
        \wrongchoice{two}
        \wrongchoice{three}
        \lastchoices
        \correctchoice{not so much}
        \wrongchoice{a lot}
      \end{choiceshoriz}
    \end{questionmult}

##### Numerical answer (not available with AMC-TXT)

see the section called “Coding the result”

##### Space between answers

Let us note that it is also possible to parameterize the vertical space between many answer blocks, thanks to the dimension `AMCinterIrep`:

    \AMCinterIrep=.75ex

##### Remarks

###### Language package

Some language packages may interfere with the identifier (french for example) if you use colon. Better use the dot.

###### maximum number of responses

The maximum number of answers for a given question is limited to 199.

#### Define the marks' display area

You may add an additional option of marking area (see Marks' position) with the package tikz.

    \usepackage{tikz}

##### Without the `separateanswersheet` option

Type this command after \begin{document} and before the command \onecopy :

    \AMCsetScoreZone{width=1.5em,height=1.5ex,depth=.5ex,position=margins}

The variables `width`, `height`, `depth` describe the dimensions of the box marking and its location on the sheet.

The `position` value may be equal to : none, question, margin, margins.

##### With the `separateanswersheet` option

Type this command after \begin{document} and before the command \onecopy :

    \AMCsetScoreZoneAnswerSheet{width=1.5em,height=1.5ex,depth=.5ex,position=question}

The variables `width`, `height`, `depth` describe the dimensions of the box marking and its location on the sheet.

The `position` value may be equal to : none, question, margin, margins.

| Warning
The option `margins` does not work with AMC-TXT. Don't type one of those commands after printing.

#### Groups of questions

Putting questions into groups allows one to shuffle questions inside these groups, in a different way for each realization of the test. Every group of questions must have a name formed solely with plain letters.

One can put questions in a group one by one, as in the following example.

    \element{mygroup}{
      \begin{question}{easy}
        So, how much is one plus one?
        \begin{choiceshoriz}
          \correctchoice{two}
          \wrongchoice{zero}
          \wrongchoice{three}
        \end{choiceshoriz}
      \end{question}
    }

| Important
The formation of the group, using the element commands, must be made only once: thus, these commands have to be used before the onecopy command, which repeats some actions for every realization.

Finally, the group content can be output to the test sheet using command \insertgroup, as in

    \insertgroup{mygroup}

Group insertion can be controlled by the group mode, that can be set by the \setgroupmode command (called after group creation, once for all, before \onecopy):

    \setgroupmode{mygroup}{XXX}

where `XXX` can be one of the following: tutorial shuffle

fixed

  with this mode, group's elements are taken from the beginnig at each insertion.

cyclic

  the elements will be taken from the group following the last call group’s use, recycling if necessary.

withreplacement

  the same as `fixed`, but the group is shuffled before each use.

withoutreplacement

  like `cyclic`, adding some shuffling when comming back to the beginning of the group.

Note that a default group mode can be set for all groups that will be created next (a group is created at the first \element call), using the command

    \setdefaultgroupmode{XXX}

Without any mode definition, the `fixed` mode is used.

Once a group is formed, it is possible to shuffle questions inside this group using the \shufflegroup command. For instance

    \shufflegroup{mygroup}

Groups of questions can be manipulated more precisely thanks to the following commands:

- `\insertgroup[n]{mygroup}` (using optional parameter `n`) only inserts the `n` first elements from the group.

- `\insertgroupfrom[n]{groupname}{i}` does the same as `\insertgroup[n]{groupname}`, starting from element at index `i` (the first element has index 0).

- `\cleargroup{mygroup}` clears all group content.

- `\copygroup{groupA}{groupB}` copies all the elements from group `groupA` to the end of group `groupB`. With an optional argument `n`, only the n first elements will be copied: `\copygroup[n]{groupA}{groupB}`.

With these commands, you can for example make a exam taking 4 questions from group GA at random, 5 questions from group GB at random, and all the questions from group GO, shuffling all these questions, with the following code (to be used inside the argument of the command \onecopy, and supposing that the group mode of groups `GA`, `GB` and `all` is `withoutreplacement` or `withreplacement`):

    \cleargroup{all}
    \copygroup[4]{GA}{all}
    \copygroup[5]{GB}{all}
    \copygroup{GO}{all}
    \insertgroup{all}

- `\copygroupfrom[n]{groupA}{groupB}{i}` does the same as `\copygroup[n]{groupA}{groupB}` starting from element at index `i` (the first element has index 0).

#### Page size, margins

The automultiplechoice LaTeX package uses geometry to set the margins and page layout. You can overwrite its settings using the \geometry command just before the `\begin{document}` - see the geometry package documentation for details. The values initially set by AMC are:

    \geometry{hmargin=3cm,headheight=2cm,headsep=.3cm,footskip=1cm,top=3.5cm,bottom=2.5cm}

When reducing the margins to gain some space, keep in mind that:

- The four corner marks must be printed entirely (they could disappear due to the printer margins).

- The four corner marks must be entirely visible on the scans (if they are too close from the border and the paper moved a little or turned a little during scanning, this could not be the case).

It is also possible to set the paper size as an option to add to the list given as argument to the \geometry command. Available values include `a4paper`, `a5paper`, `a6paper`, `b4paper`, `b5paper`, `ansibpaper`, `ansicpaper`, `ansidpaper`, `letterpaper`, `executivepaper`, `legalpaper`.

For small paper sizes, it may also be interesting to change the position of the human readable sheet IDs (like `+1/1/53+`) in the header. This can be done using the \AMCidsPosition command, in the form

    \AMCidsPosition{pos=p,width=w,height=h}

where `p` can be `none`, `top` or `side`, and the dimensions `w` and `h` refers to the (invisible) box containing the ID. The default values are

    \AMCidsPosition{pos=side,width=4cm,height=3ex}

Let us end with an example for A5 paper sheets:

    \geometry{a5paper,hmargin=1.6cm,top=2.5cm}
    \AMCidsPosition{pos=top}

| Warning
Do not load package pgfpages or any other layout applications

#### Check-box presentation style

The \AMCboxStyle (new name for the \AMCboxDimensions command which still compatible with the options) allows one to modify one or several dimensions of the check-boxes.

Default values are :

    \AMCboxStyle{shape=square,size=2.5ex,down=.4ex,rule=.5pt,outsidesep=.1em,color=black}

- `shape` is the shape of the boxes. Use the value `square` to get squares or rectangles, and `oval` to get circles or ovals. Note that the LaTeX package tikz must be loaded for `oval` to work.

- `width` is the width of the box;

- `height` is the height of the box;

- `size` is the size (`width` and `height`) of the box;

- `rule` is the thickness of the boundary of the box;

- `down` controls by how much boxes are pushed down.

- `outsidesep` for the distance between the box and the letter when printed outside the box when the `outsidebox` option is choosen (see Package options).

- `cross=true` only displayed on the answer sheet, shows the good answer with a cross instead of filling in black the box

- `crossrule=1.5pt` only displayed on the answer sheet, is the thickness of the cross.

- `color=`col`` gives the color to be used to draw boxes. The color `col` must be compatible with the xcolor package. For example, some names such as `red` can be used. You can also define your proper color, as in

      \definecolor{mylightgreen}{rgb}{0.67,0.88,0.5}
      \AMCboxStyle{color=mylightgreen}

To obtain smaller boxes, one can e.g. use the command

    \AMCboxStyle{size=1.7ex,down=.2ex}

When using `separateanswersheet` package option, you can also customize the boxes labeling. The default behavior is to use uppercase alphabetical labeling, or arabic numbering if the `digits` package option is used. To use your own labeling, one has to redefine the \AMCchoiceLabel command which takes as argument the name of the counter used to number the choices. For example, the following code will ask for lowercase letters to label the boxes:

    \def\AMCchoiceLabel#1{\alph{#1}}

As an other example, when using arabxetex package, the following code may be useful:

    \def\AMCchoiceLabel#1{\textLR{\Alph{#1}}}

One can also change the style of the boxes labels redefining the \AMCchoiceLabelFormat command, as in the following example (here we need bold labels):

    \def\AMCchoiceLabelFormat#1{\textbf{#1}}

One can also change the style of the outside labels redefining the \AMCoutsideLabelFormat command, as in the following example (here we need bold labels):

    \def\AMCoutsideLabelFormat#1{\textbf{#1}}

| Note
The switch used to tick or not correct answers is \AMC@correctrue. You can define a command to set it to true, just after the \begin{document}.
    \makeatletter
    \def\AMCforcecorrect{\AMC@correctrue}
    \makeatother
and then use it for a particular question (enclose in braces to limit its effect to one question):
    {\AMCforcecorrect\begin{questionmult}{test}\QuestionIndicative
       .....
     \end{questionmult}
    }
You should tell AMC not to count points for this question (with a 0-point scoring, or using \QuestionIndicative).

#### Questions presentation style

The way each question is presented can be modified by redefining the command \AMCbeginQuestion, whose default definition is the following:

    \def\AMCbeginQuestion#1#2{\par\noindent{\bf Question #1} #2\hspace*{1em}}

The first parameter transmitted to this command is the number of the question to be displayed. The second parameter contains `\multiSymbole` in the case of a multiple question, and is void in all other cases. The `\multiSymbole` command too can be modified: its goal is to distinguish multiple questions from the others. By default, it displays a club.

    \def\multiSymbole{$\clubsuit$}

##### Choices custom

The display of answers can be modified in the same fashion, if one uses the `choicescustom` environment instead of `choices` or `choiceshoriz`, redefining the three following LaTeX macros:

    \def\AMCbeginAnswer{}
    \def\AMCendAnswer{}
    \def\AMCanswer#1#2{#1 #2}

###### Example 1

The check boxes can be used to penalize students who delay their copy, for example (8 points less for a small delay and 20 points less for an exaggerated delay). It will be enough to include at the desired place (for example in the header, something like this):

    \fcolorbox{black}{gray}{\insertDelay}

the command \insertDelay is defined outside from \onecopy :

    \def\insertDelay{ %
    {\def\AMCbeginQuestion##1##2{}\AMCnobloc%
     \begin{questionmult}{00delay}
     \AMCnoCompleteMulti\AMCdontAnnotate%
     \def\AMCbeginAnswer{}\def\AMCendAnswer{}%
    Holded~\begin{choicescustom}[o]\wrongchoice{R1~}\scoring{b=0,m=-8}\wrongchoice{R2}\scoringb=0,m=-20}\end{choicescustom}%
     \end{questionmult}}%
    }

- the command \def\AMCbeginQuestion##1##2{} (combined with the use of the `reponsesperso` environment) allows AMC to write not "Question XX".

- \def\AMCbeginAnswer{}\def\AMCendAnswer{} also refine the result.

- \AMCnoCompleteMulti allows to tell AMC not to add the answer "none of these answers is correct" despite the use of questionmult.

- \AMCdontAnnotate ask AMC not to annotate these boxes there.

| Important
Inside the commande \onecopy, double the `#`.
    \def\AMCanswer##1##2{##1  ##2}
    \def\AMCbeginQuestion##1##2{}

###### Use in mathematics

    \begin{questionmultx}{formula}\scoring{mz=2}\AMCnoCompleteMulti
    How is the identity function defined?
      \begin{choicescustom}[o]
        \[f(x)=\correctchoice[$y$]{}\wrongchoice{[$x$]{}\correctchoice[$+$]{}\correctchoice[$x^2$]{}\]
      \end{choicescustom}
    \end{questionmultx}

##### Spacing

One can also change spacing redefining the following dimensions (here are the default values):

    \AMCinterIrep=0pt
    \AMCinterBrep=.5ex
    \AMCinterIquest=0pt
    \AMCinterBquest=3ex
    \AMCpostOquest=7mm
    \setlength{\AMChorizAnswerSep}{3em plus 4em}
    \setlength{\AMChorizBoxSep}{1em}

These dimensions are the vertical space between questions (`quest`) or answers (`rep`), in boxed mode (`B`, with \AMCBoxedAnswers or `box` package option) or standard mode (`I`) and the space left after an open question. The two last lengths are used in environment: `choicescustom`

#### Layout

##### Margins

Margins were chosen so that the document prints correctly on most printers. If your printer reduces, you can use the command geometry from laTex package geometry. For example, In order to narrow the top margin's copies, we can use `\geometry{top=3cm}` instead the default value 3.5cm, just before `\begin{document}`.

##### Number of pages

AMC automatically handles the number of pages for each subject. You can choose to fix a identical number of pages for each subject with the command \AMCaddpagesto{integer} to be called at a place you need to reach this number of pages (usually at the end of the copy description or between the question and the answer sheet).

#### Separate answer sheet presentation style

It is also possible to modify the layout of the separate answer sheet produced with the `separateanswersheet` option (see An example with a separate answer sheet).

1. If one only wants to modify the horizontal spacing between two check-boxes or the vertical spacing between two questions, one just has to redefine the following dimensions:

       \AMCformHSpace=.3em
       \AMCformVSpace=1.2ex

2. For a deeper modification of the display settings, one can also redefine the commands that are used at the beginning of each question and for each answer:

       \def\AMCformBeforeQuestion{\vspace{\AMCformVSpace}\par}
       \def\AMCformQuestion#1{\textbf{Question #1:}}
       \def\AMCformAnswer#1{\hspace{\AMCformHSpace} #1}

   These definitions have to be inserted just after `\begin{document}` in the LaTeX file.

3. You can force AMC not to respect the arrangement of the questions and to store the open questions in order to restore them together. This can be useful when you use package multicols, the answers to open questions needing more space when hand written.

   The command \AMCformFilter{!\AMCifcategory{open}} displays all questions except the open questions then the command \AMCformFilter{\AMCifcategory{open}} displays only the open questions. Both commands must be used together.

       %On two columns, the answers boxes are displayed
       %except the open questions.
       \begin{multicols}{2}
       \AMCformFilter{!\AMCifcategory{open}}
       \end{multicols}

       %All the open questions are displayed.
       \AMCformFilter{\AMCifcategory{open}}

   | Note
   The ascending numbering is always respected.

#### Code acquisition

Code acquisition can be easily performed thanks to the LaTeX command

    \AMCcodeGridInt[options]{key}{n}

for instance to allow each student to enter her/his student number by herself/himself on the answer sheet. The two arguments of this command are a code/question key (identifier), and the number `n` of digits to be used by the code. One can e.g. use the following header

    {\setlength{\parindent}{0pt}\hspace*{\fill}\AMCcodeGridInt{etu}{8}\hspace*{\fill}
    \begin{minipage}[b]{6.5cm}
    $\longleftarrow{}$\hspace{0pt plus 1cm} please encode your student number below,
    and write your first and last names below.

    \vspace{3ex}

    \hfill\namefield{\fbox{
        \begin{minipage}{.9\linewidth}
          Firstname and lastname:

          \vspace*{.5cm}\dotfill

          \vspace*{.5cm}\dotfill
          \vspace*{1mm}
        \end{minipage}
      }}\hfill\vspace{5ex}\end{minipage}\hspace*{\fill}

    }

If the `separateanswersheet` option is used, the \AMCcodeGridInt command has to be placed after the \AMCformBegin command.

Note that the codes rendering can be adapted modifying the lengths \AMCcodeHspace, \AMCcodeVspace representing the horizontal and vertical amount of space between boxes. Default values are set with the following commands:

    \AMCcodeHspace=.5em
    \AMCcodeVspace=.5em

The command \AMCcodeGrid[`options`]{`key`}{`description`} can be used to handle more complex codes, as codes including letters. Here, `description` is a coma-separated list of character pools to offer. As an example, a client code formed with a lettre from A to E followed by three digits can be handled with \AMCcodeGrid{client}{ABCDE,0123456789,0123456789,0123456789}.

The two commands \AMCcodeGrid and \AMCcodeGridInt accept the following options (coma-separated into the optional `options` argument):

vertical=`bool`

  where `bool` is `true` or `false`, to indicate the direction to be used (the default value is `true`);

v

  is an alias for `vertical=true`;

h

  is an alias for `vertical=false`;

top

  allows to get top-aligned columns in vertical direction.

#### Choice of shuffling parameters

One can modify the seed of the random number generator used to produce the shuffle, thanks to the following command (to be used just at the beginning of the document, and in any case outside the onecopy command):

    \AMCrandomseed{1527384}

If the value that is assigned (to be chosen between 1 and 4194303) is modified, then the shuffling will differ. Of course, one must not modify this value after the test sheets have been printed.

| Note
The value is recorded in the xy file (as `\rngstate{1}{1515}`). The default value is 1515.

#### Using sectioning and separate answer sheet

For sectioning to be also visible in the separate answer sheet (if any), use \AMCsection and \AMCsubsection instead of \section and \subsection (\AMCsection* and \AMCsubsection* are also defined, for unnumbered sectionning)

#### Using references inside the test sheets

Using LaTeX commands \label, \ref and \pageref within questions or answers is problematic since they will be called with the same arguments for every realization of the test, which will alter the numbering of references. To solve this problem, one should use instead the commands \AMClabel, \AMCref and \AMCpageref: they add the realization number to their argument before transmitting it to \label, \ref and \pageref.

One also has to reset counters to zero at the beginning of each realization. For instance, if one wants to include references to pictures that are put together in a separate page, one might write something like

    \element{animals}{
      \begin{figure}[p]
        \centering
        \includegraphics[width=.6\linewidth]{tiger}
        \caption{An animal}
        \AMClabel{tiger}
      \end{figure}

      \begin{question}{tiger}
        Which is the animal on figure~\AMCref{tiger} page~\AMCpageref{tiger}?
        \begin{choices}
          \correctchoice{A tiger}
          \wrongchoice{A giraffe}
          \wrongchoice{An elephant}
          \wrongchoice{A cat}
        \end{choices}
      \end{question}
    }

and it is then important to add, just after the command \onecopy the line

    \setcounter{figure}{0}

so that the numbering of figures starts at 1 for every realization. Without that last command, the numbering of figures would go on from one realization to the next one, which is clearly not desirable.

##### Using the package cleveref

This package sort in an ascending order the questions' numbers, the questions' pages or the labels' pages (the documentation http://mirrors.ctan.org/macros/latex/contrib/cleveref/cleveref.pdf).

| Warning
This package must be loaded after the package automultiplechoice.

To use this package, a new command was created: \AMCstudentlabel.

    \cref{\AMCstudentlabel{led},\AMCstudentlabel{lamp},\AMCstudentlabel{motor}}

led, lamp, motor are the created labels to reference the questions with the command \AMClabel{}.

#### Customizing some texts inserted by AMC

Use \AMCtext for the following customizations:

- `\AMCtext{none}{`sentence`}` replaces « None of these answers are correct. » (the English default text) with the given `sentence` when using option `completemulti`.

- `\AMCtext{corrected}{`title`}` replaces « Corrected » (the English default text) with the given `title` on the corrected answer sheet.

- `\AMCtext{catalog}{`title`}` replaces « Catalog » (the English default text) with the given `title` on the questions catalog produced thanks to option `catalog`.

- `\AMCtext{explain}{`title`}` replaces « Explanation » (the English default text) with the given `title` before the explanations produced due to the explain command.

  The default option for this command is:

      \AMCtext{explain}{\textit{\textbf{Explanation: }}}

- You can also consider using commands like the following ones (here the second argument is set to the default English value):

      \AMCtext{draft}{DRAFT}
      \AMCtext{message}{For your examination, preferably print documents
                        compiled from auto-multiple-choice.}

- `\AMCsetFoot{`text`}` sets the footer. Use for example `\AMCsetFoot{\thepage}` to write the page number.

#### Binary code

AMC identifies each test and the page number of test with the binary code.

- First row : 12 boxes (default value) : maximum number of tests = 2^12-1 = 4 095.

- Second row : 6 first boxes (default value) : maximum number of pages per tests = 2^6-1 = 63.

- Second row : 6 last boxes (default value) : check code.

To raise the number of tests and/or pages per test modify the commands' default values \AMC@NCBetud, \AMC@NCBpage et \AMC@NCBcheck.

Load those commands below in the preambule (here with the default values).

    \makeatletter
    \def\AMC@NCBetud{12}
    \def\AMC@NCBpage{6}
    \def\AMC@NCBcheck{6}
    \makeatother

### Options for AMC

You can add in the source file header (the first lines that begin with a '%') some options to be passed to AMC:

`%%AMC:preprocess_command=`commandname``

  tells AMC to run the `commandname` command before calling LaTeX to process the source file. This command will be run inside the project directory, and the name of a source file copy will be passed as an argument. There is no problem for `commandname` to change this file content, because this is only a copy.

`%%AMC:latex_engine=`engine``

  tells AMC to set the LaTeX engine to use for this file, regardless to the one entered as a preference by the user.

### Mathematical questions with randomized statements

#### Using package fp

Thanks to the LaTeX package fp, whose documentation is available at http://mirrors.ctan.org/macros/latex/contrib/fp/README, and which can be downloaded with the command

    \usepackage{fp}

added before that corresponding to automultiplechoice, one can create exercises with randomized numerical data. Let us start with a simple example.

    \begin{question}{addition}
      \FPeval\VQa{trunc(1+random*8,0)}
      \FPeval\VQb{trunc(4+random*5,0)}
      \FPeval\VQsomme{clip(VQa+VQb)}
      \FPeval\VQnonA{clip(VQa+VQb-1)}
      \FPeval\VQnonB{clip(VQa*VQb)}
      \FPeval\VQnonC{clip(VQa-VQb)}

      What is the sum of \VQa{} and \VQb{} ?
      \begin{choiceshoriz}
        \correctchoice{\VQsomme}
        \wrongchoice{\VQnonA}
        \wrongchoice{\VQnonB}
        \wrongchoice{\VQnonC}
      \end{choiceshoriz}
    \end{question}

The \FPeval command is used to perform computations:

| Since random returns a real number in the interval [0,1], this command sets VQa to a random integer value between 1 and 8. The next line sets VQb to a random integer value between 4 and 8.
| Putting the correct answer in the variable VQsomme.
| Putting wrong answers in variables VQnonA, VQnonB and VQnonC...

Variable names beginning with VQ have been chosen so as to avoid interference with other LaTeX commands.

| Note
You can set the random seed with
    \FPseed=integer
`integer` must be fixed, and not computed from date/time values.

##### Choosing an interval

The automultiplechoice package moreover defines a \AMCIntervals command which makes this kind of construction simpler, as illustrated in the next example:

    \begin{question}{inf-expo-indep}
      \FPeval\VQa{trunc(2 + random * 4,0)}
      \FPeval\VQb{trunc(6 + random * 5,0)}
      \FPeval\VQr{VQa/(VQa+VQb)}

      Let $X$ and $Y$ be two independent random variables, following the exponential distribution with
    respective parameters \VQa{} and \VQb{}.
      To which interval does the probability $\mathbb{P}[X<Y]$ belong ?

      \begin{multicols}{5}
        \begin{choices}[o]
          \AMCIntervals{\VQr}{0}{1}{0.1}
        \end{choices}
      \end{multicols}
    \end{question}

| This lines inserts ten answers corresponding to the intervals [0,0.1[ [0.1,0.2[ ... [0.9,1[, while indicating that the correct interval is the one containing VQr. The arguments of the \AMCIntervals command are the following: The correct answer, The left point of the first interval, The right point of the last interval, The length of each interval.

Note that the interval formatting can be changed redefining the \AMCintervalFormat command, which is originally defined as

    \def\AMCIntervalFormat#1#2{[#1,\,#2[}

to follow local conventions (writing [a,b) instead of [a,b[ is for example a common usage).

##### Coding the result

The students can also be asked to code the numerical answer, using the \AMCnumericChoices command, as in the following example:

    \begin{questionmultx}{sqrt}
      \FPeval\VQa{trunc(5+random*15,0)}
      \FPeval\VQs{VQa^0.5}
      Compute $\sqrt{\VQa}$ and round it with two digits after period.

      \AMCnumericChoices{\VQs}{digits=3,decimals=2,sign=true,
                     borderwidth=0pt,backgroundcol=lightgray,approx=5}
    \end{questionmultx}

Note the use of `questionmultx` environment: we need this question to be multiple as several boxes has to be ticked, but we can’t say that several answers are correct, so we don’t show the symbol for multiple questions.

###### Options

Available options that can be used in the second argument of the \AMCnumericChoices command are the following (`bool` can be `true` or `false`, and `color` must be a color known by the xcolor package):

digits=`num`

  gives the number of digits to request (defaults to 3).

decimals=`num`

  gives the number of digits after period to request (defaults to 0). Note that when `num` is positive, the LaTeX package fp must be loaded.

base=`num`

  gives the base for `digits` and `decimals` (defaults to 10).

significant=`bool`

  if `true`, the numbers to code are the first significant digits from the first argument of \AMCnumericChoices. For example, the right answer to

      \AMCnumericChoices{56945.23}{digits=2,significant=true}

  is 57.

exponent=`num`

  switch to scientific notation mode, with `num` digits for the exponent.

nozero=`bool`

  if true, the choice 0 is removed for all digits.

  May be useful when using \AMCnumericChoices to enter small (<10) positive values.

sign=`bool`

  requests (or not) a signed value (defaults to true).

exposign=`bool`

  same for the exponent sign.

strict=`bool`

  if `true`, a box has to be ticked for every digit (even null digits) and for the sign. If `false`, if some digits has no ticked box, they will be set to zero. Defaults to `false`.

vertical=`bool`

  if true, each digit is represented on one raw. If false (default), each digit is represented on one line.

expovertical=`bool`

  if `true`, the mantissa is above the exponent. If `false` (default), the mantissa is beside the exponent.

reverse=`bool`

  if true, place higher values of the digits on the top in `vertical` mode (defaults to true).

vhead=`bool`

  if true, in `vertical` mode, a header is placed over all digits rows, made using the command \AMCntextVHead that is originally defined as

      \def\AMCntextVHead#1{\emph{b#1}}

  This default value is useful to number the binary digits.

  Default value is `false`.

hspace=`space`

  sets the horizontal space between boxes (defaults to `.5em`).

vspace=`space`

  sets the vertical space between boxes (defaults to `1ex`).

borderwidth=`space`

  sets the width of the frame border around all the boxes (defaults to `1mm`).

bordercol=`color`

  sets the color of the frame (defaults to `lightgray`).

backgroundcol=`color`

  sets the background color (defaults to `white`).

Tsign=`text`

  sets the text to print at the top of the boxes to set the sign (Can also be redefined by `\def\AMCntextSign{`text`}`, and defaults to be empty).

Tpoint=`text`

  sets the text for the period. Can also be redefined by `\def\AMCdecimalPoint{`text`}`, and defaults to `\raisebox{1ex}{\bf .}`.

Texponent=`text`

  sets the text that separates mantissa and exponent. Can also be redefined by `\def\AMCexponent{`text`}`, and defaults to `$\times10$\textasciicircum`.

scoring=`bool`

  if `true`, a scoring strategy is given to AMC for this question. Defaults to `true`.

scoreexact=`num`

  gives the score for an exact answer (defaults to 2).

exact=`num`

  sets the maximal distance to the correct integer value (value without the decimal point) for an answer to be said exact and be rewarded to `scoreexact` points (defaults to 0).

scoreapprox=`num`

  gives the score for an approximative answer (defaults to 1).

approx=`num`

  sets the maximal distance to the correct integer value (value without the decimal point) for an answer to be said approximative and be rewarded to `scoreapprox` points (defaults to 0).

| Warning
AMC converts all numbers (decimals included) to integers (simply removing the decimal point) before subtracting them and comparing with `approx`. As an example, with `decimals=2`, if the correct answer is 3.14 and the given answer is 3.2, then the integer difference is 320-314=6, so that the student gets `scoreapprox` points only if `approx` is 6 or greater.

scorewrong=`num`

  gives the score for an wrong answer (defaults to 0).

keepas=`text`

  keeps the value entered by the student for future use with alsocorrect in another question.

  All following questions must follow the lexicographic order of IDs

alsocorrect=`text`

  gives another acceptable answer, that can be based on the values entered by the student in the previous questions. The formula use perl code:

      +, -, *, /, ** (power)

     \begin{question}{carre-a}
        \QuestionIndicative
        Choose any number.
        \begin{reponseshoriz}[o]
          \wronhchoice{2}\scoring{2,setglobal.Number=2}
          \wronhchoice{3}\scoring{3,setglobal.Number=3}
          \wronhchoice{4}\scoring{4,setglobal.Number=4}
          \wronhchoice{5}\scoring{5,setglobal.Number=5}
        \end{reponseshoriz}
      \end{question}

      \begin{questionmultx}{carre-b}
        \AMCdontAnnotate\bareme{MAX=2}
        What is his square?
        \AMCnumericChoices{}{digits=2,approx=1,alsocorrect=Number**2}
      \end{questionmultx}

      \begin{minipage}{.3\linewidth}
        \begin{tikzpicture}
          \draw[fill=blue!50] (0,0) ellipse (1.5 and 0.2);
          \draw (1.5,0) -- (0,5) -- (-1.5,0);
          \draw (1.6,0) -- (2,0);
          \draw (1.6,5) -- (2,5);
          \draw[<->] (1.8,0) -- (1.8,5);
          \node[right] at (1.8,2.5) {$h=5$};
          \draw (0,-0.4) -- (0,-0.8);
          \draw (1.5,-0.4) -- (1.5,-0.8);
          \draw[<->] (0,-0.6) -- (1.5,-0.6);
          \node[below] at (0.75,-0.6) {$r=1.5$};
          \draw[fill=black] (0,0) circle (0.02);
        \end{tikzpicture}
      \end{minipage}
      \begin{minipage}{.65\linewidth}
        \begin{questionmultx}{cone-a}
          What is the area of the blue disc?
          \AMCnumericChoices{pi*1.5^2}{digits=3,decimals=2,exponent=2,approx=2,sign=false,
          exposign=true,expovertical=true,keepas=Surface}
        \end{questionmultx}

        \begin{questionmultx}{cone-b}
          What is the volume of the cone?
          \AMCnumericChoices{pi*1.5^2*5/3}{digits=3,decimals=2,exponent=2,approx=2,sign=false,
          exposign=true,expovertical=true,alsocorrect=Surface*5/3}
        \end{questionmultx}
      \end{minipage}

      \begin{questionmultx}{pipi2-a}
        What is the value of$\pi$ ?
        \AMCnumericChoices{pi}{digits=3,decimals=2,sign=false,keepas=Pi}
      \end{questionmultx}

      \begin{questionmultx}{pipi2-b}
        What is the value  $\pi^2$ ?
        \AMCnumericChoices{pi^2}{digits=3,decimals=2,sign=false,approx=1,alsocorrect=Pi**2}
      \end{questionmultx}

You can set other default values (for the whole exam) for all these parameters using the command \AMCnumericOpts, like

    \AMCnumericOpts{scoreexact=3,borderwidth=2pt}

Moreover, the text added at the end of the questions using \AMCnumericChoices when not in the separate answer sheet (and when a separate answer sheet is requested by the `separateanswersheet` package option) can also be set redefining the \AMCntextGoto command, as:

    \def\AMCntextGoto{\par{\bf\emph{Please code the answer on
                               the separate answer sheet.}}}

###### Access to values

intX

  raw value entered by student.

intV

  correct raw value.

#### Using package pgf/tikz

This package must be declared after the package automultiplechoice.

LaTeX package pgf/tikz (see http://www.ctan.org/tex-archive/graphics/pgf/base) provides mathematical functions that can be loaded with

    \usepackage{tikz}

First of all, you must set the random seed to be sure to get the same result each time latex is run to compile the subject:

    \pgfmathsetseed{2056}

##### A simple computation

Here is an example with a simple computation:

    \begin{question}{inverse}
      \pgfmathrandominteger{\x}{1}{50}

      How much is the reciprocal of $x=\x$?

      \begin{choices}
        \correctchoice{\pgfmathparse{1/\x}\pgfmathresult }
        \wrongchoice{\pgfmathparse{1/(\x +1))}\pgfmathresult}
        \wrongchoice{\pgfmathparse{cos(\x)} \pgfmathresult}
        \wrongchoice{\pgfmathparse{\x^(-0.5)}\pgfmathresult}
      \end{choices}
    \end{question}

Here, the command \pgfmathparse makes the computation, and \pgfmathresult outputs the result.

Output formatting is also available with the command \pgfmathprintnumber, as in the following example (three digits after decimal point, and use of the comma as a decimal point).

    \begin{question}{inverse3}
      \pgfmathrandominteger{\x}{1}{50}
      \pgfkeys{/pgf/number format/.cd,fixed,fixed zerofill,precision=3,use comma}
      How much is the reciprocal of $x=\pgfmathprintnumber{\x}$?

      \begin{choices}
        \correctchoice{\pgfmathparse{1/\x}\pgfmathprintnumber{\pgfmathresult}}
        \wrongchoice{\pgfmathparse{1/(\x +1))} \pgfmathprintnumber{\pgfmathresult}}
        \wrongchoice{\pgfmathparse{cos(\x)} \pgfmathprintnumber{\pgfmathresult}}
        \wrongchoice{\pgfmathparse{\x^(-0.5)} \pgfmathprintnumber{\pgfmathresult}}
      \end{choices}
    \end{question}

| Note
You can also use the \AMCIntervals and \AMCnumericChoices commands (see the section called “Choosing an interval” and the section called “Coding the result”)

##### Graphics

The tikz package also allows to make (random or not) graphs.

    \begin{questionmult}{graph}
      Let us consider the three functions which graphs are plotted below:
      \pgfmathrandominteger{\a}{2}{4}
      \begin{center}
        \begin{tikzpicture}[domain=0:4]
          \draw[very thin,color=gray] (-0.1,-4.1) grid (3.9,3.9);
          \draw[->] (-0.2,0) -- (4.2,0) node[right] {$x$};
          \draw[->] (0,-4.2) -- (0,4.2) node[above] {$f(x)$};
          \draw[color=red] plot (\x,{(1+\a/4)*\x-\a}) node[right] {$f_{1} (x)$};
          \draw[color=blue] plot (\x,{\a*sin(\x r)}) node[right] {$f_{2}(x)$};
          \draw[color=orange] plot (\x,{\a*cos(\x r)}) node[right] {$f_{3}(x)$};
        \end{tikzpicture}
      \end{center}
      Then:
      \begin{choices}
        \pgfmathrandominteger{\x0}{2}{4}
        \correctchoice{$f_{2}(\x0)$=\pgfmathparse{\a*sin(\x0 r)} \pgfmathprintnumber{\pgfmathresult}.}
        \correctchoice{$f_{3}(\x0)$=\pgfmathparse{\a*cos(\x0 r)} \pgfmathprintnumber{\pgfmathresult}.}
        \wrongchoice{La fonction $f_{1}(x)$ est une fonction linéaire.}
      \end{choices}
    \end{questionmult}

To make pretty graphs, package pgfplots can also be useful.

With pgfmath, precision is limited, so that a "Arithmetic overflow" error can be encountered. Packages tikz and pgfplots allows to overcome this problem, using gnuplot as a backend. You need to install gnuplot on your system, and use LaTeX option `--shell-escape`. To this purpose, go to AMC preferences window, and set the LaTeX engine for your project to "`pdflatex --shell-escape`" (without the quotes).

#### Using LuaLaTeX

LUA language can be used inside LaTeX documents thanks to the lualatex command. If you uses it, your document needs to be UTF-8 encoded, and you must not load the inputenc package. See http://www.luatex.org/documentation.html for some information.

LUA commands are to be given as a \directlua argument. The most useful LUA function is tex.print, which will output results back to LaTeX.

Once again, if you use random numbers, always fix the random seed to get the same results across different compilations:

    \directlua{math.randomseed (2048)}

Here is a very simple sample source file:

    \documentclass[a4paper]{article}
    %\usepackage[utf8x]{inputenc}
    \usepackage[T1]{fontenc}
    \usepackage[box,completemulti]{automultiplechoice}
    \begin{document}

    \onecopy{10}{

    %%% head

    \noindent{\bf QCM  \hfill TEST}

    \vspace*{.5cm}
    \begin{minipage}{.4\linewidth}
      \centering\large\bf LuaLaTeX sample exam
    \end{minipage}
    \namefield{\fbox{\begin{minipage}{.5\linewidth}
    Name :

    \vspace*{.5cm}\dotfill
    \vspace*{1mm}
    \end{minipage}}}

    %%%

    \directlua{math.randomseed (2048)}
    \directlua{a=math.random()}

    \begin{question}{square-root}
      How much is the square root of \directlua{tex.print(a)}?

      \begin{choices}
        \correctchoice{\directlua{tex.print(math.sqrt(a))}}
        \wrongchoice{\directlua{tex.print(math.sqrt(2*a))}}
        \wrongchoice{\directlua{tex.print(math.sqrt(a*1.001))}}
      \end{choices}
    \end{question}

    }

    \end{document}

Output formatting can be obtained using lua functions, or with the siunitx package.

| Note
You can also use the \AMCIntervals and \AMCnumericChoices commands (see the section called “Choosing an interval” and the section called “Coding the result”)

Prev |  | Next
AMC-TXT syntax | Home | Usage - Graphical interface