Defining and structuring software problems through Problem Frames

Charles Wallace Xinli Wang Virginia Bluth Michigan Technological University wallace@mtu.edu

Software problems
(Jackson, 1995) Problem context: interaction between software machine and its environment Requirements: stated purely in terms of environmental phenomena Specification: restricted to machine-environment phenomena phenomena that affect machine state

environmental phenomena

specification phenomena

machine phenomena

phenomena visible outside machine (requirement phenomena)

Locating and bounding the problem

(Jackson, 1995, 2000)

Problem stated in terms of concrete, observable phenomena avoids overgeneralization of context (getting away from the realities of the customers world) Problem stated in terms of machine-environment interaction avoids overgeneralization of requirements (getting away from the realities of the customers problem)

What are phenomena?

events: indivisible, instantaneous occurrences arrival of elevator car at a floor elevator user pressing floor button states: entity properties, or relations between entities not instantaneous; have some duration elevator door status: closed, closing, open, opening floor at which elevator car is currently parked weight of car contents

What is the machine?

The software product under development (which possibly interacts with other software machines) Be careful about what you mean by machine e.g. In workpieces problems (e.g. word processor, spreadsheet), the workpieces are documents, residing in computer memory; still, best to think of them as outside the machine

Example: Elevator controller problem

environmental phenomena outside machine domain: physical position of elevator car current speed and direction of cable illumination of floor buttons on panel machine phenomena invisible to environment: updating car_direction variable decrementing time_to_door_close counter adding floor request to pending_requests shared phenomena: open the door command (from controller) door is blocked signal (to controller)

Problem structuring
(Jackson, 1995, 2000)

Attack the complexity of a software problem by creating a set of projections of the problem Projections (subproblems) may overlap (i.e. share phenomena) Each projection belongs to a well-known class of similar problems: a problem frame Strong similarities to notion of design patterns As we deal with instances of each problem frame, we learn heuristics (rules of thumb) for documenting and learning about such problems

Problem frame document

components: single context diagram + multiple problem diagrams

diagram elements: domains requirements interfaces (shared phenomena) requirement references

(nodes) (nodes) (edges) (edges)

Domains
represent sets of individuals (distinguishable things of interest in problem) domain may possess certain attributes may be related to other domains via shared phenomena Machine domain: exactly one per problem frame no attributes except those shared with environment Realized (designed) domain: software developers may help in its design typically, electronic representations of data

Connection domain
exists purely as intermediary between multiple domains e.g. communication channel can always be ignored... pro: higher abstraction level con: abstraction may leak reasons to include connection domain: communication failure communication delay connection domain referred to in requirements conversion of phenomena via connection domain

Shared phenomenon (Interface)

e.g. admission machine detects coin inserted by customer
(domain) (interface) (domain)

Note the abstraction here: mechanism for accepting and detecting coin ignored OK if coin detection is a given; not OK if we're designing the coin detector
customer insert coin admission machine

Beyond binary interfaces

e.g. supermarket purchase customer clerk purchase product

Note: this can be broken into multiple binary interfaces... with a lowering of abstraction level pay

customer take

clerk give

product Now, we have to stipulate that give precedes take; if pay fails, then take shall also fail,

Requirement
Form: If (antecedent), then (consequent) Antecedent and consequent refer to shared phenomena References in the antecedent: descriptive (indicative) mood References in the consequent: prescriptive (optative) mood No indicative or optative references to machine domain: requirements don't refer to machine Antecedent may be empty, but consequent must not

Requirement example
If the customer inserts a coin, the gate shall become unlocked. customer
insert (event) insert (event)

admission machine

lock, unlock (events) lock-status (state)

gate

admission criteria

(Note: arrow for optative reference)

This requirement refers to the (unshared) lock status of gate, rather than the (shared) machine-gate events lock and unlock

Patient monitoring & dosage problem

Adapted from (Jackson, 2000)

A patient monitoring program is required for the ICU in a hospital. Each patient is monitored by an analog device which measures factors such as pulse, temperature, and blood pressure. The program reads these factors on a periodic basis (specified for each patient) and stores them in a database. For each patient, safe ranges for each factor are also specified by medical staff. If a factor falls outside a patient's safe range, or if an analog device fails, the nurses station is notified.

