Cornell University Department of Computer Science

Assignment 1 (Accelerator Physics)

Submit on the CMS two weeks into the course
Magnet-Track Database

Introduction

Buried 40 feet beneath Alumni Field on the Cornell University campus is the 768 meter Cornell Electron Storage Ring (CESR). CESR is an electron-positron collider operating at a center-of-mass energy in the range of 3.5-12 GeV. Its performance builds on Cornell's long-standing program in accelerator physics. Cornell built a cyclotron as early as 1935. CESR, completed in 1979, stores beams accelerated by the Cornell Synchrotron, an earlier machine used for fixed target experiments. Using superconducting radio-frequency cavities and pretzel orbits (both technologies developed at Cornell), CESR operated throughout the 1990's as the highest luminosity electron-positron collider in the world.

At the end of the last decade, a new program began at CESR, known as CESR-c/CLEO-c. The physics focus shifted from the bottom quark to the lighter charm quark, and the energy of CESR was lowered accordingly.

This process continues as CESR is outfitted with new beam optics and instrumentation and as new techniques for improving performance are developed and perfected.

CESR does not serve only the high energy physics community; it also provides synchrotron radiation utilized for materials research. Each year, this state-of-the-art x-ray facility, known as the Cornell High Energy Synchrotron Source (CHESS), allows 400-500 scientists and scientists-in-training to collect data that comprises all or part of their research programs.

The CESR-c/CLEO-c program is scheduled to end in 2008, but two proposals are under development that will utilize CESR for work on future facilities. One of them, planned for 2012, is called the Energy Recovery Linac (ERL). This ultra-high brilliance x-ray source is a proposal by Cornell University physicists to use the CESR ring and a superconducting linac to produce very short and frequent pulses of high coherence, high energy x-rays. For more information, visit Cornell University Laboratory for Elementary-Particle Physics website.

An important component of the ERL is a magnet track where the electron can move along. It is a bending track whose cross-section area is rectangle. The magnet has several parameters such as the width and height of the cross-section, the radius and length of the bending track, and the charge of the electrons running through this magnet. Different values of the parameters create different experimental results.

Your task in this assignment is to develop a simple Java class Magnet to maintain information about a magnet and a JUnit class MagnetTester to maintain a suite of testcases for class Magnet. This assignment will help illustrate how Java’s classes and objects can be used to maintain data about a collection of things —like magnet tracks.

Read the whole assignment before starting. Follow the instructions given below in order to complete the assignment as quickly and as efficiently as possible.

HELP

If you don't know where to start, if you don't understand testing, if you are lost, SEE SOMEONE IMMEDIATELY —the course instructor, a TA, a consultant. Do not wait. A little one-on-one help can do wonders.

Class Magnet

An instance of class Magnet represents a single magnet. It has several fields that one might use to describe a magnet, as well as methods that operate on these fields. Here are the fields, all of which should be private (you can choose the names of these fields).

• name (a String)
• type (a char –'H' for high energy or 'L' for low energy)
• month of construction (an int)
• year of construction (an int)
• length in meters (an int)
• prototype (a Magnet object from which this one has been developed)
• number of versions (an int: the number of magnets that use this magnet as a prototype)
• id number (an int: a number used to reference this Magnet in a database under development)

Here are some details about these fields.

• The name is a String of characters. It is okay for two magnets to have the same name.
• The month of construction is in the range 1..12, representing a month from January to December. The year of construction is something like 1997 or 2005. Do not worry about invalid dates; do not write code that checks whether dates are valid: assume they are valid.
• The length is always positive. It does not make sense to have a magnet whose length is not positive. Do not write code that checks whether length is positive: assume it is valid.
• The id number is an index into a database. Assume all id numbers given are unique; do not write code to check whether a magnet with a given id number already exists. If a magnet hasn’t been assigned an id number yet, this field should contain -1.
• The prototype is the name of a Magnet object (manila folder) on which this magnet was developed. It is not a String. The prototype is null if this is an original magnet.

