E852 Documentation: MPS Magnet Map

E852 Documentation: MPS Magnet Map

Herein are documented the following routines:

Introduction

The E852 software can use the following field maps:

Cookbook

  1. To setup the MPS field for a given run number call the function InitMPSfield.

  2. To scale the field according to the hall probe, call the function ProcessMpsHallProbe for each event.

  3. To determine if the field is on or off, call field_isOn.

  4. To get the value of the field in any point, call field_ffield from C, or fieldb from Fortran.

Include files and libraries

To use these functions the program include tracking.h and fieldmodel.h and and should be linked with libUtil.a.

Common Operations

Initialize the MPS field

To initialize the MPS field for a given run, call this function: 
	int runNo;     // run number

	ret = InitMPSfield(runNo,0);

Scale the field

To scale the field according to the hall probe, call this function: 
	
	itape_header_t *event;    // the event pointer

	ProcessMpsHallProbe(event);

Get the field

The routines described in this section assume the coordinates in the MPS coordinate system and return the value of the magnetic field in kGausses.

The MPS coordinate system is defined to have (0,0,0) at the MPS pivot point with Y in the middle of the magnet, the z-axis points downstream, y-axis points up and the x-axis points towards the control room (i.e. towards the open side of the magnet).

From Fortran

		REAL X,Y,Z   - space point
		REAL B(3)    - returned	field value

		CALL FIELDB(X,Y,Z,B)

From C

		#include <ntypes.h>
		#include <fieldmodel.h>

		vector3_t space; - space point
		vector3_t b;	 - field value

		field_ffield(&space,&b);

		dvector3_t dspace; - same, but double instead of float
		dvector3_t db;

		field_dfield(&dspace,&db);

Find the current settings of the magnet

  1. Is the magnet on? 
    	int ret;

	ret = field_isOn();

	if (ret)
	  {
		/* field is on */
	  }
	else
	  {
		/* field is off */
	  }

Less Commonly Used Stuff

Select any field map

	To select any particular field map the following call
	can be used-

		#include <fieldmodel.h>

		field_setSwitch(<name>);

	where <name> is	the name of the	field map-

		"NONE"	  - no field,
		"FIELDB"  - full field
		"FIELDB-3/4" - 3/4 field
		"HALF"	  - half field
		"FIELD93" - the	1993 ziptrack field map
		"UNIFORM" - the	uniform 10 kGauss field map

	The older Fortran routine 'initfield(flag)' can still be used
	with 'flag' equal to 0 for the "FIELDB"	map and
	1 for the "HALF" field map.

Determining the setting of the field for a given run

	To find	out the	setting	(on or off) of the MPS magnet for
	any run, one has to load the run database and get the
	value of the 'run.field' resource:

		int runNo;    // run number
		char*field;   // field setting
	         
		param_loadDatabase("run.field",runNo);

		field =	param_getString("run.field","unknown");

		if (strcmp(field,"FULL") == 0)	    ...	 /* full field */
		else if	(strcmp(field,"3/4") == 0) ...	 /* 3/4 field */
		else if	(strcmp(field,"HALF") == 0) ...	 /* half field */
		else if	(strcmp(field,"OFF") ==	0)  ...	 /* field off  */

Turning the field ON and OFF

	To turn	the field on or	off one	can use	the 'field_toggle' call:

		#include <fieldmodel.h>

		field_toggle(1);   /* turn field on  */
		field_toggle(0);   /* turn field off */

	To find	out the	current	setting	of the field, call:

		#include <fieldmodel.h>

		int isOn;

		isOn = field_isOn();

		if (isOn) /* field is on  */
		else	  /* field is off */

	The Fortran routines 'bon, boff, fieldon and fieldoff'
	can also be used to turn the field on and off.

Field scaling

	Any field map can be scaled by setting the field
	scaling	factor.	The nominal value (i.e.	10 kGauss for
	FIELDB and FIELD93 maps) corresponds to	scaling	equal to 1.0

		#include <fieldmodel.h>

		double newScaling = 1.0;
		double oldScaling;

		oldScaling = field_setBfactor(newScaling);  /* set a new scaling */

		or

		oldScaling = field_getBfactor();  /* get the old scaling factor	*/

	The Fortran routine 'call setbfac(scaling)' can also	be used.

MPS Hall Probe

	The MPS	Hall probe has to be initialized once per run by calling:

		#include <tracking.h>

		InitMpsHallProbe();

	To set the new field scaling using the MPS Hall	probe data on an event per event basis,
	call:

		#include <tracking.h>

		<eventPointer> event;

		ProcessMpsHallProbe(event);

	This call extracts the DVM data, applies necessary calibrations
	and calls the 'field_setBfactor' routine.

ENVIRONMENT

E852_CONFIG and E852_PAR environment variables define the locations of the field map files.

FILES

	~e852/include/fieldmodel.h
	~e852/include/tracking.h
	-lUtil.a

BUGS

	Any field map defines the field	only inside a subvolume, which
	might be different for each field map. Caution should be used
	when calculating fields	far upstream, far downstream or	outside
	the MPS	magnet aperture.

	The MPS	field software has many	internal routines. Some	of them
	are/were used by some older code. Such code has	to be converted
	to use the calls described in this document.

	Only the routines described in the document are	supported.

	Report bugs to Dennis Weygand (weygand@b1.phy.bnl.gov)
	or Const Olchanski (olchansk@b1.phy.bnl.gov)

CO 11 July 1994
revised and htmlified: CO 1995-03-16
revised (added 3/4 field) and more htmlified: CO 1995-05-04
//end file