winsomnia

# Winsomnia is a utility to disable and re-enable sleep mode in Windows.

## Example:
winsomnia(true)
... your script
winsomnia(false)

winsomnia(true) duplicates the currently active power plan, adds '+winsomnia' to its name, sets all its power saving sleep timers (screen,computer, hibernation, disk) to 'never', and activates it.

winsomnia(false) restores the previous power plan. For example, if the current winsomnia plan is called 'Balanced+winsomnia', the call will reactivate the plan named 'Balanced'. In the event 'Balanced' has been deleted since 'Balanced+winsomnia' was created, a warning with ID 'winsomnia:cant_revert' is thrown and the winsomnia plan remains active.

Calling winsomnia(true) when the current power plan name contains '+winsomnia' throws a warning with ID 'winsomnia:already_insomniac' and returns without changing anything.

Calling winsomnia(false) when no power plan name contains '+winsomnia' quietly returns without changing anything. This is means it's safe to call winsomnia(false) whenever, no need to keep track.

This function is based on the Windows command 'powercfg' which is documented here:
https://docs.microsoft.com/en-us/windows-hardware/design/device-experiences/powercfg-command-line-options

## Tips
Type "!powercfg list" on the Matlab commandline to see the list of power
plans available on your computer with an asterisk indicating the currently
active one.

To see the Power Plan Control Panel, type "!control powercfg.cpl" on the
Matlab commandline.

The Power Plan Control Panel needs to be closed and re-opened for the
effects of this function to become fully visible in it.

Add winsomia(false) to your "finish.m" to reset the power plan automatically
upon exiting Matlab.

## Comparison to other similar functions

Winsomnia is similar in purpose to Francesco Montorsi's insomnia function but has four key advantages:
- winsomnia does not change your path variable;
- winsomnia does not require anything but winsomnia.m to be on your path (no header file needed);
- winsomnia does not rely on a persistent variable to restore sleep mode. Using a persistent variable for this purpose is problematic because, despite being persistent, the variable is still lost when Matlab is closed or all memory cleared using clear all;
- winsomnia transparently creates a regular, windows native power plan that can be seen, edited, and managed using Windows Control panel.