Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Fix #3831 - New (labs) CLI command for measure new and measure copy #4875

Merged
merged 8 commits into from
Jun 29, 2023
Merged

Fix #3831 - New (labs) CLI command for measure new and measure copy #4875

merged 8 commits into from
Jun 29, 2023

Conversation

jmarrec
Copy link
Collaborator

@jmarrec jmarrec commented May 3, 2023 •
edited
Loading

Pull request overview

measure --help

openstudio labs measure --help 
$ openstudio labs measure --help
Measure Commands
Usage: Products/openstudio labs measure [OPTIONS] [DIRECTORY] [SUBCOMMAND]

Positionals:
  DIRECTORY                        Directory containing the measure(s)

Options:
  -h,--help                        Print this help message and exit
  -u,--update Needs: DIRECTORY Excludes: --update_all --compute_arguments --run_tests
                                   Update the measure.xml
  -t,--update_all Needs: DIRECTORY Excludes: --update --compute_arguments --run_tests
                                   Update all measures in a directory
  -a,--compute_arguments MODEL     Specify the FILE path to the workflow to run
  -r,--run_tests Needs: DIRECTORY Excludes: --update --update_all --compute_arguments
                                   Run all tests recursively found in a directory, additional arguments are passed to minitest
  -s,--start_server PORT           Start a measure manager server

Subcommands:
  new                              Create a new measure
  copy                             Copy a measure

measure new --help

$ openstudio labs measure new --help

Create a new measure
Usage: Products/openstudio labs measure new [OPTIONS] DIRECTORY

Positionals:
  DIRECTORY                        Directory for the measure

Options:
  -t,--type measureType            Type of Measure [Default: 'ModelMeasure']: ["ModelMeasure", "EnergyPlusMeasure", "UtilityMeasure", "ReportingMeasure"]
  -l,--language measureLanguage    Language of Measure [Default: 'Ruby']: ["Ruby", "Python"]
  -c,--class-name className        Measure Class Name [Required]
  -n,--name name                   Measure Human Readable Name [Default: className]
  --taxonomy-tag tag               Taxonomy Tag [Default: 'Envelope.Fenestration']
  -d,--description desc            Description
  -m,--modeler-description modeler_desc
                                   Modeler Description


Help:
  -h,--help                        Print this help message and exit
  --examples                       Show Example usage
  --list-taxonomy-tags             List all available Taxonomy tags
  --list-for-first-taxonomy-tag tag
                                   Limit taxonomy tags to this first level

Subhelp

$ openstudio labs measure new --examples
$ openstudio labs measure new --examples Examples:
  1. Create a Ruby ModelMeasure:
$ openstudio labs measure new --class-name MyExampleRubyModelMeasure
$ openstudio labs measure new --class-name MyExampleRubyModelMeasure --type ModelMeasure --language Ruby
  1. Pass all optional args to create a Python EnergyPlusMeasure:
$ openstudio labs measure new --class-name MyExamplePythonMeasure --type EnergyPlusMeasure --language Python --name "My Python Measure" --description "This is my measure" --modeler-description "This does complicated stuff" --taxonomy-tag "Envelope.Form" ./test_measure

$ openstudio labs measure new -c MyExamplePythonMeasure -t EnergyPlusMeasure -l Python -n "My Python Measure" -d "This is my measure" -m "This does complicated stuff" --taxonomy-tag "Envelope.Form" ./test_measure
  1. List taxonomy tags
$ openstudio --list-taxonomy-tags
$ openstudio --list-for-first-taxonomy-tag HVAC

copy --help

$ openstudio labs measure copy --help

Copy a measure
Usage: Products/openstudio labs measure copy [OPTIONS] EXISTING_DIRECTORY NEW_DIRECTORY

Positionals:
  EXISTING_DIRECTORY               Existing Directory for the measure
  NEW_DIRECTORY                    New Directory for the measure

Options:
  -h,--help                        Print this help message and exit

Pull Request Author

  • Model API Changes / Additions
  • Any new or modified fields have been implemented in the EnergyPlus ForwardTranslator (and ReverseTranslator as appropriate)
  • Model API methods are tested (in src/model/test)
  • EnergyPlus ForwardTranslator Tests (in src/energyplus/Test)
  • If a new object or method, added a test in NREL/OpenStudio-resources: Add Link
  • If needed, added VersionTranslation rules for the objects (src/osversion/VersionTranslator.cpp)
  • Verified that C# bindings built fine on Windows, partial classes used as needed, etc.
  • All new and existing tests passes
  • If methods have been deprecated, update rest of code to use the new methods

