| 1 |
# (C) Copyright 2004-2023 Enthought, Inc., Austin, TX |
| 2 |
# All rights reserved. |
| 3 |
# |
| 4 |
# This software is provided without warranty under the terms of the BSD |
| 5 |
# license included in LICENSE.txt and may be redistributed only under |
| 6 |
# the conditions described in the aforementioned license. The license |
| 7 |
# is also available online at http://www.enthought.com/licenses/BSD.txt |
| 8 |
# |
| 9 |
# Thanks for using Enthought open source! |
| 10 |
|
| 11 |
""" |
| 12 |
Sometimes the inputs to a model are not correlated. That is, any valid model |
| 13 |
input produces a corresponding valid model state. However, in other cases, some |
| 14 |
or all of the model inputs are correlated. That is, there may exist one or more |
| 15 |
combinations of individually valid model inputs which produce invalid model |
| 16 |
states. |
| 17 |
|
| 18 |
In cases where this can happen, it is very often desirable to warn the user if |
| 19 |
a particular combination of input values will not produce a usable result. This |
| 20 |
problem cannot be solved solely though the use of carefully chosen trait types |
| 21 |
and editors, because each individual input may be valid, but it is the |
| 22 |
combination of inputs which is invalid. |
| 23 |
|
| 24 |
Solving this problem therefore typically requires providing a way of determining |
| 25 |
whether or not the model is in a valid state, and then communicating that |
| 26 |
information to the user via the user interface. |
| 27 |
|
| 28 |
This demonstration provides an example of doing this using the TraitEditor's |
| 29 |
'invalid' trait. Each trait editor has an 'invalid' trait which can be set |
| 30 |
equal to the name of a trait in the user interface context which contains a |
| 31 |
boolean value reflecting whether or not the user interface (and underlying |
| 32 |
model) are in a invalid state or not. A True value for the trait indicates that |
| 33 |
the editor's current value produces an invalid model state. By associating the |
| 34 |
same 'invalid' trait with one or more editors in the user interface, the |
| 35 |
resulting user interface can indicate to the user which combination of input |
| 36 |
values is producing the invalid state. |
| 37 |
|
| 38 |
In this example, we have a very simple model which allows the user to control |
| 39 |
the mass and velocity of a system. The model also defines the kinetic energy |
| 40 |
of the resulting system. For safety reasons, the kinetic energy of the system |
| 41 |
should not exceed a certain threshold. If it does, the user should be warned |
| 42 |
so that they can reduce either or both of the system mass and velocity back down |
| 43 |
to a safe level. |
| 44 |
|
| 45 |
In the model, an 'error' property is defined which is True whenever the |
| 46 |
kinetic energy level of the system exceeds the safety threshold. This trait is |
| 47 |
then synchronized with the user interface's 'mass', velocity' and 'status' |
| 48 |
editors, turning them red whenever the model enters an invalid state. |
| 49 |
|
| 50 |
The 'status' trait is another property, based on the 'error' trait, which |
| 51 |
provides a human readable description of the current system state. |
| 52 |
|
| 53 |
Note that in this example, we synchronize the 'error' trait with the user |
| 54 |
interface using 'sync_to_view' metadata, whose value is a list of user |
| 55 |
interface editor traits the trait should be synchronized 'to' (i.e. changes to |
| 56 |
the 'error' trait will be copied to the corresponding trait in the editor, but |
| 57 |
not vice versa). We could also have explicitly set the 'invalid' trait of each |
| 58 |
corresponding editor in the view definition to 'error' as well. |
| 59 |
|
| 60 |
To use the demo, simply use the 'mass' and 'velocity' sliders and observe the |
| 61 |
changes to the 'kinetic_energy' of the system. When the kinetic energy exceeds |
| 62 |
50,000, notice how the 'mass', 'velocity' and 'status' fields turn red, and |
| 63 |
that when the kinetic energy drops below 50,000, the fields return to their |
| 64 |
normal color. |
| 65 |
""" |
| 66 |
|
| 67 |
# -- Imports -------------------------------------------------------------- |
| 68 |
|
| 69 |
from traits.api import ( |
| 70 |
HasTraits, |
| 71 |
Range, |
| 72 |
Float, |
| 73 |
Bool, |
| 74 |
Str, |
| 75 |
Property, |
| 76 |
) |
| 77 |
|
| 78 |
from traitsui.api import View, VGroup, Item |
| 79 |
|
| 80 |
# -- System Class --------------------------------------------------------- |
| 81 |
|
| 82 |
|
| 83 |
class System(HasTraits): |
| 84 |
|
| 85 |
# The mass of the system: |
| 86 |
mass = Range(0.0, 100.0) |
| 87 |
|
| 88 |
# The velocity of the system: |
| 89 |
velocity = Range(0.0, 100.0) |
| 90 |
|
| 91 |
# The kinetic energy of the system: |
| 92 |
kinetic_energy = Property(Float, observe='mass, velocity') |
| 93 |
|
| 94 |
# The current error status of the system: |
| 95 |
error = Property( |
| 96 |
Bool, |
| 97 |
sync_to_view='mass.invalid, velocity.invalid, status.invalid', |
| 98 |
observe='kinetic_energy', |
| 99 |
) |
| 100 |
|
| 101 |
# The current status of the system: |
| 102 |
status = Property(Str, observe='error') |
| 103 |
|
| 104 |
view = View( |
| 105 |
VGroup( |
| 106 |
VGroup( |
| 107 |
Item('mass'), |
| 108 |
Item('velocity'), |
| 109 |
Item('kinetic_energy', style='readonly', format_str='%.0f'), |
| 110 |
label='System', |
| 111 |
show_border=True, |
| 112 |
), |
| 113 |
VGroup( |
| 114 |
Item('status', style='readonly', show_label=False), |
| 115 |
label='Status', |
| 116 |
show_border=True, |
| 117 |
), |
| 118 |
) |
| 119 |
) |
| 120 |
|
| 121 |
def _get_kinetic_energy(self): |
| 122 |
return (self.mass * self.velocity * self.velocity) / 2.0 |
| 123 |
|
| 124 |
def _get_error(self): |
| 125 |
return self.kinetic_energy > 50000.0 |
| 126 |
|
| 127 |
def _get_status(self): |
| 128 |
if self.error: |
| 129 |
return 'The kinetic energy of the system is too high.' |
| 130 |
|
| 131 |
return '' |
| 132 |
|
| 133 |
|
| 134 |
# -- Create and run the demo ---------------------------------------------- |
| 135 |
|
| 136 |
# Create the demo: |
| 137 |
demo = System() |
| 138 |
|
| 139 |
# Run the demo (if invoked from the command line): |
| 140 |
if __name__ == '__main__': |
| 141 |
demo.configure_traits() |