Patient monitoring & dosage problem

(Continued)

A patient may be connected to an intravenous pump that supplies medication. There are three ways in which medication may be administered via the pump. First, medical staff may stipulate that a patient is to receive regular periodic dosages through the pump. Second, staff may request a single dosage to be applied immediately. Finally, if authorized earlier by medical staff, a patient may request an immediate dosage by pressing a button on the pump. In all cases, the total daily dosage must not exceed the limit entered earlier by medical staff. If a pump fails, the nurses station is notified.

Domains: monitoring program (machine) patients analog devices medical staff nurses' station intravenous pump

Factors (vital signs): make them domains?

pulse, temperature, etc. not really concrete things; probably best to treat them as patient attributes

Periods, ranges & dosages (PR&D): make them domains?

con: they're data structures, internal to solution pro: any sensible solution will have such data structures awkward to talk about problem without reference to these terms

Since the pump and the analog devices both connect patients to the machine, should they be merged into a single domain?
The pump and the analog devices have little state information or shared phenomena in common; best to treat them as separate domains

How about removing medical staff and PR&D?

OK only if each patient gets the same (unchanging) treatment (unrealistic)

How about hiding medical staff behind nurses station?

If so, then nurses station becomes connection domain, channeling staff input to machine

How about removing medical staff and keeping PR&D?

periods & ranges domain allows for different patient treatments; but treatments cannot change (unrealistic)

How about removing patients?

No way --vital component of problem, even though theres no direct link to machine

What can we learn from patients? Some examples: range of expected vital sign values range of expected analog device readings frequency of patient movement in/out of the ICU frequency of additions/deletions to PR&D database patients need for pain medication usability issues surrounding dosage requests

Factors database: designed domain?

if no database is an off the shelf component, not our right/responsibility to design it is it to be accessed by others? we need to add others as a domain database is internal to solution does it really belong in requirements?

if yes if yes if no

Patient monitoring & dosage problem: Context diagram

periods, ranges & dosages
(designed)

factors database a b monitor machine e analog devices h c d

nurses' station IV pump g ICU patients

f medical staff

a: periods, ranges, dosages b: factor report c: alert d: pump control / request dose e: patient readings f: enter period/range/dose g: dose button / administer dose h: vital signs

Problem frames
Simple, generic archetypal subproblems Information display problem Required behavior problem Commanded behavior problem Workpieces problem Transformation problem

Information display problem frame

(Jackson, 2000) a information system (IS) b a: WorldState (RW) c: DisplayState (D) display (D) c real world (RW) a report-world

b: Reports (IS)

When world state is so-and-so... machine detects state info and sends report... causing appropriate change in display state.

Device failure alert: Information display problem

If an analog device or pump fails, the nurses' station shall be notified. (This is really two information display problems in one: Analog device failure and pump failure) Real world: Analog devices, IV pump Information requester: Nurses station

Patient alert: Information display problem

If a patient's vital signs are outside safe ranges, the nurses' station shall be notified. Real world: ICU patients Information requester: Nurses station Connection domain: Analog devices Periods, Ranges & Dosages database must be consulted

Information display
When world state is so-and-so real world may be static or dynamic if world is static and small, problem is trivial if world is dynamic, how frequently does machine sample world? e.g. Device and patient alert problems: both involve dynamic real-world phenomena Device alert sampling frequency: fixed Patient alert sampling frequency: determined by medical staff Device alert sampling must be frequent enough not to hide patient alerts

Information display
machine detects state info... often, there is a machine-real world connection domain real world interpreted by sensor or data-entry person a: SensorData (S) b: WorldData (RW) information system (IS) a sensor (S) Usual concerns apply with regard to connection domains: failure, translation, ... real world (RW)

Information display
Device alert problem: What is the failure model of the devices? Does device signal its impending failure? (unlikely) Fail-stop: device simply stops sending data In this case, we may sense failure via device heartbeat Byzantine: failed device continues to send (bogus) data This complicates failure detection

Information display

