README.html

<!DOCTYPE html><html><head><meta charset="utf-8"><meta name="viewport" content="width=device-width, initial-scale=1"><style>body {
  max-width: 980px;
  border: 1px solid #ddd;
  outline: 1300px solid #fff;
  margin: 16px auto;
}

body .markdown-body
{
  padding: 45px;
}

@font-face {
  font-family: fontawesome-mini;
  src: url(data:font/woff;charset=utf-8;base64,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) format('woff');
}

.markdown-body {
  font-family: sans-serif;
  -ms-text-size-adjust: 100%;
  -webkit-text-size-adjust: 100%;
  color: #333333;
  overflow: hidden;
  font-family: "Helvetica Neue", Helvetica, "Segoe UI", Arial, freesans, sans-serif;
  font-size: 16px;
  line-height: 1.6;
  word-wrap: break-word;
}

.markdown-body a {
  background: transparent;
}

.markdown-body a:active,
.markdown-body a:hover {
  outline: 0;
}

.markdown-body b,
.markdown-body strong {
  font-weight: bold;
}

.markdown-body mark {
  background: #ff0;
  color: #000;
  font-style: italic;
  font-weight: bold;
}

.markdown-body sub,
.markdown-body sup {
  font-size: 75%;
  line-height: 0;
  position: relative;
  vertical-align: baseline;
}
.markdown-body sup {
  top: -0.5em;
}
.markdown-body sub {
  bottom: -0.25em;
}

.markdown-body h1 {
  font-size: 2em;
  margin: 0.67em 0;
}

.markdown-body img {
  border: 0;
}

.markdown-body hr {
  -moz-box-sizing: content-box;
  box-sizing: content-box;
  height: 0;
}

.markdown-body pre {
  overflow: auto;
}

.markdown-body code,
.markdown-body kbd,
.markdown-body pre,
.markdown-body samp {
  font-family: monospace, monospace;
  font-size: 1em;
}

.markdown-body input {
  color: inherit;
  font: inherit;
  margin: 0;
}

.markdown-body html input[disabled] {
  cursor: default;
}

.markdown-body input {
  line-height: normal;
}

.markdown-body input[type="checkbox"] {
  box-sizing: border-box;
  padding: 0;
}

.markdown-body table {
  border-collapse: collapse;
  border-spacing: 0;
}

.markdown-body td,
.markdown-body th {
  padding: 0;
}

.markdown-body .codehilitetable {
  border: 0;
  border-spacing: 0;
}

.markdown-body .codehilitetable tr {
  border: 0;
}

.markdown-body .codehilitetable pre,
.markdown-body .codehilitetable div.codehilite {
  margin: 0;
}

.markdown-body .linenos,
.markdown-body .code,
.markdown-body .codehilitetable td {
  border: 0;
  padding: 0;
}

.markdown-body td:not(.linenos) .linenodiv {
  padding: 0 !important;
}

.markdown-body .code {
  width: 100%;
}

.markdown-body .linenos div pre,
.markdown-body .linenodiv pre,
.markdown-body .linenodiv {
  border: 0;
  -webkit-border-radius: 0;
  -moz-border-radius: 0;
  border-radius: 0;
  -webkit-border-top-left-radius: 3px;
  -webkit-border-bottom-left-radius: 3px;
  -moz-border-radius-topleft: 3px;
  -moz-border-radius-bottomleft: 3px;
  border-top-left-radius: 3px;
  border-bottom-left-radius: 3px;
}

.markdown-body .code div pre,
.markdown-body .code div {
  border: 0;
  -webkit-border-radius: 0;
  -moz-border-radius: 0;
  border-radius: 0;
  -webkit-border-top-right-radius: 3px;
  -webkit-border-bottom-right-radius: 3px;
  -moz-border-radius-topright: 3px;
  -moz-border-radius-bottomright: 3px;
  border-top-right-radius: 3px;
  border-bottom-right-radius: 3px;
}

.markdown-body * {
  -moz-box-sizing: border-box;
  box-sizing: border-box;
}

.markdown-body input {
  font: 13px Helvetica, arial, freesans, clean, sans-serif, "Segoe UI Emoji", "Segoe UI Symbol";
  line-height: 1.4;
}

.markdown-body a {
  color: #4183c4;
  text-decoration: none;
}

.markdown-body a:hover,
.markdown-body a:focus,
.markdown-body a:active {
  text-decoration: underline;
}

.markdown-body hr {
  height: 0;
  margin: 15px 0;
  overflow: hidden;
  background: transparent;
  border: 0;
  border-bottom: 1px solid #ddd;
}

.markdown-body hr:before,
.markdown-body hr:after {
  display: table;
  content: " ";
}

.markdown-body hr:after {
  clear: both;
}

.markdown-body h1,
.markdown-body h2,
.markdown-body h3,
.markdown-body h4,
.markdown-body h5,
.markdown-body h6 {
  margin-top: 15px;
  margin-bottom: 15px;
  line-height: 1.1;
}

.markdown-body h1 {
  font-size: 30px;
}

.markdown-body h2 {
  font-size: 21px;
}

.markdown-body h3 {
  font-size: 16px;
}

.markdown-body h4 {
  font-size: 14px;
}

.markdown-body h5 {
  font-size: 12px;
}

.markdown-body h6 {
  font-size: 11px;
}

.markdown-body blockquote {
  margin: 0;
}

.markdown-body ul,
.markdown-body ol {
  padding: 0;
  margin-top: 0;
  margin-bottom: 0;
}

.markdown-body ol ol,
.markdown-body ul ol {
  list-style-type: lower-roman;
}

.markdown-body ul ul ol,
.markdown-body ul ol ol,
.markdown-body ol ul ol,
.markdown-body ol ol ol {
  list-style-type: lower-alpha;
}

.markdown-body dd {
  margin-left: 0;
}

.markdown-body code,
.markdown-body pre,
.markdown-body samp {
  font-family: Consolas, "Liberation Mono", Menlo, Courier, monospace;
  font-size: 12px;
}

.markdown-body pre {
  margin-top: 0;
  margin-bottom: 0;
}

