Added separate LockedPlanningMethod and ClonedPlanningMethod calls.

[psigen]

This should be merged after #278 and #279.

This separates the @PlanningMethod decorator into two decorators:

• @LockedPlanningMethod locks the current robot environment and executes the wrapped method.
• @ClonedPlanningMethod clones the current robot environment and executes the wrapped method.

This distinction is useful for planning calls that are so fast that they take less time than the cloning operation itself, such as optimistic plans like SnapPlanner and fast mathematical solutions such as KunzCircularBlender.

This commit refactors all existing planning calls except SnapPlanner to use @ClonedPlanningMethod and updates the README to explain the distinction. @PlanningMethod is changed to inherit from @ClonedPlanningMethod but print a warning if it is used.

[mkoval]

This description does not clearly articulate the difference between the two decorators. For example, it currently implies that @LockedPlanningMethod allows PrPy to parallelize multiple planners. I think you should reword this.

[mkoval]

Typo: paralellize

[psigen]

Sure I'll fix your typos 😉
854b6f3

[mkoval]

I am generally supportive of this change.

My only concern is about the potential confusion introduced by planner.env. This environment is created in the PlannerBase class, even in sub-class that only use @LockedPlanningMethod. We also explicitly clone into planner.env inside the Ranked meta planner, which is unnecessary for @LockedPlanningMethods.

I am not sure what the best way to address this is. At a minimum, we need to clearly document that @*PlanningMethods must return a Trajectory in the same Environment as robot.GetEnv(). I believe this handles both cases.

[psigen]

I made some doc changes in 788d1d5 to clarify the above.

I think it's largely harmless to have PlannerBase create a single env per planner, because most planners will have cloned methods or a mix of cloned and locked methods, and I would rather not have to divide the PlannerBase up and have to switch classes over when they start having ClonedPlanningMethods.

Metaplanners will probably need to always use cloning for now, because they need to lock an env to maintain ActiveDOFs and other initial configuration to start up other planners, and there is currently no way to lock an env just until it has been cloned by a few planners. It is very tricky to synchronize this otherwise.

[mkoval]

👍 Thanks for improving the documentation. I will merge this once Travis finishes on #278.

[mkoval]

@psigen This will not merge cleanly. I suspect that it conflicts with something in #278. Could you resolve this on the command line?

[psigen]

Not sure what the issue was, it merged just fine on command-line with no input.
@mkoval: Should be good to merge now.

[mkoval]

Finally got Travis to run on this. LGTM.