Accompanying the declarations of these fields should be comments that describe what each field means —what it contains.  For example, on the declaration of the field type, state in a comment that the field represents what kind of magnet this is, 'H' for high energy, etc. The collection of the comments on these fields is called the “class invariant”. The class describes all legal values for the fields together.

Whenever you write a method (see below), look through the class invariant and convince yourself that the class invariant is correct when the method terminates.

Magnet Methods

Class Magnet has the following methods. Pay close attention to the parameters and return values of each method. The descriptions, while informal, are complete.

Constructor	Description
Magnet(String name, char type, int length, int month, int year)	Constructor: a new Magnet. Parameters are, in order, the name of the magnet, its type ('H' for high energy or 'L' for low energy), the length of the magnet (positive), and the month (in the range 1..12) and year of construction. The new magnet has no id number, and it has no prototype (it is the original one) and no other versions. All parameters are valid as described.
Magnet(String name, char type, Magnet prototype, int length, int month, int year, int id number)	Constructor: a new Magnet. Parameters are, in order, the name of the Magnet, its type ('H' for high energy or 'L' for low energy), its prototype, the length, the month and year of construction, and the id number. Precondition: All parameters are valid as described, prototype is not null, the length is > 0, and the id number is ≥ 0.

When you write a constructor body, be sure to set all the fields to appropriate values.

Getter Method	Description
getName()	= the name of this magnet. (a String)
getType()	= the type of this magnet —either 'H' or 'L'. (a char)
getLength()	= the length of this magnet. (an int)
getMOC()	= the month this magnet was constructed, in the range 1..12. (an int)
getYOC()	= the year this magnet was constructed. (an int)
getPrototype()	= the name (of the folder containing) this magnet’s prototype. (a Magnet)
getId()	= this magnet’s id number (-1 if it has not been assigned one). (an int)
getVersions()	= the number of magnets that have this one as a prototype. (an int)
toString()	= a String representation of this Magnet. Its precise specification is discussed below.

Setter Method	Description
setName(String n)	Set the name of this magnet to n.
setType(char t)	Set the type of this magnet to t. Precondition: t is either 'H' or 'L'
setLength(int len)	Set the length of this magnet to len.
setMOC(int m)	Set the month this magnet was constructed to m. Precondition: m is in the range 1..12.
setYOC(int y)	Set the year this magnet was constructed to y.
setPrototype(Magnet m)	Set the prototype of this magnet to m. Precondition: This magnet’s prototype is null, and m is not null.
setId(int i)	Set this magnet’s id number to i. Precondition: i >= 0, and the id number is currently -1.

Comparison Method	Description
isLarger(Magnet m)	= "mis not null, and this magnet is larger than m—i.e. this magnet's length is greater than that of m". Note that use only the length for comparison.
isLarger(Magnet m1, Magnet m2 )	Static method. = "m1 and m2 are not null, and m1 is larger than m2 —i.e. m1's length is greater than m2's length". Note that use only the length for comparison.

Make sure that the names of your methods match those listed above exactly, including capitalization. The number of parameters and their order must also match. The best way to ensure this is to copy and paste our names. Our testing will expect those method names, so any mismatch will fail during our testing. Parameter names will not be tested —you can change the parameter names if you want.

Each method MUST be preceded by an appropriate specification, or "spec", as a Javadoc comment. The best way to ensure this is to copy and paste. After you have pasted, be sure to do any necessary editing. For example, the spec of a function does not have to say that the function yields a boolean or int or anything else, because that is known from the header of the method.

A precondition should not be tested by the method; it is the responsibility of the caller to ensure that the precondition is met. For example, it is a mistake to call method setPrototype with null for the prototype argument. However, in function isLarger, the tests for m1 and m2 not null MUST be made (because there is no precondition).

It is possible for magnet m1 to be m2's prototype and visa versa, at the same time. We do not check for such strange occurrences.

In writing method setPrototype, be careful! If P is becoming the prototype of this Magnet, then P has one more version, and its field that contains its number of versions has to be updated accordingly.

Do not use if-statements, and use conditional statement (...? ... : ...) only in function toString. Boolean expressions, using the operators && (AND), || (OR), and ! (NOT), are sufficient to implement the comparison methods.

Function toString

