zach401/acnportal: v0.2.0

We added lots of cool stuff.

Features

• Adds functionality to set tolerance for is_feasible at both the network initialization and interface levels. Also, the warning raised upon submission of an invalid schedule is more descriptive, now containing the maximum violation, the time index at which this violation occurred, and the constraint that this violation violated.

• Adds a function that, given a run simulation, returns a NumPy array of the datetimes over which the simulation was run. This is useful for plotting results from a simulation; namely, the time axis can now be expressed in terms of actual days/hours instead of periods. An example showing how to do this has been added to tutorial 2.

• Adds a developer guide (CONTRIBUTING.md) and a CODE_OF_CONDUCT.md. We should add additional guidelines to CONTRIBUTING.md as needed.

• Adds function to calculate the percentage of sessions where energy demands were fully met (within a tolerance).

• Adds option to run simulation with or without verbose outputs.

JSON Serializer

Adds functionality to dump and load ACN-Sim objects as JSON serializable objects. The serializer is invoked using obj.to_json() and the deserializer is invoked using cls.from_json([output from to_json]). The to_json method may take a file location or filehandle as an argument to specify where to dump. No input argument to to_json yields a JSON string. Likewise, the from_json method may take a file location, filehandle, or JSON string as an argument to specify from where to load.

As part of this feature, a BaseSimObj from which all ACN-Sim objects inherit from was added, in which some common serialization logic takes place. Each BaseSimObj-like defines its own to_ and from_dict methods, which convert BaseSimObj-likes into JSON serializable dicts.

Behaviors

The serializer handles the following cases:

• A native ACN-Sim object: dumps and loads without a problem.
• An extended ACN-Sim object that does not define to/from_dict methods:
  • If the object has no additional attributes (and the same constructor signature), dumps and loads without a problem.
  • if the object has additional attributes, dumps as follows:
    • The object's to_registry method is called if it has one; the resulting id is placed in the args_dict of the overall object.
    • Next, if the object is JSON serializable, the object is left unchanged and placed in the args_dict.
    • otherwise, the object's repr is placed in the args_dict.
  • if the object has additional attributes, loads as follows:
    • if read_from_id works on this object's id in the context_dict, use that and setattr.
    • otherwise, setattr directly without modification.

ACN-Data Client

• Adds support to gather timeseries of charging current and pilot signal via the ACN-Data api.
• Adds support to get the number of charging sessions which match a query without returning those sessions.
• Adds support to get data from JPL and office001.

Networks

• Adds definitions of JPL and office001 networks.
• Adds simple_acn which models a single-phase network with a single capacity constraint.
  • station_ids argument allows simple_acn to work with sessions from any real ACN.

Algorithms

• Adds support for discrete allowable charging rates for SortedSchedulingAlgo.
• Add last_come_first_served and largest_remaining_processing_time functions for prioritizing sessions.

Battery Models

• When calculating energy delivered in each period using the Linear2Stage model, allows user to select between a "stepwise" energy calculation (assumes constant current in the period) or a more accurate "continuous" model. This only applies during the "tail" portion of the charging curve.

• Add function to estimate a feasible battery capacity from the requested_energy and stay_duration. Estimate is based on the smallest battery capacity (from a set of real battery capacities) and largest initial charge for which it would be feasible to deliver that much energy in the given amount of time. This puts the maximum amount of energy in the "tail" of the charging curve.

Tariffs

• Add support for utility tariffs and calculating charging cost including demand charge.

Refactors

• Refactored the representation of network constraints. Currently, network constraints are represented through the ConstraintSet class, which contains Constraints, each with a limit and a dictionary of lists representing a Current. This pull request changes the ConstraintSet representation into pandas.DataFrame of constraints, mapping individual EVSE currents to aggregate constraint currents in the network. Representing the network constraints as a DataFrame maintains information about EVSEs and Currents while also giving easy access to a matrix representation of the constraints, which is useful in optimization. Additionally, to preserve speed, is_feasible and constraint_current use pre-loaded NumPy matrices to do their calculations rather than pandas objects. Lesson 2 runs about twice as fast with these changes.

• Voltage and phase angle moved to ChargingNetwork rather than each EVSE.

• Adds support for DeadbandEVSE in Interface's allowable_pilot_signals function by:

  • Moving logic for determining allowable set into the EVSE-like classes.
  • Returning the deadband end as the minimum rate for DeadbandEVSE.

• A pilot signal of 0 is implied to be allowed for all EVSEs. This is mentioned in the documentation for the Interface's allowable_pilot_signals function.

• EVSEs have different salient parameters in their constructors depending on their types. So that constructors don't need to retain redundant arguments, a BaseEVSE class is created from which all EVSE classes inherit.

• Convert models within ACN-Sim to use kW and kWh instead of A and A * period.

  • Added methods to Interface to convert kWh to A * period for easy use by algorithms.

• ChargingNetworks are now created by factory functions rather than each being a subclass, this allows a single network definition function to easily interface with multiple subclasses of ChargingNetwork.

• max_recompute (the maximum number of periods between calls to the algorithm) is now an attribute of the algorithm, not the simulator. This makes it easier to ensure that max_recompute is set correctly for algorithms which require being called every so often, i.e. every period.

Additional Testing

• Added tests for ChargingNetwork, Simulator, and (new) Current classes. The Simulator tests include a test for the run method, which runs the first simulation of lesson 2 of the tutorials and compares charging_rates, pilot_signals, and peak with the known results from the master branch. As such, the simulator test directory now has a folder simulation data from the tutorial simulations. The integration test for run in test_simulator.py will catch tutorial-breaking bugs in future changes at the very least. Integration tests with scope between that of a unit test and that of a test running an entire simulation may be needed in the future.

• Automated testing pipelines through Travis CI (+ build passing badge)

Bug Fixes

• Removed an incorrect sym_comp current unbalance function from analysis, and the associated (commented out) test in test_integration.

• evse_voltage in interface.py was behaving as if network.voltages returned an array when it actually behaves as a dict. The tests did not account for this error due to incorrect mocking of the voltages. This release fixes the bug and the test.

• Fixed dimension mismatch in charging_rates_as_df and pilot_signals_as_df

• Fixes a bug in which Interface's last_applied_pilot_signals method returned all pilot signals instead of the last ones applied.

• Fixes bug in EV.reset() function by making init_charge input to Battery.reset() optional. Battery.reset() now resets to initial Battery charge on initialization by default.

• An index out of bounds error could occur when an empty schedule was submitted by the scheduler in the same iteration in which the pilot_signals and charging_rates matrices need to be expanded to accommodate the current iteration. The submission of an empty schedule caused the _update_schedules method to return before the lengths of the matrices were checked. This release ensures that pilot_signals and charging_rates at least have space to store data for the current iteration.

• Standardizes allowable_rates attribute in FiniteRatesEVSE objects. The allowable_rates attribute is now a list of rates, sorted in increasing order, with each rate occurring once and 0 included. User input to __init__ is processed accordingly. Appropriate tests have been added.

• Also, a bug in which the atol argument was not used for certain boundaries of the DeadbandEVSE's feasible set was fixed, and tests were added for the atol functionality.

• Use timezone.localize() instead of astimezone when converting naive date times to fix issues with using astimezone with pytz.

• Update laxity definition to account for current time rather than using arrival time.

• Updated caltech_acn definition to put CC_pod EVSEs on phase AB rather than CA, as this is the true arrangement.