Machine must model the real world e.g. patient modeled as a triple: (temp, blood pressure, pulse rate) each factor is an electronic approximation of the real vital signs gap between model and real world: how accurate must model be? What is the frequency of model state checking? What is the granularity of data?

Information display
requirement: If P(rw), then display P(rw). solution: create model m If Q(m(rw)), then display P(rw). Do we really need to require that Q(m(rw)) P(rw) ? A weaker condition may be sufficient: e.g. Q(m(rw)) P(rw) P(rw) Q(m(rw)) (no false positives) (no false negatives) In device/patient alert problems, false negatives unacceptable False positives may be tolerated: risks of wasting medical staff time, annoying patients

Information display
machine sends report, causing appropriate change in display state. e.g. Device/patient alert problems need to know precisely which device has failed also need to know which patient is connected to the device how are patients identified? Display design: important nonfunctional (usability) issues e.g. Alert problems: clarity of presentation is essential

Variant: Commanded display

a information system (IS) b c real world (RW) display (D) a d c report-world

enquiry operator (EO)

a: WorldState (RW) b: Queries (EO) c: Reports (IS) d: DisplayState (D) When world state is so-and-so... machine detects state info... if operator then makes a query... machine sends a report... causing appropriate change in display state.

Information display issues (summary)

world state: entities, attributes to be displayed causal relations between real-world entities (laws of nature) static/dynamic world, rate of sampling detection: connection domain? Delays, distortions? model level of accuracy: frequency of model updates, data granularity false positives/negatives acceptable? query (commanded display only) language of legal queries: syntax (form), semantics (meaning) report what information is needed display: layout, presentation of information

Required behavior problem frame

behavior rules controller machine (CM) a controlled domain (CD) b

a: Commands (CM), DomainState (CD)

b: DomainState (CD)

Machine issues commands... (possibly after considering current domain state information)... that keep domain in an acceptable state.

Regular dosage: Required behavior problem

If regular dosage is prescribed for a patient, the given dose will be applied regularly at the given interval, unless the total daily dosage exceeds the limit. Controlled domain: IV Pump Periods, Ranges & Dosages must be consulted for dosage amount, interval

Required behavior
Information display problem could be seen as required behavior, with the display being the controlled domain, but in information display problems, controlling the display is typically not difficult; the real difficulty is in capturing the real world accurately.

Required behavior
Machine issues commands What are the commands at the machines disposal? e.g. for Regular Dosage problem, say the commands are pump on, pump off This implies that dosages will be determined by precise timing on the part of the machine Note the distinction between the commands (at the CM-CD interface) and the domain state (mentioned in the requirement) The requirement does not mention anything about machine commands

Required behavior
possibly after considering current domain state information... How much feedback is needed from controlled domain? If effects of commands are totally predictable, and only our machine affects domain, then machine needs no state info Otherwise, need to know range of variation of commands effects how to detect failed commands how to undo/redo failed commands effects that other domains may have on the controlled domain

Required behavior
that keep domain in an acceptable state. What are the direct effects of the machine commands on the controlled domain? What are the indirect effects? e.g. Can we assume that keeping pump on for x seconds results in some amount f(x) of medication being administered? Controlled domain may include uncontrollable states (e.g. mobile unit that goes out of communication range) Can controller take domain to a state thats no longer controllable? If so, need to disable certain sequences of commands

Required behavior issues (summary)

machine commands: format, effects on controlled domain range of variation of commands effects detectability, undoability, redoability of failed commands effects on the controlled domain from outside the controller domain state: what feedback is needed? what is controllable state space? effects of machine commands on doman: direct, indirect (via laws of nature)

Commanded behavior problem frame

operator (O) a controller machine (CM) b controlled domain (CD) c a behavior rules

a: OperatorCommands (O) b: MachineCommands (CM) c: DomainState (CD) Operator issues commands... machine rejects non-sensible ones... machine ignores commands unviable in current domain state... for sensible, viable commands, machine responds with its own commands that keep the domain in an acceptable state.

Patient-administered dosage: Commanded behavior problem

If authorized earlier by medical staff, patients may request immediate dosages. Operator: ICU Patients Controlled domain: IV Pump Periods, Ranges & Dosages database must be consulted

Staff-administered dosage: Commanded behavior problem