We illustrate the required format of the output of toString with an example and then make some comments. Here is an example of output from function toString:

"L magnet CESR. Length 5 m. Id 101. Constructed 6/1983. Has 2 versions."

Here are some points about this output.

1. Exactly one blank separates each piece of information, and the periods are necessary.
2. The 'L' at the beginning means it is low energy. Use 'H' for high energy.
3. The name of the magnet follows "magnet".
4. If the id number is unknown, omit it entirely (in the example above, omit " Id 101.").
5. The prototype is not described in the output of this function.
6. If the magnet has exactly 1 version, the word "version" should appear instead of "versions".
7. In writing the body of function toString, do not use if-statements or switches. Instead, use the conditional expression (condition ? expression-1: expression-2) This is the only place you can use the conditional expression.

Class MagnetTester

You must build a suite of test cases as you develop class Magnet in a JUnit class MagnetTester. Make sure that your test suite adheres to the following principles:

• Every method in your class Magnet needs at least one test case in the test suite.
• The more interesting or complex a method is, the more test cases you should have for it. What makes a method 'interesting' or complex can be the number of interesting combinations of inputs that method can have, the number of different results that the method can have when run several times, the different results that can arise when other methods are called before and after this method, and so on.
• Here is one important point. If an argument of a method can be null, there should be a test case that has null for that argument.
• Test each method (or group of methods) carefully before moving on to the rest of the assignment.

How to do this assignment

First, remember that if-statements are not allowed. If your assignments has if-statements, you will be asked to revise the assignment and resubmit.

Second, you should develop and test class in a methodologically sound way, which we outline below. If we detect that you did not develop it this way, we may ask you to start from scratch and write one of the other alternatives for this assignment.

• First, start a new folder on your hard drive that will contain the files for this project. Start every new project in its own folder.
• Second, write a class Magnet using DrJava. In it, declare the fields in class Magnet, compiling often as you proceed. Write comments that specify what these fields mean.
• Third, start a new JUnit class, calling it MagnetTester.
• Fourth, this assignment should properly be done in several parts. For each part, write the methods, write a test procedure in class MagnetTester and add test cases to it for all the methods you wrote, and then test the methods thoroughly. Do not go on to the next group of methods until the ones you are working on are correct. If we determine that you did not follow this way of doing things —for example, you wrote all methods and then tried to test, we may ask you to set this assignment aside and do another instead. Here are the groups of methods.
• (1) The first constructor and all the getter methods of class Magnet.
• (2) The second constructor.
• (3) Function toString.
• (4) The setter methods.
• (5) The two comparison methods.

At each step, make sure all methods are correct before proceeding to the next step. When adding a new method, cut and paste the comment and the header from the assignment handout and then edit the comment. It must have suitable javadoc specifications as well as suitable comments on the field declarations. The assignment will not be accepted for testing until it does.

Other hints and directions

• Do not use if statements.
• Remember that a String literal is enclosed in "double quotation marks" and a char literal is enclosed in 'single quotation marks'.
• Be sure to create the javadoc specification and look at it carefully, to be sure that the methods are specified thoroughly and clearly.

Procedure for submission

You may submit the assignment whenever you wish. We will look at it in several steps.

1. If the field specifications and the javadoc specifications are not appropriate, we will ask you to fix them and resubmit.

2. If the field and javadoc specs are ok, we will look at your test cases. If they are inadequate, we will ask you to fix them and resubmit.

3. If the test cases are adequate, we will test your program. If there are errors, you will be asked to correct them and resubmit.

The assignment will be considered completed when it passes all three steps.

Submitting the assignment

First, at the top of file Magnet.java, put a comment that says that you looked carefully at the specifications produced by clicking the javadoc button and checked that the specifications of methods and the class specification were OK (put this comment after doing what the comments says).

Second, upload files Magnet.java and MagnetTester.java on the CMS. You will be asked to upload Ass1.java and Ass1Tester.java. Don't worry about this; just upload files Magnet.java and MagnetTester.java.

Make sure you submit .java files. do not submit a file with the extension/suffix .java~. It will help to set the preferences in your operating system so that extensions always appear.