%Appendix

\renewcommand{\thechapter}{A}

\chapter{Resources and Reactions}

\section{Structure}

\subsection{Transportation}

The transportation network serves as connective tissue that joins
the nodes of the structure together. It is up to the scenario to define
the connectivity graph, but once accomplished this will compute the
overhead in terms of resource burn to transfer individuals and cargo
through the network. 

\begin{figure}[htp]
\epsfxsize=5.5truein
\centerline{\epsfbox{figures/cd_connectivetissue.eps}}
\caption{ConnectiveTissue Class Diagram}
\end{figure}

\subsubsection*{Classes:}

\begin{description}
\item [{Cargo}] A generalized form of transportation for passengers and
cargo. Only these forms of transportation can handle material goods
and individuals. 

\begin{description}
\item [{Attributes:}]~

\begin{description}
\item [{NetworkCapacity}] The number of transport units the transportation
infrastructure can handle. As network capacity approaches this number,
congestion effects set in. 
\item [{numUnits}] Number of transport units actively using the system
at any given time. When this number nears the NetworkCapacity, congestion
delays set in which begin to cut into the efficiency of the system. 
\end{description}
\item [{AirTransport}] Expensive but fast, and often must be used in a
multimodal fashion, where households must transfer their wares up
to the city level first before making airhops between cities.
\item [{GroundCargo}] Well connected, reaching every location with road
coverage.
\item [{Rail}] High initial infrastructure costs and not very well connected,
but fairly economical once everything is in place.
\item [{Ship}] Only a boon to certain cities, and requires some contention
for port infrastructure.
\end{description}
\item [{Pipeline}] Pipeline infrastructure is good for transporting fluid
commodities, such as water, natural gas, sewage, \emph{etc.} 
\item [{Wire}] Distribution system for electricity and information 
\item [{Radio}] Distribution system for information 
\end{description}

\subsection{Reactions}

This package defines reactions that can occur within cells to transform
one set of resources into another set of resources. The definition
of the reaction governs changes to the quantities of inputs and outputs,
and balances them the same way a chemical reaction would be balanced.

\begin{figure}[htp]
\epsfxsize=5.5truein
\centerline{\epsfbox{figures/cd_reactiontypes.eps}}
\caption{ReactionTypes Class Diagram}
\end{figure}

The icons in the top right of some of the classes indicate that those
classes have activity diagrams associated with them. These diagrams
can be viewed in the corresponding System Behavior section. The specific
reactions on the right inherit the activity diagrams from parent classes,
where they can be extended. The \char`\"{}Refining\char`\"{} class
appears to have \char`\"{}lost\char`\"{} its activity diagram, though,
probably due to a bug in the way Rhapsody inherits statecharts; it
should be possible to fix by deleting the class and recreating it.

\begin{figure}[htp]
\epsfxsize=5.5truein
\centerline{\epsfbox{figures/cd_combustionreaction.eps}}
\caption{CombustionReaction Class Diagram}
\end{figure}

This diagram highlights one of the reactions in detail. Other reaction
types would look very similar to this diagram with different combinations
of input and output resources.

\subsection{Resources}

This package details the various generalizations of resources available
in the model.

\begin{description}
\item [{Resource}] A particular resource of interest that can be contained,
traded, or reacted within cells. 
\end{description}

\begin{figure}[htp]
\epsfxsize=6.0truein
\centerline{\epsfbox{figures/cd_resourcestypes.eps}}
\caption{ResourcesTypes Class Diagram}
\end{figure}

\begin{description}
\item [{Money}] Financial resources are often exchanged for goods and services,
so it's worth tracking how much each cell has on reserve.
\item [{Information}] Information can also be transferred and accounts
for education activities or entertainment.
\item [{Fuel}] The Fuel superclass generally refers to any resource that
is useful.

