https://refinery.tools/assets/js/4b2ba393.e0100501.js

1"use strict";(self.webpackChunk_tools_refinery_docs=self.webpackChunk_tools_refinery_docs||[]).push([["6818"],{1745(e,n,r){r.r(n),r.d(n,{metadata:()=>i,default:()=>u,frontMatter:()=>c,contentTitle:()=>l,toc:()=>a,assets:()=>d});var i=JSON.parse('{"id":"learn/docker/cli","title":"Command-line interface","description":"You can run Refinery as a command-line applications via our Docker container on either amd64 or arm64 machines:","source":"@site/versioned_docs/version-0.3.0/learn/docker/cli.md","sourceDirName":"learn/docker","slug":"/learn/docker/cli","permalink":"/learn/docker/cli","draft":false,"unlisted":false,"editUrl":"https://github.com/graphs4value/refinery/edit/main/subprojects/docs/versioned_docs/version-0.3.0/learn/docker/cli.md","tags":[],"version":"0.3.0","sidebarPosition":1,"frontMatter":{"SPDX-FileCopyrightText":"2024 The Refinery Authors","SPDX-License-Identifier":"EPL-2.0","sidebar_position":1,"sidebar_label":"CLI"},"sidebar":"learnSidebar","previous":{"title":"Docker","permalink":"/learn/docker/"}}'),o=r(1085),t=r(1184),s=r(6559);let c={"SPDX-FileCopyrightText":"2024 The Refinery Authors","SPDX-License-Identifier":"EPL-2.0",sidebar_position:1,sidebar_label:"CLI"},l="Command-line interface",d={},a=[{value:"The <code>generate</code> subcommand",id:"generate",level:2},{value:"<code>-output</code>, <code>-o</code>",id:"generate-output",level:3},{value:"<code>-random-seed</code>, <code>-r</code>",id:"generate-random-seed",level:3},{value:"<code>-scope</code>, <code>-s</code>",id:"generate-scope",level:3},{value:"<code>-scope-override</code>, <code>-S</code>",id:"generate-scope-override",level:3},{value:"<code>-solution-number</code>, <code>-n</code>",id:"generate-solution-number",level:3},{value:"The <code>check</code> subcommand",id:"check",level:2},{value:"<code>-concretize</code>, <code>-k</code>",id:"check-concretize",level:3},{value:"The <code>concretize</code> subcommand",id:"concretize",level:2},{value:"<code>-output</code>, <code>-o</code>",id:"concretize-output",level:3}];function h(e){let n={a:"a",code:"code",em:"em",h1:"h1",h2:"h2",h3:"h3",header:"header",li:"li",p:"p",pre:"pre",strong:"strong",ul:"ul",...(0,t.R)(),...e.components};return(0,o.jsxs)(o.Fragment,{children:[(0,o.jsx)(n.header,{children:(0,o.jsx)(n.h1,{id:"command-line-interface",children:"Command-line interface"})}),"\n",(0,o.jsxs)(n.p,{children:["You can run Refinery as a command-line applications via our ",(0,o.jsx)(n.a,{href:"https://github.com/graphs4value/refinery/pkgs/container/refinery-cli",children:"Docker container"})," on either ",(0,o.jsx)(n.code,{children:"amd64"})," or ",(0,o.jsx)(n.code,{children:"arm64"})," machines:"]}),"\n",(0,o.jsx)(n.pre,{children:(0,o.jsx)(n.code,{className:"language-shell",children:"docker run --rm -it -v ${PWD}:/data ghcr.io/graphs4value/refinery-cli:0.3.0\n"})}),"\n",(0,o.jsxs)(n.p,{children:["This will let you read input files and generate models in the current directory (",(0,o.jsx)(n.code,{children:"${PWD}"}),") of your terminal session.\nModule imports (e.g., ",(0,o.jsx)(n.code,{children:"import some::module."})," to import ",(0,o.jsx)(n.code,{children:"some/module.refinery"}),") relative to the current directory are also supported."]}),"\n",(0,o.jsxs)(n.p,{children:["For example, to generate a model based on the file named ",(0,o.jsx)(n.code,{children:"input.problem"})," in the current directory and write the results into the file named ",(0,o.jsx)(n.code,{children:"output.refinery"}),", you may run the ",(0,o.jsxs)(n.a,{href:"#generate",children:[(0,o.jsx)(n.code,{children:"generate"})," subcommand"]})," with"]}),"\n",(0,o.jsx)(n.pre,{children:(0,o.jsx)(n.code,{className:"language-shell",children:"docker run --rm -it -v ${PWD}:/data ghcr.io/graphs4value/refinery-cli:0.3.0 generate -o output.refinery input.problem\n"})}),"\n",(0,o.jsx)(n.p,{children:"If you want Refinery CLI to print its documentation, run"}),"\n",(0,o.jsx)(n.pre,{children:(0,o.jsx)(n.code,{className:"language-shell",children:"docker run --rm -it -v ${PWD}:/data ghcr.io/graphs4value/refinery-cli:0.3.0 -help\n"})}),"\n",(0,o.jsxs)(n.h2,{id:"generate",children:["The ",(0,o.jsx)(n.code,{children:"generate"})," subcommand"]}),"\n",(0,o.jsxs)(n.p,{children:["The ",(0,o.jsx)(n.code,{children:"generate"})," subcommand generates a consistent concrete model from a partial model.\nYou can also use the short name ",(0,o.jsx)(n.code,{children:"g"})," to access this subcommand."]}),"\n",(0,o.jsx)(n.pre,{children:(0,o.jsx)(n.code,{className:"language-shell",children:"docker run --rm -it -v ${PWD}:/data ghcr.io/graphs4value/refinery-cli:0.3.0 generate [options] input path\n"})}),"\n",(0,o.jsxs)(n.p,{children:["The ",(0,o.jsx)(n.code,{children:"input path"})," should be a path to a ",(0,o.jsx)(n.code,{children:".problem"})," file relative to the current directory.\nDue to Docker containerization, paths ",(0,o.jsx)(n.em,{children:"outside"})," the current directory (e.g., ",(0,o.jsx)(n.code,{children:"../in

1put.problem"}),") are not supported."]}),"\n",(0,o.jsxs)(n.p,{children:["Passing ",(0,o.jsx)(n.code,{children:"-"})," as the ",(0,o.jsx)(n.code,{children:"input path"})," will read a partial model from the standard input."]}),"\n",(0,o.jsxs)(n.p,{children:["By default, the generator is ",(0,o.jsx)(n.em,{children:"deterministic"})," and always outputs the same concrete model. See the ",(0,o.jsx)(n.a,{href:"#generate-random-seed",children:(0,o.jsx)(n.code,{children:"-random-seed"})})," option to customize this behavior."]}),"\n",(0,o.jsxs)(n.p,{children:["See below for the list of supported ",(0,o.jsx)(n.code,{children:"[options]"}),"."]}),"\n",(0,o.jsxs)(n.h3,{id:"generate-output",children:[(0,o.jsx)(n.code,{children:"-output"}),", ",(0,o.jsx)(n.code,{children:"-o"})]}),"\n",(0,o.jsxs)(n.p,{children:["The output path for the concretized model, usually a file with the ",(0,o.jsx)(n.code,{children:".refinery"})," extension.\nPassing ",(0,o.jsx)(n.code,{children:"-o -"})," will write the generated model to the standard output."]}),"\n",(0,o.jsxs)(n.p,{children:["When generating multiple models with ",(0,o.jsx)(n.a,{href:"#generate-solution-number",children:(0,o.jsx)(n.code,{children:"-solution-number"})}),", the value ",(0,o.jsx)(n.code,{children:"-"})," is not supported and individual solutions will be saved to numbered files.\nFor example, if you pass ",(0,o.jsx)(n.code,{children:"-o output.refinery -n 10"}),", solutions will be saved as ",(0,o.jsx)(n.code,{children:"output_001.refinery"}),", ",(0,o.jsx)(n.code,{children:"output_002.refinery"}),", \u2026, ",(0,o.jsx)(n.code,{children:"output_010.refinery"}),"."]}),"\n",(0,o.jsxs)(n.p,{children:[(0,o.jsx)(n.strong,{children:"Default value:"})," ",(0,o.jsx)(n.code,{children:"-"}),", i.e., the solution is written to the standard output."]}),"\n",(0,o.jsxs)(n.h3,{id:"generate-random-seed",children:[(0,o.jsx)(n.code,{children:"-random-seed"}),", ",(0,o.jsx)(n.code,{children:"-r"})]}),"\n",(0,o.jsx)(n.p,{children:"Random seed to control the behavior of model generation."}),"\n",(0,o.jsxs)(n.p,{children:["The same random seed value and Refinery release will produce the same output model for an input problem.\nModels generated with different values of ",(0,o.jsx)(n.code,{children:"-random-seed"})," are highly likely (but are not guaranteed) to be ",(0,o.jsx)(n.em,{children:"substantially"})," different."]}),"\n",(0,o.jsxs)(n.p,{children:[(0,o.jsx)(n.strong,{children:"Default value:"})," ",(0,o.jsx)(n.code,{children:"1"})]}),"\n",(0,o.jsxs)(n.h3,{id:"generate-scope",children:[(0,o.jsx)(n.code,{children:"-scope"}),", ",(0,o.jsx)(n.code,{children:"-s"})]}),"\n",(0,o.jsxs)(n.p,{children:["Add ",(0,o.jsx)(n.a,{href:"../../language/logic#type-scopes",children:"scope constraints"})," to the input problem."]}),"\n",(0,o.jsx)(n.p,{children:"This option is especially useful if you want to generate models of multiple sizes from the same partial model."}),"\n",(0,o.jsx)(n.p,{children:"For example, the command"}),"\n",(0,o.jsx)(n.pre,{children:(0,o.jsx)(n.code,{className:"language-shell",children:"docker run --rm -it -v ${PWD}:/data ghcr.io/graphs4value/refinery-cli:0.3.0 generate -s File=20..25 input.problem\n"})}),"\n",(0,o.jsx)(n.p,{children:"is equivalent to appending"}),"\n",(0,o.jsx)(n.pre,{children:(0,o.jsx)(n.code,{className:"language-refinery",metastring:'title="input.problem"',children:"scope File = 20..25.\n"})}),"\n",(0,o.jsxs)(n.p,{children:["to ",(0,o.jsx)(n.code,{children:"input.problem"}),".\nThe syntax of the argument is equivalent to the ",(0,o.jsx)(n.a,{href:"../../language/logic#type-scopes",children:(0,o.jsx)(n.code,{children:"scope"})})," declaration, but you be careful with the handling of spaces in your shell.\nAny number of ",(0,o.jsx)(n.code,{children:"-s"})," arguments are supported. For example, the following argument lists are equivalent:"]}),"\n",(0,o.jsx)(n.pre,{children:(0,o.jsx)(n.code,{className:"language-shell",children:'-scope File=20..25,Directory=3\n-s File=20..25,Directory=3\n-s File=20..25 -s Directory=3\n-s "File = 20..25, Directory = 3"\n-s "File = 20..25" -s "Directory = 3"\n'})}),"\n",(0,o.jsxs)(n.p,{children:["The ",(0,o.jsx)(n.code,{children:"*"})," opeator also has to be quoted to avoid shell expansion:"]}),"\n",(0,o.jsx)(n.pre,{children:(0,o.jsx)(n.code,{className:"language-shell",children:'-s "File=20..*"\n'})}),"\n",(0,o.jsxs)(n.h3,{id:"generate-scope-override",children:[(0,o.jsx)(n.code,{children:"-scope-override"}),", ",(0,o.jsx)(n.code,{children:"-S"})]}),"\n",(0,o.jsxs)(n.p,{children:["Override ",(0,o.jsx)(n.a,{href:"../../language/logic#type-scopes",children:"scope constraints"})," to the input problem."]}),"\n",(0,o.jsxs)(n.p,{children:["This argument is similar to ",(0,o.jsx)(n.a,{href:"#generate-scope",children:(0,o.jsx)(n.code,{children:"-scope"})}),", but has higher precedence than the ",(0,o.jsx)(n.a,{href:"../../language/logic#type-scopes",children:(0,o.jsx)(n.code,{children:"scope"})})," declarations already present in the input file.\nHowever, you can\u2019t override ",(0,o.jsx)(n.code,{children:"scope"})," declarations in modules imported in the input file using the ",(0,o.jsx)(n.code,{children:"import"})," statement."]}),"\n",(0,o.jsx)(n.p,{children:"For example, if we have"}),"\n",(0,o.jsx)(n.pre,{children:(0,o.jsx)(n.code,{className:"language-refinery",metastring:'title="input.problem"',children:"scope File = 20..25, Directory = 3.\n"})}),"\n",(0,o.jsxs)(n.p,{children:["in the input file, the arguments ",(0,o.jsx)(n.code,{children:"-s File=10..12 input.problem"})," will be interpreted as"]}),"\n",(0,o.jsx)(n.pre,{children:(0,o.jsx)(n.code,{className:"language-refinery",children:"scope File = 20..25, Directory = 3.\nscope File = 10..12.\n"})}),"\n",(0,o.jsxs)(n.p,{children:["which results in an ",(0,o.jsx)(n.em,{children:"unsatisfiable"})," problem. If the use ",(0,o.jsx)(n.code,{children:"-S File=10..12 input.problem"})," instead, the type scope for ",(0,o.jsx)(n.code,{children:"File"})," is overridden as"]}),"\n",(0,o.jsx)(n.pre,{children:(0,o.jsx)(n.code,{className:"language-refinery",children:"scope Directory = 3.\nscope File = 10..12.\n"})}),"\n",(0,o.jsxs)(n.p,{children:["and model generation can proceed as requested. Since we had specified no override for ",(0,o.jsx)(n.code,{children:"Directory"}),", its type scope declared in ",(0,o.jsx)(n.code,{children:"input.problem"})," was preserved."]}),"\n",(0,o.jsxs)(n.p,{children:["Scope overrides do not override additional scopes specified with ",(0,o.jsx)(n.a,{href:"#generate-scope",children:(0,o.jsx)(n.code,{children:"-scope"})}),", i.e., ",(0,o.jsx)(n.code,{children:"-s File=20..30 -S File=10..25"}

1)," is interpreted as ",(0,o.jsx)(n.code,{children:"-S File=20..25"}),"."]}),"\n",(0,o.jsxs)(n.h3,{id:"generate-solution-number",children:[(0,o.jsx)(n.code,{children:"-solution-number"}),", ",(0,o.jsx)(n.code,{children:"-n"})]}),"\n",(0,o.jsx)(n.p,{children:"The number of distinct solutions to generate."}),"\n",(0,o.jsxs)(n.p,{children:["Generated solutions are always different, but are frequently not ",(0,o.jsx)(n.em,{children:"substantially"})," different, i.e., the differences between generated solutions comprise only a few model elements.\nYou\u2019ll likely generate substantially different models by calling the generator multiple times with different ",(0,o.jsx)(n.a,{href:"#generate-random-seed",children:(0,o.jsx)(n.code,{children:"-random-seed"})})," values instead."]}),"\n",(0,o.jsxs)(n.p,{children:["The generator will create ",(0,o.jsx)(n.a,{href:"#generate-output",children:"numbered output files"})," for each solution found.\nThe generation is considered successful if it finds at least one solution, but may find less than the requested number of solutions if no more exist.\nIn this case, there will be fewer output files than requested."]}),"\n",(0,o.jsxs)(n.p,{children:[(0,o.jsx)(n.strong,{children:"Default value:"})," ",(0,o.jsx)(n.code,{children:"1"})]}),"\n",(0,o.jsxs)(n.h2,{id:"check",children:["The ",(0,o.jsx)(n.code,{children:"check"})," subcommand"]}),"\n",(0,o.jsxs)(n.p,{children:["The ",(0,o.jsx)(n.code,{children:"check"})," subcommand checks a partial model for inconsistencies."]}),"\n",(0,o.jsxs)(n.ul,{children:["\n",(0,o.jsxs)(n.li,{children:["For ",(0,o.jsx)(n.strong,{children:"consistent"})," partial models, it has an exit value of ",(0,o.jsx)(n.code,{children:"0"}),"."]}),"\n",(0,o.jsxs)(n.li,{children:["For ",(0,o.jsx)(n.strong,{children:"inconsistent"})," partial models that contains ",(0,o.jsx)(n.code,{children:"error"})," logic values, it prints the occurrences of ",(0,o.jsx)(n.code,{children:"error"})," logic values to the standard output and sets the exit value to ",(0,o.jsx)(n.code,{children:"1"}),"."]}),"\n",(0,o.jsxs)(n.li,{children:["For partial models that can\u2019t be constructed due to ",(0,o.jsx)(n.strong,{children:"syntax or propagation errors"}),", it prints and error message to the standard output and sets the exit value to ",(0,o.jsx)(n.code,{children:"1"}),"."]}),"\n"]}),"\n",(0,o.jsx)(n.pre,{children:(0,o.jsx)(n.code,{className:"language-shell",children:"docker run --rm -it -v ${PWD}:/data ghcr.io/graphs4value/refinery-cli:0.3.0 check [options] input path\n"})}),"\n",(0,o.jsxs)(n.p,{children:["The ",(0,o.jsx)(n.code,{children:"input path"})," should be a path to a ",(0,o.jsx)(n.code,{children:".problem"})," or ",(0,o.jsx)(n.code,{children:".refinery"})," file relative to the current directory.\nDue to Docker containerization, paths ",(0,o.jsx)(n.em,{children:"outside"})," the current directory (e.g., ",(0,o.jsx)(n.code,{children:"../input.problem"}),") are not supported."]}),"\n",(0,o.jsxs)(n.p,{children:["Passing ",(0,o.jsx)(n.code,{children:"-"})," as the ",(0,o.jsx)(n.code,{children:"input path"})," will read a partial model from the standard input."]}),"\n",(0,o.jsxs)(n.h3,{id:"check-concretize",children:[(0,o.jsx)(n.code,{children:"-concretize"}),", ",(0,o.jsx)(n.code,{children:"-k"})]}),"\n",(0,o.jsxs)(n.p,{children:["If you provide this flag, the partial model will be concretized according to the behavior of the ",(0,o.jsxs)(n.a,{href:"#concretize",children:[(0,o.jsx)(n.code,{children:"concretize"})," subcommand"]})," before checking for inconsistencies.\nYou can use this flag to check whether a partial model can be concretized consistently without having to save the result somewhere."]}),"\n",(0,o.jsxs)(n.h2,{id:"concretize",children:["The ",(0,o.jsx)(n.code,{children:"concretize"})," subcommand"]}),"\n","\n",(0,o.jsxs)(n.p,{children:["The ",(0,o.jsx)(n.code,{children:"concretize"})," subcommand creates a concrete model by replacing ",(0,o.jsx)(n.code,{children:"unknown"})," aspects of a partial model with ",(0,o.jsx)(n.code,{children:"false"})," logic values.\nThe resulting concrete model is the same as the one shown in the ",(0,o.jsx)(s.A,{className:"inline-icon","aria-hidden":"true"})," ",(0,o.jsx)(n.strong,{children:"concrete"})," view in the ",(0,o.jsx)(n.a,{href:"/learn/tutorials/file-system/#refinery-web-ui",children:"Refinery web UI"}),"."]}),"\n",(0,o.jsxs)(n.p,{children:["This subcommand is only able to save ",(0,o.jsx)(n.em,{children:"consistent"})," concrete models.\nIf the result of the concretization is inconsistent, it shows an error with a form similar to the ",(0,o.jsx)(n.a,{href:"#check",children:(0,o.jsx)(n.code,{children:"check"})})," subcommand."]}),"\n",(0,o.jsx)(n.p,{children:"Scope constraints will likely render your partial model inconsistent after concretization if they prescribe multiple nodes to be created. You should the required nodes manually to the model or remove the scope constraints before concretization."}),"\n",(0,o.jsx)(n.pre,{children:(0,o.jsx)(n.code,{className:"language-shell",children:"docker run --rm -it -v ${PWD}:/data ghcr.io/graphs4value/refinery-cli:0.3.0 concretize [options] input path\n"})}),"\n",(0,o.jsxs)(n.p,{children:["The ",(0,o.jsx)(n.code,{children:"input path"})," should be a path to a ",(0,o.jsx)(n.code,{children:".problem"})," or ",(0,o.jsx)(n.code,{children:".refinery"})," file relative to the current directory.\nDue to Docker containerization, paths ",(0,o.jsx)(n.em,{children:"outside"})," the current directory (e.g., ",(0,o.jsx)(n.code,{children:"../in

1put.problem"}),") are not supported."]}),"\n",(0,o.jsxs)(n.p,{children:["Passing ",(0,o.jsx)(n.code,{children:"-"})," as the ",(0,o.jsx)(n.code,{children:"input path"})," will read a partial model from the standard input."]}),"\n",(0,o.jsxs)(n.p,{children:["See below for the list of supported ",(0,o.jsx)(n.code,{children:"[options]"}),"."]}),"\n",(0,o.jsxs)(n.h3,{id:"concretize-output",children:[(0,o.jsx)(n.code,{children:"-output"}),", ",(0,o.jsx)(n.code,{children:"-o"})]}),"\n",(0,o.jsxs)(n.p,{children:["The output path for the concretized model, usually a file with the ",(0,o.jsx)(n.code,{children:".refinery"})," extension.\nPassing ",(0,o.jsx)(n.code,{children:"-o -"})," will write the concretized model to the standard output."]}),"\n",(0,o.jsxs)(n.p,{children:[(0,o.jsx)(n.strong,{children:"Default value:"})," ",(0,o.jsx)(n.code,{children:"-"}),", i.e., the model is written to the standard output."]})]})}function u(e={}){let{wrapper:n}={...(0,t.R)(),...e.components};return n?(0,o.jsx)(n,{...e,children:(0,o.jsx)(h,{...e})}):h(e)}},6559(e,n,r){r.d(n,{A:()=>c});var i,o=r(4041),t=["title","titleId"];function s(){return(s=Object.assign?Object.assign.bind():function(e){for(var n=1;n<arguments.length;n++){var r=arguments[n];for(var i in r)({}).hasOwnProperty.call(r,i)&&(e[i]=r[i])}return e}).apply(null,arguments)}let c=function(e){var n=e.title,r=e.titleId,c=function(e,n){if(null==e)return{};var r,i,o=function(e,n){if(null==e)return{};var r={};for(var i in e)if(({}).hasOwnProperty.call(e,i)){if(-1!==n.indexOf(i))continue;r[i]=e[i]}return r}(e,n);if(Object.getOwnPropertySymbols){var t=Object.getOwnPropertySymbols(e);for(i=0;i<t.length;i++)r=t[i],-1===n.indexOf(r)&&({}).propertyIsEnumerable.call(e,r)&&(o[r]=e[r])}return o}(e,t);return o.createElement("svg",s({xmlns:"http://www.w3.org/2000/svg",width:24,height:24,viewBox:"0 0 24 24","aria-labelledby":r},c),n?o.createElement("title",{id:r},n):null,i||(i=o.createElement("path",{d:"M18 8h-1V6c0-2.76-2.24-5-5-5S7 3.24 7 6v2H6c-1.1 0-2 .9-2 2v10c0 1.1.9 2 2 2h12c1.1 0 2-.9 2-2V10c0-1.1-.9-2-2-2m-6 9c-1.1 0-2-.9-2-2s.9-2 2-2 2 .9 2 2-.9 2-2 2m3.1-9H8.9V6c0-1.71 1.39-3.1 3.1-3.1s3.1 1.39 3.1 3.1z"})))}},1184(e,n,r){r.d(n,{R:()=>s,x:()=>c});var i=r(4041);let o={},t=i.createContext(o);function s(e){let n=i.useContext(t);return i.useMemo(function(){return"function"==typeof e?e(n):{...n,...e}},[n,e])}function c(e){let n;return n=e.disableParentContext?"function"==typeof e.components?e.components(o):e.components||o:s(e.components),i.createElement(t.Provider,{value:n},e.children)}}}]);
2//# sourceMappingURL=4b2ba393.e0100501.js.map