module TestGeneration;
from StudentInterface import Student;
from TestGrading import Mean,Median,Mode,GradedQuestion;
from TestTaking import AnsweredQuestion;
from TestAdminister import Roster;
from QuestionModule import Question,Topic,Author,Difficulty,Time,ClassName,Type,Date,Year, ID;
from QuestionBankModule import QuestionBank,LocalQuestionBank,SharedQuestionBank;

export Test,Wizard,TestName,TotalPoints,TotalTime,PointsPossible,TestQuestion,TotalGrade,ClassTaken,Section,QuestionNumber;

(*-------------------- BEGIN MATT DeVORE'S SECTION --------------------*)

object Weight is integer
	description: (* Weight indicates the amount of representation a Topic
                        or question Type receives in a test. If a Topic has a
                        high weight, it will be touched upon more in the
                        generated test than a Topic with a lower weight. *);
end;

(* enum type: GenerationType *)
object GenerationType is
	components: manual:ManualGeneration or automatic:AutomaticGeneration;
	description: (* Represents one of the two generation methods available:
		        ManualGeneration or AutomaticGeneration. This is a
                        parameter entered by the user in the first step of
                        generation. *);
end GenerationType;

object ManualGeneration is
	components: ;
 	description: (* This is one of the two available methods that
                        teachers can use to generate a
                        test. ManualGeneration indicates that 
                        the generated test will initially have no
                        questions, and that every question must be
                        searched for manually by the instructor and
                        inserted using the Edit Test interface. *);
end ManualGeneration;

object AutomaticGeneration is
	components: ;
	description: (* This is one of the two available methods that
                        teachers can use to generate a
                        test. AutomaticGeneration requires the teacher
                        to enter various criteria which allow the
                        software to automatically find a pool of
                        questions that satisfies the teacher's
                        needs. *); 
end AutomaticGeneration;

(* enum type: Direction *)
object Direction is
	components: for:Forward or back:Backward;
	description: (*
		A Direction is equal to one of the two directions the user may
		be moving while walking between steps in the Test Generation
		Wizard. Forward indicates a clicking of the Next button.
		Backward indicates a clicking of the Previous button. *);
end Direction;
object Forward; object Backward;

object LowerLimit is
	components: integer;
	description: (*
		The lower limit of a Range. Ranges are entered in the fourth
		step of the Wizard. *);
end LowerLimit;

object UpperLimit is
	components: integer;
	description: (*
		The upper limit of a Range. Ranges are entered in the fourth
		step of the Wizard. *);
end UpperLimit;

object Range is
	components: lower:LowerLimit and upper:UpperLimit;
	description: (*
		Represents one of three ranges that the user
                enters in the fourth step of the Wizard.
		Each of the three Ranges are conveyed through
		three different object types that are defined
		simply "is Range": AllowedDifficulties, AverageDifficulty,
		and EstimatedTimeLengthOfTest. *);
end Range;

object AllowedDifficulties is Range;
object AverageDifficulty is Range;
object EstimatedTimeLengthOfTest is Range;

obj Class is 
    components: roster:Roster, classname:ClassName, Quarter, Year, Instructor;
end Class;
obj CourseNumber is integer;
obj Section is integer;
obj Quarter is string;
obj Instructor is string;
object Comments is string;
object Grade is integer;
object CreatedDate is Date;
object ModifiedDate is Date;
object LastUsedDate is Date;
object Notes is string;
object EstimatedTimeTaken is real;
object SuccessRate is real;
object DateTaken is Date;
object ClassTaken is Class;
object TotalTime is integer;
object PointsPossible is integer;
object TotalPoints is PointsPossible;
object TotalGrade is integer;
object TestName is string;
object IsAvailable is boolean;
object QuestionNumber is integer;
object TestQuestion inherits from Question
	components: qt:Type, points:PointsPossible, num:QuestionNumber;
end TestQuestion;
object Test is
	components: name:TestName, totalTime:TotalTime, tp:TotalPoints, tg:TotalGrade,qs:TestQuestion*,aq:AnsweredQuestion*,gq:GradedQuestion*,
		Student, TotalGrade, DateTaken, Class, ClassTaken, Mean,Median,Mode, ia:IsAvailable;
	description: (*
		In this module, represents a generated test. However, in other modules, it may
		also represent a taken or graded test.*);
	operations: AddQuestion, RemoveQuestion, EditQuestion, MoveUp, MoveDown;
end Test;

object CriteriaRanges is
	components: allowedDiff:AllowedDifficulties,
		averageDiff:AverageDifficulty and
		estTimeLength:EstimatedTimeLengthOfTest;
	description: (*
		This object represents the three ranges that are entered during
		step four of the Wizard. Note that these ranges may not be
		blank. *);
end CriteriaRanges;

object WizardTopic is
	components: topic:Topic and weight:Weight;
	description: (*
		Contains both a Topic and that Topic's Weight. The Weight
		value is the number displayed in the Advanced Weight Specification
		dialog next to the Topic indicated in this object.*);
end WizardTopic;

object WizardType is
	components: qt:Type and weight:Weight;
	description: (*
		Contains both a Type and that Type's Weight.
		The Weight value is the number displayed in the Advanced Weight
		Specification dialog next to the Type indicated in
		this object. *);
end WizardType;

object CurrentStep is integer;
object FinishedFlag is boolean;
object IncludedClasses is ClassName*;
object IncludedTypes is WizardType*;
object IncludedTopics is WizardTopic*;

object Wizard is
	components: step:CurrentStep, finished:FinishedFlag, name:TestName,
 		genType:GenerationType, classes:IncludedClasses,
		topics:IncludedTopics, types:IncludedTypes and
		critRanges:CriteriaRanges;
	operations: Step1, Step2, Step3, Step4, Finish, SmallestMarginOfError;
end Wizard;

(* The sole purpose of the StepX operations is to plant the user-given values
   for various criteria into the Wizard object as the Wizard proceeds. *)

operation Step1 is
	inputs: wiz:Wizard and testName:TestName and genType:GenerationType;
	outputs: wiz':Wizard;
	precondition: wiz.step = 1 and #testName > 0;
	postcondition:
		(wiz'.step = 2 and wiz'.name = testName);
	description: (* Plants the user-given values for generation criteria
                        that were entered in Step 1.  These values will be in
                        the output Wizard object. *);
end Step1;

operation Step2 is
	inputs: dir:Direction and wiz:Wizard and classes:ClassName*;
	outputs: wiz':Wizard;
	precondition: wiz.step = 2;
	postcondition:
		if (dir?for) then
			(wiz'.step = 3 and wiz'.classes = classes)
		else
			wiz'.step = 1;
	description: (* Plants the user-given values for generation criteria
                        that were entered in Step 2.  These values will be in
                        the output Wizard object. This is needed whenever the
                        user leaves Step 2 to go to Step 3 or Step 1. *);
end Step2;

operation Step3 is
	inputs: dir:Direction and wiz:Wizard and wizTops:WizardTopic*;
	outputs: wiz':Wizard;
	precondition: wiz.step = 3;
	postcondition:
		if (dir?for) then
			(wiz'.step = 4 and wiz'.topics = wizTops)
		else
			wiz'.step = 2;
	description: (* Plants the user-given values for generation criteria
                        that were entered in Step 3.  These values will be in
                        the output Wizard object. This is needed whenever the
                        user leaves Step 3 to go to Step 4 or Step 2. *);
end Step3;

operation Step4 is
	inputs: dir:Direction and wiz:Wizard and types:WizardType* and critRanges:CriteriaRanges;
	outputs: wiz':Wizard;
	precondition: wiz.step = 4;
	postcondition:
		if (dir?for) then
			(wiz'.finished = true and wiz'.step = 5 and wiz'.types = types
			 and wiz'.critRanges = critRanges)
		else
			wiz'.step = 3;
	description: (* Plants the user-given values for generation criteria
                        that were entered in Step 4.  These values will be in
                        the output Wizard object. This is needed whenever the
                        user leaves Step 4 to go to Step 3 or to Finish the
                        generation. *);
end Step4;

operation Finish is
	inputs: wiz:Wizard, bank:TestQuestion*;
	outputs: test:Test;
	precondition: wiz.finished;
	postcondition:
		(* In case of manual generation, just return a blank test. *)
		(wiz.genType?manual and #(test.qs) = 0)
		or
		(let topicList = GetTopics (wiz.topics);
		let typeList = GetTypes (wiz.types);
		let error = SmallestMarginOfError (wiz, test);

		(* Margin of error cannot be so small so as to render the
		   weights meaningless. *)
		error <= MinTypeWeight (wiz.types) and
		error <= MinTopicWeight (wiz.topics) and

		(* Only classes that have been specified for inclusion may be
		   represented on the test. Same goes for topics and question
		   types. *)
		HasValidClasses (test.qs, wiz.classes) and
		HasValidTopics (test.qs, topicList) and
		HasValidTypes (test.qs, typeList) and

		(* The user weights must correctly apply to the test
		   questions. *)
		TopicWeightsMatch (wiz.topics, test.qs, error) and
		TypeWeightsMatch (wiz.types, test.qs, error) and

		(* The three ranges entered in step four must be adhered to. *)
		FitsRange (wiz.critRanges.allowedDiff,
			   MinDifficulty (test.qs)) and

		FitsRange (wiz.critRanges.allowedDiff,
			   MaxDifficulty (test.qs)) and

		FitsRange (wiz.critRanges.averageDiff,
			   AverageDifficultyOfQuestions (test.qs)) and

		FitsRange (wiz.critRanges.estTimeLength,
			   TotalTimeOfQuestions (test.qs)) and

		(* Test name must match the one entered exactly. *)
		test.name = wiz.name and

		(* Every question included in the test must be in the local
		   question bank. *)
		forall (q in test.qs) (q in bank))

		or

		(* If the above doesn't work, try making the test again, but of
		   a shorter length. *)
		(test = Finish (LowerMinimumTime(wiz), bank));
	description: (*
		This finishes the Test Generation Wizard by
		returning a new test that follows the given criteria
                that was entered in the Generation Wizard. These criteria
                are stored in the Wizard object. *);
end Finish;

operation SmallestMarginOfError is
	inputs: wiz:Wizard, test:Test;
	outputs: error:integer;
	precondition: wiz.finished;
	postcondition:
		TopicWeightsMatch (wiz.topics, test.qs, error) and
		TypeWeightsMatch (wiz.types, test.qs, error) and
		error >= 0 and
		not (exists (smallerError: integer) 
			((smallerError < error)
			and (TopicWeightsMatch (wiz.topics, test.qs, smallerError))
			and (TypeWeightsMatch (wiz.types, test.qs, smallerError))));
	description: (*
		This is not a user-visible operation, but can only be expressed
		through pre- and post-conditions. It returns the smallest margin
		of error required in order to make the given questions fit the
		user-entered weights. *);
end SmallestMarginOfError;

(* LowerMinimumTime: returns the same Wizard object, but the lower limit of the
   Estimated Length in Minutes range is decremented by one minute. This is used
   so that if the software cannot generate a test based on the given criteria,
   it reduces the amount of time required for the test to consume, and attempts
   generation again. See 2.2.1.2, subsection Weights Values Flexibility. *)
function LowerMinimumTime (wiz:Wizard) -> (Wizard)
		= {wiz.step, wiz.finished, wiz.name, wiz.genType,
		   wiz.classes, wiz.topics,
		   {wiz.critRanges.averageDiff,
                    wiz.critRanges.allowedDiff,
	            {wiz.critRanges.estTimeLength.lower - 1,
                     wiz.critRanges.estTimeLength.upper}}};

function Min (x:integer, y:integer) -> (integer) = if (x < y) then x else y;
function Max (x:integer, y:integer) -> (integer) = if (x > y) then x else y;
function MinReal (x:real, y:real) -> (real) = if (x < y) then x else y;
function MaxReal (x:real, y:real) -> (real) = if (x > y) then x else y;

function TotalTimeOfQuestions (coll:TestQuestion*) -> (real) =
	if (#coll = 0) 
	then 0
	else (coll[1].time + TotalTimeOfQuestions (coll - coll[1]))
end TotalTime;

(* Utility functions used for post/preconditions in the Finish operation *)

(* PointTotal: adds up the point value of every single question in the list. *)
function PointTotal (coll:TestQuestion*) -> (integer) =
	if (#coll = 0)
	then 0
	else (coll[1].points + PointTotal (coll - coll[1]))
end PointTotal;

(* Difficulty Total: adds up the difficulty rating of every single question in
   the list, for the purposes of finding the mean. *)
function DifficultyTotal (coll:TestQuestion*) -> (integer) =
	if (#coll = 0) then 0 else (coll[1].difficulty + DifficultyTotal (coll - coll[1]))
end DifficultyTotal;

(* AverageDifficultyOfQuestions: finds the mean difficulty rating of the
   questions in the list. *)
function AverageDifficultyOfQuestions (coll:TestQuestion*) -> (real) =
	DifficultyTotal(coll) / #coll
end AverageDifficultyOfQuestions;

(* Returns the lowest difficulty rating out of all the given questions. *)
function MinDifficulty (coll:TestQuestion*) -> (integer) =
	if (1 = #coll)
	then coll[1].difficulty
	else Min(coll[1].difficulty, MinDifficulty (coll - coll[1]))
end MinDifficulty;

(* Returns the highest difficulty rating out of all the given questions. *)
function MaxDifficulty (coll:TestQuestion*) -> (integer) =
	if (1 = #coll)
	then coll[1].difficulty
	else Max(coll[1].difficulty, MaxDifficulty (coll - coll[1]))
end MaxDifficulty;

(* Indicates the number of times that a particular topic is touched upon by
   any question, given a list of questions. *)
function TopicRepresentation (coll:TestQuestion*, what:Topic) -> (integer) =
	(let thisCount = if (what in coll[1].topics) then 1 else 0;
	if (1 = #coll)
	then thisCount
	else (thisCount + TopicRepresentation (coll - coll[1], what)))
end TopicRepresentation;

(* Finds all the questions of a given Type, then adds up their point
   values. *)
function TypeRepresentation (coll:TestQuestion*, what:Type) -> (integer) =
	(let thisCount = if (coll[1].qt = what) then coll[1].points else 0;
	if (1 = #coll)
	then thisCount
	else (thisCount + TypeRepresentation (coll - coll[1], what)))
end TypeRepresentation;

(* Returns true iff the question list has questions from a particular set of
   classes. If validClasses has CSC101 and CSC102, then the Question list
   can only have questions pertaining to those classes. *)
function HasValidClasses (coll:TestQuestion*, validClasses:ClassName*) -> (boolean) =
	(forall (q in coll)
		q.cn in validClasses)
end HasValidClasses;

(* Similar to the HasValidClasses function, but works on topics. *)
function HasValidTopics (coll:TestQuestion*, validTopics:Topic*) -> (boolean) =
	forall (q in coll)
		forall (t in q.topics)
			t in validTopics
end HasValidTopics;

function HasValidTypes (coll:TestQuestion*, validTypes:Type*) -> (boolean) =
	forall (q in coll)
		q.qt in validTypes
end HasValidTypes;

(* Given a list of WizardTopics, returns a list of Topics. This has the effect
   of  cutting away the weight values (see the WizardTopic object). *)
function GetTopics (coll:WizardTopic*) -> (Topic*) =
	if (0 = #coll)
	then empty
	else (GetTopics (coll - coll[1]) + coll[1].topic)
end GetTopics;

(* Given a list of WizardTypes, returns a list of Types. This has the effect
   of cutting away the weight values. (see the WizardType object).*)
function GetTypes (coll:WizardType*) -> (Type*) =
	if (0 = #coll)
	then empty
	else (GetTypes (coll - coll[1]) + coll[1].qt)
end GetTypes;

function FitsRange (r:Range, v:integer) -> (boolean) = ((v >= r.lower) and (v <= r.upper));

(* The ...WeightsMatch functions make sure the given weights match the representation
   of authors and topics in the given question list. A don't care weight is given by zero,
   so if any weight is non-positive, then that means the weights don't matter. *)
function TopicWeightsMatch (tops:WizardTopic*, qs:TestQuestion*, error:integer) -> (boolean) =
	exists (top in tops)
		top.weight <= 0
	or
	exists (factor:real)
		forall (top in tops)
			FitsRange ({-error, +error}, top.weight * factor - TopicRepresentation (qs, top.topic))
end TopicWeightsMatch;

function TypeWeightsMatch (types:WizardType*, qs:TestQuestion*, error:integer) -> (boolean) =
	exists (type in types)
		type.weight <= 0
	or
	exists (factor:real)
		forall (type in types)
			FitsRange ({-error, +error}, type.weight * factor - TypeRepresentation (qs, type.qt))
end TypeWeightsMatch;

(* Returns the weight of the lowest-weighted Type. *)
function MinTypeWeight (types:WizardType*) -> (real) =
	if (1 = #types)
	then types[1].weight
	else MinReal (types[1].weight, MinTypeWeight(types - types[1]))
end MinTypeWeight;

(* Returns the weight of the lowest-weighted Topic. *)
function MinTopicWeight (topics:WizardTopic*) -> (real) =
	if (1 = #topics)
	then topics[1].weight
	else MinReal (topics[1].weight, MinTopicWeight(topics - topics[1]))
end MinTopicWeight;

(*-------------------- END MATT DeVORE'S SECTION --------------------*)


(*-------------------- BEGIN Ben Williams's section------------------*)
operation AddQuestion is
	inputs: t:Test, q:Question, p:PointsPossible;
	outputs: t':Test;
	precondition: (* The given question is not in the given input  test. *)
		(not (exists (q' in t.qs) q'.id = q.id));
	postcondition:
		(* The given question is in the output test. *)
		(exists (newq in t'.qs) q.id = newq.id and newq.points = p) and
		(*
		 * A question is in the output test if and only if it is the new
		 * question or if it is in the input test.
		 *)
		(forall (q':TestQuestion)
			(q' in t'.qs) iff ((q'.id = q.id) or (q' in t.qs)))
		and
		(*
		 * There exists a test question in the output test that is the new
		 * question with the same id, number of points, and is at the end
		 * of the test.
		 *)
		(exists (tq in t'.qs)
			(tq.id = q.id) and (tq.points = p) and (tq.num = #(t.qs) + 1));
	description: (*
		AddQuestion adds the given question to the given test, which in 
		turn produces an updated test containing that question with the
		given number of points.
	*);
end AddQuestion;

operation RemoveQuestion is
	inputs: id:ID, t:Test;
	outputs: t':Test;
	precondition: (* The given question is in the given input test. *)
		((exists (q' in t.qs) q'.id = id));
	postcondition:
		(* The given question is not in the output test. *)
		(not (exists (q' in t'.qs) (q'.id = id)))
		and
		(*
		 * A question is in the output test if and only if it is not
		 * the given question to be removed and if it is in the input
		 *test.
		 *)
		(forall (r':TestQuestion)
			(r' in t'.qs) iff ((r'.id != id) and (r' in t.qs)));
	description: (*
		RemoveQuestion removes the Question with the matching given ID 
		from the given test, which in turn produces an updated Test 
		without a question matching the given ID.
	*);
end RemoveQuestion;

operation EditQuestion
	inputs:  t:Test, id:ID, tq:TestQuestion;
	outputs:  t':Test;
	precondition: (* The question with the given id exists in the test. *)
		(exists (q in t.qs) (q.id = id) and (q.type = tq.type));
	postcondition:
		(* The new question is in the test *)
		tq in t.qs
		and
		(*
		 *  The number of the editied question is the same as the
		 *  question was before it was edited(replaced)
		 *)
		(exists (q' in t.qs) (q'.id = id) and (q'.num = tq.num))
		and
		(*
		 *  A question is only in the test if it was in the input test
		 *  and is not the original question that will be edited or if
		 *  it is the edited version of the the question that was changed.
		 *)
		(forall (s':TestQuestion)
			(s' in t'.qs) iff (((s'.id != id) and (s' in t.qs)) or (s'.id = tq.id)));
	description: (*
		EditQuestion finds the test question on the given test with an ID
		matching the given ID.  This test question is replaced with the
		given updated or edited question and put back in the Test,
		which is then returned.
	*);
end EditQuestion;

operation MoveUp is
	inputs: t:Test, id:ID;
	outputs: t':Test;
	precondition: 
		(*
		 * The question to be moved up does not exist at the top
		 * of the list (in the 1st question spot)
		 *)
		(exists (q' in t.qs) (q'.id = id) and q'.num != 1);
	postcondition:
		(*
		 * The number is moved up into the position 1 above it and the 
		 * number in that place is moved down to where the number to be
		 * moved originally was.
		 *)
		((exists (q' in t.qs)
		 (exists (q'' in t'.qs)
			(q'.id = id) and (q''.id = id) and (q''.num = q'.num - 1)
		and
		((exists (r' in t.qs)
		 (exists (r'' in t'.qs)
			(r'.id = r''.id) and (r'.num = q''.num) and (r''.num = q'.num)))))));
	description: (*
		* MoveUp moves the question matching the input id up one spot in the
		* tests order of questions.
	*);
end MoveUp;

operation MoveDown is
	inputs: t:Test, id:ID;
	outputs: t':Test;
	precondition: 
		(*
		 * The question to be moved up does not exist at the top
		 * of the list (in the 1st question spot)
		 *)
		(exists (q' in t.qs) ((q'.id = id) and (q'.num != #(t.qs))));
	postcondition:
		(*
		 * The number is moved up into the position 1 above it and the 
		 * number in that place is moved down to where the number to be
		 * moved originally was.
		 *)
		((exists (q' in t.qs)
		 (exists (q'' in t'.qs)
			(q'.id = id) and (q''.id = id) and (q''.num = q'.num + 1)
		and    
		((exists (r' in t.qs)
		 (exists (r'' in t'.qs)
			(r'.id = r''.id) and (r'.num = q''.num) and (r''.num = q'.num)))))));
	description: (*
		* MoveDown moves the question matching the input id down one spot in the
		* tests order of questions.
	*);
end MoveDown;

(*-------------------- END Ben Williams's section--------------------*)

end TestGeneration;