Staff may request a single dosage to be applied to a patient immediately. Operator: Medical staff Controlled domain: IV pump Periods, Ranges & Dosages database must be consulted

Commanded behavior
Operator issues commands... Operator commands and machine commands may be quite different e.g. single command from patient/staff translated into a pump on/ pump off sequence, with an appropriate time interval in between Design of operator commands is important e.g. staff-administered dosage: specify dosage level? need to balance flexibility/expressivity vs. ease/speed of use Note: patient-administered dosage requests come via the pump; design of the patient command interface is out of our hands

Commanded behavior
machine rejects non-sensible commands... sensible commands: have some reasonable meaning given the context of previous commands non-sensible commands may be disabled (e.g. grey out currently non-sensible menu items) e.g. Staff dosage request for a patient is not sensible without an earlier establishment of a daily dosage limit

Commanded behavior
machine ignores commands unviable in current domain state... viable commands: have some reasonable meaning given the current state of the controlled domain disabling unviable commands more difficult; requires sampling of controlled domain e.g. Patient dosage requests are always sensible, but not viable if self-dosage not authorized, or dose would put the daily dosage over the limit

Commanded behavior issues (summary)

Issues of required behavior, plus: operator commands: syntax, mapping to machine commands sensibility conditions on commands viability conditions of CD for commands

Workpieces problem frame

(Jackson, 2000) user (U) a editor tool (ET) a b workpieces (WP) a: UserCommands (U) c: WorkpieceState (WP) c edit workpieces

b: WorkpieceOperations (ET)

Period, Range & Dosage data entry: Workpieces problem

Sampling periods, safe ranges, and dosages for each patient shall be entered by medical staff. User: Medical staff Workpieces: Periods, Ranges & Dosages

Workpieces
Similar to Commanded behavior frame --but controlled domain here is totally computer-internal Workpieces: intangible software objects (e.g. documents, files) usually easier to control than domains outside the computer very often a designed domain: our right/responsibility to co-design it Challenges in workpieces problems: identifying syntactically correct, sensible user commands viability conditions mapping between user and machine commands

Workpieces issues (summary)

Issues of commanded behavior, but the following have less (or no) importance: range of variation of machine command effects issues regarding failed commands controllable state space

Transformation problem frame

(Jackson, 2000) source (S) a transformer machine (TM) c mapping b destination (D) a: InputStream (S) c: InputData (S) d

b: OutputStream (TM) d: OutputData(D)

From a collection of input data, Source produces input stream... Machine responds by producing an output stream, creating output data at destination that respects the input-output mapping.

Patient factor storage: Transformation problem

Patients' vital signs shall be stored in a database. Source: Analog devices Destination: Factors database
Note: Though it deals with electronic records, this is not a workpieces problem, since there is no autonomous user performing arbitrary operations. Its a simple translation from one electronic format to another.

Transformation
Source produces input stream... Machine responds by producing an output stream input rate: is it truly streaming? Regular or intermittent? output rate: Is there an upper limit? Can input rate ever exceed maximum output rate? If so, can input data be dropped? If not, what is the max expected amount of buffering needed?

Transformation
creating output data at destination that respects the inputoutput mapping. Range of possible input data values Range of possible output data values Mapping: one-to-one, one-to-many, many-to-one? e.g. Does factors database store summary reports (many-to-one), or does it store each individual reading (one-to-one)?

Transformation issues (summary)

Input/output streams Input/output rates Buffering vs. dropping Input/output data ranges Mapping input data to output data one-to-one, many-to-one, one-to-many

References
M.A. Jackson. Software Requirements and Specifications. Addison Wesley, 1995. M.A. Jackson. Problem Frames. Addison Wesley, 2000. B.L. Kovitz. Practical Software Requirements. Manning, 1999.

Patient Monitoring & Dosage Links

Patient monitoring products: http://www.medical.philips.com/main/products/patient_monitoring/ http://www.datascope.com/pm/patientmonitoring.html Medication delivery products: http://www.baxter.com/products/medication_management/infusion_pumps/large_ volume_infusion_pumps/index.html A first-person account of patient-controlled pain medication (very interesting) http://www.asktog.com/columns/030ThePump.html