.markdown-body kbd {
  background-color: #e7e7e7;
  background-image: -moz-linear-gradient(#fefefe, #e7e7e7);
  background-image: -webkit-linear-gradient(#fefefe, #e7e7e7);
  background-image: linear-gradient(#fefefe, #e7e7e7);
  background-repeat: repeat-x;
  border-radius: 2px;
  border: 1px solid #cfcfcf;
  color: #000;
  padding: 3px 5px;
  line-height: 10px;
  font: 11px Consolas, "Liberation Mono", Menlo, Courier, monospace;
  display: inline-block;
}

.markdown-body>*:first-child {
  margin-top: 0 !important;
}

.markdown-body>*:last-child {
  margin-bottom: 0 !important;
}

.markdown-body .headerlink {
  font: normal 400 16px fontawesome-mini;
  vertical-align: middle;
  margin-left: -16px;
  float: left;
  display: inline-block;
  text-decoration: none;
  opacity: 0;
  color: #333;
}

.markdown-body .headerlink:focus {
  outline: none;
}

.markdown-body h1 .headerlink {
  margin-top: 0.8rem;
}

.markdown-body h2 .headerlink,
.markdown-body h3 .headerlink {
  margin-top: 0.6rem;
}

.markdown-body h4 .headerlink {
  margin-top: 0.2rem;
}

.markdown-body h5 .headerlink,
.markdown-body h6 .headerlink {
  margin-top: 0;
}

.markdown-body .headerlink:hover,
.markdown-body h1:hover .headerlink,
.markdown-body h2:hover .headerlink,
.markdown-body h3:hover .headerlink,
.markdown-body h4:hover .headerlink,
.markdown-body h5:hover .headerlink,
.markdown-body h6:hover .headerlink {
  opacity: 1;
  text-decoration: none;
}

.markdown-body h1 {
  padding-bottom: 0.3em;
  font-size: 2.25em;
  line-height: 1.2;
  border-bottom: 1px solid #eee;
}

.markdown-body h2 {
  padding-bottom: 0.3em;
  font-size: 1.75em;
  line-height: 1.225;
  border-bottom: 1px solid #eee;
}

.markdown-body h3 {
  font-size: 1.5em;
  line-height: 1.43;
}

.markdown-body h4 {
  font-size: 1.25em;
}

.markdown-body h5 {
  font-size: 1em;
}

.markdown-body h6 {
  font-size: 1em;
  color: #777;
}

.markdown-body p,
.markdown-body blockquote,
.markdown-body ul,
.markdown-body ol,
.markdown-body dl,
.markdown-body table,
.markdown-body pre,
.markdown-body .admonition {
  margin-top: 0;
  margin-bottom: 16px;
}

.markdown-body hr {
  height: 4px;
  padding: 0;
  margin: 16px 0;
  background-color: #e7e7e7;
  border: 0 none;
}

.markdown-body ul,
.markdown-body ol {
  padding-left: 2em;
}

.markdown-body ul ul,
.markdown-body ul ol,
.markdown-body ol ol,
.markdown-body ol ul {
  margin-top: 0;
  margin-bottom: 0;
}

.markdown-body li>p {
  margin-top: 16px;
}

.markdown-body dl {
  padding: 0;
}

.markdown-body dl dt {
  padding: 0;
  margin-top: 16px;
  font-size: 1em;
  font-style: italic;
  font-weight: bold;
}

.markdown-body dl dd {
  padding: 0 16px;
  margin-bottom: 16px;
}

.markdown-body blockquote {
  padding: 0 15px;
  color: #777;
  border-left: 4px solid #ddd;
}

.markdown-body blockquote>:first-child {
  margin-top: 0;
}

.markdown-body blockquote>:last-child {
  margin-bottom: 0;
}

.markdown-body table {
  display: block;
  width: 100%;
  overflow: auto;
  word-break: normal;
  word-break: keep-all;
}

.markdown-body table th {
  font-weight: bold;
}

.markdown-body table th,
.markdown-body table td {
  padding: 6px 13px;
  border: 1px solid #ddd;
}

.markdown-body table tr {
  background-color: #fff;
  border-top: 1px solid #ccc;
}

.markdown-body table tr:nth-child(2n) {
  background-color: #f8f8f8;
}

.markdown-body img {
  max-width: 100%;
  -moz-box-sizing: border-box;
  box-sizing: border-box;
}

.markdown-body code,
.markdown-body samp {
  padding: 0;
  padding-top: 0.2em;
  padding-bottom: 0.2em;
  margin: 0;
  font-size: 85%;
  background-color: rgba(0,0,0,0.04);
  border-radius: 3px;
}

.markdown-body code:before,
.markdown-body code:after {
  letter-spacing: -0.2em;
  content: "\00a0";
}

.markdown-body pre>code {
  padding: 0;
  margin: 0;
  font-size: 100%;
  word-break: normal;
  white-space: pre;
  background: transparent;
  border: 0;
}

.markdown-body .codehilite {
  margin-bottom: 16px;
}

.markdown-body .codehilite pre,
.markdown-body pre {
  padding: 16px;
  overflow: auto;
  font-size: 85%;
  line-height: 1.45;
  background-color: #f7f7f7;
  border-radius: 3px;
}

.markdown-body .codehilite pre {
  margin-bottom: 0;
  word-break: normal;
}

.markdown-body pre {
  word-wrap: normal;
}

.markdown-body pre code {
  display: inline;
  max-width: initial;
  padding: 0;
  margin: 0;
  overflow: initial;
  line-height: inherit;
  word-wrap: normal;
  background-color: transparent;
  border: 0;
}

.markdown-body pre code:before,
.markdown-body pre code:after {
  content: normal;
}

/* Admonition */
.markdown-body .admonition {
  -webkit-border-radius: 3px;
  -moz-border-radius: 3px;
  position: relative;
  border-radius: 3px;
  border: 1px solid #e0e0e0;
  border-left: 6px solid #333;
  padding: 10px 10px 10px 30px;
}

.markdown-body .admonition table {
  color: #333;
}

.markdown-body .admonition p {
  padding: 0;
}

.markdown-body .admonition-title {
  font-weight: bold;
  margin: 0;
}

.markdown-body .admonition>.admonition-title {
  color: #333;
}

.markdown-body .attention>.admonition-title {
  color: #a6d796;
}

.markdown-body .caution>.admonition-title {
  color: #d7a796;
}

.markdown-body .hint>.admonition-title {
  color: #96c6d7;
}

.markdown-body .danger>.admonition-title {
  color: #c25f77;
}

.markdown-body .question>.admonition-title {
  color: #96a6d7;
}

.markdown-body .note>.admonition-title {
  color: #d7c896;
}

.markdown-body .admonition:before,
.markdown-body .attention:before,
.markdown-body .caution:before,
.markdown-body .hint:before,
.markdown-body .danger:before,
.markdown-body .question:before,
.markdown-body .note:before {
  font: normal normal 16px fontawesome-mini;
  -moz-osx-font-smoothing: grayscale;
  -webkit-user-select: none;
  -moz-user-select: none;
  -ms-user-select: none;
  user-select: none;
  line-height: 1.5;
  color: #333;
  position: absolute;
  left: 0;
  top: 0;
  padding-top: 10px;
  padding-left: 10px;
}

.markdown-body .admonition:before {
  content: "\f056\00a0";
  color: 333;
}

.markdown-body .attention:before {
  content: "\f058\00a0";
  color: #a6d796;
}

.markdown-body .caution:before {
  content: "\f06a\00a0";
  color: #d7a796;
}

.markdown-body .hint:before {
  content: "\f05a\00a0";
  color: #96c6d7;
}

.markdown-body .danger:before {
  content: "\f057\00a0";
  color: #c25f77;
}

.markdown-body .question:before {
  content: "\f059\00a0";
  color: #96a6d7;
}

.markdown-body .note:before {
  content: "\f040\00a0";
  color: #d7c896;
}

.markdown-body .admonition::after {
  content: normal;
}

.markdown-body .attention {
  border-left: 6px solid #a6d796;
}

.markdown-body .caution {
  border-left: 6px solid #d7a796;
}

.markdown-body .hint {
  border-left: 6px solid #96c6d7;
}

.markdown-body .danger {
  border-left: 6px solid #c25f77;
}

.markdown-body .question {
  border-left: 6px solid #96a6d7;
}

.markdown-body .note {
  border-left: 6px solid #d7c896;
}

.markdown-body .admonition>*:first-child {
  margin-top: 0 !important;
}

.markdown-body .admonition>*:last-child {
  margin-bottom: 0 !important;
}

/* progress bar*/
.markdown-body .progress {
  display: block;
  width: 300px;
  margin: 10px 0;
  height: 24px;
  -webkit-border-radius: 3px;
  -moz-border-radius: 3px;
  border-radius: 3px;
  background-color: #ededed;
  position: relative;
  box-shadow: inset -1px 1px 3px rgba(0, 0, 0, .1);
}

.markdown-body .progress-label {
  position: absolute;
  text-align: center;
  font-weight: bold;
  width: 100%; margin: 0;
  line-height: 24px;
  color: #333;
  text-shadow: 1px 1px 0 #fefefe, -1px -1px 0 #fefefe, -1px 1px 0 #fefefe, 1px -1px 0 #fefefe, 0 1px 0 #fefefe, 0 -1px 0 #fefefe, 1px 0 0 #fefefe, -1px 0 0 #fefefe, 1px 1px 2px #000;
  -webkit-font-smoothing: antialiased !important;
  white-space: nowrap;
  overflow: hidden;
}

.markdown-body .progress-bar {
  height: 24px;
  float: left;
  -webkit-border-radius: 3px;
  -moz-border-radius: 3px;
  border-radius: 3px;
  background-color: #96c6d7;
  box-shadow: inset 0 1px 0 rgba(255, 255, 255, .5), inset 0 -1px 0 rgba(0, 0, 0, .1);
  background-size: 30px 30px;
  background-image: -webkit-linear-gradient(
    135deg, rgba(255, 255, 255, .4) 27%,
    transparent 27%,
    transparent 52%, rgba(255, 255, 255, .4) 52%,
    rgba(255, 255, 255, .4) 77%,
    transparent 77%, transparent
  );
  background-image: -moz-linear-gradient(
    135deg,
    rgba(255, 255, 255, .4) 27%, transparent 27%,
    transparent 52%, rgba(255, 255, 255, .4) 52%,
    rgba(255, 255, 255, .4) 77%, transparent 77%,
    transparent
  );
  background-image: -ms-linear-gradient(
    135deg,
    rgba(255, 255, 255, .4) 27%, transparent 27%,
    transparent 52%, rgba(255, 255, 255, .4) 52%,
    rgba(255, 255, 255, .4) 77%, transparent 77%,
    transparent
  );
  background-image: -o-linear-gradient(
    135deg,
    rgba(255, 255, 255, .4) 27%, transparent 27%,
    transparent 52%, rgba(255, 255, 255, .4) 52%,
    rgba(255, 255, 255, .4) 77%, transparent 77%,
    transparent
  );
  background-image: linear-gradient(
    135deg,
    rgba(255, 255, 255, .4) 27%, transparent 27%,
    transparent 52%, rgba(255, 255, 255, .4) 52%,
    rgba(255, 255, 255, .4) 77%, transparent 77%,
    transparent
  );
}

.markdown-body .progress-100plus .progress-bar {
  background-color: #a6d796;
}

.markdown-body .progress-80plus .progress-bar {
  background-color: #c6d796;
}

.markdown-body .progress-60plus .progress-bar {
  background-color: #d7c896;
}

.markdown-body .progress-40plus .progress-bar {
  background-color: #d7a796;
}

.markdown-body .progress-20plus .progress-bar {
  background-color: #d796a6;
}

.markdown-body .progress-0plus .progress-bar {
  background-color: #c25f77;
}

.markdown-body .candystripe-animate .progress-bar{
  -webkit-animation: animate-stripes 3s linear infinite;
  -moz-animation: animate-stripes 3s linear infinite;
  animation: animate-stripes 3s linear infinite;
}

@-webkit-keyframes animate-stripes {
  0% {
    background-position: 0 0;
  }

  100% {
    background-position: 60px 0;
  }
}

@-moz-keyframes animate-stripes {
  0% {
    background-position: 0 0;
  }

  100% {
    background-position: 60px 0;
  }
}

@keyframes animate-stripes {
  0% {
    background-position: 0 0;
  }

  100% {
    background-position: 60px 0;
  }
}

.markdown-body .gloss .progress-bar {
  box-shadow:
    inset 0 4px 12px rgba(255, 255, 255, .7),
    inset 0 -12px 0 rgba(0, 0, 0, .05);
}

/* MultiMarkdown Critic Blocks */
.markdown-body .critic_mark {
  background: #ff0;
}

.markdown-body .critic_delete {
  color: #c82829;
  text-decoration: line-through;
}

.markdown-body .critic_insert {
  color: #718c00 ;
  text-decoration: underline;
}

.markdown-body .critic_comment {
  color: #8e908c;
  font-style: italic;
}

.markdown-body .headeranchor {
  font: normal normal 16px fontawesome-mini;
  line-height: 1;
  display: inline-block;
  text-decoration: none;
  -webkit-font-smoothing: antialiased;
  -moz-osx-font-smoothing: grayscale;
  -webkit-user-select: none;
  -moz-user-select: none;
  -ms-user-select: none;
  user-select: none;
}

.headeranchor:before {
  content: '\e157';
}

.markdown-body .task-list-item {
  list-style-type: none;
}

.markdown-body .task-list-item+.task-list-item {
  margin-top: 3px;
}

.markdown-body .task-list-item input {
  margin: 0 4px 0.25em -20px;
  vertical-align: middle;
}

/* Media */
@media only screen and (min-width: 480px) {
  .markdown-body {
    font-size:14px;
  }
}

@media only screen and (min-width: 768px) {
  .markdown-body {
    font-size:16px;
  }
}

@media print {
  .markdown-body * {
    background: transparent !important;
    color: black !important;
    filter:none !important;
    -ms-filter: none !important;
  }

  .markdown-body {
    font-size:12pt;
    max-width:100%;
    outline:none;
    border: 0;
  }

  .markdown-body a,
  .markdown-body a:visited {
    text-decoration: underline;
  }

  .markdown-body .headeranchor-link {
    display: none;
  }

  .markdown-body a[href]:after {
    content: " (" attr(href) ")";
  }

  .markdown-body abbr[title]:after {
    content: " (" attr(title) ")";
  }

  .markdown-body .ir a:after,
  .markdown-body a[href^="javascript:"]:after,
  .markdown-body a[href^="#"]:after {
    content: "";
  }

  .markdown-body pre {
    white-space: pre;
    white-space: pre-wrap;
    word-wrap: break-word;
  }

  .markdown-body pre,
  .markdown-body blockquote {
    border: 1px solid #999;
    padding-right: 1em;
    page-break-inside: avoid;
  }

  .markdown-body .progress,
  .markdown-body .progress-bar {
    -moz-box-shadow: none;
    -webkit-box-shadow: none;
    box-shadow: none;
  }

  .markdown-body .progress {
    border: 1px solid #ddd;
  }

  .markdown-body .progress-bar {
    height: 22px;
    border-right: 1px solid #ddd;
  }

  .markdown-body tr,
  .markdown-body img {
    page-break-inside: avoid;
  }

  .markdown-body img {
    max-width: 100% !important;
  }

  .markdown-body p,
  .markdown-body h2,
  .markdown-body h3 {
    orphans: 3;
    widows: 3;
  }

  .markdown-body h2,
  .markdown-body h3 {
    page-break-after: avoid;
  }
}
</style><style>/*GitHub*/
.codehilite {background-color:#fff;color:#333333;}
.codehilite .hll {background-color:#ffffcc;}
.codehilite .c{color:#999988;font-style:italic}
.codehilite .err{color:#a61717;background-color:#e3d2d2}
.codehilite .k{font-weight:bold}
.codehilite .o{font-weight:bold}
.codehilite .cm{color:#999988;font-style:italic}
.codehilite .cp{color:#999999;font-weight:bold}
.codehilite .c1{color:#999988;font-style:italic}
.codehilite .cs{color:#999999;font-weight:bold;font-style:italic}
.codehilite .gd{color:#000000;background-color:#ffdddd}
.codehilite .ge{font-style:italic}
.codehilite .gr{color:#aa0000}
.codehilite .gh{color:#999999}
.codehilite .gi{color:#000000;background-color:#ddffdd}
.codehilite .go{color:#888888}
.codehilite .gp{color:#555555}
.codehilite .gs{font-weight:bold}
.codehilite .gu{color:#800080;font-weight:bold}
.codehilite .gt{color:#aa0000}
.codehilite .kc{font-weight:bold}
.codehilite .kd{font-weight:bold}
.codehilite .kn{font-weight:bold}
.codehilite .kp{font-weight:bold}
.codehilite .kr{font-weight:bold}
.codehilite .kt{color:#445588;font-weight:bold}
.codehilite .m{color:#009999}
.codehilite .s{color:#dd1144}
.codehilite .n{color:#333333}
.codehilite .na{color:teal}
.codehilite .nb{color:#0086b3}
.codehilite .nc{color:#445588;font-weight:bold}
.codehilite .no{color:teal}
.codehilite .ni{color:purple}
.codehilite .ne{color:#990000;font-weight:bold}
.codehilite .nf{color:#990000;font-weight:bold}
.codehilite .nn{color:#555555}
.codehilite .nt{color:navy}
.codehilite .nv{color:teal}
.codehilite .ow{font-weight:bold}
.codehilite .w{color:#bbbbbb}
.codehilite .mf{color:#009999}
.codehilite .mh{color:#009999}
.codehilite .mi{color:#009999}
.codehilite .mo{color:#009999}
.codehilite .sb{color:#dd1144}
.codehilite .sc{color:#dd1144}
.codehilite .sd{color:#dd1144}
.codehilite .s2{color:#dd1144}
.codehilite .se{color:#dd1144}
.codehilite .sh{color:#dd1144}
.codehilite .si{color:#dd1144}
.codehilite .sx{color:#dd1144}
.codehilite .sr{color:#009926}
.codehilite .s1{color:#dd1144}
.codehilite .ss{color:#990073}
.codehilite .bp{color:#999999}
.codehilite .vc{color:teal}
.codehilite .vg{color:teal}
.codehilite .vi{color:teal}
.codehilite .il{color:#009999}
.codehilite .gc{color:#999;background-color:#EAF2F5}
</style><title>README</title></head><body><article class="markdown-body"><h1 id="pygpu-a-very-simple-interface-for-calling-gpu">PyGPU: A very simple interface for calling GPU<a class="headerlink" href="#pygpu-a-very-simple-interface-for-calling-gpu" title="Permanent link"></a></h1>
<h2 id="1-preview">1. Preview<a class="headerlink" href="#1-preview" title="Permanent link"></a></h2>
<h3 id="11-sum-two-arrays">1.1 Sum two arrays<a class="headerlink" href="#11-sum-two-arrays" title="Permanent link"></a></h3>
<p>If you want to sum two arrays with GPU, write code just like this:<br />
in <em>main.py</em>:
<div class="codehilite"><pre><span class="c1"># main.py</span>
<span class="kn">from</span> <span class="nn">pygpu</span> <span class="kn">import</span> <span class="o">*</span>
<span class="kn">import</span> <span class="nn">numpy</span> <span class="kn">as</span> <span class="nn">np</span>

<span class="n">n</span> <span class="o">=</span> <span class="mi">1000000</span>
<span class="n">a</span> <span class="o">=</span> <span class="n">np</span><span class="o">.</span><span class="n">random</span><span class="o">.</span><span class="n">rand</span><span class="p">(</span><span class="n">n</span><span class="p">)</span>
<span class="n">b</span> <span class="o">=</span> <span class="n">np</span><span class="o">.</span><span class="n">random</span><span class="o">.</span><span class="n">rand</span><span class="p">(</span><span class="n">n</span><span class="p">)</span>

<span class="n">gpu</span> <span class="o">=</span> <span class="n">GPU</span><span class="p">()</span>
<span class="n">gpu</span><span class="o">.</span><span class="n">set_program</span><span class="p">(</span><span class="s">&quot;sum.cl&quot;</span><span class="p">,</span> <span class="s">&quot;sum&quot;</span><span class="p">)</span>
<span class="n">gpu</span><span class="o">.</span><span class="n">set_return</span><span class="p">(</span><span class="n">a</span><span class="p">)</span>
<span class="c1"># tell him the return value&#39;s shape is just like a</span>

<span class="n">result</span> <span class="o">=</span> <span class="n">gpu</span><span class="p">(</span><span class="n">a</span><span class="p">,</span> <span class="n">b</span><span class="p">)</span>
</pre></div>
in <em>sum.cl</em>:
<div class="codehilite"><pre><span class="c1">// sum.cl</span>
<span class="n">__kernel</span> <span class="kt">void</span> <span class="nf">sum</span><span class="p">(</span><span class="n">__global</span> <span class="kt">float</span><span class="o">*</span> <span class="n">result</span><span class="p">,</span>
                  <span class="n">__global</span> <span class="kt">float</span><span class="o">*</span> <span class="n">a</span><span class="p">,</span>
                  <span class="n">__global</span> <span class="kt">float</span><span class="o">*</span> <span class="n">b</span><span class="p">)</span>
<span class="p">{</span>
    <span class="kt">int</span> <span class="n">i</span> <span class="o">=</span> <span class="n">get_global_id</span><span class="p">(</span><span class="mi">0</span><span class="p">);</span>
    <span class="n">result</span><span class="p">[</span><span class="n">i</span><span class="p">]</span> <span class="o">=</span> <span class="n">a</span><span class="p">[</span><span class="n">i</span><span class="p">]</span> <span class="o">+</span> <span class="n">b</span><span class="p">[</span><span class="n">i</span><span class="p">];</span>
<span class="p">}</span>
</pre></div></p>
<h3 id="12-convert-colored-image-into-gray">1.2 Convert Colored Image into Gray<a class="headerlink" href="#12-convert-colored-image-into-gray" title="Permanent link"></a></h3>
<p>If you want to convert a colored image into gray mode with GPU, write code just like this:<br />
in <em>main.py</em>:
<div class="codehilite"><pre><span class="c1"># main.py</span>
<span class="kn">from</span> <span class="nn">pygpu</span> <span class="kn">import</span> <span class="o">*</span>
<span class="kn">import</span> <span class="nn">numpy</span> <span class="kn">as</span> <span class="nn">np</span>
<span class="kn">import</span> <span class="nn">cv2</span>

<span class="n">image_bgr</span> <span class="o">=</span> <span class="n">cv2</span><span class="o">.</span><span class="n">imread</span><span class="p">(</span><span class="s">&quot;1.jpg&quot;</span><span class="p">)</span>

<span class="n">gpu</span> <span class="o">=</span> <span class="n">GPU</span><span class="p">()</span>
<span class="n">gpu</span><span class="o">.</span><span class="n">set_program</span><span class="p">(</span><span class="s">&quot;bgr2gray.cl&quot;</span><span class="p">,</span> <span class="s">&quot;bgr2gray&quot;</span><span class="p">)</span>
<span class="n">gpu</span><span class="o">.</span><span class="n">set_return</span><span class="p">(</span><span class="n">image_bgr</span><span class="p">[:,</span> <span class="p">:,</span> <span class="mi">0</span><span class="p">])</span>
<span class="c1"># tell him the return value&#39;s shape is just like the first channel of input image</span>
<span class="c1"># because the output image will be a gray image and has only one channel</span>

<span class="n">image_gray</span> <span class="o">=</span> <span class="n">gpu</span><span class="p">(</span><span class="n">image_bgr</span><span class="p">)</span>
</pre></div>
in <em>bgr2gray.cl</em>:
<div class="codehilite"><pre><span class="c1">// bgr2gray.cl</span>
<span class="n">__kernel</span> <span class="kt">void</span> <span class="nf">bgr2gray</span><span class="p">(</span><span class="n">__global</span> <span class="n">uchar</span><span class="o">*</span>  <span class="n">image_gray</span><span class="p">,</span>
                       <span class="n">__global</span> <span class="n">uchar3</span><span class="o">*</span> <span class="n">image_bgr</span><span class="p">)</span>
<span class="p">{</span>
    <span class="kt">int</span> <span class="n">i</span> <span class="o">=</span> <span class="n">get_global_id</span><span class="p">(</span><span class="mi">0</span><span class="p">);</span>
    <span class="n">image_gray</span><span class="p">[</span><span class="n">i</span><span class="p">]</span> <span class="o">=</span> <span class="p">(</span><span class="n">uchar</span><span class="p">)(</span><span class="mf">0.11</span> <span class="o">*</span> <span class="n">image_bgr</span><span class="p">[</span><span class="n">i</span><span class="p">].</span><span class="n">x</span> <span class="o">+</span> 
                            <span class="mf">0.59</span> <span class="o">*</span> <span class="n">image_bgr</span><span class="p">[</span><span class="n">i</span><span class="p">].</span><span class="n">y</span> <span class="o">+</span>
                            <span class="mf">0.3</span>  <span class="o">*</span> <span class="n">image_bgr</span><span class="p">[</span><span class="n">i</span><span class="p">].</span><span class="n">z</span><span class="p">);</span>
<span class="p">}</span>
</pre></div>
Easy enough, isn&rsquo;t it?</p>
<h2 id="2-installing">2. Installing<a class="headerlink" href="#2-installing" title="Permanent link"></a></h2>
<h3 id="21-installing-numpy-and-opencv-python">2.1 Installing Numpy and OpenCV-Python<a class="headerlink" href="#21-installing-numpy-and-opencv-python" title="Permanent link"></a></h3>
<p>Just use the following command:
<div class="codehilite"><pre>pip install numpy
pip install opencv-python
</pre></div></p>
<h3 id="22-installing-pyopencl">2.2 Installing PyOpenCL<a class="headerlink" href="#22-installing-pyopencl" title="Permanent link"></a></h3>
<ol>
<li>
<p>Update OpenCL driver:   </p>
<ul>
<li>
<p>For Intel graphics card, go to website <a href="https://software.intel.com/en-us/articles/opencl-drivers#win64">OpenCL™ Runtimes for Intel® Processors</a>, download the correct driver for your operating system then install it.</p>
</li>
<li>
<p>For Nvidia graphics card, go to website <a href="https://www.nvidia.com/Download/index.aspx?lang=en-us">NVIDIA Driver Downloads</a>, download the correct driver for your operating system then install it.</p>
</li>
<li>
<p>For AMD graphics card, go to website <a href="https://www.amd.com/en/support/kb/faq/ccc-install">Installing The AMD Catalyst Software Driver</a>, follow the guide in the website and finish your installation.</p>
</li>
</ul>
</li>
<li>
<p>Install PyOpenCL from prebuild binary:</p>
<ol>
<li>
<p>Go to website <a href="https://www.lfd.uci.edu/~gohlke/pythonlibs/#pyopencl">PyOpenCL prebuild binary</a>, download the correct version for your operating system.</p>
</li>
<li>
<p>Use command <code>pip install &lt;the file name you've just download&gt;</code> to install PyOpenCL</p>
</li>
</ol>
</li>
</ol>
<h3 id="23-installing-pygpu">2.3 Installing PyGPU:<a class="headerlink" href="#23-installing-pygpu" title="Permanent link"></a></h3>
<ul>
<li>
<p>If you just want to import pygpu temporarily, put the file <em>pygpu.py</em> in your work directory and then you can import it in your program.</p>
</li>
<li>
<p>If you want to import pygpu from anywhere, put the file <em>pygpu.py</em> in the directory <em>Path/to/Python3/Lib/site-packages</em> or <em>Path/to/Anaconda3/Lib/site-packages</em> if you has Anaconda installed.</p>
</li>
</ul>
<h2 id="3-usage">3. Usage<a class="headerlink" href="#3-usage" title="Permanent link"></a></h2>
<p>First of all, you need to import pygpu in the head using:
<div class="codehilite"><pre><span class="kn">from</span> <span class="nn">pygpu</span> <span class="kn">import</span> <span class="o">*</span>
</pre></div></p>
<h3 id="31-process-a-single-mission">3.1 process a single mission<a class="headerlink" href="#31-process-a-single-mission" title="Permanent link"></a></h3>
<ol>
<li>
<p><strong>Define a GPU class&rsquo; variable</strong>(for example, name it as <code>gpu</code>)<br />
There are three ways to do this: </p>
<ol>
<li>
<p><code>gpu = GPU()</code>: This will use the default GPU device. In detail, it use the GPU on platform 0 and device 0.</p>
</li>
<li>
<p><code>gpu = GPU(1, 0)</code>: Tell GPU class to use the GPU device on platform 1 and device 0.</p>
</li>
<li>
<p><code>gpu = GPU("nvidia")</code>: Use a name string can also indicate GPU class to use which device.</p>
</li>
</ol>
</li>
</ol>
<p>To see what devices do you have, execute command <code>AllGPUs.list_devices()</code>. In my computer, it print this result:
<div class="codehilite"><pre><span class="o">&gt;&gt;&gt;</span> <span class="n">AllGPUs</span><span class="o">.</span><span class="n">list_device</span><span class="p">()</span>
<span class="p">(</span> <span class="mi">0</span> <span class="p">,</span> <span class="mi">0</span> <span class="p">):</span> <span class="n">GeForce</span> <span class="n">GTX</span> <span class="mi">960</span><span class="n">M</span>
<span class="p">(</span> <span class="mi">1</span> <span class="p">,</span> <span class="mi">0</span> <span class="p">):</span> <span class="n">Intel</span><span class="p">(</span><span class="n">R</span><span class="p">)</span> <span class="n">HD</span> <span class="n">Graphics</span> <span class="mi">530</span>
<span class="o">&gt;&gt;&gt;</span> 
</pre></div></p>
<ol>
<li>
<p><strong>Write kernel function</strong><br />
The kernel function define the operation that you want to eval at each single data of your data set. You must write it in another file and in the rules of OpenCL kernel function. An also, PyGPU set several special rules rules for kernel function. In detail,</p>
<ol>
<li>
<p>Begin your kernel function with a modifier <code>__kernel</code>.</p>
</li>
<li>
<p>The return type of kernel must be <code>void</code>.</p>
</li>
<li>
<p>The first argument of kernel function must be the only one output argument. And must be in type of one-dimensional pointer, modified by <code>__global</code>. For example, <code>__global float*</code>. So in your kernel function&rsquo;s logic, you must store your final computing results in the first argument and can only store in this argument.</p>
</li>
<li>
<p>Other arguments can be in base type or one-dimensional pointer. They can not be in two or more dimensional pointer or user defined type or class. And they are all input arguments.</p>
</li>
<li>
<p>Never use <code>__local</code> to be the modifier of an argument.</p>
</li>
<li>
<p>If an argument is a pointer, he must have a modifier. The modifier can only be <code>__global</code> or <code>__constant</code>.</p>
<ul>
<li>
<p>Use <code>__global</code> when this argument will vary each time when you call the variable <code>gpu</code>.</p>
</li>
<li>
<p>Use <code>__constant</code> when this argument stay the same value each time when you call the variable <code>gpu</code></p>
</li>
</ul>
</li>
<li>
<p>In the body of the kernel function, use <code>int i = get_global_id(0);</code> to get the current work position. <code>i</code> means the kernel function now is generating the <code>i</code>th data of the only output argument. <code>i</code> will vary from 0 to the length of first argument.(That comes the question: the first argument is a pure pointer, so how do program know the size of it&rsquo;s content? This will tell in step <strong>Set return template</strong>)</p>
</li>
<li>
<p>Write how to generate <code>i</code>th output data in normal C language way.</p>
</li>
</ol>
</li>
</ol>
<p>Maybe you will get a little confused about these rules. It dosen&rsquo;t matter. The examples in section <strong>Preview</strong> and <strong>Examples</strong> and in <em>examples</em> folder will help you understand them.</p>
<ol>
<li>
<p><strong>Tell <code>gpu</code> to use your kernel function</strong><br />
Return to python file where you defined <code>gpu</code> variable. Write this line to indicate GPU to use your kernel function:
<div class="codehilite"><pre><span class="n">gpu</span><span class="o">.</span><span class="n">set_program</span><span class="p">(</span><span class="s">&#39;file_name&#39;</span><span class="p">,</span> <span class="s">&#39;function_name&#39;</span><span class="p">)</span>
</pre></div>
Remember to replace <code>'file_name'</code> with your kernel file&rsquo;s real file name and <code>'function_name'</code> with your real kernel function name.</p>
</li>
<li>
<p><strong>Set return template</strong><br />
In the kernel function, the first argument is the output argument. It serve as the return value. There is a limitation that it can only be in one-dimensional pointer. So what if I want the return result to be a two or more dimensional numpy.ndarray? Don&rsquo;t worry, <code>set_return</code> method will help with it. Use <code>set_return</code> to transfer a template to tell <code>gpu</code> you want the result in this shape. Then <code>gpu</code> variable will interprete the raw one-dimensional array into the shape you want.<br />
For example, in kernel function the first argument is in type <code>float*</code> and you use <code>gpu.set_return(np.zeros((100, 200, 3)))</code> in the host side. <code>gpu</code> variable will reshape the raw one-dimensional <code>float*</code> into 100 rows 200 colums and 3 channels image liked matrix.<br />
Be attention: <code>gpu.set_return(a)</code> not means <code>gpu</code>&lsquo;s return result will store in variable <code>a</code>. <code>a</code> just give a template to <code>gpu</code> variable.</p>
</li>
<li>
<p><strong>Call <code>gpu</code> just like a function</strong><br />
Now it&rsquo;s time to pass input arguments to <code>gpu</code> variable. Just in this way:
<div class="codehilite"><pre>result = gpu(arg1, arg2, arg3, ...)
</pre></div>
Here are some rules to choose type of each arguments. For example, your kernel function is like:
<div class="codehilite"><pre>__kernel void func(Type0 result, Type1 arg1, Type2 arg2, Type3 arg3, ...)
</pre></div>
To satisfy the limitation of PyGPU, the arguments type in kernel function can only be in scalar types, vector types or their one-dimensional pointer.<br />
For scalar types or vector types, in kernel function you can choose from the following table:</p>
</li>
</ol>
<table>
<thead>
<tr>
<th>Scalar Type</th>
<th>Vector2 Type</th>
<th>Vector3 Type</th>
<th>Vector4 Type</th>
<th>Vector8 Type</th>
<th>Vector16 Type</th>
</tr>
</thead>
<tbody>
<tr>
<td>char</td>
<td>char2</td>
<td>char3</td>
<td>char4</td>
<td>char8</td>
<td>char16</td>
</tr>
<tr>
<td>uchar</td>
<td>uchar2</td>
<td>uchar3</td>
<td>uchar4</td>
<td>uchar8</td>
<td>uchar16</td>
</tr>
<tr>
<td>short</td>
<td>short2</td>
<td>short3</td>
<td>short4</td>
<td>short8</td>
<td>short16</td>
</tr>
<tr>
<td>ushort</td>
<td>ushort2</td>
<td>ushort3</td>
<td>ushort4</td>
<td>ushort8</td>
<td>ushort16</td>
</tr>
<tr>
<td>int</td>
<td>int2</td>
<td>int3</td>
<td>int4</td>
<td>int8</td>
<td>int16</td>
</tr>
<tr>
<td>uint</td>
<td>uint2</td>
<td>uint3</td>
<td>uint4</td>
<td>uint8</td>
<td>uint16</td>
</tr>
<tr>
<td>long</td>
<td>long2</td>
<td>long3</td>
<td>long4</td>
<td>long8</td>
<td>long16</td>
</tr>
<tr>
<td>ulong</td>
<td>ulong2</td>
<td>ulong3</td>
<td>ulong4</td>
<td>ulong8</td>
<td>ulong16</td>
</tr>
<tr>
<td>half</td>
<td>half2</td>
<td>half3</td>
<td>half4</td>
<td>half8</td>
<td>half16</td>
</tr>
<tr>
<td>float</td>
<td>float2</td>
<td>float3</td>
<td>float4</td>
<td>float8</td>
<td>float16</td>
</tr>
<tr>
<td>double</td>
<td>double2</td>
<td>double3</td>
<td>double4</td>
<td>double8</td>
<td>double16</td>
</tr>
</tbody>
</table>
<p>For their pointers, in kernel function you can choose from the following table:</p>
<table>
<thead>
<tr>
<th>Scalar Pointer</th>
<th>Vector2 pointer</th>
<th>Vector3 pointer</th>
<th>Vector4 pointer</th>
<th>Vector8 pointer</th>
<th>Vector16 pointer</th>
</tr>
</thead>
<tbody>
<tr>
<td>char*</td>
<td>char2*</td>
<td>char3*</td>
<td>char4*</td>
<td>char8*</td>
<td>char16*</td>
</tr>
<tr>
<td>uchar*</td>
<td>uchar2*</td>
<td>uchar3*</td>
<td>uchar4*</td>
<td>uchar8*</td>
<td>uchar16*</td>
</tr>
<tr>
<td>short*</td>
<td>short2*</td>
<td>short3*</td>
<td>short4*</td>
<td>short8*</td>
<td>short16*</td>
</tr>
<tr>
<td>ushort*</td>
<td>ushort2*</td>
<td>ushort3*</td>
<td>ushort4*</td>
<td>ushort8*</td>
<td>ushort16*</td>
</tr>
<tr>
<td>int*</td>
<td>int2*</td>
<td>int3*</td>
<td>int4*</td>
<td>int8*</td>
<td>int16*</td>
</tr>
<tr>
<td>uint*</td>
<td>uint2*</td>
<td>uint3*</td>
<td>uint4*</td>
<td>uint8*</td>
<td>uint16*</td>
</tr>
<tr>
<td>long*</td>
<td>long2*</td>
<td>long3*</td>
<td>long4*</td>
<td>long8*</td>
<td>long16*</td>
</tr>
<tr>
<td>ulong*</td>
<td>ulong2*</td>
<td>ulong3*</td>
<td>ulong4*</td>
<td>ulong8*</td>
<td>ulong16*</td>
</tr>
<tr>
<td>half*</td>
<td>half2*</td>
<td>half3*</td>
<td>half4*</td>
<td>half8*</td>
<td>half16*</td>
</tr>
<tr>
<td>float*</td>
<td>float2*</td>
<td>float3*</td>
<td>float4*</td>
<td>float8*</td>
<td>float16*</td>
</tr>
<tr>
<td>double*</td>
<td>double2*</td>
<td>double3*</td>
<td>double4*</td>
<td>double8*</td>
<td>double16*</td>
</tr>
</tbody>
</table>
<ul>
<li>
<p>if you use <strong>scalar type</strong> in kernel function, for example the first input argument is <code>double arg1</code>, in host program, you can set <code>arg1</code> a single value(means not numpy array or list or tuple or other things, just a single value). You don&rsquo;t need to transform the type of <code>arg1</code>. That means if you want to set <code>arg1 = 1</code>, then just pass <code>1</code> to <code>gpu</code>. You don&rsquo;t need to transform 1 to specific type such as <code>np.float64(1)</code> or <code>cl.cltypes.double(1)</code>, no need.</p>
</li>
<li>
<p>if you use <strong>vector type</strong> in kernel function, for example the second input argument is <code>float3 arg2</code>, in host program, then you can set <code>arg2</code> one of following type value:</p>
<ul>
<li>
<p>a one row numpy.ndarray with size 3, such as <code>np.random.rand(3)</code></p>
</li>
<li>
<p>a list with 3 scalar value, such as <code>[1, 2, 3]</code></p>
</li>
<li>
<p>a tuple with 3 scalar value, such as <code>(1, 2, 3)</code>. But you can&rsquo;t let <code>arg2</code> maked by <code>cl.cltypes.make_float3(...)</code>. Forget the old type transform way, forget them.</p>
</li>
</ul>
</li>
<li>
<p>if you use <strong>pointer</strong> in kernel function, for example the third input argument is <code>__global float*</code>, in the host program, you can set <code>arg3</code> one of the following type:</p>
<ul>
<li>
<p>a list of single value, such as <code>[1, 2, 3, 4, 5, 6, ...]</code></p>
</li>
<li>
<p>a list of list or more nesting, such as <code>[[1,2,3], [3,5,2], [9,3,6], ...]</code></p>
</li>
<li>
<p>a numpy.ndarray, such as <code>np.random.rand(3)</code>, <code>np.random.rand(3, 3)</code>, <code>np.random.rand(3, 3, 3)</code></p>
</li>
</ul>
</li>
</ul>
<p>All multi-dimension matrix liked data will be flatten into one dimension. And in the kernel side, you need to do some index tranform. You will see it in examples.</p>
<ol>
<li><strong>Next time you call <code>gpu</code></strong><br />
If you have call <code>gpu</code> once in this way: <code>result = gpu(arg1, arg2, arg3, ...)</code>, next time you call <code>gpu</code> if some arguments are the same as first time, use <code>None</code> can avoid copying large data from host to device. For example, if <code>arg1</code> is a very large matrix and you called <code>gpu</code> once just like:
<div class="codehilite"><pre>result1 = gpu(large_matrix, 3)
</pre></div>
Next time you also want to process this matrix with another int value 4, avoid using
<div class="codehilite"><pre>result2 = gpu(large_matrix, 4)
</pre></div>
instead, using
<div class="codehilite"><pre>result2 = gpu(None, 4)
</pre></div></li>
</ol>
<h3 id="32-process-multi-missions-with-a-single-gpu">3.2 process multi-missions with a single GPU<a class="headerlink" href="#32-process-multi-missions-with-a-single-gpu" title="Permanent link"></a></h3>
<p>If you want to do some same process for different arrays, such as for different images, but these images have the same size, you can copy these images to device together, process them together and copy them from device to host together. This will save a lot of time. You can do this in the following way:</p>
<ol>
<li>
<p><strong>Define a GPU class variable <code>gpu</code></strong></p>
</li>
<li>
<p><strong>Write kernel program</strong></p>
</li>
<li>
<p><strong>Tell <code>gpu</code> to use your kernel program</strong></p>
</li>
<li>
<p><strong>Set return template</strong></p>
</li>
<li>
<p><strong>Set arguments</strong>:<br />
This is the first difference from processing single mission. For each mission, all the matrix liked or array liked arguments must have the same size. So you need to sent each input argument a template before add missions. You can set arguments in this way:
<div class="codehilite"><pre>gpu.set_args(arg1, arg2, arg3, ...)
</pre></div>
For each mission, <code>arg1</code> or <code>arg2</code> will vary from time to time, but every one have the same size.</p>
</li>
<li>
<p><strong>Add missions</strong><br />
For example, if you set arguments template using <code>gpu.set_args(arg1, arg2, arg3)</code> and <code>arg1</code> is a image, it will change for each mission and <code>arg2</code> and <code>arg3</code> will be fixed. You can add missions in this way:
<div class="codehilite"><pre>gpu.add_mission(image1)
gpu.add_mission(image2)
gpu.add_mission(image3)
gpu.add_mission(image4)
</pre></div>
Be attention, their are some special rules for adding mission: </p>
</li>
</ol>
<ul>
<li>
<p>image1 to 4 must have the same size.</p>
</li>
<li>
<p>Varying arguments in kernel function must be in global pointer type. And global pointer arguments must be set in each <code>add_mission</code> time.</p>
</li>
<li>
<p>Fixed arguments in kernel function must be non-pointer type or constant pointer.</p>
</li>
</ul>
<ol>
<li>
<p><strong>Process all the missions at the same time</strong><br />
Just use <code>gpu.run()</code> is OK.</p>
</li>
<li>
<p><strong>Get results</strong><br />
You can get <code>i</code>th mission&rsquo;s result by using <code>result = gpu.result(i)</code></p>
</li>
</ol>
<h3 id="33-process-multi-missions-with-multi-gpus">3.3 process multi-missions with multi-GPUs<a class="headerlink" href="#33-process-multi-missions-with-multi-gpus" title="Permanent link"></a></h3>
<p>If you change the declaration in the first step <code>gpu = GPU()</code> into <code>gpu = AllGPUs()</code>, it will automatically distribute missions to all GPUs on your computer and let them start computation at the same time.</p>
<h3 id="34-other-functions">3.4 other functions<a class="headerlink" href="#34-other-functions" title="Permanent link"></a></h3>
<ol>
<li>
<p><code>GPU.device_name()</code> return the current GPU name.</p>
</li>
<li>
<p><code>GPU.print_info()</code> or <code>AllGPUs.print_info()</code> print current GPU&rsquo;s detail information or all GPUs&rsquo; detail information.</p>
</li>
<li>
<p><code>GPU.clear()</code> or <code>AllGPUs.clear()</code> make GPU or AllGPUs class&rsquo; instance return to the state before set_program.</p>
</li>
<li>
<p><code>GPU.clear_missions()</code> or <code>AllGPUs.clear_missions()</code> make GPU or AllGPUs class&rsquo; instance return to the state before add first mission.</p>
</li>
<li>
<p><code>GPU.print_performance()</code> or <code>AllGPUs.print_performance()</code> print the performace of last computation. It includes:</p>
<ul>
<li>total time</li>
<li>time of copying data from host to device</li>
<li>time of computing</li>
<li>time of copying data from device to host</li>
<li>computing/total time ratio</li>
<li>computing/copying time ratio</li>
</ul>
</li>
<li>
<p><code>GPU.device2host_time()</code> return the time of copying data from device to host of last computation(in second).</p>
</li>
<li>
<p><code>GPU.compute_time()</code> return computing time of last computation(in second).</p>
</li>
<li>
<p><code>GPU.host2device_time()</code> return the time of copying data from host to device of last computation(in second).</p>
</li>
<li>
<p><code>GPU.total_time()</code> return the total time of last computation(in second).</p>
</li>
</ol>
<h2 id="4-examples">4. Examples<a class="headerlink" href="#4-examples" title="Permanent link"></a></h2>
<p>In <strong>Preview</strong> section, there are already two examples. In <code>examples</code> folder, there are two more complex examples:</p>
<ul>
<li>
<p>Gaussain Blur a image(<em>blur.py</em>, it will teach you how to transform index between 2-dimensional matrix and one-dimensional array)</p>
</li>
<li>
<p>Gaussain Blur a lot of images(<em>batch_process.py</em>, it will teach you how to use multi-processing method of PyGPU)</p>
</li>
</ul>
<p>You can run them directly.</p>
<h2 id="5-limitation">5. Limitation<a class="headerlink" href="#5-limitation" title="Permanent link"></a></h2>
<p>This library&rsquo;s usage is simple enough. Simple means the degree of freedom is low. So their are much limitation. Here list some limitation I known:</p>
<ol>
<li>
<p>There can only be one output argument in kernel function.</p>
</li>
<li>
<p>The output argument in kernel function must be the first argument in kernel function.</p>
</li>
<li>
<p>You cannot use <code>__local</code> memory</p>
</li>
<li>
<p>You can only use one-dimensional pointer in kernel function.</p>
</li>
<li>
<p>You can&rsquo;t distribute work groups or work items by your self, you can only let OpenCL do this automatically for you.</p>
</li>
<li>
<p>In multi-missions processing, you can only change global pointer type arguments and global pointer type arguments must be set for each mission even if they are same.</p>
</li>
<li>
<p>You can only use the types in the table in kernel function. You cannot use user defined class or structure or other types.</p>
</li>
</ol>
<p>There are also many other limitiations. But for some simple parallel processing, I think these functions are enough.</p></article></body></html>