Merge branch 'master' into benchmarking2

.github/workflows/ci.yml

@@ -0,0 +1,33 @@
+# Run CI tests with pytest and update coverage to coveralls
+
+name: CI
+
+on: [push, pull_request]
+
+jobs:
+  test:
+    #runs-on: ${{ matrix.os }}
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        #os: [ubuntu-latest, macos-latest, windows-latest]
+        python-version: [3.7, 3.9]
+
+    steps:
+      - uses: actions/checkout@v2
+        with:
+          submodules: recursive
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v2
+        with:
+          python-version: ${{ matrix.python-version }}
+      - name: Install dependencies
+        run: pip install -e .[test]
+      - name: Test and coverage
+        run: pytest tests/ --cov=pysd
+      - name: Coveralls
+        if: matrix.python-version == 3.7
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: coveralls --service=github
+

dev-requirements.txt

@@ -0,0 +1,5 @@
+pytest
+pytest-cov
+coverage
+coveralls
+psutil

docs/advanced_usage.rst

@@ -42,16 +42,16 @@ We can substitute this function directly for the heat_loss_to_room model compone
 If you want to replace a subscripted variable, you need to ensure that the output from the new function is the same as the previous one. You can check the current coordinates and dimensions of a component by using :py:data:`.get_coords(variable_name)` as it is explained in :doc:`basic usage <../basic_usage>`.
 
 
-Splitting Vensim views in different files
------------------------------------------
-In order to replicate the Vensim views in translated models, the user can set the `split_modules` argument to True in the :py:func:`read_vensim` function::
+Splitting Vensim views in separate Python files (modules)
+---------------------------------------------------------
+In order to replicate the Vensim views in translated models, the user can set the `split_views` argument to True in the :py:func:`read_vensim` function::
 
-   read_vensim("many_views_model.mdl", split_modules=True)
+   read_vensim("many_views_model.mdl", split_views=True)
 
 
 The option to split the model in views is particularly interesting for large models with tens of views. Translating those models into a single file may make the resulting Python model difficult to read and maintain.
 
-In a Vensim model with three separate views (e.g. `view_1`, `view_2` and `view_3`), setting `split_modules` to True would create the following tree inside the directory where the `.mdl` model is located:
+In a Vensim model with three separate views (e.g. `view_1`, `view_2` and `view_3`), setting `split_views` to True would create the following tree inside the directory where the `.mdl` model is located:
 
 | main-folder
 | ├── modules_many_views_model
@@ -64,6 +64,13 @@ In a Vensim model with three separate views (e.g. `view_1`, `view_2` and `view_3
 | ├── many_views_model.py
 |
 |
+
+.. note ::
+    Often, modelers wish to organise views further. To that end, a common practice is to include a particular character in the View name to indicate that what comes after it is the name of the subview. For instance, we could name one view as `ENERGY.Supply` and another one as `ENERGY.Demand`.
+    In that particular case, setting the `subview_sep` kwarg equal to `"."`, as in the code below, would name the translated views as `demand.py` and `supply.py` and place them inside the `ENERGY` folder::
+    
+      read_vensim("many_views_model.mdl", split_views=True, subview_sep=".")
+
 If macros are present, they will be self-contained in files named as the macro itself. The macro inner variables will be placed inside the module that corresponds with the view in which they were defined.
 
 

pysd/_version.py

@@ -1 +1 @@
-__version__ = "1.8.1"
+__version__ = "1.9.0"

pysd/cli/main.py

@@ -26,7 +26,7 @@ def main(args):
     options = parser.parse_args(args)
 
     model = load(options.model_file, options.missing_values,
-                 options.split_modules)
+                 options.split_views, subview_sep=options.subview_sep)
 
     if not options.run:
         print("\nFinished!")
@@ -44,7 +44,7 @@ def main(args):
     sys.exit()
 
 
-def load(model_file, missing_values, split_modules):
+def load(model_file, missing_values, split_views, **kwargs):
     """
     Translate and load model file.
 
@@ -53,6 +53,19 @@ def load(model_file, missing_values, split_modules):
     model_file: str
         Vensim, Xmile or PySD model file.
 
+    split_views: bool (optional)
+        If True, the sketch is parsed to detect model elements in each
+        model view, and then translate each view in a separate python
+        file. Setting this argument to True is recommended for large
+        models split in many different views. Default is False.
+
+    **kwargs: (optional)
+        Additional keyword arguments.
+        subview_sep:(str)
+            Character used to separate views and subviews. If provided,
+            and split_views=True, each submodule will be placed inside the
+            folder of the parent view.
+
     Returns
     -------
     pysd.model
@@ -62,7 +75,7 @@ def load(model_file, missing_values, split_modules):
         print("\nTranslating model file...\n")
         return pysd.read_vensim(model_file, initialize=False,
                                 missing_values=missing_values,
-                                split_modules=split_modules)
+                                split_views=split_views, **kwargs)
     elif model_file.lower().endswith('.xmile'):
         print("\nTranslating model file...\n")
         return pysd.read_xmile(model_file, initialize=False,

pysd/cli/parser.py

@@ -218,9 +218,9 @@ def __call__(self, parser, namespace, values, option_string=None):
          '--saveper will be ignored')
 
 
-###################
-# Model arguments #
-###################
+#########################
+# Translation arguments #
+#########################
 
 trans_arguments = parser.add_argument_group(
     'translation arguments',
@@ -233,10 +233,18 @@ def __call__(self, parser, namespace, values, option_string=None):
          'it does not run it after translation')
 
 trans_arguments.add_argument(
-    '--split-modules', dest='split_modules',
+    '--split-views', dest='split_views',
     action='store_true', default=False,
     help='parse the sketch to detect model elements in each model view,'
-         ' and then translate each view in a separate python file')
+         ' and then translate each view in a separate Python file')
+
+trans_arguments.add_argument(
+    '--subview-sep', dest='subview_sep',
+    action='store', type=str, default="", metavar='STRING',
+    help='further division of views split in subviews, by identifying the'
+         'separator string in the view name, only availabe if --split-views'
+         ' is used')
+
 
 #######################
 # Warnings and errors #