\begin{description}
\item [{Air}] Rather than get too specific in chemistry terms, this class
represents clean useful air for breathing or to provide oxygen for
combustion.
\item [{Electricity}] Electrical distribution is one of the oldest networks
in the world and serves as a catalyst for many other useful reactions,
or merely as a utility to improve the quality of life.
\item [{Food}] Anything people can consume.
\item [{Material}] Any kind of object or artifact that might be transferred.
Along with the mass value inherited from resource, material can also
have a value density, which can increase with the refinement reaction
to represent a lot of what industry does.
\item [{Petroleum}] More traditional fuel products that are not necessarily
restricted to oil or derivatives. Anythings that burns to produce
energy could be included, such as coal and wood.
\item [{Water}] Clean potable water for drinking or for maintenance.
\end{description}
\item [{Waste}] Superclass that represents byproducts that cells probably
don't want to keep around, but that need to be tracked and disposed
of appropriately. Waste can still put a load on the transportation
infrastructure, and require industrial resources to treat and refine
properly.

\begin{description}
\item [{AirPollution}] Any kind of gaseous waste.
\item [{Garbage}] Solid waste products, mostly discarded materials.
\item [{Heat}] Otherwise known as entropy, almost every process surely
creates waste heat that needs to be dissipated.
\item [{Sewage}] Liquid waste that might be drained through the sewage
system.
\end{description}
\end{description}



\section{Behavior}


\begin{description}
\item [{%
\shadowbox{\parbox[t][1\height]{1\columnwidth}{%
\begin{description}
\item [{evWakeup}] Event signalling a person to wake up and begin their
day. 
\item [{evFeed}] Event signalling that the person should make an attempt
at going somewhere to eat. 
\item [{evSleep}] Event signalling person to go somewhere (preferably home)
so they can sleep. 
\end{description}
%
}}%
}]~
\end{description}

\subsection{ResourceEngine}

Each resource engine keeps track of the flow of one resource within
a cell. This includes the input of resource from the environment,
trade of resources with other cells, internal reactions that transform
resources to and from other resources, and waste resource output back
to the environment.

The resource engines are initialized to fire push/pull transaction
events at regular intervals. Pull transactions would offer to exchange
monetary resources for goods and services such as food or electricity.
Push transactions relate to the expulsion of waste, and would end
up in the immediate environment unless picked up by a transportation
system to take to, say, a waste processing plant (represented by an
industry) first. 

\begin{description}
\item [{Relations:}]~
\item [{itsResource}] Each ResourceEngine manages the quantity of one resource
for each Cell unit through transactions in/out of the environment,
trade with other Cell units via connective transportation cells, or
internal reactions within a Cell. 
\item [{Attributes:}]~

\begin{description}
\item [{Amount}] Amount of resource requested per cycle. Type of double,
Public 
\item [{Interval}] Time interval between requests. Type of double, Public 
\end{description}
\end{description}

\subsubsection{Activity Diagram }

Resources essentially attempt three types of transactions:

\begin{enumerate}
\item A request for resources from its parent cell or environment, in client/server
pattern.
\item A peer-to-peer trading agreement scheduled through the scenario setup.
\item A dump of resources back to its parent cell or environment.
\end{enumerate}

\begin{figure}[htp]
\epsfxsize=4.5truein
\centerline{\epsfbox{figures/sc_resourceengine.eps}}
\caption{Resource Engine Statechart}
\end{figure}

\begin{description}
\item [{Expel}] Push transaction to deposit waste into the waste management
infrastructure (or the environment). 

\begin{description}
\item [{Action}] State EntryAction evExpelResource(); 
\item [{Out}] Transition Target: Terminate 
\end{description}
\item [{Pull}] During initial scenario setup, set a starting 

\begin{description}
\item [{Action}] State EntryAction evRequestResource(); 
\item [{Out}] Transition Target: Trade 
\end{description}
\item [{Trade}] Transaction to exchange resource with another cell on the
same level. 

\begin{description}
\item [{Action}] State EntryAction evExchangeResource(); 
\item [{Out}] Transition Target: Expel 
\end{description}
\item [{Terminate}] Local Termination State 
\end{description}

\subsection{ReactionEngine}

Resources are required to fuel several reactions that occur within
a cell. These reactions are driven by the reactionengines associated
with a cell to consume several resources and turn them into other
resources and waste. 