Labels:

  • If change to an IDD file, add the label IDDChange
  • If breaking existing API, add the label APIChange
  • If deemed ready, add label Pull Request - Ready for CI so that CI builds your PR

Review Checklist

This will not be exhaustively relevant to every PR.

  • Perform a Code Review on GitHub
  • Code Style, strip trailing whitespace, etc.
  • All related changes have been implemented: model changes, model tests, FT changes, FT tests, VersionTranslation, OS App
  • Labeling is ok
  • If defect, verify by running develop branch and reproducing defect, then running PR and reproducing fix
  • If feature, test running new feature, try creative ways to break it
  • CI status: all green or justified

@jmarrec jmarrec added component - Measures component - CLI component - Workflow Pull Request - Ready for CI This pull request if finalized and is ready for continuous integration verification prior to merge. labels May 3, 2023
@jmarrec jmarrec self-assigned this May 3, 2023
jmarrec
jmarrec commented May 3, 2023
View reviewed changes
src/cli/MeasureUpdateCommand.hpp
Comment on lines +44 to +56
struct MeasureNewOptions
{
std::string name;
std::string className = "MyExampleMeasure";
openstudio::path directoryPath;
std::string taxonomyTag = "Envelope.Fenestration";
openstudio::MeasureType measureType = openstudio::MeasureType::ModelMeasure;
openstudio::MeasureLanguage measureLanguage = openstudio::MeasureLanguage::Ruby;
std::string description = "DESCRIPTION_TEXT";
std::string modelerDescription = "MODELER_DESCRIPTION_TEXT";

void debug_print() const;
};
Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Struct (and its defaults) for new/copy is here

