Documentation and clean-up

contrib/src/main/java/gov/nasa/jpl/aerie/contrib/streamline/modeling/Demo.java

@@ -30,7 +30,6 @@
 import static gov.nasa.jpl.aerie.contrib.streamline.modeling.polynomial.PolynomialResources.unitAware;
 import static gov.nasa.jpl.aerie.contrib.streamline.modeling.unit_aware.Quantities.quantity;
 import static gov.nasa.jpl.aerie.contrib.streamline.modeling.unit_aware.StandardUnits.*;
-import static gov.nasa.jpl.aerie.contrib.streamline.modeling.unit_aware.UnitAwareOperations.simplify;
 import static gov.nasa.jpl.aerie.merlin.framework.ModelActions.*;
 import static gov.nasa.jpl.aerie.contrib.streamline.core.CellResource.cellResource;
 
@@ -87,7 +86,7 @@ public final class Demo {
   UnitAware<CellResource<Discrete<Double>>> power = DiscreteResources.unitAware(
       cellResource(discrete(120.0)), WATT);
 
-  UnitAware<Resource<Polynomial>> batterySOC = integrate(asUnitAwarePolynomial(simplify(power)), quantity(100, JOULE));
+  UnitAware<Resource<Polynomial>> batterySOC = integrate(asUnitAwarePolynomial(power), quantity(100, JOULE));
   UnitAware<Resource<Discrete<Double>>> clampedPower = DiscreteResources.unitAware(map(power.value(WATT), p -> p < 0 ? 0 : p), WATT);
   UnitAware<Resource<Discrete<Double>>> clampedPower_v2 = /* map(power, p -> lessThan(p, quantity(0, WATT)) ? quantity(0, WATT) : p) */
       null;

contrib/src/main/java/gov/nasa/jpl/aerie/contrib/streamline/modeling/clocks/ClockEffects.java

@@ -9,6 +9,9 @@
 public final class ClockEffects {
   private ClockEffects() {}
 
+  /**
+   * Reset clock to zero elapsed time.
+   */
   public static void restart(CellResource<Clock> stopwatch) {
     stopwatch.emit("Restart", effect(c -> clock(ZERO)));
   }

contrib/src/main/java/gov/nasa/jpl/aerie/contrib/streamline/modeling/clocks/ClockResources.java

@@ -16,6 +16,9 @@
 public final class ClockResources {
   private ClockResources() {}
 
+  /**
+   * Create a clock starting at zero time.
+   */
   public static Resource<Clock> clock() {
     return cellResource(Clock.clock(ZERO));
   }

contrib/src/main/java/gov/nasa/jpl/aerie/contrib/streamline/modeling/clocks/VariableClockEffects.java

@@ -9,18 +9,30 @@
 public final class VariableClockEffects {
   private VariableClockEffects() {}
 
+  /**
+   * Stop the clock without affecting the current time.
+   */
   public static void pause(CellResource<VariableClock> stopwatch) {
     stopwatch.emit("Pause", effect(c -> pausedStopwatch(c.extract())));
   }
 
+  /**
+   * Start the clock without affecting the current time.
+   */
   public static void start(CellResource<VariableClock> stopwatch) {
     stopwatch.emit("Start", effect(c -> runningStopwatch(c.extract())));
   }
 
+  /**
+   * Stop the clock and reset the time to zero.
+   */
   public static void reset(CellResource<VariableClock> stopwatch) {
     stopwatch.emit("Reset", effect(c -> pausedStopwatch(ZERO)));
   }
 
+  /**
+   * Start the clock and reset the time to zero.
+   */
   public static void restart(CellResource<VariableClock> stopwatch) {
     stopwatch.emit("Restart", effect(c -> runningStopwatch(ZERO)));
   }

contrib/src/main/java/gov/nasa/jpl/aerie/contrib/streamline/modeling/discrete/DiscreteEffects.java

@@ -15,44 +15,71 @@ private DiscreteEffects() {}
 
   // More convenient overload of "set" when using discrete dynamics
 
+  /**
+   * Set the resource to the given value.
+   */
   public static <A> void set(CellResource<Discrete<A>> resource, A newValue) {
     resource.emit("Set " + newValue, effect(x -> newValue));
   }
 
   // Flag/Switch style operations
 
+  /**
+   * Set the resource to true.
+   */
   public static void turnOn(CellResource<Discrete<Boolean>> resource) {
     set(resource, true);
   }
 
+  /**
+   * Set the resource to false.
+   */
   public static void turnOff(CellResource<Discrete<Boolean>> resource) {
     set(resource, false);
   }
 
+  /**
+   * Toggle the resource value.
+   */
   public static void toggle(CellResource<Discrete<Boolean>> resource) {
     resource.emit("Toggle", effect(x -> !x));
   }
 
   // Counter style operations
 
+  /**
+   * Add one to the resource's value.
+   */
   public static void increment(CellResource<Discrete<Integer>> resource) {
     increment(resource, 1);
   }
 
+  /**
+   * Add the given amount to the resource's value.
+   */
   public static void increment(CellResource<Discrete<Integer>> resource, int amount) {
     resource.emit("Increment by " + amount, effect(x -> x + amount));
   }
 
+  /**
+   * Subtract one from the resource's value.
+   */
   public static void decrement(CellResource<Discrete<Integer>> resource) {
     decrement(resource, 1);
   }
 
+  /**
+   * Subtract the given amount from the resource's value.
+   */
   public static void decrement(CellResource<Discrete<Integer>> resource, int amount) {
     resource.emit("Decrement by " + amount, effect(x -> x - amount));
   }
 
   // Queue style operations, mirroring the Queue interface
 
+  /**
+   * Add element to the end of the queue resource
+   */
   public static <T> void add(CellResource<Discrete<List<T>>> resource, T element) {
     resource.emit("Add %s to queue".formatted(element), effect(q -> {
       var q$ = new LinkedList<>(q);
@@ -61,6 +88,12 @@ public static <T> void add(CellResource<Discrete<List<T>>> resource, T element)
     }));
   }
 
+  /**
+   * Remove an element from the front of the queue resource.
+   * <p>
+   *   Returns that element, or empty if the queue was already empty.
+   * </p>
+   */
   public static <T> Optional<T> remove(CellResource<Discrete<List<T>>> resource) {
     final var currentQueue = currentValue(resource);
     if (currentQueue.isEmpty()) return Optional.empty();
@@ -79,16 +112,25 @@ public static <T> Optional<T> remove(CellResource<Discrete<List<T>>> resource) {
 
   // Consumable style operations
 
+  /**
+   * Subtract the given amount from resource.
+   */
   public static void consume(CellResource<Discrete<Double>> resource, double amount) {
     resource.emit("Consume " + amount, effect(x -> x - amount));
   }
 
+  /**
+   * Add the given amount to resource.
+   */
   public static void restore(CellResource<Discrete<Double>> resource, double amount) {
     resource.emit("Restore " + amount, effect(x -> x + amount));
   }
 
   // Non-consumable style operations
 
+  /**
+   * Decrease resource by amount while action is running.
+   */
   public static void using(CellResource<Discrete<Double>> resource, double amount, Runnable action) {
     consume(resource, amount);
     action.run();
@@ -97,6 +139,9 @@ public static void using(CellResource<Discrete<Double>> resource, double amount,
 
   // Atomic style operations
 
+  /**
+   * Decrease resource by one while action is running.
+   */
   public static void using(CellResource<Discrete<Integer>> resource, Runnable action) {
     decrement(resource);
     action.run();
@@ -107,22 +152,34 @@ public static void using(CellResource<Discrete<Integer>> resource, Runnable acti
 
   // More convenient overload of "set" when using discrete dynamics
 
+  /**
+   * Set the resource to the given value.
+   */
   public static <A> void set(UnitAware<CellResource<Discrete<A>>> resource, UnitAware<A> newValue) {
     set(resource.value(), newValue.value(resource.unit()));
   }
 
   // Consumable style operations
 
+  /**
+   * Subtract the given amount from resource.
+   */
   public static void consume(UnitAware<CellResource<Discrete<Double>>> resource, UnitAware<Double> amount) {
     consume(resource.value(), amount.value(resource.unit()));
   }
 
+  /**
+   * Add the given amount to resource.
+   */
   public static void restore(UnitAware<CellResource<Discrete<Double>>> resource, UnitAware<Double> amount) {
     restore(resource.value(), amount.value(resource.unit()));
   }
 
   // Non-consumable style operations
 
+  /**
+   * Decrease resource by amount while action is running.
+   */
   public static void using(UnitAware<CellResource<Discrete<Double>>> resource, UnitAware<Double> amount, Runnable action) {
     consume(resource, amount);
     action.run();