When enough of the input resources become available, the reaction
event can commence. Otherwise, the reaction engine asks the resource
engine to request the required resources through pull transactions.

Several reaction types are available, but the assigment and scheduling
of reaction events is up to the scenario builder. 

\begin{description}
\item 
\item [{Subclasses:}]~

\begin{description}
\item [{Combustion}]~
\item [{Consumption}]~
\item [{Disposal}]~
\item [{Refining}]~
\item [{Utilization}]~
\end{description}
\end{description}

\begin{figure}[t]
\epsfxsize=5.5truein
\centerline{\epsfbox{figures/sc_reactionengine.eps}}
\caption{Reaction Engine Statechart}
\end{figure}

\begin{description}
\item [{WaitForTrigger}] : Poll input resources to see if there are enough
raw materials ready to undergo the reaction. 

\begin{description}
\item [{Action}] State EntryAction checkResources(); 
\item [{Out}] Transition Condition Connector Branches: 

\begin{description}
\item [{SufficientResources()}] Target: ExecuteReaction 
\item [{InsufficientResources()}] Target: ReactionFail 
\end{description}
\end{description}
\item [{ReactionFail}] Record an appropriate penalty for a failed reaction.
If no penalty action is defined, then the failure is merely recorded.
These failures could then lead to a detraction in the quality of life
output metric. 

\begin{description}
\item [{Action}] State EntryAction ReactionFailed(); 
\item [{Out}] Transition Target: Terminate 
\end{description}
\item [{ExecuteReaction}] Reduce input quantities and increase output quantities
in the ratio defined in this reaction. 

\begin{description}
\item [{Action}] State EntryAction ExecuteReaction(); 
\item [{Out}] Transition Target: Terminate
\end{description}
\item [{Terminate}] Local Termination State 
\item [{InputResources}] Proxy to ReactionEngine that requests or collects
resources available within the cell. 
\item [{OutputResources}] Proxy to ResourceEngine that increases associated
output resources upon successful reactions. 
\end{description}

\section{System Requirements Allocation}

As with everything else in this design document, a distinction must
be made between requirements for the arcology and requirements specific
to the arcology simulation model (the actual system of interest).
The ability for the simulation to successfully model the fulfillment
of fundamental arcology requirements is in itself a requirement.

The simulation tool should be able to quantify estimates for real
life occurrences. One of the odd requirements for this system is to
provide special failure cases in the event that all of an individual's
use cases cannot be met. While the consequences for failure to fulfill
a need (such as starvation, homelessness, or sickness do to poor hygiene
\- all very real-world problems) does not necessarily have to be
simulated to achieve its purpose in the system, failures do need to
be noted and become part of the output of the system. It is of interest
to note that failure is an option, and must be properly accounted
for as part of the normal operation of the system.

We present separate requirements for the arcology and the simulation
model. The simulation requirements are driven by the ability to model
interactions between elements that affect the arcology requirements,
so they may be seen as further derived.

\subsection{Arcology Primitive Requirements}
\label{sub:Arcology-Primitive-Requirements}

\begin{table}[htp]
\shadowbox{\parbox[t][1\totalheight]{1\columnwidth}{%
\baselineskip=12pt

\begin{enumerate}
\item \label{enu:1.Attend-to-basic}Attend to basic occupant needs defined
in the Individual use cases described in Live.

\begin{enumerate}
\item 1.1.Provisions (Feed)

\begin{enumerate}
\item 1.1.1.Food
\item 1.1.2.Water
\item 1.1.3.Other consumables (vitamins, nutrients, \emph{etc.})
\end{enumerate}
\item 1.2.Indirect assets \& qualities

\begin{enumerate}
\item 1.2.1.Shelter, security (Sleep)
\item 1.2.2.Health, hygiene maintenance not covered by (Maintenance)

\begin{enumerate}
\item 1.2.2.1.Waste removal
\end{enumerate}
\end{enumerate}
\end{enumerate}
\item \label{enu:2.Self-sufficiency-&-sustainability}Self-sufficiency \&
sustainability (Work)

\begin{enumerate}
\item 2.1.Extract required resources from environment
\item 2.2.Extract labor from occupants
\end{enumerate}
\item Improve quality of life for occupants (Entertain)

\begin{enumerate}
\item 3.1.Education
\item 3.2.Entertainment
\item 3.3.Social interaction
\end{enumerate}
\end{enumerate}
%
}}%
\caption{Arcology Primitive Requirements}
\label{tab:arcology-primitive-requirements}
\end{table}