src/cli/MeasureUpdateCommand.hpp
@@ -57,6 +73,8 @@ namespace cli {
bool run_tests = false;

unsigned server_port = 0;

MeasureNewOptions newMeasureOpts;
Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This is added to here. because we use make_shared for scoping issues... don't worry about it

src/cli/MeasureUpdateCommand.cpp
Comment on lines +103 to +115
// TODO: this includes 'UtilityMeasure' which I don't think we want to include
std::vector<std::string> measureTypeNames;
{
const auto& m = openstudio::MeasureType::getNames();
std::transform(m.cbegin(), m.cend(), back_inserter(measureTypeNames), [](const auto& x) { return x.second; });
// fmt::print("measureTypeNames={}\n", measureTypeNames);
[[maybe_unused]] auto* measureTypeOpt =
newMeasureSubCommand
->add_option("-t,--type", opt->newMeasureOpts.measureType,
fmt::format("Type of Measure [Default: '{}']: {}", opt->newMeasureOpts.measureType.valueName(), measureTypeNames))
->option_text("measureType")
->check(CLI::IsMember(measureTypeNames));
}
Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

TODO

src/cli/MeasureUpdateCommand.cpp
->add_option("-t,--type", opt->newMeasureOpts.measureType,
fmt::format("Type of Measure [Default: '{}']: {}", opt->newMeasureOpts.measureType.valueName(), measureTypeNames))
->option_text("measureType")
->check(CLI::IsMember(measureTypeNames));
Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Throughout the options, I'm going to validate input.

eg try to pass measure new --type Badval and you'll get:

--type: Badval not in {ModelMeasure,EnergyPlusMeasure,UtilityMeasure,ReportingMeasure}

src/cli/MeasureUpdateCommand.cpp
Comment on lines +161 to +165
[[maybe_unused]] auto* directoryPathOpt =
newMeasureSubCommand->add_option("DIRECTORY", opt->newMeasureOpts.directoryPath, "Directory for the measure")
->option_text(" ")
->required(true)
->check(CLI::NonexistentPath);
Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Throw if the target directory exists. BCLMeasure's ctor to create a new one would throw anyways, but this throws earlier and a lot more clearly.

$ mkdir ./test_measure && openstudio labs measure new --class-name MyExamplePythonMeasure ./test_measure
DIRECTORY: Path already exists: ./test_measure

src/cli/MeasureUpdateCommand.cpp
Comment on lines +167 to +180
{
static constexpr auto helpOptionsGroupName = "Help";
static constexpr auto newMeasureExamples = R"(Examples:

1. Create a Ruby ModelMeasure:

```
$ openstudio labs measure new --class-name MyExampleRubyModelMeasure
$ openstudio labs measure new --class-name MyExampleRubyModelMeasure --type ModelMeasure --language Ruby
```

2. Pass all optional args to create a Python EnergyPlusMeasure:

```
Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Helpers, because I feel like this is going to be more than helpful given the number of options we can optionally pass

src/cli/MeasureUpdateCommand.cpp
$ openstudio labs measure new --list-for-first-taxonomy-tag HVAC
```
)";
newMeasureSubCommand->set_help_flag("-h,--help", "Print this help message and exit")->group(helpOptionsGroupName);
Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Since I'm making a specific "Help" group, might as well make the CLI11 default '--help' fall into that group.

src/cli/MeasureUpdateCommand.cpp
Comment on lines +204 to +212
[[maybe_unused]] auto* listTaxonomyFlag = newMeasureSubCommand
->add_flag_callback(
"--list-taxonomy-tags",
[taxonomyTags]() {
fmt::print("{}\n", taxonomyTags);
std::exit(0); // NOLINT(concurrency-mt-unsafe)
},
"List all available Taxonomy tags")
->group(helpOptionsGroupName);
Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Couple of flags for taxonomy lookup, because even though I could just try to pass openstudio measure new --taxonomy-tag Badval ./test_measure and look at the error message to get accepted values, this is clearer to use openstudio measure new --list-taxonomy-tags

Also added one that looks up from a first level tag: openstudio measure new --list-for-first-taxonomy-tag Envelope (and throws if that first tag isn't valid)

NOTE: maybe this should live onto the measure subcommand and not the measure new subsubcommand, but that's maybe nitpicking, and it would reduce the readability of the help message in measure subcomand

src/cli/MeasureUpdateCommand.cpp
Comment on lines +240 to +242
if (opt->newMeasureOpts.name.empty()) {
opt->newMeasureOpts.name = opt->newMeasureOpts.className;
}
Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

If the "--name" isn't passed, default to the required --class-name one

src/cli/MeasureUpdateCommand.cpp
Comment on lines +270 to +292
copyMeasureSubCommand->callback([opt] {
boost::optional<BCLMeasure> b_;
try {
b_ = BCLMeasure(opt->directoryPath);
} catch (...) {
fmt::print(stderr, "Could not find a valid measure at '{}'\n", openstudio::toString(opt->directoryPath));
std::exit(1);
}
auto bClone_ = b_->clone(opt->newMeasureOpts.directoryPath);
if (bClone_) {
// Force updating the UID
bClone_->changeUID();
bClone_->checkForUpdatesFiles();
bClone_->checkForUpdatesXML();
bClone_->save();
fmt::print("Cloned the {} {} with class name '{}' from '{}' to '{}'\n", b_->measureLanguage().valueName(), b_->measureType().valueName(),
b_->className(), openstudio::toString(openstudio::filesystem::canonical(b_->directory())),
openstudio::toString(openstudio::filesystem::canonical(bClone_->directory())));
std::exit(0); // NOLINT(concurrency-mt-unsafe)
} else {
fmt::print(stderr, "Something went wrong when cloning the measure");
std::exit(1); // NOLINT(concurrency-mt-unsafe)
}
Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Copying a measure. Exit gracefully if the directory isn't a valid measure.

Make sure we do end up with a new UID and everything is up to date in the measure.xml.

@jmarrec
Copy link
Collaborator Author

jmarrec commented May 3, 2023

I’m reluctant to add new CMake add_test stuff for these new commands. It’s getting ridiculously complicated already (see

OpenStudio/src/cli/CMakeLists.txt

Line 88 in 8054887

add_test(NAME OpenStudioCLI.run_compact_ruby_only_osw
). Perhaps for this I should use a ruby or python helper script that’d call the CLI, like we do with some other stuff.

Or we’re ok not adding explicit tests for these and do it manually, as they shouldn't change often anyways.

Thoughts @kbenne @tijcolem please?

@ci-commercialbuildings
Copy link
Collaborator

ci-commercialbuildings commented May 10, 2023 •
edited
Loading

CI Results for 3b5ea39:

@jmarrec jmarrec added this to the OpenStudio SDK 3.7.0 milestone May 31, 2023
@jmarrec jmarrec merged commit ad5503e into develop Jun 29, 2023
@jmarrec jmarrec deleted the 3831_measure_new_CLI branch June 29, 2023 14:26
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Reviewers

@kbenne kbenne Awaiting requested review from kbenne

@DavidGoldwasser DavidGoldwasser Awaiting requested review from DavidGoldwasser

Assignees

@jmarrec jmarrec

Labels
component - CLI component - Measures component - Workflow Pull Request - Ready for CI This pull request if finalized and is ready for continuous integration verification prior to merge.
Projects
None yet
Milestone
OpenStudio SDK 3.7.0
Development

Successfully merging this pull request may close these issues.

New CLI command for measure --new and measure --copy
2 participants
@jmarrec @ci-commercialbuildings