\ io
\
\ io_particle
\ class of particle (a hp_ component) created for the piece io.
\
\
\ usage:
\
\ the simulation can be altered in the following ways:
\
\	parameter          normal  modify  random  mirror
\
\	particle mass        xx      xx      xx      xx
\	particle velocity    xx      xx      xx      xx
\	particle position    xx      xx      xx      xx
\
\ io.particle class' methods:
\
\	MODIFY.MASS:		( sel# --  , transform particle's mass )
\	MODIFY.POSITION:	( sel# --  , transform particle's position )
\	MODIFY.VELOCITY:	( sel# --  , transform particle's velocity )
\
\ particle.list class' methods:
\
\	MODIFY.MASS:		( elm# sel# --  , transform particle's mass )
\	MODIFY.POSITION:	( elm# sel# --  , transform particle's position )
\	MODIFY.VELOCITY:	( elm# sel# --  , transform particle's velocity )
\
\ in each case, the argument "sel#" is the transformation selector. The
\ following constants have been defined for these transformation selectors:
\
\	hp_norm		\ zero or normalize parameter
\	hp_incr		\ increment
\	hp_decr		\ decrement
\	hp_rand		\ randomize
\	hp_flip		\ mirror or flip
\
\ in addition, in the particle.list's methods, the argument "elm#" selects
\ the particle for transformation. Two special case the particle selectors
\ have been defined:
\
\	hp_rand_elm		\ apply transformation on particle selected at random 
\	hp_every_elm	\ apply transformation on every particle in list
\
\
\ see the file io_hp for the use of this component.
\
\ see the file io_top for more information on io itself.
\
\
\ constructor: Han-earl Park
\ copyright 2008 buster & friends' C-ALTO Labs
\
\ www.busterandfriends.com/io
\
\ (Edinburgh, November 1996 -
\ (London, August 1997 -
\ (Den Haag, October 1997 -
\ (Valencia, March 1999 -
\ (Southampton, May 2000 -
\ (Cork, April 2006 -
\
\ (Cork, October 2008 -
\
\	REV: 0.0.1 alpha   (Southampton, October  2000)
\	REV: 0.0.1 beta    (Southampton, November 2000)
\	REV: 0.0.1 alpha++ (Southampton, July 2004)
\	REV: 0.0.1 beta++  (Cork, May 2010)
\
\
\ MOD: HeP 04/19/00	Add io_particle component.
\ MOD: HeP 05/25/00	Base particle coord around 0 (the "origin"). This
\					simplifies mirror transformation of position.
\ MOD: HeP 05/31/00	Add PUT.FADE.RATE: method to the static.particle class.
\ MOD: HeP 06/01/00	Add the particle.list class that does what the io.space
\					class used to do -- distribute messages to the particles.
\ MOD: HeP 06/07/00	Change stack behavior of the MODIFY...: methods from
\					( n indx --  ) to ( indx --  ).
\					Replace the hp_modify selector with hp_incr and hp_decr.
\					Rename (condense) the names of the other selectors.
\ MOD: HeP 06/28/00	Add the FREEZE: method to the particle.holder class.
\ MOD: HeP 10/01/00	Update comments & documentation.
\ MOD: HeP 10/16/00	Add ability to select particle at random from
\					transformation from particle.list.
\					Define constants for the "special" particle selectors.
\ REV: 0.0.1 alpha	__________________________________________________________
\ MOD: HeP 11/09/00	Experimented with other kinds of "mass decay" of the
\					static.particle. Unimpressive results.
\ REV: 0.0.1 beta	__________________________________________________________
\ MOD: HeP 05-01-04	Move all includes (and conditional includes) from the
\					individual files to load_io.
\ REV: 0.0.1 a ++	__________________________________________________________
\ REV: 0.0.1 b ++	__________________________________________________________
\					Version for performance at Blackrock Castle Observatory,
\					Cork, Ireland, May 25, 2010.


anew task-io_particle


\ transformation selectors

00  constant  hp_norm		\ zero or normalize parameter
01  constant  hp_incr		\ increment
02  constant  hp_decr		\ decrement
03  constant  hp_rand		\ randomize
04  constant  hp_flip		\ mirror or flip


\ particle selector

-2  constant  hp_rand_elm	\ one particle selected at random 
-1  constant  hp_every_elm	\ every particle in list



method MODIFY.MASS:
method MODIFY.POSITION:
method MODIFY.VELOCITY:

method PUT.MIN.MASS:		method PUT.MAX.MASS:
							method PUT.MAX.VELOCITY:


:class  OB.PARTICLE.LIST  <super  OB.OBJLIST
	
	
\ print error

: PRTCL.LIST.REPORT.ERROR	( $ --  , print error message )
	" not a valid element number"  er_return  ob.report.error
;


\ modify particles

:m MODIFY.MASS:		( elm# sel# --  )
	swap
	dup  hp_every_elm =
	IF
		drop
		many: self  0
		DO	dup  i  get: self  modify.mass: []
		LOOP
		drop
	ELSE
		dup  hp_rand_elm =
		IF	drop
			many: self  choose
		THEN
	\
		dup  0  many: self 1-  within?
		IF
			get: self  modify.mass: []
		ELSE
			" modify.mass:"  prtcl.list.report.error  2drop
		THEN
	THEN
;m


:m MODIFY.POSITION:		( elm# sel# --  )
	swap
	dup  hp_every_elm =
	IF
		drop
		many: self  0
		DO	dup  i  get: self  modify.position: []
		LOOP
		drop
	ELSE
		dup  hp_rand_elm =
		IF	drop
			many: self  choose
		THEN
	\
		dup  0  many: self 1-  within?
		IF
			get: self  modify.position: []
		ELSE
			" modify.position:"  prtcl.list.report.error  2drop
		THEN
	THEN
;m


:m MODIFY.VELOCITY:		( elm# sel# --  )
	swap
	dup  hp_every_elm =
	IF
		drop
		many: self  0
		DO	dup  i  get: self  modify.velocity: []
		LOOP
		drop
	ELSE
		dup  hp_rand_elm =
		IF	drop
			many: self  choose
		THEN
	\
		dup  0  many: self 1-  within?
		IF
			get: self  modify.velocity: []
		ELSE
			" modify.velocity:"  prtcl.list.report.error  2drop
		THEN
	THEN
;m


:m FREEZE:	(  --  , zero particle velocity )
	many: self  0
	DO	i  get: self  freeze: []
	LOOP
;m

;class



:class  OB.IO.PARTICLE  <super  OB.PARTICLE
	
	iv.long  iv-prtcl-min-mass
	iv.long  iv-prtcl-max-mass
	
	iv.long  iv-prtcl-mid-mass
	

:m DEFAULT:	(  --  )
	default: super
\
	300  iv=> iv-prtcl-min-mass
	900  iv=> iv-prtcl-max-mass
	600  iv=> iv-prtcl-mid-mass
\
	iv-prtcl-mid-mass  put.mass: self
;m

:m NEW:	(  --  )
	new: super
	hp_range 2/  dup negate  swap  -1  put.range: self
;m



\ particle mass

: PRTCL.SET.MASS	(  --  )
	iv-prtcl-max-mass  iv-prtcl-min-mass -  2/
	iv-prtcl-min-mass +
\
	iv=> iv-prtcl-mid-mass
;


:m PUT.MAX.MASS:	(  --  )
	iv=> iv-prtcl-max-mass
	prtcl.set.mass
;m

:m PUT.MIN.MASS:	(  --  )
	iv=> iv-prtcl-min-mass
	prtcl.set.mass
;m



\ print error

: IO.HP.REPORT.ERROR	( $ --  , print error message )
	" unrecognised modification selector"  er_return  ob.report.error
;



\ modify particles mass

: NORM.MASS	(  --  )
	iv-prtcl-mid-mass
	put.mass: self
;

: INCR.MASS	(  --  )
	get.mass: self  4+  iv-prtcl-max-mass MIN
	put.mass: self
;

: DECR.MASS	(  --  )
	get.mass: self  4-  iv-prtcl-min-mass MAX
	put.mass: self
;

: RAND.MASS	(  --  )
	iv-prtcl-max-mass  iv-prtcl-min-mass  wchoose
	put.mass: self
;

: FLIP.MASS	(  --  )
	iv-prtcl-mid-mass  get.mass: self  -
	iv-prtcl-mid-mass  +
	put.mass: self
;

:m MODIFY.MASS:		( indx --  )
	CASE
		hp_norm  OF  norm.mass  ENDOF
		hp_incr  OF  incr.mass  ENDOF
		hp_decr  OF  decr.mass  ENDOF
		hp_rand  OF  rand.mass  ENDOF
		hp_flip  OF  flip.mass  ENDOF
	\
		" modify.mass:"  io.hp.report.error
	ENDCASE
;m



\ modify particles position

: NORM.POSITION	(  --  , move to "origin" )
	dimension: self  0
	DO	0
	LOOP
	hp_position  put: self
;

: INCR.POSITION	(  --  )
	dimension: self  0
	DO	i  hp_position  ed.at: self  4+
		i  hp_position  ed.to: self
	LOOP
;

: DECR.POSITION	(  --  )
	dimension: self  0
	DO	i  hp_position  ed.at: self  4-
		i  hp_position  ed.to: self
	LOOP
;

: RAND.POSITION	(  --  )
	dimension: self  0
	DO	i at: iv-prtcl-range  choose
		i at: iv-prtcl-min +
	LOOP
	hp_position  put: self
;

: FLIP.POSITION	(  --  )
	dimension: self  0
	DO	i  hp_position  ed.at: self  negate
		i  hp_position  ed.to: self
	LOOP
;

:m MODIFY.POSITION:	( sel# --  )
	CASE
		hp_norm  OF  norm.position  ENDOF
		hp_incr  OF  incr.position  ENDOF
		hp_decr  OF  decr.position  ENDOF
		hp_rand  OF  rand.position  ENDOF
		hp_flip  OF  flip.position  ENDOF
	\
		" modify.position:"  io.hp.report.error
	ENDCASE
;m



\ modify particles velocity

: NORM.VELOCITY	(  --  )
	dimension: self  0
	DO	0
	LOOP
	hp_velocity  put: self
;

: INCR.VELOCITY	(  --  )
	dimension: self  0
	DO	i  hp_velocity  ed.at: self  4+
		i  hp_velocity  ed.to: self
	LOOP
;

: DECR.VELOCITY	(  --  )
	dimension: self  0
	DO	i  hp_velocity  ed.at: self  4-
		i  hp_velocity  ed.to: self
	LOOP
;

: RAND.VELOCITY	(  --  )
	dimension: self  0
	DO	iv-prtcl-vel-max  choose choose+/-
	LOOP
	hp_velocity  put: self
;

: FLIP.VELOCITY	(  --  )
	dimension: self  0
	DO	i  hp_velocity  ed.at: self  negate
		i  hp_velocity  ed.to: self
	LOOP
;

:m MODIFY.VELOCITY:	( sel# --  )
	CASE
		hp_norm  OF  norm.velocity  ENDOF
		hp_incr  OF  incr.velocity  ENDOF
		hp_decr  OF  decr.velocity  ENDOF
		hp_rand  OF  rand.velocity  ENDOF
		hp_flip  OF  flip.velocity  ENDOF
	\
		" modify.velocity:"  io.hp.report.error
	ENDCASE
;m



\ print

:m PRINT:	(  --  )
	print: super
	
;m

;class



method PUT.FADE.RATE:


:class  OB.IO.STATIC.PARTICLE  <super  OB.IO.PARTICLE
	
	iv.byte  iv-prtcl-fade-rate
	
	
:m DEFAULT:	(  --  )
	default: super
	1  iv=> iv-prtcl-fade-rate
\
	 600  iv=> iv-prtcl-min-mass
	3000  iv=> iv-prtcl-max-mass
	1800  iv=> iv-prtcl-mid-mass	\ ***
\
	iv-prtcl-max-mass  put.mass: self
;m


:m PUT.FADE.RATE:	( n --  )
	abs  iv=> iv-prtcl-fade-rate
;m


\ set larger mass value than the dynamic particles

:m MODIFY.MASS:		( indx --  )
	dup  hp_norm =
	IF
		drop
		iv-prtcl-max-mass  put.mass: self
	ELSE
		modify.mass: super
	THEN
;m


:m UPDATE:	(  --  )
	self  refresh: []
	iv-prtcl-mass  iv-prtcl-fade-rate -  iv-prtcl-min-mass MAX
	iv=> iv-prtcl-mass
;m

;class