\subsection{Arcology Derived Requirements}
\label{sub:Arcology-Derived-Requirements}

\begin{table}[htp]
\shadowbox{\parbox[t][1\totalheight]{1\columnwidth} {
\baselineskip=12pt

\begin{description}
\item{\bf 1.}
Transformations of resources
\begin{enumerate}
\item 1.1.
Fuel to Waste - byproducts of Arcology Requirements 
\item 1.2.
Construction / deconstruction mechanism - resulting from 
\end{enumerate}
\item{\bf 2.}
Accounting and transportation mechanism for resources
\begin{enumerate}
\item 2.1.
Solid - Arcology Requirements 
\item 2.2.
Liquid - Arcology Requirements 
\item 2.3.
Gaseous - Arcology Requirements 
\item 2.4.
Information - Arcology Requirements ,
\item 2.5.
Monetary credits - intermediary between exchanges and transformations.
\end{enumerate}
\item{\bf 3.}
Transportation mechanism for resources \& occupants in order to satisfy
all of the above (Travel)
\end{description}
}}
\caption{Arcology Derived Requirements}
\end{table}

\subsection{Arcology Specifications}
\subsubsection{Specs for Arcology Primitive Requirements}
\label{sub:Specs-for-Arcology}

\begin{enumerate}
\item Attend to basic occupant needs defined in the Individual use cases
described in Live.

\begin{enumerate}
\item 1.1.Provisions

\begin{enumerate}
\item 1.1.1.Food : > 1.77 kg per diem
\item 1.1.2.Water : > 2.3 kg per diem
\item 1.1.3.Other consumables (vitamins, nutrients, \emph{etc.})
\end{enumerate}
\item 1.2.Indirect assets \& qualities

\begin{enumerate}
\item 1.2.1.Shelter, security : distribution of 5 - 10 hours of sleep, personal
living quarters with > 37 m2 of personal living space.
\item 1.2.2.Health, hygiene maintenance not covered by (1.a), \emph{e.g.}
timely delivery of emergency supplies \& services.

\begin{enumerate}
\item 1.2.2.1.Waste removal - roughly equivalent to total of Provisions.
\end{enumerate}
\end{enumerate}
\end{enumerate}
\item Self-sufficiency \& sustainability 

\begin{enumerate}
\item 2.1.Extract required resources from environment - varies, should balance
with environmental production rates, if known.
\item 2.2.Extract labor from occupants - a distribution of around 1/3 of
the daily cycle. Provide > 19 m2 of work space.
\end{enumerate}
\item Improve quality of life for occupants : maintain or increase amount
of leftover time dedicated to the following:

\begin{enumerate}
\item 3.1.Education
\item 3.2.Entertainment
\item 3.3.Social interaction
\end{enumerate}
\end{enumerate}

\subsubsection{Specs for Arcology Derived Requirements}

\label{sub:Specs-for-Arcology}

\begin{enumerate}
\item Transformations of resources

\begin{enumerate}
\item 1.1.Fuel to Waste - roughly 1 to 1 conversion factor by mass.
\item 1.2.Construction / deconstruction mechanism 
\end{enumerate}
\item Accounting \& transportation mechanism for resources - Conversion,
creation, consumption of each class of resource.
\item Transportation mechanism for resources \& occupants 

\begin{enumerate}
\item 3.1.Quantify measures of effectiveness - cost, latency, throughput,
efficiency
\end{enumerate}
\end{enumerate}


\subsubsection{Transportation System Preliminary Design Input Parameters}

Define a distribution system topology. All nodes will be fully connected,
but have different hub/node size ratio. What characterizes the difference
between hubs and ordinary nodes? Hubs will have higher transit demand
levels as well as larger throughput limitations.

