# HyperC (Windows build)

[![Marketplace Version](https://vsmarketplacebadge.apphb.com/version-short/hyperc.hyperc-ext-windows.svg)](https://marketplace.visualstudio.com/items?itemName=hyperc.hyperc-ext-windows)
[![Downloads](https://vsmarketplacebadge.apphb.com/downloads-short/hyperc.hyperc-ext-windows.svg)](https://marketplace.visualstudio.com/items?itemName=hyperc.hyperc-ext-windows)
[![Rating](https://vsmarketplacebadge.apphb.com/rating-short/hyperc.hyperc-ext-windows.svg)](https://marketplace.visualstudio.com/items?itemName=hyperc.hyperc-ext-windows)

HyperC is an AI planning system designed to simplify complex real-world automations. Its applicability ranges from financial planning to robotic motion generation.

## Features

This build focuses on ease of use for Excel workflows with `Python` scripting mode.

HyperC finds the optimal "plan" to get to a desired target. This could be a target revenue, a fully scheduled production, a state where all workers where fully assigned or all packages delivered.

In addition, this extension does:

- Automatically generates the basic template project and installs HyperC build
- Automatically generates classes definitions from XLSX file
- Convenience buttons to run and view calculaiton result

# Usage

This extension adds HyperC module to the left panel of Visual Studio Code. Try creating new project and pressing "Run".

You will need to edit `main.xlsx` file with your table data and `main.py` with your actions macros.

# XLS Table Format

HyperC requires every useful spreadsheet from `main.xlsx` to have a header row. This row will be used to generate attributes for accessing rows' columns of the spreadsheet table from Python.

> E.g. to access a spreadsheet with rows "Doctor Name" you will need to write `doctors_table_row.DOCTOR_NAME`

# Macros Format

You define your business activities(or rules) as Python functions that modify table data or other variables.

## Business Rules

A **business rule** is something that happens in your business: a customer pays for service; a package gets loaded into a truck; a truck drives 1 mile; a doctor gets assigned to a room, etc. 

HyperC will try to "solve" your problem by repeatedly applying all defined business rules until a business rule with statement `DATA.GOAL = True` can be executed.

In HyperC business rules are defined as programmatic actions that modify the data defined in `main.xlsx` file. 

> E.g. a rule that says *"doctor gets assigned to a room"* is a Python function that takes parameters: a row from `DOCTORS` sheet and a row from `ROOMS` sheet and assigns the doctor's name to a corresponding column in Rooms: `selected_room_row.CURRENT_DOCTOR = selected_doctor_row.NAME`

## Machine-based Decisions

HyperC decides which row to use from your tables automatically. Actually, it automatically decides which Python object is most applicable to your current task.

HyperC always optimizes for the minimum amount of executions of business rules that are needed to reach the goal (a function with `DATA.GOAL = True` statement).

## Conditions

Business rules might have some conditions to be applicable to a particular situation. For example the "target" business rule that sets `DATA.GOAL = True` must always have conditions - this is what asks HyperC to start searching for a solution to reach that goal.

> E.g. the rule *"for the package to be loaded onto a truck - the truck must be at the gate"* can be expressed as `selected_truck_row.LOCATION == "at_gate"` (note the `==` - see Python documentation for more about condition checking)

You control applicability of a particular business rule to a particular situation in your table data by writing `assert selected_truck_row == something2` statements. If assert statement does not allow the function to run - the business rule may not be applied to this situation and other rules must be executed first. (see Python language documentation for details about `assert`)

## Input parameters for business rule-function

Complete business rule typically looks like this:

```python
def assign_doctor(selected_doctor: DOCTORS_Class, room: ROOMS_Class):
    assert room.STATUS == "Free"
    assert selected_doctor.CONTRACT_FOR_SHIFT = DATA.PARAMETERS_1.CURRENT_RUNNING_SHIFT
    room.CURRENT_DOCTOR = selected_doctor.NAME
```

This action demonstrates multiple features:

1. Input parameters for the function `selected_doctor` and `room` are rows that are required to be from tables `DOCTORS` and `ROOMS` respectively. HyperC will decide which rows to use at-will, as long as they satisfy the two `assert` statements. Setting up which sheets to use is done by Python "type hint" feature in form `DOCTORS_Class` where `DOCTORS` may be any table name (automatically upper-cased)
2. Accessing a specific cell in spreadsheet table - all rows from all tables are available at `DATA` object that is defined globally. `DATA.PARAMETERS_1.CURRENT_RUNNING_SHIFT` means take row 1 from `Parameters` spreadsheet and use the column `Current Running Shift`

## Creating New Rows

A very useful feature is creating new rows as some business rule executes - e.g. you want to add a record to the 'business event log' table every time the truck is expected to leave the gate. 

Creating a row is done by "instantiating" the class of a table - e.g. to create a new record in "Doctors" a rule will look like:

```python
def hire_a_doctor():  # Will hire a doctor when desired
    global last_doctors_id  # last_doctors_id is a local Python variable
    new_doctor = DOCTORS_Class(NAME="New Doctor", ID=last_doctors_id)
    last_doctors_id += 1  # update doctor ID so for next doctor it will be new
    DATA.PARAMETERS_1.TOTAL_PAYROLL_COUNT += 1  # increase amount of people on payroll
```

> *NOTE*: HyperC does not garbage-collect instantiated objects so it is safe to just leave the new doctor unassigned to an object. But it is recommended to do `all_doctors.add(new_doctor)` to a global `set` object for correctness in Python terms

## Other Python Features

HyperC supports many other features of Python language so you can use `if` statements, `set` collections and object-oriented coding by defining your own classes.

# Limitations

This version of HyperC has only minimal support for integers and integer math. Numbers are effectively limited by about 100. Stay tuned for updated core with full math support.

Not all Python features are supported. Notably `for`, `while`, `list`, `dict` and most of built-in functions like `setattr` are not supported. This is an active work-in-progress.

# Training and Support

Expressivity of Python makes defining things like time and physical dimentions as easy as any other variable. There are a few tricks that can be learned with experience that will make implemeting such features faster.

Get support for commercial use of HyperC and dedicated training at https://hyperc.com

## Performance Notes

Calculation may require unexpected amount of resources. 

Whenever you run into a performance scaling issue, feel free to ask for support. HyperC team updates and trains available heuristics to accomodate for larger problems in a general case - but results are orders of magniture better with a custom trained core.

### Manual Heuristics

Most of performance gains may be created by implementing manual heurustics by incuding additinoal `assert` statements about objects that match the busines rule.

### Object Identity Warrants

Additional complexity lies in resolution of objects that might potentially have equal value. If the objects might never be equal - `hyperc.ensure_ne(obj1, obj2)` should be used. For example, if you select 3 rows from one table at once in a function - and none of them could be equal - you could write 

```python
import hyperc

def shuffle_doctors(doc1: DOCTORS_Class, doc2: DOCTORS_Class, doc3: DOCTORS_Class):
    hyperc.ensure_ne(doc1, doc2)
    hyperc.ensure_ne(doc2, doc3)
    hyperc.ensure_ne(doc1, doc3)
    # ... (other statements)
```

same principle applies to access to objects with `DATA`: 


```python
import hyperc

def shuffle_doctors(doc1: DOCTORS_Class):
    hyperc.ensure_ne(DATA.DOCTORS_1, doc1)
    hyperc.ensure_ne(DATA.DOCTORS_2, DATA.DOCTORS_3)
    hyperc.ensure_ne(doc1, DATA.DOCTORS_3)

    DATA.DOCTORS_1.SHIFT = DATA.DOCTORS_3.SHIFT  # etc..
    # ... (other statements)
```