Merge pull request #102 from RAMP-project/fix/unify-usecase

Make full use of UseCase class

CHANGELOG.md

@@ -2,7 +2,25 @@ Release History
 ===============
 
 0.4.2 (dev)
-------------------
+-----------
+
+
+
+**|fixed|**     jupyter notebooks are up to date with the UseCase class
+
+**|fixed|**     UseCase class usage is now documented
+
+**|changed|**   num_profile variable was changed to num_days
+
+**|changed|**   User class get assigned automatically to a default UseCase instance if not provided
+
+**|changed|**   Delete ramp.core.initialize and ramp.core.stochastic_process, move calc_peak_time_range inside UseCase method
+
+**|fixed|**     conversion of .py files into .xlsx is fixed
+
+**|fixed|**     using .py files is now possible in the command line as well as from IDE
+
+**|new|**       tests for example jupyter notebook (smoke test to see if the notebooks run through)
 
 **|new|**       continuous integration setup
 

README.rst

@@ -106,16 +106,15 @@ To have a look to the python files, you can download them using the `download_ex
 
    download_example("the specfic folder directory to save the files")
 
--  ``input_file_1.py``: represents the most basic electric appliances,
-   is an example of how to model lightbulbs, radios, TVs, fridges, and
+-  ``input_file_1.py``: represents the most basic electric appliances; it is 
+   an example of how to model lightbulbs, radios, TVs, fridges, and
    other electric appliances. This input file is based on the ones used
-   for `this
-   publication <https://doi.org/10.1016/j.energy.2019.04.097>`__.
+   for `the first RAMP publication <https://doi.org/10.1016/j.energy.2019.04.097>`__.
 
--  ``input_file_2.py``: shows how to model thermal loads, with the
+-  ``input_file_2.py``: shows how to model user-driven thermal loads, with the
    example of a “shower” appliance. The peculiarity of thermal appliances
    is that the nominal power can be provided as external input as a
-   “csv” file (in this case, ``shower_P.csv``). For the example “shower”
+   “.csv” file (in this case, ``shower_P.csv``). For the example “shower”
    appliance, the varying nominal power accounts for the effect of
    groundwater temperature variation throughout the year. This input
    file is based on that used for `this
@@ -138,6 +137,14 @@ To have a look to the python files, you can download them using the `download_ex
    file is used in `this
    publication <https://doi.org/10.1109/PTC.2019.8810571>`__
 
+You can execute python input files within an IDE, in your terminal with python command
+
+.. code-block:: bash
+
+   python <path to .py input file>
+
+or in your terminal with the ``ramp`` command, see `Command line options <cmd_option_>`_ below for more information.
+
 Spreadsheet input files
 -----------------------
 
@@ -149,18 +156,22 @@ need to run the ``ramp`` command with the option ``-i``:
    ramp -i <path to .xlsx input file>
 
 
-.. note:: You can input several files, separated from each others by a single blank space
+.. note:: You can input several files, separated from each others by a single blank space you can also input python files
+
+.. _cmd_option:
+
+Command line options
+--------------------
 
-If you already know how many profile you want to simulate you can indicate it with the ``-n`` option:
+In the command line you can also run .py input files
+If you already know how many daily profiles you want to simulate you can indicate it with the ``-n`` option:
 
 .. code-block:: bash
 
-   ramp -i <path to .xlsx input file> -n 10
+   ramp -i <path to .xlsx or .py input file> -n 10
 
-will simulate 10 profiles. Note that you can use this option without
-providing a ``.xlsx`` input file with the ``-i`` option, this will then
-be equivalent to running ``python ramp_run.py`` from the ``ramp`` folder
-without being prompted for the number of profile within the console.
+will simulate 10 daily profiles. Note that if you do not provide this option you will being prompted for the
+number of daily profiles within the console.
 
 
 If you want to save ramp results to a custom file, you can provide it with the option `-o`
@@ -193,11 +204,11 @@ Building a model with a python script
 .. code-block:: python
 
    # importing functions
-   from ramp import User,calc_peak_time_range,yearly_pattern
+   from ramp import UseCase, User
 
    # Create a user category
-   low_income_households = User(
-    user_name = "low_income_household", # an optional feature for the User class
+   household_1 = User(
+    user_name = "Household type 1", # an optional feature for the User class
     num_users = 10, # Specifying the number of specific user category in the community
    )
 
@@ -206,14 +217,15 @@ You can add appliances to a user category by:
 .. code-block:: python
 
    # adding some appliances for the household
-   radio = low_income_household.add_appliance(
+   radio = household_1.add_appliance(
     name = "Small Radio", # optional feature for the appliance class
-    number = 1, # how many radio each low income household holds
-    power = 10, # RAMP does not take care of unit of measures , watt
+    number = 1, # how many radio each household type 1 has
+    power = 10, # RAMP does not take care of units of measure (e.g., Watts), you must be consistent
     func_time = 120, # Total functioning time of appliance in minutes
-    num_windows = 2, # in how many time-windows the appliance is used
+    num_windows = 2, # how many time-windows the appliance is used in
    )
 
+
 The use time frames can be specified using the 'window' method for each appliance of the user category:
 
 .. code-block:: python
@@ -224,16 +236,44 @@ The use time frames can be specified using the 'window' method for each applianc
     window_2 = [1320,1380], # from 10 PM to 11 PM
    )
 
-Now you can generate your **stochastic profiles**:
+You can also add another, different user to the simulation. In this case,
+we use a more compact formulation:
 
 .. code-block:: python
 
-   # generating load_curves
-   load = low_income_household.generate_aggregated_load_profiles(
-      prof_i = 1, # the ith day profile
-      peak_time_range = calc_peak_time_range(), # the peak time range
-      Year_behaviour = yearly_pattern(), # defining the yearly pattern (like weekdays/weekends)
-   )
+   # Create a second user category
+   household_2 = User(
+    user_name = "Household type 2", # an optional feature for the User class
+    num_users = 13, # Specifying the number of specific user category in the community
+    )
+
+   # adding some appliances for the new household type in compact form, with windows specified directly and random variability
+   light_bulbs = household_2.add_appliance(
+    name = "Light bulbs", # optional feature for the appliance class
+    number = 5, # how many light bulbs each household type 2 has
+    power = 7, # RAMP does not take care of units of measure (e.g., Watts), you must be consistent
+    func_time = 120, # total functioning time of appliance in minutes
+    time_fraction_random_variability=0.2, # 20% random variability associated to the total functioning time
+    num_windows = 2, # how many time-windows the appliance is used in
+    window_1 = [390,480], # from 6.30 AM to 8 AM
+    window_2 = [1020,1440], # from 5 PM to 12 PM
+    random_var_w=0.35 # 35% randomness assigned to the size of the functioning windows
+    )
+
+At this point, we can group our different users into a "use case" and run the simulation, 
+for instance for a whole year.
+
+.. code-block:: python
+
+   use_case = UseCase(users=[household_1,household_2], date_start="2020-01-01", date_end="2020-12-31")
+   whole_year_profile = use_case.generate_daily_load_profiles()
+
+Here is your first load for a community including two types of housholds,
+for a total of 23 individual users. Of course, more variations and many more 
+features are possible! For instance, you can simulate loads even for 
+an individual appliance or user. In addition, you can use in-built plotting 
+functionalities to explore your results. Check out the documentation 
+for all the possibilities.
 
 Contributing
 ============