Number of people per node ratio. For the same total population, is
it better to have them distributed across several nodes, or occupy
relatively few. This will likely be dependent on throughput limitations.

Population / number of transport vehicle ratio. For the same total
population, is it better to have fewer vehicles working complex routes,
or many vehicles working in parallel?

To quantify the tradeoff between the urban system's structure, behavior,
and performance, we turn to simulation to help generate some data
involving the parameters of interest.





\subsection{Operational Concept}

The simulation basically boils down to an accounting of conversion
and transaction events that move resources between themselves and
their environment. Therefore, most of the coding involves making and
managing container objects. Building from the ground up, here's the
implementation plan:

\begin{enumerate}
\item Resource containers are the most elementary class. They merely have
to choose an identity, and store a number representing how much of
this resource the owning object has pooled together. It needs getter
and setter functions, and a master dictionary for looking up other
useful properties associated with that type of resource (such as density,
, market value, \emph{etc.}) that might be used for various other
calculations. Money and information are considered resources as well
for tracking purposes, but they basically constitute an \char`\"{}activation
energy\char`\"{} for a reaction or transaction to proceed, so are
treated somewhat differently.
\item Reactors come in various forms and are intended to provide balanced
conversions from one set of resources to others (often waste).
\item Cell objects are the hierarchical units. These will be the most complex
but most useful class used in the simulation. They each can contain
some combination of:

\begin{enumerate}
\item resources
\item reactors for converting internal resources from one to another
\item buffers and constraints on the amount of resources they can hold before
having to push them elsewhere
\item parent, child, and peer cells with which to interact, such as by scheduling
transactions and reporting metrics up and down their chain of command.
\item internal agendas used to schedule reaction and transaction events.
\end{enumerate}
\item Connective meshes define which cells can actually interact with each
other, representing the function and capacity constraints of various
transport networks that move resources between the cells in the system.
They can exact a cost (in terms of money transactions and resources
consumed.
\item The instantiation framework is what reads the scenario file and begins
to create cell objects and set up the simulation. This is where a
modeling language would come in.
\item A reporting engine collects data from the simulation at desired intervals
and needs to be programmed to extract useful data and analyses from
the simulation.
\end{enumerate}




\subsection{Data Interchange Schema}

\label{sec:Data-Interchange-Schema}In order to operate in an inter-modal
fashion, however, different segments of bus, rail, and even taxi and
aircraft platforms must be able to exchange data with each other in
order to feed the formulation of the global optimization problem.
This also needs to interoperate between multiple jurisdictions and
carriers, who will still want control over their own vehicle resources.

What kind of features would such a schedule collaboration system need
to make a diverse set of platforms interoperate? First of all, we
need to define a common language used to publish and exchange schedule
and status data. Next, we would want to define schemas representing
the types of data that are actually required, desired, or merely expressed
as comments for general informational purposes. Some of the properties
desired by this scheme could certainly be handled by an data representation
framework like that provided by XML (extensible markup language):

\begin{itemize}
\item It should have a standard set of tools for processing and manipulating
the data, a la XML's parsers and stylesheet transformations.
\item The data representation format should be extensible, allowing newer
versions of software to introduce new data types and tags without
breaking older software that doesn't expect or understand the additional
data. In a similar vein, older software in the system should still
preserve these newer data structures in messages that it passes along
between other, perhaps newer or more capable software components that
understand and can make use of it.
\item The schemas should be centrally version controlled and available for
verifying data types, \emph{etc.}
\end{itemize}
This language feature set would allow different organizations to continue
to share and integrate their logistics information, even as the set
and functionality of the data schemas grow, change, and evolve over
time. Incremental additions can be introduced, such as adding field
for, say, the error or uncertainty surrounding a predicted arrival
time - information that we might not be able to make good use of now,
but could give us tangible benefits once we learn to process it better.
Major version changes that alter the meaning of data fields in ways
that are fundamentally incompatible with earlier versions could be
introduced and managed by a central standards body, while a set of
standard transformation filters could be provided to convert as much
data between major revisions as possible.
