arg.coffee

### arg =====================================================================

Tags
----
scripting, JS, internal, treenode, general concept

Parameters
----------
z

General description
-------------------
Returns the angle of complex z.

###

###
 Argument (angle) of complex z

	z		arg(z)
	-		------

	a		0

	-a		-pi			See note 3 below

	(-1)^a		a pi

	exp(a + i b)	b

	a b		arg(a) + arg(b)

	a + i b		arctan(b/a)

Result by quadrant

	z		arg(z)
	-		------

	1 + i		1/4 pi

	1 - i		-1/4 pi

	-1 + i		3/4 pi

	-1 - i		-3/4 pi

Notes

	1. Handles mixed polar and rectangular forms, e.g. 1 + exp(i pi/3)

	2. Symbols in z are assumed to be positive and real.

	3. Negative direction adds -pi to angle.

	   Example: z = (-1)^(1/3), abs(z) = 1/3 pi, abs(-z) = -2/3 pi

	4. jean-francois.debroux reports that when z=(a+i*b)/(c+i*d) then

		arg(numerator(z)) - arg(denominator(z))

	   must be used to get the correct answer. Now the operation is
	   automatic.
###

DEBUG_ARG = false

Eval_arg = ->
	push(cadr(p1))
	Eval()
	arg()

arg = ->
	save()
	p1 = pop()
	push(p1)
	numerator()
	yyarg()
	push(p1)
	denominator()
	yyarg()
	subtract()
	restore()

#define RE p2
#define IM p3

yyarg = ->
	save()
	p1 = pop()

	# case of plain number
	if (ispositivenumber(p1) or p1 == symbol(PI))
		if isdouble(p1) or evaluatingAsFloats
			push_double(0)
		else
			push_integer(0)
	else if (isnegativenumber(p1))
		if isdouble(p1) or evaluatingAsFloats
			push_double(Math.PI)
		else
			push(symbol(PI))
		negate()

	# you'd think that something like
	# arg(a) is always 0 when a is real but no,
	# arg(a) is pi when a is negative so we have
	# to leave unexpressed
	else if (issymbol(p1))
		push_symbol(ARG)
		push(p1)
		list(2)

	else if (car(p1) == symbol(POWER) && equaln(cadr(p1), -1))
		# -1 to a power
		if evaluatingAsFloats
			push_double(Math.PI)
		else
			push(symbol(PI))
		push(caddr(p1))
		multiply()
	else if (car(p1) == symbol(POWER) && cadr(p1) == symbol(E))
		# exponential
		push(caddr(p1))
		imag()
	# arg(a^(1/2)) is always equal to 1/2 * arg(a)
	# this can obviously be made more generic TODO
	else if (car(p1) == symbol(POWER) && isoneovertwo(caddr(p1)))
		if DEBUG_ARG then console.log "arg of a sqrt: " + p1
		if DEBUG_ARG then debugger
		push(cadr(p1))
		arg()
		if DEBUG_ARG then console.log " = 1/2 * " + stack[tos-1]
		push(caddr(p1))
		multiply()
	else if (car(p1) == symbol(MULTIPLY))
		# product of factors
		push_integer(0)
		p1 = cdr(p1)
		while (iscons(p1))
			push(car(p1))
			arg()
			add()
			p1 = cdr(p1)
	else if (car(p1) == symbol(ADD))
		# sum of terms
		push(p1)
		rect()
		p1 = pop()
		push(p1)
		real()
		p2 = pop()
		push(p1)
		imag()
		p3 = pop()
		if (isZeroAtomOrTensor(p2))
			if evaluatingAsFloats
				push_double(Math.PI)
			else
				push(symbol(PI))
			if (isnegative(p3))
				negate()
		else
			push(p3)
			push(p2)
			divide()
			arctan()
			if (isnegative(p2))
				if evaluatingAsFloats
					push_double(Math.PI)
				else
					push_symbol(PI)
				if (isnegative(p3))
					subtract();	# quadrant 1 -> 3
				else
					add();		# quadrant 4 -> 2
	else

		if (!isZeroAtomOrTensor(get_binding(symbol(ASSUME_REAL_VARIABLES))))
			# if we assume all passed values are real
			push_integer(0)
		else
			# if we don't assume all passed values are real, all
			# we con do is to leave unexpressed
			push_symbol(ARG)
			push(p1)
			list(2)


	restore()