# 1. Usage

## 1.1. Installation

UnitCommitment.jl was tested and developed with Julia 1.6. To install Julia, please follow the installation guide on the official Julia website. To install UnitCommitment.jl, run the Julia interpreter, type `]` to open the package manager, then type:

    pkg> add UnitCommitment@0.2

To test that the package has been correctly installed, run:

    pkg> test UnitCommitment

If all tests pass, the package should now be ready to be used by any Julia script on the machine.

To solve the optimization models, a mixed-integer linear programming (MILP) solver is also required. Please see the JuMP installation guide for more instructions on installing a solver. Typical open-source choices are Cbc and GLPK. In the instructions below, Cbc will be used, but any other MILP solver listed in JuMP installation guide should also be compatible.

## 1.2. Typical Usage

### Solving user-provided instances

The first step to use UC.jl is to construct a JSON file describing your unit commitment instance. See Data Format for a complete description of the data format UC.jl expects. The next steps, as shown below, are to: (1) read the instance from file; (2) construct the optimization model; (3) run the optimization; and (4) extract the optimal solution.

    using Cbc
    using JSON
    using UnitCommitment

    # 1. Read instance
    instance = UnitCommitment.read("/path/to/input.json")

    # 2. Construct optimization model
    model = UnitCommitment.build_model(
        instance=instance,
        optimizer=Cbc.Optimizer,
    )

    # 3. Solve model
    UnitCommitment.optimize!(model)

    # 4. Write solution to a file
    solution = UnitCommitment.solution(model)
    UnitCommitment.write("/path/to/output.json", solution)

### Solving benchmark instances

UnitCommitment.jl contains a large number of benchmark instances collected from the literature and converted into a common data format. To solve one of these instances individually, instead of constructing your own, the function `read_benchmark` can be used, as shown below. See Instances for the complete list of available instances.

    using UnitCommitment
    instance = UnitCommitment.read_benchmark("matpower/case3375wp/2017-02-01")

## 1.3. Advanced usage

### Customizing the formulation

By default, `build_model` uses a formulation that combines modeling components from different publications, and that has been carefully tested, using our own benchmark scripts, to provide good performance across a wide variety of instances. This default formulation is expected to change over time, as new methods are proposed in the literature. You can, however, construct your own formulation, based on the modeling components that you choose, as shown in the next example.

    using Cbc
    using UnitCommitment

    import UnitCommitment:
        Formulation,
        KnuOstWat2018,
        MorLatRam2013,
        ShiftFactorsFormulation

    instance = UnitCommitment.read_benchmark(
        "matpower/case118/2017-02-01",
    )

    model = UnitCommitment.build_model(
        instance = instance,
        optimizer = Cbc.Optimizer,
        formulation = Formulation(
            pwl_costs = KnuOstWat2018.PwlCosts(),
            ramping = MorLatRam2013.Ramping(),
            startup_costs = MorLatRam2013.StartupCosts(),
            transmission = ShiftFactorsFormulation(
                isf_cutoff = 0.005,
                lodf_cutoff = 0.001,
            ),
        ),
    )

### Generating initial conditions

When creating random unit commitment instances for benchmark purposes, it is often hard to compute, in advance, sensible initial conditions for all generators. Setting initial conditions naively (for example, making all generators initially off and producing no power) can easily cause the instance to become infeasible due to excessive ramping. Initial conditions can also make it hard to modify existing instances. For example, increasing the system load without carefully modifying the initial conditions may make the problem infeasible or unrealistically challenging to solve.

To help with this issue, UC.jl provides a utility function which can generate feasible initial conditions by solving a single-period optimization problem, as shown below:

    using Cbc
    using UnitCommitment

    # Read original instance
    instance = UnitCommitment.read("instance.json")

    # Generate initial conditions (in-place)
    UnitCommitment.generate_initial_conditions!(instance, Cbc.Optimizer)

    # Construct and solve optimization model
    model = UnitCommitment.build_model(
        instance=instance,
        optimizer=Cbc.Optimizer,
    )
    UnitCommitment.optimize!(model)

Warning

The function `generate_initial_conditions!` may return different initial conditions after each call, even if the same instance and the same optimizer is provided. The particular algorithm may also change in a future version of UC.jl. For these reasons, it is recommended that you generate initial conditions exactly once for each instance and store them for later use.

### Verifying solutions

When developing new formulations, it is very easy to introduce subtle errors in the model that result in incorrect solutions. To help with this, UC.jl includes a utility function that verifies if a given solution is feasible, and, if not, prints all the validation errors it found. The implementation of this function is completely independent from the implementation of the optimization model, and therefore can be used to validate it. The function can also be used to verify solutions produced by other optimization packages, as long as they follow the UC.jl data format.

    using JSON
    using UnitCommitment

    # Read instance
    instance = UnitCommitment.read("instance.json")

    # Read solution (potentially produced by other packages)
    solution = JSON.parsefile("solution.json")

    # Validate solution and print validation errors
    UnitCommitment.validate(instance, solution)

UnitCommitment.jl 2. Data Format